@garygentry/feature-forge 0.2.3 → 0.2.4

package/adapters/gemini/scripts/forge-bootstrap.py

@@ -26,6 +26,8 @@ import argparse
 import json
 import os
 import re
+import shlex
+import shutil
 import subprocess
 import sys
 import tempfile
@@ -281,6 +283,32 @@ def _json_text(obj: object) -> str:
     return json.dumps(obj, indent=2, ensure_ascii=False) + "\n"
 
 
+def contained_path(base: Path, *parts: str) -> Path:
+    """Join ``parts`` onto ``base`` and assert the result stays within ``base``.
+
+    Ports epic-manifest.py's ``contained_path`` guard: canonicalizes (symlink-
+    resolves) both ends and verifies containment so no scaffold write or verify
+    cwd can escape the target repo — defense in depth behind ``_validate_answers``
+    should a crafted member path slip through. Containment violations surface only
+    as exit-2 usage errors.
+
+    Args:
+        base: The containing directory (the target repo root), already known to exist.
+        *parts: Repo-relative segments to append (member path, artifact rel path).
+
+    Returns:
+        The resolved, contained absolute path.
+
+    Raises:
+        UsageError: If the resolved path escapes ``base`` (exit 2).
+    """
+    base_real = base.resolve()
+    resolved = (base_real / Path(*parts)).resolve()
+    if resolved != base_real and base_real not in resolved.parents:
+        raise UsageError(f"path escapes target dir: {os.path.join(*parts)}")
+    return resolved
+
+
 def _atomic_write_text(path: Path, text: str) -> None:
     """Write ``text`` to ``path`` atomically via a same-dir temp file + os.replace.
 
@@ -381,7 +409,7 @@ def run(
 
 
 # --------------------------------------------------------------------------- #
-# Subcommand stubs (filled by later backlog items 003/006/008/009/010)
+# Subcommands: check / scaffold / verify / commit / status (02 §8.2)
 # --------------------------------------------------------------------------- #
 
 
@@ -476,6 +504,7 @@ def _write_artifact(
     """
     if rel_path in sentinel["artifactsWritten"]:
         return
+    contained_path(target, rel_path)  # never write outside the target repo (exit 2)
     dest = target / rel_path
     if dest.exists():
         return
@@ -529,7 +558,7 @@ def _resolve_commands(member: Member) -> tuple[str, str]:
 
 
 def write_config(answers: Answers, target: Path, sentinel: Sentinel) -> None:
-    """Write forge.config.json equivalent to forge-init's output (02 §4.3, 00 §7)."""
+    """Write forge.config.json == forge-init's field set + loopRunner (02 §4.3, 00 §7)."""
     config: dict = {
         "specsDir": "./specs",
         "docsDir": "./docs/architecture",
@@ -540,6 +569,14 @@ def write_config(answers: Answers, target: Path, sentinel: Sentinel) -> None:
         "typeCheckCommand": None,
         "testCommand": None,
         "loopIterationMultiplier": 1.5,
+        # Navigator keys — kept in lockstep with forge-init.sh's emitted field set
+        # (00 §7, REQ-CFG-02) so a bootstrapped config == forge-init's + loopRunner.
+        "autoInvokeNextStage": True,
+        "contextWindowTokens": None,
+        "contextWarnThreshold": 0.7,
+        "autoVerify": False,
+        "autoVerifyStages": {},
+        "autoFix": False,
         "loopRunner": {"name": "rauf", "bin": "rauf"},
     }
     if answers["layout"] == "single":
@@ -697,9 +734,9 @@ def scaffold(target: Path, answers: Answers) -> list[str]:
 def toolchain_present(required: list[str]) -> bool:
     """Return True iff every required tool is on PATH (REQ-LIFE-03).
 
-    Probes each binary with ``command -v`` via the run wrapper (a shell builtin,
-    invoked through ``sh -c``). A single missing tool yields False, driving the
-    distinct missing-toolchain outcome (exit 2, 00 §9): the skill then offers
+    Probes each binary with :func:`shutil.which` (a pure PATH lookup, no shell
+    spawned). A single missing tool yields False, driving the distinct
+    missing-toolchain outcome (exit 2, 00 §9): the skill then offers
     scaffold-anyway-unverified vs abort and marks the baseline unverified
     (REQ-LIFE-04). Bootstrap NEVER installs a toolchain (tech-spec §9).
 
@@ -708,17 +745,10 @@ def toolchain_present(required: list[str]) -> bool:
             already {pm}-substituted.
 
     Returns:
-        True iff ``command -v`` succeeds for every entry.
+        True iff every entry resolves on PATH.
     """
     for tool in required:
-        try:
-            proc = run(["sh", "-c", f"command -v {tool}"], cwd=Path.cwd(), check=False)
-        except UsageError:
-            # The probe itself could not be launched (e.g. an empty PATH leaves no
-            # `sh`): treat that as the tool being absent, the missing-toolchain
-            # outcome, never an internal error (REQ-LIFE-03/04).
-            return False
-        if proc.returncode != 0:
+        if shutil.which(tool) is None:
             return False
     return True
 
@@ -763,9 +793,11 @@ def verify(target: Path, answers: Answers) -> VerifyResult:
     test: list[CommandOutcome] = []
     for member in answers["members"]:
         lint_cmd, test_cmd = _resolve_commands(member)
-        cwd = target / member["path"]
+        cwd = contained_path(target, member["path"])  # never run outside the target
         for bucket, cmd in ((lint, lint_cmd), (test, test_cmd)):
-            proc = run(["sh", "-c", cmd], cwd=cwd, check=False)
+            # STACK_COMMANDS templates with an allow-listed {pm} (see _validate_answers)
+            # — split into an argv token list and run without a shell (no `sh -c`).
+            proc = run(shlex.split(cmd), cwd=cwd, check=False)
             bucket.append(
                 {"command": cmd, "ok": proc.returncode == 0, "member": member["path"]}
             )
@@ -867,9 +899,55 @@ def _parse_answers(raw: str) -> Answers:
         raise UsageError(f"malformed --answers JSON: {exc}")
     if not isinstance(parsed, dict):
         raise UsageError("--answers must be a JSON object")
+    _validate_answers(parsed)
     return parsed
 
 
+def _validate_answers(answers: Answers) -> None:
+    """Reject non-allowlisted stack/packageManager and unsafe member paths (exit 2).
+
+    Runs before any ``{pm}`` substitution, ``STACK_COMMANDS[...]`` subscript, or
+    artifact write so a malformed ``--answers`` payload fails with a stderr
+    diagnostic, never a KeyError traceback or a path escape. Mirrors the
+    input-validation rigor epic-manifest.py applies via ``assert_safe_name`` /
+    ``contained_path``:
+
+    - ``stack`` must be a known :data:`Stack` (a ``STACK_COMMANDS`` key).
+    - ``packageManager`` must be in ``PACKAGE_MANAGERS[stack]`` for a stack that
+      has a choice; stacks with no choice (go/rust/generic) must leave it ``None``.
+    - ``path`` must be a repo-relative string — no absolute path, no ``..``
+      component, no backslash — so it can never resolve outside the target.
+    """
+    members = answers.get("members")
+    if not isinstance(members, list) or not members:
+        raise UsageError("--answers must include a non-empty members[] array")
+    for member in members:
+        stack = member.get("stack")
+        if stack not in STACK_COMMANDS:
+            raise UsageError(
+                f"unknown stack {stack!r}: expected one of {sorted(STACK_COMMANDS)}"
+            )
+        pm = member.get("packageManager")
+        choices = PACKAGE_MANAGERS.get(stack)
+        if choices is not None:
+            if pm not in choices:
+                raise UsageError(
+                    f"invalid packageManager {pm!r} for stack {stack!r}: "
+                    f"expected one of {choices}"
+                )
+        elif pm is not None:
+            raise UsageError(
+                f"stack {stack!r} takes no packageManager, got {pm!r}"
+            )
+        path = member.get("path")
+        if not isinstance(path, str) or not path:
+            raise UsageError(f"member path must be a non-empty string, got {path!r}")
+        if os.path.isabs(path) or "\\" in path or ".." in Path(path).parts:
+            raise UsageError(
+                f"unsafe member path {path!r}: must be repo-relative with no '..'"
+            )
+
+
 def _dispatch(args: argparse.Namespace, target: Path) -> int:
     """Route a parsed command to its handler, translating outcomes into exit codes.
 

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

@@ -24,7 +24,10 @@ cat > "$CONFIG_FILE" << 'EOF'
   "loopIterationMultiplier": 1.5,
   "autoInvokeNextStage": true,
   "contextWindowTokens": null,
-  "contextWarnThreshold": 0.7
+  "contextWarnThreshold": 0.7,
+  "autoVerify": false,
+  "autoVerifyStages": {},
+  "autoFix": false
 }
 EOF
 
@@ -43,6 +46,9 @@ 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 "  autoVerify:          false (set true to run forge-verify automatically after each stage)"
+echo "  autoVerifyStages:    {} (per-stage overrides for autoVerify)"
+echo "  autoFix:             false (set true to chain forge-fix after an auto-verify finds issues)"
 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/gemini/scripts/forge-session.py

@@ -37,7 +37,7 @@ from __future__ import annotations
 import argparse
 import json
 import sys
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Final, TypedDict
 
@@ -102,6 +102,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 +185,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 +238,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 +280,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 +322,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 +397,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 +422,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(
@@ -449,6 +583,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")
@@ -462,12 +597,22 @@ def main() -> int:
     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":

package/adapters/gemini/skills/forge/forge.md

@@ -28,19 +28,19 @@ For pipeline architecture details, read `references/process-overview.md`.
 
 1. **Epics first.** Identify epic directories as any `{specsDir}/*/` that directly contains an `epic-manifest.json` **and no `.pipeline-state.json` of its own** (an epic root is never itself a feature). For each epic, run:
    ```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)"
+R="$(bash -c '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/epic-manifest.py" render-status "{epic}" --specs-dir "{specsDir}" --json
    ```
    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**.
-   - **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`):
+   - **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 your session / start 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)"
+R="$(bash -c '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).
+     This returns `{active: [...], counts: {...}}` with active features sorted by `updatedAt` **descending** (row 0 is the most recent). Each row carries `currentStage`, `nextStage`, `nextCommand`, `verifyPending`, `verifyCommand`, `verifyStage`, `verifyState` (`fresh`/`stale`/`failing`/`never`/`none`), `autoVerify` (the effective per-stage setting), and `autoFix` (the single source of stage order). A top-level `invalidAutoVerifyKeys` array appears when `forge.config.json` has `autoVerifyStages` keys outside the five verify-capable stages — surface it as a one-line warning. 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 the host's question mechanism — **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>`."
@@ -86,31 +86,45 @@ Use these status indicators:
 
 ### 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).
+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 your session / start a fresh session 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.
+**1. Read the next step.** From the `rank-features --json` output (above), find this feature's row and read its `nextStage`, `nextCommand`, `verifyPending`, `verifyCommand`, `verifyStage`, `verifyState`, `autoVerify`, and `autoFix`. 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. If the payload has a non-empty `invalidAutoVerifyKeys`, print a one-line warning first (e.g. "⚠️ forge.config.json `autoVerifyStages` has unknown keys: … — they are ignored; fix the typo").
 
 **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)"
+R="$(bash -c '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 the host's question mechanism.** 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}`.
+**2b. Auto-verify branch (when `verifyPending` is true).** Before offering the advance gate, decide whether verify runs automatically:
+
+- **`autoVerify` is true for the just-completed `verifyStage`** → **skip the verify question entirely** and run verify now, *provided it can run clean-room*. Auto-verify is safe to run unattended only because verify executes in a fresh `forge-verifier` subagent that inherits none of this session's context (so no clear your session / start a fresh session is needed and only a compact digest returns). Guard the clean-room assumption: proceed unattended **only when the host's subagent mechanism + `forge-verifier` subagent are available**. Invoke `feature-forge:forge-verify` via the host's skill-invocation mechanism in **require-clean (`auto`) mode** — in that mode forge-verify refuses to run inline and returns a sentinel if the subagent is not dispatchable (see `skills/forge-verify/SKILL.md`). Then:
+  - **Sentinel returned (clean-room unavailable)** → do **not** run verify inline. Degrade to the manual gate: fall through to step 3 with the **"Verify `{stage}` first (manual)"** option included, and if `overThreshold`, recommend "clear your session / start a fresh session, then verify in a clean session." Verify state stays outstanding; the stage is never advanced on false assurance.
+  - **Verify passed / no findings** → proceed to the normal advance gate (step 3), no verify option.
+  - **Verify found findings** →
+    - **`autoFix` is true AND preconditions hold** — the findings document has **zero unresolved decision points** and the **working tree is clean** → invoke `feature-forge:forge-fix` via the host's skill-invocation mechanism, then run a **mandatory re-verify** (require-clean mode). Advance only if the re-verify passes. On **any** precondition miss (decisions required, dirty tree), a forge-fix early stop, or a red re-verify → fall back to the digest + prompt below (never a silent partial mutation).
+    - **`autoFix` is false (default), or preconditions failed** → present a **compact findings digest** as text, then the host's question mechanism: *Apply fixes now (forge-fix)* / *Review findings* / *Skip & advance*.
+- **`autoVerify` is false/unconfigured** → do not auto-run; use the advance gate in step 3, which gains the folded opt-in verify options ("Verify `{stage}` now" and "Verify `{stage}` now + enable auto-verify going forward").
+
+**3. Offer the next step via the host's question mechanism.** (Reached when auto-verify did not fully resolve the step, or `verifyPending` is false.) Output the dashboard + a one-line context note as text, then ask (per the Decision Support protocol in `references/shared-conventions.md`). This is the same **Stage Exit Protocol** the stage skills stamp (`references/stage-exit-protocol.md`) — a clean session at the boundary is recommended on its own merits, and `overThreshold` only modulates *how emphatically*, never *whether*. Options, in this order:
+- **Start `{nextStage}` in a clean session** — **recommended, unconditionally**, at every boundary. A clean session is the right default for the next stage on its own merits, independent of window size. The work survives a clear because all state is on disk: instruct the user to clear your session / start a fresh session, then re-run `/feature-forge:forge {feature}` (or run `{nextCommand}` directly) in the fresh session. Note plainly that you cannot clear your session / start a fresh session for them. **When `overThreshold` is true**, strengthen this wording (the window is also genuinely full) and add mid-stage compaction advice; **when the window is healthy**, still recommend the clean session — `overThreshold` is a *secondary, additive* modifier here, not the clear on/off switch.
+- **Continue in this session** — the always-available alternative, reasonable when the window is nearly empty and the user would rather not clear. Not the default.
+- **Verify `{stage}` now** — include **only when `verifyPending` is true and `autoVerify` is false**, and the clean-room path is available. **Recommended**, since verify is clean-room and rarely worth skipping. Runs verify now (require-clean mode); **does not** change config.
+- **Verify `{stage}` now + enable auto-verify going forward** — same trigger as the option above; runs verify now **and** patches `autoVerify: true` into `forge.config.json` in place (preserve formatting and other keys) so every future stage verifies automatically without prompting. This is the **folded** config-enable — it replaces the old post-hoc "make auto-verify the default?" follow-up. No silent config writes: the config changes **only** when the user picks this option.
+- **Verify `{stage}` first (manual)** — include **only when `verifyPending` is true** and the clean-room path is unavailable (the Tier-2 degradation above), or the host lacks the host's skill-invocation and subagent mechanisms; selecting it runs `{verifyCommand}` (inline / manual). Offer the "enable auto-verify" choice as text only if a config write is possible.
 - **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).
+- **Clean session** (the default) → give the exact next command and the clear your session / start a fresh session-then-re-run instruction; do not invoke anything (you cannot clear your session / start a fresh session for the user).
+- **Continue in this session** → if `autoInvokeNextStage` is true (default) **and** the host's skill-invocation mechanism is available, invoke the chosen stage **via the host's skill-invocation mechanism** in this same session (e.g. `skill: "feature-forge:forge-3-specs"`, `args: "{feature}"`) — no retyping, no paste. If `autoInvokeNextStage` is false, or the host's skill-invocation mechanism is unavailable (a non-Claude host), fall back to printing `{nextCommand}` prominently for the user to run.
+- **Verify now / Verify now + enable auto-verify** → invoke `feature-forge:forge-verify` via the host's skill-invocation mechanism (require-clean mode). For the **enable-auto-verify** variant, additionally patch `autoVerify: true` into `forge.config.json` in place (preserve formatting and other keys) — never a silent write. On a non-Claude host or when degrading to the manual/inline gate, print `{verifyCommand}` instead.
 - **Different stage** → honor the free-form request.
 
+**Host fallback.** On a non-Claude host or when the host's skill-invocation and subagent mechanisms are unavailable, auto-verify never runs unattended — fall back to printing `{verifyCommand}` exactly as today, mirroring `autoInvokeNextStage`.
+
 This applies whether the feature was named explicitly (`/feature-forge:forge {feature}`) or resolved from the recency default.
 
 ### Epic Dashboard
@@ -118,7 +132,7 @@ This applies whether the feature was named explicitly (`/feature-forge:forge {fe
 When the named argument is an epic (`{specsDir}/{name}/epic-manifest.json` exists), render the epic dashboard instead of a per-feature one. Run:
 
 ```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)"
+R="$(bash -c '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/epic-manifest.py" render-status "{epic}" --specs-dir "{specsDir}" --json
 ```
@@ -180,16 +194,16 @@ Support these sub-commands for pipeline lifecycle management:
 - `/feature-forge:forge abandon {feature}` — Set `pipelineStatus` to `"abandoned"`. Use the host's question mechanism 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 the host's question mechanism).
-  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.
+  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 your session / start a fresh session-then-re-run instruction) — never auto-clear your session / start a fresh session.
+  3. Otherwise invoke the next stage's skill via the host's skill-invocation mechanism, 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 the host's question mechanism (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.
+  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 host's skill-invocation mechanism 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`:
 
 - Set the manifest's top-level `status` (`paused` / `active` / `abandoned`) via the helper's `set-status` mutator — an atomic write that also bumps `updatedAt`:
   ```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)"
+R="$(bash -c '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/epic-manifest.py" set-status "{epic}" --status paused --specs-dir "{specsDir}"
   ```