@garygentry/feature-forge 0.3.6 → 0.3.8

package/adapters/codex/skills/forge-verify/SKILL.md

@@ -1,7 +1,7 @@
 ---
 # GENERATED — DO NOT EDIT. Source: skills/forge-verify/SKILL.md. Regenerate: python3 scripts/build-adapters.py
 name: forge-verify
-description: Verify forge pipeline artifacts for completeness, consistency, and quality. Use when user runs /feature-forge:forge-verify or asks to check forge specs, backlog, or implementation for gaps. Do NOT trigger for general code review, quality checks, or verification tasks outside the forge pipeline.
+description: Verify forge pipeline artifacts for completeness, consistency, and quality. Use when user runs forge-verify or asks to check forge specs, backlog, or implementation for gaps. Do NOT trigger for general code review, quality checks, or verification tasks outside the forge pipeline.
 ---
 
 # forge-verify — Verification Gate
@@ -13,13 +13,13 @@ Analyze feature artifacts for completeness, consistency, and quality. Produce st
 This skill is loaded in two different roles. Determine yours before proceeding:
 
 - **You ARE the `forge-verifier` subagent** — you were dispatched via the host's subagent mechanism, you have read-only tools (Read, Glob, Grep, Bash) and **no** Agent/host's subagent mechanism, and this skill is pre-loaded in your context. **SKIP "Subagent Delegation (parent orchestrator only)" and "Synthesize" below — those describe how a *parent* dispatches *you*, not work for you to do.** Do **not** dispatch anything, do **not** try to spawn a verifier. Go straight to **Prerequisites → Steps 1–6**, execute the checks yourself, and **return your findings as your response** (the parent writes the document to disk). Dispatching a subagent from here is the classic self-referential loop — never do it.
-- **You are the parent orchestrator** — a navigator (`/feature-forge:forge`), a stage skill's in-stage auto-verify, or a direct `/feature-forge:forge-verify` invocation, and you have the host's subagent mechanism. Use "Subagent Delegation" to dispatch the `forge-verifier` subagent, then "Synthesize" to assemble and write the document.
+- **You are the parent orchestrator** — a navigator (`forge`), a stage skill's in-stage auto-verify, or a direct `forge-verify` invocation, and you have the host's subagent mechanism. Use "Subagent Delegation" to dispatch the `forge-verifier` subagent, then "Synthesize" to assemble and write the document.
 
 ## Subagent Delegation (parent orchestrator only)
 
 This skill is delegated to the `forge-verifier` subagent via the host's subagent mechanism. The verifier subagent has:
 - **Read-only tools** (Read, Glob, Grep, Bash) — it cannot accidentally modify specs
-- **Persistent memory** — it accumulates knowledge about this project's recurring issues and patterns across sessions
+- **Persistent memory + shipped patterns** — it accumulates knowledge about this project's recurring issues across sessions, and on start reads the versioned, reviewed heuristics in `references/verifier-patterns/MEMORY.md` that ship with the pipeline (the two layers are distinct)
 - **The forge-verify skill pre-loaded** — so it has all verification checklists and guidance at startup
 
 ### Choose single vs. parallel dispatch
@@ -100,7 +100,7 @@ any work:
 Do not analyze artifacts, do not write a findings document, and do not touch pipeline
 state. This is an **operational failure, not a user skip** — close through Step 7 with `--outcome failed`; as a nested owner that call writes no state and prints no terminal block, so the sentinel is your structured result. The navigator detects this sentinel and degrades to its manual verify gate (Tier
 2/3), so verify state stays outstanding and the stage is never marked verified on false
-assurance. **Manual / interactive invocation** (the normal `/feature-forge:forge-verify`
+assurance. **Manual / interactive invocation** (the normal `forge-verify`
 path, no require-clean signal) keeps the inline fallback above unchanged.
 
 ## Prerequisites
@@ -111,7 +111,7 @@ Resolve the feature directory via the **Feature Directory Resolution** block in
 
 Determine branch ownership **at entry**, from the literal `owner: nested` / `owner: direct` token in the dispatching prompt (absent the token you are `direct`), and preserve that value unchanged through any re-verify — see Step 7, which passes it through as `--owner`.
 
-**Turn structure reminder:** Output analysis/context as text, then route ALL questions through the host's question mechanism. Never embed questions in text output — the user will not be prompted and the session will stall.
+**Turn structure reminder:** Text first, then host's question mechanism for all questions — never embed one in your text (it stalls). At rung 2/3, see the Interaction Capability Ladder.
 
 ## Step 1: Read Configuration and Determine Mode
 
@@ -119,18 +119,18 @@ Read `{resolvedFeatureDir}/.pipeline-state.json` to understand current pipeline
 
 ### Mode Selection
 
-An explicit `--served-stage <production-stage>` argument on this invocation is authoritative — it is what the scripted exit and forge-fix pass when they route back here (the fix rejoin fences `/feature-forge:forge-verify {feature} --served-stage {stage}`). Map it to the mode directly (`forge-0-epic`→epic, `forge-1-prd`→prd, `forge-2-tech`→tech, `forge-3-specs`→specs, `forge-4-backlog`→backlog, `forge-5-loop`→impl) and skip auto-detection.
+An explicit `--served-stage <production-stage>` argument on this invocation is authoritative — it is what the scripted exit and forge-fix pass when they route back here (the fix rejoin fences `forge-verify {feature} --served-stage {stage}`). Map it to the mode directly (`forge-0-epic`→epic, `forge-1-prd`→prd, `forge-2-tech`→tech, `forge-3-specs`→specs, `forge-4-backlog`→backlog, `forge-5-loop`→impl) and skip auto-detection.
 
-Otherwise, if a stage is specified as a second argument (e.g., `/feature-forge:forge-verify auth specs`), use that mode. Otherwise, auto-detect based on pipeline state:
+Otherwise, if a stage is specified as a second argument (e.g., `forge-verify auth specs`), use that mode. Otherwise, auto-detect based on pipeline state:
 
-- **epic mode**: Explicit via `/feature-forge:forge-verify {epic} epic`, or auto-detected when the named argument resolves to an **epic directory** — i.e. `{specsDir}/{name}/epic-manifest.json` exists (an epic root holds `epic-manifest.json` but no `.pipeline-state.json` of its own). When the argument is an epic, prefer epic mode over feature-mode resolution.
+- **epic mode**: Explicit via `forge-verify {epic} epic`, or auto-detected when the named argument resolves to an **epic directory** — i.e. `{specsDir}/{name}/epic-manifest.json` exists (an epic root holds `epic-manifest.json` but no `.pipeline-state.json` of its own). When the argument is an epic, prefer epic mode over feature-mode resolution.
 - **prd mode**: If `forge-1-prd` is complete but `forge-verify-prd` is not `passed` or `findings-applied`
 - **tech mode**: If `forge-2-tech` is complete but `forge-verify-tech` is not `passed` or `findings-applied`
 - **specs mode**: If `forge-3-specs` is complete but `forge-verify-specs` is not `passed` or `findings-applied`
 - **backlog mode**: If `forge-4-backlog` is complete but `forge-verify-backlog` is not `passed` or `findings-applied`
 - **impl mode**: If user explicitly requests or if implementation code exists for this feature
 
-If ambiguous, use the host's question mechanism to ask which stage to verify — **before any write**. Serialize the resolved mode as `--verify-mode` at Step 7: that mode, never conversational context and never `currentStage`, determines the served production stage.
+If ambiguous, use host's question mechanism to ask which stage to verify — **before any write**. Serialize the resolved mode as `--verify-mode` at Step 7: that mode, never conversational context and never `currentStage`, determines the served production stage.
 
 ## Step 2: Load All Relevant Artifacts
 
@@ -218,10 +218,10 @@ When building the Fix Execution Plan:
 **If not in plan mode:** Output the following as text:
 "Findings and fix plan written to `{findings-file}`."
 
-**Advisory-only reports skip the question.** When the report contains no blocking finding (`error`/`gap`), there is nothing to route to forge-fix: do not present the fix options below — state that the report is advisory-only, record `passed` with the report attached (Step 6), and continue; the advisories stay discoverable in the findings document for whoever next touches the artifact. Otherwise (at least one blocking finding), use the host's question mechanism to ask how to proceed — **unless this report closes the SECOND consecutive `reverify-findings` for this served stage** (count the round-discriminated reports in `.verification/`), in which case follow "Escalation (the round ledger)" in `references/stage-exit-protocol.md` instead: present the digest and recommend explicit acceptance of the residual findings, never another fix pass. Otherwise follow the **Decision Support** protocol in `references/shared-conventions.md`: recommend a path based on the findings and give each option a one-line trade-off. Let the severity and volume of findings drive the recommendation — e.g. recommend (b) **Apply fixes now** when findings are clear-cut and mechanical; recommend (a) **Review first** when findings involve design judgment or you flagged low-confidence items; recommend (c) **plan-mode workflow** when the fixes are large or interdependent enough to warrant a reviewed plan. Present:
+**Advisory-only reports skip the question.** When the report contains no blocking finding (`error`/`gap`), there is nothing to route to forge-fix: do not present the fix options below — state that the report is advisory-only, record `passed` with the report attached (Step 6), and continue; the advisories stay discoverable in the findings document for whoever next touches the artifact. Otherwise (at least one blocking finding), use host's question mechanism to ask how to proceed — **unless this report closes the SECOND consecutive `reverify-findings` for this served stage** (count the round-discriminated reports in `.verification/`), in which case follow "Escalation (the round ledger)" in `references/stage-exit-protocol.md` instead: present the digest and recommend explicit acceptance of the residual findings, never another fix pass. Otherwise follow the **Decision Support** protocol in `references/shared-conventions.md`: recommend a path based on the findings and give each option a one-line trade-off. Let the severity and volume of findings drive the recommendation — e.g. recommend (b) **Apply fixes now** when findings are clear-cut and mechanical; recommend (a) **Review first** when findings involve design judgment or you flagged low-confidence items; recommend (c) **plan-mode workflow** when the fixes are large or interdependent enough to warrant a reviewed plan. Present:
 - **(a) Review the findings first** — read `{findings-file}` and decide per-finding; safest, but you act on nothing until you return.
-- **(b) Run `/feature-forge:forge-fix {feature} --served-stage {servedStage}` now** — applies the fix plan immediately; fastest, best when findings are unambiguous.
-- **(c) Enter plan mode and re-run `/feature-forge:forge-verify {feature}`** — produces a reviewable plan before any edits; best for large or risky fix sets.
+- **(b) Run `forge-fix {feature} --served-stage {servedStage}` now** — applies the fix plan immediately; fastest, best when findings are unambiguous.
+- **(c) Enter plan mode and re-run `forge-verify {feature}`** — produces a reviewable plan before any edits; best for large or risky fix sets.
 
 Do NOT embed this question in your text output.
 
@@ -232,7 +232,7 @@ Never hand-author a verify entry. Every `stages.forge-verify-*` transition is wr
 Choose result arguments from the report outcome, never a combined placeholder: clean uses `--status passed --findings-count 0`; advisory-only uses `--status passed` with its positive count; blocking uses `--status findings-reported` with its positive total count. All variants attach the Step 4 report:
 
 ```bash
-R="$(bash -c 'for d in "${FEATURE_FORGE_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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${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 "{outcome-specific status}" \
@@ -243,7 +243,7 @@ python3 "$R/scripts/forge-session.py" state-verify \
 **Two-commit provenance — never `--amend`.** The write above records `commitHash: null`. Commit 1 records the findings document and the state together (Git Commit Protocol, `references/shared-conventions.md`). Then record the provenance of that commit in Commit 2, passing the **full 40-character** hash of Commit 1 — 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 "${FEATURE_FORGE_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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${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}" \
@@ -258,30 +258,27 @@ Epic mode is **epic-scoped**, not per-feature: `--stage forge-0-epic` writes `{s
 
 ## Step 7: Close the Stage
 
-**Ownership.** Read branch ownership 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-verify` is the only path that carries no dispatcher. Never infer ownership from how the invocation happened to be phrased; judge the token, not the wording. Pass the resolved value straight through as `--owner`, and preserve it through any re-verify. As a **nested** owner you return your structured result (mode, served stage, outcome, findings file, findings count) to the caller and print **no terminal block at all** — the outer authoring stage is the sole terminal 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. `references/stage-exit-protocol.md` § "Branch ownership: the `owner:` token" owns this rule.
+**Ownership.** Read branch ownership from the literal `owner: nested` / `owner: direct` token in the prompt that dispatched you. **Absent the token you are `direct`** — a user-typed `forge-verify` is the only path that carries no dispatcher. Never infer ownership from how the invocation happened to be phrased; judge the token, not the wording. Pass the resolved value straight through as `--owner`, and preserve it through any re-verify. As a **nested** owner you return your structured result (mode, served stage, outcome, findings file, findings count) to the caller and print **no terminal block at all** — the outer authoring stage is the sole terminal 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. `references/stage-exit-protocol.md` § "Branch ownership: the `owner:` token" owns this rule.
 
 **Served stage.** Pass `--verify-mode` carrying Step 1's explicit or auto-detected mode (`epic`, `prd`, `tech`, `specs`, `backlog`, `impl`); the script maps it to the served production stage. When the caller already owns a stage and states it, additionally pass that value as `--served-stage` — if the two disagree the script fails closed rather than guessing. Derive the served stage **only** from that mode argument or from authoritative pipeline state: conversational context and `currentStage` are never valid inference sources.
 
-**Capability.** Pass `--verify-capability interactive` only when **both** a question mechanism equivalent to the host's question mechanism is available **and** a clean-room `forge-verifier` may actually be dispatched right now. Clause (b) tests **permitted dispatch, not a listed tool**: a session that may dispatch only when the user asked, but does have a question mechanism, is `interactive` — the gate's affirmative choice supplies the request. Reserve `manual` for **no** question mechanism **and** **no** permitted dispatch. An auto-verify directive under a no-unsolicited-dispatch bar is presented through the gate and dispatched on the affirmative choice — never skipped, and never resolved by advancing to the production successor.
+**Capability.** Determine `--verify-capability` per **Host and capability determination** in `references/stage-exit-protocol.md` (summarized under **Verify Capability** in `references/shared-conventions.md`): pass `interactive` only when a question mechanism equivalent to host's question mechanism is available **and** dispatching a clean-room `forge-verifier` is *permitted* right now — otherwise `manual`. That reference owns the full rule, including why a consent-only bar is still `interactive`. Applied here: an auto-verify directive under a no-unsolicited-dispatch bar is presented through the gate and dispatched on the affirmative choice — never skipped, and never resolved by advancing to the production successor.
 
-**Outcome.** Invoke the exit **exactly once**, with the `--outcome` this run's result maps to:
+**Outcome.** Derive the `--outcome` from the settled on-disk record, never by eyeballing conversational state. **For a production-stage verify** (mode `prd`/`tech`/`specs`/`backlog`/`impl`, so `{servedStage}` is `forge-1-prd`…`forge-5-loop`), after Step 6's `state-verify` write run `select-outcome` — it reads the verify entry and the latest report and returns `{outcome, reason, evidence}`, the `outcome` being exactly one of `passed`, `findings`, `skipped`, or `failed`. Add `--op-failure` when a dispatch, check, or state write failed this run (a `CLEAN_ROOM_UNAVAILABLE` sentinel or a non-answer counts): it is the one signal disk cannot record. On exit 2 the disk names no terminal result and no signal was given — surface its `Error:` line rather than guessing. **Epic mode is out of the verb's scope** — an epic's verification lives in `.epic-state.json`, not a member's `.pipeline-state.json`, so the verb rejects `forge-0-epic`; for `epic` choose the `--outcome` directly per the `### verify` mapping. That four-outcome mapping and its rationale live in `references/select-outcome.md`.
 
-| This run's result | `--outcome` |
-|---|---|
-| Zero findings — the artifacts are clean | `passed` |
-| Advisory-only report (no `error`/`gap`) — recorded `passed` with the report attached | `passed` |
-| A report with at least one blocking finding (`error`/`gap`) was written | `findings` |
-| The user explicitly chose to defer pipeline action **and** that skip was persisted via `state-verify --status skipped` | `skipped` |
-| A dispatch, a check, or a state write failed and needs intervention | `failed` |
-
-Merely **presenting** blocking findings is `findings`, not `skipped` — all three Step 5 options are `findings`, including (a) "review the findings first", which defers *your* next action rather than the pipeline's. `skipped` is available only for an explicit user deferral of **pipeline action** whose skip has already been persisted. A `CLEAN_ROOM_UNAVAILABLE` sentinel or a non-answer from an advertised dispatch is an operational failure, not a user skip: it is `failed`. A state-write failure is `failed`, and no success block may be printed after one.
+```bash
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${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; }
+# production-stage modes only (not epic); append --op-failure on an operational failure per the paragraph above
+python3 "$R/scripts/forge-session.py" select-outcome --feature "{feature}" --served-stage "{servedStage}" --skill verify --specs-dir "{specsDir}" --json
+```
 
-Add `--epic "{epic}"` when the feature is an epic member, and `--served-stage "{servedStage}"` when the caller supplied one. Pass no other flags.
+Pass the returned `outcome` straight through as the `stage-exit --outcome` below. Add `--epic "{epic}"` (both calls) when the feature is an epic member, and `--served-stage "{servedStage}"` to the exit when the caller supplied one. Pass no other flags.
 
 **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 "${FEATURE_FORGE_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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${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-verify --owner "{owner}" --outcome "{VerifyOutcome}" --verify-mode "{mode}" --specs-dir "{specsDir}" --host generic --verify-capability "{verify-capability}"
 ```
@@ -299,7 +296,7 @@ Obey the DIRECTIVES it prints, in the consumption order this protocol fixes: sur
 - For specs verification, also run the deterministic traceability validator to supplement agent-driven traceability checks. Include any uncovered requirements or orphaned references as findings:
 
 ```bash
-R="$(bash -c 'for d in "${FEATURE_FORGE_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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${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/validate-traceability.py" {resolvedFeatureDir}/PRD.md {resolvedFeatureDir}/ --json
 ```
@@ -310,6 +307,6 @@ python3 "$R/scripts/validate-traceability.py" {resolvedFeatureDir}/PRD.md {resol
 
 This skill was authored Claude-first; the body above refers to "the host's question mechanism", "the host's subagent mechanism", and "the host's background-execution mechanism". On Codex:
 
-- **User input:** Codex has no structured question tool — ask the question directly and wait for the user's reply before proceeding. Never skip a required question or assume an answer.
+- **User input:** Codex has no structured question tool. Which rung you are on is **not** observable from inside the session — a `codex exec` run looks exactly like an interactive one — so read it from the Interaction Capability Ladder's `interaction-mode` record instead of judging it. Interactive session — ask the question directly and wait for the reply; never assume an answer. Non-interactive — don't wait: take the Interaction Capability Ladder's declared conservative default, state it in your output, and use `no-default: abort — <question> requires a human answer` for an interview question with no sane default (`references/shared-conventions.md`).
 - **Subagents:** spawn a Codex subagent using the named custom agent under `.codex/agents/<name>.toml`. Codex spawns a subagent only when explicitly asked; if the custom agent is unavailable, run that step inline yourself.
 - **Background / monitoring:** run long-lived runner commands in your shell session and report progress as it arrives — there is no Claude-style background or monitoring tool to arm.

package/adapters/codex/skills/forge-verify/references/findings-template.md

@@ -107,7 +107,7 @@ Here are complete example findings showing the expected quality:
 - **Severity:** inconsistency
 - **Location:** 00-core-definitions.md section 2.3 vs 03-session-management.md section 1.1
 - **Issue:** 00-core-definitions.md defines `SESSION_DURATION_MS = 7 * 24 * 60 * 60 * 1000` (7 days), but 03-session-management.md section 1.1 states "sessions expire after 30 days." These contradict each other.
-- **Suggested fix:** Align both documents to the PRD requirement. PRD.md REQ-SEC-03 says "sessions should have a reasonable expiry" without specifying a duration — use the host's question mechanism to ask the user which value is intended, then update both documents.
+- **Suggested fix:** Align both documents to the PRD requirement. PRD.md REQ-SEC-03 says "sessions should have a reasonable expiry" without specifying a duration — use host's question mechanism to ask the user which value is intended, then update both documents.
 - **References:** PRD.md REQ-SEC-03, 00-core-definitions.md section 2.3, 03-session-management.md section 1.1
 ```
 
@@ -145,7 +145,7 @@ This is the one `state-*` call site where the member `--epic` rule does **not**
 version — which is what keeps the result reading fresh rather than stale.
 
 ```bash
-R="$(bash -c 'for d in "${FEATURE_FORGE_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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${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 \

package/adapters/codex/skills/forge-verify/references/select-outcome.md

@@ -0,0 +1,138 @@
+# `select-outcome` — deterministic exit-outcome selection
+
+`forge-verify` and `forge-fix` each close a run by choosing exactly one
+`stage-exit --outcome`. That choice used to be model judgment over conversational
+state. `forge-session.py select-outcome` derives it from the authoritative on-disk
+record instead — the same "never eyeball the graph" move `rank-features` makes when
+it derives `verifyGate` for the navigator (issue #276, part of the #265 guard-first
+program).
+
+The verb reads, never writes. It is called at the exit step, **after** the run's
+result has already been persisted by `state-verify` and the findings document has
+been written, so the disk state it reads is the run's own settled record.
+
+## Synopsis
+
+```
+python3 forge-session.py select-outcome \
+  --feature F --served-stage S --skill verify|fix \
+  [--op-failure] [--user-deferred] [--decisions-open] \
+  [--specs-dir DIR] [--epic E] [--json]
+```
+
+`--served-stage` is one of the five verify-token production stages
+(`forge-1-prd`, `forge-2-tech`, `forge-3-specs`, `forge-4-backlog`, `forge-5-loop`).
+`forge-0-epic` (epic-scoped verification lives in `.epic-state.json`) and
+`forge-6-docs` (no verify token) are **out of scope** and rejected.
+
+Output — always `{outcome, reason, evidence: [...]}`:
+
+```json
+{
+  "outcome": "reverify-findings",
+  "reason": "fixes were applied and a re-verify reopened blocking findings for the served stage",
+  "evidence": [
+    "forge-verify-tech status = findings-reported",
+    "latest report .verification/VERIFY-tech-2026-09-07-round2.md (round 2): 2 blocking = 1 error + 1 gap, 3 total finding(s)",
+    "round reports on disk: 2",
+    "fix progress: 1 step(s) applied; sweep 1 fixed / 0 justified / 0 false-positive"
+  ]
+}
+```
+
+## Outcome vocabularies
+
+The verb chooses from exactly the branch skills' `--outcome` domains — the
+`VerifyOutcome` and `FixOutcome` aliases in `forge-session.py`. Those aliases are
+pinned to the tables below by `tests/test_select_outcome.py` (both directions), so the
+enum and this reader-facing mapping can never drift. `forge-verify` and `forge-fix`
+used to carry these tables in their SKILL bodies; issue #278 flipped the bodies to
+call the verb and moved the tables here, their reader-facing home.
+
+### verify
+
+| This run's result | `--outcome` |
+|---|---|
+| Zero findings — the artifacts are clean | `passed` |
+| Advisory-only report (no `error`/`gap`), recorded `passed` with the report attached | `passed` |
+| A report with at least one blocking finding (`error`/`gap`) was written | `findings` |
+| The user explicitly deferred pipeline action and that skip was persisted (`state-verify --status skipped`) | `skipped` |
+| A dispatch, check, or state write failed and needs intervention | `failed` |
+
+### fix
+
+| This run's result | `--outcome` | Authoritative downstream 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, validation, commit, or state write failed (Steps 4–6) | `failed` | Fix/navigator recovery; no advancement |
+| Fixes persisted and re-verify not yet 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 reopened an unresolved prior finding or a new blocking defect (clean-or-advisory-only 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; findings remain unresolved; no advancement |
+
+## Inputs read from disk
+
+- The served stage's `stages.forge-verify-{token}` entry in `.pipeline-state.json` —
+  its `status` is the authoritative signal, written mechanically by `state-verify`.
+- The latest `.verification/VERIFY-{mode}-*.md` report (round-aware: `-round{N}` beats
+  the un-suffixed base file, and the newest day's newest round is "latest"). Blocking
+  counts come from the `## Findings` severities (`error`/`gap`), never from the human
+  `## Summary` line.
+- Each report's `## Fix Progress` section — its `[APPLIED]` steps and the sweep
+  dispositions (`FIXED`/`JUSTIFIED`/`FALSE-POSITIVE`). A report carrying `[APPLIED]`
+  steps is the disk record that a fix pass ran (`fix-applied`).
+
+## Derivation
+
+### verify
+
+1. `--op-failure` → **failed**.
+2. entry `skipped` → **skipped**.
+3. entry `findings-reported` → **findings**.
+4. entry `passed` → **passed** (a clean report, an advisory-only report, or accepted
+   residual findings — all three are recorded `passed`).
+5. otherwise (no terminal result recorded) → **fail closed** (exit 2).
+
+### fix
+
+1. `--op-failure` → **failed**.
+2. `--user-deferred` → **deferred**.
+3. `--decisions-open` → **decisions**.
+4. no report for the mode → **no-findings**.
+5. entry `findings-applied` → **applied** (a re-verify is still owed).
+6. entry `passed` → **reverified**. A forge-fix pass reaches a `passed` served stage
+   only by re-verifying it: forge-fix Step 1.5 resolves its served stage to an
+   *unresolved* verify entry (`findings-reported`, `findings-applied`, or a pending
+   debt), never an already-resolved `passed`, so a `passed` entry at a fix exit is the
+   mandatory re-verify's own passing result. (`fix-applied` is not consulted here — it
+   reads every round on disk and so cannot tell this pass's fixes from an earlier
+   cycle's.)
+7. entry `findings-reported` + a fix ran → **reverify-findings** (a re-verify reopened
+   findings); entry `findings-reported` + no fix ran → **fail closed** (exit 2).
+8. any other resolved/absent entry with no fix → **no-findings**.
+
+Two cases the issue calls out because a model tends to mis-eyeball them, and the verb
+gets right by keying on the entry status rather than the presence of findings text:
+
+- **A sweep whose survivors are all `FALSE-POSITIVE`.** Disposition is not a defect —
+  the entry is still `findings-applied`, so the outcome is **applied**, never `failed`.
+- **A re-verify red on a scoped subset.** The round-2 report reopens blocking findings
+  and the entry returns to `findings-reported`, so the outcome is **reverify-findings**.
+
+## Runtime signals
+
+Three outcomes cannot be read off disk, because the fact that distinguishes each is
+inherently runtime:
+
+- **failed** — an operational failure (a dispatch, step, validation, commit, or state
+  write) leaves *no* state write, so disk shows the prior state.
+- **deferred** — an explicit user deferral of the fix or re-verify is byte-identical on
+  disk to a nested/manual `applied` (both leave the entry at `findings-applied`).
+- **decisions** — unresolved user decisions live in the free-prose "User Decisions
+  Required" section, which has no machine format.
+
+The caller asserts these with `--op-failure` / `--user-deferred` / `--decisions-open`
+(the latter two are `fix`-only). Everything else is pure disk derivation. When the disk
+record names no terminal outcome and no signal was supplied, the verb **fails closed**
+with `Error:` on stderr and exit 2 — it never guesses.