@garygentry/feature-forge 0.2.2 → 0.2.4

package/adapters/cursor/references/forge-config-schema.json

@@ -16,7 +16,8 @@
     },
     "backlogDir": {
       "type": ["string", "null"],
-      "description": "Optional override for backlog location. If set, backlog.json is written here instead of with the feature specs. Default behavior (null): backlog.json is written to {specsDir}/{feature}/backlog.json."
+      "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",
@@ -56,6 +57,44 @@
       "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.",
@@ -94,7 +133,7 @@
         "eventStreamCommand": {
           "type": "string",
           "default": "{bin} loop run . --backlog {backlogDir} --iterations {iterations} --ndjson",
-          "description": "PREFERRED launch command for forge-5. Same as runCommand but emits one machine-readable JSON event per stdout line (NDJSON): 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). forge-5 redirects this stdout to {backlogDir}/{stateDir}/events.ndjson and arms a Monitor on it for live, structured supervision. If a runner cannot emit NDJSON, omit this field — forge-5 falls back to runCommand + tailing the human log."
+          "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",
@@ -173,8 +212,8 @@
         },
         "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.10.1 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.10.1 --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.10.1), 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."
+          "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",

package/adapters/cursor/references/pipeline-state-schema.json

@@ -80,7 +80,7 @@
         "completedAt": { "type": ["string", "null"], "format": "date-time" },
         "commitHash": {
           "type": ["string", "null"],
-          "description": "Git commit SHA after this stage completed"
+          "description": "Git commit SHA of this stage's artifact commit (Commit 1 of the two-commit Git Commit Protocol in shared-conventions.md). Written by a small follow-up commit so it points at the artifact commit itself, never at an orphaned amend or the hash-recording commit. null until recorded (or when there was no new artifact commit)."
         },
         "basedOnVersions": {
           "type": "object",
@@ -107,7 +107,8 @@
         },
         "verifiedAt": { "type": ["string", "null"], "format": "date-time" },
         "fixedAt": { "type": ["string", "null"], "format": "date-time" },
-        "commitHash": { "type": ["string", "null"] }
+        "commitHash": { "type": ["string", "null"], "description": "Git commit SHA of the verify/fix artifact commit. Recorded via the two-commit Git Commit Protocol (shared-conventions.md) so it points at the artifact commit, never an orphaned amend." },
+        "verifiedStageVersion": { "type": ["integer", "null"], "description": "The production stage's `version` at the moment this verify was resolved. The navigator's freshness ledger compares it to the stage's current `version`: equal means the verify is fresh; a mismatch (artifact revised since) or an absent field (legacy state) means stale, so auto-verify re-fires. Recorded by forge-verify/forge-fix when writing a passed/findings-applied status." }
       }
     }
   }

package/adapters/cursor/references/portable-root.md

@@ -12,7 +12,7 @@ against the fenced block here, byte-for-byte.
 ## Canonical bootstrap prelude
 
 ```bash
-R="$(for d in "$HOME"/.claude/skills/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 'for d in "$HOME"/.claude/skills/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; }
 ```
 
@@ -24,7 +24,7 @@ makes several calls, add the prelude once and reuse `$R` for each. A fresh block
 prelude (per-block re-resolution). Worked example:
 
 ```bash
-R="$(for d in "$HOME"/.claude/skills/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 'for d in "$HOME"/.claude/skills/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/epic-manifest.py" render-status "{epic}" --specs-dir "{specsDir}" --json
 ```

package/adapters/cursor/references/process-overview.md

@@ -36,6 +36,16 @@ The pipeline compiles a fuzzy feature idea into a machine-executable `backlog.js
 **Output:** `{specsDir}/{feature}/.verification/VERIFY-<stage>-<timestamp>.md` (includes both findings and a Fix Execution Plan)
 **Method:** Clean-context analysis producing actionable findings with an ordered fix plan.
 
+**Manual or automatic.** By default the navigator offers verification after each stage. Because
+it runs in a fresh, read-only subagent (clean-room by construction, never needs a `/clear`), it is
+safe to automate: set `autoVerify: true` (or per-stage via `autoVerifyStages`) in
+`forge.config.json` and the navigator runs `forge-verify` automatically once a stage completes,
+returning only a compact digest to the session. The freshness ledger (verify entries record the
+artifact `version` they ran against) means a stage is re-verified only when its artifact changes,
+and an explicitly `skipped` verify is respected. Fixing stays human-gated unless `autoFix: true` is
+also set, which chains `forge-fix` only when preconditions hold (zero unresolved decisions, clean
+tree, passing re-verify). See `references/shared-conventions.md` for the config keys.
+
 After verification, fixes can be applied via:
 - `/feature-forge:forge-fix <feature>` — reads the Fix Execution Plan from the findings document and applies changes (works in any session)
 - Plan mode workflow — enter plan mode, run verify, review plan, exit and execute

package/adapters/cursor/references/shared-conventions.md

@@ -68,6 +68,12 @@ Extract these config values (use defaults if not present):
 - `branchPerFeature` (default: true)
 - `branchPrefix` (default: `forge/`)
 - `loopIterationMultiplier` (default: `1.5`)
+- `autoInvokeNextStage` (default: `true` — the `/feature-forge:forge` navigator auto-invokes the next stage via the `Skill` tool after the user confirms; `false` keeps copy-paste behavior. Navigator-only.)
+- `contextWindowTokens` (default: `null` — context window used by the navigator's context-usage check; `null` infers from the session model and falls back to 200000. Set to the model's window, e.g. `1000000` on a 1M model. Navigator-only.)
+- `contextWarnThreshold` (default: `0.7` — fraction of the window past which the navigator recommends a clean session. Navigator-only.)
+- `autoVerify` (default: `false` — when `true`, the navigator auto-runs `forge-verify` after a stage completes, no prompt; runs in a fresh clean-room subagent so it never needs a `/clear` and costs only a compact digest. Navigator-only.)
+- `autoVerifyStages` (default: `{}` — per-stage overrides for `autoVerify`, e.g. `{"forge-1-prd": false}`. Effective value = `autoVerifyStages[stage]` if present, else `autoVerify`. Keys are constrained to the five verify-capable stages; a typo is a config error surfaced as `invalidAutoVerifyKeys`. Navigator-only.)
+- `autoFix` (default: `false` — when `true`, the navigator chains `forge-fix` after an auto-verify that finds issues, but only when auto-verify is on for that stage AND preconditions hold (zero unresolved decisions, clean tree, passing re-verify); otherwise it surfaces a digest and prompts. Navigator-only.)
 - `loopRunner` (optional object — the loop runner to drive; **defaults to rauf** when absent, with every command templated. See `references/forge-config-schema.json` and `references/ralph-loop-contract.md`.)
 
 ## Feature Directory Resolution
@@ -75,7 +81,7 @@ Extract these config values (use defaults if not present):
 Before any file I/O against a feature's artifacts, resolve its directory through the deterministic helper rather than hardcoding `{specsDir}/{feature}/`. This makes flat (`{specsDir}/{feature}/`) and nested (`{specsDir}/{epic}/{feature}/`) layouts both resolve from a bare feature name (REQ-DIR-03), with standalone features behaving exactly as today.
 
 ```bash
-R="$(for d in "$HOME"/.claude/skills/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 'for d in "$HOME"/.claude/skills/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; }
 resolvedFeatureDir=$(python3 "$R/scripts/epic-manifest.py" \
   resolve "<feature>" --specs-dir "<specsDir>")
@@ -105,7 +111,7 @@ Whenever a stage creates the specs tree for the first time (the first PRD or epi
 Run this after creating the feature/epic directory, before the stage's git commit:
 
 ```bash
-R="$(for d in "$HOME"/.claude/skills/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 'for d in "$HOME"/.claude/skills/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; }
 mkdir -p "<specsDir>"
 [ -f "<specsDir>/AGENTS.md" ] || cp "$R/references/templates/specs-hygiene/AGENTS.md" "<specsDir>/AGENTS.md"
@@ -132,7 +138,7 @@ After resolving the feature directory, check the feature's `.pipeline-state.json
 To obtain the manifest contracts and the live completion status of each dependency in one deterministic call, run `render-status` and read the per-feature `status` and the `consumes`/`exposes` arrays rather than re-deriving them:
 
 ```bash
-R="$(for d in "$HOME"/.claude/skills/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 'for d in "$HOME"/.claude/skills/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/epic-manifest.py" \
   render-status "<epic>" --specs-dir "<specsDir>" --json
@@ -177,16 +183,18 @@ Invoke this block at the **very start** of a pipeline entry point — `forge-1-p
 
 ## Git Commit Protocol
 
-When `gitCommitAfterStage` is true, follow this exact order to avoid state inconsistency:
+When `gitCommitAfterStage` is true, follow this exact order to avoid state inconsistency.
+
+**Why two commits.** The stage's `.pipeline-state.json` is itself part of the staged commit, but the stage's `commitHash` cannot be known until *after* that commit is made. Recording it *inside* the same commit is a chicken-and-egg with no single-commit solution. Resolve it with a **deterministic two-commit sequence**, and **never** with `git commit --amend`: amending rewrites HEAD, so a hash captured before the amend points at an orphaned commit that is not in the final history (the exact defect this protocol exists to prevent).
 
 1. **Stage specific files only:** `git add {specsDir}/{feature}/` — never use `git add -A` or `git add .`
-2. **Attempt commit:** `git commit -m "{commitPrefix}({feature}): <action>"`
-3. **If commit succeeds:** capture the commit hash, then update pipeline state with `status: "complete"` and the `commitHash`
-4. **If commit fails:** do NOT update pipeline state to complete. Report the error to the user and leave state as `in-progress` so the stage can be resumed. Common failure causes:
+2. **Commit 1 — artifacts + state, hash not yet known:** In `.pipeline-state.json`, set this stage's `status: "complete"` and `commitHash: null`, then `git commit -m "{commitPrefix}({feature}): <action>"`. This is the stage's **artifact commit**; its hash is the provenance hash callers rely on.
+3. **If Commit 1 succeeds — Commit 2 records the hash:** Capture the hash of Commit 1 (`git rev-parse HEAD`). Write it into this stage's `commitHash` in `.pipeline-state.json`, then commit only that one-line change: `git add {specsDir}/{feature}/.pipeline-state.json && git commit -m "{commitPrefix}({feature}): record stage commit hash"`. The stored `commitHash` now points at the artifact commit (Commit 1) — never at Commit 2, and never at an orphaned amend. The working tree is clean afterward, so the next stage's dirty-tree check passes.
+4. **If Commit 1 fails:** do NOT update pipeline state to complete. Report the error to the user and leave state as `in-progress` so the stage can be resumed. Common failure causes:
    - **Pre-commit hook failure:** Report the hook output. Never use `--no-verify` to bypass. Help the user fix the underlying issue.
    - **Merge conflicts:** Report conflicting files. Suggest resolution steps appropriate to the conflict.
-   - **Nothing to commit:** If all artifacts were already committed, this is fine — proceed with state update but note the absence of a new commit hash.
-5. **Never** use `git add -A`, `--no-verify`, or `--force` flags
+   - **Nothing to commit:** If all artifacts were already committed, this is fine — mark the stage `complete`, leave `commitHash` at its existing value (or `null` if there was never an artifact commit), and skip Commit 2. There is no new artifact commit to record.
+5. **Never** use `git add -A`, `--amend`, `--no-verify`, or `--force` flags
 
 ## Crash Recovery
 

package/adapters/cursor/references/stage-exit-protocol.md

@@ -0,0 +1,99 @@
+# 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 block 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.** 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. Clearing first throws that
+   context away.
+
+## How this file is used
+
+The blocks below are **stamped verbatim** into each stage skill's closing (a runtime
+`references/` include would not survive the adapter build, which flattens skills into
+`adapters/<agent>/`). 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).
+
+Each stamp site fills three slots; everything else is identical across sites:
+
+- `{stage}` — the just-completed stage as a lowercase noun phrase (e.g. `the PRD`,
+  `the tech spec`, `the backlog`). Always used mid-sentence, never sentence-initial.
+- `{verify-command}` — the verify command for that stage (e.g.
+  `` `/feature-forge:forge-verify {feature}` ``).
+- `{next-command}` — the command that starts the next stage (e.g.
+  `` `/feature-forge:forge-2-tech {feature}` ``).
+
+`{feature}` / `{epic}` and similar remain runtime placeholders that pass through
+untouched — they are resolved by the skill at run time, not by this template.
+
+## Stamp sites
+
+| Stamp site | Block | `{stage}` |
+|---|---|---|
+| `forge-0-epic` (epic → first PRD) | standard | the epic decomposition |
+| `forge-1-prd` | standard | the PRD |
+| `forge-2-tech` | standard | the tech spec |
+| `forge-3-specs` | standard | the implementation specs |
+| `forge-4-backlog` | standard | the backlog |
+| `forge-5-loop` (step-6 epic-member handoff) | standard | feature `{feature}`'s loop |
+| `forge-5-loop` (all-done closing → docs) | warm | — |
+
+`forge-6-docs` is **terminal** — it stamps no exit block. It is the *target* of the
+warm variant, not a stamp site.
+
+---
+
+## Standard block
+
+Stamp this at every authoring-stage boundary. 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.
+
+<!-- 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.** When this stage has no fresh verification on record (`verifyState` is **missing or stale**) **and** `autoVerify` is off for it, verify **now, before clearing**. If verify already ran, is pending under auto-verify, or the stage was explicitly skipped, say so and go straight to step 2. Present the **Standard Verify Gate** 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 `{next-command}`** in the fresh session — or re-run `/feature-forge:forge` to let the navigator resume from disk.
+<!-- 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 `{next-command}`** — in this warm session, or a fresh one if you prefer.
+<!-- END: warm-exit-block -->

package/adapters/cursor/scripts/epic-manifest.py

@@ -312,6 +312,16 @@ def atomic_write(path: Path, data: dict) -> None:
             handle.flush()
             os.fsync(handle.fileno())
         os.replace(tmp_path, path)
+        # fsync the parent dir so the rename itself is durable on crash, not just
+        # the file bytes (best-effort — some filesystems reject O_RDONLY dir fsync).
+        try:
+            dir_fd = os.open(parent, os.O_RDONLY)
+            try:
+                os.fsync(dir_fd)
+            finally:
+                os.close(dir_fd)
+        except OSError:
+            pass
     except OSError as exc:
         tmp_path.unlink(missing_ok=True)
         raise UsageError(f"atomic write to {path} failed: {exc}")

package/adapters/cursor/scripts/forge-bootstrap.py

@@ -26,6 +26,8 @@ import argparse
 import json
 import os
 import re
+import shlex
+import shutil
 import subprocess
 import sys
 import tempfile
@@ -281,6 +283,32 @@ def _json_text(obj: object) -> str:
     return json.dumps(obj, indent=2, ensure_ascii=False) + "\n"
 
 
+def contained_path(base: Path, *parts: str) -> Path:
+    """Join ``parts`` onto ``base`` and assert the result stays within ``base``.
+
+    Ports epic-manifest.py's ``contained_path`` guard: canonicalizes (symlink-
+    resolves) both ends and verifies containment so no scaffold write or verify
+    cwd can escape the target repo — defense in depth behind ``_validate_answers``
+    should a crafted member path slip through. Containment violations surface only
+    as exit-2 usage errors.
+
+    Args:
+        base: The containing directory (the target repo root), already known to exist.
+        *parts: Repo-relative segments to append (member path, artifact rel path).
+
+    Returns:
+        The resolved, contained absolute path.
+
+    Raises:
+        UsageError: If the resolved path escapes ``base`` (exit 2).
+    """
+    base_real = base.resolve()
+    resolved = (base_real / Path(*parts)).resolve()
+    if resolved != base_real and base_real not in resolved.parents:
+        raise UsageError(f"path escapes target dir: {os.path.join(*parts)}")
+    return resolved
+
+
 def _atomic_write_text(path: Path, text: str) -> None:
     """Write ``text`` to ``path`` atomically via a same-dir temp file + os.replace.
 
@@ -381,7 +409,7 @@ def run(
 
 
 # --------------------------------------------------------------------------- #
-# Subcommand stubs (filled by later backlog items 003/006/008/009/010)
+# Subcommands: check / scaffold / verify / commit / status (02 §8.2)
 # --------------------------------------------------------------------------- #
 
 
@@ -476,6 +504,7 @@ def _write_artifact(
     """
     if rel_path in sentinel["artifactsWritten"]:
         return
+    contained_path(target, rel_path)  # never write outside the target repo (exit 2)
     dest = target / rel_path
     if dest.exists():
         return
@@ -529,7 +558,7 @@ def _resolve_commands(member: Member) -> tuple[str, str]:
 
 
 def write_config(answers: Answers, target: Path, sentinel: Sentinel) -> None:
-    """Write forge.config.json equivalent to forge-init's output (02 §4.3, 00 §7)."""
+    """Write forge.config.json == forge-init's field set + loopRunner (02 §4.3, 00 §7)."""
     config: dict = {
         "specsDir": "./specs",
         "docsDir": "./docs/architecture",
@@ -540,6 +569,14 @@ def write_config(answers: Answers, target: Path, sentinel: Sentinel) -> None:
         "typeCheckCommand": None,
         "testCommand": None,
         "loopIterationMultiplier": 1.5,
+        # Navigator keys — kept in lockstep with forge-init.sh's emitted field set
+        # (00 §7, REQ-CFG-02) so a bootstrapped config == forge-init's + loopRunner.
+        "autoInvokeNextStage": True,
+        "contextWindowTokens": None,
+        "contextWarnThreshold": 0.7,
+        "autoVerify": False,
+        "autoVerifyStages": {},
+        "autoFix": False,
         "loopRunner": {"name": "rauf", "bin": "rauf"},
     }
     if answers["layout"] == "single":
@@ -697,9 +734,9 @@ def scaffold(target: Path, answers: Answers) -> list[str]:
 def toolchain_present(required: list[str]) -> bool:
     """Return True iff every required tool is on PATH (REQ-LIFE-03).
 
-    Probes each binary with ``command -v`` via the run wrapper (a shell builtin,
-    invoked through ``sh -c``). A single missing tool yields False, driving the
-    distinct missing-toolchain outcome (exit 2, 00 §9): the skill then offers
+    Probes each binary with :func:`shutil.which` (a pure PATH lookup, no shell
+    spawned). A single missing tool yields False, driving the distinct
+    missing-toolchain outcome (exit 2, 00 §9): the skill then offers
     scaffold-anyway-unverified vs abort and marks the baseline unverified
     (REQ-LIFE-04). Bootstrap NEVER installs a toolchain (tech-spec §9).
 
@@ -708,17 +745,10 @@ def toolchain_present(required: list[str]) -> bool:
             already {pm}-substituted.
 
     Returns:
-        True iff ``command -v`` succeeds for every entry.
+        True iff every entry resolves on PATH.
     """
     for tool in required:
-        try:
-            proc = run(["sh", "-c", f"command -v {tool}"], cwd=Path.cwd(), check=False)
-        except UsageError:
-            # The probe itself could not be launched (e.g. an empty PATH leaves no
-            # `sh`): treat that as the tool being absent, the missing-toolchain
-            # outcome, never an internal error (REQ-LIFE-03/04).
-            return False
-        if proc.returncode != 0:
+        if shutil.which(tool) is None:
             return False
     return True
 
@@ -763,9 +793,11 @@ def verify(target: Path, answers: Answers) -> VerifyResult:
     test: list[CommandOutcome] = []
     for member in answers["members"]:
         lint_cmd, test_cmd = _resolve_commands(member)
-        cwd = target / member["path"]
+        cwd = contained_path(target, member["path"])  # never run outside the target
         for bucket, cmd in ((lint, lint_cmd), (test, test_cmd)):
-            proc = run(["sh", "-c", cmd], cwd=cwd, check=False)
+            # STACK_COMMANDS templates with an allow-listed {pm} (see _validate_answers)
+            # — split into an argv token list and run without a shell (no `sh -c`).
+            proc = run(shlex.split(cmd), cwd=cwd, check=False)
             bucket.append(
                 {"command": cmd, "ok": proc.returncode == 0, "member": member["path"]}
             )
@@ -867,9 +899,55 @@ def _parse_answers(raw: str) -> Answers:
         raise UsageError(f"malformed --answers JSON: {exc}")
     if not isinstance(parsed, dict):
         raise UsageError("--answers must be a JSON object")
+    _validate_answers(parsed)
     return parsed
 
 
+def _validate_answers(answers: Answers) -> None:
+    """Reject non-allowlisted stack/packageManager and unsafe member paths (exit 2).
+
+    Runs before any ``{pm}`` substitution, ``STACK_COMMANDS[...]`` subscript, or
+    artifact write so a malformed ``--answers`` payload fails with a stderr
+    diagnostic, never a KeyError traceback or a path escape. Mirrors the
+    input-validation rigor epic-manifest.py applies via ``assert_safe_name`` /
+    ``contained_path``:
+
+    - ``stack`` must be a known :data:`Stack` (a ``STACK_COMMANDS`` key).
+    - ``packageManager`` must be in ``PACKAGE_MANAGERS[stack]`` for a stack that
+      has a choice; stacks with no choice (go/rust/generic) must leave it ``None``.
+    - ``path`` must be a repo-relative string — no absolute path, no ``..``
+      component, no backslash — so it can never resolve outside the target.
+    """
+    members = answers.get("members")
+    if not isinstance(members, list) or not members:
+        raise UsageError("--answers must include a non-empty members[] array")
+    for member in members:
+        stack = member.get("stack")
+        if stack not in STACK_COMMANDS:
+            raise UsageError(
+                f"unknown stack {stack!r}: expected one of {sorted(STACK_COMMANDS)}"
+            )
+        pm = member.get("packageManager")
+        choices = PACKAGE_MANAGERS.get(stack)
+        if choices is not None:
+            if pm not in choices:
+                raise UsageError(
+                    f"invalid packageManager {pm!r} for stack {stack!r}: "
+                    f"expected one of {choices}"
+                )
+        elif pm is not None:
+            raise UsageError(
+                f"stack {stack!r} takes no packageManager, got {pm!r}"
+            )
+        path = member.get("path")
+        if not isinstance(path, str) or not path:
+            raise UsageError(f"member path must be a non-empty string, got {path!r}")
+        if os.path.isabs(path) or "\\" in path or ".." in Path(path).parts:
+            raise UsageError(
+                f"unsafe member path {path!r}: must be repo-relative with no '..'"
+            )
+
+
 def _dispatch(args: argparse.Namespace, target: Path) -> int:
     """Route a parsed command to its handler, translating outcomes into exit codes.
 

package/adapters/cursor/scripts/forge-init.sh

@@ -21,7 +21,13 @@ cat > "$CONFIG_FILE" << 'EOF'
   "stack": null,
   "typeCheckCommand": null,
   "testCommand": null,
-  "loopIterationMultiplier": 1.5
+  "loopIterationMultiplier": 1.5,
+  "autoInvokeNextStage": true,
+  "contextWindowTokens": null,
+  "contextWarnThreshold": 0.7,
+  "autoVerify": false,
+  "autoVerifyStages": {},
+  "autoFix": false
 }
 EOF
 
@@ -37,6 +43,12 @@ echo "  stack:               null (auto-detected during forge-2-tech)"
 echo "  typeCheckCommand:    null (auto-detected during forge-2-tech)"
 echo "  testCommand:         null (auto-detected during forge-2-tech)"
 echo "  loopIterationMultiplier: 1.5 (multiplier for loop iterations)"
+echo "  autoInvokeNextStage: true (navigator auto-starts the next stage after you confirm)"
+echo "  contextWindowTokens: null (infer; set to 1000000 on a 1M-context model)"
+echo "  contextWarnThreshold: 0.7 (suggest a clean session past this fraction of the window)"
+echo "  autoVerify:          false (set true to run forge-verify automatically after each stage)"
+echo "  autoVerifyStages:    {} (per-stage overrides for autoVerify)"
+echo "  autoFix:             false (set true to chain forge-fix after an auto-verify finds issues)"
 echo ""
 echo "The loop runner defaults to rauf. To target a different ralph-style runner,"
 echo "add a \"loopRunner\" block (see references/forge-config-schema.json)."