@garygentry/feature-forge 0.3.0 → 0.3.2

package/adapters/gemini/skills/forge-5-loop/references/runner-contract.md

@@ -2,8 +2,10 @@
 
 This file holds the detailed loop-runner contract relocated out of
 `forge-5-loop/SKILL.md`: the event-stream vs. log-fallback **launch** detail
-(Steps 3b/3d/3e), the structured-surface **monitoring** caveats, the **model
-precedence** rule, and the **optional-flags catalog** referenced from Step 2d.
+(Steps 3b/3d/3e), the structured-surface **monitoring** caveats, and the **model
+precedence** rule. The agent-selection surface, its Claude-only model-alias guard,
+and the optional-flags catalog live in `references/agent-selection.md`, which is
+read **only** when the Step 2d `loopRunner.agentArgument` capability gate is on.
 Every command below is rendered from `loopRunner` with token substitution, as in
 the skill body.
 
@@ -17,97 +19,10 @@ item.model  >  --model / options  >  project default  >  provider default
 
 So a backlog item's own `model` field overrides a `--model` flag passed to the
 run, which overrides the project's configured default, which overrides the
-runner/provider default. Pass `--model <model>` (optional flag below) to override
-the project default for the whole run.
-
-## Agent selection (Step 2d)
-
-This section is **parallel** to `## Model selection precedence` above: it governs
-which **coding agent** rauf drives for the run. The entire surface is
-**presence-gated** on `loopRunner.agentArgument` — when that field is absent or
-empty, there is no selector, no probe, and no `{agent}` substitution, and Step 2d /
-Step 3c are byte-identical to today (capability gate;
-`02-config-schema-and-gating.md`, REQ-PLUG-02). The rest assumes the gate is on.
-
-**Precedence (highest wins):**
-
-```
-item.provider  >  --agent (run selection)  >  loopRunner.defaultAgent (project)  >  runner default (claude-cli)
-```
-
-**Run-layer mapping — why forge never re-implements rauf's resolver.** forge owns
-**only** its run and project layers and collapses them into **one** value
-(`resolve()`: `run_selection or defaultAgent or none`), which it emits as a single
-`--agent {agent}` occupying rauf's **run layer only**. rauf alone resolves
-item-vs-run via its own 5-layer resolver, sitting the per-item `BacklogItem.provider`
-**above** forge's run layer — so a run selection can never clobber a deliberate
-per-item agent. forge **never reads, writes, or overrides** `BacklogItem.provider`
-(REQ-AGENT-05). When forge sends nothing (the default path), rauf applies its own
-default `claude-cli`, byte-identical to today. Empty/whitespace selections are
-treated as unset, and an explicit pick of the runner default id collapses to the
-default path (append nothing, run no probe). See
-`03-selection-resolution-observability.md §3–§4`.
-
-**Availability pre-check + disambiguation.** For a **non-default** resolved id only,
-forge runs `loopRunner.agentsProbeCommand` **once** (no retries) and classifies the
-id by **membership** in the advertised set (`{ row.id for row in agents }`), then the
-matching row's `available` flag — **never** by exit code, because `rauf agents
---json` always exits 0 (an unknown id is simply absent; a known-unavailable one is
-present with `available: false`):
-
-- **UNKNOWN** (`∉` advertised set): hard-reject **before any loop side-effect**,
-  listing the sorted valid ids; **no proceed-anyway**; the value never interpolates
-  into `{agent}` (the advertised set IS the allow-list — REQ-SEC-01).
-- **UNAVAILABLE** (member, `available == False`): warn with the row's `detail`, then
-  offer **proceed-anyway OR choose-another** — never silent.
-- **AVAILABLE** (member, `available == True`): proceed; the validated id fills
-  `{agent}`.
-- **Probe failure** (non-zero exit / unparseable / wrong shape / empty `agents[]` /
-  row missing `id`): surface it and offer **choose-another OR abort**; never launch
-  the non-default agent unvalidated, never silently fall back to the default.
-
-The default / `claude-cli` path runs **no** probe (zero extra cost). See
-`04-availability-precheck.md` for the full pre-check, classification, and allow-list,
-and `02-config-schema-and-gating.md` for the capability gate.
-
-> **Probe false-negative for Claude Code installs (advisory).** `rauf agents` may
-> report `claude-cli` **unavailable** (e.g. *"credentials file not found:
-> ~/.config/claude-code/credentials.json"*) even when a working `claude` CLI
-> authenticates elsewhere — the probe's credential heuristic doesn't cover every
-> install. This is a rauf probe concern, not something forge-5-loop fixes. The
-> **default-agent path skips the probe entirely**, so an ordinary default run is
-> unaffected; only an **explicit** `--agent claude-cli` would be flagged UNAVAILABLE,
-> and the existing **proceed-anyway** path (above) covers it. Do not attempt to
-> patch rauf's probe from here.
-
-### Claude-only model-alias guard (Step 2d, sub-step d-model)
-
-When the resolved agent is **non-default** (not the default / `claude-cli` path),
-forge must guard against a backlog whose items pin **Claude-specific** model aliases.
-forge-4-backlog (via the rauf author-backlog skill) writes Claude tier aliases
-(`opus` / `sonnet`) into each item's `model`. Because rauf's precedence puts
-`item.model` **above** `--agent`, the alias is forwarded verbatim to the selected
-agent; a non-Claude agent (e.g. codex) then 400s — *"The 'sonnet' model is not
-supported when using Codex with a ChatGPT account."* — so **every** spawn exits 1 and
-rauf reports *"Circuit breaker: 3 consecutive infra failures — halting"* with no hint
-of the real cause. forge-5-loop therefore detects Claude-specific `model` aliases in
-the backlog (tier aliases `opus`/`sonnet`/`haiku` or `claude-*` ids) and, before
-launch, **warns** and offers (via `AskUserQuestion`) to **strip `model` for this run**
-(remove the key from each affected item so each spawn uses the agent's own default) or
-**proceed as-is**. forge only ever touches the `model` field — never `provider`. The
-default / `claude-cli` path skips this guard (the aliases are valid there).
-
-> **Follow-up (out of scope here — rauf repo).** The durable fix would be for the
-> rauf `author-backlog` skill to keep `model` **provider-neutral** by default (or to
-> document that writing a tier alias binds the backlog to Claude agents). That lives
-> in the separate rauf plugin/repo, not feature-forge; tracked as a follow-up.
->
-> **Follow-up (out of scope here — rauf repo).** The durable fix for the root/sandbox
-> refusal (see "Root/sandbox env guard" under Step 3b) is for **rauf itself** to honor
-> `IS_SANDBOX` when it launches `claude --dangerously-skip-permissions` as root (or to
-> detect root+flag-refused and emit a clear error instead of an opaque circuit-break).
-> feature-forge's launch-time export is the mitigation; the upstream fix lives in the
-> rauf plugin/repo. Track as a follow-up.
+runner/provider default. Pass `--model <model>` to override the project default for
+the whole run; it is catalogued with the run's other optional flags under
+`## Optional flags catalog (Step 2d, rauf)` in `references/agent-selection.md` —
+read that file only when Step 2d's `loopRunner.agentArgument` capability gate is on.
 
 ## Run mode (Step 2d, rauf)
 
@@ -150,22 +65,6 @@ Notes:
   byte-identical to the pre-review-default behavior. `--review` is a rauf-specific
   flag; a swapped-in runner conforming to the contract need not support it.
 
-## Optional flags catalog (Step 2d, rauf)
-
-These are the optional flags the user may add to the rendered run command. If the
-user requests additional flags, append them to the rendered run command.
-
-```
-  --agent <id>      Coding agent rauf drives this run (see Agent selection below).
-                    Only the runner's advertised ids are valid; an unknown id is
-                    rejected before launch. Shown only when the runner advertises
-                    an agent surface (loopRunner.agentArgument present).
-  --review          Run a review pass after all iterations (extra agent session)
-  --model <model>   Override the model (see precedence above)
-  --timeout <min>   Per-session timeout in minutes (default: 60)
-  --retry-blocked   Unblock and retry previously blocked items
-```
-
 ## Launch detail (Step 3b — background process)
 
 Launch the loop **backgrounded** so it survives session end and does not block the
@@ -299,6 +198,16 @@ high and the noise low:
 
 ## Inform-user output template (Step 3c)
 
+Step 3c's instruction, relocated verbatim from the SKILL body:
+
+> Tell the user the run has started and that **this session is now actively
+> supervising it** — they don't need to babysit a terminal — and surface the rendered
+> `loopRunner` monitoring commands (`statusCommand` / `followCommand` / `logCommand` /
+> `listCommand`) and the state-file locations under
+> `{backlogDir}/{loopRunner.stateDir}/` so they can watch directly if they like. The
+> verbatim "Loop started…" inform-user output template is in
+> `references/runner-contract.md`.
+
 This is the verbatim "Loop started…" output the session shows the user after
 launch. Commands are the rendered `loopRunner` monitoring commands.
 

package/adapters/gemini/skills/forge-5-loop/references/shared-conventions.md

@@ -133,6 +133,8 @@ mkdir -p "<specsDir>"
 If the host is Claude (the `AskUserQuestion` tool is available), also ensure the Claude-framed variant:
 
 ```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
 [ -f "<specsDir>/CLAUDE.md" ] || cp "$R/references/templates/specs-hygiene/CLAUDE.md" "<specsDir>/CLAUDE.md"
 ```
 
@@ -183,7 +185,49 @@ If the helper is unavailable (a non-Claude host without the resolver), skip this
 
 ## Pipeline State Protocol
 
-Write pipeline state conforming to `references/pipeline-state-schema.json`. Always update `updatedAt` when modifying pipeline state.
+Pipeline state is written by the `state-*` verbs of `scripts/forge-session.py` — never by hand. Each verb writes `{resolvedFeatureDir}/.pipeline-state.json` atomically, conforms to `references/pipeline-state-schema.json` by construction, and refreshes `updatedAt` for you, so no stage needs to read the schema in order to author state.
+
+**Epic members MUST pass `--epic`.** Every `state-*` verb takes an optional `--epic "{epic}"`, and it is **required** whenever the feature is an epic member (its resolved directory is `{specsDir}/{epic}/{feature}/`, i.e. its state carries an `epic` back-pointer) — append it to **every** `state-*` call in this file and in every skill body, exactly as the `state-ecr` calls already do. Omit it only for a standalone feature. Without it the verb resolves the bare name itself and, mirroring `epic-manifest.py resolve`, refuses with exit 2 whenever more than one directory carries a state file rather than guessing which feature to write — so a same-named standalone feature can never be mutated in a member's place.
+
+If a `state-*` verb exits 2, surface the plain `Error:` line from stderr verbatim, do **not** proceed to the next step of the surrounding protocol, and do **not** hand-author the JSON as a workaround. The stage remains resumable because the entry stamp is already on disk — re-run the verb once the cause is fixed.
+
+**The eight `state-*` verbs.** `state-enter` (Stage-Entry Guard), `state-artifact` (incremental artifact tracking), `state-complete` (Git Commit Protocol), `state-branch` (Branch Setup and Branch Reconciliation), `state-note` (the Immediate Downstream Note below, and the optional completion note at stage closure), `state-decision` (deferred decisions), `state-ecr` (epic change requests), and `state-verify` (one `forge-verify-*` verification transition — below). The `--epic` member requirement and the exit-2 failure protocol above apply to **every** one of them, `state-verify` included; no verify entry is ever hand-authored.
+
+### `state-verify` — verification results and provenance
+
+`state-verify` writes exactly one `stages.forge-verify-{token}` entry — the verification result for the production stage named by `--stage` — plus the top-level `updatedAt`, and nothing else. `--stage` takes the **served production stage** (`forge-0-epic` through `forge-5-loop`; `forge-6-docs` has no verification token and is rejected). Add `--epic "{epic}"` when the feature is an epic member — required, per the member rule above. Result mode passes `--status` (`auto-verify-pending`, `passed`, `findings-reported`, `findings-applied`, or `skipped`) with whatever `--findings-file`, `--findings-count`, and `--verified-stage-version` that status requires; contradictory metadata is refused before any write. `passed` may additionally carry `--findings-file` + `--findings-count` together for an **advisory-only** report (`inconsistency`/`improvement` findings only, per forge-verify's severity floor) — the stage resolves without a fix round and the report stays attached:
+
+**`auto-verify-pending` is not a skill-facing status.** It is written by `stage-exit`'s scheduling boundary, which records the debt automatically when auto-verify is effective for a stage. The value is accepted on this CLI so the entry stays inspectable and repairable, not so a skill can hand-schedule verification: no skill body and no reference passes it, and none should. Every other status in the list is the recorded *result* of a verification that ran (or was explicitly skipped); this one records that one was *owed*.
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" state-verify \
+  --feature "{feature}" --stage "{served-production-stage}" --status "<status>" \
+  --specs-dir "{specsDir}"
+```
+
+Provenance follows the same two-commit sequence as `state-complete`: the result transition above writes `commitHash: null`, Commit 1 records the findings document and the state, and a second `state-verify` call records the full 40-hex hash of Commit 1 and touches nothing else (never `--amend`; an abbreviated hash is refused rather than expanded). Add `--epic "{epic}"` for an epic member — required, per the member rule above:
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" state-verify \
+  --feature "{feature}" --stage "{served-production-stage}" \
+  --commit-hash "$(git rev-parse HEAD)" --specs-dir "{specsDir}"
+```
+
+Epic-scoped verification is the single exception to the member rule: with `--stage forge-0-epic`, `--feature` names the **epic** and `--epic` must be absent or exactly equal to it. That call writes `{specsDir}/{epic}/.epic-state.json` and never a member's `.pipeline-state.json`, and its freshness version is the epic manifest's `revision`, never a member's stage version:
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" state-verify \
+  --feature "{epic}" --stage forge-0-epic --status "<status>" \
+  --specs-dir "{specsDir}"
+```
+
+On exit 2 the verification result is **not** recorded: surface the `Error:` line verbatim, name the feature (and epic), and do not claim the verification was persisted or advance past it.
 
 ### Staleness Detection (Read-Time)
 
@@ -193,6 +237,31 @@ When loading upstream artifacts as prerequisites, check `basedOnVersions` in the
 
 Frame the choice with its cost: re-running re-derives this stage from the current upstream (safest, but discards any hand-edits to this stage's artifacts); proceeding stale is faster but risks baking outdated assumptions into everything downstream. Recommend re-running unless the user knows the upstream change doesn't affect this stage.
 
+## Immediate Downstream Note (Parking Lot)
+
+When an interview raises a concern that belongs to a *later stage of this same feature*, acknowledge it and persist it **immediately, at the moment it is raised** — not at stage closure — by running `state-note` with a concise one-line statement of the concern. Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol above; omitting it for a member is an error and must never be allowed to fall back to a same-named flat feature.
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" state-note \
+  --feature "{feature}" --note "<concise downstream concern>" \
+  --specs-dir "{specsDir}"
+```
+
+`state-note` **overwrites** the single top-level `notes` string — it does not append. To preserve an earlier note, read the current `notes` value out of the feature's `.pipeline-state.json` first and pass one combined concise string in a single `--note`; never edit or round-trip the JSON by hand. This interview-time call is separate from the optional completion note offered at stage closure and must not be deferred until then — a session that ends before closure would otherwise lose the concern entirely.
+
+On `UsageError`/exit 2, surface the `Error:` line verbatim together with the named feature (and epic) and the recovery instruction, and **stop claiming the concern was recorded** — it was not. Epic *decomposition* changes are not notes: they go through `state-ecr` into `epicChangeRequests`, never into `notes`.
+
+## Verify Capability
+
+Skills that close a stage pass `--verify-capability interactive|manual` to `stage-exit`. The full determination rule, the Standard Verify Gate, and the recovery path live in `references/stage-exit-protocol.md`; the two facts that are most often gotten wrong:
+
+- **Dispatch capability is *permitted* dispatch, not a listed tool.** The question is "**may I dispatch `forge-verifier` right now**", not "is a subagent-dispatch tool in my tool surface". A session can carry a standing host instruction against dispatching subagents unless the user asked; such instructions are injected by the harness, sit outside this project's control, and outrank skill prose. Classify on permission, up front.
+- **A consent requirement is `interactive`, not `manual`.** When dispatch is barred only *unless the user asked* and a question mechanism is available, pass `interactive`: the gate's own affirmative choice supplies the missing user request. Pass `manual` only when there is **no** question mechanism **and** **no** permitted dispatch.
+
+A bar on unsolicited dispatch is never grounds to skip verification, and never grounds to fence the production successor while verification is unresolved. On the `runInStageVerify: true` path the emitted `verifyGate` stays `none`: reuse the Standard Verify Gate block for consent with **choice 2 omitted** (auto-verify is already effective, so "enable auto-verify going forward" is a no-op), leaving exactly two choices: *Verify now* (recommended) and *Skip for now*. The clean-room `forge-verifier` is **dispatched on the affirmative choice**, never merely printed for the user to run later; *Skip for now* is persisted as an explicit `skipped` before any advancing block.
+
 ## Branch Setup
 
 Invoke this block at the **very start** of a pipeline entry point — `forge-1-prd` (standalone feature) and `forge-0-epic` (epic) — **before** any directory resolution or interview, so the rest of the run lands on the intended branch. `{label}` is the feature name (forge-1-prd) or epic name (forge-0-epic); `{scope}` is `feature` or `epic` correspondingly.
@@ -214,7 +283,16 @@ Invoke this block at the **very start** of a pipeline entry point — `forge-1-p
    - **Create** → `git switch -c {branchPrefix}{label}` (or `git checkout -b` if `switch` is unavailable). If the branch already exists, `git switch {branchPrefix}{label}`.
    - **Stay** → proceed on the default branch; note that subsequent commits (and any `forge-5-loop` run) will land directly on `{defaultBranch}`.
 
-**Record the branch.** After this block resolves, write the resulting branch name to the feature's `.pipeline-state.json` top-level `branch` field (create/update it when the state file is first written for this stage). Downstream stages and `forge-5-loop` read it to detect drift back onto the default branch.
+**Record the branch.** After this block resolves, record the resulting branch name in the feature's top-level `branch` field by running `state-branch` (create/update it when the state file is first written for this stage). Emit the call **once the feature directory exists** — i.e. after Feature Directory Resolution and the Entry Stamp, **not** at this block: Branch Setup runs at the very start of the entry point, before any directory resolution, and a brand-new standalone feature may have no directory yet. Add `--epic "{epic}"` to the call when this feature is an epic member — required, per the Pipeline State Protocol.
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" state-branch \
+  --feature "{feature}" --branch "<name>" --specs-dir "{specsDir}"
+```
+
+Downstream stages and `forge-5-loop` read it to detect drift back onto the default branch.
 
 ## Branch Reconciliation
 
@@ -227,10 +305,19 @@ python3 "$R/scripts/forge-session.py" reconcile-branch --feature "{feature}" --s
 ```
 
 Act on the emitted `action` (source of truth is where the state actually resolves, not the recorded field):
-- **`adopt-current`** — you are on a non-default topic branch where the state resolves, and the recorded `branch` differs (a stale/imposed value). Write `newBranch` into the state `branch` field with a **visible one-line note** ("recorded branch was `{stateBranch}`; work is on `{currentBranch}` — updating to match") — never silently, and **never push the user back** to the recorded branch (offer that only as a plain alternative).
+- **`adopt-current`** — you are on a non-default topic branch where the state resolves, and the recorded `branch` differs (a stale/imposed value). Run `state-branch` (below) to write `newBranch` into the state `branch` field, with a **visible one-line note** ("recorded branch was `{stateBranch}`; work is on `{currentBranch}` — updating to match") — never silently, and **never push the user back** to the recorded branch (offer that only as a plain alternative).
 - **`warn-drift`** — you are on the **default** branch and the state records a topic branch. Via `AskUserQuestion`, strongly recommend creating/switching to `{branchPrefix}{feature}` (then record it), still allowing **proceed on the default branch**. Never hard-stop.
 - **`none`** / **`not-resolved`** — nothing to do; proceed.
 
+The `adopt-current` write, with the portable plugin-root prelude. Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol:
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" state-branch \
+  --feature "{feature}" --branch "{newBranch}" --specs-dir "{specsDir}"
+```
+
 If the helper is unavailable (non-Claude host without the resolver), fall back to the manual check: current branch differs from recorded → adopt the current branch unless it is the default, in which case recommend creating `{branchPrefix}{feature}`.
 
 ## Git Commit Protocol
@@ -240,14 +327,29 @@ When `gitCommitAfterStage` is true, follow this exact order to avoid state incon
 **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. **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:
+2. **Commit 1 — artifacts + state, hash not yet known:** Run `state-complete --feature {feature} --stage {stage} --version N …` (which sets this stage's `status: "complete"`, `completedAt`, `version`, `basedOnVersions`, `artifacts` and `commitHash: null`, and applies the downstream staleness cascade), 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`) by running `state-complete --feature {feature} --stage {stage} --version N --commit-hash $(git rev-parse HEAD)`, which writes it into this stage's `commitHash` and touches nothing else, 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. Do that with `state-complete --feature {feature} --stage {stage} --version N --resumable`, which records **only** `status` — no `completedAt`, no version bump, no `basedOnVersions`/`artifacts`, no `commitHash` reset, and no staleness cascade, so the stage stays resumable. (`--version` is still REQUIRED by argparse and must be passed even though `--resumable` does not write it; omitting it makes the recovery command exit 2 every time.) 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 — 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.
+   - **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. Pass `--preserve-commit-hash` on the Commit-1 `state-complete` call so the recorded hash is left alone instead of being reset to `null`. There is no new artifact commit to record.
 5. **Never** use `git add -A`, `--amend`, `--no-verify`, or `--force` flags
 
+The two `state-complete` calls, with the portable plugin-root prelude. Add `--epic "{epic}"` to each when this feature is an epic member — required, per the Pipeline State Protocol:
+
+```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; }
+# Commit 1 — before `git commit`
+python3 "$R/scripts/forge-session.py" state-complete \
+  --feature "{feature}" --stage "{stage}" --version {n} \
+  --based-on "<upstream>=<n>" --artifact "<file>" --specs-dir "{specsDir}"
+# Commit 2 — after Commit 1 lands, so its hash exists
+python3 "$R/scripts/forge-session.py" state-complete \
+  --feature "{feature}" --stage "{stage}" --version {n} \
+  --commit-hash "$(git rev-parse HEAD)" --specs-dir "{specsDir}"
+```
+
 ## Stage-Entry Guard
 
 Invoke this block at the **start of an authoring stage** (`forge-1-prd`..`forge-4-backlog`), **after** Feature Directory Resolution and **before** any interview or (re-)authoring. It prevents a re-entered stage — an injected skill body or a re-invoked `Skill` — from blindly re-running the interview over an in-progress or already-complete draft. `{stage}` is the invoking skill's id (e.g. `forge-2-tech`).
@@ -263,16 +365,27 @@ Invoke this block at the **start of an authoring stage** (`forge-1-prd`..`forge-
 
 3. **Re-authoring** (`status: "complete"` or `"stale"`) — a finished draft exists. Warn via `AskUserQuestion` before overwriting: "A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?" On confirm, proceed to the Entry Stamp and author a new version (the version increments at exit, per that stage's Update-Pipeline-State step).
 
-**Entry Stamp** (fresh, restart, and re-author paths — NOT the resume path). Before authoring, write to `{resolvedFeatureDir}/.pipeline-state.json` and update `updatedAt`:
-- `stages.{stage}.status` → `"in-progress"`
-- `stages.{stage}.startedAt` → current ISO-8601 UTC timestamp
-- top-level `currentStage` → `"{stage}"` (where the pipeline IS, per O1)
+**Entry Stamp** (fresh, restart, and re-author paths — NOT the resume path). Before authoring, record the entry stamp by running `state-enter` — one atomic write that sets `stages.{stage}.status` → `"in-progress"`, `stages.{stage}.startedAt` → current ISO-8601 UTC timestamp, top-level `currentStage` → `"{stage}"` (where the pipeline IS, per O1), and refreshes `updatedAt`. Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol:
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" state-enter \
+  --feature "{feature}" --stage "{stage}" --specs-dir "{specsDir}"
+```
 
 This write is **left uncommitted**: it is staged and committed as part of this stage's existing exit commit (Git Commit Protocol), so no extra commit is needed at entry. If the run is interrupted after the stamp but before the exit commit, the marker survives on disk (uncommitted) and the next entry classifies as **Interrupted** — which is exactly the intent.
 
 **Force Mode.** When `--force` is passed, skip the interactive gate: do not prompt for resume-vs-restart or the re-author warning. Treat entry as a fresh restart — apply the Entry Stamp and author. (`--force` already skips prerequisite checks; here it likewise bypasses the self-stage gate. Existing on-disk artifacts are still loaded per Force Mode.)
 
-**Incremental artifact tracking:** When a stage writes multiple files (e.g. forge-3-specs writing a suite of spec documents), update the `stages.{stage}.artifacts` array in `.pipeline-state.json` after writing each file — not just at stage completion. This is what makes the Interrupted inventory above precise about which files were successfully written.
+**Incremental artifact tracking:** When a stage writes multiple files (e.g. forge-3-specs writing a suite of spec documents), run `state-artifact --feature {feature} --stage {stage} --path <file>` after writing each file — not just at stage completion. This is what makes the Interrupted inventory above precise about which files were successfully written. Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol.
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" state-artifact \
+  --feature "{feature}" --stage "{stage}" --path "<file>" --specs-dir "{specsDir}"
+```
 
 ## Stage-Completion Re-check