@garygentry/feature-forge 0.3.2 → 0.3.5

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

@@ -14,9 +14,9 @@ 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] [--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]
+        [--outcome O] [--cause dependency-starvation] [--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 effective-config [--config FILE] [--schema PATH] [--json]
 
 Plus the `state-*` write verbs, which author `.pipeline-state.json` so no stage
@@ -41,6 +41,15 @@ has to hand-write the JSON (and therefore no stage has to read the state schema)
     python3 forge-session.py state-verify --feature F --stage S [--status ST] \
         [--findings-file P] [--findings-count N] [--verified-stage-version N] \
         [--commit-hash H] [--specs-dir DIR] [--epic E] [--json]
+    python3 forge-session.py decision-record --backlog-dir DIR --item ID [--item ID ...] \
+        --question Q (--answer A | --deferred) [--cluster CID] [--actor LABEL] \
+        [--state-dir NAME] [--config PATH] [--json]
+    python3 forge-session.py decision-list --backlog-dir DIR [--unapplied] \
+        [--state-dir NAME] [--config PATH] [--json]
+    python3 forge-session.py decision-apply --backlog-dir DIR --item ID [--actor LABEL] \
+        [--state-dir NAME] [--config PATH] [--json]
+    python3 forge-session.py backlog-topology (--items-json PATH | --items-stdin) \
+        [--cluster] [--json]
 
 `rank-features` scans the specs tree for feature-shaped directories (those that
 directly contain a `.pipeline-state.json`, in both the flat
@@ -158,8 +167,10 @@ from __future__ import annotations
 
 import argparse
 import json
+import math
 import os
 import re
+import socket
 import subprocess
 import sys
 import tempfile
@@ -240,8 +251,15 @@ VERIFY_TOKEN_BY_STAGE: Final[dict[str, str]] = {
 #: there is no `forge-verify-*` key for it to write.
 VERIFY_STAGES: Final[tuple[str, ...]] = ("forge-0-epic", *VERIFY_TOKEN_BY_STAGE)
 
-#: A production stage status that counts as "done" for next-stage selection.
+#: The terminal status the completion writer records (and the commit-hash
+#: follow-up requires) — NOT the whole "done for selection" set below.
 _DONE_STATUS: Final = "complete"
+#: Production stage statuses that count as "done" for next-stage selection.
+#: `skipped` is legal only on forge-6-docs (schema: `docsStageEntry`) — an
+#: explicitly skipped documentation stage ends the pipeline without claiming
+#: artifacts it never produced (#197). Selection treats the status as done
+#: wherever it appears; the schema is what confines it to the docs stage.
+_DONE_STATUSES: Final = frozenset({_DONE_STATUS, "skipped"})
 #: The authoritative forge-verify status vocabulary. SOURCE OF TRUTH:
 #: references/pipeline-state-schema.json (definitions.verifyEntry.properties.status.enum).
 #: A status outside this set is unrecognized and must not be silently interpreted (#148).
@@ -261,6 +279,15 @@ KNOWN_VERIFY_STATUSES: Final = frozenset(
 #: subset of KNOWN_VERIFY_STATUSES — not collapsible into it (different meaning).
 #: `auto-verify-pending` is deliberately ABSENT: owed-but-unrun debt is not resolved.
 _VERIFY_RESOLVED: Final = frozenset({"passed", "findings-applied", "skipped"})
+#: Prior verify statuses a `skipped` result write may NOT replace (#203). Mirrors
+#: epic-manifest.py's `_VERIFY_ORCH_COMPLETE`: these two statuses make an epic
+#: member complete-for-orchestration, so silently replacing one with `skipped`
+#: demoted the member out of the rollup and fabricated unmetDeps on every
+#: dependent — the observed 5/6 → 1/6 collapse. A deferral over one of these
+#: needs NO write: the recorded result already carries the outstanding state.
+#: NOT the same set as `_VERIFY_RESOLVED` (`skipped` re-writing `skipped` is a
+#: harmless idempotent refresh and stays legal).
+_SKIP_PROTECTED_PRIOR: Final = frozenset({"passed", "findings-applied"})
 #: Per-process dedupe for the unknown-verify-status diagnostic (#148) so a single
 #: bogus status is flagged once, not once per verify_state() call in a command.
 _UNKNOWN_VERIFY_WARNED: set[str] = set()
@@ -371,8 +398,10 @@ VerifyStatus = Literal[
 #: Which gate form a stage exit asks the caller to render.
 VerifyGate = Literal["none", "standard", "manual-print"]
 
-LoopOutcome = Literal["complete", "partial", "blocked", "needs-human", "deferred"]
-DocsOutcome = Literal["complete", "blocked"]
+LoopOutcome = Literal[
+    "complete", "partial", "blocked", "needs-human", "deferred", "resolved"
+]
+DocsOutcome = Literal["complete", "blocked", "skipped"]
 VerifyOutcome = Literal["passed", "findings", "skipped", "failed"]
 FixOutcome = Literal[
     "no-findings",
@@ -414,6 +443,27 @@ VERIFY_MODE_TO_STAGE: Final[dict[str, str]] = {
     "backlog": "forge-4-backlog",
     "impl": "forge-5-loop",
 }
+#: Token-set Jaccard edge threshold for ``cluster_blocked``: two blocked items whose
+#: normalized blockedReason token sets score >= this join one systemic-cause cluster
+#: candidate. Calibrated against a real one-cause-three-phrasings incident — the
+#: binding pair clears 0.5 by only ~0.028, and tests/test_decision_clustering.py
+#: vendors those strings verbatim so a threshold change that would re-split the
+#: incident is caught. Under-clustering is the deliberately chosen failure direction:
+#: the agent holds merge authority, so the scripted floor must never over-merge.
+CLUSTER_JACCARD_THRESHOLD: Final[float] = 0.5
+#: Advisory topology warn triggers for ``compute_topology`` — a single root whose
+#: gated subtree is >= ceil(ratio * itemCount) items trips "single-root-fanout";
+#: a dependsOn chain of >= ceil(ratio * itemCount) nodes trips "chain-depth".
+#: math.ceil keeps the ratios the single source of the thresholds even if a
+#: future ratio is non-half. Advisory only: no consumer blocks on them.
+TOPOLOGY_FANOUT_WARN_RATIO: Final[float] = 0.5
+TOPOLOGY_DEPTH_WARN_RATIO: Final[float] = 0.5
+#: The forge-side capability threshold for the runner's `backlog answer` apply
+#: surface: at or above this rauf version the recovery procedure applies answers
+#: via `rauf backlog answer`; below it, it degrades to `rauf backlog unblock`.
+#: It never hard-fails recovery, and it is NOT ``loopRunner.minRunnerVersion``
+#: (the install floor in references/forge-config-schema.json, which stays 0.6.0).
+RECOVERY_MIN_RUNNER_VERSION: Final[str] = "0.14.0"
 #: The fixed final line of the NEXT-STEPS block. The stamp instructs the skill
 #: to print the block verbatim as its absolute last output — nothing after this.
 NEXT_STEPS_SENTINEL: Final = "─ forge: end of stage ─"
@@ -746,9 +796,10 @@ def next_stage(state: dict) -> str | None:
     """Return the first production stage that is not yet complete (the next step).
 
     Walks ``PRODUCTION_STAGES`` in order and returns the first whose recorded
-    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).
+    status is not in ``_DONE_STATUSES`` (a missing/pending/in-progress/stale
+    stage all count as "not done"; ``complete`` and a forge-6-docs ``skipped``
+    both count as done). Returns ``None`` when every production stage is done
+    (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
@@ -757,7 +808,7 @@ def next_stage(state: dict) -> str | None:
     ``currentStage``.
     """
     for stage in PRODUCTION_STAGES:
-        if _stage_status(state, stage) != _DONE_STATUS:
+        if _stage_status(state, stage) not in _DONE_STATUSES:
             return stage
     return None
 
@@ -912,7 +963,7 @@ def verify_state(state: dict) -> tuple[str | None, str]:
     likewise ``stale``: verify rather than skip.
     """
     for stage in reversed(PRODUCTION_STAGES):
-        if _stage_status(state, stage) != _DONE_STATUS:
+        if _stage_status(state, stage) not in _DONE_STATUSES:
             continue
         token = VERIFY_TOKEN_BY_STAGE.get(stage)
         if token is None:
@@ -1236,6 +1287,18 @@ def _config_value(config_path: Path, key: str):
     return _load_config(config_path).get(key)
 
 
+def _config_duplicate_keys(config_path: Path) -> list[str]:
+    """Duplicate key names in the config file, for doctor's health report.
+
+    Empty on a missing/unreadable/invalid config — those conditions are
+    reported by doctor's ``configExists`` field, not here.
+    """
+    try:
+        return load_json_with_duplicates(config_path)[1]
+    except (OSError, json.JSONDecodeError):
+        return []
+
+
 def auto_verify_for(config: dict, stage: str) -> bool:
     """Return the effective auto-verify setting for ``stage``.
 
@@ -1468,6 +1531,7 @@ def doctor_report(specs_dir: Path, config_path: Path) -> dict:
         "counts": _counts(specs_dir),
         "features": features,
         "invalidAutoVerifyKeys": invalid_auto_verify_keys(config),
+        "duplicateConfigKeys": _config_duplicate_keys(config_path),
         "rootSandbox": _root_sandbox_status(),
     }
 
@@ -1535,6 +1599,11 @@ def _print_doctor(report: dict) -> None:
     invalid = report.get("invalidAutoVerifyKeys") or []
     if invalid:
         print("  ! invalid autoVerifyStages keys (ignored): " + ", ".join(invalid))
+    duplicates = report.get("duplicateConfigKeys") or []
+    if duplicates:
+        print(
+            "  ! duplicate config keys (last value wins): " + ", ".join(duplicates)
+        )
     rs = report.get("rootSandbox") or {}
     if rs.get("isRoot"):
         if rs.get("isSandboxSet"):
@@ -2040,6 +2109,402 @@ def _print_check_epic_base(payload: dict) -> None:
         print(f"  → switch to the epic's home branch: {payload['homeBranch'] or '(unknown)'}")
 
 
+# --------------------------------------------------------------------------- #
+# Dependency graph & blocked-item clustering
+# --------------------------------------------------------------------------- #
+# Pure, stdlib-only flat functions over the loop runner's item array (the
+# `listCommand` JSON the caller already holds) — same precedent as
+# rank-features/reconcile-branch, no class. Nothing here reads backlog.json off
+# disk: single data source, so every derived claim cites the runner's
+# authoritative counts. All ordering flows through _id_key, never dict/hash
+# iteration, which is what makes the output deterministic and testable.
+
+
+def _id_key(item_id: object) -> tuple[int, object]:
+    """Deterministic sort key for backlog ids.
+
+    All-digit ids sort numerically ("2" before "10"); everything else sorts
+    lexically, after the numeric block. Used everywhere an ordering must not
+    depend on dict/hash iteration.
+
+    Args:
+        item_id: A backlog item id (usually ``str``; coerced defensively).
+
+    Returns:
+        A ``(bucket, value)`` tuple that is a total order across mixed id shapes.
+    """
+    s = str(item_id)
+    return (0, int(s)) if s.isdigit() else (1, s)
+
+
+def _build_dep_index(
+    items: list[dict],
+) -> tuple[dict[str, dict], dict[str, list[str]], dict[str, list[str]]]:
+    """Build the in-backlog dependency adjacency from ``dependsOn`` edges.
+
+    Edges pointing at ids **not present** in this backlog are dropped (an item
+    whose only ``dependsOn`` targets are external is therefore a root).
+
+    Args:
+        items: The runner's item array (each a dict with at least ``id``; optional
+            ``dependsOn``, ``status``, ``blockedReason``).
+
+    Returns:
+        ``(by_id, deps, dependents)`` where ``by_id`` maps id → item, ``deps`` maps
+        id → the ids it depends on (in-backlog only), and ``dependents`` maps id →
+        the ids that directly depend on it.
+    """
+    by_id = {str(it["id"]): it for it in items}
+    deps: dict[str, list[str]] = {
+        i: [str(d) for d in (by_id[i].get("dependsOn") or []) if str(d) in by_id]
+        for i in by_id
+    }
+    dependents: dict[str, list[str]] = {i: [] for i in by_id}
+    for i, ds in deps.items():
+        for d in ds:
+            dependents[d].append(i)
+    return by_id, deps, dependents
+
+
+def _transitive_dependents(
+    dependents: dict[str, list[str]],
+) -> dict[str, set[str]]:
+    """Memoized transitive-dependents (gated-subtree) closure for every node.
+
+    ``dependents[x]`` lists items that directly depend on ``x``; the returned map
+    gives, for each item, the set of items that **transitively** depend on it — the
+    gated subtree that item's completion would unblock ("gates").
+
+    Cycle-safe: a node re-encountered on the current DFS path contributes nothing
+    and is not memoized (rauf rejects cycles upstream, so this only hardens against
+    malformed input; it never fires on validated backlogs).
+
+    Args:
+        dependents: The reverse adjacency from :func:`_build_dep_index`.
+
+    Returns:
+        A map id → set of transitively-dependent ids. O(V + E) overall (each edge
+        is walked once thanks to memoization).
+    """
+    memo: dict[str, set[str]] = {}
+
+    def visit(node: str, on_path: set[str]) -> set[str]:
+        if node in memo:
+            return memo[node]
+        if node in on_path:  # cycle guard — unreachable on validated backlogs
+            return set()
+        on_path.add(node)
+        acc: set[str] = set()
+        for child in dependents[node]:
+            acc.add(child)
+            acc |= visit(child, on_path)
+        on_path.discard(node)
+        memo[node] = acc
+        return acc
+
+    for n in dependents:
+        visit(n, set())
+    return memo
+
+
+#: A token that is a pure number or item-id-shaped (``42``, ``req12``, ``t7``) —
+#: noise carrying no cause signal, dropped by _normalize_reason.
+_ID_SHAPED_TOKEN = re.compile(r"^(?:\d+|[a-z]*\d+)$")
+
+
+def _normalize_reason(text: str | None) -> set[str]:
+    """Normalize a ``blockedReason`` into its comparison token set.
+
+    Lowercases, splits on any run of non-alphanumeric characters, and drops noise
+    tokens — pure numbers and item-id-shaped tokens (``42``, ``req12``, ``t7``) —
+    which carry no cause signal and would spuriously separate or merge reasons.
+
+    Args:
+        text: The item's ``blockedReason`` (may be ``None``/empty).
+
+    Returns:
+        The set of meaningful lowercased tokens (possibly empty).
+    """
+    tokens = re.split(r"[^a-z0-9]+", (text or "").lower())
+    return {t for t in tokens if t and not _ID_SHAPED_TOKEN.match(t)}
+
+
+def _jaccard(a: set[str], b: set[str]) -> float:
+    """Jaccard similarity |A∩B| / |A∪B| of two token sets.
+
+    Symmetric and order-insensitive. Two empty sets score ``0.0`` — an item with
+    no meaningful reason tokens never clusters with anything.
+
+    Args:
+        a: First token set.
+        b: Second token set.
+
+    Returns:
+        A similarity in ``[0.0, 1.0]``.
+    """
+    union = a | b
+    return len(a & b) / len(union) if union else 0.0
+
+
+def cluster_blocked(items: list[dict]) -> list[dict]:
+    """Cluster blocked items by ``blockedReason`` similarity.
+
+    Union-find over every pair of ``status == "blocked"`` items whose normalized
+    token-set Jaccard is ``>= CLUSTER_JACCARD_THRESHOLD``. Each emitted component
+    carries its member ids, the members' raw reasons, the shared token core, and
+    the **union** of the members' gated subtrees for blast-radius framing.
+    Components of size 1 are emitted too — the recovery procedure consolidates
+    only components of >= 2, prompting singletons per item.
+
+    The result is the deterministic *substrate*: the agent may merge components it
+    judges to share a cause (under-clustering is the deliberately chosen failure
+    direction). It never reads disk; ``items`` is the runner's array.
+
+    Args:
+        items: The runner's ``listCommand`` item array.
+
+    Returns:
+        A list of cluster dicts, sorted by lowest member id:
+        ``{clusterId, memberIds, memberReasons, sharedTokens, gatedIds, gatedCount}``.
+    """
+    by_id, _deps, dependents = _build_dep_index(items)
+    gated = _transitive_dependents(dependents)
+    blocked = sorted(
+        (i for i, it in by_id.items() if it.get("status") == "blocked"),
+        key=_id_key,
+    )
+    tokens = {i: _normalize_reason(by_id[i].get("blockedReason")) for i in blocked}
+
+    parent = {i: i for i in blocked}
+
+    def find(x: str) -> str:
+        while parent[x] != x:
+            parent[x] = parent[parent[x]]  # path halving
+            x = parent[x]
+        return x
+
+    def union(a: str, b: str) -> None:
+        ra, rb = find(a), find(b)
+        if ra == rb:
+            return
+        lo, hi = sorted((ra, rb), key=_id_key)  # lowest id is the component root
+        parent[hi] = lo
+
+    for idx, a in enumerate(blocked):
+        for b in blocked[idx + 1:]:
+            if _jaccard(tokens[a], tokens[b]) >= CLUSTER_JACCARD_THRESHOLD:
+                union(a, b)
+
+    groups: dict[str, list[str]] = {}
+    for i in blocked:
+        groups.setdefault(find(i), []).append(i)
+
+    clusters: list[dict] = []
+    for root in sorted(groups, key=_id_key):
+        members = sorted(groups[root], key=_id_key)
+        shared = set.intersection(*(tokens[m] for m in members)) if members else set()
+        union_gated: set[str] = set()
+        for m in members:
+            union_gated |= gated[m]
+        union_gated -= set(members)  # a member gating a sibling is not its own blast radius
+        clusters.append(
+            {
+                "clusterId": "c" + members[0],  # "c" + lowest member id: stable across runs
+                "memberIds": members,
+                "memberReasons": [by_id[m].get("blockedReason") or "" for m in members],
+                "sharedTokens": sorted(shared),
+                "gatedIds": sorted(union_gated, key=_id_key),
+                "gatedCount": len(union_gated),
+            }
+        )
+    return clusters
+
+
+def _max_chain_depth(by_id: dict[str, dict], deps: dict[str, list[str]]) -> int:
+    """Longest ``dependsOn`` chain length (node count), memoized and cycle-safe.
+
+    Depth of a node = ``1 + max(depth(dep) …)`` over its in-backlog dependencies;
+    the result is the maximum over all nodes. A node re-seen on the current path
+    contributes ``0`` (cycle guard; unreachable on validated backlogs).
+
+    Args:
+        by_id: id → item, from :func:`_build_dep_index`.
+        deps: id → dependency ids, from :func:`_build_dep_index`.
+
+    Returns:
+        The longest chain length; ``0`` for an empty backlog.
+    """
+    memo: dict[str, int] = {}
+
+    def depth(node: str, on_path: set[str]) -> int:
+        if node in memo:
+            return memo[node]
+        if node in on_path:  # cycle guard
+            return 0
+        on_path.add(node)
+        d = 1 + max((depth(x, on_path) for x in deps[node]), default=0)
+        on_path.discard(node)
+        memo[node] = d
+        return d
+
+    return max((depth(n, set()) for n in by_id), default=0)
+
+
+def compute_topology(items: list[dict]) -> dict:
+    """Compute dependency-topology metrics + advisory warnings (REQ-TOPO-01..03).
+
+    Pure function over the runner's item array (single data source, decision
+    V-007) — it never reads ``backlog.json`` off disk, so every derived count
+    cites the runner's authoritative array (REQ-ATTR-01, REQ-OBS-01). Linear via
+    the memoized DFS helpers above (REQ-PERF-01).
+
+    Args:
+        items: The runner's ``listCommand`` item array. Each item may carry
+            ``id``, ``dependsOn`` (list of ids), and ``status`` (``pending``/
+            ``done``/``blocked``/…).
+
+    Returns:
+        The ``backlog-topology`` output shape (without ``clusters`` — that is
+        appended by the verb under ``--cluster``): ``{itemCount, rootCount,
+        roots, maxChainDepth, selectable, starvation, warnings}``.
+    """
+    by_id, deps, dependents = _build_dep_index(items)
+    item_count = len(by_id)
+    gated = _transitive_dependents(dependents)
+
+    roots = [i for i in by_id if not deps[i]]  # no in-backlog dependsOn edges
+    roots_out = sorted(
+        (
+            {
+                "id": r,
+                "gatedCount": len(gated[r]),
+                "gatedIds": sorted(gated[r], key=_id_key),
+            }
+            for r in roots
+        ),
+        key=lambda row: _id_key(row["id"]),
+    )
+
+    max_depth = _max_chain_depth(by_id, deps)
+
+    selectable = sum(
+        1
+        for i, it in by_id.items()
+        if it.get("status") == "pending"
+        and all(by_id[d].get("status") == "done" for d in deps[i])
+    )
+    pending = sum(1 for it in by_id.values() if it.get("status") == "pending")
+
+    fanout_threshold = math.ceil(TOPOLOGY_FANOUT_WARN_RATIO * item_count)
+    depth_threshold = math.ceil(TOPOLOGY_DEPTH_WARN_RATIO * item_count)
+
+    # A trivial graph (0-1 items, or no dependsOn edges at all) has no topology
+    # to warn about — a single node's depth of 1 would otherwise trip the
+    # ceil(0.5 * 1) = 1 depth threshold on every one-item backlog.
+    warnings: list[str] = []
+    if item_count > 1 and any(deps[i] for i in by_id):
+        if any(row["gatedCount"] >= fanout_threshold for row in roots_out):
+            warnings.append("single-root-fanout")
+        if max_depth >= depth_threshold:
+            warnings.append("chain-depth")
+
+    starvation = None
+    if selectable == 0 and pending > 0:
+        starvation = {
+            "starved": True,
+            "blockingRoots": [
+                {"id": row["id"], "gatedCount": row["gatedCount"]}
+                for row in roots_out
+                if row["gatedCount"] > 0 and by_id[row["id"]].get("status") != "done"
+            ],
+        }
+
+    return {
+        "itemCount": item_count,
+        "rootCount": len(roots),
+        "roots": roots_out,
+        "maxChainDepth": max_depth,
+        "selectable": selectable,
+        "starvation": starvation,
+        "warnings": warnings,
+    }
+
+
+def cmd_backlog_topology(items: list[dict], *, with_clusters: bool) -> dict:
+    """Assemble the ``backlog-topology`` payload.
+
+    Args:
+        items: The runner's ``listCommand`` item array.
+        with_clusters: When true, append the ``clusters`` section.
+
+    Returns:
+        The topology dict; with ``clusters`` appended iff ``with_clusters``.
+    """
+    result = compute_topology(items)
+    if with_clusters:
+        result["clusters"] = cluster_blocked(items)
+    return result
+
+
+def _load_topology_items(args: argparse.Namespace) -> list[dict]:
+    """Read and parse the runner item array for ``backlog-topology``.
+
+    Accepts either a top-level JSON array or an object with an ``items`` array
+    (rauf ``backlog list --json`` emits the array; the object form is tolerated
+    for forward-compatibility). All failures raise ``UsageError`` → exit 2,
+    never a partial/guessed result. This is the ONLY input path for the
+    topology verb — it never opens ``backlog.json`` off disk (single data
+    source, decision V-007).
+
+    Args:
+        args: Parsed namespace with ``items_stdin`` / ``items_json``.
+
+    Returns:
+        The item list.
+
+    Raises:
+        UsageError: unreadable ``--items-json``, invalid JSON, or a shape that is
+            neither an array nor an object carrying an ``items`` array.
+    """
+    if args.items_stdin:
+        raw = sys.stdin.read()
+    else:
+        try:
+            raw = Path(args.items_json).read_text(encoding="utf-8")
+        except OSError as exc:
+            raise UsageError(f"cannot read --items-json {args.items_json}: {exc}") from exc
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise UsageError(f"invalid items JSON: {exc}") from exc
+    items = data.get("items", []) if isinstance(data, dict) else data
+    if not isinstance(items, list):
+        raise UsageError("items JSON must be an array or an object with an 'items' array")
+    return items
+
+
+def _print_topology(payload: dict) -> None:
+    """Human-readable topology summary (machine consumers pass ``--json``)."""
+    print(
+        f"Topology: {payload['itemCount']} items, {payload['rootCount']} roots, "
+        f"max chain depth {payload['maxChainDepth']}, selectable {payload['selectable']}"
+    )
+    for row in sorted(payload["roots"], key=lambda r: -r["gatedCount"]):
+        print(f"  root {row['id']} gates {row['gatedCount']} item(s)")
+    for warning in payload["warnings"]:
+        print(f"  warning: {warning}")
+    starvation = payload.get("starvation")
+    if starvation:
+        blocking = ", ".join(r["id"] for r in starvation["blockingRoots"])
+        print(f"  starved: no selectable item; blocking roots: {blocking}")
+    for cluster in payload.get("clusters", []):
+        members = ", ".join(cluster["memberIds"])
+        print(
+            f"  cluster {cluster['clusterId']}: members {members} "
+            f"(gates {cluster['gatedCount']} item(s))"
+        )
+
+
 # --------------------------------------------------------------------------- #
 # Scripted Stage Exit
 # --------------------------------------------------------------------------- #
@@ -2869,6 +3334,36 @@ _DOCS_OUTCOME_TEXT: Final[dict[str, str]] = {
         "nor epic {epic} is complete. Only valid partial state was persisted. Open "
         "the epic dashboard below to see the epic's live state and recover from there."
     ),
+    # The `skipped` variants (#197): same routes as `complete`, honest wording — a
+    # deliberate skip closes the pipeline without any stage claiming artifacts it
+    # never produced, and the state says `skipped`, not `complete`.
+    "standalone-skipped": (
+        "Documentation was deliberately skipped for {feature} and recorded as "
+        "`skipped` in state, closing the pipeline without claiming docs that were "
+        "never written. The navigator command below is the authoritative completion "
+        "action — it confirms the finished state from disk. Docs can still be "
+        "generated later by re-running `{docs_stage}`. Optionally, you can start a "
+        "new feature with `{new_feature}` or group related work into an epic with "
+        "`{new_epic}`; neither is required to finish here."
+    ),
+    "epic-actionable-skipped": (
+        "Documentation was deliberately skipped for {feature} and recorded as "
+        "`skipped` in state. Epic {epic} has more work that can be started now "
+        "({complete}/{total} members complete), so the pipeline continues with the "
+        "next actionable member below."
+    ),
+    "epic-blocked-members-skipped": (
+        "Documentation was deliberately skipped for {feature} and recorded as "
+        "`skipped` in state, but no member of epic {epic} is actionable right now "
+        "({complete}/{total} members complete) — the remaining work is blocked by "
+        "unmet dependencies. Open the epic dashboard below to see what is holding "
+        "it up."
+    ),
+    "epic-complete-skipped": (
+        "Documentation was deliberately skipped for {feature} and recorded as "
+        "`skipped` in state, and every member of epic {epic} is now complete "
+        "({complete}/{total}). Open the epic dashboard below for its completion view."
+    ),
 }
 
 
@@ -2882,13 +3377,15 @@ def _docs_route(
     next member routes to that member's own live command, and anything else (blocked
     remaining work, or every member complete) routes to the epic dashboard, which is
     also the dashboard's completion view. A ``blocked`` docs outcome routes to
-    recovery and NEVER claims pipeline completion.
+    recovery and NEVER claims pipeline completion. A ``skipped`` outcome (#197)
+    takes exactly the routes ``complete`` takes — the pipeline still ends here —
+    but its wording says the docs were deliberately skipped, never that they exist.
 
     Args:
         feature: The feature whose documentation stage is closing.
         epic: The owning epic, or None for a standalone feature.
         specs_dir: Configured specs directory.
-        outcome: `complete` or `blocked`, already validated.
+        outcome: `complete`, `blocked`, or `skipped`, already validated.
         host: Host surface, used only to translate the INLINE secondary mentions —
             the primary command is translated by the renderer.
 
@@ -2903,12 +3400,11 @@ def _docs_route(
     rather than converting into a second failure.
     """
     if epic is None:
-        text = _DOCS_OUTCOME_TEXT[
-            "standalone-complete" if outcome == "complete" else "standalone-blocked"
-        ].format(
+        text = _DOCS_OUTCOME_TEXT[f"standalone-{outcome}"].format(
             feature=feature,
             new_feature=_host_command("/skill:forge-1-prd <new-feature>", host),
             new_epic=_host_command("/skill:forge-0-epic <new-epic>", host),
+            docs_stage=_host_command(f"/skill:forge-6-docs {feature}", host),
         )
         return f"/skill:forge {feature}", None, text, False
 
@@ -2917,6 +3413,7 @@ def _docs_route(
         text = _DOCS_OUTCOME_TEXT["epic-blocked"].format(feature=feature, epic=epic)
         return dashboard, None, text, False
 
+    skip_suffix = "-skipped" if outcome == "skipped" else ""
     status = _render_status(specs_dir, epic)
     rollup = status["rollup"]
     fields = {
@@ -2927,7 +3424,12 @@ def _docs_route(
     }
     next_command = status["nextCommand"]
     if status["actionable"] and next_command:
-        return next_command, None, _DOCS_OUTCOME_TEXT["epic-actionable"].format(**fields), True
+        return (
+            next_command,
+            None,
+            _DOCS_OUTCOME_TEXT["epic-actionable" + skip_suffix].format(**fields),
+            True,
+        )
     # Nothing actionable. Under the current derivation that coincides with "every
     # member complete" (a valid graph is acyclic, so an incomplete member always has
     # an actionable ancestor), but the two cases are named separately and the
@@ -2935,7 +3437,7 @@ def _docs_route(
     # reachable if a future derivation admits an unactionable incomplete member. Both
     # route to the same epic command either way; only the explanation differs.
     key = "epic-complete" if rollup["complete"] >= rollup["total"] else "epic-blocked-members"
-    return dashboard, None, _DOCS_OUTCOME_TEXT[key].format(**fields), False
+    return dashboard, None, _DOCS_OUTCOME_TEXT[key + skip_suffix].format(**fields), False
 
 
 #: The route each loop outcome takes. A COMPLETE map over
@@ -2953,6 +3455,7 @@ _LOOP_ROUTE_KIND: Final[dict[str, str]] = {
     "complete": "handoff",
     "partial": "resume",
     "deferred": "resume",
+    "resolved": "resume",
     "blocked": "recover",
     "needs-human": "recover",
 }
@@ -2986,8 +3489,26 @@ _LOOP_OUTCOME_TEXT: Final[dict[str, str]] = {
         "navigator below to see the live pipeline state from disk and recover from "
         "there."
     ),
+    "resolved": (
+        "The needs-human stop for {feature} was resolved — the recorded decisions "
+        "were applied and every affected item was verified, per item, to have left "
+        "blocked/needsHuman, with the working tree clean. The recorded state is "
+        "resumable and nothing downstream is ready: run the loop again below to "
+        "continue from where it stopped."
+    ),
 }
 
+#: The starvation variant of the `partial` next-steps sentence (REQ-ATTR-02): names
+#: the unblock path instead of the iteration limit, which was NOT the binding
+#: constraint. Selected only by ``--cause dependency-starvation`` (REQ-ATTR-04).
+_LOOP_PARTIAL_STARVED_TEXT: Final[str] = (
+    "The loop stopped for {feature} with backlog items still pending, but the "
+    "iteration limit was NOT the constraint — no pending item was selectable because "
+    "unblocked root items gate the rest of the backlog. The recorded state is "
+    "resumable and nothing downstream is ready: unblock the roots named in the "
+    "starvation report above, then run the loop again below to continue."
+)
+
 #: 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).
@@ -3043,8 +3564,10 @@ _RECONCILE_FIRST_TEXT: Final[dict[str, str]] = {
         "the continuation named under it."
     ),
     "forge-6-docs": (
-        "Documentation is complete for {feature}, but {count} blocking epic change "
-        "request{plural} recorded against epic {epic} must be reconciled first. "
+        # "closed", not "complete": this wording also serves a `skipped` docs
+        # outcome, which must never claim the docs exist (#197).
+        "The documentation stage is closed for {feature}, but {count} blocking epic "
+        "change request{plural} recorded against epic {epic} must be reconciled first. "
         "Handing off would build the next member on a decomposition that is about to "
         "change, so the reconcile below comes before the continuation named under it."
     ),
@@ -3123,6 +3646,7 @@ def _loop_route(
     resolved: bool,
     verify_canonical: str,
     fix_canonical: str | None,
+    cause: str | None = None,
 ) -> tuple[str, str | None, str, bool]:
     """Route one loop result — the outcome table.
 
@@ -3147,6 +3671,10 @@ def _loop_route(
             else None. A live report outranks a fresh verify on the ``complete``
             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).
 
     Returns:
         `(primary_canonical, deferred_canonical, outcome_text, advancing)`, matching
@@ -3171,7 +3699,11 @@ def _loop_route(
             if kind == "resume"
             else f"/skill:forge {feature}"
         )
-        return primary, None, _LOOP_OUTCOME_TEXT[outcome].format(feature=feature), False
+        if outcome == "partial" and cause == "dependency-starvation":
+            text = _LOOP_PARTIAL_STARVED_TEXT.format(feature=feature)
+        else:
+            text = _LOOP_OUTCOME_TEXT[outcome].format(feature=feature)
+        return primary, None, text, False
 
     handoff = successor_command or f"/skill:forge {feature}"
     fields: dict[str, object] = {"feature": feature, "epic": epic}
@@ -3334,6 +3866,7 @@ def stage_exit(
     outcome: str | None = None,
     owner: str | None = None,
     verify_capability: str = "manual",
+    cause: str | None = None,
 ) -> StageExitPayload:
     """Compute a deterministic stage-exit payload.
 
@@ -3354,6 +3887,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.
 
     Returns:
         A JSON-serializable `StageExitPayload` dictionary.
@@ -3484,6 +4021,14 @@ def stage_exit(
             f"{', '.join(sorted(allowed_outcomes))}"
         )
 
+    # --cause is a forge-5-loop/partial-only attribution annotation (REQ-ATTR-04).
+    # 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 "
+            "--stage forge-5-loop --outcome partial"
+        )
+
     # 5. Ownership: required for the branch skills, rejected for stages 0-6.
     if stage in _BRANCH_STAGES:
         if owner is None:
@@ -3687,12 +4232,33 @@ def stage_exit(
     # hands off the same way the epic's own exit does. Identical to the previous
     # behavior for every production exit, where `route_stage is stage`.
     if route_stage == "forge-0-epic" and next_feature is None:
-        # An epic exit that names no concrete member has nothing to hand off to.
-        # The dashboard is the same non-fabrication answer given to a named member
-        # that has finished every production stage: never invent a member, and
-        # never print a template the user cannot run.
-        next_stage_id = None
-        next_command = f"/skill:forge-0-epic {feature}"
+        # A branch exit (verify/fix) that served forge-0-epic cannot carry
+        # --next-feature (the CLI rejects it for non-epic stages), so the member
+        # must be resolved HERE from live epic state.  Creation-mode exits pass
+        # --next-feature and skip this block entirely (#230).
+        try:
+            status = _render_status(specs_dir, feature)
+            actionable = status["actionable"]
+            if actionable:
+                resolved_member = actionable[0]
+                ms, mr = _epic_member_state(specs_dir, feature, resolved_member)
+                if mr is not None:
+                    next_stage_id = "forge-1-prd"
+                    next_command = f"/skill:forge-1-prd {resolved_member}"
+                else:
+                    member_next = next_stage(ms)
+                    if member_next is None:
+                        next_stage_id = None
+                        next_command = f"/skill:forge-0-epic {feature}"
+                    else:
+                        next_stage_id = member_next
+                        next_command = f"/skill:{member_next} {resolved_member}"
+            else:
+                next_stage_id = None
+                next_command = f"/skill:forge-0-epic {feature}"
+        except UsageError:
+            next_stage_id = None
+            next_command = f"/skill:forge-0-epic {feature}"
     else:
         next_arg = next_feature or feature
         next_command = (
@@ -3822,6 +4388,7 @@ def stage_exit(
             resolved,
             verify_canonical,
             fix_canonical if live_findings_report else None,
+            cause,
         )
         if blocking_reconcile:
             # Same reconcile-first rule as every other advancing route — but the
@@ -4102,7 +4669,8 @@ def _write_state(state_path: Path, state: dict) -> None:
     the temp file onto the target. os.replace is atomic on POSIX within one
     filesystem, so an interrupted write never leaves a partial or corrupt state
     file. Concurrent multi-session mutation is out of scope (single writer
-    assumed, matching epic-manifest.py).
+    assumed, matching epic-manifest.py; decision record:
+    references/decisions/single-writer-threat-model.md, issue #180).
 
     Args:
         state_path: Destination path, e.g.
@@ -4708,6 +5276,62 @@ def cmd_state_complete(
     return echo
 
 
+def cmd_state_skip(feature: str, stage: str, specs_dir: Path, epic: str | None) -> dict:
+    """Record a deliberate skip of the documentation stage (#197).
+
+    Writes a REPLACEMENT ``stages.forge-6-docs`` entry ``{"status": "skipped",
+    "skippedAt": …, "commitHash": null}`` — the honest terminal for a feature
+    that ships without architecture docs. ``skipped`` counts as done for
+    next-stage selection (``_DONE_STATUSES``), so the pipeline reads
+    ``complete: true`` / ``nextStage: null`` without any stage claiming
+    artifacts it never produced.
+
+    Scoped to ``forge-6-docs`` on purpose: a skipped PRD or specs stage is a
+    different and much worse proposition, so both the CLI (``choices``) and this
+    callable refuse any other stage.
+
+    The skip must not DESTROY a record of docs that exist: a prior entry whose
+    ``artifacts`` list is non-empty is refused. A prior ``complete`` entry with
+    no recorded artifacts is exactly the dishonest workaround this verb replaces
+    (``state-complete`` with no ``--artifact``), so it may be corrected to
+    ``skipped`` — that is the sanctioned migration path for such state.
+
+    Args:
+        feature: Feature name.
+        stage: Must be ``"forge-6-docs"`` (kept explicit so the scoping shows up
+            in every call site).
+        specs_dir: Specs directory.
+        epic: Owning epic name, or None.
+
+    Returns:
+        The mutated state dict (for the --json echo).
+
+    Raises:
+        UsageError: A stage other than forge-6-docs, a prior entry recording
+            artifacts, an unknown feature directory, an unparseable state file,
+            or a failed atomic write (→ exit 2).
+    """
+    if stage != "forge-6-docs":
+        raise UsageError(
+            f"state-skip is scoped to forge-6-docs; a skipped {stage} is not a "
+            "representable pipeline state"
+        )
+    state_path, state = _load_state_for_write(specs_dir, feature, epic)
+    prior = state.get("stages", {}).get(stage)
+    if isinstance(prior, dict) and prior.get("artifacts"):
+        raise UsageError(
+            f"{stage} already records {len(prior['artifacts'])} artifact(s) "
+            f"(status: {prior.get('status')!r}); skipping now would erase the "
+            "record that docs exist. Re-run forge-6-docs to refresh them instead."
+        )
+    state.setdefault("stages", {})[stage] = {
+        "status": "skipped",
+        "skippedAt": _now_iso(),
+        "commitHash": None,
+    }
+    return _commit_state(state_path, state)
+
+
 def cmd_state_branch(feature: str, branch: str, specs_dir: Path, epic: str | None) -> dict:
     """Set the top-level ``branch`` field.
 
@@ -4966,10 +5590,12 @@ def _validated_findings_file(
 def _current_artifact_version(state: dict, stage: str) -> int:
     """Return the artifact revision a verify result is being recorded against.
 
-    For a feature target that is the selected production stage's ``version``. A
-    result other than ``skipped`` cannot be recorded without it: `passed` and
+    For a feature target that is the selected production stage's ``version``.
+    Only the statuses that consume it resolve it: `passed` and
     `findings-reported` write it into the freshness ledger, and
     `auto-verify-pending` writes it as the revision the debt is owed on.
+    `skipped` and `findings-applied` never read it and skip the lookup, so both
+    stay recordable on a completed stage with no recorded ``version``.
 
     Args:
         state: The loaded state document.
@@ -5074,7 +5700,8 @@ def _verify_result_entry(
     Args:
         status: The validated result status.
         prior: The existing entry (``{}`` when absent).
-        current: The current artifact revision, or None for ``skipped``.
+        current: The current artifact revision, or None for ``skipped`` and
+            ``findings-applied`` (which never consume it).
         findings_file: Validated relative report path, when supplied.
         findings_count: Validated non-negative count, when supplied.
         now: The shared ISO-8601 timestamp for this write.
@@ -5343,7 +5970,12 @@ def cmd_state_verify(
     if findings_file is not None:
         _validated_findings_file(findings_file, target_dir)
 
-    if status == "skipped":
+    if status in ("skipped", "findings-applied"):
+        # Neither status consumes the artifact revision: `skipped` records no
+        # freshness, and `findings-applied` deliberately clears it (the entry is
+        # built from the prior report plus `fixedAt`). Resolving it anyway would
+        # make both unrecordable on a completed stage whose `version` was never
+        # written — exactly the state that needs the recovery path (#202).
         current = None
     elif is_epic_target:
         # The epic's artifact revision is the manifest revision — never a member's
@@ -5363,6 +5995,20 @@ def cmd_state_verify(
         )
 
     prior = _verify_entry(state, verify_key)
+    if status == "skipped" and prior.get("status") in _SKIP_PROTECTED_PRIOR:
+        # The #203 demotion trap: `skipped` over a complete-for-orchestration
+        # status silently dropped the member from its epic rollup and re-blocked
+        # every dependent. Fail closed; a deferral needs no write at all.
+        raise UsageError(
+            f"--status skipped would demote {verify_key} from "
+            f"{prior.get('status')!r}: that status counts as resolved (and, for an "
+            f"epic member, complete-for-orchestration), so replacing it with "
+            f"skipped would drop the member from its epic rollup and re-block its "
+            f"dependents. A deferral needs no write — the recorded result already "
+            f"stands. Re-run verification to refresh it, or record --status passed "
+            f"(with the report attached) to accept residual findings. "
+            f"Nothing was written."
+        )
     if status == "auto-verify-pending" and prior.get("status") == "findings-reported":
         # `_verify_result_entry` REPLACES the entry, so scheduling over a report
         # for the current revision would delete its `findingsFile`/`findingsCount`
@@ -5453,6 +6099,14 @@ def _print_state_complete(
     )
 
 
+def _print_state_skip(state: dict, stage: str) -> None:
+    """Print the one-line human summary for `state-skip`."""
+    print(
+        f"recorded {stage} as skipped for {state['feature']} "
+        "(deliberate — no docs claimed)"
+    )
+
+
 def _print_state_branch(state: dict) -> None:
     """Print the one-line human summary for `state-branch`."""
     print(f"recorded branch for {state['feature']}: {state['branch']}")
@@ -5506,6 +6160,338 @@ def _print_state_ecr(state: dict) -> None:
     )
 
 
+# --------------------------------------------------------------------------- #
+# Decision record (forge-decisions.json) — the decision-* verbs
+# --------------------------------------------------------------------------- #
+
+#: The one persistent artifact this feature adds; only decision-* verbs write it.
+DECISIONS_FILENAME: Final[str] = "forge-decisions.json"
+#: Enum-locked at references/forge-decisions-schema.json; a bump is a breaking change.
+DECISIONS_SCHEMA_VERSION: Final[str] = "1"
+
+
+def _resolve_decisions_path(
+    backlog_dir: Path,
+    state_dir: str | None,
+    config_path: Path,
+    schema_path: Path,
+) -> Path:
+    """Resolve `{backlog_dir}/{stateDir}/forge-decisions.json`.
+
+    When ``state_dir`` is None, ``stateDir`` is taken from the effective loopRunner
+    config (schema default ``.rauf``) via ``resolve_loop_runner`` — the same resolver
+    the loop itself uses — so the record lands beside the runner's own state and is
+    covered by the ``**/.rauf/*`` ignore rule with zero ``.gitignore`` edits.
+
+    Args:
+        backlog_dir: The resolved backlog directory (e.g. ``specs/loop-recovery``).
+        state_dir: An explicit state-dir name, or None to resolve from config.
+        config_path: ``forge.config.json`` path (``_load_config`` tolerates absent).
+        schema_path: ``forge-config-schema.json`` path (source of the default).
+
+    Returns:
+        The resolved path to the decision record (its parent may not yet exist).
+    """
+    if state_dir is None:
+        resolved = resolve_loop_runner(config_path, schema_path)
+        state_dir = str(resolved["stateDir"])
+    return backlog_dir / state_dir / DECISIONS_FILENAME
+
+
+def _read_decisions_for_write(path: Path, feature: str) -> dict:
+    """Load the decisions document for mutation, or seed a fresh one on first write.
+
+    A MISSING file is the first-write case → return a fresh skeleton whose parent
+    dir is created on commit. An UNPARSEABLE or non-object existing file is a HARD
+    failure (exit 2) — a write path must not inherit ``_read_state``'s corrupt→{}
+    tolerance, which would atomically replace a recoverable record with a
+    near-empty one.
+
+    Args:
+        path: The resolved decision-record path.
+        feature: The feature label to stamp on a first write (backlog dir basename).
+
+    Returns:
+        The loaded (or freshly-seeded) decisions document, ready to mutate.
+
+    Raises:
+        UsageError: The existing file is unreadable/unparseable or not a JSON object.
+    """
+    if not path.exists():
+        return {
+            "schemaVersion": DECISIONS_SCHEMA_VERSION,
+            "feature": feature,
+            "createdAt": _now_iso(),
+            "decisions": [],
+        }
+    try:
+        parsed = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise UsageError(f"unparseable decision record at {path}: {exc}") from exc
+    if not isinstance(parsed, dict):
+        raise UsageError(f"decision record at {path} is not a JSON object")
+    return parsed
+
+
+def _new_decision_entry(
+    item_id: str,
+    question: str,
+    answer: str | None,
+    deferred: bool,
+    cluster_id: str | None,
+    actor: str,
+) -> dict:
+    """Build one decision entry conforming to references/forge-decisions-schema.json.
+
+    Args:
+        item_id: The backlog item the decision answers.
+        question: The needs-human question text (original text on a deferral).
+        answer: The operator's answer, or None for a deferral.
+        deferred: True iff this is a deferral / cancel-early entry.
+        cluster_id: Shared clusterId for a consolidated decision, or None.
+        actor: The session/actor label for ``recordedBy`` (never user identity).
+
+    Returns:
+        A dict carrying all eight required fields (``appliedAt``/``appliedBy`` null),
+        plus ``clusterId`` when supplied.
+    """
+    entry: dict = {
+        "itemId": item_id,
+        "question": question,
+        "answer": answer,
+        "deferred": deferred,
+        "decidedAt": _now_iso(),
+        "recordedBy": actor,
+        "appliedAt": None,
+        "appliedBy": None,
+    }
+    if cluster_id is not None:
+        entry["clusterId"] = cluster_id
+    return entry
+
+
+def _default_actor() -> str:
+    """Return the default recordedBy/appliedBy label: ``forge-5-loop@<host>``.
+
+    The host segment is a machine label, not a user identity (REQ-SEC-01).
+    """
+    return f"forge-5-loop@{socket.gethostname()}"
+
+
+def _unapplied_decisions(decisions: list[dict]) -> list[dict]:
+    """Return the latest entry per itemId whose ``appliedAt`` is None (REQ-DEC-05).
+
+    Walks entries in stored (append) order keeping the LAST entry seen per itemId,
+    then keeps only those still unapplied. Deferrals (never applied) are included
+    (REQ-DEC-06); an item whose latest entry is applied drops out; a later
+    per-item entry supersedes an earlier consolidated (clusterId) one for that item
+    only (REQ-DEC-07). Output is sorted by itemId for deterministic reporting.
+
+    Args:
+        decisions: The document's ``decisions`` array, in stored order.
+
+    Returns:
+        The unapplied entries, one per item, sorted by ``itemId``.
+    """
+    latest: dict[str, dict] = {}
+    for entry in decisions:
+        latest[entry["itemId"]] = entry
+    return [
+        entry for _item_id, entry in sorted(latest.items())
+        if entry.get("appliedAt") is None
+    ]
+
+
+def cmd_decision_record(
+    backlog_dir: Path,
+    item_ids: list[str],
+    question: str,
+    answer: str | None,
+    deferred: bool,
+    cluster_id: str | None,
+    actor: str,
+    state_dir: str | None,
+    config_path: Path,
+    schema_path: Path,
+) -> dict:
+    """Append one needs-human decision entry per ``--item`` (append-only).
+
+    Records a decision at the moment it is collected (REQ-DEC-01), on EVERY branch:
+    an answered decision (``--answer``), and a deferral or cancel-early
+    (``--deferred`` → ``answer: null``, REQ-DEC-06). With ``--cluster`` the per-item
+    entries of ONE consolidated decision share a ``clusterId`` (REQ-CLU-04) yet stay
+    independently re-decidable (REQ-DEC-07). The file and its
+    ``schemaVersion``/``feature``/``createdAt`` stamp are created on first write.
+    Existing entries are never mutated (append-only).
+
+    Args:
+        backlog_dir: The resolved backlog directory; its basename stamps ``feature``.
+        item_ids: One or more backlog item ids; one entry is appended per id.
+        question: The needs-human question text (original text on a deferral).
+        answer: The operator's answer, or None for a deferral.
+        deferred: True iff this is a deferral / cancel-early entry.
+        cluster_id: Shared ``clusterId`` for a consolidated decision, or None.
+        actor: Session/actor label for ``recordedBy`` (never user identity).
+        state_dir: State-dir name override, or None to resolve from config.
+        config_path: ``forge.config.json`` path (for the stateDir default).
+        schema_path: ``forge-config-schema.json`` path (source of the default).
+
+    Returns:
+        The mutated decisions document (for the ``--json`` echo).
+
+    Raises:
+        UsageError: Missing backlog dir; both/neither of ``--answer``/``--deferred``;
+            an unparseable existing record; or a failed atomic write (→ exit 2).
+    """
+    # Defense in depth: the argparse mutually-exclusive group rejects both/neither
+    # first, but a direct call must fail the same way. Valid states are exactly
+    # (answered, not deferred) or (deferred, no answer).
+    if deferred == (answer is not None):
+        raise UsageError("exactly one of --answer or --deferred is required")
+    if not backlog_dir.is_dir():
+        raise UsageError(f"no backlog directory at {backlog_dir}")
+
+    path = _resolve_decisions_path(backlog_dir, state_dir, config_path, schema_path)
+    doc = _read_decisions_for_write(path, backlog_dir.resolve().name)
+    for item_id in item_ids:
+        doc["decisions"].append(
+            _new_decision_entry(item_id, question, answer, deferred, cluster_id, actor)
+        )
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return _commit_state(path, doc)
+
+
+def cmd_decision_list(
+    backlog_dir: Path,
+    unapplied: bool,
+    state_dir: str | None,
+    config_path: Path,
+    schema_path: Path,
+) -> dict:
+    """Read the decision record back — the full log, or the unapplied set.
+
+    With ``--unapplied`` returns the REQ-DEC-05 set (``_unapplied_decisions``).
+    Without it, echoes the full on-disk document. A missing record returns an
+    empty result at exit 0 (nothing recorded yet is not a failure). This verb
+    never mutates the file; it parses an existing record **strictly** (exit 2 on
+    corruption) for both the plain and ``--unapplied`` forms — it never
+    downgrades a corrupt record to ``{}``.
+
+    Args:
+        backlog_dir: The resolved backlog directory.
+        unapplied: Return only the latest-unapplied-per-item set.
+        state_dir: State-dir name override, or None to resolve from config.
+        config_path: ``forge.config.json`` path (for the stateDir default).
+        schema_path: ``forge-config-schema.json`` path (source of the default).
+
+    Returns:
+        On a plain read: the full document ``{schemaVersion, feature, createdAt,
+        updatedAt, decisions}`` (or ``{"decisions": []}`` when none recorded).
+        On ``--unapplied``: a report view ``{"feature", "unapplied": [...],
+        "count": N}`` (NOT the on-disk shape; it is never written).
+
+    Raises:
+        UsageError: Missing backlog dir, or an unparseable existing record (→ exit 2).
+    """
+    if not backlog_dir.is_dir():
+        raise UsageError(f"no backlog directory at {backlog_dir}")
+    path = _resolve_decisions_path(backlog_dir, state_dir, config_path, schema_path)
+
+    if not path.exists():
+        return {"feature": backlog_dir.resolve().name, "unapplied": [], "count": 0} \
+            if unapplied else {"decisions": []}
+
+    try:
+        doc = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise UsageError(f"unparseable decision record at {path}: {exc}") from exc
+
+    if not unapplied:
+        return doc
+    pending = _unapplied_decisions(doc.get("decisions", []))
+    return {"feature": doc.get("feature"), "unapplied": pending, "count": len(pending)}
+
+
+def cmd_decision_apply(
+    backlog_dir: Path,
+    item_id: str,
+    actor: str,
+    state_dir: str | None,
+    config_path: Path,
+    schema_path: Path,
+) -> dict:
+    """Stamp ``appliedAt``/``appliedBy`` on the LATEST entry for ``item_id``.
+
+    Append-only mutation (REQ-DEC-07): only the most recent entry for the item is
+    touched, and only its ``appliedAt`` (→ ``_now_iso()``) and ``appliedBy``
+    (→ ``actor``) fields. Called by the Post-Run Recovery Procedure only AFTER
+    the runner apply for the item succeeded, so the record's applied state
+    tracks the runner's (REQ-UNB-01).
+
+    Args:
+        backlog_dir: The resolved backlog directory.
+        item_id: The backlog item whose latest decision to stamp applied.
+        actor: The session/actor label for ``appliedBy``.
+        state_dir: State-dir name override, or None to resolve from config.
+        config_path: ``forge.config.json`` path (for the stateDir default).
+        schema_path: ``forge-config-schema.json`` path (source of the default).
+
+    Returns:
+        The mutated decisions document (for the ``--json`` echo).
+
+    Raises:
+        UsageError: Missing backlog dir; no decision recorded for the item; the
+            item's latest entry is already applied (nothing unapplied); an
+            unparseable record; or a failed atomic write (→ exit 2).
+    """
+    if not backlog_dir.is_dir():
+        raise UsageError(f"no backlog directory at {backlog_dir}")
+    path = _resolve_decisions_path(backlog_dir, state_dir, config_path, schema_path)
+    doc = _read_decisions_for_write(path, backlog_dir.resolve().name)
+
+    latest_index: int | None = None
+    for index, entry in enumerate(doc["decisions"]):
+        if entry["itemId"] == item_id:
+            latest_index = index  # keep the LAST match — stored order is chronological
+    if latest_index is None:
+        raise UsageError(f"no decision recorded for item {item_id!r}")
+    entry = doc["decisions"][latest_index]
+    if entry["appliedAt"] is not None:
+        raise UsageError(
+            f"latest decision for item {item_id!r} is already applied "
+            f"(at {entry['appliedAt']}) — nothing unapplied"
+        )
+
+    entry["appliedAt"] = _now_iso()
+    entry["appliedBy"] = actor
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return _commit_state(path, doc)
+
+
+def _print_decision_record(doc: dict) -> None:
+    """One-line human summary for ``decision-record``."""
+    print(f"decision recorded — {len(doc['decisions'])} entr"
+          f"{'y' if len(doc['decisions']) == 1 else 'ies'} on record for {doc['feature']}")
+
+
+def _print_decision_list(view: dict) -> None:
+    """One-line-per-entry human summary for ``decision-list``."""
+    if "unapplied" in view:
+        print(f"{view['count']} unapplied decision(s)")
+        for entry in view["unapplied"]:
+            kind = "deferred" if entry["deferred"] else "answered"
+            print(f"  {entry['itemId']}: {kind} — {entry['question']}")
+    else:
+        print(f"{len(view.get('decisions', []))} decision(s) on record")
+
+
+def _print_decision_apply(doc: dict) -> None:
+    """One-line human summary naming the just-applied entry (max appliedAt)."""
+    applied = [d for d in doc["decisions"] if d["appliedAt"] is not None]
+    entry = max(applied, key=lambda d: d["appliedAt"])
+    print(f"applied decision for item {entry['itemId']} ({entry['appliedBy']})")
+
+
 # --------------------------------------------------------------------------- #
 # CLI dispatch
 # --------------------------------------------------------------------------- #
@@ -5652,6 +6638,11 @@ def main() -> int:
     # argparse cannot express. `stage_exit` validates it against EXIT_OUTCOMES.
     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",),
+        help="Pending-attribution cause; valid only with "
+             "--stage forge-5-loop --outcome partial",
+    )
     p_exit.add_argument("--owner", default=None, choices=get_args(ExitOwner),
                         help="Branch terminal ownership (forge-verify/forge-fix only)")
     p_exit.add_argument("--verify-capability", default="manual",
@@ -5736,6 +6727,16 @@ def main() -> int:
     p_comp.add_argument("--epic", default=None, help="Epic name for a nested member")
     p_comp.add_argument("--json", action="store_true", dest="json_output")
 
+    p_skip = sub.add_parser(
+        "state-skip", help="Record forge-6-docs as deliberately skipped (#197)"
+    )
+    p_skip.add_argument("--feature", required=True, help="Feature name")
+    p_skip.add_argument("--stage", required=True, choices=("forge-6-docs",),
+                        help="The stage being skipped (only forge-6-docs is skippable)")
+    p_skip.add_argument("--specs-dir", default="./specs", help="Specs directory")
+    p_skip.add_argument("--epic", default=None, help="Epic name for a nested member")
+    p_skip.add_argument("--json", action="store_true", dest="json_output")
+
     p_br = sub.add_parser("state-branch", help="Set the top-level branch field")
     p_br.add_argument("--feature", required=True, help="Feature name")
     p_br.add_argument("--branch", required=True, help="Branch name to record")
@@ -5815,6 +6816,74 @@ def main() -> int:
     p_ver.add_argument("--epic", default=None, help="Epic name for a nested member")
     p_ver.add_argument("--json", action="store_true", dest="json_output")
 
+    p_drec = sub.add_parser(
+        "decision-record", help="Append a needs-human decision entry (append-only)"
+    )
+    p_drec.add_argument("--backlog-dir", required=True, dest="backlog_dir",
+                        help="Resolved backlog directory (e.g. specs/loop-recovery)")
+    p_drec.add_argument("--item", required=True, action="append", dest="item_ids",
+                        metavar="ID", help="Backlog item id (repeatable — one entry per id)")
+    p_drec.add_argument("--question", required=True, help="The needs-human question text")
+    _ans = p_drec.add_mutually_exclusive_group(required=True)
+    _ans.add_argument("--answer", default=None, help="The operator's answer")
+    _ans.add_argument("--deferred", action="store_true",
+                      help="Record a deferral / cancel-early (answer: null)")
+    p_drec.add_argument("--cluster", default=None, dest="cluster_id", metavar="CID",
+                        help="Shared clusterId for one consolidated decision (REQ-CLU-04)")
+    p_drec.add_argument("--actor", default=None,
+                        help="Session/actor label for recordedBy (default forge-5-loop@<host>)")
+    p_drec.add_argument("--state-dir", default=None, dest="state_dir",
+                        help="State-dir name (default: effective loopRunner.stateDir)")
+    p_drec.add_argument("--config", default="./forge.config.json",
+                        help="forge.config.json path")
+    p_drec.add_argument("--json", action="store_true", dest="json_output")
+
+    p_dlist = sub.add_parser(
+        "decision-list", help="Read the decision record (or the unapplied set)"
+    )
+    p_dlist.add_argument("--backlog-dir", required=True, dest="backlog_dir",
+                         help="Resolved backlog directory")
+    p_dlist.add_argument("--unapplied", action="store_true",
+                         help="Return only the latest-unapplied-per-item set (REQ-DEC-05)")
+    p_dlist.add_argument("--state-dir", default=None, dest="state_dir",
+                         help="State-dir name (default: effective loopRunner.stateDir)")
+    p_dlist.add_argument("--config", default="./forge.config.json",
+                         help="forge.config.json path")
+    p_dlist.add_argument("--json", action="store_true", dest="json_output")
+
+    p_dapply = sub.add_parser(
+        "decision-apply", help="Mark the latest decision for an item applied"
+    )
+    p_dapply.add_argument("--backlog-dir", required=True, dest="backlog_dir",
+                          help="Resolved backlog directory")
+    p_dapply.add_argument("--item", required=True, dest="item_id", metavar="ID",
+                          help="Backlog item whose latest decision to stamp applied")
+    p_dapply.add_argument("--actor", default=None,
+                          help="Session/actor label for appliedBy (default forge-5-loop@<host>)")
+    p_dapply.add_argument("--state-dir", default=None, dest="state_dir",
+                          help="State-dir name (default: effective loopRunner.stateDir)")
+    p_dapply.add_argument("--config", default="./forge.config.json",
+                          help="forge.config.json path")
+    p_dapply.add_argument("--json", action="store_true", dest="json_output")
+
+    p_topo = sub.add_parser(
+        "backlog-topology",
+        help="Dependency-topology metrics + advisory warnings over a runner item array",
+    )
+    topo_src = p_topo.add_mutually_exclusive_group(required=True)
+    topo_src.add_argument(
+        "--items-json", help="Path to the loopRunner listCommand JSON output"
+    )
+    topo_src.add_argument(
+        "--items-stdin", action="store_true",
+        help="Read the listCommand JSON from stdin",
+    )
+    p_topo.add_argument(
+        "--cluster", action="store_true", dest="with_clusters",
+        help="Append blocked-item clusters for consolidated prompts",
+    )
+    p_topo.add_argument("--json", action="store_true", dest="json_output")
+
     args = parser.parse_args()
 
     try:
@@ -5903,6 +6972,7 @@ def main() -> int:
                 args.outcome,
                 args.owner,
                 args.verify_capability,
+                args.cause,
             )
             if args.json_output:
                 print(json.dumps(payload, indent=2, ensure_ascii=False))
@@ -5960,6 +7030,17 @@ def main() -> int:
             )
             return 0
 
+        if args.cmd == "state-skip":
+            payload = cmd_state_skip(
+                args.feature, args.stage, Path(args.specs_dir), args.epic
+            )
+            _emit(
+                payload,
+                args.json_output,
+                lambda state: _print_state_skip(state, args.stage),
+            )
+            return 0
+
         if args.cmd == "state-branch":
             payload = cmd_state_branch(
                 args.feature, args.branch, Path(args.specs_dir), args.epic
@@ -6020,6 +7101,44 @@ def main() -> int:
             )
             return 0
 
+        if args.cmd == "decision-record":
+            payload = cmd_decision_record(
+                Path(args.backlog_dir),
+                args.item_ids,
+                args.question,
+                args.answer,
+                args.deferred,
+                args.cluster_id,
+                args.actor or _default_actor(),
+                args.state_dir,
+                Path(args.config),
+                _default_schema_path(),
+            )
+            _emit(payload, args.json_output, _print_decision_record)
+            return 0
+
+        if args.cmd == "decision-list":
+            payload = cmd_decision_list(
+                Path(args.backlog_dir), args.unapplied, args.state_dir,
+                Path(args.config), _default_schema_path(),
+            )
+            _emit(payload, args.json_output, _print_decision_list)
+            return 0
+
+        if args.cmd == "decision-apply":
+            payload = cmd_decision_apply(
+                Path(args.backlog_dir), args.item_id, args.actor or _default_actor(),
+                args.state_dir, Path(args.config), _default_schema_path(),
+            )
+            _emit(payload, args.json_output, _print_decision_apply)
+            return 0
+
+        if args.cmd == "backlog-topology":
+            items = _load_topology_items(args)
+            payload = cmd_backlog_topology(items, with_clusters=args.with_clusters)
+            _emit(payload, args.json_output, _print_topology)
+            return 0
+
         raise UsageError(f"unknown command: {args.cmd}")
     except UsageError as exc:
         print(f"Error: {exc}", file=sys.stderr)