@garygentry/feature-forge 0.2.14 → 0.3.1

package/README.md

@@ -2,7 +2,7 @@
 
 Cross-agent installer for the [**feature-forge**](https://github.com/garygentry/feature-forge)
 skill suite — an end-to-end feature-development pipeline that runs on any coding agent
-(Claude, Codex, Copilot, Cursor, or Gemini).
+(Claude, Codex, Copilot, Cursor, Gemini, or Pi).
 
 This package installs the canonical forge skills into the agents detected on your machine.
 It is dependency-free and performs sandboxed, manifest-tracked writes.
@@ -33,7 +33,7 @@ npx @garygentry/feature-forge install --dry-run --json
 
 | Flag                | Description                                                            |
 | ------------------- | --------------------------------------------------------------------- |
-| `-a, --agent <id>`  | Scope to one agent (`claude`/`codex`/`copilot`/`cursor`/`gemini`).    |
+| `-a, --agent <id>`  | Scope to one agent (`claude`/`codex`/`copilot`/`cursor`/`gemini`/`pi`). |
 | `-g, --global`      | Install into the user-level config dir (default: project-local).      |
 | `--symlink`         | Symlink the bundle instead of copying (Windows always copies).        |
 | `--dry-run`         | Print the planned actions without changing anything.                  |
@@ -52,6 +52,9 @@ Each agent's bundle is installed where that agent actually loads it (project sco
 | copilot | `.github/feature-forge/`             | managed block in `.github/copilot-instructions.md`      |
 | cursor  | `.cursor/rules/feature-forge/`       | —                                                       |
 | gemini  | `.gemini/extensions/feature-forge/`  | —                                                       |
+| pi      | `.pi/skills/feature-forge/`          | —                                                       |
+
+For Pi, `--global` installs to `~/.pi/agent/skills/feature-forge/` and project scope installs to `./.pi/skills/feature-forge/`. The Pi bundle includes real `package.json` metadata plus the `AskUserQuestion` compatibility extension; run `/trust` (or use `--approve` in non-interactive tests) before relying on project-local Pi resources.
 
 The Copilot block is delimited by `<!-- feature-forge:managed:start -->` /
 `<!-- feature-forge:managed:end -->` sentinels and merged without disturbing the rest of the
@@ -71,7 +74,7 @@ Claude Code users can alternatively install via the plugin marketplace:
 
 The default loop runner is [**rauf**](https://github.com/garygentry/rauf), published as
 [`@garygentry/rauf`](https://www.npmjs.com/package/@garygentry/rauf). The installer runs a
-read-only resolvability preflight on the pin (`@garygentry/rauf@0.12.0`) and records it; pass
+read-only resolvability preflight on the pin (`@garygentry/rauf@0.13.0`) and records it; pass
 `--skip-rauf` to defer the check (e.g. offline installs). Install the rauf CLI itself with
 `npx @garygentry/rauf` or its
 [binary script](https://github.com/garygentry/rauf#install). See the

package/adapters/GENERATION-REPORT.md

@@ -124,6 +124,26 @@ _No dropped constructs — every canonical construct is representable in this ag
 | `skills/forge-verify/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
 | `skills/forge/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
 
+## pi
+
+| Source | Construct | Reason |
+|--------|-----------|--------|
+| `agents/forge-researcher.md` | `sub-agent key 'model'` | Claude model aliases (opus/sonnet) are not Pi model ids; pin via subagents.agentOverrides.<name>.model in Pi settings instead (D1) |
+| `agents/forge-spec-writer.md` | `sub-agent key 'model'` | Claude model aliases (opus/sonnet) are not Pi model ids; pin via subagents.agentOverrides.<name>.model in Pi settings instead (D1) |
+| `agents/forge-verifier.md` | `sub-agent key 'model'` | Claude model aliases (opus/sonnet) are not Pi model ids; pin via subagents.agentOverrides.<name>.model in Pi settings instead (D1) |
+| `skills/forge-0-epic/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-1-prd/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-2-tech/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-3-specs/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-4-backlog/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-5-loop/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-6-docs/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-bootstrap/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-fix/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-guide/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge-verify/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+| `skills/forge/SKILL.md` | `argument-hint` | Pi skills have no invocation-hint field |
+
 ## Copied verbatim (no provenance header)
 
 These files are transported byte-for-byte from canon into every `adapters/<agent>/` bundle and intentionally carry **no** provenance header (a header would break byte-identity / corrupt parsed files):

package/adapters/claude/.feature-forge-bundle.json

@@ -1,6 +1,6 @@
 {
   "name": "feature-forge",
-  "version": "0.12.9",
+  "version": "0.14.0",
   "agent": "claude",
   "generatedBy": "python3 scripts/build-adapters.py"
 }

package/adapters/claude/agents/forge-verifier.md

@@ -24,7 +24,7 @@ You have READ-ONLY access. You cannot and should not modify any files. Your outp
 
 1. Read the pipeline state file to understand what stage the feature is at
 2. Load all relevant artifacts for the current verification mode
-3. Execute every check in the verification checklists (loaded via the forge-verify skill)
+3. Read **only your dispatched mode's checklist** — `references/verification-checklists/{mode}.md` (the parent's dispatch prompt names your `{mode}`) — and execute every check in it. Do **not** read the other five mode files or `references/findings-template.md`; those are for other modes and for the parent orchestrator respectively.
 4. Return structured findings as your response in the Output Format specified below
 5. Generate a fix plan suitable for a fresh agent to execute
 

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

@@ -217,8 +217,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.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."
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.13.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.13.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.13.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/claude/references/pipeline-state-schema.json

@@ -33,7 +33,7 @@
     "currentStage": {
       "type": "string",
       "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog", "forge-5-loop", "forge-6-docs", "complete", "forge-verify-prd", "forge-verify-tech", "forge-verify-specs", "forge-verify-backlog", "forge-verify-impl", "forge-0-epic", "forge-verify-epic"],
-      "description": "Where the pipeline IS: the most recently started stage — its `stages[<currentStage>].status` is `in-progress` while that stage is being authored, then `complete` once its artifacts are committed. A stage skill sets this to its own id when it starts. This is deliberately NOT 'the next stage to run': the next stage is DERIVED, never stored — it is the first production stage whose `stages[].status` is not `complete` (see `next_stage()` in forge-session.py, surfaced as the navigator/doctor `nextStage`). Consumers that need 'what runs next' compute it from `stages[].status`, not from this field. `complete` here means the whole pipeline is done. (Legacy/absent value: tools fall back to the derived next stage for display only — `build_rows` in forge-session.py.)"
+      "description": "Where the pipeline IS: the most recently started stage — its `stages[<currentStage>].status` is `in-progress` while that stage is being authored, then `complete` once its artifacts are committed. A stage skill sets this to its own id when it starts. This is deliberately NOT 'the next stage to run': the next stage is DERIVED, never stored — it is the first production stage whose `stages[].status` is not `complete` (see `next_stage()` in forge-session.py, surfaced as the navigator/doctor `nextStage`). Consumers that need 'what runs next' compute it from `stages[].status`, not from this field. `complete` is a LEGACY enum value, retained so pre-0.14 state files still validate: no writer produces it (the `state-*` verbs are the only writers, and only `state-enter` touches this field, setting it to the stage being entered). A finished pipeline therefore records the last stage it started — `forge-6-docs` — and 'the whole pipeline is done' is DERIVED too: `next_stage()` returns null (surfaced as `nextStage: null` / `complete: true`). Never test this field against `complete` to decide whether a pipeline finished. (Legacy/absent value: tools fall back to the derived next stage for display only — `build_rows` in forge-session.py.)"
     },
     "notes": {
       "type": "string",

package/adapters/claude/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,11 @@ 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.
 
 ### Staleness Detection (Read-Time)
 
@@ -214,7 +220,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 +242,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 +264,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 +302,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
 

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

@@ -182,10 +182,20 @@ concrete cache backend that `forge-2-tech` will design). Soliciting it here gues
 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"`.
+a `deferredDecisions[]` entry on this feature's `.pipeline-state.json` by running
+`state-decision` (`--rationale` and `--target-stage` are optional; the verb stamps
+`raisedAt` and `status: "open"` for you). Add `--epic "{epic}"` when this feature is an
+epic member — required, per the Pipeline State Protocol in `references/shared-conventions.md`:
+
+```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-decision \
+  --feature "{feature}" --question "<phrased for the target stage>" \
+  --rationale "<why it belongs downstream>" --target-stage "<owning stage>" \
+  --raised-by "{stage}" --specs-dir "{specsDir}"
+```
+
 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

package/adapters/claude/references/vendor-construct-inventory.md

@@ -23,7 +23,7 @@ vocabulary defined in `00-core-definitions.md` §8. No free-form values are perm
 | Construct | Locations / count | Disposition | Rationale / notes |
 |---|---|---|---|
 | `argument-hint` (top-level frontmatter key) | 10 `skills/*/SKILL.md` (all skills **except** `forge-init`) | `relocated` | Claude-specific vendor key (constraint C-2). Moved verbatim to `metadata.argument-hint` per REQ-VND-01 (see `02-frontmatter-purity-and-inventory.md` §2). Value byte-identical; `description` untouched. |
-| `${CLAUDE_PLUGIN_ROOT}` — canonical invocations + prose | 23 occurrences across 9 canonical surfaces: `skills/forge-0-epic/SKILL.md` (12), `skills/forge/SKILL.md` (3), `skills/forge-5-loop/SKILL.md` (1), `skills/forge-6-docs/SKILL.md` (1), `skills/forge-init/SKILL.md` (1), `skills/forge-verify/SKILL.md` (1), `skills/forge-verify/references/verification-checklists.md` (1), `references/shared-conventions.md` (2), `agents/forge-verifier.md` (1) | `routed-through-resolver` | Claude-only env var. Routed through the byte-identical bootstrap prelude + `scripts/forge-root.sh` per REQ-RES-03. Mechanics owned by `03-portable-root-resolver.md`; recorded here for audit completeness. |
+| `${CLAUDE_PLUGIN_ROOT}` — canonical invocations + prose | 23 occurrences across 9 canonical surfaces: `skills/forge-0-epic/SKILL.md` (12), `skills/forge/SKILL.md` (3), `skills/forge-5-loop/SKILL.md` (1), `skills/forge-6-docs/SKILL.md` (1), `skills/forge-init/SKILL.md` (1), `skills/forge-verify/SKILL.md` (1), `skills/forge-verify/references/verification-checklists/epic.md` (1), `references/shared-conventions.md` (2), `agents/forge-verifier.md` (1) | `routed-through-resolver` | Claude-only env var. Routed through the byte-identical bootstrap prelude + `scripts/forge-root.sh` per REQ-RES-03. Mechanics owned by `03-portable-root-resolver.md`; recorded here for audit completeness. |
 | `${CLAUDE_PLUGIN_ROOT}` — sanctioned residual | 1 occurrence in `scripts/forge-root.sh` (env-fallback, REQ-RES-02 step 3) | `preserved-as-spec-allowed` | The single sanctioned residual: the resolver's documented Claude-compat fallback (REQ-RES-03 / REQ-RES-05). Exempt from the residual-var scan (`00-core-definitions.md` §6 `RESIDUAL_VAR_EXEMPT`). |
 | `${CLAUDE_PLUGIN_ROOT:-}` — bootstrap-prelude first-hint (Chunk 2b) | 1 occurrence per prelude across every canonical stamp site (the byte-pinned `BOOTSTRAP_PRELUDE`) | `preserved-as-spec-allowed` | The prelude's first resolver candidate — exact, glob-free root resolution on any Claude layout; expands to empty and is skipped when unset. Rule 3 allows it by stripping the byte-pinned prelude before its scan (detection is by `${CLAUDE_PLUGIN_ROOT` prefix, so the `:-}` default form is not an escape hatch elsewhere). `forge-agent-adapters-build` translates it to `${FEATURE_FORGE_ROOT:-}` in non-Claude bundles. |
 | `${CLAUDE_PLUGIN_ROOT}` — in `hooks/hooks.json` | 1 occurrence in `hooks/hooks.json` | `out-of-canon` | Non-canonical Claude artifact (REQ-VND-04). Not a canonical surface; exempt from the REQ-RES-03 scan. Left in place. |

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

@@ -62,6 +62,21 @@ KNOWN_VERIFY_STATUSES: Final = frozenset(
 #: 'skipped', and 'pending' do NOT unblock dependents. Not collapsible into the set above.
 _VERIFY_ORCH_COMPLETE: Final = frozenset({"passed", "findings-applied"})
 
+#: The six production stages in pipeline order — mirrors ``PRODUCTION_STAGES`` in
+#: forge-session.py. Used ONLY to DERIVE "what runs next" from ``stages[].status``
+#: (see ``_next_production_stage``), never to read it out of ``currentStage``:
+#: the schema defines ``currentStage`` as "where the pipeline IS" (the most
+#: recently *started* stage), which is one stage behind the next un-run stage for
+#: the whole window between a stage completing and its successor being entered.
+_PRODUCTION_STAGES: Final = (
+    "forge-1-prd",
+    "forge-2-tech",
+    "forge-3-specs",
+    "forge-4-backlog",
+    "forge-5-loop",
+    "forge-6-docs",
+)
+
 
 # --------------------------------------------------------------------------- #
 # Type Definitions (00-core-definitions.md §4, §5; 02 §8.4)
@@ -946,19 +961,47 @@ def _transitive_deps(name: str, adjacency: dict[str, list[str]]) -> set[str]:
     return seen
 
 
+def _next_production_stage(state: dict) -> str | None:
+    """Return the first production stage that is not yet complete, else None.
+
+    The epic-side mirror of ``next_stage()`` in forge-session.py, and for the same
+    reason its docstring gives: "what runs next" is DERIVED from ``stages[].status``,
+    never read from the stored ``currentStage``. A missing, pending, in-progress or
+    stale stage all count as "not done".
+    """
+    stages = state.get("stages")
+    if not isinstance(stages, dict):
+        return _PRODUCTION_STAGES[0]
+    for stage in _PRODUCTION_STAGES:
+        entry = stages.get(stage)
+        if not isinstance(entry, dict) or entry.get("status") != "complete":
+            return stage
+    return None
+
+
 def _next_command(feature_dir: Path, status_row: FeatureStatus) -> str:
     """Recommend the next forge command for an actionable feature (02 §8.3).
 
-    ``/feature-forge:forge-1-prd <name>`` when the feature's PRD is absent (or it
-    has not progressed past epic creation), else the command for its next un-run
-    stage (its ``currentStage``).
+    ``/feature-forge:forge-1-prd <name>`` when the feature's PRD is absent (or the
+    member has not progressed past epic creation), else the command for its next
+    un-run production stage — DERIVED from ``stages[].status``, not read from
+    ``currentStage`` (item 020: ``currentStage`` is "where the pipeline IS", so
+    reading it here recommended re-running the stage the member had just finished
+    for the whole window before the next stage was entered).
+
+    When every production stage is complete but the member is still actionable, the
+    only thing holding it back is unapplied verify findings (``forge-verify-impl``
+    is ``findings-reported``), so ``forge-fix`` is the accurate recommendation.
     """
     name = status_row["name"]
-    stage = status_row["stage"]
+    state = _read_state_safely(feature_dir / PIPELINE_STATE_FILENAME)
+    nxt = _next_production_stage(state)
     prd_present = (feature_dir / "PRD.md").is_file()
-    if not prd_present or stage in ("forge-0-epic", "forge-1-prd"):
+    if not prd_present or nxt == "forge-1-prd":
         return f"/feature-forge:forge-1-prd {name}"
-    return f"/feature-forge:{stage} {name}"
+    if nxt is None:
+        return f"/feature-forge:forge-fix {name}"
+    return f"/feature-forge:{nxt} {name}"
 
 
 def render_status(epic_dir: Path, specs_dir: Path) -> RenderStatus:

package/adapters/claude/scripts/forge-root.sh

@@ -92,9 +92,24 @@ done < <(ls -t "$HOME"/.claude/plugins/cache/*/feature-forge/*/.claude-plugin/pl
 # Globs that match nothing expand to themselves; the is_root test rejects such literals. Covers
 # every supported agent's install destination under BOTH global ($HOME) and project ($PWD) scope,
 # matching the installer's per-agent layout: claude .claude/skills, codex .agents/skills, copilot
-# .github/feature-forge, cursor .cursor/rules, gemini .gemini/extensions. The cache glob repeats
-# step 2a's path for a cache install that carries only the neutral bundle sentinel (no
-# plugin.json for ls -t to key on).
+# .github/feature-forge, cursor .cursor/rules, gemini .gemini/extensions, pi .pi/skills or
+# $PI_CODING_AGENT_DIR/skills. The cache glob repeats step 2a's path for a cache install that
+# carries only the neutral bundle sentinel (no plugin.json for ls -t to key on).
+if [ -n "${PI_CODING_AGENT_DIR:-}" ]; then
+  for candidate in \
+    "$PI_CODING_AGENT_DIR/skills/feature-forge" \
+    "$PI_CODING_AGENT_DIR"/git/*/feature-forge/adapters/pi \
+    "$PI_CODING_AGENT_DIR"/git/*/*/feature-forge/adapters/pi \
+    "$PI_CODING_AGENT_DIR"/packages/*/feature-forge/adapters/pi \
+    "$PI_CODING_AGENT_DIR"/npm/*/@garygentry/feature-forge/adapters/pi \
+    "$PI_CODING_AGENT_DIR"/node_modules/@garygentry/feature-forge/adapters/pi \
+  ; do
+    if is_root "$candidate"; then
+      accept_root "$candidate"
+    fi
+  done
+fi
+
 for candidate in \
   "$HOME/.claude/skills/feature-forge" \
   "$PWD/.claude/skills/feature-forge" \
@@ -108,12 +123,41 @@ for candidate in \
   "$PWD/.cursor/rules/feature-forge" \
   "$HOME/.gemini/extensions/feature-forge" \
   "$PWD/.gemini/extensions/feature-forge" \
+  "$HOME/.pi/agent/skills/feature-forge" \
+  "$PWD/.pi/skills/feature-forge" \
+  "$HOME"/.pi/agent/git/*/feature-forge/adapters/pi \
+  "$HOME"/.pi/agent/git/*/*/feature-forge/adapters/pi \
+  "$HOME"/.pi/agent/packages/*/feature-forge/adapters/pi \
+  "$HOME"/.pi/agent/npm/*/@garygentry/feature-forge/adapters/pi \
+  "$HOME"/.pi/agent/node_modules/@garygentry/feature-forge/adapters/pi \
+  "$PWD"/.pi/git/*/feature-forge/adapters/pi \
+  "$PWD"/.pi/git/*/*/feature-forge/adapters/pi \
+  "$PWD"/.pi/packages/*/feature-forge/adapters/pi \
+  "$PWD"/.pi/npm/*/@garygentry/feature-forge/adapters/pi \
+  "$PWD"/.pi/node_modules/@garygentry/feature-forge/adapters/pi \
 ; do
   if is_root "$candidate"; then
     accept_root "$candidate"
   fi
 done
 
+# Project-scoped Pi installs may be discovered from a subdirectory of the repository. Probe
+# ancestor .pi roots up to the filesystem root; this is bounded by path depth and avoids
+# recursive globs. Scoped to .pi ONLY — every other agent's project layout is probed at $PWD
+# in the fixed list above, and widening those to ancestors here would silently change
+# established discovery behaviour for agents this bundle did not introduce.
+probe_dir="$PWD"
+while :; do
+  candidate="$probe_dir/.pi/skills/feature-forge"
+  if is_root "$candidate"; then
+    accept_root "$candidate"
+  fi
+  [ "$probe_dir" = "/" ] && break
+  next_probe_dir="$(dirname -- "$probe_dir")"
+  [ "$next_probe_dir" = "$probe_dir" ] && break
+  probe_dir="$next_probe_dir"
+done
+
 # ── Step 3: env fallback — neutral FEATURE_FORGE_ROOT, then the legacy CLAUDE_PLUGIN_ROOT. ─
 # The neutral override works for every agent; CLAUDE_PLUGIN_ROOT is kept only for backwards
 # compatibility with existing Claude installs (C-4).