@garygentry/feature-forge 0.3.8 → 0.3.9

package/README.md

@@ -74,7 +74,7 @@ Claude Code users can alternatively install via the plugin marketplace:
 
 The default loop runner is [**rauf**](https://github.com/garygentry/rauf), published as
 [`@garygentry/rauf`](https://www.npmjs.com/package/@garygentry/rauf). The installer runs a
-read-only resolvability preflight on the pin (`@garygentry/rauf@0.16.1`) and records it; pass
+read-only resolvability preflight on the pin (`@garygentry/rauf@0.17.1`) and records it; pass
 `--skip-rauf` to defer the check (e.g. offline installs). Install the rauf CLI itself with
 `npx @garygentry/rauf` or its
 [binary script](https://github.com/garygentry/rauf#install). See the

package/adapters/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "feature-forge",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "End-to-end feature development pipeline: PRD → tech spec → implementation specs → backlog → documentation, with verification gates, pipeline state tracking, and specialized subagents for verification and codebase research.",
   "author": {
     "name": "Gary Gentry"

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

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

package/adapters/claude/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/session-check.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/adapters/claude/references/forge-config-schema.json

@@ -235,8 +235,8 @@
         },
         "installHint": {
           "type": "string",
-          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.16.1 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.16.1 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
-          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.16.1), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.17.1 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.17.1 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
+          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.17.1), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
         },
         "schemaVersion": {
           "type": "string",

package/adapters/claude/references/preflight-and-self-heal.md

@@ -6,7 +6,7 @@ silent unasked mutation. It runs whenever a skill gates on `doctor`'s structured
 `checks[]` (`roadmap/self-healing-resilience.md` §5.2); today that is `forge-5-loop`'s
 gates 1c/1d (`skills/forge-5-loop/SKILL.md`), which resolve the loop runner **before**
 touching it, `forge-init`'s install preflight (`skills/forge-init/SKILL.md`), where
-neither check is a stop, and `forge-guide --doctor` (`skills/forge-guide/SKILL.md`), the
+no check is a stop, and `forge-guide --doctor` (`skills/forge-guide/SKILL.md`), the
 operator-facing repair surface, which gates nothing at all. All three are callers, not
 the procedure's scope: any skill that gates on `checks[]` follows it in full. Its seven
 ordered steps: **enumerate → cluster → consolidated prompts → record → apply → prove →

package/adapters/claude/references/ralph-loop-contract.md

@@ -40,9 +40,11 @@ defined authoritatively in rauf's
 - **A machine-readable event stream** for live supervision (`loopRunner.eventStreamCommand`,
   rauf: `loop run … --ndjson`): one JSON event per line with a stable `type`
   vocabulary — `item_completed` / `item_blocked` / `needs_human` / `signal_parsed`
-  / `loop_completed` / `loop_error` / `loop_cancelled` / `llm_stuck_warning` (a
-  circuit-breaker halt surfaces as `loop_error`) — plus a
-  derived-status JSON (`loopRunner.statusJsonCommand`, rauf: `status … --json`) and
+  / `loop_completed` / `loop_error` / `loop_cancelled` / `review_failed` /
+  `llm_stuck_warning` (a circuit-breaker halt surfaces as `loop_error`) — plus a
+  derived-status JSON (`loopRunner.statusJsonCommand`, rauf: `status … --json`;
+  forge-5-loop also reads its optional `loopState` / `lock` / `sleepUntil` /
+  `reviewPending` fields when present, and degrades to the counts when absent) and
   per-iteration telemetry with a `stuckWarning` flag (`loopRunner.watchCommand`,
   rauf: `status … --json` — the `loop watch` verb was removed in v0.5.0). `forge-5-loop` supervises the run through these,
   **not** by parsing the human log. `followCommand` / `logCommand` are

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

@@ -47,7 +47,7 @@ an epic member. Only the flags below are stage-specific; pass no others.
 |---|---|---|
 | `forge-0-epic` | `forge-0-epic` | `--next-feature "{member}"` when a concrete member exists |
 | `forge-1-prd` … `forge-4-backlog` | that stage's own id | none beyond identity/capability |
-| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation` with `--outcome partial` |
+| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation`, `review-pending` or `runner-stopped` with `--outcome partial` |
 | `forge-6-docs` | `forge-6-docs` | `--outcome` — `complete`, `blocked`, or `skipped` (deliberate docs skip, persisted via `state-skip` before the exit; routes like `complete` with honest wording) |
 | direct `forge-verify` | `forge-verify` | `--owner direct`, `--outcome` (`passed`, `findings`, `skipped`, `failed`), and served-stage metadata |
 | nested `forge-verify` | `forge-verify` | `--owner nested`, plus the same outcome and served-stage metadata |

package/adapters/claude/references/vendor-construct-inventory.md

@@ -27,7 +27,7 @@ vocabulary defined in `00-core-definitions.md` §8. No free-form values are perm
 | `${CLAUDE_PLUGIN_ROOT}` — sanctioned residual | 1 occurrence in `scripts/forge-root.sh` (env-fallback, REQ-RES-02 step 3) | `preserved-as-spec-allowed` | The single sanctioned residual: the resolver's documented Claude-compat fallback (REQ-RES-03 / REQ-RES-05). Exempt from the residual-var scan (`00-core-definitions.md` §6 `RESIDUAL_VAR_EXEMPT`). |
 | `${CLAUDE_PLUGIN_ROOT:-}` — bootstrap-prelude first-hint (Chunk 2b) | 1 occurrence per prelude across every canonical stamp site (the byte-pinned `BOOTSTRAP_PRELUDE`) | `preserved-as-spec-allowed` | The prelude's first resolver candidate — exact, glob-free root resolution on any Claude layout; expands to empty and is skipped when unset. Rule 3 allows it by stripping the byte-pinned prelude before its scan (detection is by `${CLAUDE_PLUGIN_ROOT` prefix, so the `:-}` default form is not an escape hatch elsewhere). `forge-agent-adapters-build` translates it to `${FEATURE_FORGE_ROOT:-}` in non-Claude bundles. |
 | `${CLAUDE_PLUGIN_ROOT}` — in `hooks/hooks.json` | 1 occurrence in `hooks/hooks.json` | `out-of-canon` | Non-canonical Claude artifact (REQ-VND-04). Not a canonical surface; exempt from the REQ-RES-03 scan. Left in place. |
-| `hooks/hooks.json` SessionStart wiring | 1 file (`hooks/hooks.json`) — Claude `SessionStart` → `bash ${CLAUDE_PLUGIN_ROOT}/scripts/session-check.sh` | `out-of-canon` | Claude-specific plugin hook wiring (REQ-VND-04, decision D3). Preserved + documented so `forge-agent-adapters-build` treats it as a Claude artifact, not portable canon. |
+| `hooks/hooks.json` SessionStart wiring | 1 file (`hooks/hooks.json`) — Claude `SessionStart` → `bash "${CLAUDE_PLUGIN_ROOT}/scripts/session-check.sh"` | `out-of-canon` | Claude-specific plugin hook wiring (REQ-VND-04, decision D3). Preserved + documented so `forge-agent-adapters-build` treats it as a Claude artifact, not portable canon. |
 | (contingency) any other vendor invocation directive | none found in the audit | — | REQ-VND-02 contingency did not fire (see Notes). If one is later surfaced, add a row with `removed` or `out-of-canon` per `02-frontmatter-purity-and-inventory.md` §3. |
 
 ## Notes

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

@@ -14,7 +14,8 @@ root navigator:
     python3 forge-session.py check-epic-base --feature F [--specs-dir DIR] \
         [--config FILE] [--epic E] [--json]
     python3 forge-session.py stage-exit --feature F --stage S [--owner direct|nested] \
-        [--outcome O] [--cause dependency-starvation] [--verify-mode M] \
+        [--outcome O] [--cause dependency-starvation|review-pending|runner-stopped] \
+        [--verify-mode M] \
         [--served-stage S] [--verify-capability interactive|manual] [--specs-dir DIR] \
         [--config FILE] [--epic E] [--next-feature N] [--host claude|generic|pi] [--json]
     python3 forge-session.py select-outcome --feature F --served-stage S \
@@ -470,6 +471,8 @@ from forge_session.routes import (  # noqa: E402
     _LOOP_COMPLETE_SETTLED,
     _LOOP_COMPLETE_TEXT,
     _LOOP_OUTCOME_TEXT,
+    _LOOP_PARTIAL_REVIEW_PENDING_TEXT,
+    _LOOP_PARTIAL_RUNNER_STOPPED_TEXT,
     _LOOP_PARTIAL_STARVED_TEXT,
     _LOOP_ROUTE_KIND,
     _NO_FINDINGS_RESOLVED_TEXT,
@@ -767,6 +770,8 @@ __all__ = [
     "_LOOP_COMPLETE_SETTLED",
     "_LOOP_COMPLETE_TEXT",
     "_LOOP_OUTCOME_TEXT",
+    "_LOOP_PARTIAL_REVIEW_PENDING_TEXT",
+    "_LOOP_PARTIAL_RUNNER_STOPPED_TEXT",
     "_LOOP_PARTIAL_STARVED_TEXT",
     "_LOOP_ROUTE_KIND",
     "_NO_FINDINGS_RESOLVED_TEXT",

package/adapters/claude/scripts/forge_session/cli.py

@@ -467,7 +467,8 @@ def main() -> int:
     p_exit.add_argument("--outcome", default=None,
                         help="Stage-specific outcome (loop/docs/verify/fix only)")
     p_exit.add_argument(
-        "--cause", default=None, dest="cause", choices=("dependency-starvation",),
+        "--cause", default=None, dest="cause",
+        choices=("dependency-starvation", "review-pending", "runner-stopped"),
         help="Pending-attribution cause; valid only with "
              "--stage forge-5-loop --outcome partial",
     )

package/adapters/claude/scripts/forge_session/doctor.py

@@ -686,8 +686,37 @@ def _feature_label(feat: dict) -> str:
     return feat["name"] + (f" [{feat['epic']}]" if feat.get("epic") else "")
 
 
+#: Remedy for a resolved root that is un-built canon. Every route loads a BUILT bundle and names
+#: what it writes (#283/#317) — the npx installer's writes mirror ``installer/src`` (the sibling
+#: ``manifestPath`` manifest + every ``resolvePlacements`` destination, both scopes), pinned by
+#: ``installer/test/doctor-canon-remedy.test.ts`` against the installer's typed contract.
+#: Tier = the most conservative route (``network``: the marketplace and npm fetch).
+_CANON_ROOT_REMEDY: Final[str] = (
+    "Load a built bundle, not the repo checkout. Install: the Claude marketplace "
+    "(`/plugin install feature-forge@feature-forge`, ships ./adapters/claude; writes under "
+    "~/.claude/plugins and enables it in ~/.claude/settings.json) or "
+    "`npx @garygentry/feature-forge install` (under the install scope's root — the project, or ~ "
+    "for a global install — writes the host's bundle dir, e.g. .claude/skills/feature-forge, plus "
+    "a sibling .feature-forge.<scope>.json manifest; also Codex agent files in .codex/agents, a "
+    "managed block in .github/copilot-instructions.md for Copilot, Pi agent files in .pi/agents "
+    "(global: ~/.pi/agent/agents)). Source dogfood: rebuild with "
+    "`python3 scripts/build-adapters.py` (rewrites adapters/), then `claude --plugin-dir "
+    "adapters/claude` or FEATURE_FORGE_ROOT=adapters/<host> (neither writes files), "
+    "`pi install ./adapters/pi -l` (writes .pi/settings.json), or `scripts/dev-plugin.sh` "
+    "(writes an out-of-repo plugin dir, default ~/.cache/feature-forge-dev/claude) — see "
+    "docs/DOGFOODING.md"
+)
+
+
 def _check_plugin_root(ctx: _CheckContext) -> dict:
-    """The sibling ``forge-root.sh`` resolves an install root (never ``na``)."""
+    """The sibling ``forge-root.sh`` resolves an install root (never ``na``).
+
+    A resolved root without the neutral ``.feature-forge-bundle.json`` sentinel is
+    un-built canon (the repo checkout): its skills' prose ``Read references/X`` resolves
+    skill-local, where canon carries none of the shared refs the build fans in, so they
+    dead-reference mid-stage (#122/#305/#314). That warns — never fails (#244 policy), and
+    doctor still exits 0 (INV-3), so the repo's own ``doctor --json`` smoke stays green.
+    """
     root = ctx.plugin_root
     evidence = dict(root)
     if root.get("resolved"):
@@ -695,7 +724,18 @@ def _check_plugin_root(ctx: _CheckContext) -> dict:
         channel = root.get("channel")
         suffix = f" (version {version})" if version else " (no version manifest)"
         chan = f" via {channel}" if channel else ""
-        return _result("ok", f"resolved {root.get('root')}{chan}{suffix}", evidence)
+        built = (Path(str(root.get("root"))) / ".feature-forge-bundle.json").is_file()
+        evidence["bundleSentinel"] = built
+        if built:
+            return _result("ok", f"resolved {root.get('root')}{chan}{suffix}", evidence)
+        return _result(
+            "warn",
+            f"resolved {root.get('root')}{chan}{suffix} is un-built canon (no "
+            ".feature-forge-bundle.json): skills loaded from it cannot Read their shared "
+            "references (references/shared-conventions.md, …) skill-local (#305/#314)",
+            evidence,
+            _remedy(_CANON_ROOT_REMEDY, None, "network"),
+        )
     return _result(
         "warn",
         f"plugin root unresolved: {root.get('error', 'unknown')}",

package/adapters/claude/scripts/forge_session/exit.py

@@ -329,10 +329,10 @@ def stage_exit(
             capability is permission, not tool presence: a dispatch permitted
             only once the user has asked is still `interactive`, because the
             `standard` gate's own prompt supplies that request.
-        cause: Pending-attribution annotation (`dependency-starvation`), valid
-            only with `--stage forge-5-loop --outcome partial` (REQ-ATTR-04).
-            It swaps the partial next-steps sentence for the starvation variant
-            and changes no routing.
+        cause: Pending-attribution annotation (`dependency-starvation`,
+            `review-pending` or `runner-stopped`), valid only with `--stage forge-5-loop --outcome
+            partial` (REQ-ATTR-04, #339). It swaps the partial next-steps sentence
+            for the matching variant and changes no routing.
 
     Returns:
         A JSON-serializable `StageExitPayload` dictionary.
@@ -486,7 +486,7 @@ def stage_exit(
     # argparse `choices` already restricts the value; this restricts the combination.
     if cause is not None and not (stage == "forge-5-loop" and outcome == "partial"):
         raise UsageError(
-            "--cause dependency-starvation is valid only with "
+            f"--cause {cause} is valid only with "
             "--stage forge-5-loop --outcome partial"
         )
 

package/adapters/claude/scripts/forge_session/routes.py

@@ -799,6 +799,27 @@ _LOOP_PARTIAL_STARVED_TEXT: Final[str] = (
     "resumable and nothing downstream is ready: unblock the roots named in the "
     "starvation report above, then run the loop again below to continue."
 )
+#: The pending-review variant of the `partial` next-steps sentence: every item may be
+#: done, but the runner's review pass failed or was interrupted, so the run is not
+#: complete. Selected only by ``--cause review-pending`` (issue #339); the route is
+#: still the loop resume, whose Step 2a re-runs exactly that review.
+_LOOP_PARTIAL_REVIEW_PENDING_TEXT: Final[str] = (
+    "The loop for {feature} is not finished — its review pass failed or was "
+    "interrupted, so the review is still pending even if every item is done. The "
+    "recorded state is resumable and nothing downstream is ready: run the loop again "
+    "below to re-run the pending review."
+)
+#: The unfinished-runner variant of the `partial` next-steps sentence: the runner's
+#: own terminal state (a crash, a stop, a stale lock, a limit halt) says it did not
+#: finish cleanly, so the run is not complete even when every item reads `done`.
+#: Selected only by ``--cause runner-stopped`` (issue #339); the route is still the
+#: loop resume, whose Step 2a offers the runner's own resume.
+_LOOP_PARTIAL_RUNNER_STOPPED_TEXT: Final[str] = (
+    "The loop runner for {feature} did not reach a clean finish — it crashed, was "
+    "stopped, or halted on a limit — so the run is not complete even if every item "
+    "reads done. The recorded state is resumable and nothing downstream is ready: run "
+    "the loop again below to resume the runner."
+)
 #: The `complete` preamble, selected by where the handoff actually lands. The epic
 #: rows name the epic and its live rollup, so the operator can see WHY the handoff is
 #: this member's own documentation rather than another member (or vice versa).
@@ -956,9 +977,11 @@ def _loop_route(
             handoff: findings already exist at this exact revision, so the fenced
             action is applying them, exactly as on a production re-exit.
         cause: The already-validated attribution annotation — only
-            ``"dependency-starvation"`` with ``outcome == "partial"``, else None.
-            Swaps the partial next-steps sentence for the starvation variant; the
-            route itself is unchanged (partial stays a resume either way).
+            ``"dependency-starvation"``, ``"review-pending"`` or
+            ``"runner-stopped"`` with
+            ``outcome == "partial"``, else None. Swaps the partial next-steps
+            sentence for the matching variant; the route itself is unchanged
+            (partial stays a resume either way).
 
     Returns:
         `(primary_canonical, deferred_canonical, outcome_text, advancing)`, matching
@@ -985,6 +1008,10 @@ def _loop_route(
         )
         if outcome == "partial" and cause == "dependency-starvation":
             text = _LOOP_PARTIAL_STARVED_TEXT.format(feature=feature)
+        elif outcome == "partial" and cause == "review-pending":
+            text = _LOOP_PARTIAL_REVIEW_PENDING_TEXT.format(feature=feature)
+        elif outcome == "partial" and cause == "runner-stopped":
+            text = _LOOP_PARTIAL_RUNNER_STOPPED_TEXT.format(feature=feature)
         else:
             text = _LOOP_OUTCOME_TEXT[outcome].format(feature=feature)
         return primary, None, text, False

package/adapters/claude/scripts/session-check.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Check if forge.config.json exists in the current working directory
+if [[ -f "forge.config.json" ]]; then
+  exit 0
+fi
+
+# Check if any pipeline state files exist at any depth under specs/. Use find, not a
+# `specs/**/…` glob: without `shopt -s globstar` the `**` collapses to a single level
+# and would miss epic-member state (specs/<epic>/<member>/.pipeline-state.json).
+if find specs/ -name ".pipeline-state.json" -print -quit 2>/dev/null | grep -q .; then
+  echo "⚠ Feature forge pipeline state found but no forge.config.json. Run /feature-forge:forge-init to create configuration."
+fi
+
+exit 0

package/adapters/claude/skills/forge/references/stage-exit-protocol.md

@@ -47,7 +47,7 @@ an epic member. Only the flags below are stage-specific; pass no others.
 |---|---|---|
 | `forge-0-epic` | `forge-0-epic` | `--next-feature "{member}"` when a concrete member exists |
 | `forge-1-prd` … `forge-4-backlog` | that stage's own id | none beyond identity/capability |
-| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation` with `--outcome partial` |
+| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation`, `review-pending` or `runner-stopped` with `--outcome partial` |
 | `forge-6-docs` | `forge-6-docs` | `--outcome` — `complete`, `blocked`, or `skipped` (deliberate docs skip, persisted via `state-skip` before the exit; routes like `complete` with honest wording) |
 | direct `forge-verify` | `forge-verify` | `--owner direct`, `--outcome` (`passed`, `findings`, `skipped`, `failed`), and served-stage metadata |
 | nested `forge-verify` | `forge-verify` | `--owner nested`, plus the same outcome and served-stage metadata |

package/adapters/claude/skills/forge-0-epic/references/stage-exit-protocol.md

@@ -47,7 +47,7 @@ an epic member. Only the flags below are stage-specific; pass no others.
 |---|---|---|
 | `forge-0-epic` | `forge-0-epic` | `--next-feature "{member}"` when a concrete member exists |
 | `forge-1-prd` … `forge-4-backlog` | that stage's own id | none beyond identity/capability |
-| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation` with `--outcome partial` |
+| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation`, `review-pending` or `runner-stopped` with `--outcome partial` |
 | `forge-6-docs` | `forge-6-docs` | `--outcome` — `complete`, `blocked`, or `skipped` (deliberate docs skip, persisted via `state-skip` before the exit; routes like `complete` with honest wording) |
 | direct `forge-verify` | `forge-verify` | `--owner direct`, `--outcome` (`passed`, `findings`, `skipped`, `failed`), and served-stage metadata |
 | nested `forge-verify` | `forge-verify` | `--owner nested`, plus the same outcome and served-stage metadata |

package/adapters/claude/skills/forge-1-prd/references/stage-exit-protocol.md

@@ -47,7 +47,7 @@ an epic member. Only the flags below are stage-specific; pass no others.
 |---|---|---|
 | `forge-0-epic` | `forge-0-epic` | `--next-feature "{member}"` when a concrete member exists |
 | `forge-1-prd` … `forge-4-backlog` | that stage's own id | none beyond identity/capability |
-| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation` with `--outcome partial` |
+| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation`, `review-pending` or `runner-stopped` with `--outcome partial` |
 | `forge-6-docs` | `forge-6-docs` | `--outcome` — `complete`, `blocked`, or `skipped` (deliberate docs skip, persisted via `state-skip` before the exit; routes like `complete` with honest wording) |
 | direct `forge-verify` | `forge-verify` | `--owner direct`, `--outcome` (`passed`, `findings`, `skipped`, `failed`), and served-stage metadata |
 | nested `forge-verify` | `forge-verify` | `--owner nested`, plus the same outcome and served-stage metadata |

package/adapters/claude/skills/forge-2-tech/references/stage-exit-protocol.md

@@ -47,7 +47,7 @@ an epic member. Only the flags below are stage-specific; pass no others.
 |---|---|---|
 | `forge-0-epic` | `forge-0-epic` | `--next-feature "{member}"` when a concrete member exists |
 | `forge-1-prd` … `forge-4-backlog` | that stage's own id | none beyond identity/capability |
-| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation` with `--outcome partial` |
+| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation`, `review-pending` or `runner-stopped` with `--outcome partial` |
 | `forge-6-docs` | `forge-6-docs` | `--outcome` — `complete`, `blocked`, or `skipped` (deliberate docs skip, persisted via `state-skip` before the exit; routes like `complete` with honest wording) |
 | direct `forge-verify` | `forge-verify` | `--owner direct`, `--outcome` (`passed`, `findings`, `skipped`, `failed`), and served-stage metadata |
 | nested `forge-verify` | `forge-verify` | `--owner nested`, plus the same outcome and served-stage metadata |

package/adapters/claude/skills/forge-3-specs/references/stage-exit-protocol.md

@@ -47,7 +47,7 @@ an epic member. Only the flags below are stage-specific; pass no others.
 |---|---|---|
 | `forge-0-epic` | `forge-0-epic` | `--next-feature "{member}"` when a concrete member exists |
 | `forge-1-prd` … `forge-4-backlog` | that stage's own id | none beyond identity/capability |
-| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation` with `--outcome partial` |
+| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation`, `review-pending` or `runner-stopped` with `--outcome partial` |
 | `forge-6-docs` | `forge-6-docs` | `--outcome` — `complete`, `blocked`, or `skipped` (deliberate docs skip, persisted via `state-skip` before the exit; routes like `complete` with honest wording) |
 | direct `forge-verify` | `forge-verify` | `--owner direct`, `--outcome` (`passed`, `findings`, `skipped`, `failed`), and served-stage metadata |
 | nested `forge-verify` | `forge-verify` | `--owner nested`, plus the same outcome and served-stage metadata |

package/adapters/claude/skills/forge-4-backlog/references/stage-exit-protocol.md

@@ -47,7 +47,7 @@ an epic member. Only the flags below are stage-specific; pass no others.
 |---|---|---|
 | `forge-0-epic` | `forge-0-epic` | `--next-feature "{member}"` when a concrete member exists |
 | `forge-1-prd` … `forge-4-backlog` | that stage's own id | none beyond identity/capability |
-| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation` with `--outcome partial` |
+| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation`, `review-pending` or `runner-stopped` with `--outcome partial` |
 | `forge-6-docs` | `forge-6-docs` | `--outcome` — `complete`, `blocked`, or `skipped` (deliberate docs skip, persisted via `state-skip` before the exit; routes like `complete` with honest wording) |
 | direct `forge-verify` | `forge-verify` | `--owner direct`, `--outcome` (`passed`, `findings`, `skipped`, `failed`), and served-stage metadata |
 | nested `forge-verify` | `forge-verify` | `--owner nested`, plus the same outcome and served-stage metadata |

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

@@ -110,7 +110,7 @@ The runner commits each item onto the current branch. Skip if not a git repo or
 
 ### 1g. Stranded-Work Pre-flight (if using git)
 
-Run `git status --porcelain`. If it reports changes **and** `{backlogDir}/{loopRunner.stateDir}/state.json` exists from a previous run, **STOP**: name that run (its `startedAt`, `currentItem`, and `blockedItems` from `state.json`) and point the user at the **Post-Run Tree Reconciliation** section of `references/recovery-procedure.md` to commit / stash / discard the stranded work before relaunch — never auto-pass `--force`. If the tree is dirty with **no** prior-run `state.json`, keep today's behavior (surface it; let the user commit/stash or pass `--force`). A clean tree is silent. rauf's own launch refusal remains the backstop.
+Run `git status --porcelain`. If it reports changes **and** `{backlogDir}/{loopRunner.stateDir}/state.json` exists from a previous run, **STOP**: name that run (its `startedAt`, `currentItem`, and `blockedItems` from `state.json`) and point the user at the **Post-Run Tree Reconciliation** section of `references/recovery-procedure.md` to commit / stash / discard the stranded work before relaunch — never auto-pass `--force`. If the tree is dirty with **no** prior-run `state.json`, keep today's behavior (surface it; let the user commit/stash or pass `--force`). A clean tree is silent.
 
 ## Step 2: Construct the Loop Command
 
@@ -120,7 +120,7 @@ Run the **list command** (`loopRunner.listCommand`, default `rauf backlog list .
 
 Calculate the iteration count: `ceil((pending + in_progress) * loopIterationMultiplier)` where `loopIterationMultiplier` comes from `forge.config.json` (default: 1.5, headroom for retries).
 
-If there are no pending or in_progress items, STOP and tell the user: "All backlog items are already done or blocked. Nothing to run."
+Then, **whatever the counts**, run the **status-json command**: `reviewPending: true` (optional field) means a prior review pass failed or was interrupted — follow **Pending review** in `references/runner-contract.md` before any fresh run (which would drop it). Otherwise, with no pending or in_progress items: a reported `loopState` that is not a clean finish → follow **Unfinished runner** in that file; else STOP and tell the user: "All backlog items are already done or blocked. Nothing to run."
 
 If there are `blocked` items, note them — the user may want `--retry-blocked`.
 
@@ -186,11 +186,11 @@ R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scri
 python3 "$R/scripts/forge-session.py" state-enter --feature "{feature}" --stage forge-5-loop --specs-dir "{specsDir}"
 ```
 
-Then commit this state write before launching (mandatory). The runner refuses to run with uncommitted changes (*"…pass --force"*), and this marker is itself one — so an otherwise-clean repo fails its first launch unless committed. Commit it via the shared-conventions **Git Commit Protocol** (epic members: stage `{specsDir}/{epic}/`): `{commitPrefix}({feature}): forge-5-loop in-progress` — a launch precondition, required regardless of `gitCommitAfterStage`. Unrelated leftover changes still trip the refusal; surface it, never auto-pass `--force`. See `references/runner-contract.md`.
+Then commit this state write before launching (mandatory — the runner refuses a dirty tree, and this marker is itself a change) via the shared-conventions **Git Commit Protocol** (epic members: stage `{specsDir}/{epic}/`): `{commitPrefix}({feature}): forge-5-loop in-progress`, regardless of `gitCommitAfterStage`. Unrelated leftover changes still trip the refusal; surface it, never auto-pass `--force`.
 
 ### 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). 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`.
+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 and rotates `{stateDir}/events.ndjson` natively), launch the **plain `runCommand`** with **no stdout redirect** and supervise that native file; never redirect `--ndjson` into `{stateDir}` (it collides with the runner's own writer). 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). 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
 
@@ -198,21 +198,11 @@ Follow the **Inform-user output template (Step 3c)** section of `references/runn
 
 ### 3d. Arm a Monitor on the event stream, and react to events
 
-Arm the **`Monitor` tool** on the structured event stream (the NDJSON file, or the
-human log as fallback) with **`persistent: true`**, a coverage-complete filter
-matching every terminal and exception state (silence is not success), and react to
-each event as it arrives. Each NDJSON line is a JSON object whose event kind lives
-under the **`type`** field (rauf's schema — e.g. `{"type":"item_completed",…}`), so
-the filter must select on **`.type`**, **not** `kind`: a `kind`-keyed filter surfaces
-nothing (no `grep` match; `jq` aborts on the null `.kind`), so the watch stays dark. The exact Monitor
-commands, the filter event list, and the full per-event reaction rules (`needs_human`
-/ `loop_error` surfaced immediately with a `PushNotification`, `item_completed`
-coalesced into milestones, `llm_stuck_warning` as a hang warning) are in
-`references/runner-contract.md` — follow them verbatim.
+Arm the **`Monitor` tool** (`persistent: true`) on the structured event stream (the NDJSON file, or the human log as fallback) with a coverage-complete filter matching every terminal and exception state (silence is not success). The filter selects on each NDJSON line's **`.type`** field, **never** `kind` (a `kind`-keyed filter matches nothing and the watch stays dark). The exact commands, the filter list (incl. `review_failed` and usage-limit events), and the per-event reactions (`needs_human` / `loop_error` / `review_failed` surfaced with a `PushNotification`, `item_completed` coalesced into milestones, `llm_stuck_warning` reported with its in-flight tool) are in `references/runner-contract.md` — follow them verbatim.
 
 ### 3f. Reach completion
 
-Step 4 is reached when the backgrounded process exits (its completion notification is authoritative); the `loop_completed` / `loop_error` / `loop_cancelled` event is the live heads-up that it's imminent. Stop the Monitor (it ends on its own when `tail` sees the process-ended log, or via `TaskStop`) and proceed to Step 4. Do NOT foreground-sleep or poll — the harness drives both the Monitor events and the completion notification.
+Step 4 is reached when the backgrounded process exits (its completion notification is authoritative; a `loop_completed` / `loop_error` / `loop_cancelled` event is the live heads-up). Stop the Monitor (`TaskStop` if it has not ended) and proceed. Do NOT foreground-sleep or poll — the harness drives both signals.
 
 ## Step 4: Check Results
 
@@ -224,7 +214,7 @@ Run the **status-json command** (`loopRunner.statusJsonCommand`) and read
 `backlogSummary` for the authoritative counts — it separates the three non-done
 outcomes: genuine `blocked`, `needsHuman`, and runner-`deferred` ("false blocks").
 Fall back to the **list command** (`loopRunner.listCommand`) if `statusJsonCommand`
-is not configured. If the run used a review flag (e.g. rauf's `--review`), also read any `review_completed` event (event stream, or `{loopRunner.stateDir}/events.ndjson`) for its `itemsCreated`/`summary` to surface in 4b — see `references/result-reporting.md`.
+is not configured. Also read the optional `loopState`, `reviewPending`, `lock` fields (absent on older runners = unset); **Runner terminal states** in `references/result-reporting.md` maps them. **`reviewPending: true` is never complete, whatever the counts** — offer the resume per **Pending review** in `references/runner-contract.md` before 4b. If the run used a review flag (e.g. rauf's `--review`), also read any `review_completed` event (event stream, or `{loopRunner.stateDir}/events.ndjson`) for its `itemsCreated`/`summary` to surface in 4b — see `references/result-reporting.md`.
 
 ### 4b. Report Results
 
@@ -233,11 +223,11 @@ blocked and needs-human) and render its report. The five verbatim result-report
 
 ### 4c. Post-Run Recovery Pass (unconditional)
 
-Run the **Post-Run Recovery Procedure** (`references/recovery-procedure.md`) now — on **every** run close, before Step 5 writes state, so the tree it inspects is exactly what the run left. The live `needs_human` handler (3d) collects answers early but is **not** the entry condition: a run that emitted no event still enters here — this is what makes the plain-blocked unblock reachable on blocked-only runs. With nothing to decide, its step 1 skips straight to the §4 tree reconciliation — silent on a clean tree. A run can strand uncommitted work with no signal (items failing a shared final acceptance criterion are never committed); this pass reconciles it — 1g's pre-flight is only the next-launch backstop. Its step-7 gate feeds Step 7's `resolved` rung; the stage still closes exactly once, in Step 7.
+Run the **Post-Run Recovery Procedure** (`references/recovery-procedure.md`) now — on **every** run close, before Step 5 writes state, so the tree it inspects is exactly what the run left. The live `needs_human` handler (3d) is **not** the entry condition: a run that emitted no event still enters here, so blocked-only runs reach the unblock. With nothing to decide, its step 1 skips to the §4 tree reconciliation — silent on a clean tree — which also reconciles work a run stranded uncommitted with no signal (1g is only the next-launch backstop). Its step-7 gate feeds Step 7's `resolved` rung; the stage still closes exactly once, in Step 7.
 
 ## Step 5: Update Pipeline State
 
-Record completion by running `state-complete` (below). Evaluate "all backlog items are `done`" yourself and pass the result as `--status`: `complete` if every item is `done`, else `in-progress`. The verb records `completedAt`, the version, `basedOnVersions` and `artifacts`, and refreshes `updatedAt`. Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol.
+Record completion by running `state-complete` (below). Evaluate "all backlog items are `done`" yourself and pass the result as `--status`: `complete` only when Step 7's ladder selects `complete` (every item `done`, `total > 0`, no pending review, a clean runner finish per `references/result-reporting.md`), else `in-progress`. The verb records `completedAt`, the version, `basedOnVersions` and `artifacts`, and refreshes `updatedAt`. Add `--epic "{epic}"` when this feature is an epic member — required, per the Pipeline State Protocol.
 
 ```bash
 R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
@@ -272,7 +262,7 @@ python3 "$R/scripts/forge-session.py" state-verify --feature "{feature}" --stage
 
 Every loop run ends here, and ends here **exactly once** — standalone or epic member, complete or not.
 
-First select the single `LoopOutcome` with the ladder in `references/result-reporting.md` (`resolved` → `needs-human` → `blocked` → `deferred` → `partial` → `complete`, first match wins), reading it from Step 4a's authoritative counts and never from the runner's process exit code. If those counts were never obtained, follow that file's operational-failure rule instead: report the failure and its recovery and run no exit at all.
+First select the single `LoopOutcome` with the ladder in `references/result-reporting.md` (`resolved` → unfinished-runner `partial` → `needs-human` → `blocked` → `deferred` → `partial` → `complete`, first match wins, plus any `--cause` it names), reading it from Step 4a's authoritative counts and never from the runner's process exit code. If those counts were never obtained, follow that file's operational-failure rule instead: report the failure and its recovery and run no exit at all.
 
 **Close this stage with the Scripted Stage Exit** (contract: `references/stage-exit-protocol.md`; do not improvise a "Next steps" list). Run:
 
@@ -291,7 +281,7 @@ Add `--epic "{epic}"` when this feature is an epic member — required, per the
 - **Plugin-root discovery (1b-epic helper) covers installed paths, not workspace-dev checkouts.** The `forge-root.sh` search probes the locations of an **installed** plugin only, so a feature-forge **source checkout** (e.g. `~/workspace/feature-forge`) exits "cannot locate plugin root" unless `FEATURE_FORGE_ROOT` points at it (#323). Expected in a dev environment; run the epic-manifest script from the checkout directly (`python3 <checkout>/scripts/epic-manifest.py …`).
 - `{backlogDir}` is a **directory path**, not a file path. Pass `specs/auth`, not `specs/auth/backlog.json`.
 - rauf resolves `RAUF.md` with fallback (`{backlogDir}/.rauf/RAUF.md` first, then the project's `.rauf/RAUF.md`). State files (state.json, {loopRunner.logFile}, etc.) land at `{backlogDir}/{loopRunner.stateDir}/`, isolated per backlog dir, so concurrent features don't collide.
-- If the session disconnects mid-loop, the runner process continues independently — check results later with the status / list commands. A stale lock from a previous run may need `--force` to clear.
-- 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). 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 the session disconnects mid-loop, the runner process continues independently — check results later with the status / list commands. A crashed run's stale lock (`PAUSED` + `lock.stale`) is cleared by rauf's `resume`, not `--force` (see `references/result-reporting.md`).
+- 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). 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.
 - 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** specs and `backlog.json` freely — they are the source of truth, and the backlog rightly cites specs for provenance. But artifacts the loop **writes into the target repo** (source code, generated `SKILL.md`/agent files, configs, code comments) must be **self-contained**: no references to feature-forge spec files (no `See specs/{feature}/NN-*.md`, no "source spec" provenance notes) — specs are pre-implementation inputs that may be archived or deleted once the feature ships. This applies only to shipped implementation output, never to the backlog or spec documents, which keep citing specs.

package/adapters/claude/skills/forge-5-loop/references/preflight-and-self-heal.md

@@ -6,7 +6,7 @@ silent unasked mutation. It runs whenever a skill gates on `doctor`'s structured
 `checks[]` (`roadmap/self-healing-resilience.md` §5.2); today that is `forge-5-loop`'s
 gates 1c/1d (`skills/forge-5-loop/SKILL.md`), which resolve the loop runner **before**
 touching it, `forge-init`'s install preflight (`skills/forge-init/SKILL.md`), where
-neither check is a stop, and `forge-guide --doctor` (`skills/forge-guide/SKILL.md`), the
+no check is a stop, and `forge-guide --doctor` (`skills/forge-guide/SKILL.md`), the
 operator-facing repair surface, which gates nothing at all. All three are callers, not
 the procedure's scope: any skill that gates on `checks[]` follows it in full. Its seven
 ordered steps: **enumerate → cluster → consolidated prompts → record → apply → prove →

package/adapters/claude/skills/forge-5-loop/references/ralph-loop-contract.md

@@ -40,9 +40,11 @@ defined authoritatively in rauf's
 - **A machine-readable event stream** for live supervision (`loopRunner.eventStreamCommand`,
   rauf: `loop run … --ndjson`): one JSON event per line with a stable `type`
   vocabulary — `item_completed` / `item_blocked` / `needs_human` / `signal_parsed`
-  / `loop_completed` / `loop_error` / `loop_cancelled` / `llm_stuck_warning` (a
-  circuit-breaker halt surfaces as `loop_error`) — plus a
-  derived-status JSON (`loopRunner.statusJsonCommand`, rauf: `status … --json`) and
+  / `loop_completed` / `loop_error` / `loop_cancelled` / `review_failed` /
+  `llm_stuck_warning` (a circuit-breaker halt surfaces as `loop_error`) — plus a
+  derived-status JSON (`loopRunner.statusJsonCommand`, rauf: `status … --json`;
+  forge-5-loop also reads its optional `loopState` / `lock` / `sleepUntil` /
+  `reviewPending` fields when present, and degrades to the counts when absent) and
   per-iteration telemetry with a `stuckWarning` flag (`loopRunner.watchCommand`,
   rauf: `status … --json` — the `loop watch` verb was removed in v0.5.0). `forge-5-loop` supervises the run through these,
   **not** by parsing the human log. `followCommand` / `logCommand` are