@garygentry/feature-forge 0.2.8 → 0.2.10

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

@@ -162,9 +162,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 Agent tool, 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 Agent tool, 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/claude/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/codex/.feature-forge-bundle.json

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

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

@@ -142,6 +142,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`.
 
@@ -157,12 +158,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).