@garygentry/feature-forge 0.2.12 → 0.2.14

package/adapters/cursor/skills/forge-3-specs/references/stage-exit-protocol.md

@@ -0,0 +1,258 @@
+# Stage Exit Protocol
+
+The single source of truth for how every forge **authoring** stage closes. It
+replaces the old ad-hoc "Next steps:" bullet lists with one fixed, correctly-ordered
+sequence: **verify (if missing or stale) → `/clear` → run the next command.**
+
+Two principles this protocol encodes (do not relitigate — they are locked product
+decisions):
+
+1. **Clearing is recommended on its own merits at every stage boundary** — a clean
+   start for the next stage — *not* as a proxy for a full context window. Window
+   fullness only changes *how emphatically* the clear is recommended, never *whether*
+   it is.
+2. **Verify happens before the clear, never after** — in the authoring session, whether
+   manual **or** auto. Verify's clean-room subagent is dispatched from the *current*
+   session, so the findings digest and any fix decision land where the context to act on
+   them still exists. This holds for auto-verify too: the stage skill dispatches the
+   clean-room verify (and any autoFix) at stage end, in-session, before the exit — it is
+   **not** deferred to the navigator, which runs *after* the `/clear` with none of the
+   authoring context. Clearing first throws that context away.
+
+## How this file is used
+
+The five authoring stages (`forge-0-epic` … `forge-4-backlog`) close with the
+**Scripted Stage Exit**: a short stamped block (below) that runs
+`forge-session.py stage-exit`, obeys the DIRECTIVES it prints per the **directive
+contract** in this file, and prints the script-emitted NEXT-STEPS block verbatim as the
+absolute last output. All the conditional logic the old prose blocks asked the model to
+compute (effective auto-verify, freshness collapse, gate selection, host wording) now
+lives in the script, deterministically; only genuinely interactive work (clean-room
+subagent dispatch, `AskUserQuestion` gates) remains prose — specified once here, not
+per stage.
+
+The loop (`forge-5-loop`) keeps its bespoke exits: it stamps the **standard block**
+(step-6 epic-member handoff) and the **warm variant** (all-done closing) below,
+verbatim. `forge-6-docs` is **terminal** — it stamps no exit block.
+
+A drift-guard test (`tests/test_stage_exit_protocol.py`) asserts each stamp site still
+contains its block, so an edit here must be mirrored into every stamp site (and
+vice-versa).
+
+## Stamp sites
+
+| Stamp site | Block |
+|---|---|
+| `forge-0-epic` … `forge-4-backlog` | scripted-stage-exit stamp |
+| `forge-5-loop` (step-6 epic-member handoff) | standard |
+| `forge-5-loop` (all-done closing → docs) | warm |
+
+The scripted stamp fills one build-time slot, `{stage-exit-args}` — the per-stage
+argument list (e.g. `--feature "{feature}" --stage forge-2-tech`; the epic stage passes
+`--feature "{epic}" --stage forge-0-epic --next-feature "{first-actionable-feature}"`).
+`{feature}` / `{epic}` / `{specsDir}` / `{first-actionable-feature}` remain runtime
+placeholders the skill resolves before running the command, exactly as elsewhere.
+
+<!-- BEGIN: scripted-stage-exit-stamp -->
+**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 {stage-exit-args} --specs-dir "{specsDir}" --host claude
+```
+
+Obey the DIRECTIVES it prints, in order, per the directive contract: `runInStageVerify: true` → dispatch the in-stage clean-room verify now (honoring `autoFixEligible`); `verifyGate: "standard"` → present the Standard Verify Gate; `verifyGate: "manual-print"` → print the `verifyCommand` for the user; non-empty `invalidAutoVerifyKeys` → print a one-line warning. Then **print the NEXT-STEPS block verbatim as your absolute last output — nothing after its sentinel line.**
+<!-- END: scripted-stage-exit-stamp -->
+
+## Directive contract
+
+`stage-exit` emits a DIRECTIVES object and a NEXT-STEPS block. The skill executes the
+directives **in this order**; the script has already computed every conditional, so a
+directive is an instruction, not a question to re-derive.
+
+### `invalidAutoVerifyKeys` (non-empty)
+
+Print a one-line warning first (e.g. "⚠️ forge.config.json `autoVerifyStages` has
+unknown keys: … — they are ignored; fix the typo").
+
+### `runInStageVerify: true` — in-stage auto-verify {stageNoun}
+
+Auto-verify is effective for this stage and verification is outstanding — verify **now,
+in this session** (principle #2 applied to auto-verify: the digest and any fix decision
+land here, where the authoring context still exists — not deferred to a post-`/clear`
+navigator):
+
+1. **Clean-room verify (require-clean).** Dispatch the clean-room `forge-verifier`
+   subagent from this session in require-clean mode — the same path the navigator uses
+   (`skills/forge-verify/SKILL.md`). Dispatch it **synchronously and await its digest
+   inline** — do **not** run it in the background or announce it as "still running";
+   the digest and any fix decision must land in this session. It inherits none of this
+   session's context, so no `/clear` is needed and only a compact digest returns.
+   **Clean-room unavailable** (no `Agent` tool, `forge-verifier` not dispatchable) **or
+   a non-answer returned** (the verifier returned a placeholder / "still running" /
+   delegation message instead of a findings block): do **not** run inline and do **not**
+   silently accept the non-answer as a pass — leave verify **pending** so the navigator
+   catch-up fires on a later Claude-host `/feature-forge:forge`, print the
+   `verifyCommand` for the user to run, and continue to the NEXT-STEPS block.
+2. **Verify passed / no findings** → the fresh verify state is recorded by the
+   clean-room run; continue to the NEXT-STEPS block.
+3. **Verify found findings** →
+   - **`autoFixEligible: true` AND the findings document has zero unresolved decision
+     points** → chain `feature-forge:forge-fix` in-session (it owns its own commit +
+     step tracking), then run a **mandatory re-verify** in require-clean mode. Continue
+     to the NEXT-STEPS block only if the re-verify passes. On any precondition miss, a
+     forge-fix early stop, or a red re-verify, fall through to the digest gate below —
+     never a silent partial mutation. (`autoFixEligible` already folds in the config
+     `autoFix` flag and the clean-tree precondition; a dirty tree or
+     `gitCommitAfterStage: false` arrives here as `false`.)
+   - **`autoFixEligible: false`, or unresolved decision points** → surface a **compact
+     findings digest** as text, then present the gate via `AskUserQuestion`: **Run
+     `forge-fix` now** *(recommended — you are in-context and the digest is right
+     here)* / **Clear + advance anyway** (leave the findings for later) / **Stop
+     here**. Do **not** hard-stop and do **not** silently walk past. Act on the choice,
+     then continue to the NEXT-STEPS block.
+
+### `verifyGate: "standard"` — the Standard Verify Gate
+
+Auto-verify is off for this stage and verification is outstanding (`verifyState` is
+`never`, `stale`, or `failing`). Verify **now, before clearing**, using
+`AskUserQuestion` with exactly these three options — but only when the host has a
+question mechanism **and** the clean-room path is available (the `Agent` tool plus a
+dispatchable `forge-verifier` subagent); otherwise degrade exactly as `manual-print`
+below:
+
+- **Verify {stageNoun} now** *(recommended)* — dispatch the clean-room `forge-verifier`
+  subagent from this session in require-clean mode; the digest returns here so any fix
+  decision keeps its context. One-time — it does **not** change config.
+- **Verify now + enable auto-verify going forward** — verify now **and** patch
+  `"autoVerify": true` into `forge.config.json` in place (preserve formatting and every
+  other key) so future stages verify automatically, no prompt. This complements the
+  `forge-init` opt-in. **Do not auto-commit this config change** — treat it like
+  `notes`: a user-facing edit the user commits on their own cadence, never folded into
+  a stage's artifact commit.
+- **Skip for now** — go straight to the NEXT-STEPS block without verifying. Record this
+  stage's verify status as `"skipped"` in pipeline state (mirroring the existing skip
+  handling) **only** on an explicit skip — a skip does not go stale.
+
+If verify runs and finds findings, handle them exactly as in the in-stage flow above
+(digest + `AskUserQuestion` gate; `autoFixEligible` applies unchanged).
+
+### `verifyGate: "manual-print"`
+
+Verification is outstanding but the host cannot present the gate or dispatch
+clean-room. Do **not** run verify inline — print the `verifyCommand` for the user to
+run (mirroring `autoInvokeNextStage`), offer the auto-verify enable as plain text only
+if a config write is possible, and continue to the NEXT-STEPS block. Verify state stays
+outstanding, so the navigator catch-up can fire later.
+
+### `verifyGate: "none"`
+
+Verification is already resolved (fresh or explicitly skipped) or the in-stage run
+above covers it. Say so in one line and continue to the NEXT-STEPS block.
+
+### `epicReconcile` (epic backflow — present only when there are open requests)
+
+Emitted only when the exiting member carries `open` `epicChangeRequests` (recorded by
+`forge-1-prd`/`forge-2-tech` when the epic *decomposition* itself must change — see
+`references/pipeline-state-schema.json`). Absent on the common path and for standalone
+features. The script has already folded the routing into the NEXT-STEPS block, so this
+directive is informational — you do **not** re-derive the wording:
+
+- `required: true` (at least one `blocksCurrent: true` request) — the NEXT-STEPS block's
+  fenced **primary** command is the epic reconcile command
+  (`/feature-forge:forge-0-epic {epic}`), and the normal next stage is demoted to a
+  follow-up line ("After reconciling, continue with …"). This is *reconcile-before-specs*:
+  proceeding would author artifacts against a decomposition that is about to change. It is
+  strongest when exiting `forge-2-tech` (next is `forge-3-specs`, the point of no cheap
+  return).
+- `reminder: true` (only `blocksCurrent: false` requests) — normal next-stage routing is
+  unchanged; the block appends a non-blocking reminder line ("You also flagged N epic
+  change(s) to reconcile when convenient …"). This is *finish-then-edit*.
+
+Either way the added lines are host-neutral (no literal `/clear`) and sit **above** the
+sentinel; just print the NEXT-STEPS block verbatim as always.
+
+### Deferred decisions — do not solicit next-stage decisions at this exit
+
+Each stage owns its own decisions. At a stage exit, do **not** pull a *later* stage's
+decision forward — do not ask the user (or decide unilaterally) something that properly
+belongs to the next stage's interview (e.g. at `forge-1-prd` exit, don't settle the
+concrete cache backend that `forge-2-tech` will design). Soliciting it here guesses ahead
+of the stage that owns the context, and the answer has nowhere durable to live.
+
+Instead, when you notice a decision that belongs downstream, **record it structurally** as
+a `deferredDecisions[]` entry on this feature's `.pipeline-state.json` (schema in
+`references/pipeline-state-schema.json`; same direct-edit path as `notes` /
+`epicChangeRequests[]`): `question` (phrased for the target stage), optional `rationale`
+and `targetStage`, `raisedBy` (this stage), `raisedAt` (ISO-8601 UTC), `status: "open"`.
+This keeps the exit focused on *this* stage's next-step routing while carrying the open
+question forward for the owning stage to resolve (it flips `status` to `addressed` when it
+does). Prefer a `deferredDecisions[]` entry over stuffing the same thing into the free-text
+`notes` string. This is a recording affordance, not a gate: never block the exit on it.
+
+### The NEXT-STEPS block (always last)
+
+Print the script's NEXT-STEPS block **verbatim as your absolute last output**. Nothing
+follows its final sentinel line (`─ forge: end of stage ─`) — no caveats, no summary,
+no sign-off. The block already carries the `/clear` recommendation (host-aware wording
+via `--host`) and the exact next command, so trailing prose can only push the user's
+next action out of view.
+
+---
+
+## Standard block
+
+Stamped at the loop's step-6 epic-member handoff (finishing feature A → starting
+feature B's PRD). It self-adapts: step 1's verify gate only fires when verification is
+actually outstanding, so at a boundary where verify already ran (or was explicitly
+skipped, or auto-verify is on) it silently collapses to just the `/clear` →
+next-command steps.
+
+Slots: `{stage}` (a lowercase noun phrase), `{verify-command}`, `{next-command}`.
+
+<!-- BEGIN: standard-exit-block -->
+**This stage is done — walk the user through the Stage Exit Protocol** before moving on. The order is fixed, and step 2 is something only the user can do:
+
+1. **Verify {stage} first — if it isn't already verified.** If verify already ran in this session — via the in-stage auto-verify on the authoring stages, or the interactive impl-verify offered above on the loop — or is already fresh on record, or the stage was explicitly skipped, say so and go straight to step 2. Only when `autoVerify` is off for this stage **and** verify is **missing or stale** do you present the **Standard Verify Gate**: verify **now, before clearing**, using `AskUserQuestion` with exactly these three options — but only when the host has a question mechanism **and** the clean-room path is available (the `Agent` tool plus a dispatchable `forge-verifier` subagent):
+   - **Verify {stage} now** *(recommended)* — dispatch the clean-room `forge-verifier` subagent from this session in require-clean mode; the digest returns here so any fix decision keeps its context. One-time — it does **not** change config.
+   - **Verify now + enable auto-verify going forward** — verify now **and** patch `"autoVerify": true` into `forge.config.json` in place (preserve formatting and every other key) so future stages verify automatically, no prompt. This complements the `forge-init` opt-in. **Do not auto-commit this config change** — treat it like `notes`: a user-facing edit the user commits on their own cadence, never folded into a stage's artifact commit.
+   - **Skip for now** — go straight to `/clear` and the next command without verifying. Record this stage's verify status as `"skipped"` in pipeline state (mirroring the existing skip handling) **only** on an explicit skip — a skip does not go stale.
+
+   **Host / clean-room fallback (not a user-selectable option):** if the question mechanism, the `Agent` tool, or the `forge-verifier` subagent is unavailable, do **not** run clean-room — degrade to printing `{verify-command}` for the user to run inline/manually (mirroring `autoInvokeNextStage`), and offer the auto-verify enable as plain text only if a config write is possible.
+2. **Then `/clear`.** Recommended **unconditionally** at this boundary for a clean start — independent of how full the context window is. Every artifact is on disk, so the work survives the clear. **I can't `/clear` for you — you have to run it yourself.**
+3. **Then run the next command** in the fresh session — or re-run `/feature-forge:forge` to let the navigator resume from disk:
+
+   ```
+   {next-command}
+   ```
+<!-- END: standard-exit-block -->
+
+---
+
+## Warm-acceptable variant
+
+Stamp this only at the `forge-5-loop → forge-6-docs` boundary (the all-done result
+report). Here clearing is **optional**: the docs stage benefits from the still-warm
+context of what the loop actually did, and impl-verify is already offered interactively
+by the loop itself, so this block defers rather than re-presenting a gate.
+
+> **Note — no literal `/clear` here.** The warm block lives in `result-reporting.md`, a
+> skill-*own* reference that the adapter build copies **verbatim** (unlike skill bodies,
+> it is not host-term translated), so a literal `/clear` would reach non-Claude adapters
+> undegraded. The warm variant says "clearing is optional" anyway, so it is phrased
+> host-neutrally without the token on purpose — do not reintroduce `/clear` here. (The
+> standard block *does* use `/clear`; that is fine because every standard stamp site is a
+> skill **body**, where `scripts/build-adapters.py` degrades it.)
+
+<!-- BEGIN: warm-exit-block -->
+**The loop is complete — this is the one boundary where clearing before the next stage is optional.**
+
+1. **Verify is already offered above.** Impl-verify is offered interactively right after this report (Step 5b for a standalone feature, Step 6.1 for an epic member) — run it there rather than as a second gate. It runs clean-room, so it needs no fresh session.
+2. **Clearing is optional here — warm is fine.** `forge-6-docs` benefits from the still-warm context of what the loop actually did, so continuing in this same session is the easy default. A cold start also works — every artifact is on disk — but there is no need to force it.
+3. **Then run the next command** — in this warm session, or a fresh one if you prefer:
+
+   ```
+   {next-command}
+   ```
+<!-- END: warm-exit-block -->

package/adapters/cursor/skills/forge-4-backlog/forge-4-backlog.mdc

@@ -94,6 +94,9 @@ After presenting the plan as text, use the host's question mechanism following t
 
 **Forge-specific item requirements** layered on top of `author-backlog`'s output:
 - `specReferences` must be paths **relative to the project root** (e.g. `specs/auth/00-core-definitions.md`), NOT relative to the backlog file. The validator resolves them from the project root (not from `--specs-dir`, which only gates the check).
+- **Epic members — cross-member shared-state coupling (#144).** When authoring the backlog for an epic member, check whether this feature writes or migrates a file that a *sibling* member's already-shipped tests pin (its `mutatesShared[]` hint in `epic-manifest.json`, or a shared data corpus / generated fixture its specs say it mutates). If so, schedule a **reconciliation item up front** — before the first mutating item — that regenerates or re-pins the sibling's fixture (or updates the sibling test to the new shape), so the sibling suite stays green instead of red-gating every commit mid-loop. This is the authoring counterpart to forge-verify's CHECK-E10.
+- **Generated-artifact freshness vs. `testCommand` `--check` gates (#145).** If the project's `testCommand` gates on staleness of generated artifacts (`<generator> --check`-style sub-commands that fail when a checked-in generated file is out of date), then any item that regenerates **one** such artifact must regenerate **and commit all** the sibling artifacts those `--check` gates depend on — enumerate the whole gated set, not just the artifact the item is "about", or the item passes locally yet red-gates on the stale-generated check. Pass this to `author-backlog` alongside `testCommand` so the full regeneration sequence lands in each affected item; forge-verify's CHECK-B26 flags a partial set or an ungated regenerator after the fact.
+- **Lifecycle-gated artifacts — no test item forcing a forbidden transition (#150).** A test/e2e item whose acceptance asserts a *published / released / approved / human-reviewed* artifact state must either (a) `dependsOn` an explicit, human-gated publish/review item that legitimately produces that state, or (b) assert the state via a **dev-build / fixture path**. A test item must **never** be the only thing forcing a lifecycle transition another item pins the other way (e.g. one item keeps artifact `X` *draft* while a test demands it *published*, with nothing between to publish it) — the loop, unable to publish or obtain a human sign-off, will **fabricate** the provenance. `author-backlog` owns the general rule; forge-verify's CHECK-B27 flags a contradictory pair with no publisher in the dependency closure after the fact.
 
 > **Backlog schema & rauf contract are unchanged (REQ-COMPAT-03).** Epic membership adds **no** fields to backlog items — dependency edges live in the epic manifest, never in any backlog item. The JSON written here is byte-for-byte the same shape as a pre-epic standalone feature's backlog, and rauf is still launched against a single per-feature backlog path. Only the *path composition* changes (the `{feature}` segment in the backlog-directory rule above), not the schema or rauf's CLI surface.
 
@@ -131,6 +134,8 @@ State that the backlog is ready and invite adjustments before committing — a s
 
 ## Step 7: Update Pipeline State and Commit
 
+Before writing state or running the stage exit, invoke the **Stage-Completion Re-check** block in `references/shared-conventions.md` with `{stage}` = `forge-4-backlog` — a resumed mid-stage continuation must not overwrite a committed `backlog.json` or re-fire a finished exit.
+
 Write pipeline state conforming to `references/pipeline-state-schema.json`. Follow the Git Commit Protocol in `references/shared-conventions.md`.
 
 1. Update `{resolvedFeatureDir}/.pipeline-state.json`:

package/adapters/cursor/skills/forge-4-backlog/references/forge-config-schema.json

@@ -0,0 +1,236 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Feature Forge Configuration",
+  "description": "Project-level configuration for the feature-forge plugin. Place as forge.config.json in your project root.",
+  "type": "object",
+  "properties": {
+    "specsDir": {
+      "type": "string",
+      "default": "./specs",
+      "description": "Root directory for feature spec documents. Each feature gets a subdirectory."
+    },
+    "docsDir": {
+      "type": "string",
+      "default": "./docs/architecture",
+      "description": "Root directory for generated architecture documentation."
+    },
+    "backlogDir": {
+      "type": ["string", "null"],
+      "default": null,
+      "description": "Optional override for the backlog root. If set, the backlog is written to {backlogDir}/{feature}/backlog.json — the {feature} subdirectory is always composed in so multi-feature epics never collide. Default behavior (null): backlog.json is written to {specsDir}/{feature}/backlog.json with the feature specs."
+    },
+    "gitCommitAfterStage": {
+      "type": "boolean",
+      "default": true,
+      "description": "Automatically commit after each pipeline stage completes."
+    },
+    "commitPrefix": {
+      "type": "string",
+      "default": "forge",
+      "description": "Prefix for conventional commit messages, e.g., forge(auth): complete PRD"
+    },
+    "branchPerFeature": {
+      "type": "boolean",
+      "default": true,
+      "description": "Offer to create an isolated git branch when a feature/epic starts on the default branch (main/master). Gated only on the project using git — independent of gitCommitAfterStage. When false, forge never prompts for a branch and works on whatever branch is checked out. See the Branch Setup block in references/shared-conventions.md."
+    },
+    "branchPrefix": {
+      "type": "string",
+      "default": "forge/",
+      "description": "Prefix for the branch name suggested by Branch Setup, e.g. 'forge/' yields 'forge/{feature}' or 'forge/{epic}'. Ignored when branchPerFeature is false."
+    },
+    "stack": {
+      "type": ["string", "null"],
+      "description": "Detected or configured project stack identifier. Selects guidance from references/stacks/{stack}.md. Set during forge-2-tech or manually (null until then). Examples: 'typescript', 'python', 'go', 'rust'."
+    },
+    "typeCheckCommand": {
+      "type": ["string", "null"],
+      "description": "Command to verify type correctness or lint. Null until set. Examples: 'bun run typecheck', 'mypy .', 'go vet ./...'. Used in acceptance criteria and verification."
+    },
+    "testCommand": {
+      "type": ["string", "null"],
+      "description": "Command to run tests. Null until set. Examples: 'bun test', 'pytest', 'go test ./...'. Used in acceptance criteria and verification."
+    },
+    "smokeCommand": {
+      "type": ["string", "null"],
+      "default": null,
+      "description": "Optional end-to-end smoke command that boots the wired application entrypoint and drives one happy-path request, exiting 0 on success. DISTINCT from testCommand (unit tests, which may self-bootstrap) and loopRunner.runCommand (the loop launcher). Consumed by impl-verify's runnability check (CHECK-I21): when set it is executed (pass iff exit 0); when null the check degrades to an advisory not-applicable finding, never a hard fail (mirrors how a null typeCheckCommand is treated). Examples: 'npm run smoke', './scripts/smoke.sh', 'curl -fsS localhost:3000/health'."
+    },
+    "loopIterationMultiplier": {
+      "type": "number",
+      "default": 1.5,
+      "minimum": 1,
+      "description": "Multiplier applied to pending backlog item count to calculate loop iterations. Higher values allow more retries. Default: 1.5 (e.g., 10 items = 15 iterations)."
+    },
+    "autoInvokeNextStage": {
+      "type": "boolean",
+      "default": true,
+      "description": "When true (default), the /feature-forge:forge navigator auto-invokes the next pipeline stage via the Skill tool after the user confirms it, instead of only printing the command to copy. Set false to keep the old copy-paste behavior (the navigator suggests the command but never launches it). Ignored on non-Claude hosts, which always fall back to printing the command."
+    },
+    "autoVerify": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, the /feature-forge:forge navigator automatically runs forge-verify after a stage completes, with no prompt. forge-verify runs in a fresh forge-verifier subagent (clean-room), so it never needs a context clear and costs the current session only a compact findings digest. Default false preserves today's manual-gate behavior. Ignored on non-Claude hosts, which always fall back to printing the verify command. Per-stage overrides in autoVerifyStages take precedence."
+    },
+    "autoVerifyStages": {
+      "type": "object",
+      "default": {},
+      "description": "Per-stage overrides for autoVerify. Maps a production stage id to a boolean; the effective value for a stage is autoVerifyStages[stage] if present, else autoVerify. Keys are constrained to the five verify-capable stages so a typo (e.g. 'forge-1-prod') is a schema error, not a silent no-op. forge-6-docs has no verify step and is not a valid key.",
+      "propertyNames": {
+        "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog", "forge-5-loop"]
+      },
+      "additionalProperties": {
+        "type": "boolean"
+      }
+    },
+    "autoFix": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, the navigator chains forge-fix automatically after an auto-verify that finds issues. Honored ONLY when auto-verify is effectively on for the stage, and ONLY when preconditions hold (findings doc has zero unresolved decision points, working tree is clean, and a mandatory re-verify passes) — otherwise it falls back to surfacing the findings digest and prompting. Default false keeps fixing human-gated."
+    },
+    "contextWindowTokens": {
+      "type": ["integer", "null"],
+      "default": null,
+      "description": "Context window size (tokens) used by the navigator's context-usage check to compute how full the current session is. Null (default) lets the helper infer from the session model and fall back to 200000 — and if observed usage already exceeds 200000 it auto-bumps the assumed window to 1000000 (proof a 1M-beta window is active). Set this explicitly to your model's window (e.g. 1000000 for a 1M-context model) for accurate percentages below 200000 too, since 1M cannot be detected from the transcript until usage crosses 200000."
+    },
+    "contextWarnThreshold": {
+      "type": "number",
+      "default": 0.7,
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Fraction of the context window (0-1) past which the navigator recommends starting the next stage in a clean session rather than continuing. Default: 0.7."
+    },
+    "workspaces": {
+      "type": "array",
+      "description": "Monorepo members. Absent for single-package projects.",
+      "items": {
+        "type": "object",
+        "required": ["name", "path", "stack"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {"type": "string"},
+          "path": {"type": "string", "description": "Repo-relative member dir"},
+          "stack": {"type": "string"},
+          "typeCheckCommand": {"type": ["string", "null"]},
+          "testCommand": {"type": ["string", "null"]}
+        }
+      }
+    },
+    "loopRunner": {
+      "type": "object",
+      "description": "The autonomous loop runner feature-forge drives. Defaults to rauf when absent (forge-5 states 'defaulting to rauf loop runner'). Every command is a template — {bin}, {backlogDir}, {specsDir}, {iterations} are substituted at call time — so an alternative ralph-style runner conforming to rauf's SPEC-BACKLOG-TOOL-CONTRACT.md can be swapped in without editing any skill. See references/ralph-loop-contract.md.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "default": "rauf",
+          "description": "Display name of the loop runner."
+        },
+        "bin": {
+          "type": "string",
+          "default": "rauf",
+          "description": "The runner executable. Assumed on PATH; may be an absolute path. Substituted as {bin} in every command."
+        },
+        "runCommand": {
+          "type": "string",
+          "default": "{bin} loop run . --backlog {backlogDir} --iterations {iterations}",
+          "description": "Run the loop. Launched in the background by forge-5. Human-formatted output; used as the fallback launch command when eventStreamCommand is absent."
+        },
+        "eventStreamCommand": {
+          "type": "string",
+          "default": "{bin} loop run . --backlog {backlogDir} --iterations {iterations} --ndjson",
+          "description": "Stdout NDJSON launch command for a runner that does NOT persist its own event file — same as runCommand but emits one machine-readable JSON event per stdout line: item_completed / item_blocked / needs_human / signal_parsed / loop_completed / loop_error / loop_cancelled / llm_stuck_warning, each with {type, timestamp, projectPath} plus payload (a circuit-breaker halt surfaces as loop_error). NOTE: rauf (the default runner) ALREADY persists {stateDir}/events.ndjson natively and rotates it per run, so forge-5 launches the plain runCommand and monitors that native file — it does NOT use this field, and must NOT redirect --ndjson into {stateDir} (redundant, and it collides with the runner's own writer / archive rotation). This field is only for a stdout-only runner with no native event file; forge-5 then redirects its stdout to a file OUTSIDE {stateDir} and monitors that. Omit it entirely for a runner that self-persists or cannot emit NDJSON."
+        },
+        "validateCommand": {
+          "type": "string",
+          "default": "{bin} backlog validate . --backlog {backlogDir} --specs-dir {specsDir} --json",
+          "description": "Validate a backlog. MUST exit 0=valid, 1=findings, 2=usage/IO, and emit { valid, findings[] } with --json. `specReferences` are project-root-relative (resolved against the project root); `--specs-dir` only gates the existence check, so passing the specs root ({specsDir}) is sufficient."
+        },
+        "statusCommand": {
+          "type": "string",
+          "default": "{bin} status . --backlog {backlogDir}",
+          "description": "One-shot loop status, human-formatted. Shown to the user as a monitoring hint."
+        },
+        "statusJsonCommand": {
+          "type": "string",
+          "default": "{bin} status . --backlog {backlogDir} --json",
+          "description": "Machine-readable derived status used by forge-5 for milestone tallies and the final summary. Emits { loopState, iteration, maxIterations, currentItem, lastSignal, backlogSummary{pending,inProgress,blocked,needsHuman,deferred,done,total}, lock{...} }. Distinguishes the three non-done outcomes (genuine blocked vs needsHuman vs runner-deferred 'false blocks')."
+        },
+        "listCommand": {
+          "type": "string",
+          "default": "{bin} backlog list . --backlog {backlogDir} --json",
+          "description": "List backlog items as JSON."
+        },
+        "followCommand": {
+          "type": "string",
+          "default": "{bin} follow . --backlog {backlogDir}",
+          "description": "Stream live loop events, HUMAN-formatted (pretty-printed / log tail) — for a person watching in another terminal, NOT a machine-readable surface. forge-5 supervises via eventStreamCommand (NDJSON) instead."
+        },
+        "logCommand": {
+          "type": "string",
+          "default": "{bin} log . --backlog {backlogDir} --follow",
+          "description": "Tail the runner log, human-formatted. Monitoring hint for the user."
+        },
+        "watchCommand": {
+          "type": "string",
+          "default": "{bin} status . --backlog {backlogDir} --json",
+          "description": "Machine-readable status used by forge-5 for stall detection. rauf's `loop watch` verb was removed in v0.5.0, so this now points at `status --json`; forge-5 keys off the iteration-status `stuckWarning` flag (read from `status --json` / `iteration-status.json`) rather than guessing liveness from state.json timestamps."
+        },
+        "versionCommand": {
+          "type": "string",
+          "default": "{bin} version --json",
+          "description": "Report runner version as { version: <semver> }. Used to enforce minRunnerVersion before running."
+        },
+        "agentArgument": {
+          "type": "string",
+          "default": "--agent {agent}",
+          "description": "Tokenized argument appended to the launch command (eventStreamCommand/runCommand) when forge resolves a non-default coding agent for the run. {agent} is substituted ONLY with a validated, advertised agent id (a member of the set agentsProbeCommand reports). PRESENCE of this field advertises the runner's agent surface: when present and non-empty, forge-5 offers the per-run agent selector, honors defaultAgent, and may run agentsProbeCommand; OMIT it for a runner with no agent dimension and forge skips agent selection entirely — no selector, no probe, no {agent} substitution, no agent argument sent (byte-identical to today). Distinct from the version gate (minRunnerVersion)."
+        },
+        "agentsProbeCommand": {
+          "type": "string",
+          "default": "{bin} agents --json",
+          "description": "Coding-agent availability probe. MUST emit { agents: [{ id, displayName, available, ... }] } and exit 0 (it always exits 0: an unknown id simply never appears; a known-unavailable one appears with available:false). forge-5 runs it ONCE (no retries) before launching a non-default agent to (a) validate the resolved id against the advertised id set and (b) report availability in the pre-launch confirmation. Ignored on the default path and when agentArgument is absent."
+        },
+        "defaultAgent": {
+          "type": "string",
+          "default": "",
+          "description": "Project-default coding agent id, so a project can fix its agent once without specifying it every run. Empty string ⇒ no project default (the runner's own default — claude-cli for rauf — applies, behaving exactly as today). Overridden by the per-run agent selector (run > project precedence, resolved inside forge before the single --agent is emitted). Ignored when agentArgument is absent."
+        },
+        "preconditionFile": {
+          "type": "string",
+          "default": ".rauf.json",
+          "description": "Project-root marker file that must exist (runner installed into the target project)."
+        },
+        "stateDir": {
+          "type": "string",
+          "default": ".rauf",
+          "description": "Per-backlog state directory name created under the backlog dir."
+        },
+        "logFile": {
+          "type": "string",
+          "default": "rauf.log",
+          "description": "Human-readable event log filename written under {stateDir}. Substituted as {loopRunner.logFile} in the log-tail fallback Monitor command when eventStreamCommand (events.ndjson) is unavailable. The structured NDJSON path uses the contract-standard name events.ndjson and is not configurable here."
+        },
+        "setupHint": {
+          "type": "string",
+          "default": "Run `rauf install .` to install rauf's per-project artifacts (.rauf/, RAUF.md, schema), then re-run forge-5.",
+          "description": "Shown when preconditionFile is missing — how to set up the runner IN THIS PROJECT (per-project artifacts)."
+        },
+        "installHint": {
+          "type": "string",
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.12.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.12.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
+          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.12.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
+        },
+        "schemaVersion": {
+          "type": "string",
+          "default": "1",
+          "description": "Backlog schemaVersion this runner config targets."
+        },
+        "minRunnerVersion": {
+          "type": "string",
+          "default": "0.6.0",
+          "description": "Minimum runner version (semver). 0.6.0 is the AGENT-SURFACE FLOOR: the rauf version that ships the coding-agent selection surface (the --agent flag, the `agents` availability probe, and the preset agent registry) that this config's agentArgument/agentsProbeCommand consume. Flooring here guarantees a successful gate implies those surfaces exist. (0.5.0 was the prior grammar/contract-flip floor — unified exit codes, `loop run --detached`, explicit `review` signal, versioned events.ndjson — which predates the agent surface and so could not guarantee it.) forge-5 enforces this via versionCommand before any loop side-effects."
+        }
+      }
+    }
+  }
+}