@garygentry/feature-forge 0.3.6 → 0.3.8

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

@@ -1,7 +1,7 @@
 ---
 # 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 /feature-forge: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.'
+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 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
@@ -13,7 +13,7 @@ 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 the host's question mechanism.
+question in inline prose — every question goes through host's question mechanism.
 
 ## Prerequisites
 
@@ -38,7 +38,7 @@ checks but still load any on-disk artifacts.
 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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${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/epic-manifest.py" <subcommand> ... --specs-dir "{specsDir}"
 ```
@@ -74,7 +74,7 @@ Resolve the epic subtree path `{specsDir}/{epic}/` and decide which branch to ru
    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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${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/epic-manifest.py" check-name "{epic}" --specs-dir "{specsDir}"
    ```
@@ -99,7 +99,7 @@ than prompting again.
 ### Step C1 — Epic Framing Interview
 
 Output context as text (what an epic is, that a decomposition interview will follow). Then
-call the host's question mechanism to elicit:
+call host's question mechanism to elicit:
 
 1. **Epic goal / problem** — the overarching change being decomposed. Becomes the EPIC.md
    "Overall Goal" narrative and seeds the manifest `description`.
@@ -112,13 +112,13 @@ The epic `name` is the validated CLI argument from Step 0 — do NOT prompt for
 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
-the host's question mechanism 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.
+host's question mechanism 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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${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/epic-manifest.py" check-name "{feature}" --specs-dir "{specsDir}"
 ```
@@ -132,7 +132,7 @@ 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 the host's question mechanism batch (one feature at a time,
+For each confirmed feature, run a focused host's question mechanism batch (one feature at a time,
 2–3 questions per call) eliciting:
 
 - **Charter** — a single paragraph: scope statement + contract obligations. This is a
@@ -151,7 +151,7 @@ the structured arrays are the source of truth; EPIC.md renders them as prose lat
 
 ### Step C4 — Dependency-Edge Interview
 
-For each feature, use the host's question mechanism: "Which sibling features must be complete before this
+For each feature, use host's question mechanism: "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.
@@ -179,7 +179,7 @@ For the *initial* creation write the skill writes the file directly — atomic g
 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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${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/epic-manifest.py" validate "{epic}" --specs-dir "{specsDir}" --json
 ```
@@ -239,7 +239,7 @@ 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 the host's question mechanism: "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.
+1. **Review.** Present a summary (epic name, N features, dependency edges, contracts) as text, then use host's question mechanism: "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.
@@ -253,7 +253,7 @@ Determine `{verify-capability}` per the **Host and capability determination** se
 **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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${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 --feature "{epic}" --stage forge-0-epic --next-feature "{first-actionable-feature}" --specs-dir "{specsDir}" --host generic --verify-capability "{verify-capability}"
 ```
@@ -268,7 +268,7 @@ Entered from Step 0 when `{specsDir}/{epic}/epic-manifest.json` already 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
-the host's question mechanism, and **every mutation is committed individually** so git history is the audit trail.
+host's question mechanism, 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
@@ -299,7 +299,7 @@ section).
 - 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 the host's question mechanism. Never put a question in your text output.
+- All questions go through host's question mechanism, never text. Rung 2/3: Interaction Capability Ladder.
 
 ---
 
@@ -307,6 +307,6 @@ section).
 
 This skill was authored Claude-first; the body above refers to "the host's question mechanism", "the host's subagent mechanism", and "the host's background-execution mechanism". On Codex:
 
-- **User input:** Codex has no structured question tool — ask the question directly and wait for the user's reply before proceeding. Never skip a required question or assume an answer.
+- **User input:** Codex has no structured question tool. Which rung you are on is **not** observable from inside the session — a `codex exec` run looks exactly like an interactive one — so read it from the Interaction Capability Ladder's `interaction-mode` record instead of judging it. Interactive session — ask the question directly and wait for the reply; never assume an answer. Non-interactive — don't wait: take the Interaction Capability Ladder's declared conservative default, state it in your output, and use `no-default: abort — <question> requires a human answer` for an interview question with no sane default (`references/shared-conventions.md`).
 - **Subagents:** spawn a Codex subagent using the named custom agent under `.codex/agents/<name>.toml`. Codex spawns a subagent only when explicitly asked; if the custom agent is unavailable, run that step inline yourself.
 - **Background / monitoring:** run long-lived runner commands in your shell session and report progress as it arrives — there is no Claude-style background or monitoring tool to arm.

package/adapters/codex/skills/forge-0-epic/references/edit-mode.md

@@ -9,14 +9,18 @@ Entered from Step 0 when `{specsDir}/{epic}/epic-manifest.json` already exists (
 branch). The edit branch mutates the manifest **only** through helper mutators — the skill never
 hand-rolls an in-place write. Every mutator is atomic (temp file + `os.replace`) and re-validates
 the edited graph internally, so a refused write leaves the manifest **byte-identical**. Every
-question goes through the host's question mechanism.
+question goes through host's question mechanism. **Rung-3 default**
+(`references/shared-conventions.md` § Interaction Capability Ladder, "dependency / epic
+gates" and "interviews / pickers / blocking gates" classes): no question mechanism →
+STOP or `no-default: abort` per the site — never guess an edit operation or a conflict
+resolution unattended.
 
 ## Step E1 — Load + Validate, Refuse if Invalid
 
 Before offering any edit, validate the existing manifest:
 
 ```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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${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/epic-manifest.py" validate "{epic}" --specs-dir "{specsDir}" --json
 ```
@@ -40,7 +44,7 @@ report it and continue with the rest — do **not** abort edit mode over one bad
 E1's "report, never silently repair" posture).
 
 If any open requests exist, present them grouped (show `kind`, `target`, `rationale`,
-`blocksCurrent`, `raisedBy`), then for **each** request use the host's question mechanism to offer **Apply**,
+`blocksCurrent`, `raisedBy`), then for **each** request use host's question mechanism to offer **Apply**,
 **Dismiss**, or **Skip for now**:
 
 - **Apply — simple kinds (`add-feature`, `redep`):** pre-fill the matching E2 operation and flow
@@ -52,7 +56,7 @@ If any open requests exist, present them grouped (show `kind`, `target`, `ration
   user through a **guided-manual** sequence — the relevant `set-dep` and/or direct `exposes`/
   `consumes` edits on the composed manifest entries (per E3's "Contracts have no mutator" rule),
   across **both** affected features — re-validating after each step. Confirm each mutation via
-  the host's question mechanism; never batch-apply.
+  host's question mechanism; never batch-apply.
 - **Dismiss:** the user decides the epic is fine after all — flip the source request's `status` to
   `"dismissed"` (no manifest mutation). Explicit only; there is **no auto-expiry**.
 - **Skip for now:** leave the request `open`; it resurfaces on the next edit-mode entry and stays
@@ -72,7 +76,7 @@ requests exist, say nothing and proceed straight to E2.
 
 ## Step E2 — Choose Operation
 
-Use the host's question mechanism to offer the edit operations, each mapping to one helper mutator:
+Use host's question mechanism to offer the edit operations, each mapping to one helper mutator:
 
 | Operation | Helper subcommand |
 |-----------|-------------------|
@@ -123,13 +127,13 @@ status is **not** `not-started`, warn the user. Read the **live** status (never
 completion in prose):
 
 ```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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${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/epic-manifest.py" render-status "{epic}" --specs-dir "{specsDir}" --json
 ```
 
 If the operation removes, reorders-around, or re-deps a feature whose derived status is
-`in-progress` or `complete`, use the host's question mechanism with an explicit warning naming the affected
+`in-progress` or `complete`, use host's question mechanism with an explicit warning naming the affected
 in-flight/completed feature(s) and **require confirmation** before applying. Example: "`token-service`
 is already in-progress (forge-3-specs). Removing `config-store`, which it consumes `JWT_SECRET`
 from, may invalidate its in-flight specs. Proceed?" If `render-status` exits `≥ 1`, surface the
@@ -140,7 +144,7 @@ findings and STOP (do not mutate over an invalid graph).
 Patch **only** the affected feature/Contracts section(s) — the section(s) for the added, removed,
 or changed feature and any feature whose `dependsOn`/`consumes` changed — applying the §C6 mirror
 rule (one bullet per `exposes`/`consumes` entry). **Full regeneration happens only on explicit
-user request**: offer it via the host's question mechanism but default to the targeted patch. The skill keeps
+user request**: offer it via host's question mechanism but default to the targeted patch. The skill keeps
 EPIC.md in sync but does not itself diff it against the manifest — drift detection is `forge-verify`
 epic mode CHECK-E06.
 
@@ -209,7 +213,7 @@ After a successful **edit-mode mutation** — the mutator returned exit `0` **an
 **Read live status again first.** The E4 `render-status` snapshot is stale by the time you get here — it was taken *before* the mutation, so a member the edit just unblocked (or just blocked) is misreported, and the whole point of routing from live state is lost. Re-read it **after** the mutation and the commit:
 
 ```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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${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/epic-manifest.py" render-status "{epic}" --specs-dir "{specsDir}" --json
 ```
@@ -217,7 +221,7 @@ python3 "$R/scripts/epic-manifest.py" render-status "{epic}" --specs-dir "{specs
 Choosing the `--next-feature` argument from that **fresh** payload is the only routing decision this step makes; every other one belongs to the script:
 
 - **`actionable` is non-empty** → `{first-actionable-feature}` is its **first** entry, a concrete member name. Pass it as `--next-feature "{first-actionable-feature}"`. The script then resolves that member's own `.pipeline-state.json` and routes to its **first incomplete production stage**, so a member whose PRD is already written resumes at tech/specs/backlog/loop/docs — it is never sent back to `forge-1-prd`. Do **not** derive that stage yourself and do **not** read the member's state to second-guess the script.
-- **`actionable` is empty** → there is no member to hand off to. **Omit `--next-feature` entirely**; the script routes to the epic dashboard/completion view. Never substitute a stand-in for the flag value — not the literal `{first-actionable-feature}`, not the epic name, not an arbitrary member off `features[]`. An unresolved placeholder is not a member name, and the script rejects an unsafe value with exit `2`.
+- **`actionable` is empty** → there is no member to hand off to. **Omit `--next-feature` entirely**; the script decides the terminus from live epic state — a **finished** epic closes terminally (`primaryCommand: null`, nothing fenced), anything else routes to the epic dashboard. Print whichever block it emits verbatim; do not add a command to a terminal one. Never substitute a stand-in for the flag value — not the literal `{first-actionable-feature}`, not the epic name, not an arbitrary member off `features[]`. An unresolved placeholder is not a member name, and the script rejects an unsafe value with exit `2`.
 - **`render-status` exits `≥ 1`, or its payload is malformed or missing a required field** → surface every `findings[]` entry **verbatim**, then take the same no-member path: close with the epic stage exit carrying **no** `--next-feature`, so recovery lands on the epic dashboard. A failed status read is never grounds to guess a follow-up member.
 
 **Surface the script's warnings before the block.** `warnings` is part of the directive contract. When the selected member's pipeline state is missing, unreadable, malformed, or not a member of this epic, the script emits a named warning naming that member and the recovery command, and degrades **only** to `forge-1-prd {member}` on its own. Print that warning ahead of the terminal block exactly as emitted, and leave the routing where the script put it — do **not** "correct" the fallback to a later stage you inferred, and do **not** re-read the member's state to override it.

package/adapters/codex/skills/forge-0-epic/references/epic-manifest-subcommands.md

@@ -12,7 +12,7 @@ the write if it would introduce a cycle, dangling ref, duplicate, or schema viol
 flag surface (owned by 02 §7):
 
 ```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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${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; }
 # Add a feature — seeds EMPTY exposes/consumes; contracts are populated below.
 python3 "$R/scripts/epic-manifest.py" add-feature "{epic}" "{feature}" \
@@ -66,7 +66,7 @@ helper exit `≥ 1`. All findings are surfaced **verbatim**.
 
 | Condition | Helper signal | Skill behavior |
 |-----------|---------------|----------------|
-| Epic name duplicates an existing name | `check-name` exit 1 (`duplicate-name`) | STOP creation; surface finding; ask for a new name via the host's question mechanism |
+| Epic name duplicates an existing name | `check-name` exit 1 (`duplicate-name`) | STOP creation; surface finding; ask for a new name via host's question mechanism |
 | Member feature name duplicates | `check-name` exit 1 (`duplicate-name`) | Reject that name in C2 / add-feature; surface verbatim; re-prompt |
 | Unsafe name (`/`, `..`, absolute) | `check-name`/mutator exit 2 (`unsafe-name`) | Reject; surface; re-prompt |
 | Composed manifest has a cycle | `validate` exit 1 (`cycle`) | Surface verbatim; re-open the dependency interview (C4); never finalize |
@@ -74,7 +74,12 @@ helper exit `≥ 1`. All findings are surfaced **verbatim**.
 | Corrupt/unparseable manifest (edit) | `validate` exit 1 (`corrupt-json`) | Surface ALL findings verbatim; **refuse all mutation** until repaired; never auto-repair |
 | Existing manifest otherwise invalid (edit) | `validate` exit 1/2 | Surface ALL findings verbatim; **refuse all mutation** (E1) |
 | Mutator would introduce cycle/dangling ref/duplicate | mutator exit 1 | Abort the edit; manifest byte-identical (atomic refusal); surface finding |
-| Bad `--status` value | `set-status` exit 2 (argparse) | Surface; re-prompt via the host's question mechanism with the valid choices |
+| Bad `--status` value | `set-status` exit 2 (argparse) | Surface; re-prompt via host's question mechanism with the valid choices |
 | Edit affects in-flight/completed feature | `render-status` derived status (`in-progress`/`complete`) | Warn naming the affected feature(s); require confirmation before applying (E4) |
 | `render-status` over an invalid graph | `render-status` exit ≥ 1 | Surface findings; STOP (do not mutate over an invalid graph) |
 | Git commit fails | — | Report; leave state `in-progress`; never bypass hooks (`--no-verify`/`--force`) |
+
+**Rung-3 default** (`references/shared-conventions.md` § Interaction Capability Ladder,
+"dependency / epic gates" class): no question mechanism → **STOP** on every row above that
+names host's question mechanism — never invent a name or a `--status` value to keep the mutator
+moving unattended.

package/adapters/codex/skills/forge-0-epic/references/portable-root.md

@@ -12,7 +12,7 @@ against the fenced block here, byte-for-byte.
 ## Canonical bootstrap prelude
 
 ```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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${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; }
 ```
 
@@ -24,24 +24,27 @@ makes several calls, add the prelude once and reuse `$R` for each. A fresh block
 prelude (per-block re-resolution). Worked example:
 
 ```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')"
+R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${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/epic-manifest.py" render-status "{epic}" --specs-dir "{specsDir}" --json
 ```
 
 ## Invariants (do NOT "fix" these)
 
-1. **First hint is the Claude plugin-root env var; the rest are paths.** The prelude's
-   `for d in …` list leads with the `CLAUDE_PLUGIN_ROOT` env var (in default-empty `:-` form)
-   — the exact bundle dir Claude exports in every marketplace/plugin session — followed by the
-   directory-path candidates. The hint gives exact, glob-free resolution on any current/future
-   Claude layout (no version-skew window); when unset it expands to empty and is harmlessly
-   skipped, so other hosts fall through to the path candidates unchanged. This is the **one
-   sanctioned** appearance of that variable in canonical surfaces: spec-purity rule 3 allows it
-   by stripping the byte-pinned prelude before its residual-var scan (so a stray var anywhere
-   else — including the default-empty form — still fails), and `forge-agent-adapters-build`
-   translates it to `FEATURE_FORGE_ROOT` for non-Claude bundles (which `forge-root.sh` already
-   prefers). The exact literal is shown only in the fenced prelude above and audited in
+1. **Explicit `FEATURE_FORGE_ROOT` override first, then the Claude env hint, then paths.** The
+   prelude opens with a guard: if `FEATURE_FORGE_ROOT` is set but carries no
+   `scripts/forge-root.sh`, it fails loudly (`exit 2`) instead of silently falling back to
+   discovery — an operator override that does not resolve is an error, not a hint (the same rule
+   `forge-root.sh` Step 0 applies). The `for d in …` list then leads with the `FEATURE_FORGE_ROOT`
+   env var in default-empty `:-` form (the host-neutral operator override, honored on every agent)
+   followed by the `CLAUDE_PLUGIN_ROOT` env var in the same form (the exact bundle dir Claude
+   exports in every marketplace/plugin session), then the directory-path candidates. Both env hints
+   give exact, glob-free resolution; when unset each expands to empty and is harmlessly skipped, so
+   other hosts fall through to the path candidates unchanged. `CLAUDE_PLUGIN_ROOT` remains the **one
+   sanctioned** appearance of that vendor variable in canonical surfaces: spec-purity rule 3 allows
+   it by stripping the byte-pinned prelude
+   before its residual-var scan (so a stray var anywhere else — including the default-empty form —
+   still fails). The exact literal is shown only in the fenced prelude above and audited in
    `vendor-construct-inventory.md`.
 2. **First-discoverable-resolver-wins.** The `exec` inside the `$(…)` command substitution means
    the loop stops at the first directory holding an executable `forge-root.sh` and delegates ALL
@@ -64,8 +67,9 @@ python3 "$R/scripts/epic-manifest.py" render-status "{epic}" --specs-dir "{specs
 
 The prelude delegates to [`scripts/forge-root.sh`](../scripts/forge-root.sh) — the portable
 skill/plugin-root resolver. It takes no arguments, prints the absolute plugin root to stdout and
-exits `0`, or writes an actionable message to stderr and exits `1`. It resolves the root by
-self-location → candidate-root probe → plugin-root environment-variable fallback → actionable failure,
-and never sources or executes a discovered path — it only ever prints a directory string. The
+exits `0`, or writes an actionable message to stderr and exits non-zero. It resolves the root by
+explicit `FEATURE_FORGE_ROOT` override (Step 0) → self-location → candidate-root probe →
+`CLAUDE_PLUGIN_ROOT` fallback → actionable failure, and never sources or executes a discovered
+path — it only ever prints a directory string. The
 spec-purity checker (rule 5) enforces that every prelude occurrence across the canon is
 byte-identical to the fenced block in this file.