@garygentry/feature-forge 0.2.14 → 0.3.1

package/adapters/pi/skills/forge/references/stage-exit-protocol.md

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

package/adapters/pi/skills/forge-0-epic/SKILL.md

@@ -0,0 +1,308 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-0-epic/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-0-epic
+description: 'Create or edit a forge epic: decompose a large change into discrete member features with dependencies, charters, and structured contracts, producing epic-manifest.json + EPIC.md. Re-run on an existing epic to enter edit mode (add/remove/reorder features, change dependencies). Use when the user runs /skill:forge-0-epic or explicitly asks to start/modify an epic. Do NOT trigger for single-feature PRD work (that is forge-1-prd) or for general project planning outside forge.'
+---
+
+# forge-0-epic — Epic Decomposition & Orchestration
+
+Create an epic — a named grouping of related forge features with declared dependencies
+and shared contracts — through a structured decomposition interview, OR edit an existing
+epic. The manifest is the source of truth; EPIC.md mirrors it. All graph/validation work
+is delegated to `scripts/epic-manifest.py`.
+
+This skill **composes** JSON and **issues** helper commands. It NEVER eyeballs a dependency
+graph for cycles, NEVER hand-rolls a manifest write where a mutator exists, and NEVER asks a
+question in inline prose — every question goes through `AskUserQuestion`.
+
+## Prerequisites
+
+Read and follow `references/shared-conventions.md` for:
+- the **Feature Name Requirement** (applied here to the *epic* name — see below),
+- the **User Input Protocol** (the AskUserQuestion guardrail — all questions go through the tool),
+- **Configuration Reading**, and
+- the **Git Commit Protocol**.
+
+**Epic name handling.** The single positional argument is the **epic** name (not a feature).
+If no name is given, STOP and ask for one — do not guess. Convert multi-word input to a single
+kebab-case token. The name must satisfy `SAFE_NAME_RE` (`^[a-z0-9]+(?:-[a-z0-9]+)*$`); the
+helper rejects unsafe names. Member feature names are elicited later, in the interview.
+
+**Force mode.** `--force` is honored as in shared-conventions: skip pipeline-state prerequisite
+checks but still load any on-disk artifacts.
+
+**Config values read** (defaults from shared-conventions): `specsDir` (default `./specs`),
+`gitCommitAfterStage` (default true), `commitPrefix` (default `forge`).
+
+**Helper invocation.** Every helper call uses the convention from 01 §2.2 — the absolute
+plugin path and the configured specs dir:
+
+```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" <subcommand> ... --specs-dir "{specsDir}"
+```
+
+`$R` resolves to the installed plugin root via the portable resolver (`scripts/forge-root.sh`,
+bootstrapped by the prelude above; see `references/portable-root.md`). Pass `--specs-dir "{specsDir}"`
+on every invocation.
+
+---
+
+## Step 0 — Dispatch Detection
+
+Resolve the epic subtree path `{specsDir}/{epic}/` and decide which branch to run.
+
+1. **Collision check — is this name already a standalone feature?** If `{specsDir}/{epic}/`
+   exists and directly contains a `.pipeline-state.json` of its own (i.e. it is itself a
+   *feature* directory, not an epic root), STOP. Surface verbatim:
+   > `{epic}` is already a standalone feature, not an epic. Choose a different epic name or
+   > relocate the feature.
+
+2. **Manifest existence probe** — does this epic already have a manifest?
+
+   ```bash
+   test -f "{specsDir}/{epic}/epic-manifest.json" && echo EXISTS || echo NEW
+   ```
+
+   - **NEW** (no `epic-manifest.json`) → **Creation branch** (Step C1 onward).
+   - **EXISTS** → **Edit branch** (§ Edit Mode below).
+
+   This manifest-existence dispatch **is** forge-0-epic's stage-entry guard: a re-entry on an existing epic lands in Edit Mode (helper-mutated, re-validated) rather than re-running the creation interview, so the **Stage-Entry Guard** block used by `forge-1-prd`..`forge-4-backlog` does not apply here (an epic has no self `.pipeline-state.json` to stamp — it writes member states).
+
+3. **Pre-flight epic-name uniqueness (creation only).** Before composing anything for a NEW
+   epic, confirm the epic name itself does not collide with any existing feature or epic:
+
+   ```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" check-name "{epic}" --specs-dir "{specsDir}"
+   ```
+
+   - Exit `0` → the name is free; proceed to C1.
+   - Exit `1` (`duplicate-name`) → STOP and surface the helper's finding **verbatim**; ask
+     for a different epic name, then re-run check-name.
+   - Exit `2` (unsafe name) → STOP and surface the finding; ask for a corrected name.
+
+---
+
+## Creation Branch
+
+### Step 1 — Branch Setup
+
+Invoke the **Branch Setup** block in `references/shared-conventions.md` with `{label}` = `{epic}` and
+`{scope}` = `epic`. It self-gates (skips when not a git repo or when `branchPerFeature` is false),
+detects whether you're on the default branch, and strongly recommends — still optionally — creating
+`{branchPrefix}{epic}` when you are. Each member feature's `forge-1-prd` inherits this branch rather
+than prompting again.
+
+### Step C1 — Epic Framing Interview
+
+Output context as text (what an epic is, that a decomposition interview will follow). Then
+call `AskUserQuestion` to elicit:
+
+1. **Epic goal / problem** — the overarching change being decomposed. Becomes the EPIC.md
+   "Overall Goal" narrative and seeds the manifest `description`.
+2. **One-paragraph description** — a confirmed/edited summary. Becomes the manifest `description`.
+
+The epic `name` is the validated CLI argument from Step 0 — do NOT prompt for it again.
+
+### Step C2 — Feature-List Interview
+
+Drive a decomposition dialogue. Output your analysis as text first (how the goal might split,
+right-sizing guidance: each feature should be a single pipeline-sized unit — a unit forge-1-prd
+through forge-5-loop would carry end-to-end — not item-level interleaving). Then use
+`AskUserQuestion` to elicit the candidate feature list. Per the **Decision Support** protocol in `references/shared-conventions.md`, lead with a **recommended decomposition** and a one-line rationale rather than asking the user to invent it unaided, then probe its seams ("Is any of these two really one? Is any one really two?"), naming the trade-off (more features = more parallelism but more edges). Iterate until the user confirms.
+
+For **each** proposed feature name, before accepting it into the set, enforce global uniqueness
+and name safety via the helper:
+
+```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" check-name "{feature}" --specs-dir "{specsDir}"
+```
+
+- Exit `0` → accept the name.
+- Exit `1` (`duplicate-name`) → reject that name; surface the finding verbatim and re-prompt
+  for a different name.
+- Exit `2` (`unsafe-name`) → reject; surface the finding and re-prompt.
+
+Never accept a feature name that has not passed `check-name` exit 0.
+
+### Step C3 — Per-Feature Charter + Structured Contracts
+
+For each confirmed feature, run a focused `AskUserQuestion` batch (one feature at a time,
+2–3 questions per call) eliciting:
+
+- **Charter** — a single paragraph: scope statement + contract obligations. This is a
+  **charter only, NOT a PRD**. Do NOT conduct a full requirements interview here. If the user
+  starts dictating detailed requirements, redirect (as context text, then continue the batch):
+  > "That's PRD-level detail — `forge-1-prd` will capture it when this feature is ready. For
+  > the charter I just need the one-paragraph scope and what it must expose/consume."
+- **`exposes`** — zero or more structured `Contract` objects this feature provides to
+  dependents. Each is `{ "name", "kind", "summary" }` where `kind` ∈
+  `function | type | endpoint | module | event`.
+- **`consumes`** — zero or more structured `ConsumedContract` objects this feature relies on.
+  Each is `{ "from", "name", "summary" }`, where `from` is a sibling feature name in this epic.
+
+Collect these into plain JSON objects per feature. Do NOT free-form the contracts in prose —
+the structured arrays are the source of truth; EPIC.md renders them as prose later (Step C6).
+
+### Step C4 — Dependency-Edge Interview
+
+For each feature, use `AskUserQuestion`: "Which sibling features must be complete before this
+one can build?" → populates `dependsOn: [names]`.
+
+**Seed the suggestion from `consumes`:** a `consumes.from` X strongly implies `dependsOn` X. Per the **Decision Support** protocol, offer the union of each feature's `consumes.from` set as the **recommended default**, evidence-backed — but flag the cost (each edge serializes the loop and blocks dependents, so add only what contracts require). User confirms/overrides; `dependsOn` is authoritative.
+
+The `features[]` array order is the user-declared sequence from C2 (order is a presentation
+sequence, **not** a dependency ordering). Preserve the C2 order unless the user asks to reorder.
+
+### Step C5 — Compose & Validate the Manifest
+
+Compose the full `epic-manifest.json` per the 00 §2 schema, setting:
+
+- `schemaVersion`: `1`
+- `epic`: `"{epic}"`
+- `description`: from C1
+- `status`: `"active"`
+- `narrativeDoc`: `"EPIC.md"`
+- `createdAt` and `updatedAt`: the **same** current ISO-8601 UTC timestamp (`createdAt == updatedAt`)
+- `features[]`: in declared order, each with `name`, `charter`, `dependsOn`, `exposes`,
+  `consumes`. **No per-feature `status` field** — including one makes the manifest fail
+  validation (the `cached-status` finding).
+
+Write the composed JSON to `{specsDir}/{epic}/epic-manifest.json` (creating the epic dir first).
+For the *initial* creation write the skill writes the file directly — atomic guarantees are only
+required for in-place mutation, which is the helper mutators' job. Creating the epic dir first creates `{specsDir}/`, so after writing the manifest invoke the **Specs Directory Hygiene** block in `references/shared-conventions.md` (idempotent; stage anything it writes with this stage's commit). Then validate:
+
+```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" validate "{epic}" --specs-dir "{specsDir}" --json
+```
+
+- Exit `0` → proceed to C6.
+- Exit `1` → the manifest is malformed. Surface **every** `findings[]` entry **verbatim**, do
+  NOT proceed, and loop back into the relevant interview step to correct, then re-compose and
+  re-validate:
+  - `cycle` → re-open the dependency interview (C4).
+  - `dangling-ref` → re-open C4 (bad `dependsOn`) or C3 (bad `consumes.from`).
+  - `duplicate-name` / `unsafe-name` → re-open the feature-list interview (C2).
+  - `cached-status` / schema violation → fix the composed JSON and re-validate.
+- Exit `2` → IO/usage error (missing manifest or unreadable). Surface and STOP.
+
+Acyclicity, uniqueness, and dangling-ref checks are thus ALWAYS performed by the helper, never
+by the LLM eyeballing the graph.
+
+> **Contracts have no mutator.** There is intentionally no `--exposes-json`/`--consumes-json`
+> flag. At creation, the skill populates each feature's `exposes`/`consumes` directly in the
+> composed manifest entry (above), then re-runs `validate` — exactly as described here. The
+> same pattern applies after an edit-mode `add-feature` (see Edit Mode).
+
+### Step C6 — Generate EPIC.md
+
+Generate `{specsDir}/{epic}/EPIC.md` from the **validated** manifest. It is the human-readable
+**mirror** of the manifest (the manifest is the source of truth). For the full EPIC.md structure
+skeleton, read `references/edit-mode.md` (EPIC.md Mirror Template section) — the same template the
+edit-mode E5 patch applies.
+
+**The mirror rule.** Render each feature's `exposes`/`consumes` arrays as prose, one bullet per
+contract entry, preserving `name`, `kind`/`from`, and `summary`. Do not invent a contract that
+is not in the manifest, and do not omit one that is. The Overall Goal and Decomposition
+Rationale are the only prose without a 1:1 manifest counterpart. The skill does NOT itself diff
+EPIC.md against the manifest — drift detection is `forge-verify` epic mode CHECK-E06.
+
+### Step C7 — Create Member Subdirectories + Back-Pointer States
+
+After the manifest validates and EPIC.md is written, create one subdirectory per member feature
+so the navigator and resolver can see them before any stage runs. For each `features[].name`:
+
+1. Create `{specsDir}/{epic}/{feature}/`.
+2. Write `{specsDir}/{epic}/{feature}/.pipeline-state.json` conforming to
+   `references/pipeline-state-schema.json`, carrying:
+   - `epic`: `"{epic}"` — the back-pointer.
+   - `currentStage`: `"forge-1-prd"` — the next actionable stage for the member.
+   - `stages["forge-0-epic"]`: `{ "status": "complete", "version": 1, "completedAt": "<ts>" }`
+     — recording that the epic stage seeded this member.
+   - No other stages (all other stages absent/pending), exactly as a freshly-initialized
+     standalone feature. **No per-feature `status` beyond the stage entry** — the member state
+     holds derived stage progress only.
+
+For an example member state, read `references/edit-mode.md` (Member State Example section). This stub is written by hand rather than by a `state-*` verb — deliberately: no verb writes the `epic` back-pointer a brand-new member needs, so this is a sanctioned exception to the Pipeline State Protocol.
+
+The member subtree holds the **same** artifact set a standalone feature holds; only
+`.pipeline-state.json` exists at creation. No PRD/specs are authored here. The epic subtree is
+now self-contained: manifest + EPIC.md + one subdirectory per member.
+
+### Step C8 — Review, Pipeline State & Commit
+
+1. **Review.** Present a summary (epic name, N features, dependency edges, contracts) as text, then use `AskUserQuestion`: "Does this epic decomposition look right? Any feature, dependency, or contract to change before I commit?" If the user wants changes, loop back to the relevant creation step, re-compose, and re-validate.
+
+2. **Commit (Git Commit Protocol).** If `gitCommitAfterStage` is true, follow the Git Commit Protocol in shared-conventions:
+   - Stage the whole epic subtree only: `git add {specsDir}/{epic}/` — never `git add -A`. This captures `epic-manifest.json`, `EPIC.md`, and all member `.pipeline-state.json` files atomically.
+   - Commit with message `"{commitPrefix}({epic}): create epic with {N} features"`.
+   - On success, capture the commit hash for the closing message only — the epic manifest has no `commitHash` field, so nothing is written back into a committed file and the two-commit step of the Git Commit Protocol does not apply here. On failure (pre-commit hook, conflict), report and do not mark complete; never use `--amend`/`--no-verify`/`--force`.
+
+3. **Closing message — the Stage Exit Protocol.** Congratulate the user ("Epic `{epic}` created with {N} features."), then close with the Stage Exit Protocol below (single-sourced in `references/stage-exit-protocol.md`; the epic → first-PRD boundary is a full stage boundary — do not improvise a "Next steps" list). `{first-actionable-feature}` = any feature with empty `dependsOn` (or the first entry of `render-status`'s `actionable` set):
+
+**Close this stage with the Scripted Stage Exit** (contract: `references/stage-exit-protocol.md`; do not improvise a "Next steps" list). Run:
+
+```bash
+R="$(bash -c 'for d in "${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" stage-exit --feature "{epic}" --stage forge-0-epic --next-feature "{first-actionable-feature}" --specs-dir "{specsDir}" --host pi
+```
+
+Obey the DIRECTIVES it prints, in order, per the directive contract: `runInStageVerify: true` → dispatch the in-stage clean-room verify now (honoring `autoFixEligible`); `verifyGate: "standard"` → present the Standard Verify Gate; `verifyGate: "manual-print"` → print the `verifyCommand` for the user; non-empty `invalidAutoVerifyKeys` → print a one-line warning. Then **print the NEXT-STEPS block verbatim as your absolute last output — nothing after its sentinel line.**
+
+---
+
+## Edit Mode
+
+Entered from Step 0 when `{specsDir}/{epic}/epic-manifest.json` already exists (the **EXISTS**
+branch). The edit branch mutates the manifest **only** through helper mutators — atomic
+(temp file + `os.replace`) and internally re-validated, so a refused write leaves the manifest
+**byte-identical**; the skill never hand-rolls an in-place write. Every question goes through
+`AskUserQuestion`, and **every mutation is committed individually** so git history is the audit trail.
+
+For the full E1–E6 mechanics — the E1 refuse-if-invalid protocol, E2 operation→mutator table, E3
+contracts/remove-feature caveats (incl. the verbatim WARN block), E4 impact-warning rules, E5
+EPIC.md patch rule, and the E6 Observability / Pipeline State & Commit machinery
+(`.epic-state.json` schema, `updatedAt` rules, Git Commit Protocol shared with C8) — read
+`references/edit-mode.md`. For the exact `epic-manifest.py` mutator flag surface and
+per-subcommand exit-code (`0`/`1`/`2`) handling, read `references/epic-manifest-subcommands.md`.
+
+---
+
+## Error Handling
+
+The skill **never** repairs a corrupt manifest automatically and **never** proceeds past a gating
+helper exit `≥ 1`. All findings are surfaced **verbatim**. For the full condition → helper-signal →
+skill-behavior disposition table, read `references/epic-manifest-subcommands.md` (Error Handling
+section).
+
+---
+
+## Gotchas
+
+- The argument names an **epic**, not a feature — this is the only stage where that is true.
+  Member feature names come from the C2 interview, each gated through `check-name`.
+- Never eyeball the dependency graph for cycles. Compose the manifest, run `validate`, and
+  surface findings. The helper owns acyclicity, uniqueness, dangling-ref, and schema checks.
+- A charter is one paragraph, not a PRD. Redirect requirement-level detail to `forge-1-prd`.
+- Contracts have no mutator: edit `exposes`/`consumes` in the composed manifest entry, then
+  re-run `validate`.
+- All questions go through `AskUserQuestion`. Never put a question in your text output.
+
+---
+
+## 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.