@garygentry/feature-forge 0.2.8 → 0.2.10

package/adapters/copilot/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/copilot/skills/forge/forge.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).

package/adapters/copilot/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/copilot/skills/forge-1-prd/forge-1-prd.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/copilot/skills/forge-2-tech/forge-2-tech.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/copilot/skills/forge-5-loop/forge-5-loop.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/copilot/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/copilot/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/copilot/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/copilot/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/copilot/skills/forge-verify/forge-verify.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/copilot/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/cursor/.feature-forge-bundle.json

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

package/adapters/cursor/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": {