@garygentry/feature-forge 0.2.1 → 0.2.3

package/README.md

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

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

@@ -56,6 +56,23 @@
       "minimum": 1,
       "description": "Multiplier applied to pending backlog item count to calculate loop iterations. Higher values allow more retries. Default: 1.5 (e.g., 10 items = 15 iterations)."
     },
+    "autoInvokeNextStage": {
+      "type": "boolean",
+      "default": true,
+      "description": "When true (default), the /feature-forge:forge navigator auto-invokes the next pipeline stage via the Skill tool after the user confirms it, instead of only printing the command to copy. Set false to keep the old copy-paste behavior (the navigator suggests the command but never launches it). Ignored on non-Claude hosts, which always fall back to printing the command."
+    },
+    "contextWindowTokens": {
+      "type": ["integer", "null"],
+      "default": null,
+      "description": "Context window size (tokens) used by the navigator's context-usage check to compute how full the current session is. Null (default) lets the helper infer from the session model and fall back to 200000 — and if observed usage already exceeds 200000 it auto-bumps the assumed window to 1000000 (proof a 1M-beta window is active). Set this explicitly to your model's window (e.g. 1000000 for a 1M-context model) for accurate percentages below 200000 too, since 1M cannot be detected from the transcript until usage crosses 200000."
+    },
+    "contextWarnThreshold": {
+      "type": "number",
+      "default": 0.7,
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Fraction of the context window (0-1) past which the navigator recommends starting the next stage in a clean session rather than continuing. Default: 0.7."
+    },
     "workspaces": {
       "type": "array",
       "description": "Monorepo members. Absent for single-package projects.",
@@ -94,7 +111,7 @@
         "eventStreamCommand": {
           "type": "string",
           "default": "{bin} loop run . --backlog {backlogDir} --iterations {iterations} --ndjson",
-          "description": "PREFERRED launch command for forge-5. Same as runCommand but emits one machine-readable JSON event per stdout line (NDJSON): item_completed / item_blocked / needs_human / signal_parsed / loop_completed / loop_error / loop_cancelled / llm_stuck_warning, each with {type, timestamp, projectPath} plus payload (a circuit-breaker halt surfaces as loop_error). forge-5 redirects this stdout to {backlogDir}/{stateDir}/events.ndjson and arms a Monitor on it for live, structured supervision. If a runner cannot emit NDJSON, omit this field — forge-5 falls back to runCommand + tailing the human log."
+          "description": "Stdout NDJSON launch command for a runner that does NOT persist its own event file — same as runCommand but emits one machine-readable JSON event per stdout line: item_completed / item_blocked / needs_human / signal_parsed / loop_completed / loop_error / loop_cancelled / llm_stuck_warning, each with {type, timestamp, projectPath} plus payload (a circuit-breaker halt surfaces as loop_error). NOTE: rauf (the default runner) ALREADY persists {stateDir}/events.ndjson natively and rotates it per run, so forge-5 launches the plain runCommand and monitors that native file — it does NOT use this field, and must NOT redirect --ndjson into {stateDir} (redundant, and it collides with the runner's own writer / archive rotation). This field is only for a stdout-only runner with no native event file; forge-5 then redirects its stdout to a file OUTSIDE {stateDir} and monitors that. Omit it entirely for a runner that self-persists or cannot emit NDJSON."
         },
         "validateCommand": {
           "type": "string",
@@ -173,8 +190,8 @@
         },
         "installHint": {
           "type": "string",
-          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.8.1 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.8.1 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
-          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.8.1), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.11.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.11.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
+          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.11.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
         },
         "schemaVersion": {
           "type": "string",

package/adapters/claude/references/shared-conventions.md

@@ -68,6 +68,9 @@ Extract these config values (use defaults if not present):
 - `branchPerFeature` (default: true)
 - `branchPrefix` (default: `forge/`)
 - `loopIterationMultiplier` (default: `1.5`)
+- `autoInvokeNextStage` (default: `true` — the `/feature-forge:forge` navigator auto-invokes the next stage via the `Skill` tool after the user confirms; `false` keeps copy-paste behavior. Navigator-only.)
+- `contextWindowTokens` (default: `null` — context window used by the navigator's context-usage check; `null` infers from the session model and falls back to 200000. Set to the model's window, e.g. `1000000` on a 1M model. Navigator-only.)
+- `contextWarnThreshold` (default: `0.7` — fraction of the window past which the navigator recommends a clean session. Navigator-only.)
 - `loopRunner` (optional object — the loop runner to drive; **defaults to rauf** when absent, with every command templated. See `references/forge-config-schema.json` and `references/ralph-loop-contract.md`.)
 
 ## Feature Directory Resolution

package/adapters/claude/scripts/forge-init.sh

@@ -21,7 +21,10 @@ cat > "$CONFIG_FILE" << 'EOF'
   "stack": null,
   "typeCheckCommand": null,
   "testCommand": null,
-  "loopIterationMultiplier": 1.5
+  "loopIterationMultiplier": 1.5,
+  "autoInvokeNextStage": true,
+  "contextWindowTokens": null,
+  "contextWarnThreshold": 0.7
 }
 EOF
 
@@ -37,6 +40,9 @@ echo "  stack:               null (auto-detected during forge-2-tech)"
 echo "  typeCheckCommand:    null (auto-detected during forge-2-tech)"
 echo "  testCommand:         null (auto-detected during forge-2-tech)"
 echo "  loopIterationMultiplier: 1.5 (multiplier for loop iterations)"
+echo "  autoInvokeNextStage: true (navigator auto-starts the next stage after you confirm)"
+echo "  contextWindowTokens: null (infer; set to 1000000 on a 1M-context model)"
+echo "  contextWarnThreshold: 0.7 (suggest a clean session past this fraction of the window)"
 echo ""
 echo "The loop runner defaults to rauf. To target a different ralph-style runner,"
 echo "add a \"loopRunner\" block (see references/forge-config-schema.json)."

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

@@ -0,0 +1,491 @@
+#!/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`
+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]
+
+`rank-features` scans the specs tree for feature-shaped directories (those that
+directly contain a `.pipeline-state.json`, in both the flat
+`{specsDir}/{feature}/` and nested `{specsDir}/{epic}/{feature}/` layouts) and
+reports the **active** ones ordered by `updatedAt` descending, so the navigator
+can offer the most-recently-touched feature as the recency default. Each row
+carries the next actionable stage + its slash command, derived from the single
+ordered stage map below.
+
+`context-usage` reads the live Claude Code session transcript (the most-recently
+modified `*.jsonl` under `~/.claude/projects/<cwd-slug>/`), sums the last
+assistant message's token usage, and compares it to the context window so the
+navigator can recommend a clean session before the next stage. It is best-effort
+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.
+
+3.10 baseline, Google-style docstrings, full type annotations, stdlib only —
+matching the conventions of `scripts/epic-manifest.py`.
+
+Exit codes:
+    0 = ok (including an empty feature list or unavailable context usage)
+    2 = usage error or unreadable I/O
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Final, TypedDict
+
+
+# --------------------------------------------------------------------------- #
+# Constants
+# --------------------------------------------------------------------------- #
+
+#: A directory is "feature-shaped" iff it directly contains this file.
+PIPELINE_STATE_FILENAME: Final = ".pipeline-state.json"
+#: Epic roots hold this (and no .pipeline-state.json) — never a feature.
+MANIFEST_FILENAME: Final = "epic-manifest.json"
+
+#: The ordered production stages. This is the ONE place stage order lives.
+PRODUCTION_STAGES: Final[tuple[str, ...]] = (
+    "forge-1-prd",
+    "forge-2-tech",
+    "forge-3-specs",
+    "forge-4-backlog",
+    "forge-5-loop",
+    "forge-6-docs",
+)
+
+#: Production stage -> the verify token its findings file uses, and the
+#: `forge-verify-<token>` key its state lives under. forge-6-docs has no verify.
+VERIFY_TOKEN_BY_STAGE: Final[dict[str, str]] = {
+    "forge-1-prd": "prd",
+    "forge-2-tech": "tech",
+    "forge-3-specs": "specs",
+    "forge-4-backlog": "backlog",
+    "forge-5-loop": "impl",
+}
+
+#: A production stage status that counts as "done" for next-stage selection.
+_DONE_STATUS: Final = "complete"
+#: Verify statuses that count as "resolved" (no outstanding verify needed).
+_VERIFY_RESOLVED: Final = frozenset({"passed", "findings-applied", "skipped"})
+
+#: Default context window when the model can't be inferred and config is silent.
+_DEFAULT_WINDOW: Final = 200_000
+#: Window for 1M-context models (model id carries a `[1m]` / `-1m` marker).
+_WIDE_WINDOW: Final = 1_000_000
+#: Default fraction of the window past which a clean session is recommended.
+_DEFAULT_THRESHOLD: Final = 0.7
+
+
+# --------------------------------------------------------------------------- #
+# Types
+# --------------------------------------------------------------------------- #
+
+
+class FeatureRow(TypedDict):
+    """One active feature, ranked by recency, with its next actionable step."""
+
+    name: str
+    epic: str | None
+    currentStage: str
+    branch: str | None
+    updatedAt: str | None
+    complete: bool
+    nextStage: str | None
+    nextCommand: str | None
+    verifyPending: bool
+    verifyCommand: str | None
+
+
+class UsageError(Exception):
+    """A usage or I/O failure that must exit 2."""
+
+
+# --------------------------------------------------------------------------- #
+# Feature scanning & ranking
+# --------------------------------------------------------------------------- #
+
+
+def _read_state(state_path: Path) -> dict:
+    """Read a `.pipeline-state.json`, tolerating missing/corrupt files.
+
+    A missing, unreadable, or unparseable state downgrades to ``{}`` rather than
+    crashing the scan — the navigator simply treats that feature as not-started.
+    """
+    try:
+        parsed = json.loads(state_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _scan_features(specs_dir: Path) -> list[tuple[str, str | None, dict]]:
+    """Find every feature-shaped dir under the specs tree (flat + nested).
+
+    Descends exactly one level below each top-level dir (never deeper), matching
+    ``epic-manifest.py``'s feature-shaped-dir bound.
+
+    Args:
+        specs_dir: The configured specs directory.
+
+    Returns:
+        A list of ``(feature_name, epic_name_or_None, state_dict)`` tuples. The
+        epic name is the parent dir name for a nested member, ``None`` for a flat
+        feature.
+    """
+    if not specs_dir.is_dir():
+        return []
+    out: list[tuple[str, str | None, dict]] = []
+    for top in sorted(p for p in specs_dir.iterdir() if p.is_dir()):
+        flat_state = top / PIPELINE_STATE_FILENAME
+        if flat_state.is_file():
+            out.append((top.name, None, _read_state(flat_state)))
+        # Descend one level for nested epic members (skip the epic root itself).
+        for child in sorted(p for p in top.iterdir() if p.is_dir()):
+            nested_state = child / PIPELINE_STATE_FILENAME
+            if nested_state.is_file():
+                out.append((child.name, top.name, _read_state(nested_state)))
+    return out
+
+
+def _stage_status(state: dict, stage: str) -> str | None:
+    """Return the recorded status of a stage, 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
+    status = entry.get("status")
+    return status if isinstance(status, str) else None
+
+
+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).
+    """
+    for stage in PRODUCTION_STAGES:
+        if _stage_status(state, stage) != _DONE_STATUS:
+            return stage
+    return None
+
+
+def pending_verify(state: dict) -> str | None:
+    """Return the production stage whose verify is outstanding, if any.
+
+    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.
+    """
+    for stage in reversed(PRODUCTION_STAGES):
+        if _stage_status(state, stage) != _DONE_STATUS:
+            continue
+        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
+
+
+def _parse_ts(value: str | None) -> datetime | None:
+    """Parse an ISO-8601 timestamp (tolerating a trailing 'Z'), else None."""
+    if not isinstance(value, str):
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def build_rows(specs_dir: Path) -> 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.
+    """
+    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)
+        branch = state.get("branch")
+        updated = state.get("updatedAt")
+        rows.append({
+            "name": name,
+            "epic": epic,
+            "currentStage": state.get("currentStage") or (nxt or "complete"),
+            "branch": branch if isinstance(branch, str) else None,
+            "updatedAt": updated if isinstance(updated, str) else None,
+            "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,
+        })
+    # 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)),
+        reverse=True,
+    )
+    return rows
+
+
+def _counts(specs_dir: Path) -> dict[str, int]:
+    """Tally active/paused/abandoned pipelines across the specs tree."""
+    tally = {"active": 0, "paused": 0, "abandoned": 0}
+    for _name, _epic, state in _scan_features(specs_dir):
+        status = state.get("pipelineStatus", "active")
+        if status in tally:
+            tally[status] += 1
+    return tally
+
+
+# --------------------------------------------------------------------------- #
+# Context-window usage
+# --------------------------------------------------------------------------- #
+
+
+def _cwd_slug(cwd: Path) -> str:
+    """Map a working directory to its Claude Code project-dir slug.
+
+    Claude Code names the per-project transcript dir by replacing path
+    separators (and dots) in the absolute cwd with hyphens, e.g.
+    ``/home/u/proj`` -> ``-home-u-proj``.
+    """
+    return str(cwd.resolve()).replace("/", "-").replace(".", "-")
+
+
+def _latest_transcript(cwd: Path) -> Path | None:
+    """Return the most-recently-modified transcript JSONL for this cwd, if any."""
+    project_dir = Path.home() / ".claude" / "projects" / _cwd_slug(cwd)
+    if not project_dir.is_dir():
+        return None
+    transcripts = [p for p in project_dir.glob("*.jsonl") if p.is_file()]
+    if not transcripts:
+        return None
+    return max(transcripts, key=lambda p: p.stat().st_mtime)
+
+
+def _last_usage(transcript: Path) -> tuple[int, str | None] | None:
+    """Scan a transcript from the end for the last `usage` record.
+
+    Returns ``(token_total, model_id)`` where the total sums
+    ``input_tokens + cache_creation_input_tokens + cache_read_input_tokens +
+    output_tokens`` of the most recent message carrying a usage object — i.e. the
+    current context occupancy. Returns ``None`` if no usable record is found.
+    """
+    try:
+        lines = transcript.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return None
+    for line in reversed(lines):
+        line = line.strip()
+        if not line or '"usage"' not in line:
+            continue
+        try:
+            record = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        message = record.get("message")
+        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)
+        )
+        if total <= 0:
+            continue
+        model = message.get("model") if isinstance(message, dict) else record.get("model")
+        return total, (model if isinstance(model, str) else None)
+    return None
+
+
+def _infer_window(model: str | None) -> int:
+    """Infer the context window from a model id (1M-context markers -> wide)."""
+    if model and ("[1m]" in model.lower() or "-1m" in model.lower()):
+        return _WIDE_WINDOW
+    return _DEFAULT_WINDOW
+
+
+def _config_value(config_path: Path, key: str):
+    """Read a single key from forge.config.json, or None if absent/unreadable."""
+    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
+
+
+def context_usage(
+    config_path: Path,
+    window_override: int | None,
+    threshold_override: float | None,
+) -> dict:
+    """Compute live context-window occupancy for the current session.
+
+    Window precedence: ``--window`` > config ``contextWindowTokens`` > inferred
+    from the transcript's model id > ``_DEFAULT_WINDOW``. When inferring (no
+    override, no config) and the observed token total already exceeds the default
+    window, the window is auto-bumped to ``_WIDE_WINDOW`` — observed tokens above
+    200k prove a wider (1M-beta) window is active, so this corrects the reading
+    without ever under-reporting a genuine 200k session. Threshold precedence:
+    ``--threshold`` > config ``contextWarnThreshold`` > ``_DEFAULT_THRESHOLD``.
+
+    Returns a dict with ``available: True`` and ``{tokens, windowTokens, pct,
+    overThreshold, recommendation, model}`` when usage is found, or
+    ``{available: False, reason}`` otherwise. Never raises for a missing
+    transcript — that is the expected non-Claude / fresh-session path.
+    """
+    threshold = threshold_override
+    if threshold is None:
+        cfg_threshold = _config_value(config_path, "contextWarnThreshold")
+        threshold = (
+            float(cfg_threshold)
+            if isinstance(cfg_threshold, (int, float))
+            else _DEFAULT_THRESHOLD
+        )
+
+    transcript = _latest_transcript(Path.cwd())
+    if transcript is None:
+        return {"available": False, "reason": "no session transcript found"}
+    found = _last_usage(transcript)
+    if found is None:
+        return {"available": False, "reason": "no usage record in transcript"}
+    tokens, model = found
+
+    window = window_override
+    if window is None or window <= 0:
+        cfg_window = _config_value(config_path, "contextWindowTokens")
+        if isinstance(cfg_window, int) and cfg_window > 0:
+            window = cfg_window
+        else:
+            # Inferring (no override, no config). Start from the model marker /
+            # conservative default, then auto-bump: observed tokens above the
+            # default window PROVE a wider window is active (a 200k session can
+            # never exceed 200k), so widen to 1M rather than report a nonsensical
+            # >100%. Never under-reports a real 200k session, which can't trip it.
+            window = _infer_window(model)
+            if tokens > window:
+                window = _WIDE_WINDOW
+
+    pct = round(tokens / window, 4)
+    over = pct >= threshold
+    if over:
+        recommendation = "clean-session"
+    else:
+        recommendation = "continue"
+    return {
+        "available": True,
+        "tokens": tokens,
+        "windowTokens": window,
+        "pct": pct,
+        "threshold": threshold,
+        "overThreshold": over,
+        "recommendation": recommendation,
+        "model": model,
+    }
+
+
+# --------------------------------------------------------------------------- #
+# CLI dispatch
+# --------------------------------------------------------------------------- #
+
+
+def _print_rank_table(rows: list[FeatureRow], counts: dict[str, int]) -> None:
+    """Print a human-readable recency-ranked feature list."""
+    print(
+        f"Active: {counts['active']}  "
+        f"(paused: {counts['paused']}, abandoned: {counts['abandoned']})"
+    )
+    if not rows:
+        print("  (no active feature pipelines)")
+        return
+    for idx, row in enumerate(rows):
+        marker = "→" if idx == 0 else " "
+        label = row["name"] + (f" [{row['epic']}]" if row["epic"] else "")
+        nxt = row["nextCommand"] or "complete"
+        print(f"  {marker} {label}: {row['currentStage']} — next: {nxt}")
+        if row["verifyPending"]:
+            print(f"      (verify available: {row['verifyCommand']})")
+
+
+def _print_context(usage: dict) -> None:
+    """Print a one-line human-readable context-usage summary."""
+    if not usage.get("available"):
+        print(f"context usage: unavailable ({usage.get('reason', 'unknown')})")
+        return
+    pct = round(usage["pct"] * 100, 1)
+    flag = " — over threshold, clean session recommended" if usage["overThreshold"] else ""
+    print(
+        f"context: {usage['tokens']:,} / {usage['windowTokens']:,} tokens "
+        f"(~{pct}%){flag}"
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="forge-session.py", description=__doc__)
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    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("--json", action="store_true", dest="json_output")
+
+    p_ctx = sub.add_parser("context-usage", help="Report live context-window usage")
+    p_ctx.add_argument("--config", default="./forge.config.json", help="forge.config.json path")
+    p_ctx.add_argument("--window", type=int, default=None, help="Override context window size")
+    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")
+
+    args = parser.parse_args()
+
+    try:
+        if args.cmd == "rank-features":
+            specs_dir = Path(args.specs_dir)
+            rows = build_rows(specs_dir)
+            counts = _counts(specs_dir)
+            if args.json_output:
+                print(json.dumps({"active": rows, "counts": counts}, indent=2, ensure_ascii=False))
+            else:
+                _print_rank_table(rows, counts)
+            return 0
+
+        if args.cmd == "context-usage":
+            usage = context_usage(Path(args.config), args.window, args.threshold)
+            if args.json_output:
+                print(json.dumps(usage, indent=2, ensure_ascii=False))
+            else:
+                _print_context(usage)
+            return 0
+
+        raise UsageError(f"unknown command: {args.cmd}")
+    except UsageError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+    except OSError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/adapters/claude/skills/forge/SKILL.md

@@ -35,7 +35,14 @@ python3 "$R/scripts/epic-manifest.py" render-status "{epic}" --specs-dir "{specs
    ```
    and show one rollup line: `{epic} — {complete}/{total} complete, next: {nextCommand}`.
 2. **Standalone features below.** Scan the remaining `{specsDir}/*/` that directly contain a `.pipeline-state.json` **without** an `epic` back-pointer. A nested member's `.pipeline-state.json` is **attributed to its epic (Tier 1), never listed as a standalone feature**.
-   - Within this standalone tier the existing logic still applies: if exactly one active (non-complete) standalone pipeline exists, show its dashboard; if multiple exist, list them with a one-line summary each and use `AskUserQuestion` to ask which to focus on.
+   - **Rank by recency.** Run the recency ranker so the most-recently-touched active feature is the default — the user rarely has to type a name (especially on mobile after a `/clear`):
+     ```bash
+R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" rank-features --specs-dir "{specsDir}" --json
+     ```
+     This returns `{active: [...], counts: {...}}` with active features sorted by `updatedAt` **descending** (row 0 is the most recent). Each row carries `currentStage`, `nextStage`, `nextCommand`, `verifyPending`, and `verifyCommand` (the single source of stage order). The `active` list excludes nested epic members surfaced in Tier 1 — but the ranker scans them too, so ignore rows whose `epic` is non-null here (they belong to the epic rollup).
+   - **Pick the feature:** if exactly one active standalone pipeline exists, show its dashboard. If multiple exist, use `AskUserQuestion` — **list the most-recently-updated first, labeled `(recommended)`**, each option's description showing its `currentStage` and a relative age ("updated 2h ago"). Always include a free-form escape ("A different feature / something else") so the user is never boxed in. Then render the chosen feature's dashboard.
 
 If no epics and no standalone features exist, say: "No active feature pipelines found. Start one with `/feature-forge:forge-1-prd <feature-name>` or group several with `/feature-forge:forge-0-epic <epic-name>`."
 
@@ -78,6 +85,35 @@ Use these status indicators:
 - ⏭️ = verification skipped (user chose to proceed without verifying)
 - ⚠️ = stale (built against an older version of an upstream artifact)
 
+### 3b. Drive to the Next Stage
+
+After rendering a **per-feature** dashboard for an **active** pipeline (skip this for paused/abandoned pipelines and for the Epic Dashboard), don't stop at a text suggestion — actively offer to start the next stage. This removes the copy-paste-after-`/clear` chore that makes long, multi-stage runs painful (especially on mobile).
+
+**1. Read the next step.** From the `rank-features --json` output (above), find this feature's row and read its `nextStage`, `nextCommand`, `verifyPending`, and `verifyCommand`. If the feature is not in the `active` list (paused/abandoned), or `nextStage` is `null` (every production stage complete), skip the drive prompt — instead congratulate the user and, if `forge-6-docs` has not run, offer it; otherwise note the pipeline is complete.
+
+**2. Check the context window.** Run the context-usage helper so you can advise whether to continue here or start the next stage in a fresh session:
+```bash
+R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" context-usage --json
+```
+- `{"available": true, ...}` → note `pct` (e.g. "context ~68% full") and `overThreshold`. Window/threshold come from `contextWindowTokens` / `contextWarnThreshold` in `forge.config.json` (the helper defaults to a 200k window and 0.7 threshold, and auto-bumps the assumed window to 1M once observed usage exceeds 200k; **on a 1M-context model set `contextWindowTokens: 1000000` so the percentage is accurate below 200k too** — 1M can't be detected from the transcript until usage crosses 200k).
+- `{"available": false, ...}` → omit context advice silently (non-Claude host, or a fresh session with no transcript). Never treat this as an error.
+
+**3. Offer the next step via `AskUserQuestion`.** Output the dashboard + a one-line context note as text, then ask (per the Decision Support protocol in `references/shared-conventions.md`). Options, in this order:
+- **Start `{nextStage}` now** — recommended **when context is healthy** (`overThreshold` false or context unavailable).
+- **Start in a clean session** — recommended-**first** instead **when `overThreshold` is true**. The work survives a clear because all state is on disk: instruct the user to `/clear`, then re-run `/feature-forge:forge {feature}` (or run `{nextCommand}` directly) in the fresh session. Note plainly that you cannot `/clear` for them.
+- **Verify `{stage}` first** — include **only when `verifyPending` is true**; selecting it runs `{verifyCommand}`.
+- **Pick a different stage** — free-form escape to any stage or other action.
+
+**4. Act on the choice.**
+- **Start now** → if `autoInvokeNextStage` is true (default) **and** the `Skill` tool is available, invoke the chosen stage **via the `Skill` tool** in this same session (e.g. `skill: "feature-forge:forge-3-specs"`, `args: "{feature}"`) — no retyping, no paste. If `autoInvokeNextStage` is false, or the `Skill` tool is unavailable (a non-Claude host), fall back to printing `{nextCommand}` prominently for the user to run.
+- **Clean session** → give the exact next command and the `/clear`-then-re-run instruction; do not invoke anything.
+- **Verify** → invoke `feature-forge:forge-verify` via the `Skill` tool (or print `{verifyCommand}` on a non-Claude host).
+- **Different stage** → honor the free-form request.
+
+This applies whether the feature was named explicitly (`/feature-forge:forge {feature}`) or resolved from the recency default.
+
 ### Epic Dashboard
 
 When the named argument is an epic (`{specsDir}/{name}/epic-manifest.json` exists), render the epic dashboard instead of a per-feature one. Run:
@@ -143,6 +179,12 @@ Support these sub-commands for pipeline lifecycle management:
 - `/feature-forge:forge pause {feature}` — Set `pipelineStatus` to `"paused"`. Do NOT modify `currentStage` or any stage statuses. The pipeline freezes exactly as-is. Show a confirmation.
 - `/feature-forge:forge resume {feature}` — Set `pipelineStatus` back to `"active"`. Calculate how long the feature was paused (from `updatedAt` to now). If paused for more than 24 hours, show a hint: "This feature was paused for {duration}. Session context may have been lost — consider re-running `/feature-forge:forge-{currentStage} {feature}` to rebuild context."
 - `/feature-forge:forge abandon {feature}` — Set `pipelineStatus` to `"abandoned"`. Use `AskUserQuestion` to confirm first, and state what's reversible: abandoning does not delete artifacts and can be undone with `/feature-forge:forge resume {feature}`, so the cost is low — but if the user really means "stop and discard," point out that `pause` is the better choice when they're only setting it aside. Offer **Abandon** · **Pause instead** · **Cancel**.
+- `/feature-forge:forge run [{feature}]` — **Opt-in auto-advance.** Drive the feature through consecutive stages in one session instead of confirming each boundary. This is a convenience wrapper over **3b. Drive to the Next Stage** — same stage order, same context gate — just looped:
+  1. Resolve the feature (if omitted, use the recency default from `rank-features`; if multiple are equally plausible, ask once via `AskUserQuestion`).
+  2. **Before each stage,** run `forge-session.py context-usage`. If `overThreshold` is true, **stop** and recommend a clean session (give the exact `{nextCommand}` and the `/clear`-then-re-run instruction) — never auto-`/clear`.
+  3. Otherwise invoke the next stage's skill via the `Skill` tool, let it run to its natural stopping point, then re-read state and continue from step 2.
+  4. **Stop conditions:** the next stage is an interview/decision point that calls `AskUserQuestion` (PRD and tech inherently pause for input — let them); `nextStage` is `null` (pipeline complete); context over threshold; or a stage signals it needs human input / is blocked. Always report where the loop stopped and why.
+  Per-stage confirmation (3b) remains the default — `run` is only used when the user explicitly asks to "run" / "drive" / "auto-advance" the pipeline. On a non-Claude host where the `Skill` tool is unavailable, fall back to printing the ordered list of commands to run.
 
 **Epic lifecycle.** When the argument names an **epic** (`{specsDir}/{name}/epic-manifest.json` exists), `pause` / `resume` / `abandon` operate on the epic manifest, not a `.pipeline-state.json`: