[Workstream F] PR 13 of 21: Wire issue-tracer v3 receipts and prove issue ingestion reaches a durable plan

[zaxbysauce]

Roadmap: F13 · Workstream F: User workflows, host support and configuration
Sequence: PR 13 of 21 (tracking slot; dependencies define execution order)
Roadmap rebaseline: 2026-09-05

The existing scope below remains required. Historical source/validation notes are context, not fresh execution evidence; the 2026-09-05 requirements refine the current closure contract.

Summary

Follow-up to #2563 (issue-tracer v3). The v3 protocol adds gates that are currently enforced only by scripts/trace-check.sh and by convention in the trace ledger. The plugin-side reducer (src/hooks/issue-trace-reducer.ts) and record-recurrence-sweep do not yet record receipts for them.

Scope

• Phase 0 branch-freshness receipt (fetch result or fail-closed override string).
• trace-check.sh validator receipts per phase (pass/fail, reviewed-commit, tree-id).
• Widened recurrence sweep receipt (Phase 1 related-problems sweep results).
• Merge-approval receipt bound to the PR head (10b-merge-approval.md), recorded but never certified by the plugin.

Constraints

• Must follow the "never defer work / never ship unwired code" directives: reducer transition, status enum, tool map, docs, and tests wired in one change.
• Keep the repo model-agnostic; no runner routing in the reducer.

Related: #2563

2026-09-05 required additions and corrections

• Prove each v3 receipt has a producer, exact current phase/head/run consumer and registered tool/status/docs path; declarations alone are not execution evidence.
• Include a normal issue-ingestion journey: issue input -> research/knowledge/scope gates -> durable plan with acceptance criteria, files and requirement references -> interruption/resume or truthful cancellation. Verify the actionable next step at each gate.
• [Workstream D] PR 09 of 17: Recover complete plans from the ledger and preserve valid U+FFFD text #2531 owns the plan recovery defect. Coordinate focused ingestion validation with it, without making unrelated PR-review features prerequisites. Keep merge approval recorded but never certified by the plugin, and preserve model-agnostic runtime rules.

Execution and closure contract

Treat PR n of total as a stable tracking slot, not merge order. The explicit dependencies govern execution; focused implementation issues supply evidence to later qualification issues without depending on those later issues closing. Re-anchor source and active-PR overlap before implementation. Close only the fully satisfied scope: wired production callers, meaningful focused validation and documented outcomes, with no silent deferral. For user-visible code changes, include the repository-required pending release fragment and invariant audit; no version/changelog hand edits. Verification-only residuals may close with concrete current evidence rather than an unnecessary code patch.

[zaxbysauce]

Verified against HEAD: the gap described here is real. The plugin-side reducer (src/hooks/issue-trace-reducer.ts) only knows the v2-era artifacts — reproduction, critic approval, implementation-review receipt, recurrence-sweep receipt, publication receipt. Issue-tracer v3's Phase 0 branch-freshness receipt, the per-phase trace-check.sh validator receipts, and the 10b-merge-approval receipt appear nowhere under src/; grep finds them only in .opencode/skills/issue-tracer/ (SKILL.md gate table and the validator script) plus their shell-side tests. record_recurrence_sweep (src/tools/record-recurrence-sweep.ts) validates only the residual-B shape (defectClass/predicates/dispositions/guardrail) with no Phase 1 related-problems sweep field, and the matching reader in src/hooks/issue-trace-state.ts enforces the same v2 shape. One nuance worth preserving in the design: merge-approval must stay recorded-but-never-certified — trace-check.sh already documents it as a human-enforced gate it cannot certify, and the plugin should inherit that exact posture rather than gaining authority over merges. Also note the existing e2e test reaches published only via internals overrides and the receipt tools are tested in isolation, so the required ingestion-journey fixture (issue input -> gates -> durable plan -> interruption/resume or truthful cancellation, with real record* calls driving the reducer) is genuinely new coverage, not a re-run of existing tests. Coordinate the fixture with #2531 (plan recovery defect) and the reducer-transition/skill-integration work in #2600 so the two changes don't duplicate the wiring, and include the required pending release fragment and invariant audit in the same change.

[zaxbysauce]

[Deep-dive audit 2026-09-06, HEAD e58e383d5] Journey-proof confirmation for your 2026-09-05 required additions: no test currently wires handleIssueCommand + the real record_* receipt tools + the reducer to published. tests/unit/hooks/issue-trace-e2e.test.ts reaches published only via _internals DI overrides (critic approval and plan phase status), and the receipt tools are tested only in isolation (record-issue-receipts.test.ts, record-residual-b-receipts.test.ts); handleIssueCommand is tested for parsing/persistence only. A reducer/skill-integration defect would pass all unit tests and still wedge a real run — which matches this host's history (a trace parked in_progress since 2026-08-27 while a later non-trace invocation rewrote the reference).

The reducer-side defects the audit found (missing plan↔issue binding DD-C001, silent rows (d)/(g) DD-C002, non-trace invocation writing in_progress DD-C005, vacuous dispositions DD-C009) are tracked in #2600, which will land the reducer transitions + skill text + tests in one change; its integration test should be coordinated with (or become part of) your ingestion-journey fixture so the two PRs don't duplicate the wiring.

[zaxbysauce]

Delivered via #2783 (head d2ff0213, branch feat/issue-2564-tracer-v3-receipts, base b865ba262).

What landed (all four v3 receipt surfaces wired in one change — producer, reader, reducer-consumer, registration, docs, tests):

• Phase 0 branch-freshness receipt: record_branch_freshness → .swarm/branch-freshness.json; the reader mirrors trace-check.sh phase0 exactly (behind and bare fetch-failed fail closed; only a recorded user override rescues a failed fetch); the reducer's new FRESHNESS_GATE one-shot parks the trace before PLAN until the receipt permits.
• Per-phase validator receipts: record_trace_validation records each trace-check.sh phase <N> outcome (v3 phase enum, pass/fail, 40-hex reviewedCommit + treeId), upserting per phase into .swarm/trace-validation.json; any fail entry fails closed until re-recorded as a pass; the reducer's TRACE_VALIDATION_GATE blocks the commit-pr handoff and chains after the recurrence gate in the canonical ladder.
• Widened recurrence sweep: record_recurrence_sweep now requires relatedProblems (Phase 1 related-problems sweep results, ≥1 entry) on both defect-class paths; the reader enforces the widened shape non-vacuously (v2-shaped receipts no longer satisfy the gate).
• Merge-approval receipt: record_merge_approval binds the human approval to the exact PR head (prHeadSha === finalCriticReviewedCommit, mismatch rejected at write time) with the approval verbatim; the trace gains the true terminal merge_approval_recorded status after published — recorded, never certified: nextMode stays null and the directive names the human as the merge authority, inheriting trace-check.sh's posture verbatim.

2026-09-05 required additions: each receipt's producer/consumer/tool/status/docs path is proven by the frozen arm's-length acceptance checks C1-C9 (red-checkpointed at base, all green at head) and a new end-to-end journey suite that drives handleIssueCommand + every real record_* executor + the ledger-authoritative savePlan/loadPlan (tasks carry acceptance criteria, files_touched, fr_refs) + the real approve_plan_critic path + an interruption/resume step (module cache resets) through every gate to published and then merge_approval_recorded, asserting the actionable next step at each gate — no _internals behavioral overrides. Coordination: #2600's reducer defects are NOT absorbed (rows (d)/(g) untouched, DD-C009 empty-dispositions acceptance preserved — pinned by a PRESERVING check); #2531's ledger recovery is exercised (the journey reads plans through the ledger-aware loader); #2566 owns load-time receipt migrations (documented in the release fragment).

Process evidence: plan critic (2 rounds, APPROVE), independent implementation reviewer (4 rounds, APPROVE — caught an FR-006 cap violation and a truthful-directive regression, both fixed and re-verified), final critic (2 rounds, APPROVE — caught a silent-park at the new validation gate, fixed and re-verified). All nine frozen checks RED/ERROR at base → GREEN at head; PRESERVING checks stayed GREEN throughout. A pre-existing committed merge-conflict marker in docs/observability-retention-registry.md (verified at base) was resolved and disclosed in the PR body.

The issue can close when #2783 merges; the merge decision itself is human-enforced.