@garygentry/feature-forge 0.3.6 → 0.3.7

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

@@ -16,7 +16,7 @@ Read and follow `references/shared-conventions.md` for feature name validation,
 
 **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 `/skill: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.
+**Turn structure reminder:** Text first, then `AskUserQuestion` for all questions — never embed one in your text (it stalls). At rung 2/3, see the Interaction Capability Ladder.
 
 ## Step 1: Locate Findings and Establish the Served Stage
 
@@ -38,7 +38,7 @@ Read and follow `references/shared-conventions.md` for feature name validation,
 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 "${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/fix-sweep.py" plan-coverage "{resolvedFeatureDir}/.verification/{findingsFile}" --json
 ```
@@ -73,7 +73,7 @@ For each step in the "Execution Steps" section, in order:
 **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 "${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/fix-sweep.py" sweep --json
 ```
@@ -98,7 +98,7 @@ Detection is mechanical; disposition is judgment — a hit is a candidate, not a
 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 "${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 findings-applied \
@@ -112,7 +112,7 @@ Then follow the Git Commit Protocol in `references/shared-conventions.md`. If `g
 **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 "${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}" \
@@ -142,21 +142,18 @@ On a **direct** invocation, present the gate with `AskUserQuestion` using these
 
 **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.
+**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 `AskUserQuestion` is available **and** dispatching a clean-room `forge-verifier` is *permitted* right now — otherwise `manual`. That reference owns the full rule (permission-not-presence, why a consent-only bar is still `interactive`, and the `none`-gate consent variant). Applied here: 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:
+**Outcome.** Derive the `--outcome` from the settled on-disk record, never by eyeballing conversational state. **For a production-stage served stage** (`{servedStage}` is `forge-1-prd`…`forge-5-loop`, whether or not `--epic` also applies), after Step 5's `state-verify` write run `select-outcome --skill fix` — it reads the verify entry and the latest report (including its `## Fix Progress`) and returns `{outcome, reason, evidence}`. Three outcomes turn on facts disk cannot record, asserted with flags: `--op-failure` (a fix step, validation, commit, or state write failed — Steps 4–6; a cancellation or unavailable tool is a failure, never a skip), `--user-deferred` (the user explicitly deferred the fix pass or the re-verify — Steps 3, 6), and `--decisions-open` (user decisions remain unresolved — Step 3). Everything else — `no-findings`, `applied`, `reverified`, `reverify-findings` — is pure disk derivation; on exit 2 the disk names no terminal result and no signal was given, so surface its `Error:` line rather than guessing. **An epic-mode served stage (`forge-0-epic`, from an `epic`-mode findings report) is out of the verb's scope** — that verification lives in `.epic-state.json`, so the verb rejects `forge-0-epic`; choose the `--outcome` directly per the `### fix` mapping. The seven-outcome mapping and each outcome's authoritative downstream action live in `references/select-outcome.md`.
 
-| 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 |
+```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 served stage only (not forge-0-epic); append --op-failure / --user-deferred / --decisions-open per the paragraph above when they apply
+python3 "$R/scripts/forge-session.py" select-outcome --feature "{feature}" --served-stage "{servedStage}" --skill fix --specs-dir "{specsDir}" --json
+```
 
-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.
+`applied` is not `reverified`: `findings-applied` cleared the freshness the writer deliberately dropped, so only `reverified` after a passing verify permits advancement. Pass the returned `outcome` straight through as the `stage-exit --outcome` below.
 
 **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.
 
@@ -165,7 +162,7 @@ Add `--epic "{epic}"` when the feature is an epic member. 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-fix --owner "{owner}" --outcome "{FixOutcome}" --served-stage "{servedStage}" --specs-dir "{specsDir}" --host pi --verify-capability "{verify-capability}"
 ```
@@ -179,7 +176,8 @@ Obey the DIRECTIVES it prints, in the consumption order this protocol fixes: sur
 This Pi bundle preserves Claude's `AskUserQuestion` references because it ships a Pi compatibility extension registering an `AskUserQuestion` tool. On Pi:
 
 - **User input:** use `AskUserQuestion` for genuine user decisions. It supports multiple questions, option descriptions, recommended ordering, multi-select, previews, and free-form Other/custom answers.
-- **Skill dispatch:** Pi uses `/skill:<name>` commands. If you cannot invoke a skill directly, print the exact `/skill:<name> ...` command for the user to run.
+- **Non-interactive (`-p`/`--mode json`):** `AskUserQuestion` is stripped from the tool list, so its absence alone cannot tell you the rung — read that from the Interaction Capability Ladder's `interaction-mode` record. A call attempted anyway fails with `Error: UI not available (running in non-interactive mode)` — never read that as a decline. 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`).
+- **Skill dispatch:** Pi uses `/skill:<name>` commands. If you cannot invoke a skill directly, print the exact `/skill:<name> ...` command for the user to run. A **forge-invocation-args** compatibility extension wraps the arguments of a `/skill:forge-*` command in a `<feature-forge-invocation>` envelope before Pi expands it, so read the feature name from that envelope's `<arguments>` element (an empty element means none was supplied) rather than from unlabeled trailing text — see `references/shared-conventions.md` § Feature Name Requirement.
 - **Subagents:** this bundle declares its custom agents (`forge-researcher`, `forge-spec-writer`, `forge-verifier`) as package agents. If a `subagent` tool is registered, dispatch one with `{ agent: "forge-verifier", task: "..." }`, or fan several out concurrently with `{ tasks: [{ agent: "forge-spec-writer", task: "..." }, ...] }`. If no `subagent` tool is available, run that step inline yourself.
 - **Background / monitoring (forge-5-loop):** Pi has no built-in background bash, persistent monitor, or push-notification, so do **not** run the loop runner in the foreground and do **not** try to arm one. This bundle registers a **forge-loop-supervisor** extension that IS the "background-execution mechanism" and "monitoring mechanism" Steps 3b–3f refer to. Concretely:
   - **Launch (Step 3b):** call **`forge_loop_launch`** with the backlog dir (and `review` / `agent` / `iterations` as resolved from config). It starts the loop **detached** — it runs in rauf's server and outlives this session — and returns immediately; you do not build or redirect a command yourself.

package/adapters/pi/skills/forge-fix/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.