@garygentry/feature-forge 0.2.8 → 0.2.10

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

@@ -28,6 +28,48 @@ python3 "$R/scripts/epic-manifest.py" validate "{epic}" --specs-dir "{specsDir}"
   manifest by hand. **Never auto-repair**, never offer an edit operation, and never proceed past
   this gate. Tell the user what is wrong and STOP.
 
+## Step E0-read — Surface Pending Epic Change Requests (backflow)
+
+Immediately after E1's validate gate passes, and **before** offering the E2 operation menu,
+scan for epic-level change requests that a member stage recorded during the pipeline (the
+backflow path — see `references/pipeline-state-schema.json` `epicChangeRequests[]`, written by
+`forge-1-prd`/`forge-2-tech`). Enumerate the manifest's feature list (already loaded in E1) and
+read each member's `{specsDir}/{epic}/{member}/.pipeline-state.json`, collecting every
+`epicChangeRequests[]` entry with `status: "open"`. If a member state is missing or unreadable,
+report it and continue with the rest — do **not** abort edit mode over one bad member file (mirror
+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 `AskUserQuestion` to offer **Apply**,
+**Dismiss**, or **Skip for now**:
+
+- **Apply — simple kinds (`add-feature`, `redep`):** pre-fill the matching E2 operation and flow
+  through E3→E4→E5→E6 unchanged. `add-feature` seeds the new feature's charter from the request's
+  `rationale` (the user still edits `exposes`/`consumes`/`dependsOn` before commit, exactly as
+  C3/C4/C5); `redep` pre-fills `set-dep {epic} {target} --depends-on "…"`. The existing E4 impact
+  warning fires normally — a `blocksCurrent` boundary change naturally trips it, which is correct.
+- **Apply — composite kinds (`move-boundary`, `split`):** there is no single mutator (v1). Walk the
+  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
+  `AskUserQuestion`; 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
+  visible in the navigator/verify (once Phase 2 surfacing lands).
+
+**On a successful Apply** (mutator exit 0, or the guided-manual sequence confirmed), flip the
+**source** request's `status` from `"open"` to `"applied"` in its member `.pipeline-state.json`,
+using the same atomic temp-file + `os.replace` write the skill uses for any state edit. The E6 git
+step already stages the whole `{specsDir}/{epic}/` subtree, so the flipped member state is captured
+in the **same commit** as the manifest mutation — no new commit machinery. If a **Dismiss** is the
+only action taken (no manifest mutation follows), still commit the member-state change under the
+standard edit-mode message form, e.g. `forge({epic}): dismiss epic change request`.
+
+E0-read is **read-then-offer** — it never auto-applies. Every apply still passes through E3/E4 with
+explicit human confirmation, preserving the human-approves-every-mutation invariant. If **no** open
+requests exist, say nothing and proceed straight to E2.
+
 ## Step E2 — Choose Operation
 
 Use `AskUserQuestion` to offer the edit operations, each mapping to one helper mutator:

package/adapters/codex/skills/forge-1-prd/SKILL.md

@@ -80,6 +80,8 @@ Before moving to Step 4, summarize your coverage as text, then use the host's qu
 
 **Parking lot:** If the user raises a concern that belongs to a different pipeline stage, acknowledge it and note it in the pipeline state's `notes` field: "Good point — I've noted that for the [tech spec/implementation specs]. Let's continue with [current stage]."
 
+**Epic-level concern (backflow):** The parking lot above is for concerns about a *later stage of THIS feature*. If instead the interview reveals the **epic decomposition itself** is wrong — a **sibling feature must be added**, a **frozen boundary between features must move**, a feature must **split**, or a **dependency edge is wrong** — that is an *epic-level* concern and does **not** go in `notes`. It only applies when this feature is an epic member (its `.pipeline-state.json` has an `epic` back-pointer); for a standalone feature there is no epic to reconcile, so treat the concern as same-feature or out of scope. To record one, append an entry to the member state's `epicChangeRequests[]` array (same direct-edit path as `notes`; schema in `references/pipeline-state-schema.json`): `kind` (`add-feature`|`redep`|`move-boundary`|`split`), `target`, `rationale`, `raisedBy: "forge-1-prd"`, `raisedAt` (ISO-8601 UTC), `status: "open"`, and `blocksCurrent`. Set `blocksCurrent: true` when the change alters a contract (`exposes`/`consumes`) or dependency edge this feature relies on for its *next* stage (proceeding would build specs on a soon-to-change decomposition); `false` for a peer/downstream change this feature does not consume. When the change touches a contract/dep edge and the classification is genuinely ambiguous, confirm `blocksCurrent` with a single the host's question mechanism, defaulting to `true` (a false negative silently diverges two members' contracts). **Do not** edit `epic-manifest.json` here — recording is not applying; only `/feature-forge:forge-0-epic` edit mode mutates the epic. Then acknowledge without blocking: "That's an epic-level change — I've recorded it so `forge-0-epic` can reconcile it. [Blocking: We'll want to reconcile the epic before writing specs. | Non-blocking: We can finish this feature first and reconcile when convenient.]" and continue the interview.
+
 ## Step 4: Write the PRD
 
 Once the interview is thorough, write `{resolvedFeatureDir}/PRD.md` following the structure in `references/prd-template.md`.

package/adapters/codex/skills/forge-2-tech/SKILL.md

@@ -91,6 +91,8 @@ Interview the user about technology decisions. Unlike the PRD interview, here yo
 
 **Parking lot:** If the user raises a concern that belongs to a different pipeline stage (e.g., backlog granularity, documentation format), acknowledge it and note it in the pipeline state's `notes` field: "Good point — I've noted that for the [specs/backlog/docs stage]. Let's continue with the tech spec."
 
+**Epic-level concern (backflow):** The parking lot above is for concerns about a *later stage of THIS feature*. If instead the design reveals the **epic decomposition itself** is wrong — a **sibling feature must be added**, a **frozen boundary between features must move**, a feature must **split**, or a **dependency edge is wrong** — that is an *epic-level* concern and does **not** go in `notes`. It only applies when this feature is an epic member (its `.pipeline-state.json` has an `epic` back-pointer); for a standalone feature there is no epic to reconcile. To record one, append an entry to the member state's `epicChangeRequests[]` array (same direct-edit path as `notes`; schema in `references/pipeline-state-schema.json`): `kind` (`add-feature`|`redep`|`move-boundary`|`split`), `target`, `rationale`, `raisedBy: "forge-2-tech"`, `raisedAt` (ISO-8601 UTC), `status: "open"`, and `blocksCurrent`. Set `blocksCurrent: true` when the change alters a contract (`exposes`/`consumes`) or dependency edge this feature relies on for its *next* stage — proceeding to specs would build on a soon-to-change decomposition (this is the point of no cheap return, so bias toward `true`); `false` for a peer/downstream change this feature does not consume. When a contract/dep edge is touched and the classification is ambiguous, confirm `blocksCurrent` with a single the host's question mechanism, defaulting to `true`. **Do not** edit `epic-manifest.json` here — recording is not applying; only `/feature-forge:forge-0-epic` edit mode mutates the epic. Then acknowledge without blocking and continue the tech spec.
+
 ### Key Decision Areas to Cover
 
 Work through these areas across multiple turns, grouping related areas (1-2 per message):

package/adapters/codex/skills/forge-5-loop/SKILL.md

@@ -196,7 +196,7 @@ Then commit this state write before launching (mandatory). The runner refuses to
 
 ### 3b. Launch Background Process
 
-Launch the loop **backgrounded** (the host's background-execution mechanism) so it survives session end and does not block the session. For a runner that **persists its own structured event file** (the default — rauf writes `{stateDir}/events.ndjson` natively and rotates it per run), launch the **plain `runCommand`** with **no stdout redirect** and supervise the runner's **native** `events.ndjson` directly; do **not** redirect `--ndjson` into `{stateDir}` (it is redundant and collides with the runner's own writer — see `references/runner-contract.md`). Only a stdout-only runner (no native event file) uses `eventStreamCommand`, redirected to a file **outside** `{stateDir}`. The background task's exit notification is the single authoritative terminal signal (Step 4). Loop runs can take significant time (minutes to hours depending on backlog size). For the exact launch commands (incl. the `mkdir -p` state-dir guard) and the self-persisting vs. stdout-only detail, read `references/runner-contract.md`.
+Launch the loop **backgrounded** (the host's background-execution mechanism) so it survives session end and does not block the session. For a runner that **persists its own structured event file** (the default — rauf writes `{stateDir}/events.ndjson` natively and rotates it per run), launch the **plain `runCommand`** with **no stdout redirect** and supervise the runner's **native** `events.ndjson` directly; do **not** redirect `--ndjson` into `{stateDir}` (it is redundant and collides with the runner's own writer — see `references/runner-contract.md`). Only a stdout-only runner (no native event file) uses `eventStreamCommand`, redirected to a file **outside** `{stateDir}`. The background task's exit notification is the single authoritative terminal signal (Step 4). Loop runs can take significant time (minutes to hours depending on backlog size). For the exact launch commands (incl. the `mkdir -p` state-dir guard and the root→`IS_SANDBOX` sandbox guard) and the self-persisting vs. stdout-only detail, read `references/runner-contract.md`.
 
 ### 3c. Inform User
 
@@ -288,17 +288,19 @@ Update `{resolvedFeatureDir}/.pipeline-state.json`:
 
    **Host / clean-room fallback (not a user-selectable option):** if the question mechanism, the host's subagent mechanism, or the `forge-verifier` subagent is unavailable, do **not** run clean-room — degrade to printing `/feature-forge:forge-verify {feature} impl` 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 your session / start a fresh session.** 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 your session / start a fresh session for you — you have to run it yourself.**
-3. **Then run `/feature-forge:forge-1-prd {chosen}`** in the fresh session — or re-run `/feature-forge:forge` to let the navigator resume from disk.
+3. **Then run the next command** in the fresh session — or re-run `/feature-forge:forge` to let the navigator resume from disk:
+
+   ```
+   /feature-forge:forge-1-prd {chosen}
+   ```
 
 ## Gotchas
 
 - **Plugin-root discovery (1b-epic helper) covers installed paths, not workspace-dev checkouts.** The `forge-root.sh` search in 1b-epic probes `~/.claude/skills/feature-forge`, `~/.claude/plugins/cache/*/feature-forge/*` (marketplace-cache installs), `~/.claude/plugins/*/feature-forge`, and `./.agents/skills/feature-forge` — the locations of an **installed** plugin. A feature-forge **source checkout** (e.g. `~/workspace/feature-forge`) is not on that list, so the helper exits "cannot locate plugin root." That is expected in a dev environment, not a bug; run the epic-manifest script from the checkout directly (`python3 <checkout>/scripts/epic-manifest.py …`). The bootstrap prelude wraps its candidate loop in `bash -c` so the `~/.claude/plugins/*/feature-forge` glob is zsh-safe: an empty expansion no longer aborts the loop under zsh's `nomatch`.
 - `{backlogDir}` is a **directory path**, not a file path. Pass `specs/auth`, not `specs/auth/backlog.json`.
-- rauf resolves `RAUF.md` with fallback: checks `{backlogDir}/.rauf/RAUF.md` first, then the project's `.rauf/RAUF.md`. As long as the runner is installed in the project, the prompt template will be found.
-- State files (state.json, {loopRunner.logFile}, etc.) are created at `{backlogDir}/{loopRunner.stateDir}/` — this is within the feature's spec directory and is expected. State is isolated per backlog dir, so concurrent features don't collide.
-- If the session disconnects during a long-running loop, the runner process continues independently. The user can check results later with the status / list commands.
+- rauf resolves `RAUF.md` with fallback (`{backlogDir}/.rauf/RAUF.md` first, then the project's `.rauf/RAUF.md`) — found as long as the runner is installed in the project. State files (state.json, {loopRunner.logFile}, etc.) are created at `{backlogDir}/{loopRunner.stateDir}/`, within the feature's spec directory (expected) and isolated per backlog dir, so concurrent features don't collide.
+- If the session disconnects during a long-running loop, the runner process continues independently — the user can check results later with the status / list commands. If a previous run left a stale lock, the user may need to pass `--force` to clear it (rauf reports this error clearly).
 - Never run the run command in the foreground (without the host's background-execution mechanism) — it blocks and will hit the Bash tool timeout for any non-trivial backlog. "Don't block the foreground" is NOT "stay silent": supervise via the host's monitoring mechanism (3d), never `sleep`/poll in the foreground. The host's monitoring mechanism must use `persistent: true` (not a bounded `timeout_ms`), watch the **structured** surface (`events.ndjson`), and never filter on raw `RAUF_*` tokens — they appear in agent prose and false-match. A `needs_human`/`blocked`/`review` signal does **not** pause the loop — the runner sets the item aside and keeps going; surface it live but don't tell the user the loop is waiting. See `references/runner-contract.md` for the full monitoring rules.
-- If a previous loop run left a stale lock, the user may need to pass `--force` to clear it. rauf will report this error clearly.
 - The version gate (1c) uses the `--json` form on purpose; never parse `rauf version`'s human output.
 - **Implementation artifacts must not cite specs.** The loop should **read** the specs and `backlog.json` freely — they are the source of truth for what to build, and the backlog rightly references specs for provenance. But the artifacts the loop **writes into the target repo** (source code, generated `SKILL.md`/agent files, configs, code comments) must be **self-contained**: they must NOT reference feature-forge spec files (no `See specs/{feature}/NN-*.md`, no "source spec" provenance notes in shipped output). Specs are pre-implementation inputs that may be archived or deleted once the feature ships; the implementation must stand on its own. This applies only to shipped implementation output — never to the backlog or spec documents, which should keep citing specs.
 

package/adapters/codex/skills/forge-5-loop/references/result-reporting.md

@@ -16,7 +16,11 @@ Loop completed for {feature}. All {N} items implemented successfully.
 
 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 `/feature-forge:forge-6-docs {feature}`** — in this warm session, or a fresh one if you prefer.
+3. **Then run the next command** — in this warm session, or a fresh one if you prefer:
+
+   ```
+   /feature-forge:forge-6-docs {feature}
+   ```
 
 **Runner review pass.** A review flag (e.g. rauf's `--review`) makes the runner run
 a post-loop review that **auto-creates and implements fix items** rather than handing

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

@@ -101,6 +101,13 @@ default / `claude-cli` path skips this guard (the aliases are valid there).
 > rauf `author-backlog` skill to keep `model` **provider-neutral** by default (or to
 > document that writing a tier alias binds the backlog to Claude agents). That lives
 > in the separate rauf plugin/repo, not feature-forge; tracked as a follow-up.
+>
+> **Follow-up (out of scope here — rauf repo).** The durable fix for the root/sandbox
+> refusal (see "Root/sandbox env guard" under Step 3b) is for **rauf itself** to honor
+> `IS_SANDBOX` when it launches `claude --dangerously-skip-permissions` as root (or to
+> detect root+flag-refused and emit a clear error instead of an opaque circuit-break).
+> feature-forge's launch-time export is the mitigation; the upstream fix lives in the
+> rauf plugin/repo. Track as a follow-up.
 
 ## Optional flags catalog (Step 2d, rauf)
 
@@ -131,6 +138,19 @@ session, then supervise it live via the runner's structured event file.
 > changes after that commit, surface it and let the user commit/stash or pass
 > `--force`; never auto-pass `--force`.
 
+> **Root/sandbox env guard.** On a hosted remote (e.g. Claude.ai) the loop often runs
+> **as root**. rauf's default Claude launch is `claude -p --dangerously-skip-permissions
+> …`, which the Claude CLI **refuses under root unless `IS_SANDBOX` is set** — the remote
+> container is a legitimate ephemeral sandbox, but without the flag every spawn exits and
+> rauf circuit-breaks (*"3 consecutive infra failures — halting"*) with no hint of the
+> cause. So when — and only when — the launcher is root (`[ "$(id -u)" = 0 ]`), export
+> `IS_SANDBOX="${IS_SANDBOX:-1}"` in front of the launch (an explicitly-set value is
+> honored; the `:-1` only supplies a default). Non-root/local runs are unaffected — the
+> guard is a no-op. **Surface a one-line note** when you set it — e.g. *"running as root →
+> setting IS_SANDBOX=1 so the sandboxed runner can use --dangerously-skip-permissions"* —
+> so the behavior is never silent. `forge-session.py doctor` also reports this condition.
+> Both launch commands below already carry the guard.
+
 **Do NOT redirect the run's stdout into `{loopRunner.stateDir}`.** rauf **persists
 its own** `{stateDir}/events.ndjson` (structured) and `{stateDir}/{logFile}` (human)
 natively, and **rotates** them at the start of every run (the prior run's files are
@@ -150,7 +170,7 @@ rotation timing. So:
   (Step 3d). Guard the very first run with the state dir:
 
   ```
-  mkdir -p {backlogDir}/{loopRunner.stateDir} && {rendered runCommand}
+  mkdir -p {backlogDir}/{loopRunner.stateDir} && { [ "$(id -u)" = 0 ] && export IS_SANDBOX="${IS_SANDBOX:-1}" || true; } && {rendered runCommand}
   ```
 
   (Note: the `--ndjson` stdout stream and `loopRunner.eventStreamCommand` are **not**
@@ -160,7 +180,7 @@ rotation timing. So:
   collide with any native file or be swept into `archive/`, then Monitor that file:
 
   ```
-  mkdir -p {backlogDir}/{loopRunner.stateDir} && {rendered eventStreamCommand} > {backlogDir}/forge-events.ndjson 2>&1
+  mkdir -p {backlogDir}/{loopRunner.stateDir} && { [ "$(id -u)" = 0 ] && export IS_SANDBOX="${IS_SANDBOX:-1}" || true; } && {rendered eventStreamCommand} > {backlogDir}/forge-events.ndjson 2>&1
   ```
 
 The background task's exit notification remains the single authoritative terminal

package/adapters/codex/skills/forge-bootstrap/references/templates/hygiene/AGENTS.md

@@ -22,3 +22,14 @@ This project was scaffolded by forge-bootstrap. To continue development:
 - Documents under `specs/` (PRDs, tech specs, numbered implementation specs) establish the backlog. They are **not** kept in sync with the code as it evolves.
 - Do not flag or "fix" divergence between a finalized spec and the implementation — code is the source of truth for behavior.
 - It's fine for `specs/` artifacts and `backlog.json` to reference specs for provenance, but implementation artifacts (source code, generated skills/agents, configs, docs) must not reference spec files, which may be archived or deleted after a feature ships.
+
+## Tooling feedback (feature-forge / rauf)
+
+This project is driven by the feature-forge pipeline and the rauf loop. Help improve those tools by capturing friction as you hit it — papercuts included, not just outright bugs.
+
+- **When to flag:** any forge/rauf command, skill, agent, or prompt that is confusing, buggy, missing a capability, forces a workaround, or produces a surprising result.
+- **Where to file** — route by which tool the friction is with:
+  - feature-forge (pipeline stages, forge skills/agents): https://github.com/garygentry/feature-forge/issues
+  - rauf (the autonomous loop runner, `rauf` CLI): https://github.com/garygentry/rauf/issues
+- **How:** capture it while fresh — *what you ran / what you expected / what actually happened / a fix idea* — then propose a titled issue and file it with `gh issue create` **on the human's go-ahead, not silently.**
+- **In an autonomous rauf iteration:** do **not** open issues mid-loop. Note the friction in `progress.md` for the human to triage later.

package/adapters/codex/skills/forge-bootstrap/references/templates/hygiene/CLAUDE.md

@@ -23,3 +23,14 @@ This project was scaffolded by forge-bootstrap. To continue development:
 - Documents under `specs/` (PRDs, tech specs, numbered implementation specs) establish the backlog. They are **not** kept in sync with the code as it evolves.
 - Don't flag or "fix" divergence between a finalized spec and the implementation — code is the source of truth for behavior.
 - It's fine for `specs/` artifacts and `backlog.json` to reference specs for provenance, but implementation artifacts (source code, generated skills/agents, configs, docs) must not reference spec files, which may be archived or deleted after a feature ships.
+
+## Tooling feedback (feature-forge / rauf)
+
+I'm driving this project with the feature-forge pipeline and the rauf loop, and I want to keep improving them. When you hit friction with either tool, help me capture it — papercuts included, not just outright bugs.
+
+- **When to flag:** any forge/rauf command, skill, agent, or prompt that is confusing, buggy, missing a capability, forces a workaround, or produces a surprising result.
+- **Where to file** — route by which tool the friction is with:
+  - feature-forge (pipeline stages, `/feature-forge:*`, forge skills/agents): https://github.com/garygentry/feature-forge/issues
+  - rauf (the autonomous loop runner, `rauf` CLI): https://github.com/garygentry/rauf/issues
+- **How:** capture it while fresh — *what you ran / what you expected / what actually happened / a fix idea* — then propose a titled issue and file it with `gh issue create` **once I give the go-ahead, not silently.**
+- **In an autonomous rauf iteration:** don't open issues mid-loop. Note the friction in `progress.md` for me to triage later.

package/adapters/codex/skills/forge-verify/SKILL.md

@@ -161,9 +161,9 @@ Load into context ALL artifacts for this feature based on mode:
 
 Read `references/verification-checklists.md` for the detailed checklists per mode. Execute every check. Do not skip checks because things "look fine." That same reference also holds the relocated **Findings Document Template (Step 4)**, the worked **Example Findings (Step 4)**, and the **Epic Mode State Write Detail (Step 6)** sections used later in this skill.
 
-Each check in `verification-checklists.md` has a unique ID (CHECK-P01, CHECK-T01, CHECK-S01, CHECK-B01, etc.). As you execute each check, record its ID and result (pass/fail/not-applicable). After completing all checks, report the total: "Executed N of M checks. Results: X pass, Y fail, Z not-applicable." If your count is significantly below the expected total for the mode (prd: ~15 checks, tech: ~15 checks, specs: ~38 checks, backlog: ~25 checks, impl: ~20 checks, epic: ~8 checks), you likely skipped checks — go back and complete them.
+Each check in `verification-checklists.md` has a unique ID (CHECK-P01, CHECK-T01, CHECK-S01, CHECK-B01, etc.). As you execute each check, record its ID and result (pass/fail/not-applicable). After completing all checks, report the total: "Executed N of M checks. Results: X pass, Y fail, Z not-applicable." If your count is significantly below the expected total for the mode (prd: ~15 checks, tech: ~15 checks, specs: ~38 checks, backlog: ~25 checks, impl: ~20 checks, epic: ~9 checks), you likely skipped checks — go back and complete them.
 
-**Epic mode dispatch.** Epic mode is a small (~8-check) checklist, so per the single-vs-parallel rule above, dispatch a **single `forge-verifier`** via the host's subagent mechanism, passing the epic name and `mode=epic`. The verifier runs CHECK-E01..E08 from the `## Epic Mode Checklist` in `references/verification-checklists.md` (E01/E02/E03/E08 are delegated to `epic-manifest.py validate`/`check-name`; E04–E07 are verifier judgment) and returns its findings.
+**Epic mode dispatch.** Epic mode is a small (~9-check) checklist, so per the single-vs-parallel rule above, dispatch a **single `forge-verifier`** via the host's subagent mechanism, passing the epic name and `mode=epic`. The verifier runs CHECK-E01..E09 from the `## Epic Mode Checklist` in `references/verification-checklists.md` (E01/E02/E03/E08 are delegated to `epic-manifest.py validate`/`check-name`; E04–E07 and E09 are verifier judgment) and returns its findings.
 
 ### Important: Be Specific, Not General
 

package/adapters/codex/skills/forge-verify/references/verification-checklists.md

@@ -223,6 +223,18 @@ python3 "$R/scripts/epic-manifest.py" validate "{epic}" --specs-dir "{specsDir}"
   `.pipeline-state.json` `epic` value names this epic, and every `features[]` entry has a
   matching member directory. On conflict the **manifest wins** (REQ-STATE-01); report, do
   not auto-repair.
+- [ ] **CHECK-E09**: **open epic change requests** — any member whose `.pipeline-state.json`
+  carries `epicChangeRequests[]` entries with `status: "open"` is surfaced as a **non-fatal**
+  finding (one per open request). Severity keys off `blocksCurrent`: a **blocking** request →
+  `inconsistency` (the epic decomposition and an in-flight member disagree; specs written now
+  would build on a soon-invalid premise), a **non-blocking** request → `improvement` (a
+  peer/downstream change to reconcile when convenient). Name the request's `kind`, `target`,
+  and `rationale`, and point at `/feature-forge:forge-0-epic {epic}` to reconcile. **Report, do
+  not repair** (same posture as CHECK-E07). Which members have open requests comes from the
+  same `render-status --json` counts the navigator uses (`features[].openEpicChangeRequests` /
+  `.blockingEpicChangeRequests`); the per-request `kind`/`target`/`rationale` detail is read
+  from the member `.pipeline-state.json` already loaded in Step 2. This is the pre-emptive
+  surface for the divergence class CHECK-E06/E07 otherwise catch only after the fact.
 
 ## Findings Document Template (Step 4)
 

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

@@ -1,6 +1,6 @@
 {
   "name": "feature-forge",
-  "version": "0.12.3",
+  "version": "0.12.5",
   "agent": "copilot",
   "generatedBy": "python3 scripts/build-adapters.py"
 }

package/adapters/copilot/references/pipeline-state-schema.json

@@ -33,12 +33,88 @@
     "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": "The stage currently in progress or next to start"
+      "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": {

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

@@ -151,6 +151,46 @@ outstanding, so the navigator catch-up can fire later.
 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
+  (`/feature-forge: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` (schema in
+`references/pipeline-state-schema.json`; same direct-edit path as `notes` /
+`epicChangeRequests[]`): `question` (phrased for the target stage), optional `rationale`
+and `targetStage`, `raisedBy` (this stage), `raisedAt` (ISO-8601 UTC), `status: "open"`.
+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
@@ -181,7 +221,11 @@ Slots: `{stage}` (a lowercase noun phrase), `{verify-command}`, `{next-command}`
 
    **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 `{next-command}`** in the fresh session — or re-run `/feature-forge:forge` to let the navigator resume from disk.
+3. **Then run the next command** in the fresh session — or re-run `/feature-forge:forge` to let the navigator resume from disk:
+
+   ```
+   {next-command}
+   ```
 <!-- END: standard-exit-block -->
 
 ---
@@ -206,5 +250,9 @@ by the loop itself, so this block defers rather than re-presenting a gate.
 
 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 `{next-command}`** — in this warm session, or a fresh one if you prefer.
+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/copilot/references/templates/specs-hygiene/AGENTS.md

@@ -20,4 +20,13 @@ traceability matrices, and per-feature `backlog.json` files).
   reference files under `specs/`, which may be archived or deleted after a feature
   ships.
 
+## Tooling feedback
+
+Friction with the feature-forge pipeline or the rauf loop — anything confusing, buggy, or
+missing? Capture it while fresh and file it (feature-forge →
+https://github.com/garygentry/feature-forge/issues, rauf →
+https://github.com/garygentry/rauf/issues). See the project-root `AGENTS.md` "Tooling
+feedback" section for the full flow. In an autonomous rauf iteration, note it in
+`progress.md` instead of opening an issue mid-loop.
+
 This file was generated by feature-forge. Edit or remove it to suit your project.

package/adapters/copilot/references/templates/specs-hygiene/CLAUDE.md

@@ -19,4 +19,13 @@ traceability matrices, and per-feature `backlog.json` files).
   skills/agents, configs, docs) should be self-contained and should **not** reference
   files under `specs/`, which may be archived or deleted after a feature ships.
 
+## Tooling feedback
+
+Friction with the feature-forge pipeline or the rauf loop — anything confusing, buggy, or
+missing? Help me capture it while fresh and file it (feature-forge →
+https://github.com/garygentry/feature-forge/issues, rauf →
+https://github.com/garygentry/rauf/issues). See the project-root `CLAUDE.md` "Tooling
+feedback" section for the full flow. In an autonomous rauf iteration, note it in
+`progress.md` instead of opening an issue mid-loop.
+
 This file was generated by feature-forge. Edit or remove it to suit your project.

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

@@ -99,6 +99,13 @@ class FeatureStatus(TypedDict):
         blocked: True if any entry in unmetDeps is non-empty.
         unmetDeps: Names of this feature's direct dependencies that are not yet
             complete-for-orchestration (00 §7). Empty when actionable or complete.
+        openEpicChangeRequests: Count of this member's ``epicChangeRequests``
+            entries with ``status == "open"`` — epic-level change requests raised
+            by a member stage that forge-0-epic edit mode has not yet reconciled.
+            0 for standalone features or members with no pending requests.
+        blockingEpicChangeRequests: The subset of ``openEpicChangeRequests`` with
+            ``blocksCurrent == true`` (pause-now, reconcile-before-specs). Always
+            ``<= openEpicChangeRequests``.
     """
 
     name: str
@@ -106,6 +113,8 @@ class FeatureStatus(TypedDict):
     status: DerivedStatus
     blocked: bool
     unmetDeps: list[str]
+    openEpicChangeRequests: int
+    blockingEpicChangeRequests: int
 
 
 class Rollup(TypedDict):
@@ -836,12 +845,26 @@ def derive_status(feature_dir: Path) -> FeatureStatus:
         )
         derived = "in-progress" if started else "not-started"
 
+    # Epic-backflow surfacing (Phase 2): count open epicChangeRequests from the
+    # same state dict. A missing/torn state, a non-list value, or non-dict items
+    # count as 0 — a malformed request must never crash the dashboard, mirroring
+    # the torn-state -> not-started tolerance above.
+    requests = state.get("epicChangeRequests", [])
+    open_reqs = [
+        r for r in requests
+        if isinstance(r, dict) and r.get("status") == "open"
+    ] if isinstance(requests, list) else []
+    open_count = len(open_reqs)
+    blocking_count = sum(1 for r in open_reqs if r.get("blocksCurrent") is True)
+
     return {
         "name": name,
         "stage": stage,
         "status": derived,
         "blocked": False,
         "unmetDeps": [],
+        "openEpicChangeRequests": open_count,
+        "blockingEpicChangeRequests": blocking_count,
     }
 
 
@@ -1212,6 +1235,9 @@ def _print_status_table(status: RenderStatus) -> None:
         line = f"  - {row['name']}: {row['status']} (stage {row['stage']})"
         if row["blocked"]:
             line += f" — blocked on {', '.join(row['unmetDeps'])}"
+        if row["openEpicChangeRequests"]:
+            marker = "⚠️ BLOCKING" if row["blockingEpicChangeRequests"] else "⚠️"
+            line += f" — {marker} {row['openEpicChangeRequests']} pending epic change(s)"
         print(line)
     if status["actionable"]:
         print(f"Actionable: {', '.join(status['actionable'])}")