feat(templates): reconcile authored scope against originating issues in propose, propose-batch, and decompose-phase

[joctaTorres]

Hardens the three change-authoring workflows so the failure chain #100 documents — a security-relevant half of an issue silently dropped, Closes #80 claimed anyway, the deferral invisible at the next phase boundary — is structurally impossible.

What changed

One shared fragment module, three embeds. src/core/templates/workflows/scope-reconciliation.ts is now the single author of three rule blocks:

• ISSUE_RECONCILIATION_STEP — identify every originating issue, fetch it, enumerate its material requirements from both its explicit fix items and the problems named in its narrative, map each to an authored feature or task, and surface every uncovered one as an enumerated "issue asks X, this proposal does not include X" decision point. Hedged source wording ("consider", "optionally") explicitly does not lower the bar for a security-relevant requirement — engine: RATCHET_BATCH_AGENT_CMD / RATCHET_EVAL_AGENT_CMD silently replace the agent in production — no gating, no notice, no journal marker, permissions bypassed #80's own "Consider requiring…" is what handed the original agent its de-scope justification.
• CLOSE_CLAIM_RULES — a close-claim is an output of verification, never an input of planning; partial work says "partially addresses #N".
• STOP_AND_SURFACE_GUARDRAIL — any de-scope of security-, permission-, or integrity-relevant work halts the workflow and asks; an approved deferral requires a filed, linked tracking issue with a named owner. A prose bullet in plan.md is not a deferral mechanism.

Three copies of a rule are exactly the drift this issue is about, so the rules live in one module each body interpolates once — which also turns "verbatim in all three" into a mechanical assertion instead of a prose review.

Per workflow:

• propose — reconciliation step before artifacts are authored; guardrails embedded. Its two verbatim-duplicated bodies (skill instructions + command content) were first collapsed into one builder parameterized by the two lines that genuinely differ; adding the rules to only one of them would have reproduced the divergence this issue is about, inside the fix for it.
• propose-batch — reconciliation before the manifest is scaffolded, plus the no-premature-Closes rule: phase contracts say "targets #N" / "addresses #N", and a done covering part of an issue says "partially addresses #N".
• decompose-phase — reads each prior phase's plan.md (not only the injected done paraphrase, in which plan-prose deferrals are invisible), extracts every out-of-scope / deferred / revisit item, and resolves each as carried-forward | tracked | explicitly-dropped. Silently ignoring one is not an available outcome. It also verifies a prior phase's Fixes/Closes #N was actually earned before treating the issue as shipped.

Both trees, through the generator. .claude/ and .opencode/ are gitignored here — they are rendered into consuming projects from these templates. test/core/init-scope-reconciliation.test.ts runs the real InitCommand and asserts the hardened text in both trees for all three skills, so the "both trees" requirement is proven through the generator rather than by hand-editing a tree that regeneration would revert.

Verification

Independent verify pass (fresh context, did not implement): PASS, no merge blockers. 20/20 feature scenarios backed by evidence; 207 files / 2969 tests green; coverage 95.54% ≥ 95% gate, threshold untouched; ratchet validate clean; lint clean.

Scope — partially addresses #100

Criteria 1–5 are fully met and mechanically tested. Two are partial, surfaced here rather than self-approved, per the rules this PR adds:

Criterion 6 — the worked-example demonstration. The fixture and llm-judge binding are authored, correctly bound (the case resolves to judged, not unjudged), and runnable. What cannot be produced is a passing verdict: extractVerdictJson (src/core/eval/judge.ts:211, from PR #40, on main) takes the last balanced top-level [...] in agent stdout, so under any stream-json adapter the real verdict array — which lives inside a JSON string value — is skipped in favour of the result envelope's own permission_denials array. Both installed adapters (claude, opencode) set emitsStreamJson; the three that don't are not installed, so switching adapters doesn't rescue it either. This branch touches neither src/core/eval/ nor src/core/batch/engine/ — git diff main...HEAD over both paths is empty.

This is a repo-wide pre-existing defect: it silently fails-closed every llm-judge binding under a stream-json adapter, including the pre-existing eval-self.yaml. It needs its own change and is not fixed here.

Weakening the spec so it passes, ratchet eval record-ing the verdict to green, and quietly checking the task off were each considered and rejected — they are the exact patterns this PR exists to forbid. Task 6.3 is left unchecked with its evidence recorded durably in plan.md (the run records themselves live in gitignored .ratchet/evals/runs/, which is precisely the "deferral recorded where nothing durable can see it" failure this change is about).

Criterion 7 — #80's remainder. The tracking half is done: #112 is open, assigned, and enumerates #80's unimplemented remainder as MUST-level close-gates — the ungated override seam, the permission posture voided under an override (buildAgentSpawnRequest's override branch returns a bare bash -c <override> and never calls buildAdapterRequest(), so the adapter's resolvePermissionFlags(...) block is skipped), and src/commands/batch/config.ts:118 printing the posture as enforced with no override awareness. All three were verified against origin/erh/phase-1-spawn-env-plumbing before filing. The remaining half — amending PR #97's Closes #80 — was declined by the repository owner, who will close #97 directly instead; that decision and its sign-off are recorded on task 8.2 per the security-remediation standard.

Because two criteria are partial, this PR partially addresses #100 and deliberately does not claim Closes. That is this change's own honest-close-claim rule applied to itself.

Standards

Follows security-remediation (this PR is its enforcement point in the authoring workflows), documentation (docs/configuration/generated-artifacts.md + README, with a Mermaid overview), testing, multi-agent-support (one shared definition rendered per agent through the adapter registry; bodies assert no agent-specific naming), generalizable-defaults (gh issue view <n> named only as a GitHub example, with a paste-the-issue-text fallback — no tracker baked in), instruction-fed-config (no config read added to any template body), and delegated-lifecycle (templates remain the single author of lifecycle instruction text).

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	ratchet	1f3900f	Commit Preview URL Branch Preview URL	Aug 26 2026, 10:59 PM