loki-mode 9.22.4 → 9.22.6

package/docs/ISSUE-TO-PR-GOLDEN-PATH-PLAN.md

@@ -0,0 +1,257 @@
+# Issue-to-PR Golden Path -- Architecture and Acceptance Plan
+
+Lane: LOKI-GOLDEN-PATH-68. Status: plan for the first user-visible slice.
+
+## 0. Two scope facts stated up front
+
+**Which file was read as AGENTS.md.** There is no `AGENTS.md` at the repo root.
+The two candidates are `skills/agents.md` (263 lines) and `references/agents.md`
+(1043 lines). `skills/agents.md` was read in full; it is the agent-dispatch and
+structured-prompting module, and its "Project AGENTS.md" section (L184-192)
+defines the AAIF priority order this repo follows. It contains no numbered
+feature list.
+
+**Where the feature numbering comes from.** The directive names features
+1, 2, 3, 4, 9, 10. No document in this repo contains a numbered list of >=10
+items describing the issue-to-PR journey. `docs/CAPABILITY-BACKLOG.md` has a
+numbered priority table but it stops at 6 and is about verification-tax
+measurement, not this journey. This was verified exhaustively, not
+assumed: searches over the semantics (`review-ready`, `time to first`,
+`issue to PR`, `golden path`) across every file type, every local and remote
+ref, and deleted files in git history found no such list. The phrase "golden
+path" appears nowhere in the repo, and the closest founder mandates
+(`docs/COCKPIT-UX-MANDATE.md`, the deleted `docs/KILLER-FEATURE-MANDATE.md`)
+carry 6 and 7 items respectively on unrelated subjects.
+
+Therefore this plan maps the six labels onto the six required-outcome clauses in
+the directive itself, in the order the directive states them. This is an
+assumption, and it is recorded here so it can be corrected cheaply:
+
+| # | Feature | Directive clause |
+|---|---------|------------------|
+| 1 | Single entrypoint | one `loki start <issue>` path |
+| 2 | Exact acceptance context import | imports exact issue acceptance context |
+| 3 | Early machine-readable status/plan | useful machine-readable early result inside 60s |
+| 4 | One unified review-ready result | completes with one unified review-ready result |
+| 9 | Consent-gated PR | PR created/prepared only after existing consent rules |
+| 10 | Truthful evidence receipt | attaches a truthful evidence/outcome receipt |
+
+Features 5-8 are unallocated under this reading. Nothing in this slice claims
+to implement them.
+
+## 1. What already exists (verified by reading, not assumed)
+
+This journey is mostly assembled, not missing. The slice is integration.
+
+| Seam | Location | State |
+|---|---|---|
+| Issue ref parsing | `autonomy/issue-parser.sh:89` `parse_issue_ref` | Handles URL, `owner/repo#N`, bare `N` |
+| Acceptance extraction | `autonomy/issue-parser.sh:154` `extract_acceptance_criteria` | Extracts checkboxes + Acceptance Criteria / Requirements sections |
+| Structured issue output | `autonomy/issue-parser.sh:423` `output_json` | Emits `acceptance_criteria` as a JSON field |
+| Single entrypoint | `autonomy/loki:2779` | `loki start` already detects issue refs and re-dispatches to `cmd_run` |
+| PR creation (attached) | `autonomy/loki:10237` | `gh pr create` in the `cmd_run` github branch |
+| PR creation (detached) | `autonomy/loki:10088` | second `gh pr create` inside the detached inner script |
+| Evidence receipt render | `autonomy/lib/proof-pr.sh:49` `render_evidence_receipt_md` | Print-only, honesty-gated, never blocks PR creation |
+| Proof assembly | `autonomy/lib/proof-generator.py:1097` `_build_proof` | Emits facts/assessments/honesty blocks |
+| Time to first artifact | `.loki/state/first-artifact.json` (writer `run.sh:23292`, reader `run.sh:4271`) | `seconds_to_first_artifact`, write-once |
+| Intervention socket | `autonomy/lib/trust_trajectory.py:145` `_interventions_value` | Reads `proof.interventions`; documents that no writer exists yet |
+| Zero-spend preview pattern | `autonomy/quickstart.sh:475` + `_qs_load_preview:510` | `--dry-run --json`, schema-v1, bounded + validated |
+| Test harness pattern | `tests/cli/test-quickstart.sh` | Source-level stubs, zero spend, zero network |
+
+### Required product facts: already present vs missing
+
+Present in `proof.json` today: elapsed time (`wall_clock_sec`), iterations
+(`_collect_iterations`, with progress/rework attribution), exact changed files
+(`_git_diffstat`), test outcomes (`_collect_tests`), spec (`_collect_spec`).
+
+Missing and in scope for this slice: time to first useful result,
+human-intervention count, acceptance-criteria coverage, PR state/URL,
+uncertainty, rollback, and lint/typecheck/build commands recorded alongside
+their outcomes.
+
+## 2. Architecture of the slice
+
+Four small additions on existing seams. No new subsystem, no new gate, no new
+artifact format (`docs/CAPABILITY-BACKLOG.md:45-50` explicitly forbids the
+last two).
+
+**A. Carry acceptance criteria forward (feature 2).**
+`extract_acceptance_criteria` already produces the exact criteria; they are
+rendered into a generated PRD and then lost. Persist the parsed criteria to
+`.loki/state/issue-context.json` at import time so later stages can key on the
+exact text rather than re-deriving it from prose.
+
+**B. Early machine-readable plan (feature 3).**
+Write `.loki/state/journey-plan.json` from the issue-parse output *before the
+first provider call*. Because it is derived from `gh` output and not from model
+output, it does not depend on provider latency at all -- the 60s budget becomes
+deterministic rather than conditional. Shape and validation discipline mirror
+the quickstart schema-v1 preview.
+
+**C. Receipt facts (features 4 and 10).**
+Extend `_build_proof` with the missing facts, and extend
+`render_evidence_receipt_md` to print them. Both follow the honesty rule already
+enforced throughout this codebase: absent measurement renders nothing, never a
+fabricated zero (`run.sh:4258`, `proof-generator.py` `_compute_degraded`).
+Acceptance coverage is reported as *stated vs addressed*, never as a pass/fail
+verdict, because no deterministic checker exists for free-text criteria; claiming
+one would be the exact "fake green" this repo's trust core forbids.
+Interventions fill the socket `trust_trajectory.py:145` already reads.
+
+**D. Consent-gated PR (feature 9).**
+The consent rules already exist; the gap is that there are **two**
+`gh pr create` call sites and a guard on one leaves the other unguarded. This
+slice covers the attached path at `autonomy/loki:10237` and adds a
+prepare-only mode that writes the PR title/body to disk without mutating
+GitHub. The detached path at `:10088` is explicitly **not** covered by this
+slice and is named in section 5 as remaining work.
+
+## 3. Files to change
+
+| File | Change |
+|---|---|
+| `autonomy/issue-parser.sh` | Persist parsed issue context (incl. exact acceptance criteria) to `.loki/state/issue-context.json` |
+| `autonomy/loki` | Write `journey-plan.json` before the provider call; add prepare-only PR mode at the `:10237` seam |
+| `autonomy/lib/proof-generator.py` | Collect the 7 missing facts into the existing `facts` block |
+| `autonomy/lib/proof-pr.sh` | Render the new facts in the receipt, honesty-gated |
+| `tests/cli/test-issue-to-pr.sh` | New: end-to-end journey test with mocked `gh` + provider |
+
+Deliberately unchanged: `autonomy/run.sh` prompt construction. CLAUDE.md records
+that goal scoring is byte-mirrored between `run.sh` and
+`loki-ts/src/runner/goal_score.ts` and that parity fixtures diverge if one side
+is edited. Staying out of `build_prompt` also avoids the prompt-cache prefix
+rule and the `loki-ts` dist-rebuild requirement entirely.
+
+## 4. Acceptance tests
+
+All zero-spend, zero-network, no external GitHub mutation. `gh` and the provider
+are PATH-shimmed exactly as `tests/cli/test-quickstart.sh` shims its boundaries.
+
+1. **Issue ref forms** -- URL, `owner/repo#N`, and bare `N` all resolve to the
+   same parsed context.
+2. **Exact acceptance import** -- criteria in `issue-context.json` match the
+   fixture issue body verbatim, including checkbox items.
+3. **Early plan exists and validates** -- `journey-plan.json` is written before
+   any provider invocation, and parses against the expected schema.
+4. **Provider-free dry-run** -- the full journey runs to a printed contract with
+   the provider shim asserting it was never called.
+5. **No PR without consent** -- default path performs no `gh pr create`; the
+   `gh` shim records every invocation and the test asserts the mutation set is
+   empty.
+6. **Prepare-only writes locally** -- prepare mode produces a PR body on disk
+   and still performs no GitHub mutation.
+7. **Receipt truthfulness** -- with facts absent, the receipt omits them rather
+   than printing zeros; with facts present, it prints the measured values.
+8. **Acceptance coverage is not a verdict** -- coverage renders as stated vs
+   addressed and never emits a pass/fail claim.
+
+## 4a. What shipped (post-implementation)
+
+Implemented as planned, with one deviation recorded honestly:
+
+- `autonomy/issue-parser.sh` -- `_gp_criteria_lines` + `write_journey_context`,
+  called from the `parse_github_issue` chokepoint so every caller is covered.
+- `autonomy/loki` -- `--prepare-pr` at BOTH `loki start` and `cmd_run`; a
+  prepare-only block that writes `pr-title.txt` / `pr-body.md` / `pr.json` and
+  never invokes `gh`; PR state recorded on the published path only on ACTUAL
+  success, so a failed create cannot leave a "created" claim behind.
+- `autonomy/lib/proof-generator.py` -- `_collect_journey` + the top-level
+  `interventions` mirror.
+- `autonomy/lib/proof-pr.sh` -- journey rows, each conditional on measurement.
+- `tests/cli/test-issue-to-pr.sh` -- 13 assertions, all passing.
+
+**Two dead-code defects found and fixed during verification.** Both were caught
+only by driving the real CLI; every unit test stayed green through both.
+
+1. **Wrong chokepoint.** The first implementation hooked
+   `issue-parser.sh::parse_github_issue`, which serves ONLY the deprecated
+   `loki issue parse|view`. `loki start` / `loki run` route through
+   `fetch_issue` (`autonomy/issue-providers.sh:333`), so features 2 and 3 were
+   dead on the required path. Re-hooked at the `fetch_issue` call site in
+   `cmd_run`, which is also provider-agnostic (github/gitlab/jira/azure). A
+   follow-on bug surfaced there too: `ISSUE_OWNER`/`ISSUE_REPO` are re-cleared
+   by later `parse_issue_reference` calls, producing a `"/#42"` ref; the ref now
+   comes from the normalized JSON's `repo` field.
+
+2. **Unreachable after exec.** `cmd_start` exec-replaces the process
+   (`autonomy/loki:3490`), so everything after a bare call in `cmd_run` is
+   unreachable -- including the PRE-EXISTING `if $create_pr` block, which
+   explains why the detached route reimplements PR creation instead of sharing
+   it. Verified empirically with a minimal repro, not inferred. `--prepare-pr`
+   now subshells the runner so control returns; the default path keeps the bare
+   call, because subshelling everything would change signal and Ctrl+C
+   semantics for existing users.
+
+A third defect was found in the test harness itself: the issue fixture was
+built with `python3 -c '...' FIXTURE_BODY="$body"`, which passes a positional
+argument rather than an environment variable, so `os.environ` raised and
+`2>/dev/null` hid it. The empty fixture made the CLI fail to fetch while
+assertions passed for the wrong reason. Fixed, and an explicit non-empty guard
+now fails loudly rather than vacuously.
+
+**Deviation.** The first draft of `_gp_criteria_lines` carried a `grep -vE '^#'`
+guard against a section heading leaking in as a criterion. Mutation testing
+showed the guard was never reached: `extract_acceptance_criteria`'s `sed` range
+already terminates at the next `^#`, and four separate constructions failed to
+produce a heading that reached the filter. It was removed rather than kept as
+decorative defense. The horizontal-rule guard beside it was tested the same way,
+found genuinely load-bearing (a bare `---` survives the bullet-strip as a lone
+`-` and would become a phantom criterion), and kept with a dedicated test.
+
+## 4b. Required product facts: delivered vs not
+
+| Fact | Status |
+|---|---|
+| Elapsed time | delivered (pre-existing `wall_clock_sec`) |
+| Time to first useful result | delivered (reads the existing `first-artifact.json`) |
+| Iterations | delivered (pre-existing, incl. progress/rework split) |
+| Human interventions | delivered; writer added at `run.sh::handle_pause` |
+| Exact changed files | delivered (pre-existing `_git_diffstat`) |
+| Test command + outcome | delivered (pre-existing) |
+| Build command + outcome | delivered (pre-existing) |
+| **Lint command + outcome** | **NOT delivered** |
+| **Typecheck command + outcome** | **NOT delivered** |
+| Acceptance-criteria coverage | delivered as *stated*, never as *met* (see below) |
+| PR state / URL | delivered (`prepared` and `created`) |
+| Uncertainty | delivered (counts `honesty.degraded[]`) |
+| Rollback | delivered (`git reset --hard <base_sha>`) |
+
+**Lint and typecheck are not delivered, and nothing in the receipt pretends they
+are.** There is no lint or typecheck record anywhere in the proof chain today
+(`grep -rn "lint\|typecheck" autonomy/lib/proof-generator.py
+autonomy/lib/proof-pr.sh` returns nothing). Emitting them would require
+instrumenting the gate-execution path in `run.sh` to record each command and
+exit code -- real scope, and beyond a first coherent slice. Because every row in
+this receipt is conditional on measurement, their absence renders no row rather
+than a false green.
+
+**Acceptance coverage is a correspondence, not a verdict.** `addressed_count` is
+deliberately `null`, not `0`: there is no deterministic checker for free-text
+criteria, and `0` would read as "none met", which is not known. The row states
+how many criteria the issue asked for and says plainly that they are not
+machine-verified.
+
+## 5. Explicitly not done in this slice
+
+- Lint and typecheck command/outcome capture (see section 4b).
+- The detached `gh pr create` (the inner detached script) is unguarded by this
+  slice's prepare-only mode, and the pre-existing attached `--pr` block remains
+  dead code after the `cmd_start` exec. This slice does NOT revive it: making
+  `--pr` publish from the attached path would turn a currently-inert flag into
+  one that mutates GitHub, which is a behavior change requiring its own consent
+  review rather than a side effect of this work.
+- GitLab (`glab`) parity for prepare-only mode.
+- Acceptance-criteria coverage is a reported correspondence, not a verified one.
+  There is no deterministic checker for free-text criteria and this slice does
+  not pretend to add one.
+- Features 5-8 under the numbering assumption in section 0.
+- No version bump, no release, no commit, no push.
+
+## 6. Risks
+
+| Risk | Mitigation |
+|---|---|
+| Numbering assumption in section 0 is wrong | Recorded explicitly; the six implemented clauses come verbatim from the directive, so the work stands even if labels are renumbered |
+| Two PR call sites, one guarded | Named as remaining work rather than silently half-fixed |
+| Receipt could overstate | Every new fact follows the existing absent-renders-nothing rule; coverage is never a verdict |
+| Dirty worktree | All new writes go to `.loki/state/`, which is run state, not tracked source |