@garygentry/feature-forge 0.2.8 → 0.2.10

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

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

package/adapters/claude/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/claude/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/claude/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/claude/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/claude/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'])}")

package/adapters/claude/scripts/forge-session.py

@@ -66,6 +66,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import subprocess
 import sys
 from datetime import datetime, timezone
@@ -210,6 +211,12 @@ def next_stage(state: dict) -> str | None:
     status is not ``complete`` (a missing/pending/in-progress/stale stage all
     count as "not done"). Returns ``None`` when every production stage is
     complete (nothing left to run).
+
+    This is the derived "what runs next" value — the single source of truth for
+    the next stage. It is intentionally distinct from the stored
+    ``currentStage`` field ("where the pipeline IS"; see the schema): the next
+    stage is computed from ``stages[].status`` here, never read from
+    ``currentStage``.
     """
     for stage in PRODUCTION_STAGES:
         if _stage_status(state, stage) != _DONE_STATUS:
@@ -348,6 +355,9 @@ def build_rows(specs_dir: Path, config: dict | None = None) -> list[FeatureRow]:
         rows.append({
             "name": name,
             "epic": epic,
+            # currentStage = "where the pipeline IS" (the recorded field). When a
+            # legacy/absent state omits it, fall back to the DERIVED next stage
+            # for display only — never conflate the two elsewhere (schema O1).
             "currentStage": state.get("currentStage") or (nxt or "complete"),
             "branch": branch if isinstance(branch, str) else None,
             "updatedAt": updated if isinstance(updated, str) else None,
@@ -710,6 +720,27 @@ def doctor_report(specs_dir: Path, config_path: Path) -> dict:
         "counts": _counts(specs_dir),
         "features": features,
         "invalidAutoVerifyKeys": invalid_auto_verify_keys(config),
+        "rootSandbox": _root_sandbox_status(),
+    }
+
+
+def _root_sandbox_status() -> dict:
+    """Report the root/sandbox launch condition for forge-5-loop (issue #99).
+
+    On a hosted remote (e.g. Claude.ai) the loop runs as root, where rauf's
+    ``claude --dangerously-skip-permissions`` is refused unless ``IS_SANDBOX``
+    is set. forge-5-loop exports ``IS_SANDBOX=${IS_SANDBOX:-1}`` at launch when
+    root; this surfaces the same condition as a diagnosable check. ``geteuid``
+    is absent on Windows — treat that as non-root.
+    """
+    geteuid = getattr(os, "geteuid", None)
+    is_root = geteuid() == 0 if geteuid is not None else False
+    is_sandbox_set = os.environ.get("IS_SANDBOX") not in (None, "")
+    return {
+        "isRoot": is_root,
+        "isSandboxSet": is_sandbox_set,
+        # True only when the loop would need to supply the default at launch.
+        "loopWillSetSandbox": is_root and not is_sandbox_set,
     }
 
 
@@ -756,6 +787,16 @@ def _print_doctor(report: dict) -> None:
     invalid = report.get("invalidAutoVerifyKeys") or []
     if invalid:
         print("  ! invalid autoVerifyStages keys (ignored): " + ", ".join(invalid))
+    rs = report.get("rootSandbox") or {}
+    if rs.get("isRoot"):
+        if rs.get("isSandboxSet"):
+            print("root/sandbox: running as root; IS_SANDBOX already set — loop launch OK")
+        else:
+            print(
+                "root/sandbox: running as root; IS_SANDBOX not set — forge-5-loop will "
+                "export IS_SANDBOX=1 at launch so rauf's "
+                "--dangerously-skip-permissions is not refused"
+            )
 
 
 # --------------------------------------------------------------------------- #
@@ -1243,13 +1284,24 @@ def _resolve_feature_dir(specs_dir: Path, feature: str, epic: str | None) -> Pat
     return flat
 
 
-def _next_steps_block(next_command: str, host: str) -> str:
+def _next_steps_block(
+    next_command: str, host: str, reconcile: dict | None = None
+) -> str:
     """Render the sentinel-terminated NEXT-STEPS block for the given host.
 
     The Claude wording uses the literal ``/clear`` slash-command; the generic
     wording is host-neutral (matching the adapter build's host-term table, so
     a non-Claude bundle invoking ``--host generic`` never instructs a fake
     slash-command).
+
+    ``reconcile`` carries the epic-backflow routing (§Epic backflow in
+    ``references/stage-exit-protocol.md``). When it marks a **blocking** request
+    (``required: true``), the fenced primary command becomes the epic reconcile
+    command and the normal next stage is demoted to a follow-up line. When it
+    marks only **non-blocking** requests (``reminder: true``), the fenced command
+    stays the normal next stage and a reminder line is appended. Either way the
+    added prose is host-neutral (no literal ``/clear``) so it survives verbatim
+    into a generic bundle.
     """
     if host == "claude":
         clear_line = (
@@ -1271,13 +1323,40 @@ def _next_steps_block(next_command: str, host: str) -> str:
             "2. Then start a fresh session and run the next stage below — or "
             "re-run the forge navigator skill to resume from disk."
         )
-    # The next-stage command goes in a fenced block so mobile/remote hosts get a
-    # native copy button (inline code is not tap-to-copy). The fence sits before
-    # the sentinel, so the sentinel remains the absolute last line.
-    command_block = f"```\n{next_command}\n```"
-    return "\n".join(
-        ["**Next steps**", clear_line, next_line, "", command_block, NEXT_STEPS_SENTINEL]
-    )
+    blocking = bool(reconcile and reconcile.get("required"))
+    # The primary actionable command goes in a fenced block so mobile/remote hosts
+    # get a native copy button (inline code is not tap-to-copy). For a blocking
+    # epic-change request the primary is the reconcile command; otherwise it is the
+    # normal next-stage command. The fence sits before the sentinel, so the
+    # sentinel remains the absolute last line.
+    fenced_command = reconcile["command"] if blocking else next_command
+    lines = ["**Next steps**", clear_line]
+    if blocking:
+        count = reconcile["count"]
+        plural = "s" if count != 1 else ""
+        lines.append(
+            f"2. Then reconcile the epic **before** the next stage — {count} "
+            f"blocking epic change request{plural} flagged, and proceeding would "
+            "build this feature's artifacts on a decomposition that is about to "
+            "change. Run the reconcile command below first."
+        )
+    else:
+        lines.append(next_line)
+    lines.append("")
+    lines.append(f"```\n{fenced_command}\n```")
+    if blocking and reconcile.get("deferred"):
+        lines.append(
+            f"After reconciling, continue the pipeline with: `{reconcile['deferred']}`"
+        )
+    elif reconcile and reconcile.get("reminder"):
+        count = reconcile["count"]
+        plural = "s" if count != 1 else ""
+        lines.append(
+            f"You also flagged {count} epic change{plural} to reconcile when "
+            f"convenient: `{reconcile['command']}`"
+        )
+    lines.append(NEXT_STEPS_SENTINEL)
+    return "\n".join(lines)
 
 
 def stage_exit(
@@ -1310,6 +1389,13 @@ def stage_exit(
       the fixed successor. ``--next-feature`` names the first actionable
       feature for the epic handoff; without it the runtime placeholder
       ``{first-actionable-feature}`` passes through for the skill to resolve.
+    - ``epicReconcile`` — present only when the exiting member carries
+      ``open`` ``epicChangeRequests`` (epic-backflow). ``required: true`` (any
+      ``blocksCurrent: true`` request) interposes a reconcile-first exit: the
+      NEXT-STEPS primary command becomes ``/feature-forge:forge-0-epic {epic}``
+      and the normal next stage is deferred. Only non-blocking requests set
+      ``reminder: true`` and append a non-blocking reminder line. Absent when
+      there are no open requests (common path) or the epic name is unresolvable.
 
     Read-only, deterministic, exit 0 — errors degrade to defaults, never
     crash a stage closing.
@@ -1355,6 +1441,37 @@ def stage_exit(
     )
     next_command = f"/feature-forge:{next_stage_id} {next_arg}" if next_stage_id else None
 
+    # Epic backflow routing: an exiting member may carry epic-level change requests
+    # (recorded by forge-1-prd/forge-2-tech). A `blocksCurrent: true` request means
+    # the current feature's next stage would build on a soon-to-change decomposition,
+    # so the exit interposes a reconcile-first step; only-`false` requests append a
+    # non-blocking reminder. Read-only; the common path (no open requests) is a no-op.
+    # The epic name comes from the `--epic` arg or the state's `epic` back-pointer.
+    epic_reconcile: dict | None = None
+    epic_name = epic or state.get("epic")
+    open_requests = [
+        r
+        for r in state.get("epicChangeRequests", [])
+        if isinstance(r, dict) and r.get("status") == "open"
+    ]
+    if open_requests and epic_name:
+        reconcile_command = f"/feature-forge:forge-0-epic {epic_name}"
+        blocking = [r for r in open_requests if r.get("blocksCurrent") is True]
+        if blocking:
+            epic_reconcile = {
+                "required": True,
+                "command": reconcile_command,
+                "count": len(blocking),
+                "deferred": next_command,
+            }
+        else:
+            epic_reconcile = {
+                "required": False,
+                "reminder": True,
+                "command": reconcile_command,
+                "count": len(open_requests),
+            }
+
     directives = {
         "stage": stage,
         "stageNoun": STAGE_NOUN.get(stage, stage),
@@ -1372,9 +1489,13 @@ def stage_exit(
         "cleanTree": clean_tree,
         "host": host,
     }
+    if epic_reconcile is not None:
+        directives["epicReconcile"] = epic_reconcile
     return {
         "directives": directives,
-        "nextSteps": _next_steps_block(next_command or "/feature-forge:forge", host),
+        "nextSteps": _next_steps_block(
+            next_command or "/feature-forge:forge", host, epic_reconcile
+        ),
         "sentinel": NEXT_STEPS_SENTINEL,
     }
 

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

@@ -143,6 +143,7 @@ and render from its output:
 - **Epic header:** name + `status` (active | paused | abandoned | complete).
 - **Dependency graph:** each feature with its `dependsOn`, as an arrow list or indented tree (the helper guarantees the graph is acyclic).
 - **Per-feature rows:** reuse the **existing status indicators** below (✅/✅⚠️/🔄/⬜/❌/✅🔍/⏭️/⚠️), driven by each feature's derived `stage`/`status`. Mark `blocked` features and list their `unmetDeps`.
+- **Pending epic changes:** for any feature with `openEpicChangeRequests > 0`, append a ⚠️ marker and a hint: *"N pending epic change(s) — run `/feature-forge:forge-0-epic {epic}` to reconcile."* If `blockingEpicChangeRequests > 0`, use a stronger marker (⚠️ **blocking**) and word it *"reconcile the epic **before** writing specs"* — this mirrors the pause-now vs finish-then split that stage-exit already routes on. Take these counts **only** from `render-status --json` (`features[].openEpicChangeRequests` / `.blockingEpicChangeRequests`); do not read member `.pipeline-state.json` directly for them.
 - **Actionable vs blocked:** list the `actionable` set and the recommended `nextCommand`.
 - **Rollup:** `{complete}/{total} features complete`.
 
@@ -158,12 +159,13 @@ Dependency graph:
   audit-log         (no deps)
 
 ✅ config-store     complete
-🔄 token-service    forge-3-specs (in progress)
+🔄 token-service    forge-3-specs (in progress) — ⚠️ 1 pending epic change
 ⬜ api-gateway      blocked — waiting on token-service
 ✅ audit-log        complete
 
 Actionable now: token-service
 Next: /feature-forge:forge-3-specs token-service
+⚠️ Pending epic changes: token-service (1). Run /feature-forge:forge-0-epic auth-overhaul to reconcile.
 ```
 
 All of this is reconstructed **purely from disk** — the manifest plus each member's `.pipeline-state.json`, with no in-memory state — so a fresh session renders the same dashboard. If `render-status` fails, do not render a partial dashboard; surface per the exit-1/exit-2 split in the **Feature Directory Resolution** block of `references/shared-conventions.md` (exit 1 → parse `{findings[]}` from stdout; exit 2 → surface the plain `Error:` stderr line verbatim).

package/adapters/claude/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/claude/skills/forge-1-prd/SKILL.md

@@ -81,6 +81,8 @@ Before moving to Step 4, summarize your coverage as text, then use `AskUserQuest
 
 **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 `AskUserQuestion`, 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/claude/skills/forge-2-tech/SKILL.md

@@ -92,6 +92,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 `AskUserQuestion`, 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/claude/skills/forge-5-loop/SKILL.md

@@ -197,7 +197,7 @@ Then commit this state write before launching (mandatory). The runner refuses to
 
 ### 3b. Launch Background Process
 
-Launch the loop **backgrounded** (`run_in_background: true`) 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** (`run_in_background: true`) 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
 
@@ -289,16 +289,18 @@ Update `{resolvedFeatureDir}/.pipeline-state.json`:
 
    **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 `/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`.** 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 `/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 `run_in_background`) — 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 `Monitor` tool (3d), never `sleep`/poll in the foreground. The `Monitor` 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/claude/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