@garygentry/feature-forge 0.2.3 → 0.2.5

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

@@ -1,12 +1,16 @@
 #!/usr/bin/env python3
 """Session-aware navigation helpers for the feature-forge pipeline navigator.
 
-Two read-only subcommands that drive the usability features of the `/forge`
+Read-only subcommands that drive the usability features of the `/forge`
 root navigator:
 
     python3 forge-session.py rank-features [--specs-dir DIR] [--json]
     python3 forge-session.py context-usage [--config FILE] [--window N] \
         [--threshold F] [--json]
+    python3 forge-session.py doctor [--specs-dir DIR] [--config FILE] [--json]
+    python3 forge-session.py discover-feature NAME [--specs-dir DIR] [--json]
+    python3 forge-session.py stage-exit --feature F --stage S [--specs-dir DIR] \
+        [--config FILE] [--epic E] [--next-feature N] [--host claude|generic] [--json]
 
 `rank-features` scans the specs tree for feature-shaped directories (those that
 directly contain a `.pipeline-state.json`, in both the flat
@@ -24,6 +28,30 @@ and degrades gracefully: when no transcript or usage is found (a non-Claude host
 or a fresh session) it reports `{"available": false}` and still exits 0, so the
 caller simply omits the context advice.
 
+`doctor` captures pipeline ground truth in one shot for debugging a confused
+session or a broken install: the plugin root the sibling `forge-root.sh`
+actually resolves (plus its version and commit), the current git branch vs.
+each feature's recorded state branch, the recency-ranked feature summary, and
+whether each feature's composed backlog path exists on disk. Every probe is
+best-effort — a failure is reported as data, never as a crash — and the
+command always exits 0 so it can run in any half-broken environment.
+
+`discover-feature` looks for a feature's `.pipeline-state.json` across ALL
+git branches (local heads and remote-tracking refs), so a session on the
+default branch can learn that a pipeline exists on a topic branch instead of
+concluding it was never started. When nothing is found locally it also asks
+`git ls-remote --heads origin` about branches a single-branch clone never
+fetched, and emits the exact `git fetch`/`git switch` commands a caller could
+run. It is strictly read-only — it never checks anything out itself — and
+like `doctor` it always exits 0 and degrades to data.
+
+`stage-exit` computes everything an authoring stage's closing used to derive
+in prose (the Scripted Stage Exit, `references/stage-exit-protocol.md`):
+the DIRECTIVES (whether the in-stage auto-verify runs, which verify gate to
+present, autoFix eligibility, the verify and next-stage commands) plus the
+exact sentinel-terminated NEXT-STEPS block the skill must print verbatim as
+its absolute last output. Deterministic and read-only; always exits 0.
+
 3.10 baseline, Google-style docstrings, full type annotations, stdlib only —
 matching the conventions of `scripts/epic-manifest.py`.
 
@@ -36,8 +64,9 @@ from __future__ import annotations
 
 import argparse
 import json
+import subprocess
 import sys
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Final, TypedDict
 
@@ -102,6 +131,10 @@ class FeatureRow(TypedDict):
     nextCommand: str | None
     verifyPending: bool
     verifyCommand: str | None
+    verifyStage: str | None
+    verifyState: str
+    autoVerify: bool
+    autoFix: bool
 
 
 class UsageError(Exception):
@@ -181,13 +214,52 @@ def next_stage(state: dict) -> str | None:
     return None
 
 
-def pending_verify(state: dict) -> str | None:
-    """Return the production stage whose verify is outstanding, if any.
+def _stage_version(state: dict, stage: str) -> int | None:
+    """Return the recorded ``version`` of a stage entry, or None if absent."""
+    stages = state.get("stages")
+    if not isinstance(stages, dict):
+        return None
+    entry = stages.get(stage)
+    if not isinstance(entry, dict):
+        return None
+    version = entry.get("version")
+    return version if isinstance(version, int) else None
 
-    The most recently completed production stage whose corresponding
-    ``forge-verify-*`` is neither resolved (passed/findings-applied/skipped) nor
-    already run. Surfaced so the navigator can offer "verify before continuing"
-    as an alternative to advancing. Returns ``None`` when nothing needs verify.
+
+def _verify_entry(state: dict, verify_key: str) -> dict:
+    """Return the ``forge-verify-*`` entry dict, or ``{}`` if absent."""
+    stages = state.get("stages")
+    if not isinstance(stages, dict):
+        return {}
+    entry = stages.get(verify_key)
+    return entry if isinstance(entry, dict) else {}
+
+
+def verify_state(state: dict) -> tuple[str | None, str]:
+    """Classify verify freshness for the most-recently-completed stage.
+
+    Returns ``(stage, state_label)`` where ``state_label`` is one of:
+
+    - ``fresh``   — verify is resolved AND its ``verifiedStageVersion`` matches the
+      stage's current ``version`` (so no re-verify is needed).
+    - ``stale``   — verify was resolved once, but the stage version has since moved
+      (artifact revised) OR the entry predates the freshness ledger (no
+      ``verifiedStageVersion``). A revised artifact must be re-verified.
+    - ``failing`` — verify ran and reported findings that are not yet applied
+      (``findings-reported``).
+    - ``never``   — the stage completed but verify has not run at all.
+    - ``skipped`` — the user explicitly chose to proceed without verifying. A
+      resolved, non-pending state: it is deliberately NOT re-offered or
+      auto-verified, and (unlike a genuine verification result) it does not go
+      stale on an artifact revision — skip writers record no version to compare
+      against, and re-surfacing would override an explicit human decision.
+    - ``none``    — no completed verify-capable stage (nothing to verify), stage
+      is ``None``.
+
+    Only the most-recent completed production stage is considered, matching the
+    navigator's "verify before continuing" gate. Absent ``verifiedStageVersion``
+    on a ``passed``/``findings-applied`` entry (legacy state) is deliberately
+    treated as ``stale`` — verify rather than skip.
     """
     for stage in reversed(PRODUCTION_STAGES):
         if _stage_status(state, stage) != _DONE_STATUS:
@@ -195,11 +267,41 @@ def pending_verify(state: dict) -> str | None:
         token = VERIFY_TOKEN_BY_STAGE.get(stage)
         if token is None:
             continue  # forge-6-docs has no verify step
-        verify_status = _stage_status(state, f"forge-verify-{token}")
-        if verify_status not in _VERIFY_RESOLVED:
-            return stage
-        return None  # most-recent complete stage is already verified
-    return None
+        entry = _verify_entry(state, f"forge-verify-{token}")
+        status = entry.get("status")
+        if status == "skipped":
+            # An explicit skip is resolved and non-pending — preserve the user's
+            # decision. It never goes stale (no recorded version to compare), so
+            # the freshness check below deliberately does not apply.
+            return stage, "skipped"
+        if status not in _VERIFY_RESOLVED:
+            if status == "findings-reported":
+                return stage, "failing"
+            return stage, "never"
+        verified_version = entry.get("verifiedStageVersion")
+        stage_version = _stage_version(state, stage)
+        if (
+            isinstance(verified_version, int)
+            and stage_version is not None
+            and verified_version == stage_version
+        ):
+            return stage, "fresh"
+        return stage, "stale"
+    return None, "none"
+
+
+def pending_verify(state: dict) -> str | None:
+    """Return the production stage whose verify is outstanding, if any.
+
+    Outstanding means the most-recently-completed production stage's verify is not
+    ``fresh`` (never run, reported findings, or gone stale after an artifact
+    revision). An explicit ``skipped`` is treated as resolved (never outstanding).
+    Surfaced so the navigator can offer "verify before continuing" as an
+    alternative to advancing. Returns ``None`` when the latest stage is fresh,
+    skipped, or there is nothing to verify.
+    """
+    stage, label = verify_state(state)
+    return stage if label not in ("fresh", "none", "skipped") else None
 
 
 def _parse_ts(value: str | None) -> datetime | None:
@@ -207,25 +309,37 @@ def _parse_ts(value: str | None) -> datetime | None:
     if not isinstance(value, str):
         return None
     try:
-        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+        dt = datetime.fromisoformat(value.replace("Z", "+00:00"))
     except ValueError:
         return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt
 
 
-def build_rows(specs_dir: Path) -> list[FeatureRow]:
+def build_rows(specs_dir: Path, config: dict | None = None) -> list[FeatureRow]:
     """Build the recency-ranked active-feature rows (the rank-features payload).
 
     Active features (``pipelineStatus == "active"``, the default when absent) are
     sorted by ``updatedAt`` descending — most recently touched first — so the
     navigator's recency default is row 0.
+
+    ``config`` is the loaded forge.config.json (or ``{}``); it drives the effective
+    ``autoVerify``/``autoFix`` per stage so the navigator can branch without
+    re-reading config.
     """
+    config = config or {}
+    # Fail closed: only a literal JSON ``true`` enables artifact-mutating autoFix.
+    global_auto_fix = config.get("autoFix") is True
     rows: list[FeatureRow] = []
     for name, epic, state in _scan_features(specs_dir):
         status = state.get("pipelineStatus", "active")
         if status != "active":
             continue
         nxt = next_stage(state)
-        verify_stage = pending_verify(state)
+        vstage, vlabel = verify_state(state)
+        verify_pending = vstage is not None and vlabel not in ("fresh", "none", "skipped")
+        effective_auto_verify = auto_verify_for(config, vstage) if vstage else False
         branch = state.get("branch")
         updated = state.get("updatedAt")
         rows.append({
@@ -237,12 +351,16 @@ def build_rows(specs_dir: Path) -> list[FeatureRow]:
             "complete": nxt is None,
             "nextStage": nxt,
             "nextCommand": f"/feature-forge:{nxt} {name}" if nxt else None,
-            "verifyPending": verify_stage is not None,
-            "verifyCommand": f"/feature-forge:forge-verify {name}" if verify_stage else None,
+            "verifyPending": verify_pending,
+            "verifyCommand": f"/feature-forge:forge-verify {name}" if verify_pending else None,
+            "verifyStage": vstage,
+            "verifyState": vlabel,
+            "autoVerify": effective_auto_verify,
+            "autoFix": global_auto_fix and effective_auto_verify,
         })
     # Sort by updatedAt desc; rows without a parseable timestamp sort last.
     rows.sort(
-        key=lambda r: (_parse_ts(r["updatedAt"]) or datetime.min.replace(tzinfo=None)),
+        key=lambda r: (_parse_ts(r["updatedAt"]) or datetime.min.replace(tzinfo=timezone.utc)),
         reverse=True,
     )
     return rows
@@ -308,12 +426,17 @@ def _last_usage(transcript: Path) -> tuple[int, str | None] | None:
         usage = message.get("usage") if isinstance(message, dict) else record.get("usage")
         if not isinstance(usage, dict):
             continue
-        total = (
-            int(usage.get("input_tokens", 0) or 0)
-            + int(usage.get("cache_creation_input_tokens", 0) or 0)
-            + int(usage.get("cache_read_input_tokens", 0) or 0)
-            + int(usage.get("output_tokens", 0) or 0)
-        )
+        # A malformed transcript may carry a non-numeric usage field; skip that
+        # record rather than crash the whole context-usage read (ValueError/TypeError).
+        try:
+            total = (
+                int(usage.get("input_tokens", 0) or 0)
+                + int(usage.get("cache_creation_input_tokens", 0) or 0)
+                + int(usage.get("cache_read_input_tokens", 0) or 0)
+                + int(usage.get("output_tokens", 0) or 0)
+            )
+        except (TypeError, ValueError):
+            continue
         if total <= 0:
             continue
         model = message.get("model") if isinstance(message, dict) else record.get("model")
@@ -328,13 +451,53 @@ def _infer_window(model: str | None) -> int:
     return _DEFAULT_WINDOW
 
 
-def _config_value(config_path: Path, key: str):
-    """Read a single key from forge.config.json, or None if absent/unreadable."""
+def _load_config(config_path: Path) -> dict:
+    """Read forge.config.json into a dict, tolerating missing/corrupt files.
+
+    A missing, unreadable, or non-object config downgrades to ``{}`` so callers
+    read every key through absent-safe ``.get`` defaults.
+    """
     try:
         config = json.loads(config_path.read_text(encoding="utf-8"))
     except (OSError, json.JSONDecodeError):
-        return None
-    return config.get(key) if isinstance(config, dict) else None
+        return {}
+    return config if isinstance(config, dict) else {}
+
+
+def _config_value(config_path: Path, key: str):
+    """Read a single key from forge.config.json, or None if absent/unreadable."""
+    return _load_config(config_path).get(key)
+
+
+def auto_verify_for(config: dict, stage: str) -> bool:
+    """Return the effective auto-verify setting for ``stage``.
+
+    Per-stage override in ``autoVerifyStages`` wins over the global ``autoVerify``;
+    both default to off, so a config with neither key means "no auto-verify".
+
+    Parsing is strict and **fails closed**: only a literal JSON ``true`` enables
+    auto-verify. A non-boolean value (e.g. the string ``"false"``, which is truthy
+    in Python) is treated as off, not on. The schema already rejects non-booleans
+    at author time; this guards a hand-edited config from silently enabling
+    automation.
+    """
+    stages = config.get("autoVerifyStages")
+    if isinstance(stages, dict) and stage in stages:
+        return stages[stage] is True
+    return config.get("autoVerify") is True
+
+
+def invalid_auto_verify_keys(config: dict) -> list[str]:
+    """Return ``autoVerifyStages`` keys outside the verify-capable stage ids.
+
+    An unknown/typo key (e.g. ``forge-1-prod``) would silently never take effect,
+    turning an intended off-switch into a no-op. Surfacing it lets the navigator
+    warn instead of failing quietly. Mirrors the schema's ``propertyNames.enum``.
+    """
+    stages = config.get("autoVerifyStages")
+    if not isinstance(stages, dict):
+        return []
+    return [key for key in stages if key not in VERIFY_TOKEN_BY_STAGE]
 
 
 def context_usage(
@@ -407,6 +570,607 @@ def context_usage(
     }
 
 
+# --------------------------------------------------------------------------- #
+# Doctor
+# --------------------------------------------------------------------------- #
+
+
+def _git_output(args: list[str]) -> str | None:
+    """Run a read-only git command and return stripped stdout, or None.
+
+    Any failure (git missing, not a repo, nonzero exit, timeout) degrades to
+    ``None`` — doctor reports absence rather than crashing.
+    """
+    try:
+        proc = subprocess.run(
+            ["git", *args], capture_output=True, text=True, timeout=10,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if proc.returncode != 0:
+        return None
+    out = proc.stdout.strip()
+    return out or None
+
+
+def _resolve_plugin_root() -> dict:
+    """Resolve the plugin root by running the sibling ``forge-root.sh``.
+
+    Uses the resolver that ships next to this script, so the answer reflects
+    the install this helper actually belongs to — exactly what a skill's
+    bootstrap prelude would find (or fail to find). On success the dict also
+    carries the root's ``version`` (from ``.claude-plugin/plugin.json`` or the
+    neutral ``.feature-forge-bundle.json``) and, when the root is a git
+    checkout, its short ``commit`` — enough to spot version skew between the
+    resolved root and the skills a session loaded.
+    """
+    resolver = Path(__file__).resolve().parent / "forge-root.sh"
+    if not resolver.is_file():
+        return {"resolved": False, "error": f"resolver not found: {resolver}"}
+    try:
+        proc = subprocess.run(
+            ["bash", str(resolver)], capture_output=True, text=True, timeout=10,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return {"resolved": False, "error": str(exc)}
+    if proc.returncode != 0:
+        return {
+            "resolved": False,
+            "error": proc.stderr.strip() or f"resolver exited {proc.returncode}",
+        }
+    root = proc.stdout.strip()
+    info: dict = {"resolved": True, "root": root}
+    for rel in (".claude-plugin/plugin.json", ".feature-forge-bundle.json"):
+        manifest = Path(root) / rel
+        if manifest.is_file():
+            version = _load_config(manifest).get("version")
+            if isinstance(version, str):
+                info["version"] = version
+            info["manifest"] = rel
+            break
+    commit = _git_output(["-C", root, "rev-parse", "--short", "HEAD"])
+    if commit:
+        info["commit"] = commit
+    return info
+
+
+def _backlog_path(config: dict, name: str, epic: str | None, specs_dir: Path) -> Path:
+    """Compose a feature's backlog.json path per the forge-4-backlog rule.
+
+    ``{backlogDir}/{feature}/backlog.json`` when ``backlogDir`` is configured,
+    else ``{resolvedFeatureDir}/backlog.json`` (flat or nested under the epic).
+    """
+    backlog_dir = config.get("backlogDir")
+    if isinstance(backlog_dir, str) and backlog_dir:
+        return Path(backlog_dir) / name / "backlog.json"
+    feature_dir = specs_dir / epic / name if epic else specs_dir / name
+    return feature_dir / "backlog.json"
+
+
+def doctor_report(specs_dir: Path, config_path: Path) -> dict:
+    """Assemble the ground-truth diagnostic payload (always succeeds).
+
+    One snapshot of everything a confused session needs checked: resolved
+    plugin root + version/commit, current git branch vs. each feature's
+    recorded state branch, the recency-ranked feature summary, and whether
+    each feature's composed backlog path exists on disk.
+    """
+    config = _load_config(config_path)
+    # --show-current (not rev-parse HEAD) so an unborn branch (fresh repo,
+    # no commits yet) still reports its name instead of failing.
+    current_branch = _git_output(["branch", "--show-current"])
+    rows = build_rows(specs_dir, config)
+    features = []
+    for row in rows:
+        backlog = _backlog_path(config, row["name"], row["epic"], specs_dir)
+        state_branch = row["branch"]
+        features.append({
+            "name": row["name"],
+            "epic": row["epic"],
+            "currentStage": row["currentStage"],
+            "nextStage": row["nextStage"],
+            "verifyState": row["verifyState"],
+            "stateBranch": state_branch,
+            "branchMatchesState": (
+                state_branch == current_branch
+                if state_branch and current_branch
+                else None
+            ),
+            "backlogPath": str(backlog),
+            "backlogExists": backlog.is_file(),
+        })
+    return {
+        "pluginRoot": _resolve_plugin_root(),
+        "currentBranch": current_branch,
+        "specsDir": str(specs_dir),
+        "specsDirExists": specs_dir.is_dir(),
+        "configPath": str(config_path),
+        "configExists": config_path.is_file(),
+        "counts": _counts(specs_dir),
+        "features": features,
+        "invalidAutoVerifyKeys": invalid_auto_verify_keys(config),
+    }
+
+
+def _print_doctor(report: dict) -> None:
+    """Print the human-readable doctor report."""
+    root = report["pluginRoot"]
+    if root.get("resolved"):
+        detail = " ".join(
+            f"{key}={root[key]}" for key in ("version", "commit") if key in root
+        )
+        print(f"plugin root: {root['root']}" + (f"  ({detail})" if detail else ""))
+    else:
+        print(f"plugin root: UNRESOLVED — {root.get('error', 'unknown')}")
+    print(f"current branch: {report['currentBranch'] or '(not a git repo)'}")
+    print(
+        f"specs dir: {report['specsDir']}"
+        + ("" if report["specsDirExists"] else "  (MISSING)")
+    )
+    print(
+        f"config: {report['configPath']}"
+        + ("" if report["configExists"] else "  (MISSING)")
+    )
+    counts = report["counts"]
+    print(
+        f"features: {counts['active']} active "
+        f"(paused: {counts['paused']}, abandoned: {counts['abandoned']})"
+    )
+    for feat in report["features"]:
+        label = feat["name"] + (f" [{feat['epic']}]" if feat["epic"] else "")
+        branch = feat["stateBranch"] or "?"
+        if feat["branchMatchesState"] is False:
+            branch += " (MISMATCH vs current)"
+        backlog = "exists" if feat["backlogExists"] else "MISSING"
+        print(
+            f"  - {label}: stage={feat['currentStage']} "
+            f"verify={feat['verifyState']} branch={branch} "
+            f"backlog={backlog} ({feat['backlogPath']})"
+        )
+    invalid = report.get("invalidAutoVerifyKeys") or []
+    if invalid:
+        print("  ! invalid autoVerifyStages keys (ignored): " + ", ".join(invalid))
+
+
+# --------------------------------------------------------------------------- #
+# Cross-branch feature discovery
+# --------------------------------------------------------------------------- #
+
+
+def _specs_rel(specs_dir: str) -> str:
+    """Normalize a specs dir to the repo-relative POSIX form git ls-tree uses."""
+    rel = specs_dir.replace("\\", "/")
+    while rel.startswith("./"):
+        rel = rel[2:]
+    return rel.rstrip("/")
+
+
+def _state_paths_in_ref(ref: str, specs_rel: str, name: str) -> list[str]:
+    """Feature-shaped ``.pipeline-state.json`` paths for ``name`` in one ref.
+
+    Mirrors the ``_scan_features`` flat/nested bound: exactly
+    ``{specsDir}/{name}/.pipeline-state.json`` or
+    ``{specsDir}/{epic}/{name}/.pipeline-state.json`` — never deeper.
+    """
+    listing = _git_output(["ls-tree", "-r", "--name-only", ref, "--", specs_rel])
+    if not listing:
+        return []
+    hits: list[str] = []
+    prefix = specs_rel + "/"
+    for path in listing.splitlines():
+        if not path.startswith(prefix) or not path.endswith("/" + PIPELINE_STATE_FILENAME):
+            continue
+        segments = path[len(prefix):].split("/")
+        # [name, state-file] (flat) or [epic, name, state-file] (nested).
+        if len(segments) == 2 and segments[0] == name:
+            hits.append(path)
+        elif len(segments) == 3 and segments[1] == name:
+            hits.append(path)
+    return hits
+
+
+def _read_state_at_ref(ref: str, path: str) -> dict:
+    """Parse ``git show ref:path`` as pipeline state, downgrading failures to {}."""
+    raw = _git_output(["show", f"{ref}:{path}"])
+    if raw is None:
+        return {}
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError:
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _list_refs(pattern: str) -> list[tuple[str, str]]:
+    """Return ``(short_ref, committer_date)`` pairs under a ref namespace."""
+    raw = _git_output([
+        "for-each-ref",
+        "--format=%(refname:short)\t%(committerdate:iso-strict)",
+        pattern,
+    ])
+    if not raw:
+        return []
+    out: list[tuple[str, str]] = []
+    for line in raw.splitlines():
+        ref, _, date = line.partition("\t")
+        if ref:
+            out.append((ref, date))
+    return out
+
+
+def discover_feature(name: str, specs_dir: str) -> dict:
+    """Find a feature's pipeline state across all branches (strictly read-only).
+
+    Scans every local head and remote-tracking ref for a feature-shaped
+    ``.pipeline-state.json``, parses each hit via ``git show``, and ranks
+    candidates by (state's own ``branch`` field matches the ref) first, then
+    local-before-remote-tracking, then newest commit. When no candidate exists
+    locally, ``git ls-remote --heads origin`` surfaces plausibly-named
+    branches a single-branch clone never fetched, as ``needsFetch`` entries
+    with the exact fetch/switch commands.
+
+    Never mutates anything: checkout is the caller's decision (and requires
+    the user's explicit accept plus a clean tree — see shared-conventions).
+    """
+    if _git_output(["rev-parse", "--git-dir"]) is None:
+        return {
+            "feature": name,
+            "gitRepo": False,
+            "currentBranch": None,
+            "candidates": [],
+            "remoteCandidates": [],
+        }
+    current_branch = _git_output(["branch", "--show-current"])
+    specs_rel = _specs_rel(specs_dir)
+
+    refs = [(ref, date, False) for ref, date in _list_refs("refs/heads")]
+    refs += [(ref, date, True) for ref, date in _list_refs("refs/remotes")]
+
+    candidates: list[dict] = []
+    matched_branches: set[str] = set()
+    known_branches: set[str] = set()
+    for ref, commit_date, is_remote in refs:
+        branch = ref.split("/", 1)[1] if is_remote else ref
+        if is_remote and (not branch or branch == "HEAD"):
+            continue
+        known_branches.add(branch)
+        if branch in matched_branches:
+            continue  # the local head already yielded this branch's state
+        for path in _state_paths_in_ref(ref, specs_rel, name):
+            state = _read_state_at_ref(ref, path)
+            state_branch = state.get("branch")
+            state_branch = state_branch if isinstance(state_branch, str) else None
+            updated = state.get("updatedAt")
+            matched_branches.add(branch)
+            candidates.append({
+                "branch": branch,
+                "ref": ref,
+                "remoteTracking": is_remote,
+                "path": path,
+                "stateBranch": state_branch,
+                "stateBranchMatches": state_branch == branch,
+                "currentStage": state.get("currentStage"),
+                "pipelineStatus": state.get("pipelineStatus", "active"),
+                "updatedAt": updated if isinstance(updated, str) else None,
+                "commitDate": commit_date or None,
+                "isCurrentBranch": branch == current_branch,
+                "switchCommand": f"git switch {branch}",
+            })
+
+    def _rank(cand: dict) -> tuple:
+        ts = _parse_ts(cand["commitDate"]) or datetime.min.replace(tzinfo=timezone.utc)
+        return (
+            not cand["stateBranchMatches"],
+            cand["remoteTracking"],
+            -ts.timestamp(),
+        )
+
+    candidates.sort(key=_rank)
+
+    # Single-branch clones: the branch holding the state may never have been
+    # fetched. Only when nothing was found locally, ask the remote for heads we
+    # do not know and surface the plausibly-named ones (the feature name appears
+    # in the branch name — e.g. forge/<feature>). These are name-based hints
+    # only; their contents were NOT inspected.
+    remote_candidates: list[dict] = []
+    if not candidates:
+        ls_remote = _git_output(["ls-remote", "--heads", "origin"])
+        for line in (ls_remote or "").splitlines():
+            _, _, refname = line.partition("\t")
+            if not refname.startswith("refs/heads/"):
+                continue
+            branch = refname[len("refs/heads/"):]
+            if branch in known_branches or name not in branch:
+                continue
+            remote_candidates.append({
+                "branch": branch,
+                "needsFetch": True,
+                "fetchCommand": f"git fetch origin {branch}:refs/remotes/origin/{branch}",
+                "switchCommand": f"git switch {branch}",
+            })
+
+    return {
+        "feature": name,
+        "gitRepo": True,
+        "currentBranch": current_branch,
+        "specsDir": specs_rel,
+        "candidates": candidates,
+        "remoteCandidates": remote_candidates,
+    }
+
+
+def _print_discover(payload: dict) -> None:
+    """Print the human-readable discovery report."""
+    name = payload["feature"]
+    if not payload["gitRepo"]:
+        print(f"discover-feature {name}: not a git repository — nothing to scan")
+        return
+    candidates = payload["candidates"]
+    remote = payload["remoteCandidates"]
+    if not candidates and not remote:
+        print(
+            f"discover-feature {name}: no pipeline state found on any local or "
+            "remote-tracking branch"
+        )
+        return
+    for cand in candidates:
+        marks = []
+        if cand["isCurrentBranch"]:
+            marks.append("current branch")
+        if cand["remoteTracking"]:
+            marks.append("remote-tracking")
+        if not cand["stateBranchMatches"] and cand["stateBranch"]:
+            marks.append(f"state records branch {cand['stateBranch']}")
+        suffix = f"  ({'; '.join(marks)})" if marks else ""
+        print(
+            f"  {cand['branch']}: stage={cand['currentStage'] or '?'} "
+            f"status={cand['pipelineStatus']} path={cand['path']}{suffix}"
+        )
+        if not cand["isCurrentBranch"]:
+            print(f"      switch: {cand['switchCommand']}")
+    for cand in remote:
+        print(
+            f"  {cand['branch']}: on origin only (never fetched; contents not "
+            "inspected — name matches)"
+        )
+        print(f"      fetch:  {cand['fetchCommand']}")
+        print(f"      switch: {cand['switchCommand']}")
+
+
+# --------------------------------------------------------------------------- #
+# Scripted Stage Exit
+# --------------------------------------------------------------------------- #
+
+#: Authoring stages whose closing runs stage-exit (the loop keeps bespoke exits).
+EXIT_STAGES: Final[tuple[str, ...]] = (
+    "forge-0-epic",
+    "forge-1-prd",
+    "forge-2-tech",
+    "forge-3-specs",
+    "forge-4-backlog",
+)
+
+#: Stage id -> the noun phrase gate wording uses (the old {stage} stamp slot).
+STAGE_NOUN: Final[dict[str, str]] = {
+    "forge-0-epic": "the epic decomposition",
+    "forge-1-prd": "the PRD",
+    "forge-2-tech": "the tech spec",
+    "forge-3-specs": "the implementation specs",
+    "forge-4-backlog": "the backlog",
+}
+
+#: Verify token per exit stage. Extends the production map with the epic stage,
+#: whose verify entry is recorded under ``forge-verify-epic``.
+_EXIT_VERIFY_TOKEN: Final[dict[str, str]] = {
+    **VERIFY_TOKEN_BY_STAGE,
+    "forge-0-epic": "epic",
+}
+
+#: The stage each exit hands off to when pipeline state cannot say better.
+_EXIT_NEXT_STAGE: Final[dict[str, str]] = {
+    "forge-0-epic": "forge-1-prd",
+    "forge-1-prd": "forge-2-tech",
+    "forge-2-tech": "forge-3-specs",
+    "forge-3-specs": "forge-4-backlog",
+    "forge-4-backlog": "forge-5-loop",
+}
+
+#: 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 ─"
+
+
+def _verify_state_for(state: dict, stage: str) -> str:
+    """Classify THIS stage's verify freshness (stage-scoped ``verify_state``).
+
+    Same labels as ``verify_state`` — fresh / stale / failing / never /
+    skipped / none — but for the given stage rather than the most-recently
+    completed one, because stage-exit runs inside the stage that just closed.
+    """
+    token = _EXIT_VERIFY_TOKEN.get(stage)
+    if token is None:
+        return "none"
+    entry = _verify_entry(state, f"forge-verify-{token}")
+    status = entry.get("status")
+    if status == "skipped":
+        return "skipped"
+    if status == "findings-reported":
+        return "failing"
+    if status not in _VERIFY_RESOLVED:
+        return "never"
+    verified_version = entry.get("verifiedStageVersion")
+    stage_version = _stage_version(state, stage)
+    if (
+        isinstance(verified_version, int)
+        and stage_version is not None
+        and verified_version == stage_version
+    ):
+        return "fresh"
+    return "stale"
+
+
+def _resolve_feature_dir(specs_dir: Path, feature: str, epic: str | None) -> Path:
+    """Best-effort feature dir (flat, else unique nested, else flat literal).
+
+    stage-exit tolerates an unresolvable dir — the state read downgrades to
+    ``{}`` and every directive still computes from defaults.
+    """
+    if epic:
+        return specs_dir / epic / feature
+    flat = specs_dir / feature
+    if (flat / PIPELINE_STATE_FILENAME).is_file():
+        return flat
+    if specs_dir.is_dir():
+        nested = [
+            p for p in specs_dir.glob(f"*/{feature}")
+            if (p / PIPELINE_STATE_FILENAME).is_file()
+        ]
+        if len(nested) == 1:
+            return nested[0]
+    return flat
+
+
+def _next_steps_block(next_command: str, host: str) -> str:
+    """Render the sentinel-terminated NEXT-STEPS block for the given host.
+
+    The Claude wording uses the literal ``/clear`` slash-command; the generic
+    wording is host-neutral (matching the adapter build's host-term table, so
+    a non-Claude bundle invoking ``--host generic`` never instructs a fake
+    slash-command).
+    """
+    if host == "claude":
+        clear_line = (
+            "1. `/clear` — recommended unconditionally at this stage boundary; "
+            "every artifact is on disk, so the work survives the clear. "
+            "I can't `/clear` for you — you have to run it yourself."
+        )
+        next_line = (
+            f"2. Then run `{next_command}` in the fresh session — or re-run "
+            "`/feature-forge:forge` to let the navigator resume from disk."
+        )
+    else:
+        clear_line = (
+            "1. Clear your session / start a fresh session — recommended "
+            "unconditionally at this stage boundary; every artifact is on "
+            "disk, so the work survives it."
+        )
+        next_line = (
+            f"2. Then run `{next_command}` in the fresh session — or re-run "
+            "the forge navigator skill to resume from disk."
+        )
+    return "\n".join(["**Next steps**", clear_line, next_line, NEXT_STEPS_SENTINEL])
+
+
+def stage_exit(
+    feature: str,
+    stage: str,
+    specs_dir: Path,
+    config_path: Path,
+    epic: str | None,
+    host: str,
+    next_feature: str | None,
+) -> dict:
+    """Compute the Scripted Stage Exit payload: DIRECTIVES + NEXT-STEPS block.
+
+    Directive semantics (the contract in ``references/stage-exit-protocol.md``):
+
+    - ``runInStageVerify`` — the effective auto-verify (per-stage override,
+      else global; strict-true) is on AND this stage's verify is not already
+      resolved (fresh/skipped). The skill then dispatches the clean-room
+      verify in-session (principle #2: verify before the clear).
+    - ``autoFixEligible`` — ``autoFix`` is strict-true AND the in-stage verify
+      runs AND the working tree is clean. Findings-level preconditions (zero
+      unresolved decisions) remain the skill's runtime check.
+    - ``verifyGate`` — ``none`` when verify is resolved or the in-stage run
+      covers it; ``standard`` when auto-verify is off and verification is
+      outstanding on a host with a question mechanism + clean-room path
+      (``--host claude``); ``manual-print`` for the same state on a generic
+      host (print ``verifyCommand`` instead of presenting the gate).
+    - ``nextStage``/``nextCommand`` — from pipeline state when it already
+      records this stage complete (first non-complete production stage), else
+      the fixed successor. ``--next-feature`` names the first actionable
+      feature for the epic handoff; without it the runtime placeholder
+      ``{first-actionable-feature}`` passes through for the skill to resolve.
+
+    Read-only, deterministic, exit 0 — errors degrade to defaults, never
+    crash a stage closing.
+    """
+    config = _load_config(config_path)
+    feature_dir = _resolve_feature_dir(specs_dir, feature, epic)
+    state = _read_state(feature_dir / PIPELINE_STATE_FILENAME)
+
+    git_repo = _git_output(["rev-parse", "--git-dir"]) is not None
+    clean_tree: bool | None = None
+    if git_repo:
+        porcelain = _git_output(["status", "--porcelain"])
+        clean_tree = porcelain is None or porcelain == ""
+
+    verify_label = _verify_state_for(state, stage)
+    resolved = verify_label in ("fresh", "skipped")
+    effective_auto_verify = auto_verify_for(config, stage)
+    run_in_stage = effective_auto_verify and not resolved
+    auto_fix_eligible = (
+        config.get("autoFix") is True and run_in_stage and clean_tree is True
+    )
+    if resolved or effective_auto_verify:
+        verify_gate = "none"
+    elif host == "claude":
+        verify_gate = "standard"
+    else:
+        verify_gate = "manual-print"
+
+    next_stage_id = _EXIT_NEXT_STAGE.get(stage)
+    state_next = next_stage(state)
+    if (
+        stage in PRODUCTION_STAGES
+        and state_next is not None
+        and PRODUCTION_STAGES.index(state_next) > PRODUCTION_STAGES.index(stage)
+    ):
+        # State records this stage complete AND its walk lands beyond it —
+        # trust it (it skips stages already completed out of order). A missing
+        # or behind-the-stage walk (state not yet flushed, corrupt file) falls
+        # back to the fixed successor, never to an earlier stage.
+        next_stage_id = state_next
+    next_arg = next_feature or (
+        "{first-actionable-feature}" if stage == "forge-0-epic" else feature
+    )
+    next_command = f"/feature-forge:{next_stage_id} {next_arg}" if next_stage_id else None
+
+    directives = {
+        "stage": stage,
+        "stageNoun": STAGE_NOUN.get(stage, stage),
+        "feature": feature,
+        "runInStageVerify": run_in_stage,
+        "verifyGate": verify_gate,
+        "autoFixEligible": auto_fix_eligible,
+        "verifyState": verify_label,
+        "verifyCommand": f"/feature-forge:forge-verify {feature}",
+        "autoVerifyEffective": effective_auto_verify,
+        "nextStage": next_stage_id,
+        "nextCommand": next_command,
+        "invalidAutoVerifyKeys": invalid_auto_verify_keys(config),
+        "gitRepo": git_repo,
+        "cleanTree": clean_tree,
+        "host": host,
+    }
+    return {
+        "directives": directives,
+        "nextSteps": _next_steps_block(next_command or "/feature-forge:forge", host),
+        "sentinel": NEXT_STEPS_SENTINEL,
+    }
+
+
+def _print_stage_exit(payload: dict) -> None:
+    """Print DIRECTIVES then the NEXT-STEPS block (the skill-facing form)."""
+    print("DIRECTIVES:")
+    print(json.dumps(payload["directives"], indent=2, ensure_ascii=False))
+    print(
+        "NEXT-STEPS (print this block verbatim as your absolute last output — "
+        "nothing after the sentinel):"
+    )
+    print(payload["nextSteps"])
+
+
 # --------------------------------------------------------------------------- #
 # CLI dispatch
 # --------------------------------------------------------------------------- #
@@ -449,6 +1213,7 @@ def main() -> int:
 
     p_rank = sub.add_parser("rank-features", help="Rank active features by recency")
     p_rank.add_argument("--specs-dir", default="./specs", help="Specs directory")
+    p_rank.add_argument("--config", default="./forge.config.json", help="forge.config.json path")
     p_rank.add_argument("--json", action="store_true", dest="json_output")
 
     p_ctx = sub.add_parser("context-usage", help="Report live context-window usage")
@@ -457,17 +1222,55 @@ def main() -> int:
     p_ctx.add_argument("--threshold", type=float, default=None, help="Override warn fraction (0-1)")
     p_ctx.add_argument("--json", action="store_true", dest="json_output")
 
+    p_doc = sub.add_parser("doctor", help="Capture pipeline ground truth for debugging")
+    p_doc.add_argument("--specs-dir", default="./specs", help="Specs directory")
+    p_doc.add_argument("--config", default="./forge.config.json", help="forge.config.json path")
+    p_doc.add_argument("--json", action="store_true", dest="json_output")
+
+    p_disc = sub.add_parser(
+        "discover-feature", help="Find a feature's pipeline state across all branches"
+    )
+    p_disc.add_argument("name", help="Feature name to discover")
+    p_disc.add_argument("--specs-dir", default="./specs", help="Specs directory")
+    p_disc.add_argument("--json", action="store_true", dest="json_output")
+
+    p_exit = sub.add_parser(
+        "stage-exit", help="Emit the Scripted Stage Exit directives + NEXT-STEPS block"
+    )
+    p_exit.add_argument("--feature", required=True,
+                        help="Feature name (the epic name for forge-0-epic)")
+    p_exit.add_argument("--stage", required=True, choices=EXIT_STAGES,
+                        help="The just-completed authoring stage")
+    p_exit.add_argument("--specs-dir", default="./specs", help="Specs directory")
+    p_exit.add_argument("--config", default="./forge.config.json", help="forge.config.json path")
+    p_exit.add_argument("--epic", default=None, help="Epic name for a nested member")
+    p_exit.add_argument("--next-feature", default=None, dest="next_feature",
+                        help="First actionable feature (epic handoff next-command arg)")
+    p_exit.add_argument("--host", default="claude", choices=("claude", "generic"),
+                        help="Host wording for the NEXT-STEPS block")
+    p_exit.add_argument("--json", action="store_true", dest="json_output")
+
     args = parser.parse_args()
 
     try:
         if args.cmd == "rank-features":
             specs_dir = Path(args.specs_dir)
-            rows = build_rows(specs_dir)
+            config = _load_config(Path(args.config))
+            rows = build_rows(specs_dir, config)
             counts = _counts(specs_dir)
+            invalid_keys = invalid_auto_verify_keys(config)
             if args.json_output:
-                print(json.dumps({"active": rows, "counts": counts}, indent=2, ensure_ascii=False))
+                payload = {"active": rows, "counts": counts}
+                if invalid_keys:
+                    payload["invalidAutoVerifyKeys"] = invalid_keys
+                print(json.dumps(payload, indent=2, ensure_ascii=False))
             else:
                 _print_rank_table(rows, counts)
+                if invalid_keys:
+                    print(
+                        "  ! invalid autoVerifyStages keys (ignored): "
+                        + ", ".join(invalid_keys)
+                    )
             return 0
 
         if args.cmd == "context-usage":
@@ -478,6 +1281,38 @@ def main() -> int:
                 _print_context(usage)
             return 0
 
+        if args.cmd == "doctor":
+            report = doctor_report(Path(args.specs_dir), Path(args.config))
+            if args.json_output:
+                print(json.dumps(report, indent=2, ensure_ascii=False))
+            else:
+                _print_doctor(report)
+            return 0
+
+        if args.cmd == "discover-feature":
+            payload = discover_feature(args.name, args.specs_dir)
+            if args.json_output:
+                print(json.dumps(payload, indent=2, ensure_ascii=False))
+            else:
+                _print_discover(payload)
+            return 0
+
+        if args.cmd == "stage-exit":
+            payload = stage_exit(
+                args.feature,
+                args.stage,
+                Path(args.specs_dir),
+                Path(args.config),
+                args.epic,
+                args.host,
+                args.next_feature,
+            )
+            if args.json_output:
+                print(json.dumps(payload, indent=2, ensure_ascii=False))
+            else:
+                _print_stage_exit(payload)
+            return 0
+
         raise UsageError(f"unknown command: {args.cmd}")
     except UsageError as exc:
         print(f"Error: {exc}", file=sys.stderr)