@garygentry/feature-forge 0.3.1 → 0.3.4

package/adapters/claude/skills/forge-6-docs/SKILL.md

@@ -21,6 +21,28 @@ Resolve the feature directory via the **Feature Directory Resolution** block in
 
 Read `{resolvedFeatureDir}/.pipeline-state.json` to understand what exists.
 
+### Documentation Decision Gate
+
+Documentation is valuable but not mandatory: a feature may close with docs deliberately skipped, recorded honestly as `skipped` (never as a false `complete`). This gate is configured by `docsStage` in `forge.config.json` (`"prompt"` | `"skip"`, default `"prompt"`; an unrecognized or absent value behaves as `"prompt"`):
+
+- **`"prompt"`** — before gathering sources, use `AskUserQuestion` to ask: **Generate docs (recommended)** — proceed with this skill as written · **Skip documentation for this feature** — close the stage with no docs, recorded as `skipped`; docs can still be generated later by re-running this stage.
+- **`"skip"`** — take the skip path below directly, with no question: say one line — "docsStage is configured to skip: recording forge-6-docs as deliberately skipped for {feature}." — and proceed to the `state-skip` write. The user opted out of the per-run prompt by setting the config; re-asking would defeat it.
+
+On **Skip documentation**, persist the skip through the `state-skip` verb — never by hand, and never via `state-complete` (which would claim a completion that did not happen). Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol in `references/shared-conventions.md`:
+
+```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-skip \
+  --feature "{feature}" --stage forge-6-docs --specs-dir "{specsDir}"
+```
+
+If the verb exits 2, surface its plain `Error:` line verbatim — a refusal means the skip would erase a record of docs that already exist; do not force it. Ask the user how to proceed (typically: generate/refresh the docs normally).
+
+After a successful skip write: if `gitCommitAfterStage` is true, commit the state change (`git add {resolvedFeatureDir}/`, message `"{commitPrefix}({feature}): skip architecture docs"`) — a plain single commit; there is no artifact commit, so the two-commit hash follow-up does not apply. Then go **directly to Step 6** with `{DocsOutcome}` = `skipped`. Steps 1 (rest), 2, 3, 4, and 5 are all skipped — including the Impl-Verify Backstop: skipping docs generates nothing over unverified code, and any outstanding verification stays visible in state and keeps being surfaced by the navigator.
+
+On **Generate docs**, continue below.
+
 ### Gather Sources
 
 Load into context:
@@ -37,7 +59,28 @@ Also check `.pipeline-state.json` for `stages.forge-5-loop`. If it exists and ha
 
 ### Impl-Verify Backstop
 
-Check `.pipeline-state.json` for `stages.forge-verify-impl`. If it is **absent** or has status `"skipped"`, use `AskUserQuestion` to warn with the cost of skipping: "Implementation hasn't been verified yet. Recommended: run `/feature-forge:forge-verify {feature} impl` first to audit the loop's output — docs generated over unverified code can document bugs or gaps as if they were intended behavior, and readers will trust them. Generate docs anyway?" Offer **Verify first (recommended)** · **Generate docs anyway**. This mirrors `forge-4-backlog`'s pre-stage verification check and backstops a skipped impl-verify regardless of how the loop ended. If `stages.forge-verify-impl` shows it already ran (`findings-applied`, `findings-reported`, or `passed`), proceed with no warning.
+Read `stages.forge-verify-impl` from `.pipeline-state.json` and branch on its status — **five** cases, in this order (the pending case must be tested *before* the absent/`skipped` one, or owed-and-dropped debt gets reported as never-scheduled):
+
+1. **`passed`** — verification ran and resolved clean (or advisory-only, report attached); proceed with no warning.
+2. **`findings-reported`** — blocking findings are live and **unresolved**: docs generated over them can document known defects as intended behavior. Use `AskUserQuestion` to offer: **Apply the findings first (recommended)** (`/feature-forge:forge-fix {feature} --served-stage forge-5-loop`) · **Generate docs anyway**. Proceeding is an explicit deferral, persisted per the skip rule below — the findings documents stay on disk and the deferral is a recorded decision.
+3. **`findings-applied`** — fixes landed but nothing re-verified them: this status deliberately clears freshness, so the implementation's verification is still outstanding, not silently satisfied. Use `AskUserQuestion` to offer: **Re-verify first (recommended)** (`/feature-forge:forge-verify {feature} impl`) · **Generate docs anyway**. On proceed, **write nothing to the verify entry** — the skip rule below does NOT apply to this case. `findings-applied` counts as complete-for-orchestration, so replacing it with `skipped` would demote the member out of its epic rollup and re-block dependents (`state-verify` refuses exactly that write — issue #203's 5/6 → 1/6 collapse). The recorded status already says re-verification is outstanding; proceeding is the deferral, and later gates keep surfacing it.
+4. **`auto-verify-pending`** — automatic verification *was* scheduled for the implementation stage and the debt *was* durably recorded; it simply has not run. Say exactly that, naming the served stage and the retry command: *"{feature}: automatic verification is still pending for forge-5-loop; run `/feature-forge:forge-verify {feature} impl` to resolve it."* Then use `AskUserQuestion` to offer the same two choices as case 5. Never report this as "hasn't been verified yet" — an **absent** entry means verification was never scheduled, `auto-verify-pending` means it was scheduled and never ran, and the operator acts on those two facts differently.
+5. **Absent, or `skipped`** — use `AskUserQuestion` to warn with the cost of skipping: "Implementation hasn't been verified yet. Recommended: run `/feature-forge:forge-verify {feature} impl` first to audit the loop's output — docs generated over unverified code can document bugs or gaps as if they were intended behavior, and readers will trust them. Generate docs anyway?"
+
+Cases 2–5 all pair a recommended first action with **Generate docs anyway**. On **Verify first** / **Re-verify first**, invoke `feature-forge:forge-verify {feature} impl` with the literal `owner: nested` token in the dispatching prompt — this dispatch happens inside the docs stage, so **you** remain the sole terminal owner and the branch skill returns its structured result and prints no terminal block of its own (see "Branch ownership: the `owner:` token" in `references/stage-exit-protocol.md`); on **Apply the findings first**, dispatch `feature-forge:forge-fix` the same way (same token, same ownership). This mirrors `forge-4-backlog`'s pre-stage verification check and backstops a skipped or unresolved impl-verify regardless of how the loop ended.
+
+**"Generate docs anyway" persists the skip before docs can complete — in cases 2, 4, and 5 only.** An explicit choice to proceed without verification is recorded as `skipped` through `state-verify` — never by hand — **before** Step 2, so an unresolved result cannot be bypassed by this stage's terminal wording. Case 3 (`findings-applied`) is the exception spelled out above: its deferral writes nothing, because the verb refuses to demote a complete-for-orchestration status (#203). Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol in `references/shared-conventions.md`:
+
+```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 forge-5-loop --status skipped --specs-dir "{specsDir}"
+```
+
+If that verb exits 2, surface its plain `Error:` line verbatim and stop — the skip is not persisted, so docs may not complete.
+
+**Verification that is operationally unavailable is not an implicit skip.** If the user chose **Verify first** and the clean-room verifier could not be dispatched, returned `CLEAN_ROOM_UNAVAILABLE`, or returned a non-answer, then verification did **not** run: write nothing, follow the *Clean-room unavailable, or a non-answer* path in `references/stage-exit-protocol.md` (leave the debt unresolved and print the verify command for the user to run), and never read the failed attempt as consent to proceed. Docs may complete only after verification passes or after the user makes the explicit "Generate docs anyway" choice above, which persists `skipped` — an unavailable tool is neither.
 
 ### Epic-Level Documentation (epic members only)
 
@@ -51,13 +94,13 @@ python3 "$R/scripts/epic-manifest.py" render-status "{epic}" --specs-dir "{specs
 
 If `render-status` fails, skip the epic-level offer and proceed with the per-feature docs only; surface the error per the exit-1/exit-2 split in the **Feature Directory Resolution** block of `references/shared-conventions.md` (exit 1 → parse `{findings[]}` from stdout; exit 2 → surface the plain `Error:` stderr line verbatim).
 
-**Only if `rollup.total > 0 AND rollup.complete == rollup.total`** (every member is complete-for-orchestration; the `total > 0` guard excludes an empty epic), offer the extra doc as a statement the user can take or leave — not a forced question:
+**Gate the offer on per-member DOCS state, not the orchestration rollup (#173).** `rollup.complete` counts loop-completeness, so in an epic implemented before any docs were written it reads full on the *first* member's docs run — offering an epic doc that would be sourced from a fraction of its inputs. Instead, read each member row's `docsStatus` from the same `render-status` payload and offer **only if**: `rollup.total > 0`, AND every member **other than {feature}** has `docsStatus` of `complete` or `skipped` (#197's deliberate skip satisfies — those members will contribute no per-feature docs by decision, not by omission). The current member counts as satisfied by this in-flight run. This fires exactly once per epic, on its final docs run:
 
-"All {total} features in the '{epic}' epic are complete. I can also generate an **epic-level architecture document** spanning the features, alongside {feature}'s per-feature docs — say the word and I'll add it."
+"All {total} features in the '{epic}' epic now have their documentation settled. I can also generate an **epic-level architecture document** spanning the features, alongside {feature}'s per-feature docs — say the word and I'll add it."
 
-If the user asks for it, synthesize a doc at **`{docsDir}/{epic}/`** sourced from: the `EPIC.md` narrative, each member's per-feature docs, and the manifest contracts (each feature's `exposes`/`consumes`). When the epic-level doc is written, the Step 5 commit also stages `{docsDir}/{epic}/`.
+If the user asks for it, synthesize a doc at **`{docsDir}/{epic}/`** sourced from: the `EPIC.md` narrative, each member's per-feature docs (members whose docs were deliberately skipped contribute their manifest charter/contracts only), and the manifest contracts (each feature's `exposes`/`consumes`). When the epic-level doc is written, the Step 5 commit also stages `{docsDir}/{epic}/`.
 
-If not all members are complete (or the feature has no `epic` back-pointer), **do not offer** — the per-feature doc flow proceeds unchanged.
+If any other member's `docsStatus` is neither `complete` nor `skipped` (or the feature has no `epic` back-pointer), **do not offer** — the per-feature doc flow proceeds unchanged.
 
 Read `references/doc-conventions.md` for documentation standards.
 
@@ -183,10 +226,34 @@ python3 "$R/scripts/forge-session.py" state-complete \
 
 1. Record completion by running the `state-complete` call above with `--version`, one `--artifact` per doc file this stage produced, and one `--based-on STAGE=<version>` per completed upstream stage. Always include forge-1-prd, forge-2-tech, forge-3-specs. Include forge-4-backlog and forge-5-loop ONLY if they have status `complete`. The verb sets `status: "complete"`, `completedAt`, the version, `basedOnVersions` and `artifacts`, and refreshes `updatedAt`.
 2. If `gitCommitAfterStage` is true, follow the Git Commit Protocol in `references/shared-conventions.md`: stage files (`git add {docsDir}/{feature}/ {resolvedFeatureDir}/` — and **also** `{docsDir}/{epic}/` when an epic-level doc was written in Step 1), attempt commit with message `"{commitPrefix}({feature}): complete architecture docs"` (marking `stages.forge-6-docs.status` `complete` with `commitHash: null` in that commit), then record the artifact-commit hash via the protocol's two-commit follow-up (never `--amend`) only on success. If commit fails, leave status as `in-progress`.
-4. Tell user: "Documentation complete. Feature pipeline for '{feature}' is finished!\n  `/feature-forge:forge {feature}` to see the final pipeline status." Then **hand off to the next unit of work** — do not dead-end here (Issue #124):
+3. Say that the docs are written — "Documentation complete for '{feature}'." — and stop there. The hand-off is Step 6's, and it is the script's to decide.
+
+## Step 6: Close the Stage
+
+Every docs run ends here, and ends here **exactly once** — standalone or epic member, complete or not.
+
+Select `{DocsOutcome}` first, from what actually landed:
+
+- **`complete`** — the docs were written and Step 5's state (and commit, when `gitCommitAfterStage` is true) succeeded.
+- **`skipped`** — the user chose **Skip documentation** at the Documentation Decision Gate and the `state-skip` write succeeded. Routes exactly like `complete` (the pipeline still ends here), but the wording says the docs were deliberately skipped — never that they exist.
+- **`blocked`** — docs work could not complete. Persist only valid partial state, then run the same call with `blocked`; it routes to navigator/recovery and never claims the pipeline is finished. If the failure happened **before** a safe state write, report the failure and its recovery and run **no** exit at all — there is nothing durable for an exit to close over.
+
+**Close this stage with the Scripted Stage Exit** (contract: `references/stage-exit-protocol.md`; do not improvise a "Next steps" list). 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/forge-session.py" stage-exit --feature "{feature}" --stage forge-6-docs --outcome "{DocsOutcome}" --specs-dir "{specsDir}" --host claude --verify-capability "{verify-capability}"
+```
+
+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.
+
+Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol in `references/shared-conventions.md`. Determine `{verify-capability}` per the **Host and capability determination** section of `references/stage-exit-protocol.md`: `interactive` needs both a question mechanism and *permission* to dispatch the clean-room `forge-verifier`, and a session that merely needs consent first is still `interactive`.
+
+The script owns the routing for both outcomes, so append nothing to its block — no hand-off paragraph, no "start a new feature" list, no second command:
 
-   - **Epic member** (the resolved feature has an `epic` back-pointer in its `.pipeline-state.json`): reuse the `render-status "{epic}" --specs-dir "{specsDir}" --json` output from Step 1's Epic-Level Documentation block (re-run it if you skipped that block). If `actionable` is non-empty, point at the next member: "Epic '{epic}' has {total−complete} feature(s) left — next up: **{actionable[0].name}**. Start it with `{actionable[0].nextCommand}`." (Offer to start it now if the host can invoke it — honor `autoInvokeNextStage` + `Skill`-tool availability; else just print the command.) If `actionable` is empty but the epic is not fully complete, note the remaining members are blocked on dependencies. If the epic is fully complete (`rollup.complete == rollup.total`, `total > 0`), congratulate on the whole epic — the epic-level architecture doc was already offered in Step 1 — and point at `/feature-forge:forge {epic}` for the finished dashboard.
-   - **Standalone** (no `epic` back-pointer): offer the next feature — "Start a new feature: `/feature-forge:forge-1-prd <feature-name>` (or group several with `/feature-forge:forge-0-epic <epic-name>`). Run `/feature-forge:forge` to see any other active pipelines." Defer the full recency-ranked list of other pipelines to the navigator (`/feature-forge:forge`) rather than duplicating it here.
+- **Epic member** — the script reads live epic status **at exit time**, after this stage's own state write and commit. Do **not** reuse Step 1's `render-status` snapshot and do **not** pass a member you picked yourself: that snapshot predates the docs state it would be routing from. An actionable member gets its own live command fenced; nothing actionable routes to the epic dashboard; every member complete routes to the dashboard completion view.
+- **Standalone** — `complete` fences `/feature-forge:forge {feature}` as the authoritative completion action, and leaves starting a new feature (or grouping several with `/feature-forge:forge-0-epic`) as secondary unfenced text.
 
 ## Gotchas
 

package/adapters/claude/skills/forge-6-docs/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).