@garygentry/feature-forge 0.3.1 → 0.3.4

package/adapters/claude/skills/forge-fix/SKILL.md

@@ -2,41 +2,49 @@
 # GENERATED — DO NOT EDIT. Source: skills/forge-fix/SKILL.md. Regenerate: python3 scripts/build-adapters.py
 name: forge-fix
 description: Apply fixes from the most recent forge-verify findings document. Use when user runs /feature-forge:forge-fix or asks to apply verification fixes for a forge feature. Do NOT trigger for general code fixes, bug fixes, or repairs outside the forge verification workflow.
-argument-hint: <feature-name>
+argument-hint: <feature-name> [--served-stage <production-stage>]
 ---
 
 # forge-fix — Apply Verification Fixes
 
 Apply fixes from the most recent forge-verify findings document, with step-level tracking for crash recovery.
 
-Usually invoked by the user, but an **`autoFix` caller** may also invoke this skill automatically
-when `autoFix: true` is configured **and** its preconditions hold (the findings document has zero
-unresolved decision points, the working tree is clean, and a mandatory re-verify passes afterward).
-Two callers drive that chain: an **authoring stage's in-stage auto-verify** (the primary path — see
-`references/stage-exit-protocol.md`, the in-stage verify block) and the **`/feature-forge:forge`
-navigator's catch-up** (§3b). The **fix application** below is identical either way — this skill is
-not "auto-aware" about *applying* findings; it always applies the latest findings document. The
-**caller** owns the gating decisions, including the closing re-verify: the Step 6 gate is presented
-**only on a direct invocation**, because under an `autoFix` chain the caller (stage skill or
-navigator) runs the mandatory re-verify itself.
+Usually invoked by the user. An **`autoFix` caller** may also dispatch this skill automatically when `autoFix: true` is configured **and** its preconditions hold (the findings document has zero unresolved decision points, the working tree is clean, and a mandatory re-verify passes afterward). Two callers drive that chain: an **authoring stage's in-stage auto-verify** (the primary path — see `references/stage-exit-protocol.md`, the in-stage verify block) and the **`/feature-forge:forge` navigator's catch-up** (§3b). The **fix application** below is identical either way — this skill is not "auto-aware" about *applying* findings; it always applies the selected findings document. What differs is **branch ownership**, and ownership is read from the literal `owner:` token described under Prerequisites, never inferred from how the invocation happened to be phrased.
 
 ## Prerequisites
 
 Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
 
+**Ownership.** Determine branch ownership **at entry**, from the literal `owner: nested` / `owner: direct` token in the prompt that dispatched you. **Absent the token you are `direct`** — a user-typed `/feature-forge:forge-fix` is the only path that carries no dispatcher. Judge the token, never the phrasing of the invocation. Preserve that value unchanged through any re-verify and pass it straight through as `--owner` in Step 7. A **direct** fix stays the terminal owner through its optional re-verify; a **nested** fix invokes nested verify and returns its structured result to the outer stage, printing no terminal block at all. `references/stage-exit-protocol.md` § "Branch ownership: the `owner:` token" owns this rule.
+
 **Turn structure reminder:** Output analysis/context as text, then route ALL questions through `AskUserQuestion`. Never embed questions in text output — the user will not be prompted and the session will stall.
 
-## Step 1: Locate Findings Document
+## Step 1: Locate Findings and Establish the Served Stage
 
 1. Read `forge.config.json` for `specsDir` (default: `./specs`)
 2. Resolve the feature directory via the **Feature Directory Resolution** block in `references/shared-conventions.md` (a standalone feature resolves to its flat `{specsDir}/{feature}/` path exactly as today; an epic member resolves to its nested path). Then find the most recent `VERIFY-*-*.md` file in `{resolvedFeatureDir}/.verification/`.
-3. If no findings document exists, tell the user: "No verification findings found. Run `/feature-forge:forge-verify {feature}` first."
+3. **Establish the served production stage before any mutation**, in this order:
+   - An explicit `--served-stage {stage}` argument on this invocation is authoritative — that is what `forge-verify` and the scripted exit pass when they route here.
+   - Otherwise read it from the **selected report's own mode/header**: the `{mode}` in its `VERIFY-{mode}-{YYYY-MM-DD}.md` name together with the mode recorded in the report header, mapped as `epic` → `forge-0-epic`, `prd` → `forge-1-prd`, `tech` → `forge-2-tech`, `specs` → `forge-3-specs`, `backlog` → `forge-4-backlog`, `impl` → `forge-5-loop`.
+   - If both are present and disagree, fail closed rather than picking one.
+   - Never derive the served stage from conversational context, from `currentStage`, or from whichever feature stage happens to be newest. The report you are applying decides which stage this diversion serves.
+4. **An unestablishable served stage is a fail-closed error, not a guess.** If a report exists but its mode is missing, malformed, or ambiguous (for example two same-day reports for different modes, or a header whose mode does not match the filename) and no explicit `--served-stage` was supplied, mutate nothing: list the reports you found and tell the user to re-invoke as `/feature-forge:forge-fix {feature} --served-stage {stage}` or to re-run `/feature-forge:forge-verify {feature} {stage}`. Stop there — with no served stage there is no stage to close against, so do not run Step 7.
+5. **No applicable findings → `no-findings`.** If `.verification/` holds no findings document, or none whose steps still apply, the outcome is `no-findings`: mutate nothing and take the served stage from **authoritative pipeline state** — the production stage whose `stages.forge-verify-*` entry is unresolved (`findings-reported`, `findings-applied`, `auto-verify-pending`, or `pending`) — then close through Step 7. If no verification is outstanding either, there is nothing for this pass to serve: tell the user "No verification findings found. Run `/feature-forge:forge-verify {feature}` first." and stop without closing a stage.
 
 ## Step 2: Parse Fix Execution Plan
 
 1. Read the "Fix Execution Plan" section of the findings document
 2. Identify all execution steps and their dependencies
 3. Check for a `## Fix Progress` section at the bottom of the findings document — if present, some steps were already applied in a previous interrupted run
+4. **Assert the plan covers every finding** before any fix executes. Exit 1 is that assertion firing, not a tool failure; only exit 2 is a tool failure. Run:
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/fix-sweep.py" plan-coverage "{resolvedFeatureDir}/.verification/{findingsFile}" --json
+```
+
+Exit 0 with `"applicable": false` means the document declares no findings set or no plan to assert — proceed silently. Exit 1 → surface the **named** uncovered findings and any `claimed N, actual M` total mismatch, then resolve each one through `AskUserQuestion` per the **Decision Support** protocol in `references/shared-conventions.md`: either **author a covering execution step** into the Fix Execution Plan and execute it in this pass's Step 4, or **record an explicit justification** against that finding in the findings document. Never resolve a mismatch by editing the claimed total to match — re-derive which finding is missing and name it. Any finding still uncovered when you stop closes with `decisions` in Step 7, no advancement. Exit 2 → surface the `Error:` line verbatim and close with `failed`.
 
 ## Step 3: Handle User Decisions
 
@@ -45,6 +53,8 @@ If the "User Decisions Required" section has unresolved items:
 2. Wait for answers before proceeding
 3. Record decisions in the findings document under the "User Decisions Required" section (mark each as resolved)
 
+If any decision is still unresolved when you stop — the user deferred it, the question mechanism was unavailable, or no answer arrived — do **not** apply the steps that depend on it. Close with `decisions` in Step 7: that is the specific outcome for unanswered decisions, it never advances the pipeline, and its resume action names the unresolved work. A user who explicitly defers the **whole fix pass** is `deferred` instead; an operational failure that is not merely an unanswered decision is `failed` (Step 7).
+
 ## Step 4: Execute Fix Steps
 
 For each step in the "Execution Steps" section, in order:
@@ -57,32 +67,108 @@ For each step in the "Execution Steps" section, in order:
    ```
    - Step {N}: [APPLIED] {date} — {short summary of what was done}
    ```
-6. If a step fails or produces unexpected results, STOP. Report the issue to the user. Do not continue to dependent steps.
+6. If a step fails or produces unexpected results, STOP. Report the issue to the user. Do not continue to dependent steps. Any applied step stays recorded in `## Fix Progress` so a later run resumes rather than repeats, and this run closes with `failed` in Step 7 — no advancement.
+
+**Shipped comments state intent, never measurement (anti-churn).** A fix pass writes **no empirical or quantified claims** into comments, docstrings, or test narration — no "measured", "probed and confirmed", no counts of what was checked, no blanket claims over enumerated cases. Every such claim is a fresh falsifiable surface for the next verify round; a chain of them is exactly how a fix loop stops converging. Shipped prose states what the code intends and what constraint binds it. The evidence — what was probed, how, with what result — belongs in the findings document's `## Fix Progress` entry (and the commit message), which are the sanctioned records for acceptance evidence.
+
+**Closing sub-step — sweep for surviving occurrences of what you just corrected.** After the last plan step is applied and BEFORE Step 5 commits anything, while the working tree is still dirty, sweep this fix's own delta for text you removed that survives elsewhere. Pass no flags beyond `--json` — the exclusions the script applies by default are the correct ones in both a plugin repository and a consumer repository. Exit 1 means survivors were found: that is the sweep working, not a tool failure. Run:
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/fix-sweep.py" sweep --json
+```
+
+**Disposition every hit before Step 5.** Each hit names the file, the line, and the removed text it matched, so nothing needs re-deriving. Give every hit exactly one disposition — `FIXED` (you corrected the survivor now, in this pass, so the edit joins this same delta), `JUSTIFIED: {reason}` (it stands by decision: a deliberate quote, a historical or audit record), or `FALSE-POSITIVE: {reason}` (the match is not the corrected claim) — and record the sweep with its dispositions in the `## Fix Progress` section of the findings document, in this shape:
+
+```
+- Sweep: {date} — {K} needle(s), {N} survivor(s), {M} disposition(s)
+  - {file}:{line} — "{matched removed text}" → FIXED {date}
+  - {file}:{line} — "{matched removed text}" → JUSTIFIED: {reason}
+  - {file}:{line} — "{matched removed text}" → FALSE-POSITIVE: {reason}
+```
+
+Detection is mechanical; disposition is judgment — a hit is a candidate, not automatically a defect. When you cannot classify a hit confidently, route that hit through `AskUserQuestion` following the same **Decision Support** protocol as Step 3: lead with a recommended disposition and put the trade-off in each option's description. A survivor left awaiting a user decision closes with `decisions` in Step 7; a survivor you can neither fix nor justify closes with `failed`; a fully dispositioned sweep leaves this pass on whatever outcome it otherwise maps to.
+
+**Re-run the sweep once when a disposition edited files.** Those edits joined the same delta, so run the same command again to confirm they introduced no fresh survivors, and append a second `- Sweep:` block for the re-run. A hit already dispositioned `JUSTIFIED` or `FALSE-POSITIVE` — same file, same matched text — legitimately re-appears and needs no second disposition. A re-appearing hit that was dispositioned `FIXED` means the fix did not remove every occurrence: re-disposition it — correct it now, or close with `failed` — never leave it recorded as `FIXED`. One re-run is enough: do not loop. Exit 1 with no JSON payload on stdout is a crash, not survivors — surface the stderr traceback and close with `failed`.
+
+**The sweep is never silent.** When the payload reports `"skipped": true` (exit 0 — no delta was available), append the visible notice `- Sweep: NOT RUN — no git delta ({reason})` under `## Fix Progress`, using the payload's `reason` verbatim, and continue on this pass's normal outcome. A skip is not a failure; exit 2 is — surface its `Error:` line verbatim and close with `failed`.
+
+## Step 5: Record the Fixes Through `state-verify` and Commit
+
+Never hand-author a verify entry, and never write a `verifiedStageVersion` value by hand. Record the fix pass with the `state-verify` verb described in the **Pipeline State Protocol** in `references/shared-conventions.md`, which owns its full flag surface, its status matrix, and the exit-2 failure protocol. `--stage` names the **served production stage** established in Step 1. `findings-applied` deliberately **clears** `verifiedStageVersion` and refuses `--verified-stage-version`: applying fixes is not verifying them, so the served stage's verification stays outstanding until a re-verify passes. Add `--epic "{epic}"` when the feature is an epic member — required, per the Pipeline State Protocol; omitting it for a member is an error and must never fall back to a same-named flat feature.
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" state-verify \
+  --feature "{feature}" --stage "{servedStage}" --status findings-applied \
+  --specs-dir "{specsDir}"
+```
 
-## Step 5: Update Pipeline State and Commit
+**Stage every disposition-edited path explicitly.** Commit 1's staging scope is the feature directory only, so a survivor you fixed outside it (Step 4's sweep) would otherwise be left uncommitted. Before committing, run one `git add <path>` per file recorded as `FIXED` in the sweep record — enumerated, one path at a time, never `git add -A` and never `git add .`. Those fixes then ride Commit 1 alongside the findings document that records them, and the tree is left clean for the re-verify and for the next stage's dirty-tree check.
 
-Follow the Git Commit Protocol in `references/shared-conventions.md`.
+Then follow the Git Commit Protocol in `references/shared-conventions.md`. If `gitCommitAfterStage` is true, stage files (`git add {resolvedFeatureDir}/` — or `{specsDir}/{epic}/` for an epic member so the member-state change commits atomically with the epic subtree) and commit with message `"{commitPrefix}({feature}): apply {mode} verification fixes"`. That is Commit 1, and the write above already recorded `commitHash: null` for it.
 
-1. Update `{resolvedFeatureDir}/.pipeline-state.json`:
-   - Set the relevant `forge-verify-*` entry status to `findings-applied`
-   - Record `fixedAt` timestamp
-   - Record `verifiedStageVersion` = the current `version` of the production stage entry
-     this verify covers (e.g. fixing `tech` findings → `stages["forge-2-tech"].version`).
-     This keeps the navigator's freshness ledger accurate after a fix, so the verified
-     stage reads as `fresh` and auto-verify does not needlessly re-fire on an unchanged
-     artifact. (If the fix itself bumped the production stage's `version`, use the new
-     value so the ledger reflects what was actually verified/fixed.)
-2. If `gitCommitAfterStage` is true, follow the Git Commit Protocol: stage files (`git add {resolvedFeatureDir}/` — or `{specsDir}/{epic}/` for an epic member so the member-state change commits atomically with the epic subtree), attempt commit with message `"{commitPrefix}({feature}): apply {mode} verification fixes"` (writing `commitHash: null` in that commit), then record the artifact-commit hash via the protocol's two-commit follow-up (never `--amend`) only on success.
+**Two-commit provenance — never `--amend`.** Record the provenance of Commit 1 in a second `state-verify` call, passing the **full 40-character** hash — an abbreviation is refused rather than expanded, and this call touches nothing but `commitHash`. Add `--epic "{epic}"` when the feature is an epic member — required, per the Pipeline State Protocol.
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" state-verify \
+  --feature "{feature}" --stage "{servedStage}" \
+  --commit-hash "$(git rev-parse HEAD)" --specs-dir "{specsDir}"
+```
+
+On exit 2 **nothing was recorded**: surface the `Error:` line verbatim together with the named feature (and epic), do not claim the fixes were persisted, and close with `failed` in Step 7 — the verify entry is unchanged, so no success block may be printed. A failed validation or a failed commit is `failed` for the same reason.
 
 ## Step 6: Re-verify Gate
 
-Fixes are applied and recorded (`findings-applied`), so the stage reads **fresh** in the navigator's ledger (Step 5 set `verifiedStageVersion` to the current version). A re-verify is nonetheless the only thing that *confirms* the fixes actually resolved the findings, so on a **direct/manual** `forge-fix` invocation, **prompt** it rather than leaving it as a passive suggestion — this is the same **Standard Verify Gate** the stage skills stamp (`references/stage-exit-protocol.md`).
+Fixes are applied and recorded as `findings-applied`. That status makes **no** claim of freshness: the writer clears `verifiedStageVersion`, so the served stage's verification stays **outstanding** in the navigator's ledger, and only a re-verify that passes resolves it. Because a re-verify is the one thing that confirms the fixes actually resolved the findings, on a **direct** invocation **prompt** for it rather than leaving it as a passive suggestion — this is the same **Standard Verify Gate** the stage skills stamp (`references/stage-exit-protocol.md`).
+
+**A nested owner presents no gate.** Return your structured result (served stage, outcome `applied`, findings file, steps applied) to the outer caller — it performs the mandatory re-verify itself — and print no terminal block of your own. This follows from the `owner:` token read at entry; it is never decided by how the invocation was phrased.
+
+On a **direct** invocation, present the gate with `AskUserQuestion` using these three options — but only when your verify capability is `interactive` (Step 7):
+- **Re-verify {feature} now** *(recommended)* — dispatch the clean-room `forge-verifier` subagent from this session in require-clean mode to confirm every finding is resolved. The dispatch is **scoped** per "Re-verify scope and convergence" in `references/stage-exit-protocol.md`: it confirms the prior report's findings against their acceptance evidence and examines this fix's delta — never a fresh full-checklist sweep — a finding with a recorded decision is never re-filed, and only an unresolved prior finding or a new blocking defect the fix introduced may block. The digest returns here so any remaining issue keeps its context. One-time — it does **not** change config. A clean-or-advisory-only result closes as `reverified`; unresolved prior findings or new blocking defects close as `reverify-findings` for the same served stage. **Escalation:** if that would be the second consecutive `reverify-findings` for this served stage (count the round-discriminated reports in `.verification/`), follow "Escalation (the round ledger)" in `references/stage-exit-protocol.md` before closing — present the digest and offer explicit acceptance of the residual findings; do not recommend another fix pass.
+- **Re-verify now + enable auto-verify going forward** — re-verify now **and** patch `"autoVerify": true` into `forge.config.json` in place (preserve formatting and every other key) so future stages verify automatically, no prompt. This complements the `forge-init` opt-in. **Do not auto-commit this config change** — treat it like `notes`: a user-facing edit the user commits on their own cadence, never folded into a stage's artifact commit. Its outcome mapping is identical to the option above.
+- **Skip for now** — an explicit deferral of the re-verify. It closes as **`deferred`**, never `reverified`: the fixes are recorded but nothing has confirmed them, and the served stage's verification stays outstanding until a re-verify passes, so the pipeline does not advance on this pass. Run `/feature-forge:forge {feature}` when you want pipeline status.
+
+**Manual capability is not a skip, and not a deferral.** When your capability is `manual` (Step 7 — no question mechanism **and** no permitted dispatch), do not run clean-room and do not fabricate a choice nobody made: close with `applied`, and the script prints `/feature-forge:forge-verify {feature} --served-stage {servedStage}` as the primary action for the user to run. Offer the auto-verify enable as plain text only if a config write is possible.
+
+**A re-verify that cannot run is an operational failure.** If the user chose to re-verify and the dispatch is refused, returns the `CLEAN_ROOM_UNAVAILABLE` sentinel, or returns no answer, the fixes remain recorded but nothing was confirmed: close with `failed`. Never report `reverified` on an unrun verify, and never treat an unavailable tool as an explicit user skip.
+
+## Step 7: Close the Stage
+
+**Ownership.** Pass the `owner: nested` / `owner: direct` value read at entry (absent the token: `direct`) straight through as `--owner`. As a **direct** owner you print the script's NEXT-STEPS block verbatim as your absolute final output, with nothing after its sentinel line. As a **nested** owner the payload carries `terminalOwnedBy: "outer"` and `nextSteps: null`: return your structured result to the caller and print no terminal block at all.
+
+**Served stage.** Pass the stage established in Step 1 as `--served-stage`, so every branch command carries the diversion's thread forward. Never re-derive it here.
+
+**Capability.** Determine `--verify-capability` before running the exit (full rule: `references/stage-exit-protocol.md`; summary: **Verify Capability** in `references/shared-conventions.md`). Pass `interactive` only when a question mechanism equivalent to `AskUserQuestion` is available **and** a clean-room `forge-verifier` may actually be dispatched right now; otherwise pass `manual`. Dispatch capability means **permitted** dispatch, not a listed tool — the test is "may I dispatch `forge-verifier` right now", not "is a dispatch tool in my tool surface". A session that bars *unsolicited* dispatch while offering a question mechanism is therefore **`interactive`, not `manual`**: the gate's affirmative choice is the user request that authorizes the dispatch. An auto-verify or re-verify directive under a no-unsolicited-dispatch bar is presented through the Step 6 gate and dispatched on the affirmative choice — never skipped, and never resolved by closing with an outcome that advances the pipeline.
+
+**Outcome.** Invoke the exit **exactly once**, with the `--outcome` this run maps to. Every path lands on exactly one row; none may be left open:
+
+| This run's result | `--outcome` | Authoritative action |
+|---|---|---|
+| No applicable findings document or steps (Step 1.5) | `no-findings` | Re-verify while verification is still owed; otherwise the live production successor |
+| User decisions remain unresolved (Step 3) | `decisions` | Resume `forge-fix` naming the unresolved decisions; no advancement |
+| A fix step, a validation, a commit, or a state write failed (Steps 4–6) | `failed` | Fix/navigator recovery; no advancement |
+| Fixes persisted and re-verify has not been run (nested, or manual capability) | `applied` | Re-run `forge-verify` for the same served stage — re-verification is mandatory |
+| A mandatory re-verify passed | `reverified` | The live production successor |
+| A mandatory re-verify reported an unresolved prior finding or a new blocking defect (a clean-or-advisory-only result is `reverified`) | `reverify-findings` | `forge-fix` for the same served stage |
+| The user explicitly deferred the fix pass or the re-verify (Steps 3, 6) | `deferred` | Deterministic `forge-fix`/navigator resume stating the findings remain unresolved; no advancement |
+
+A cancellation, an unavailable tool, or a non-answer is `deferred` **only** when it was an explicit user choice and `failed` when it was an operational failure — an unavailable tool is never an explicit user skip, and neither ever becomes `reverified`. `applied` is not `reverified`: `findings-applied` cleared the freshness the writer deliberately dropped, so only `reverified` after a passing verify permits advancement.
+
+**Round-ledger escalation binds this row on every capability.** Before closing `reverify-findings` that is the SECOND consecutive for this served stage (count the round-discriminated reports in `.verification/`), present the escalation dispositions per "Escalation (the round ledger)" in `references/stage-exit-protocol.md` — through the question mechanism when `interactive`, or printed as text (digest + the three dispositions, "Accept the residual findings" first) BEFORE the terminal block when `manual`. Never recommend another fix pass at this point.
+
+Add `--epic "{epic}"` when the feature is an epic member. Pass no other flags.
 
-**Skip this gate when an `autoFix` caller invoked you as part of a chain** — the authoring stage's in-stage auto-verify (`references/stage-exit-protocol.md`, in-stage verify block) or the navigator's catch-up (`skills/forge/SKILL.md` §3b step 2b): there the caller owns the mandatory re-verify, so a second gate here would block the unattended flow or double the re-verify. Just return and let the caller proceed.
+**Close this stage with the Scripted Stage Exit** (contract: `references/stage-exit-protocol.md`; do not improvise a "Next steps" list). Run:
 
-On a direct invocation, present the gate using `AskUserQuestion` with these three options — but only when the host has a question mechanism **and** the clean-room path is available (the `Agent` tool plus a dispatchable `forge-verifier` subagent):
-- **Re-verify {feature} now** *(recommended)* — dispatch the clean-room `forge-verifier` subagent from this session in require-clean mode to confirm every finding is resolved; the digest returns here so any remaining issue keeps its context. One-time — it does **not** change config.
-- **Re-verify now + enable auto-verify going forward** — re-verify now **and** patch `"autoVerify": true` into `forge.config.json` in place (preserve formatting and every other key) so future stages verify automatically, no prompt. This complements the `forge-init` opt-in. **Do not auto-commit this config change** — treat it like `notes`: a user-facing edit the user commits on their own cadence, never folded into a stage's artifact commit.
-- **Skip for now** — proceed without re-verifying; the fixes are already recorded, so the stage stays `findings-applied` (fresh in the ledger). Run `/feature-forge:forge {feature}` when you want pipeline status.
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" stage-exit --feature "{feature}" --stage forge-fix --owner "{owner}" --outcome "{FixOutcome}" --served-stage "{servedStage}" --specs-dir "{specsDir}" --host claude --verify-capability "{verify-capability}"
+```
 
-**Host / clean-room fallback (not a user-selectable option):** if the question mechanism, the `Agent` tool, or the `forge-verifier` subagent is unavailable, do **not** run clean-room — degrade to printing `/feature-forge:forge-verify {feature}` for the user to run inline/manually (mirroring `autoInvokeNextStage`), and offer the auto-verify enable as plain text only if a config write is possible.
+Obey the DIRECTIVES it prints, in the consumption order this protocol fixes: surface `invalidAutoVerifyKeys` and every `warnings` entry first; `runInStageVerify: true` → run the in-stage clean-room verify chain now (honoring `autoFixEligible`, and asking through the Standard Verify Gate first when you may not dispatch unsolicited); `verifyGate: "standard"` → present the Standard Verify Gate; `verifyGate: "manual-print"` → print the `verifyCommand` for the user and do **not** dispatch inline. Then, and only when `terminalOwnedBy` is `"self"`, **print the NEXT-STEPS block verbatim as your absolute last output — nothing after its sentinel line.** A `terminalOwnedBy: "outer"` payload carries `nextSteps: null`: return your structured result to the caller and print no terminal block at all.

package/adapters/claude/skills/forge-fix/references/shared-conventions.md

@@ -36,7 +36,7 @@ I found that the codebase uses React and TanStack Router.
 
 ### Decision Support: Help the User Choose
 
-When an `AskUserQuestion` carries substantive options (a real choice — not a trivial yes/no confirmation), do not just list them. The interview stages have already done codebase research and integration analysis; surfacing that synthesis at the decision moment is the whole point. For every such question:
+When a question posed through `AskUserQuestion` carries substantive options (a real choice — not a trivial yes/no confirmation), do not just list them. The interview stages have already done codebase research and integration analysis; surfacing that synthesis at the decision moment is the whole point. For every such question:
 
 - **Lead with a recommended option.** Place it first and label it `(recommended)` (matching the `AskUserQuestion` "(Recommended)" convention).
 - **Put the trade-off in each option's `description`.** Say why you'd pick it and what you give up versus the alternatives — the cost, not just the benefit.
@@ -53,6 +53,17 @@ For genuinely comparable artifacts (competing module structures, two code snippe
 
 The **Branch Setup** block below is the reference pattern: a strong recommendation as the first option, rationale inline, the alternative still available, never a hard-stop.
 
+## Stage Review Gate
+
+Every authoring stage ends its "Review with User" step in exactly one of two shapes. Which shape a stage uses is declared **here, once** — each stage's review step points at this block by title, and the shape is never re-derived from the surrounding prose or inferred from how sibling stages behave (three stages block and one does not; majority-shape inference is precisely the failure this block exists to prevent):
+
+- **Blocking review (gate).** The stage presents the artifact and collects feedback through `AskUserQuestion`; it does **not** proceed until the user answers, iterating until they confirm. Stages: **forge-1-prd** (Step 5), **forge-2-tech** (Step 6), **forge-3-specs** (Step 6).
+- **Non-blocking review (invitation).** The stage states the artifact is ready and invites adjustments **as a statement, not a question** — and then **proceeds to the next step in the same turn unless the user asks for changes**. The invitation obliges the agent to *continue*: emitting the invitation sentence and stopping treats the non-gate as a gate and strands the stage `in-progress` with its completion step unrun — a defect, not caution. Stage: **forge-4-backlog** (Step 6).
+
+**Why the shapes differ.** A blocking review guards an artifact whose content was just authored from open-ended interview or synthesis — the user is the only authority on "complete", so the stage must wait. forge-4's backlog is *derived* from specs the user already approved, was planned interactively in its Step 3, and is machine-validated in its Step 5; a second hard gate would re-ask a settled question, and the loop never launches without forge-5-loop's own Step 2d confirmation anyway. The invitation is a courtesy checkpoint, not an approval gate (removed deliberately in #78's consistency sweep).
+
+A stage that changes shape changes it **in this block first**; the per-stage pointer stays a pointer.
+
 ## Configuration Reading
 
 Read `forge.config.json` from the project root. If it doesn't exist, use defaults.
@@ -130,7 +141,7 @@ mkdir -p "<specsDir>"
 [ -f "<specsDir>/AGENTS.md" ] || cp "$R/references/templates/specs-hygiene/AGENTS.md" "<specsDir>/AGENTS.md"
 ```
 
-If the host is Claude (the `AskUserQuestion` tool is available), also ensure the Claude-framed variant:
+If the host is Claude (the Claude-native question tool is available), also ensure the Claude-framed variant:
 
 ```bash
 R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
@@ -191,6 +202,44 @@ Pipeline state is written by the `state-*` verbs of `scripts/forge-session.py`
 
 If a `state-*` verb exits 2, surface the plain `Error:` line from stderr verbatim, do **not** proceed to the next step of the surrounding protocol, and do **not** hand-author the JSON as a workaround. The stage remains resumable because the entry stamp is already on disk — re-run the verb once the cause is fixed.
 
+**The nine `state-*` verbs.** `state-enter` (Stage-Entry Guard), `state-artifact` (incremental artifact tracking), `state-complete` (Git Commit Protocol), `state-skip` (the deliberate forge-6-docs documentation skip — scoped to that one stage; writes `status: "skipped"` + `skippedAt`, refuses to erase a record of docs that exist, and is the only sanctioned writer of a skipped docs stage), `state-branch` (Branch Setup and Branch Reconciliation), `state-note` (the Immediate Downstream Note below, and the optional completion note at stage closure), `state-decision` (deferred decisions), `state-ecr` (epic change requests), and `state-verify` (one `forge-verify-*` verification transition — below). The `--epic` member requirement and the exit-2 failure protocol above apply to **every** one of them, `state-verify` included; no verify entry is ever hand-authored.
+
+### `state-verify` — verification results and provenance
+
+`state-verify` writes exactly one `stages.forge-verify-{token}` entry — the verification result for the production stage named by `--stage` — plus the top-level `updatedAt`, and nothing else. `--stage` takes the **served production stage** (`forge-0-epic` through `forge-5-loop`; `forge-6-docs` has no verification token and is rejected). Add `--epic "{epic}"` when the feature is an epic member — required, per the member rule above. Result mode passes `--status` (`auto-verify-pending`, `passed`, `findings-reported`, `findings-applied`, or `skipped`) with whatever `--findings-file`, `--findings-count`, and `--verified-stage-version` that status requires; contradictory metadata is refused before any write. `passed` may additionally carry `--findings-file` + `--findings-count` together for an **advisory-only** report (`inconsistency`/`improvement` findings only, per forge-verify's severity floor) — the stage resolves without a fix round and the report stays attached:
+
+**`auto-verify-pending` is not a skill-facing status.** It is written by `stage-exit`'s scheduling boundary, which records the debt automatically when auto-verify is effective for a stage. The value is accepted on this CLI so the entry stays inspectable and repairable, not so a skill can hand-schedule verification: no skill body and no reference passes it, and none should. Every other status in the list is the recorded *result* of a verification that ran (or was explicitly skipped); this one records that one was *owed*.
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" state-verify \
+  --feature "{feature}" --stage "{served-production-stage}" --status "<status>" \
+  --specs-dir "{specsDir}"
+```
+
+Provenance follows the same two-commit sequence as `state-complete`: the result transition above writes `commitHash: null`, Commit 1 records the findings document and the state, and a second `state-verify` call records the full 40-hex hash of Commit 1 and touches nothing else (never `--amend`; an abbreviated hash is refused rather than expanded). Add `--epic "{epic}"` for an epic member — required, per the member rule above:
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" state-verify \
+  --feature "{feature}" --stage "{served-production-stage}" \
+  --commit-hash "$(git rev-parse HEAD)" --specs-dir "{specsDir}"
+```
+
+Epic-scoped verification is the single exception to the member rule: with `--stage forge-0-epic`, `--feature` names the **epic** and `--epic` must be absent or exactly equal to it. That call writes `{specsDir}/{epic}/.epic-state.json` and never a member's `.pipeline-state.json`, and its freshness version is the epic manifest's `revision`, never a member's stage version:
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" state-verify \
+  --feature "{epic}" --stage forge-0-epic --status "<status>" \
+  --specs-dir "{specsDir}"
+```
+
+On exit 2 the verification result is **not** recorded: surface the `Error:` line verbatim, name the feature (and epic), and do not claim the verification was persisted or advance past it.
+
 ### Staleness Detection (Read-Time)
 
 When loading upstream artifacts as prerequisites, check `basedOnVersions` in the pipeline state for this stage. If any upstream stage's current version is newer than the version recorded in `basedOnVersions`, warn the user before proceeding:
@@ -199,6 +248,31 @@ When loading upstream artifacts as prerequisites, check `basedOnVersions` in the
 
 Frame the choice with its cost: re-running re-derives this stage from the current upstream (safest, but discards any hand-edits to this stage's artifacts); proceeding stale is faster but risks baking outdated assumptions into everything downstream. Recommend re-running unless the user knows the upstream change doesn't affect this stage.
 
+## Immediate Downstream Note (Parking Lot)
+
+When an interview raises a concern that belongs to a *later stage of this same feature*, acknowledge it and persist it **immediately, at the moment it is raised** — not at stage closure — by running `state-note` with a concise one-line statement of the concern. Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol above; omitting it for a member is an error and must never be allowed to fall back to a same-named flat feature.
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" state-note \
+  --feature "{feature}" --note "<concise downstream concern>" \
+  --specs-dir "{specsDir}"
+```
+
+`state-note` **overwrites** the single top-level `notes` string — it does not append. To preserve an earlier note, read the current `notes` value out of the feature's `.pipeline-state.json` first and pass one combined concise string in a single `--note`; never edit or round-trip the JSON by hand. This interview-time call is separate from the optional completion note offered at stage closure and must not be deferred until then — a session that ends before closure would otherwise lose the concern entirely.
+
+On `UsageError`/exit 2, surface the `Error:` line verbatim together with the named feature (and epic) and the recovery instruction, and **stop claiming the concern was recorded** — it was not. Epic *decomposition* changes are not notes: they go through `state-ecr` into `epicChangeRequests`, never into `notes`.
+
+## Verify Capability
+
+Skills that close a stage pass `--verify-capability interactive|manual` to `stage-exit`. The full determination rule, the Standard Verify Gate, and the recovery path live in `references/stage-exit-protocol.md`; the two facts that are most often gotten wrong:
+
+- **Dispatch capability is *permitted* dispatch, not a listed tool.** The question is "**may I dispatch `forge-verifier` right now**", not "is a subagent-dispatch tool in my tool surface". A session can carry a standing host instruction against dispatching subagents unless the user asked; such instructions are injected by the harness, sit outside this project's control, and outrank skill prose. Classify on permission, up front.
+- **A consent requirement is `interactive`, not `manual`.** When dispatch is barred only *unless the user asked* and a question mechanism is available, pass `interactive`: the gate's own affirmative choice supplies the missing user request. Pass `manual` only when there is **no** question mechanism **and** **no** permitted dispatch.
+
+A bar on unsolicited dispatch is never grounds to skip verification, and never grounds to fence the production successor while verification is unresolved. On the `runInStageVerify: true` path the emitted `verifyGate` stays `none`: reuse the Standard Verify Gate block for consent with **choice 2 omitted** (auto-verify is already effective, so "enable auto-verify going forward" is a no-op), leaving exactly two choices: *Verify now* (recommended) and *Skip for now*. The clean-room `forge-verifier` is **dispatched on the affirmative choice**, never merely printed for the user to run later; *Skip for now* is persisted as an explicit `skipped` before any advancing block.
+
 ## Branch Setup
 
 Invoke this block at the **very start** of a pipeline entry point — `forge-1-prd` (standalone feature) and `forge-0-epic` (epic) — **before** any directory resolution or interview, so the rest of the run lands on the intended branch. `{label}` is the feature name (forge-1-prd) or epic name (forge-0-epic); `{scope}` is `feature` or `epic` correspondingly.
@@ -332,7 +406,7 @@ Invoke this block **at the head of any post-entry step that writes a stage artif
 
 1. **Proceed** when `stages.{stage}.status` is `"in-progress"` (this session's Entry Stamp — you are finishing the run you started) or absent/`pending`. Run the write / exit normally.
 
-2. **Detect-and-refuse** when ALL of these hold: `stages.{stage}.status ∈ {"complete", "stale"}` **AND** the stage's artifacts (incl. `TRACEABILITY.md` for forge-3-specs) exist on disk **AND** a `commitHash` is recorded for the stage **AND** you did **not** author this stage earlier in the current session. This is a stale/replayed continuation of an already-finished, committed stage. Do **not** overwrite the artifact or re-run the exit. Route instead to the **Stage-Entry Guard**'s *Re-authoring* path: surface the same `AskUserQuestion` warning ("A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?"). Only on explicit confirmation re-enter from the Entry Stamp (the version bumps at exit); otherwise **stop** and report that the stage is already complete — cite the recorded `commitHash` and offer `/feature-forge:forge {feature}` to see true state.
+2. **Detect-and-refuse** when ALL of these hold: `stages.{stage}.status ∈ {"complete", "stale"}` **AND** the stage's artifacts (incl. `TRACEABILITY.md` for forge-3-specs) exist on disk **AND** a `commitHash` is recorded for the stage **AND** you did **not** author this stage earlier in the current session. This is a stale/replayed continuation of an already-finished, committed stage. Do **not** overwrite the artifact or re-run the exit. Route instead to the **Stage-Entry Guard**'s *Re-authoring* path: surface the same warning via `AskUserQuestion` ("A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?"). Only on explicit confirmation re-enter from the Entry Stamp (the version bumps at exit); otherwise **stop** and report that the stage is already complete — cite the recorded `commitHash` and offer `/feature-forge:forge {feature}` to see true state.
 
 When you cannot confirm you authored the current run, treat it as a replay and refuse: a false refuse costs one confirmation click; a false proceed overwrites a committed artifact and re-churns a stage version. `--force` follows Force Mode (skip the gate, treat as a deliberate re-author).