@garygentry/feature-forge 0.2.14 → 0.3.0

package/adapters/pi/scripts/validate-traceability.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""Validate requirement traceability between PRD and implementation specs.
+
+Extracts REQ-XXX-NN identifiers from a PRD file and checks that every
+requirement is referenced in at least one implementation spec document.
+Also reports orphaned references (IDs found in specs but not in PRD).
+
+Usage:
+    python validate-traceability.py <prd-path> <specs-dir> [--json]
+
+Exit codes:
+    0 = all requirements covered, no orphans
+    1 = gaps or orphans found
+    2 = file not found or read error
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+REQ_PATTERN = re.compile(r"REQ-[A-Z]+-\d+")
+
+
+def extract_req_ids(text: str) -> set[str]:
+    """Extract all unique REQ-XXX-NN identifiers from text."""
+    return set(REQ_PATTERN.findall(text))
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate requirement traceability between PRD and specs"
+    )
+    parser.add_argument("prd_path", help="Path to PRD.md file")
+    parser.add_argument("specs_dir", help="Directory containing ##-*.md spec files")
+    parser.add_argument(
+        "--json", action="store_true", dest="json_output", help="Output as JSON"
+    )
+    args = parser.parse_args()
+
+    prd_path = Path(args.prd_path)
+    specs_dir = Path(args.specs_dir)
+
+    # Read PRD
+    if not prd_path.exists():
+        print(f"Error: PRD file not found: {prd_path}", file=sys.stderr)
+        return 2
+
+    try:
+        prd_text = prd_path.read_text()
+    except OSError as e:
+        print(f"Error reading PRD: {e}", file=sys.stderr)
+        return 2
+
+    prd_reqs = extract_req_ids(prd_text)
+
+    if not prd_reqs:
+        print(f"Warning: No REQ-XXX-NN identifiers found in {prd_path}", file=sys.stderr)
+
+    # Read spec files (##-*.md pattern)
+    if not specs_dir.exists():
+        print(f"Error: Specs directory not found: {specs_dir}", file=sys.stderr)
+        return 2
+
+    spec_files = sorted(specs_dir.glob("[0-9][0-9]-*.md"))
+    if not spec_files:
+        print(f"Warning: No spec files matching ##-*.md found in {specs_dir}", file=sys.stderr)
+
+    # Track which specs cover which requirements
+    spec_reqs: dict[str, set[str]] = {}
+    all_spec_reqs: set[str] = set()
+
+    for spec_file in spec_files:
+        try:
+            text = spec_file.read_text()
+            reqs = extract_req_ids(text)
+            spec_reqs[spec_file.name] = reqs
+            all_spec_reqs |= reqs
+        except OSError as e:
+            print(f"Warning: Could not read {spec_file}: {e}", file=sys.stderr)
+
+    # Also check TRACEABILITY.md if it exists
+    traceability_file = specs_dir / "TRACEABILITY.md"
+    if traceability_file.exists():
+        try:
+            text = traceability_file.read_text()
+            trace_reqs = extract_req_ids(text)
+            spec_reqs["TRACEABILITY.md"] = trace_reqs
+            all_spec_reqs |= trace_reqs
+        except OSError:
+            pass
+
+    # Analysis
+    uncovered = sorted(prd_reqs - all_spec_reqs)
+    orphaned = sorted(all_spec_reqs - prd_reqs)
+
+    # Per-requirement coverage map
+    coverage: dict[str, list[str]] = {}
+    for req_id in sorted(prd_reqs):
+        covering_specs = [
+            name for name, reqs in spec_reqs.items() if req_id in reqs
+        ]
+        coverage[req_id] = covering_specs
+
+    has_issues = bool(uncovered or orphaned)
+
+    if args.json_output:
+        result = {
+            "prd_file": str(prd_path),
+            "specs_dir": str(specs_dir),
+            "total_requirements": len(prd_reqs),
+            "total_spec_files": len(spec_files),
+            "uncovered_requirements": uncovered,
+            "orphaned_references": orphaned,
+            "coverage": coverage,
+            "valid": not has_issues,
+        }
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"PRD: {prd_path} ({len(prd_reqs)} requirements)")
+        print(f"Specs: {specs_dir} ({len(spec_files)} spec files)")
+        print()
+
+        if uncovered:
+            print(f"UNCOVERED REQUIREMENTS ({len(uncovered)}):")
+            for req_id in uncovered:
+                print(f"  - {req_id}: not found in any spec file")
+            print()
+
+        if orphaned:
+            print(f"ORPHANED REFERENCES ({len(orphaned)}):")
+            for req_id in orphaned:
+                sources = [
+                    name for name, reqs in spec_reqs.items() if req_id in reqs
+                ]
+                print(f"  - {req_id}: found in {', '.join(sources)} but not in PRD")
+            print()
+
+        if not has_issues:
+            print("All requirements covered. No orphaned references.")
+        else:
+            total_issues = len(uncovered) + len(orphaned)
+            print(f"Found {total_issues} issue(s).")
+
+    return 1 if has_issues else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,243 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge
+description: Feature-forge pipeline navigator and status dashboard. Use when the user references the forge pipeline, asks about forge status or progress, types /skill:forge, or wants to check what stage a feature is at in the forge pipeline. Do NOT use for general feature requests, project status, or tasks unrelated to the forge development pipeline.
+---
+
+# Feature Forge — Pipeline Navigator
+
+You are the navigator for the feature-forge development pipeline. Your job is to orient the user: show where they are, what's been done, and what's next.
+
+## Behavior
+
+### 1. Read Configuration
+
+Read and follow `references/shared-conventions.md` for configuration reading (feature name validation, config defaults, force mode).
+
+For pipeline architecture details, read `references/process-overview.md`.
+
+### 2. Determine Context
+
+**If a feature name is provided** (e.g., `/skill:forge auth`):
+- **First test whether the name is an epic:** if `{specsDir}/{name}/epic-manifest.json` exists, render the **Epic Dashboard** (see format below) and stop — do not treat it as a feature.
+- Otherwise, resolve the name via the **Feature Directory Resolution** block in `references/shared-conventions.md` (so a nested epic-member name finds its dashboard too). On a resolution failure (`not-found` / `ambiguous` at exit 1; `unsafe-name` or a path-containment escape at exit 2), surface it verbatim.
+  - On `not-found`, first run the cross-branch discovery step from that same Feature Directory Resolution block (`forge-session.py discover-feature` — the state may live on a topic branch or an unfetched remote branch). Candidates → offer switch / fetch+switch per that block (explicit accept + clean tree only), then re-resolve and render the dashboard. Only when discovery also returns nothing, ask: "No pipeline exists for '{feature}' on any branch. Want to start one? Run `/skill:forge-1-prd {feature}` to begin." Never render a dashboard from memory of earlier sessions (anti-fabrication guard).
+- If resolution succeeds, display the per-feature pipeline status dashboard (see format below) from `{resolvedFeatureDir}/`.
+
+**If no feature name is provided:** list in two tiers.
+
+1. **Epics first.** Identify epic directories as any `{specsDir}/*/` that directly contains an `epic-manifest.json` **and no `.pipeline-state.json` of its own** (an epic root is never itself a feature). For each epic, run:
+   ```bash
+R="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -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
+   ```
+   and show one rollup line: `{epic} — {complete}/{total} complete, next: {nextCommand}`.
+2. **Standalone features below.** Scan the remaining `{specsDir}/*/` that directly contain a `.pipeline-state.json` **without** an `epic` back-pointer. A nested member's `.pipeline-state.json` is **attributed to its epic (Tier 1), never listed as a standalone feature**.
+   - **Rank by recency.** Run the recency ranker so the most-recently-touched active feature is the default — the user rarely has to type a name (especially on mobile after a `/new`):
+     ```bash
+R="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" rank-features --specs-dir "{specsDir}" --json
+     ```
+     This returns `{active: [...], counts: {...}}` with active features sorted by `updatedAt` **descending** (row 0 is the most recent). Each row carries `currentStage`, `nextStage`, `nextCommand`, `verifyPending`, `verifyCommand`, `verifyStage`, `verifyState` (`fresh`/`stale`/`failing`/`never`/`none`), `autoVerify` (the effective per-stage setting), `autoFix` (the single source of stage order), and `verifyGate` (`none`/`auto`/`standard` — the single resolved verify-gate, computed once by the ranker; read it rather than re-deriving from `verifyPending`+`autoVerify`). A top-level `invalidAutoVerifyKeys` array appears when `forge.config.json` has `autoVerifyStages` keys outside the five verify-capable stages — surface it as a one-line warning. The `active` list excludes nested epic members surfaced in Tier 1 — but the ranker scans them too, so ignore rows whose `epic` is non-null here (they belong to the epic rollup).
+   - **Pick the feature:** if exactly one active standalone pipeline exists, show its dashboard. If multiple exist, use `AskUserQuestion` — **list the most-recently-updated first, labeled `(recommended)`**, each option's description showing its `currentStage` and a relative age ("updated 2h ago"). Always include a free-form escape ("A different feature / something else") so the user is never boxed in. Then render the chosen feature's dashboard.
+
+If no epics and no standalone features exist **on the current branch**, do not conclude the pipeline is empty yet — the state may live on topic branches (a fresh clone / default-branch session sees nothing on disk). Run `discover-feature --all` (via the standard prelude: `python3 "$R/scripts/forge-session.py" discover-feature --all --specs-dir "{specsDir}" --json`). If it surfaces features, list them with their branches and offer to switch (explicit accept + clean tree only, per the Feature Directory Resolution block), then render that feature's dashboard. Only when `--all` also returns nothing, say: "No active feature pipelines found. Start one with `/skill:forge-1-prd <feature-name>` or group several with `/skill:forge-0-epic <epic-name>`." Never fabricate a dashboard from memory of earlier sessions.
+
+The feature name must be a single kebab-case token. If the user provides multiple words (e.g., "user auth flow"), convert to kebab-case: `user-auth-flow`.
+
+### 3. Pipeline Status Dashboard
+
+Write pipeline state conforming to `references/pipeline-state-schema.json`.
+
+Display a clear, scannable status for the feature:
+
+```
+Feature: {feature}  [active]
+Stage: {currentStage} ({status}, started {relative time})
+
+✅ forge-1-prd     → PRD.md (v{n})
+⬜ forge-verify     (prd)          ← show only if forge-1-prd is complete
+✅ forge-2-tech    → tech-spec.md (v{n}, ⚠️ not yet verified)
+⬜ forge-verify     (tech)         ← show only if forge-2-tech is complete
+🔄 forge-3-specs   → in progress
+⬜ forge-verify     (specs)        ← show only if forge-3-specs is complete
+⬜ forge-4-backlog
+⬜ forge-verify     (backlog)      ← show only if forge-4-backlog is complete
+⬜ forge-5-loop
+⬜ forge-6-docs
+
+Next: Continue with /skill:forge-3-specs {feature}
+      Or verify tech-spec with /skill:forge-verify {feature}
+
+Notes: "{any persisted notes}"
+```
+
+Use these status indicators:
+- ✅ = complete
+- ✅⚠️ = complete but not yet verified
+- 🔄 = in progress
+- ⬜ = pending
+- ❌ = verification found issues (not yet fixed)
+- ✅🔍 = verified and fixes applied
+- ⏭️ = verification skipped (user chose to proceed without verifying)
+- ⚠️ = stale (built against an older version of an upstream artifact)
+
+### 3b. Drive to the Next Stage
+
+After rendering a **per-feature** dashboard for an **active** pipeline (skip this for paused/abandoned pipelines and for the Epic Dashboard), don't stop at a text suggestion — actively offer to start the next stage. This removes the copy-paste-after-`/new` chore that makes long, multi-stage runs painful (especially on mobile).
+
+**1. Read the next step.** From the `rank-features --json` output (above), find this feature's row and read its `nextStage`, `nextCommand`, `verifyPending`, `verifyCommand`, `verifyStage`, `verifyState`, `autoVerify`, `autoFix`, and `verifyGate` (the resolved gate: `none` → no verify action; `auto` → the §2b catch-up; `standard` → the §3 gate). If the feature is not in the `active` list (paused/abandoned), or `nextStage` is `null` (every production stage complete), skip the drive prompt — instead congratulate the user and, if `forge-6-docs` has not run, offer it; otherwise the whole pipeline is done, so **route into the Completion hand-off block below instead of dead-ending** (steps 2/2b/3 do not apply — there is no next stage to drive). If the payload has a non-empty `invalidAutoVerifyKeys`, print a one-line warning first (e.g. "⚠️ forge.config.json `autoVerifyStages` has unknown keys: … — they are ignored; fix the typo").
+
+**Detached-epic hint (completion of a *standalone* feature, Issue #125).** When `nextStage` is `null` for a feature whose row has no `epic` (a standalone completion), run `discover-feature "{feature}" --json` (via the standard prelude) *before* congratulating. If any candidate has `isEpicMember: true` on another branch, add an **additive, non-blocking** hint — it does not change the completion, only flags a likely split-brain: "⚠️ Heads-up: `{feature}` matches a member of epic `{epic}` on branch `{stateBranch}`. This standalone pipeline may have been forged detached from that epic. To reconcile, see `docs/recovery-detached-epic-member.md` (or continue — this is only a heads-up)." Skip the hint for epic-member rows (their `epic` is non-null) and when discovery surfaces no epic-member candidate.
+
+**Completion hand-off (fires when `nextStage` is `null` AND `forge-6-docs` has run — the pipeline is fully complete, Issue #124).** Do not dead-end on "pipeline is complete" — after congratulating, point the user at the next unit of work. This is a **terminal branch**: the drive steps (2/2b/3) do not run.
+
+- **Epic member** (this feature's `rank-features` row has a non-null `epic`, i.e. its `.pipeline-state.json` carries an `epic` back-pointer): run `epic-manifest.py render-status "{epic}" --specs-dir "{specsDir}" --json` (standard prelude; you likely already have this from the Tier-1 epic rollup — reuse it rather than re-running). Then:
+  - If `actionable` is non-empty, offer the next member via `AskUserQuestion`: *"Epic '{epic}' has {total−complete} feature(s) left — next up: **{actionable[0].name}** (`{actionable[0].nextCommand}`). Start it now?"* On accept, drive it exactly like a normal next stage (honor `autoInvokeNextStage` + `Skill`-tool availability per step 3's Continue-in-this-session rule; else print `{nextCommand}`). List any remaining `actionable` members as also-available.
+  - If `actionable` is empty but the epic is **not** fully complete (members blocked on unmet `dependsOn`), say so and point at the blockers rather than offering a start.
+  - If the epic is **fully complete** (`rollup.complete == rollup.total`, `total > 0`), congratulate on the whole epic and offer the epic-level architecture doc (`/skill:forge-6-docs` already surfaces this — mention it) and/or that the epic can be marked complete (`/skill:forge {epic}` renders the finished dashboard).
+- **Standalone** (row's `epic` is null): offer to start a fresh feature — *"Start a new feature: `/skill:forge-1-prd <feature-name>` (or group several with `/skill:forge-0-epic <epic-name>`)."* Then, from the `rank-features` `active` list, surface any **other** active pipelines (exclude this just-completed one) as a one-line list with their `nextCommand`s so the user can jump straight back into in-flight work. If the **detached-epic hint above fired** for this feature, lead with that recovery path (`docs/recovery-detached-epic-member.md`) — the split-brain reconcile is the more likely next action than starting something new.
+
+**2. Check the context window.** Run the context-usage helper so you can advise whether to continue here or start the next stage in a fresh session:
+```bash
+R="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" context-usage --json
+```
+- `{"available": true, ...}` → note `pct` (e.g. "context ~68% full") and `overThreshold`. Window/threshold come from `contextWindowTokens` / `contextWarnThreshold` in `forge.config.json` (the helper defaults to a 200k window and 0.7 threshold, and auto-bumps the assumed window to 1M once observed usage exceeds 200k; **on a 1M-context model set `contextWindowTokens: 1000000` so the percentage is accurate below 200k too** — 1M can't be detected from the transcript until usage crosses 200k).
+- `{"available": false, ...}` → omit context advice silently (non-Claude host, or a fresh session with no transcript). Never treat this as an error.
+
+**2b. Auto-verify catch-up (when `verifyPending` is true).** Under this behavior the just-completed authoring stage runs auto-verify **in-stage** (`references/stage-exit-protocol.md`, in-stage verify block), which clears `verifyPending` — so on the normal path this branch does **nothing**. It fires only as a **catch-up**: `verifyPending` is still true because the producing stage could not dispatch a clean-room subagent (non-Claude host), or ran before this behavior landed. When it does fire, decide whether verify runs automatically (identical logic to the in-stage run, so a stage that already verified is never double-verified):
+
+- **`autoVerify` is true for the just-completed `verifyStage`** → **skip the verify question entirely** and run verify now, *provided it can run clean-room*. Auto-verify is safe to run unattended only because verify executes in a fresh `forge-verifier` subagent that inherits none of this session's context (so no `/new` is needed and only a compact digest returns). Guard the clean-room assumption: proceed unattended **only when the host's subagent mechanism + `forge-verifier` subagent are available**. Invoke `feature-forge:forge-verify` via the host's skill-invocation mechanism in **require-clean (`auto`) mode** — in that mode forge-verify refuses to run inline and returns a sentinel if the subagent is not dispatchable (see `skills/forge-verify/SKILL.md`). Then:
+  - **Sentinel returned (clean-room unavailable)** → do **not** run verify inline. Degrade to the manual gate: fall through to step 3 with the **"Verify `{stage}` first (manual)"** option included, and if `overThreshold`, recommend "/new, then verify in a clean session." Verify state stays outstanding; the stage is never advanced on false assurance.
+  - **Verify passed / no findings** → proceed to the normal advance gate (step 3), no verify option.
+  - **Verify found findings** →
+    - **`autoFix` is true AND preconditions hold** — the findings document has **zero unresolved decision points** and the **working tree is clean** → invoke `feature-forge:forge-fix` via the host's skill-invocation mechanism, then run a **mandatory re-verify** (require-clean mode). Advance only if the re-verify passes. On **any** precondition miss (decisions required, dirty tree), a forge-fix early stop, or a red re-verify → fall back to the digest + prompt below (never a silent partial mutation).
+    - **`autoFix` is false (default), or preconditions failed** → present a **compact findings digest** as text, then `AskUserQuestion`: *Apply fixes now (forge-fix)* / *Review findings* / *Skip & advance*.
+- **`autoVerify` is false/unconfigured** → do not auto-run; use the advance gate in step 3, which gains the folded opt-in verify options ("Verify `{stage}` now" and "Verify `{stage}` now + enable auto-verify going forward").
+
+**3. Offer the next step via `AskUserQuestion`.** (Reached when auto-verify did not fully resolve the step, or `verifyPending` is false.) Output the dashboard + a one-line context note as text, then ask (per the Decision Support protocol in `references/shared-conventions.md`). **Present this gate exactly once and act only on the option the user chooses — never also narrate the not-taken branch.** Concretely: do not print the "start in a clean session" recommendation as prose and *then* auto-invoke the next stage in the same session (or the reverse) — the `AskUserQuestion` answer is the single decision, and only the chosen path's action follows. This is the same **Stage Exit Protocol** the stage skills stamp (`references/stage-exit-protocol.md`) — a clean session at the boundary is recommended on its own merits, and `overThreshold` only modulates *how emphatically*, never *whether*. Options, in this order:
+- **Start `{nextStage}` in a clean session** — **recommended, unconditionally**, at every boundary. A clean session is the right default for the next stage on its own merits, independent of window size. The work survives a clear because all state is on disk: instruct the user to `/new`, then re-run `/skill:forge {feature}` (or run `{nextCommand}` directly) in the fresh session. Note plainly that you cannot `/new` for them. **When `overThreshold` is true**, strengthen this wording (the window is also genuinely full) and add mid-stage compaction advice; **when the window is healthy**, still recommend the clean session — `overThreshold` is a *secondary, additive* modifier here, not the clear on/off switch.
+- **Continue in this session** — the always-available alternative, reasonable when the window is nearly empty and the user would rather not clear. Not the default.
+- **Verify `{stage}` now** — include **only when `verifyPending` is true and `autoVerify` is false**, and the clean-room path is available. **Recommended**, since verify is clean-room and rarely worth skipping. Runs verify now (require-clean mode); **does not** change config.
+- **Verify `{stage}` now + enable auto-verify going forward** — same trigger as the option above; runs verify now **and** patches `autoVerify: true` into `forge.config.json` in place (preserve formatting and other keys) so every future stage verifies automatically without prompting. This is the **folded** config-enable — it replaces the old post-hoc "make auto-verify the default?" follow-up. No silent config writes: the config changes **only** when the user picks this option.
+- **Verify `{stage}` first (manual)** — include **only when `verifyPending` is true** and the clean-room path is unavailable (the Tier-2 degradation above), or the host lacks the host's skill-invocation and subagent mechanisms; selecting it runs `{verifyCommand}` (inline / manual). Offer the "enable auto-verify" choice as text only if a config write is possible.
+- **Pick a different stage** — free-form escape to any stage or other action.
+
+**4. Act on the choice.**
+- **Clean session** (the default) → give the exact next command and the `/new`-then-re-run instruction; do not invoke anything (you cannot `/new` for the user).
+- **Continue in this session** → if `autoInvokeNextStage` is true (default) **and** the host's skill-invocation mechanism is available, invoke the chosen stage **via the host's skill-invocation mechanism** in this same session (e.g. `skill: "feature-forge:forge-3-specs"`, `args: "{feature}"`) — no retyping, no paste. If `autoInvokeNextStage` is false, or the host's skill-invocation mechanism is unavailable (a non-Claude host), fall back to printing `{nextCommand}` prominently for the user to run.
+- **Verify now / Verify now + enable auto-verify** → invoke `feature-forge:forge-verify` via the host's skill-invocation mechanism (require-clean mode). For the **enable-auto-verify** variant, additionally patch `autoVerify: true` into `forge.config.json` in place (preserve formatting and other keys) — never a silent write. On a non-Claude host or when degrading to the manual/inline gate, print `{verifyCommand}` instead.
+- **Different stage** → honor the free-form request.
+
+**Host fallback.** On a non-Claude host or when the host's skill-invocation and subagent mechanisms are unavailable, auto-verify never runs unattended — fall back to printing `{verifyCommand}` exactly as today, mirroring `autoInvokeNextStage`.
+
+This applies whether the feature was named explicitly (`/skill:forge {feature}`) or resolved from the recency default.
+
+### Epic Dashboard
+
+When the named argument is an epic (`{specsDir}/{name}/epic-manifest.json` exists), render the epic dashboard instead of a per-feature one. Run:
+
+```bash
+R="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -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
+```
+
+and render from its output:
+
+- **Epic header:** name + `status` (active | paused | abandoned | complete).
+- **Dependency graph:** each feature with its `dependsOn`, as an arrow list or indented tree (the helper guarantees the graph is acyclic).
+- **Per-feature rows:** reuse the **existing status indicators** below (✅/✅⚠️/🔄/⬜/❌/✅🔍/⏭️/⚠️), driven by each feature's derived `stage`/`status`. Mark `blocked` features and list their `unmetDeps`.
+- **Pending epic changes:** for any feature with `openEpicChangeRequests > 0`, append a ⚠️ marker and a hint: *"N pending epic change(s) — run `/skill:forge-0-epic {epic}` to reconcile."* If `blockingEpicChangeRequests > 0`, use a stronger marker (⚠️ **blocking**) and word it *"reconcile the epic **before** writing specs"* — this mirrors the pause-now vs finish-then split that stage-exit already routes on. Take these counts **only** from `render-status --json` (`features[].openEpicChangeRequests` / `.blockingEpicChangeRequests`); do not read member `.pipeline-state.json` directly for them.
+- **Actionable vs blocked:** list the `actionable` set and the recommended `nextCommand`.
+- **Rollup:** `{complete}/{total} features complete`.
+
+Example:
+
+```
+Epic: auth-overhaul  [active]   —   2/4 features complete
+
+Dependency graph:
+  config-store      (no deps)
+  token-service     → config-store
+  api-gateway       → token-service
+  audit-log         (no deps)
+
+✅ config-store     complete
+🔄 token-service    forge-3-specs (in progress) — ⚠️ 1 pending epic change
+⬜ api-gateway      blocked — waiting on token-service
+✅ audit-log        complete
+
+Actionable now: token-service
+Next: /skill:forge-3-specs token-service
+⚠️ Pending epic changes: token-service (1). Run /skill:forge-0-epic auth-overhaul to reconcile.
+```
+
+All of this is reconstructed **purely from disk** — the manifest plus each member's `.pipeline-state.json`, with no in-memory state — so a fresh session renders the same dashboard. If `render-status` fails, do not render a partial dashboard; surface per the exit-1/exit-2 split in the **Feature Directory Resolution** block of `references/shared-conventions.md` (exit 1 → parse `{findings[]}` from stdout; exit 2 → surface the plain `Error:` stderr line verbatim).
+
+### 4. Notes Management
+
+If the user says something like "note: switching to jose for JWT" or "remember: we decided X", update the `notes` field in `.pipeline-state.json`. This helps preserve context across session clears.
+
+### 5. Available Commands Reference
+
+When showing the dashboard, include a compact reference:
+
+```
+Commands:
+  /skill:forge-1-prd <feature>      Create requirements document
+  /skill:forge-2-tech <feature>     Create technical spec
+  /skill:forge-3-specs <feature>    Create implementation specs
+  /skill:forge-4-backlog <feature>  Generate rauf backlog
+  /skill:forge-5-loop <feature>  Run rauf autonomous loop
+  /skill:forge-6-docs <feature>     Generate architecture docs
+  /skill:forge-verify <feature>     Run verification on current stage
+```
+
+### 6. Pipeline Lifecycle Commands
+
+Support these sub-commands for pipeline lifecycle management:
+- `/skill:forge pause {feature}` — Set `pipelineStatus` to `"paused"`. Do NOT modify `currentStage` or any stage statuses. The pipeline freezes exactly as-is. Show a confirmation.
+- `/skill:forge resume {feature}` — Set `pipelineStatus` back to `"active"`. Calculate how long the feature was paused (from `updatedAt` to now). If paused for more than 24 hours, show a hint: "This feature was paused for {duration}. Session context may have been lost — consider re-running `/skill:forge-{currentStage} {feature}` to rebuild context."
+- `/skill:forge abandon {feature}` — Set `pipelineStatus` to `"abandoned"`. Use `AskUserQuestion` to confirm first, and state what's reversible: abandoning does not delete artifacts and can be undone with `/skill:forge resume {feature}`, so the cost is low — but if the user really means "stop and discard," point out that `pause` is the better choice when they're only setting it aside. Offer **Abandon** · **Pause instead** · **Cancel**.
+- `/skill:forge run [{feature}]` — **Opt-in auto-advance.** Drive the feature through consecutive stages in one session instead of confirming each boundary. This is a convenience wrapper over **3b. Drive to the Next Stage** — same stage order, same context gate — just looped:
+  1. Resolve the feature (if omitted, use the recency default from `rank-features`; if multiple are equally plausible, ask once via `AskUserQuestion`).
+  2. **Before each stage,** run `forge-session.py context-usage`. If `overThreshold` is true, **stop** and recommend a clean session (give the exact `{nextCommand}` and the `/new`-then-re-run instruction) — never auto-`/new`.
+  3. Otherwise invoke the next stage's skill via the host's skill-invocation mechanism, let it run to its natural stopping point, then re-read state and continue from step 2.
+  4. **Stop conditions:** the next stage is an interview/decision point that calls `AskUserQuestion` (PRD and tech inherently pause for input — let them); `nextStage` is `null` (pipeline complete); context over threshold; or a stage signals it needs human input / is blocked. Always report where the loop stopped and why.
+  Per-stage confirmation (3b) remains the default — `run` is only used when the user explicitly asks to "run" / "drive" / "auto-advance" the pipeline. On a non-Claude host where the host's skill-invocation mechanism is unavailable, fall back to printing the ordered list of commands to run.
+
+**Epic lifecycle.** When the argument names an **epic** (`{specsDir}/{name}/epic-manifest.json` exists), `pause` / `resume` / `abandon` operate on the epic manifest, not a `.pipeline-state.json`:
+
+- Set the manifest's top-level `status` (`paused` / `active` / `abandoned`) via the helper's `set-status` mutator — an atomic write that also bumps `updatedAt`:
+  ```bash
+R="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/epic-manifest.py" set-status "{epic}" --status paused --specs-dir "{specsDir}"
+  ```
+  For `complete`, do **not** set the status directly — completion is *derived* from member states (the rollup), so the manifest `status` is a lifecycle flag, never a completion signal.
+- **Member feature states are NOT silently mutated.** Pausing/abandoning the epic changes only the manifest `status`. Before doing so, use `AskUserQuestion` to make the relationship explicit and frame the trade-off: "Pausing the epic does not pause its in-flight member features. {N} members are active. Pause the epic only, or also pause each member?" Recommend **epic only** when members are mid-stage and the user just wants to stop *new* orchestration; recommend **also pause members** when the intent is a hard freeze of all in-flight work. If the user opts to pause members too, update each member's own `pipelineStatus` **individually and visibly** (one explicit action per member), never as a hidden side-effect.
+- Commit the change via the Git Commit Protocol, staging `{specsDir}/{epic}/`.
+
+When listing features, show active pipelines by default. Include a count of paused/abandoned: "3 active pipelines (1 paused, 1 abandoned — use `/skill:forge list all` to see them)."
+
+## Gotchas
+
+- Never modify any spec files, backlog files, or pipeline state beyond the `notes`, `updatedAt`, and `pipelineStatus` fields. The navigator is read-only except for notes and lifecycle commands.
+- If a user asks to "continue" or "pick up where I left off" without naming a feature, check for active pipelines before asking. Only ask if ambiguous.
+- The pipeline state file is the source of truth. Don't infer stage from the existence of files alone — a file might exist from a previous incomplete run.
+
+---
+
+## Host execution notes (Pi)
+
+This Pi bundle preserves Claude's `AskUserQuestion` references because it ships a Pi compatibility extension registering an `AskUserQuestion` tool. On Pi:
+
+- **User input:** use `AskUserQuestion` for genuine user decisions. It supports multiple questions, option descriptions, recommended ordering, multi-select, previews, and free-form Other/custom answers.
+- **Skill dispatch:** Pi uses `/skill:<name>` commands. If you cannot invoke a skill directly, print the exact `/skill:<name> ...` command for the user to run.
+- **Subagents:** this bundle declares its custom agents (`forge-researcher`, `forge-spec-writer`, `forge-verifier`) as package agents. If a `subagent` tool is registered, dispatch one with `{ agent: "forge-verifier", task: "..." }`, or fan several out concurrently with `{ tasks: [{ agent: "forge-spec-writer", task: "..." }, ...] }`. If no `subagent` tool is available, run that step inline yourself.
+- **Background / monitoring:** run long-lived commands in the foreground and report progress as it arrives.

package/adapters/pi/skills/forge/references/pipeline-state-schema.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Feature Forge Pipeline State",
+  "description": "Tracks pipeline progress for a single feature across sessions. Lives at {specsDir}/{feature}/.pipeline-state.json",
+  "type": "object",
+  "required": ["feature", "createdAt", "updatedAt", "currentStage", "stages", "pipelineStatus"],
+  "properties": {
+    "pipelineStatus": {
+      "type": "string",
+      "enum": ["active", "paused", "abandoned"],
+      "default": "active"
+    },
+    "feature": {
+      "type": "string",
+      "description": "Feature name (matches directory name under specsDir)"
+    },
+    "epic": {
+      "type": "string",
+      "description": "Back-pointer to the owning epic's name. Absent for standalone features. The epic-manifest.json is canonical on conflict (REQ-STATE-01)."
+    },
+    "branch": {
+      "type": "string",
+      "description": "Git branch this feature's pipeline work is intended to land on, recorded by the Branch Setup block (shared-conventions.md) at the entry stage. Absent when the project isn't a git repo or branchPerFeature is false. Downstream stages and forge-5-loop compare the current branch against this to detect drift back onto the default branch before committing."
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "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.)"
+    },
+    "notes": {
+      "type": "string",
+      "description": "Free-form notes persisted between sessions (user can add context before stepping away)"
+    },
+    "epicChangeRequests": {
+      "type": "array",
+      "description": "Epic-level change requests raised by a member stage (forge-1-prd/forge-2-tech) when the epic DECOMPOSITION itself must change — distinct from the same-feature `notes` parking lot. Read by forge-0-epic edit mode (which applies them) and by forge-session stage-exit (which routes the exit on `blocksCurrent`). Absent/empty for standalone features. Additive/optional: legacy states without it validate unchanged.",
+      "items": {
+        "type": "object",
+        "required": ["kind", "target", "rationale", "blocksCurrent", "raisedBy", "raisedAt", "status"],
+        "additionalProperties": false,
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": ["add-feature", "redep", "move-boundary", "split"],
+            "description": "The decomposition change. add-feature/redep map 1:1 onto edit-mode mutators; move-boundary/split are composite (applied guided-manual in v1)."
+          },
+          "target": {
+            "type": "string",
+            "description": "The sibling feature to add, or the feature/boundary affected."
+          },
+          "rationale": {
+            "type": "string",
+            "description": "Why the epic must change; seeds the edit-mode charter/prompt when applied."
+          },
+          "blocksCurrent": {
+            "type": "boolean",
+            "description": "true → the current feature's next stage would build on a soon-to-change decomposition (pause-now: reconcile before proceeding). false → a peer/downstream change (finish-then-edit). Drives stage-exit routing."
+          },
+          "raisedBy": {
+            "type": "string",
+            "enum": ["forge-1-prd", "forge-2-tech"],
+            "description": "The stage that detected the epic-level concern."
+          },
+          "raisedAt": { "type": "string", "format": "date-time" },
+          "status": {
+            "type": "string",
+            "enum": ["open", "applied", "dismissed"],
+            "default": "open",
+            "description": "Lifecycle: open → applied|dismissed. Only forge-0-epic edit mode flips open→applied/dismissed; recording stages only create open entries; navigator/verify only read."
+          }
+        }
+      }
+    },
+    "deferredDecisions": {
+      "type": "array",
+      "description": "Same-feature decisions deliberately postponed to a LATER stage of THIS feature — a structured alternative to burying them in the free-text `notes` string. Distinct from `notes` (unstructured scratch) and from `epicChangeRequests[]` (the epic DECOMPOSITION must change). Use this when a stage would otherwise be tempted to solicit a decision that properly belongs to a downstream stage (e.g. forge-1-prd deferring the concrete cache backend to forge-2-tech): record it here instead of asking now (see the deferred-decisions rule in `references/stage-exit-protocol.md`), and the target stage addresses it. Additive/optional: legacy states without it validate unchanged.",
+      "items": {
+        "type": "object",
+        "required": ["question", "raisedBy", "raisedAt", "status"],
+        "additionalProperties": false,
+        "properties": {
+          "question": {
+            "type": "string",
+            "description": "The decision being deferred, phrased as a concrete question for the target stage to answer."
+          },
+          "rationale": {
+            "type": "string",
+            "description": "Why it is deferred rather than decided now (e.g. depends on information the target stage produces)."
+          },
+          "targetStage": {
+            "type": "string",
+            "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog", "forge-5-loop", "forge-6-docs"],
+            "description": "The stage that should resolve this decision. Omit when unknown/any-later-stage."
+          },
+          "raisedBy": {
+            "type": "string",
+            "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog"],
+            "description": "The stage that deferred the decision."
+          },
+          "raisedAt": { "type": "string", "format": "date-time" },
+          "status": {
+            "type": "string",
+            "enum": ["open", "addressed", "dismissed"],
+            "default": "open",
+            "description": "Lifecycle: open → addressed|dismissed. The target stage flips open→addressed when it resolves the decision (or dismissed if it no longer applies); recording stages only create open entries."
+          }
+        }
+      }
+    },
+    "stages": {
+      "type": "object",
+      "properties": {
+        "forge-0-epic": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-epic": { "$ref": "#/definitions/verifyEntry" },
+        "forge-1-prd": { "$ref": "#/definitions/stageEntry" },
+        "forge-2-tech": { "$ref": "#/definitions/stageEntry" },
+        "forge-3-specs": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-specs": { "$ref": "#/definitions/verifyEntry" },
+        "forge-4-backlog": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-backlog": { "$ref": "#/definitions/verifyEntry" },
+        "forge-5-loop": { "$ref": "#/definitions/stageEntry" },
+        "forge-6-docs": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-impl": { "$ref": "#/definitions/verifyEntry" },
+        "forge-verify-prd": { "$ref": "#/definitions/verifyEntry" },
+        "forge-verify-tech": { "$ref": "#/definitions/verifyEntry" }
+      }
+    }
+  },
+  "definitions": {
+    "stageEntry": {
+      "type": "object",
+      "required": ["status"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["pending", "in-progress", "complete", "stale"]
+        },
+        "version": {
+          "type": "integer",
+          "description": "Incremented each time this stage's artifacts are revised"
+        },
+        "artifacts": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Relative paths to artifacts produced by this stage"
+        },
+        "startedAt": { "type": ["string", "null"], "format": "date-time" },
+        "completedAt": { "type": ["string", "null"], "format": "date-time" },
+        "commitHash": {
+          "type": ["string", "null"],
+          "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",
+          "description": "Upstream stage versions this artifact was built against",
+          "additionalProperties": { "type": "integer" }
+        }
+      }
+    },
+    "verifyEntry": {
+      "type": "object",
+      "required": ["status"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["pending", "passed", "findings-reported", "findings-applied", "skipped"]
+        },
+        "findingsFile": {
+          "type": ["string", "null"],
+          "description": "Path to the verification findings document"
+        },
+        "findingsCount": {
+          "type": ["integer", "null"],
+          "description": "Number of findings reported"
+        },
+        "verifiedAt": { "type": ["string", "null"], "format": "date-time" },
+        "fixedAt": { "type": ["string", "null"], "format": "date-time" },
+        "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." }
+      }
+    }
+  }
+}