diff --git a/memory-bank/README.md b/memory-bank/README.md index 9fb5b97..6d4b3ff 100644 --- a/memory-bank/README.md +++ b/memory-bank/README.md @@ -72,3 +72,7 @@ flows and templates remain upstream-derived process references. Setup onboarding and first-run user config. - [features/FT-015/README.md](features/FT-015/README.md) Codex batch human-gate mode with resume flow. +- [features/FT-016/README.md](features/FT-016/README.md) + Opt-in real Codex human-gate E2E suite. +- [features/FT-017/README.md](features/FT-017/README.md) + Codex human-gate delivery permission modes. diff --git a/memory-bank/features/FT-017/README.md b/memory-bank/features/FT-017/README.md new file mode 100644 index 0000000..6aad750 --- /dev/null +++ b/memory-bank/features/FT-017/README.md @@ -0,0 +1,33 @@ +--- +title: "FT-017: Codex human-gate delivery permissions" +doc_kind: feature +doc_function: index +purpose: "Navigation for the Codex human-gate permission and full-delivery contract feature package." +derived_from: + - ../../dna/governance.md + - brief.md + - design.md + - implementation-plan.md +status: active +audience: humans_and_agents +--- + +# FT-017: Codex human-gate delivery permissions + +## About + +This package tracks GitHub issue #37. It extends the FT-015 batch/resume flow +with an explicit capability contract for restricted work and opt-in end-to-end +Git delivery. + +## Annotated index + +- [brief.md](brief.md) + Canonical problem space, scope, acceptance scenarios, checks, and evidence + contract. +- [design.md](design.md) + Selected permission-mode design, Codex command contract, trust boundary, + failure modes, and rollout/backout rules. +- [implementation-plan.md](implementation-plan.md) + Grounded execution sequence, test strategy, checkpoints, and approval gate + for live GitHub-writing verification. diff --git a/memory-bank/features/FT-017/brief.md b/memory-bank/features/FT-017/brief.md new file mode 100644 index 0000000..42c9353 --- /dev/null +++ b/memory-bank/features/FT-017/brief.md @@ -0,0 +1,202 @@ +--- +title: "FT-017: Codex human-gate delivery permissions" +doc_kind: feature +doc_function: canonical +purpose: "Canonical brief for making Codex human-gate capabilities explicit and supporting opt-in end-to-end Git delivery." +derived_from: + - ../../flows/feature-flow.md + - ../../product/context.md + - ../../engineering/testing-policy.md + - ../FT-015/feature.md + - https://github.com/dapi/start-issue/issues/37 +status: active +delivery_status: planned +audience: humans_and_agents +must_not_define: + - implementation_sequence + - solution_space +--- + +# FT-017: Codex human-gate delivery permissions + +## What + +### Problem + +FT-015 established a resumable Codex batch flow, but its runtime contract is +limited to `workspace-write`. That mode can edit the prepared worktree, yet it +does not reliably provide network access or Git metadata writes. A run can +therefore complete implementation and tests but fail before reading complete +GitHub context, committing, pushing, or creating a pull request. + +The current help does not distinguish working-tree automation from full Git +delivery. Capability failures can consequently look like task-level +`HUMAN_GATE` decisions even though the real blocker is the launcher policy. + +The obsolete argument-order failure described in issue #37 has already been +removed on `master`; this feature must preserve compatibility with the current +supported Codex CLI while closing the remaining capability-contract gap. + +### Outcome + +| Metric ID | Metric | Baseline | Target | Measurement method | +| --- | --- | --- | --- | --- | +| `MET-01` | Human-gate capability contract visibility | One implicit `workspace-write` command | Every run reports either restricted or full-delivery permissions | Dry-run/help assertions | +| `MET-02` | Full Git delivery reachability | GitHub/network/Git writes are not guaranteed | An explicitly authorized mode can edit, test, commit, push, and create/update a PR | Deterministic command tests plus opt-in live E2E evidence | +| `MET-03` | Supported Codex command compatibility | Compatibility can drift with CLI option placement | Generated commands are accepted by the supported Codex CLI contract | Bats command-shape coverage and real-Codex smoke validation | + +### Scope + +- `REQ-01` Preserve a restricted human-gate mode for working-tree-only + automation and make that restricted completion boundary explicit in output + and help. +- `REQ-02` Add an explicit opt-in full-delivery mode whose declared contract + includes GitHub reads, network operations, Git metadata writes, push, and + pull-request creation/update. +- `REQ-03` Resolve the human-gate permission mode from a documented CLI option, + environment variable, and safe built-in default, and show the winning value + in dry-run output. +- `REQ-04` Generate a Codex command compatible with the supported CLI syntax, + including correct placement of global permission options and existing model, + worktree, JSONL, and last-message arguments. +- `REQ-05` Keep FT-015 state artifacts, final-status parsing, explicit-thread + resume behavior, and exit-code contract unchanged unless a capability error + occurs before the batch run. +- `REQ-06` Explain authentication, network access, Git write access, the risk of + full-delivery mode, restricted-mode limitations, and troubleshooting in + dedicated human-gate help and project documentation. +- `REQ-07` Add deterministic automated coverage for permission precedence, + validation, command construction, dry-run visibility, default compatibility, + and existing `DONE`/`HUMAN_GATE` behavior. +- `REQ-08` Provide an explicit opt-in real-Codex E2E procedure for validating + full delivery without adding live GitHub writes to `make test` or CI. + +### Non-Scope + +- `NS-01` Do not generalize human-gate mode to Claude, Kimi, Pi, or `agent=none`. +- `NS-02` Do not provision GitHub credentials, modify Codex user configuration, + or store secrets in project files. +- `NS-03` Do not authorize production changes, destructive Git operations, or + other product/security decisions merely because full-delivery mode is active; + the prompt's `HUMAN_GATE` rules remain authoritative. +- `NS-04` Do not redesign thread capture, state storage, status parsing, or + interactive resume semantics from FT-015. +- `NS-05` Do not couple this feature to the Go runtime migration or another CLI + rewrite. + +### Constraints / Assumptions + +- `ASM-01` The supported reference environment is Codex CLI `0.145.0`, whose + global permission options are accepted before the `exec` subcommand. +- `ASM-02` Full delivery requires independently configured GitHub + authentication and repository authorization; `start-issue` can select a + launcher policy but cannot grant those external capabilities. +- `CON-01` Restricted mode remains the built-in default so upgrading the CLI + does not silently broaden command execution privileges. +- `CON-02` Full-delivery mode must require an explicit user choice and must be + visible before Codex starts. +- `CON-03` Secrets and tokens must remain outside CLI arguments, tracked config, + logs, JSONL events, and state artifacts. +- `CON-04` Live delivery verification performs external GitHub writes and is + therefore manual, explicit-opt-in, and outside normal local/CI checks. + +## Design Requirement Decision + +| Decision | Reason | Downstream owner | +| --- | --- | --- | +| `Design required: yes` | The feature changes CLI/environment contracts and a security/trust boundary, and requires explicit trade-offs, command contracts, failure modes, and rollout rules. | `design.md` | + +## Verify + +### Exit Criteria + +- `EC-01` Restricted mode remains the default, is clearly reported, and does + not claim commit/push/PR completion. +- `EC-02` Full-delivery mode is accepted only through explicit opt-in and + produces the documented supported-Codex command contract. +- `EC-03` Invalid permission values and incompatible command construction fail + before a batch session with actionable diagnostics. +- `EC-04` Existing FT-015 `DONE`, `HUMAN_GATE`, state-file, thread-resume, and + exit-code behavior remains covered and unchanged. +- `EC-05` Help and project docs describe authentication, network/Git access, + security risk, mode selection, and troubleshooting consistently. +- `EC-06` An explicitly approved live E2E can demonstrate end-to-end Git + delivery and preserve auditable artifacts without becoming a CI dependency. + +### Traceability matrix + +| Requirement ID | Problem refs | Acceptance refs | Checks | Evidence IDs | +| --- | --- | --- | --- | --- | +| `REQ-01` | `CON-01` | `EC-01`, `SC-01` | `CHK-01`, `CHK-02` | `EVID-01`, `EVID-02` | +| `REQ-02` | `ASM-02`, `CON-02` | `EC-02`, `SC-02` | `CHK-01`, `CHK-03` | `EVID-01`, `EVID-03` | +| `REQ-03` | `CON-01`, `CON-02` | `EC-01`, `EC-02`, `SC-01`, `SC-02`, `NEG-01` | `CHK-01` | `EVID-01` | +| `REQ-04` | `ASM-01` | `EC-02`, `EC-03`, `SC-03` | `CHK-01`, `CHK-03` | `EVID-01`, `EVID-03` | +| `REQ-05` | `NS-04` | `EC-04`, `SC-04` | `CHK-01` | `EVID-01` | +| `REQ-06` | `ASM-02`, `CON-03` | `EC-05`, `SC-05` | `CHK-02` | `EVID-02` | +| `REQ-07` | `CON-01` | `EC-01` - `EC-04`, `SC-01` - `SC-04`, `NEG-01` | `CHK-01` | `EVID-01` | +| `REQ-08` | `CON-04` | `EC-06`, `SC-06` | `CHK-03` | `EVID-03` | + +### Acceptance Scenarios + +- `SC-01` Given no permission override, when a user inspects or runs + human-gate mode, then restricted mode is selected and its working-tree-only + completion boundary is visible. +- `SC-02` Given explicit full-delivery selection, when the human-gate command is + built, then the mode is visibly reported and the command permits the declared + GitHub/network/Git delivery workflow. +- `SC-03` Given the supported Codex CLI, when either permission mode builds the + batch command, then global permission options occur in a supported position + and batch-only output arguments remain attached to `exec`. +- `SC-04` Given either permission mode and a valid Codex response, when the + final status is `DONE` or `HUMAN_GATE`, then FT-015 state and resume behavior + remains unchanged. +- `SC-05` Given dedicated help or project documentation, when an operator plans + a run, then prerequisites, limitations, risks, and recovery steps are clear + without reading source code. +- `SC-06` Given explicit operator authorization, isolated fixture resources, + and valid credentials, when the full-delivery E2E runs, then it records + successful commit/push/PR delivery and retained diagnostic artifacts. + +### Negative / Edge Scenarios + +- `NEG-01` Given an unknown permission mode, when configuration is resolved, + then `start-issue` exits before issue fetching, worktree mutation, or Codex + launch and names the accepted values. +- `NEG-02` Given restricted mode and a task requiring Git delivery, when the + operator reads help or run output, then the tool does not represent the + restricted run as capable of completing commit/push/PR delivery. +- `NEG-03` Given full-delivery mode without valid GitHub credentials or remote + authorization, when the live workflow reaches delivery, then it fails with a + capability diagnostic and does not relabel the failure as a product decision. + +### Checks + +| Check ID | Covers | How to check | Expected result | Evidence path | +| --- | --- | --- | --- | --- | +| `CHK-01` | `EC-01` - `EC-04`, `SC-01` - `SC-04`, `NEG-01` | `make test` | Syntax, shellcheck, memory-bank audit, and deterministic Bats coverage pass for both modes and FT-015 regressions. | Local terminal/CI test output | +| `CHK-02` | `EC-01`, `EC-05`, `SC-01`, `SC-05`, `NEG-02` | Review `--help`, `--human-gate-help`, README files, and spec alongside output assertions | All surfaces state the same default, opt-in, capability, risk, and troubleshooting contract. | Review diff and Bats output | +| `CHK-03` | `EC-02`, `EC-03`, `EC-06`, `SC-02`, `SC-03`, `SC-06`, `NEG-03` | With explicit approval, run the real-Codex full-delivery E2E procedure from FT-017's plan | Supported Codex accepts the command and the isolated fixture records commit, push, PR, terminal status, and retained artifacts. | Retained E2E artifact directory and fixture PR URL | + +### Test matrix + +| Check ID | Evidence IDs | Evidence path | +| --- | --- | --- | +| `CHK-01` | `EVID-01` | Local terminal output and CI job | +| `CHK-02` | `EVID-02` | Review diff and deterministic help assertions | +| `CHK-03` | `EVID-03` | Retained opt-in E2E artifact directory and fixture PR URL | + +### Evidence + +- `EVID-01` Automated verification output covering permission resolution, + command construction, errors, and FT-015 regression behavior. +- `EVID-02` Documentation/help review evidence showing one consistent operator + contract. +- `EVID-03` Explicitly approved live-E2E evidence for full Git delivery. + +### Evidence contract + +| Evidence ID | Artifact | Producer | Path contract | Reused by checks | +| --- | --- | --- | --- | --- | +| `EVID-01` | Local and CI test output | implementer / CI | Terminal output and GitHub Actions job | `CHK-01` | +| `EVID-02` | Documentation diff plus help assertions | implementer / reviewer | Changed docs and Bats output | `CHK-02` | +| `EVID-03` | Live-E2E log, state files, commit/PR identifiers | approved operator | Retained E2E artifact path printed by runner | `CHK-03` | diff --git a/memory-bank/features/FT-017/design.md b/memory-bank/features/FT-017/design.md new file mode 100644 index 0000000..73fba04 --- /dev/null +++ b/memory-bank/features/FT-017/design.md @@ -0,0 +1,176 @@ +--- +title: "FT-017: Design" +doc_kind: feature +doc_function: canonical +purpose: "Solution-space document for explicit restricted and full-delivery Codex human-gate permission modes." +derived_from: + - brief.md + - ../FT-015/solution.md + - ../FT-016/design.md +status: active +audience: humans_and_agents +must_not_define: + - ft_017_scope + - ft_017_acceptance_criteria + - ft_017_evidence_contract + - implementation_sequence +--- + +# FT-017: Design + +## Design Pack + +| Artifact | Role | Owns | +| --- | --- | --- | +| `design.md` | Feature-local solution owner | `SOL-*`, `ALT-*`, `TRD-*`, `C4-*`, `SD-*`, `CTR-*`, `INV-*`, `FM-*`, `RB-*` | + +## Context + +FT-015 owns the batch/resume lifecycle. FT-017 changes only the launcher +capability boundary around that lifecycle. The solution must keep restricted +behavior safe by default while giving an operator one deliberate, visible way +to authorize end-to-end Git delivery. + +The local reference CLI is Codex `0.145.0`. Its approval and sandbox flags are +global options, while JSONL and last-message outputs are `exec` options. The +design therefore needs a stable semantic contract owned by `start-issue`, not +an unchecked string of arbitrary Codex arguments. + +## C4 Applicability + +| C4 ID | Decision | Trigger / reason | Artifact | +| --- | --- | --- | --- | +| `C4-01` | `C1` | Full-delivery mode changes the trust boundary between the operator, `start-issue`, Codex, the local Git repository, and GitHub. | Mermaid system-context diagram below | + +### C4 Artifact + +```mermaid +flowchart LR + U["Operator"] -->|selects restricted or full-delivery| S["start-issue CLI"] + S -->|validated command + rendered issue prompt| C["Codex CLI"] + C -->|working-tree operations| G["Local Git worktree/repository"] + C -->|full-delivery only: authenticated reads, push, PR| H["GitHub"] + C -->|DONE or HUMAN_GATE + thread state| S + S -->|status, artifacts, exact resume target| U + + classDef trust fill:#fff4d6,stroke:#a36b00; + class C,G,H trust; +``` + +The operator's explicit mode selection is the authorization boundary. +`start-issue` validates and renders the policy; Codex executes it; GitHub still +enforces credentials and repository authorization independently. + +## Selected Solution + +- `SOL-01` Add one semantic configuration axis named human-gate permissions + with exactly two values: `restricted` and `full-delivery`. Resolve it as CLI + option → environment variable → built-in `restricted`. +- `SOL-02` Map `restricted` to Codex global options + `--ask-for-approval never --sandbox workspace-write` and map explicit + `full-delivery` to + `--ask-for-approval never --sandbox danger-full-access`. +- `SOL-03` Build the command in supported grammar order: `codex`, global model + and permission options, `exec`, then worktree and batch-output options. +- `SOL-04` Print the resolved semantic mode and a concise capability statement + in dry-run and immediately before batch execution. Full-delivery output also + prints a high-signal warning before Codex starts. +- `SOL-05` Keep FT-015's prompt, run-state, thread-id, status parser, exit codes, + and resume path unchanged. The selected permission mode applies to the batch + run; interactive resume remains a human-controlled transition. +- `SOL-06` Extend the opt-in real-Codex E2E runner with a separately authorized + full-delivery scenario that uses isolated fixture resources and retains + delivery evidence. + +## Alternatives Considered + +| Alternative ID | Option | Why not selected | +| --- | --- | --- | +| `ALT-01` | Pass arbitrary extra Codex arguments from CLI or environment | Makes validation, documentation, shell quoting, and safety review unreliable. | +| `ALT-02` | Require a named Codex profile and infer capabilities from it | `start-issue` cannot reliably prove the effective network/Git permissions of an arbitrary external profile, so the advertised contract could be false. | +| `ALT-03` | Make full delivery the new default | Silently broadens privileges for existing automation and violates `CON-01`. | +| `ALT-04` | Keep only `workspace-write` and document manual delivery | Does not satisfy the explicit end-to-end delivery outcome in `REQ-02`. | + +## Trade-offs + +| Trade-off ID | Decision | Benefit | Cost / Risk | +| --- | --- | --- | --- | +| `TRD-01` | Expose two semantic modes instead of raw Codex controls | Small, testable public contract with stable operator meaning | Advanced Codex policies are not expressible through this feature. | +| `TRD-02` | Use `danger-full-access` for explicit full delivery | Provides network and Git metadata writes required by the delivery contract | Batch commands are unsandboxed and must be treated as high risk. | +| `TRD-03` | Keep `never` approval for batch execution | Preserves unattended human-gate semantics | Capability errors cannot escalate mid-run and must be diagnosed clearly. | + +## Accepted Local Decisions + +- `SD-01` Name the public values by user outcome (`restricted`, + `full-delivery`) rather than Codex implementation names so help and future + adapters can describe capability without leaking every low-level flag. +- `SD-02` Use `--human-gate-permissions VALUE` and + `START_ISSUE_HUMAN_GATE_PERMISSIONS` as the two explicit inputs. Project/user + persistence is deferred; the dangerous mode must not become an unnoticed + repository default in this feature. +- `SD-03` A full-delivery selection is itself explicit authorization to launch + the unsandboxed batch command, but not authorization for destructive or + production actions excluded by `NS-03`. +- `SD-04` Live full-delivery verification remains a manual approval gate and is + never folded into `make test` or CI. + +## Contracts + +| Contract ID | Input / Output | Producer / Consumer | Semantics / Constraints | +| --- | --- | --- | --- | +| `CTR-01` | `--human-gate-permissions restricted\|full-delivery` | CLI parser / config resolver | CLI value wins over environment; invalid or empty explicit values fail before issue fetch. | +| `CTR-02` | `START_ISSUE_HUMAN_GATE_PERMISSIONS` | shell environment / config resolver | Used only when CLI input is absent; unset resolves to `restricted`. | +| `CTR-03` | Restricted Codex command | launcher / Codex | `codex [--model MODEL] --ask-for-approval never --sandbox workspace-write exec --cd WORKTREE --json --output-last-message PATH -`. | +| `CTR-04` | Full-delivery Codex command | launcher / Codex | Same shape as `CTR-03`, with `--sandbox danger-full-access`; selected only by explicit `full-delivery`. | +| `CTR-05` | Permission status output | launcher / operator | Reports semantic mode and capability boundary before execution and in dry-run; full delivery includes an unsandboxed-execution warning. | + +## Invariants + +- `INV-01` Absence of configuration always resolves to `restricted`. +- `INV-02` Only `restricted` and `full-delivery` are accepted; no value is + interpolated directly into a shell command. +- `INV-03` Full-delivery selection never injects credentials or secret values. +- `INV-04` Batch commands remain arrays and are never evaluated through `eval`. +- `INV-05` FT-015's exact thread-id resume and state-artifact paths remain + stable across permission modes. + +## Failure Modes + +- `FM-01` Codex changes option grammar: deterministic command assertions or the + real-Codex smoke run fails before the feature is accepted; update the adapter + and supported-version documentation together. +- `FM-02` Full delivery lacks GitHub authentication or repository permission: + preserve run artifacts and report an operational capability failure rather + than treating it as a product-choice `HUMAN_GATE`. +- `FM-03` An invalid permission value is supplied: reject it before fetching an + issue, creating/reusing a worktree, or invoking Codex. +- `FM-04` A full-delivery prompt proposes destructive or production work: + prompt policy still requires `STATUS: HUMAN_GATE`; permission mode does not + broaden product authorization. + +## Rollout / Backout + +| Stage ID | Stage | Entry condition | Backout | +| --- | --- | --- | --- | +| `RB-01` | Ship restricted/default path and deterministic tests | Command contract passes `make test`; docs state restricted boundary | Remove the new input while retaining FT-015's existing restricted command | +| `RB-02` | Document and enable explicit full delivery | Warning, negative tests, and command-shape coverage pass | Reject `full-delivery` and keep `restricted` available | +| `RB-03` | Validate live fixture delivery | Explicit operator approval and isolated fixture repo/issue are available | Stop the E2E, retain artifacts, and leave feature not-done | + +## ADR / External Design Dependencies + +No cross-feature architecture decision is introduced. The permission mapping is +feature-local and can be revised with this design if the supported Codex CLI +contract changes. + +## Traceability + +| Requirement ID | Solution refs | Contracts / invariants | Failure / rollout refs | +| --- | --- | --- | --- | +| `REQ-01` | `SOL-01`, `SOL-04`, `SD-01` | `CTR-01` - `CTR-03`, `CTR-05`, `INV-01` | `FM-03`, `RB-01` | +| `REQ-02` | `SOL-01`, `SOL-02`, `TRD-02`, `SD-03` | `CTR-04`, `CTR-05`, `INV-02`, `INV-03` | `FM-02`, `FM-04`, `RB-02` | +| `REQ-03` | `SOL-01`, `SD-02` | `CTR-01`, `CTR-02`, `INV-01`, `INV-02` | `FM-03`, `RB-01` | +| `REQ-04` | `SOL-02`, `SOL-03` | `CTR-03`, `CTR-04`, `INV-04` | `FM-01`, `RB-01`, `RB-02` | +| `REQ-05` | `SOL-05` | `INV-05` | `RB-01` | +| `REQ-06` | `SOL-04`, `TRD-02`, `SD-03` | `CTR-05`, `INV-03` | `FM-02`, `FM-04`, `RB-02` | +| `REQ-07` | `SOL-01` - `SOL-05` | `CTR-01` - `CTR-05`, `INV-01` - `INV-05` | `FM-01` - `FM-04`, `RB-01`, `RB-02` | +| `REQ-08` | `SOL-06`, `SD-04` | `INV-03`, `INV-05` | `FM-02`, `RB-03` | diff --git a/memory-bank/features/FT-017/implementation-plan.md b/memory-bank/features/FT-017/implementation-plan.md new file mode 100644 index 0000000..757d928 --- /dev/null +++ b/memory-bank/features/FT-017/implementation-plan.md @@ -0,0 +1,160 @@ +--- +title: "FT-017: Implementation Plan" +doc_kind: feature +doc_function: derived +purpose: "Execution plan for explicit restricted and full-delivery Codex human-gate permission modes." +derived_from: + - brief.md + - design.md +status: active +audience: humans_and_agents +must_not_define: + - ft_017_scope + - ft_017_selected_design + - ft_017_acceptance_criteria + - ft_017_blocker_state +--- + +# FT-017: Implementation Plan + +## Current goal + +Implement the accepted FT-017 permission-mode contract while preserving the +existing FT-015 batch, state, status, and resume behavior. + +## Grounding / Support References + +| Document | Role in this plan | Facts reused | Conflict action | +| --- | --- | --- | --- | +| `brief.md` | Canonical problem / verify owner | `REQ-*`, `SC-*`, `NEG-*`, `CHK-*`, `EVID-*` | Update `brief.md` first | +| `design.md` | Canonical solution owner | `SOL-*`, `C4-01`, `SD-*`, `CTR-*`, `INV-*`, `FM-*`, `RB-*` | Update `design.md` first | +| `../FT-015/feature.md` and `solution.md` | Existing human-gate contract | State, status, thread, resume, and exit semantics | Preserve FT-015 ownership; update FT-017 if extension assumptions change | +| `../FT-016/brief.md` and `design.md` | Existing real-Codex E2E boundary | Explicit opt-in, fake-Codex rejection, retained artifacts | Extend rather than duplicate the runner contract | + +## Current State / Reference Points + +| Path / module | Current role | Why relevant | Reuse / mirror | +| --- | --- | --- | --- | +| `scripts/start-issue` | Initializes shared CLI state and sources modules | New resolved permission state needs a safe default | Follow existing agent/model state initialization | +| `scripts/lib/start_issue/cli.sh` | Parses public options and validates mode combinations | Owns the new CLI input and early rejection path | Follow `--human-gate`/`--model` value parsing patterns | +| `scripts/lib/start_issue/config.sh` | Resolves config values and sources | Owns CLI/environment/default precedence | Mirror model resolution without adding project/user persistence | +| `scripts/lib/start_issue/agent.sh` | Builds and runs Codex human-gate commands | Main permission mapping and supported grammar change surface | Keep array-based command construction and FT-015 state helpers | +| `scripts/lib/start_issue/output.sh` | Renders help, dry-run, and runtime status | Must expose mode, capabilities, and warning consistently | Extend current human-gate help and dry-run output | +| `test/helpers/fake-bin/codex` | Deterministic Codex command double | Must validate global option order and both sandbox mappings | Extend argument capture/rejection behavior | +| `test/start_issue.bats` | Public CLI and human-gate regression suite | Existing tests cover restricted command, DONE, HUMAN_GATE, and errors | Add precedence, invalid value, full-delivery, and order assertions | +| `test/e2e/human-gate.sh` | Opt-in real-Codex smoke runner | Closest existing live verification surface | Add a separately guarded full-delivery scenario only after approval | +| `README.md`, `README.ru.md`, `doc/spec.md` | Public and canonical behavior docs | Must match help and command behavior | Update together with output assertions | + +## Test Strategy + +| Test surface | Canonical refs | Existing coverage | Planned automated coverage | Required local suites / commands | Required CI suites / jobs | Manual-only gap / justification | Manual-only approval ref | +| --- | --- | --- | --- | --- | --- | --- | --- | +| Permission resolution and validation | `REQ-03`, `SC-01`, `SC-02`, `NEG-01`, `CTR-01`, `CTR-02` | None | CLI beats env; env beats default; invalid value fails before fetch/mutation | `make test` | Existing test job | none | none | +| Codex command construction | `REQ-01`, `REQ-02`, `REQ-04`, `SC-03`, `CTR-03`, `CTR-04`, `INV-02`, `INV-04` | Restricted dry-run and fake Codex execution | Assert semantic mode mapping, global-before-`exec` order, model coexistence, and no raw interpolation | `make test` | Existing test job | Real installed-Codex parser behavior is external | `AG-01` for live run | +| FT-015 state/resume regression | `REQ-05`, `SC-04`, `INV-05` | DONE, HUMAN_GATE, missing status/thread | Run existing scenarios under default restricted and one full-delivery fake path | `make test` | Existing test job | none | none | +| Help/docs contract | `REQ-01`, `REQ-06`, `SC-05`, `NEG-02`, `CTR-05` | Dedicated human-gate help assertions | Assert default, full-delivery warning, prerequisites, limitations, and troubleshooting | `make test`; documentation review | Existing test job | Prose consistency review is manual | reviewer approval in PR | +| End-to-end Git delivery | `REQ-02`, `REQ-08`, `SC-06`, `NEG-03`, `SOL-06`, `RB-03` | Real Codex terminal-state smoke only | Keep syntax/static coverage automated; add guarded scenario entrypoint | `make test` plus explicitly approved E2E | Excluded from CI | Requires real Codex, credentials, network, Git writes, push, and PR creation | `AG-01` | + +## Open Questions / Ambiguities + +| Open Question ID | Question | Why unresolved | Blocks | Default action / escalation owner | +| --- | --- | --- | --- | --- | +| `OQ-01` | Which future Codex versions remain compatible after `0.145.0`? | The external CLI has no repository-owned stability guarantee. | Does not block implementation; affects future maintenance | Treat `0.145.0` as the tested baseline and update adapter/docs together on command-shape failure. | +| `OQ-02` | Which isolated fixture repository/issue should receive the live full-delivery PR? | Live target selection is operator-owned and may change. | `STEP-06` only | Require explicit target and approval through `AG-01`; never infer from global focus or an unrelated repo. | + +## Environment Contract + +| Area | Contract | Used by | Failure symptom | +| --- | --- | --- | --- | +| setup | Bash, Git, jq, shellcheck, Bats, fake agent binaries, and the current modular source tree | `STEP-01` - `STEP-05` | `make test` dependency or fixture failure | +| supported Codex | Local reference is `codex-cli 0.145.0`; approval/sandbox options must be accepted before `exec` | `STEP-03`, `STEP-06` | Real CLI rejects command before emitting `thread.started` | +| deterministic test | `make test` is canonical and must not use network or real agent binaries | `CHK-01`, `STEP-02` - `STEP-05` | External side effects or nondeterministic test failures | +| live access | Explicit opt-in, authenticated `gh`, real Codex, authorized fixture repo/issue, network, and permission to push/create a PR | `STEP-06` | Missing auth, push rejection, absent PR, or no terminal status | +| secrets | Credentials remain in existing authenticated tools/environment and never enter tracked files or command output | all steps | Token-like data appears in diff, logs, or state artifacts | + +## Preconditions + +| Precondition ID | Canonical ref | Required state | Used by steps | Blocks start | +| --- | --- | --- | --- | --- | +| `PRE-01` | `CON-01`, `SOL-01`, `INV-01` | Restricted remains the accepted default | `STEP-01` - `STEP-05` | yes | +| `PRE-02` | `ASM-01`, `SOL-03`, `CTR-03`, `CTR-04` | Supported command grammar is recorded and locally inspectable | `STEP-03`, `STEP-06` | yes | +| `PRE-03` | `CON-04`, `SD-04`, `RB-03` | Explicit operator approval and isolated target exist | `STEP-06` | no; blocks live acceptance only | + +## Workstreams + +| Workstream | Implements | Result | Owner | Dependencies | +| --- | --- | --- | --- | --- | +| `WS-1` | `REQ-03`, `SOL-01`, `SD-02`, `CTR-01`, `CTR-02` | Validated permission resolution and early errors | agent | `PRE-01` | +| `WS-2` | `REQ-01`, `REQ-02`, `REQ-04`, `SOL-02` - `SOL-05`, `CTR-03` - `CTR-05` | Correct commands and visible capability status | agent | `WS-1`, `PRE-02` | +| `WS-3` | `REQ-06`, `REQ-07`, `SC-01` - `SC-05` | Automated regression coverage and aligned docs | agent | `WS-1`, `WS-2` | +| `WS-4` | `REQ-08`, `SOL-06`, `SC-06`, `RB-03` | Guarded full-delivery E2E evidence | human + agent | `WS-2`, `WS-3`, `PRE-03`, `AG-01` | + +## Approval Gates + +| Approval Gate ID | Trigger | Applies to | Why approval is required | Approver / evidence | +| --- | --- | --- | --- | --- | +| `AG-01` | Running a real full-delivery session that can commit, push, and create/update a PR | `STEP-06`, `WS-4`, `CHK-03` | The run is unsandboxed and creates external GitHub state | User names/approves the fixture target; retained log and PR URL record approval context | + +## Work Order + +| Step ID | Actor | Implements | Goal | Touchpoints | Artifact | Verifies | Evidence IDs | Check command / procedure | Blocked by | Needs approval | Escalate if | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| `STEP-01` | agent | `REQ-03`, `SOL-01`, `SD-02`, `CTR-01`, `CTR-02`, `FM-03` | Add CLI/environment/default resolution and fail-fast validation | `scripts/start-issue`, `cli.sh`, `config.sh` | Resolved mode and source | `CHK-01`, `NEG-01` | `EVID-01` | Focused Bats tests, then `make test` | `PRE-01` | none | Validation occurs after fetch or mutation | +| `STEP-02` | agent | `REQ-07`, `INV-01`, `INV-02` | Extend fake Codex and tests before changing launcher behavior | Fake Codex, Bats suite | Red/green command contract tests | `CHK-01`, `SC-01` - `SC-04` | `EVID-01` | `bats test/start_issue.bats` | `STEP-01` | none | Fake cannot distinguish global and exec arguments | +| `STEP-03` | agent | `REQ-01`, `REQ-02`, `REQ-04`, `SOL-02`, `SOL-03`, `CTR-03`, `CTR-04`, `INV-04` | Build validated restricted/full-delivery commands in supported order | `agent.sh` | Array-based Codex command mapping | `CHK-01`, `SC-02`, `SC-03` | `EVID-01` | Focused Bats tests; inspect `--dry-run` command | `STEP-02`, `PRE-02` | none | Supported Codex rejects generated grammar | +| `STEP-04` | agent | `REQ-01`, `REQ-06`, `SOL-04`, `CTR-05`, `FM-02`, `FM-04` | Add capability output, warning, dedicated help, and public docs | `output.sh`, README files, spec | Consistent operator contract | `CHK-02`, `SC-05`, `NEG-02` | `EVID-02` | Help assertions and documentation review | `STEP-03` | none | Docs imply permission equals credentials or product authorization | +| `STEP-05` | agent | `REQ-05`, `REQ-07`, `SOL-05`, `INV-05`, `RB-01`, `RB-02` | Run full deterministic regression and simplify review | All changed runtime/tests/docs | Green local suite and complexity verdict | `CHK-01`, `CHK-02`, `SC-04` | `EVID-01`, `EVID-02`, `EVID-09` | `make test`; inspect diff for unnecessary branches/abstractions | `STEP-01` - `STEP-04` | none | FT-015 state/resume behavior changes | +| `STEP-06` | human + agent | `REQ-08`, `SOL-06`, `SD-04`, `SC-06`, `NEG-03`, `RB-03` | Extend/run isolated live full-delivery verification and retain evidence | E2E runner and approved fixture repo/issue | E2E log, state artifacts, commit and PR URL | `CHK-03`, `EC-06` | `EVID-03` | Follow canonical cmux caller-tab procedure and poll to terminal PASS/failure | `STEP-05`, `PRE-03`, `OQ-02` | `AG-01` | Target/auth/caller context is missing, or any unexpected external scope appears | + +## Parallelizable Work + +- `PAR-01` Documentation wording and fake-Codex fixture preparation can proceed + in parallel after `STEP-01` stabilizes names and precedence. +- `PAR-02` Launcher code and command-order assertions share the same contract + and should be reviewed together even if edited in parallel. +- `PAR-03` Live E2E work cannot begin before deterministic checks and explicit + approval complete. + +## Checkpoints + +| Checkpoint ID | Refs | Condition | Evidence IDs | +| --- | --- | --- | --- | +| `CP-01` | `STEP-01`, `STEP-02`, `CTR-01`, `CTR-02`, `FM-03` | Precedence/default/error behavior is deterministic and side-effect free | `EVID-01` | +| `CP-02` | `STEP-03`, `CTR-03`, `CTR-04`, `FM-01` | Both commands match supported grammar and exact sandbox mapping | `EVID-01` | +| `CP-03` | `STEP-04`, `STEP-05`, `CTR-05`, `INV-05` | Docs/help/tests agree and FT-015 regression suite passes | `EVID-01`, `EVID-02`, `EVID-09` | +| `CP-04` | `STEP-06`, `RB-03`, `AG-01` | Approved live run records full Git delivery or a precise capability failure | `EVID-03` | + +## Execution Risks + +| Risk ID | Risk | Impact | Mitigation | Trigger | +| --- | --- | --- | --- | --- | +| `ER-01` | Codex option grammar changes again | Batch mode fails before thread creation | Centralize command mapping, assert order, document tested baseline, run opt-in real smoke | Parser rejection or missing `thread.started` | +| `ER-02` | Full-delivery mode is mistaken for product authorization | Agent can perform unintended high-impact work | High-signal warning, explicit opt-in, preserve prompt human-gate rules | Docs/output omit warning or prompt bypass is proposed | +| `ER-03` | Configuration surface expands unnecessarily | More precedence and persistence bugs | Keep one CLI option, one env variable, one safe default | Proposal adds raw passthrough or project/user persistence | +| `ER-04` | Live E2E writes to the wrong repository | Unwanted external branch/PR state | Require explicit approved target and canonical cmux caller context | Target or caller context is ambiguous | + +## Stop Conditions / Fallback + +| Stop ID | Related refs | Trigger | Immediate action | Safe fallback state | +| --- | --- | --- | --- | --- | +| `STOP-01` | `FM-01`, `RB-01` | Supported Codex rejects restricted command | Stop rollout and retain existing FT-015-compatible restricted behavior | No full-delivery exposure | +| `STOP-02` | `FM-02`, `RB-03`, `AG-01` | Live target/auth/capability is missing | Stop without guessing credentials or target; retain logs | Deterministic implementation complete, live acceptance pending | +| `STOP-03` | `FM-04`, `NS-03`, `SD-03` | Implementation treats full delivery as destructive/production authorization | Remove that behavior and return to prompt-gated policy | Explicit mode controls capability only | +| `STOP-04` | `INV-05`, `REQ-05` | Thread/state/resume regression appears | Back out permission changes until FT-015 behavior is restored | Existing restricted human-gate flow | + +## Plan-local Evidence + +| Evidence ID | Artifact | Producer | Path contract | Reused by checkpoints | +| --- | --- | --- | --- | --- | +| `EVID-09` | Simplify-review verdict for the final runtime diff | implementer / reviewer | Final handoff or PR review note | `CP-03` | + +## Ready for Acceptance + +- `CP-01` through `CP-03` have deterministic evidence. +- `CP-04` has explicitly approved live evidence; otherwise FT-017 remains short + of `delivery_status: done`. +- `make test` and required CI jobs are green. +- No secrets, arbitrary argument interpolation, or hidden privilege defaults + were introduced. +- Final acceptance uses `brief.md` `CHK-01` through `CHK-03` and their evidence + contracts. diff --git a/memory-bank/features/README.md b/memory-bank/features/README.md index 0ec58d1..16cb5cb 100644 --- a/memory-bank/features/README.md +++ b/memory-bank/features/README.md @@ -32,5 +32,13 @@ audience: humans_and_agents ## Feature packages +- [Missing feature packages inventory](missing.md) + Comparison of GitHub issues with instantiated packages, including current + gaps, duplicates, and superseded migration work. + - [FT-016: Real Codex human-gate E2E suite](FT-016/README.md) Opt-in local smoke suite that validates the real Codex human-gate path. + +- [FT-017: Codex human-gate delivery permissions](FT-017/README.md) + Explicit restricted/default and opt-in full-delivery capability contract for + Codex human-gate runs. diff --git a/memory-bank/features/missing.md b/memory-bank/features/missing.md new file mode 100644 index 0000000..fa8896f --- /dev/null +++ b/memory-bank/features/missing.md @@ -0,0 +1,79 @@ +--- +title: Missing feature packages inventory +doc_kind: feature +doc_function: index +purpose: "Inventory of GitHub issue work that is not represented by a dedicated feature package, including duplicate and superseded work." +derived_from: + - ../dna/governance.md + - ../product/context.md + - ../../README.md + - https://github.com/dapi/start-issue/issues +status: active +audience: humans_and_agents +--- + +# Missing Feature Packages + +This inventory compares the GitHub issue history with the instantiated +packages under this directory. It is a navigation and gap document, not a +replacement for a feature `brief.md`. + +## Current gaps + +| Issue | Current state | Memory-bank state | Gap / recommended action | +| --- | --- | --- | --- | +| [#35](https://github.com/dapi/start-issue/issues/35) | Open; duplicates the already delivered #13 contract | FT-013 documents and implements the release-backed self-update, but does not reference #35. | Do not create a second package. Reconcile #35 with FT-013: add the issue as provenance or close the duplicate after verifying the acceptance criteria against current tests. | + +## Closed issues without a dedicated package + +These issues are implemented or closed in GitHub, but their requirements are +not independently navigable from `memory-bank/features/`: + +| Issues | Missing coverage | +| --- | --- | +| [#1](https://github.com/dapi/start-issue/issues/1) | Agent-agnostic configurable portable prompt. | +| [#2](https://github.com/dapi/start-issue/issues/2) | No-issue configuration/status summary showing selected agent and prompt. | +| [#3](https://github.com/dapi/start-issue/issues/3) | `init` project/user configuration initialization with defaults. | +| [#30](https://github.com/dapi/start-issue/issues/30) | Meaningful transliterated branch slugs and removal of bracketed title tags. | +| [#32](https://github.com/dapi/start-issue/issues/32) | Explicit terminal status before waiting for input or handing off to an agent. | + +Create packages for these only if their behavior is expected to remain a +separately maintained product contract. Otherwise, add their issue links to +the relevant canonical package or to a historical decision record. + +## Not feature work: migrations + +Issue [#34](https://github.com/dapi/start-issue/issues/34) is a Go rewrite and +distribution/runtime migration, not a product feature. It should be tracked +as an architecture/migration package (and, where needed, an ADR) under +`memory-bank/adr/` or a dedicated migration area. `FT-016` must remain reserved +for the real Codex E2E suite; the issue branch's attempted reuse of that ID +should not be copied into the feature catalog. + +## Superseded migration issues + +Issues [#15](https://github.com/dapi/start-issue/issues/15) and +[#17](https://github.com/dapi/start-issue/issues/17)–[#23](https://github.com/dapi/start-issue/issues/23) +describe a Rust migration sequence, but the current repository has no Rust +runtime or Rust feature packages. The newer [#34](https://github.com/dapi/start-issue/issues/34) +reframes the migration in Go. These issues should be represented by one +historical/supersession note or by the migration/ADR for #34, not by seven +duplicate feature packages. + +## Already represented + +The following issue work has a corresponding package: + +- #4 → [FT-004](FT-004/README.md) +- #8 → [FT-008](FT-008/README.md) +- #9 → [FT-009](FT-009/README.md) +- #12 → [FT-012](FT-012/README.md) +- #13 → [FT-013](FT-013/README.md) +- #25 → [FT-014](FT-014/README.md) +- #26 → [FT-015](FT-015/README.md) +- Real Codex E2E validation → [FT-016](FT-016/README.md) +- #37 → [FT-017](FT-017/README.md) + +The package `delivery_status` fields still describe several packages as +`in_progress`; issue closure alone is not treated as evidence that a feature +package has passed its documented verification contract.