@garygentry/feature-forge 0.2.12 → 0.2.14

package/adapters/codex/scripts/epic-manifest.py

@@ -27,6 +27,7 @@ import argparse
 import json
 import os
 import re
+import shutil
 import sys
 import tempfile
 from datetime import datetime, timezone
@@ -46,6 +47,21 @@ PIPELINE_STATE_FILENAME: Final = ".pipeline-state.json"
 MANIFEST_FILENAME: Final = "epic-manifest.json"
 NARRATIVE_FILENAME: Final = "EPIC.md"
 
+#: The authoritative forge-verify status vocabulary. SOURCE OF TRUTH:
+#: references/pipeline-state-schema.json (definitions.verifyEntry.properties.status.enum).
+#: A member state carrying a forge-verify-*.status outside this set is treated as
+#: incomplete-for-orchestration but SURFACED (never guessed silently) by render_status
+#: — a single typo'd status otherwise poisons the epic rollup + dependency gates (#148).
+#: NOTE: forge-session.py keeps a byte-identical copy of this constant — flat, self-
+#: contained scripts have no shared import module (each is copied verbatim into adapters).
+KNOWN_VERIFY_STATUSES: Final = frozenset(
+    {"pending", "passed", "findings-reported", "findings-applied", "skipped"}
+)
+#: The subset of KNOWN_VERIFY_STATUSES that makes a member's forge-verify-impl count as
+#: complete-for-orchestration (00 §7). A STRICT subset — 'findings-reported' (unfixed),
+#: 'skipped', and 'pending' do NOT unblock dependents. Not collapsible into the set above.
+_VERIFY_ORCH_COMPLETE: Final = frozenset({"passed", "findings-applied"})
+
 
 # --------------------------------------------------------------------------- #
 # Type Definitions (00-core-definitions.md §4, §5; 02 §8.4)
@@ -138,6 +154,10 @@ class RenderStatus(TypedDict):
         rollup: Aggregate {complete, total} counts.
         nextCommand: Recommended next command for the first actionable feature, or
             None when nothing is actionable (all complete, empty epic, or paused).
+        warnings: Human-readable diagnostics that do NOT invalidate the graph but
+            need surfacing — currently, members carrying a ``forge-verify-*.status``
+            outside ``KNOWN_VERIFY_STATUSES`` (treated as incomplete, but silently so
+            would poison the rollup + dependency gates, #148). Empty in the common case.
     """
 
     epic: str
@@ -147,6 +167,7 @@ class RenderStatus(TypedDict):
     parallelEligible: list[str]
     rollup: Rollup
     nextCommand: str | None
+    warnings: list[str]
 
 
 # --------------------------------------------------------------------------- #
@@ -541,6 +562,11 @@ _TOP_REQUIRED: Final = (
 )
 #: Required keys on each Feature object (00 §2.2).
 _FEATURE_REQUIRED: Final = ("name", "charter", "dependsOn", "exposes", "consumes")
+#: Optional keys on each Feature object. `mutatesShared` is the #144 precision
+#: hint for cross-member coupling (array of project-root-relative path strings);
+#: schema-legal when present, ignored when absent (mirrors
+#: epic-manifest-schema.json definitions.feature.properties.mutatesShared).
+_FEATURE_OPTIONAL: Final = ("mutatesShared",)
 #: Required keys on each Contract (exposes[]) object (00 §2.3).
 _CONTRACT_REQUIRED: Final = ("name", "kind", "summary")
 #: Required keys on each ConsumedContract (consumes[]) object (00 §2.4).
@@ -616,11 +642,16 @@ def _schema_findings(manifest: dict) -> list[Finding]:
                 findings.append(_schema(f"feature {label!r} missing required key {key!r}", fname))
         for key in feat:
             # 'status' is rejected separately above via the dedicated 'cached-status' code.
-            if key not in _FEATURE_REQUIRED and key != "status":
+            if key not in _FEATURE_REQUIRED and key not in _FEATURE_OPTIONAL and key != "status":
                 findings.append(_schema(f"feature {label!r} has unknown key {key!r}", fname))
         for key in ("name", "charter"):
             if key in feat and not isinstance(feat[key], str):
                 findings.append(_schema(f"feature {label!r} {key} must be a string", fname))
+        if "mutatesShared" in feat and (
+            not isinstance(feat["mutatesShared"], list)
+            or not all(isinstance(p, str) for p in feat["mutatesShared"])
+        ):
+            findings.append(_schema(f"feature {label!r} mutatesShared must be an array of strings", fname))  # noqa: E501
         if "dependsOn" in feat:
             if not isinstance(feat["dependsOn"], list) or not all(isinstance(d, str) for d in feat["dependsOn"]):  # noqa: E501
                 findings.append(_schema(f"feature {label!r} dependsOn must be an array of strings", fname))  # noqa: E501
@@ -791,7 +822,41 @@ def is_complete_for_orchestration(state: dict) -> bool:
         return True
     if not isinstance(impl, dict):
         return False
-    return impl.get("status") in {"passed", "findings-applied"}
+    return impl.get("status") in _VERIFY_ORCH_COMPLETE
+
+
+def _verify_status_warnings(name: str, state: dict) -> list[str]:
+    """Flag any ``forge-verify-*.status`` outside the known vocabulary (#148).
+
+    An unrecognized status (e.g. the eye-slip ``findings-resolved``, conflated with the
+    adjacent ``findingsResolved`` count) is correctly treated as incomplete by
+    ``is_complete_for_orchestration`` — but *silently*, so one typo on one member
+    under-reports the whole epic rollup and fabricates phantom ``unmetDeps`` on
+    dependents. Surfacing it turns that non-local corruption into a visible diagnostic.
+
+    Non-string / malformed status values (a list, an int) are also flagged, and the
+    membership test is guarded so an unhashable value never raises.
+    """
+    stages = state.get("stages", {})
+    if not isinstance(stages, dict):
+        return []
+    warnings: list[str] = []
+    known = ", ".join(sorted(KNOWN_VERIFY_STATUSES))
+    for stage_name, entry in stages.items():
+        if not (isinstance(stage_name, str) and stage_name.startswith("forge-verify-")):
+            continue
+        if not isinstance(entry, dict):
+            continue
+        status = entry.get("status")
+        if status is None:
+            continue
+        if isinstance(status, str) and status in KNOWN_VERIFY_STATUSES:
+            continue
+        warnings.append(
+            f"{name}: unknown {stage_name} status {status!r} "
+            f"(treated as incomplete; expected one of {known})"
+        )
+    return warnings
 
 
 def _read_state_safely(state_path: Path) -> dict:
@@ -926,14 +991,15 @@ def render_status(epic_dir: Path, specs_dir: Path) -> RenderStatus:
     rows: list[FeatureStatus] = []
     feature_dir_by_name: dict[str, Path] = {}
     complete: dict[str, bool] = {}
+    warnings: list[str] = []
     for feat in features:
         name = feat["name"]
         member_dir = contained_path(epic_dir, name)
         feature_dir_by_name[name] = member_dir
         rows.append(derive_status(member_dir))
-        complete[name] = is_complete_for_orchestration(
-            _read_state_safely(member_dir / PIPELINE_STATE_FILENAME)
-        )
+        member_state = _read_state_safely(member_dir / PIPELINE_STATE_FILENAME)
+        complete[name] = is_complete_for_orchestration(member_state)
+        warnings.extend(_verify_status_warnings(name, member_state))
 
     # (4) per-feature unmetDeps + blocked. A feature that is itself complete is
     #     never "blocked" — unmet deps only matter for work not yet finished.
@@ -988,6 +1054,7 @@ def render_status(epic_dir: Path, specs_dir: Path) -> RenderStatus:
         "parallelEligible": parallel_eligible,
         "rollup": rollup,
         "nextCommand": next_command,
+        "warnings": warnings,
     }
 
 
@@ -1195,6 +1262,180 @@ def set_status(epic_dir: Path, specs_dir: Path, status: str) -> list[Finding]:
     return _bump_and_write(epic_dir, specs_dir, manifest)
 
 
+def _load_state_strict(state_path: Path) -> dict:
+    """Read a .pipeline-state.json, raising UsageError on a missing/corrupt file.
+
+    Unlike ``_read_state_safely`` (which downgrades a torn read to ``{}`` for the
+    read-only dashboard), an adopt mutation must NOT silently discard the
+    standalone's stage history — a corrupt source is a hard stop (exit 2) so the
+    human fixes it before the irreversible move.
+    """
+    try:
+        parsed = json.loads(state_path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise UsageError(f"cannot read {state_path}: {exc}")
+    except json.JSONDecodeError as exc:
+        raise UsageError(f"{state_path} is not valid JSON: {exc}")
+    if not isinstance(parsed, dict):
+        raise UsageError(f"{state_path} is not a JSON object")
+    return parsed
+
+
+def _merge_member_state(stub: dict, standalone: dict, epic_name: str) -> dict:
+    """Merge a detached standalone's state onto an epic member stub (Issue #126).
+
+    The **stub** is the base — it carries the correct ``epic`` and ``branch``
+    back-pointers that the epic minted. The **standalone** holds the real work, so
+    its stage history / artifacts / currentStage overlay the stub. The ``epic``
+    back-pointer is forced to the target epic; the stub's ``branch`` is preserved
+    (only falling back to the standalone's when the stub has none).
+    """
+    merged = dict(stub)
+    for key in ("currentStage", "artifacts", "notes",
+                "deferredDecisions", "epicChangeRequests"):
+        if key in standalone:
+            merged[key] = standalone[key]
+    stages = dict(stub.get("stages") or {})
+    stages.update(standalone.get("stages") or {})
+    merged["stages"] = stages
+    merged["epic"] = epic_name
+    if not (isinstance(stub.get("branch"), str) and stub["branch"]) and \
+            isinstance(standalone.get("branch"), str) and standalone["branch"]:
+        merged["branch"] = standalone["branch"]
+    return merged
+
+
+def adopt_feature(
+    epic_dir: Path,
+    specs_dir: Path,
+    feature: str,
+    charter: str | None,
+    deps: list[str],
+) -> dict:
+    """Reconcile a detached standalone feature into an epic member (Issue #126).
+
+    The scripted recovery for a **split-brain epic** (#125): a feature that should
+    be an epic member was forged as a flat standalone at ``{specsDir}/{feature}/``.
+    This relocates it into the member slot ``{epicDir}/{feature}/``, merging state
+    so the stub's ``epic``/``branch`` back-pointers survive, removes the flat dir
+    (no residual), and adds the feature to the manifest if absent.
+
+    Operates on the CURRENT tree/branch — both the flat standalone and the epic
+    manifest must already be present (the human brings a cross-branch standalone
+    onto the epic's home branch first, per ``docs/recovery-detached-epic-member.md``;
+    EPIC.md prose is regenerated separately via forge-0-epic). Deliberately ordered
+    **relocate-then-manifest**: after the flat dir is gone the feature name maps to
+    exactly one dir, so ``add_feature``'s global-uniqueness re-validation stays
+    clean. Re-entrant — a half-finished run (files moved, manifest not yet updated)
+    completes on re-run.
+
+    Args:
+        epic_dir: The target epic subtree directory (must hold epic-manifest.json).
+        specs_dir: The configured specs directory.
+        feature: The detached standalone feature name to adopt.
+        charter: Charter for the manifest entry when the feature is not yet a
+            member; a default is used when omitted.
+        deps: dependsOn for the new manifest entry (ignored if already a member).
+
+    Returns:
+        A summary dict (``adopted``/``relocated``/``manifestUpdated``/…) on success.
+
+    Raises:
+        UsageError: Unsafe name, missing manifest, nothing to adopt, or an I/O
+            failure (exit 2).
+        FindingsError: A blocking manifest finding from ``add_feature`` (e.g. an
+            unknown dependency) after relocation — exit 1; re-run after fixing.
+    """
+    assert_safe_name(feature)
+    for dep in deps:
+        assert_safe_name(dep)
+
+    # The epic manifest must exist on this tree (exit 2 if not — nothing to adopt into).
+    load_manifest(epic_dir)
+
+    flat_dir = contained_path(specs_dir, feature)
+    member_dir = contained_path(epic_dir, feature)
+    if flat_dir == member_dir:
+        raise UsageError(f"feature {feature!r} resolves to the epic dir itself")
+
+    flat_state = flat_dir / PIPELINE_STATE_FILENAME
+    member_state = member_dir / PIPELINE_STATE_FILENAME
+    flat_exists = flat_state.is_file()
+    member_exists = member_state.is_file()
+
+    if not flat_exists and not member_exists:
+        raise UsageError(
+            f"nothing to adopt: neither a standalone {flat_dir} nor a member "
+            f"{member_dir} has a {PIPELINE_STATE_FILENAME}"
+        )
+
+    relocated = False
+    if flat_exists:
+        standalone = _load_state_strict(flat_state)
+        if member_exists:
+            merged = _merge_member_state(
+                _read_state_safely(member_state), standalone, epic_dir.name
+            )
+        else:
+            merged = dict(standalone)
+            merged["epic"] = epic_dir.name
+        # Move every artifact except the state file (merged separately) into the
+        # member slot; the standalone (real work) wins on any name collision.
+        member_dir.mkdir(parents=True, exist_ok=True)
+        for child in sorted(flat_dir.iterdir()):
+            if child.name == PIPELINE_STATE_FILENAME:
+                continue
+            dest = member_dir / child.name
+            if dest.is_dir():
+                shutil.rmtree(dest)
+            elif dest.exists():
+                dest.unlink()
+            shutil.move(str(child), str(dest))
+        atomic_write(member_state, merged)
+        shutil.rmtree(flat_dir)
+        relocated = True
+    else:
+        # Already nested (a prior run moved the files) — only ensure the back-pointer.
+        stub = _read_state_safely(member_state)
+        if stub.get("epic") != epic_dir.name:
+            stub["epic"] = epic_dir.name
+            atomic_write(member_state, stub)
+
+    # Ensure the feature is a manifest member (idempotent — the flat dir is gone now,
+    # so add_feature's tree-uniqueness re-check sees exactly one dir for the name).
+    manifest = load_manifest(epic_dir)
+    already_member = any(
+        isinstance(f, dict) and f.get("name") == feature
+        for f in manifest.get("features", [])
+    )
+    manifest_updated = False
+    if not already_member:
+        findings = add_feature(
+            epic_dir, specs_dir, feature,
+            charter or f"Adopted into the {epic_dir.name} epic from a detached standalone.",
+            deps,
+        )
+        if findings:
+            raise FindingsError(findings)
+        manifest_updated = True
+
+    return {
+        "adopted": True,
+        "epic": epic_dir.name,
+        "feature": feature,
+        "memberDir": str(member_dir),
+        "relocated": relocated,
+        "manifestUpdated": manifest_updated,
+        "wasAlreadyMember": already_member,
+        "nextSteps": [
+            f"Regenerate EPIC.md prose via /feature-forge:forge-0-epic {epic_dir.name}",
+            f"Confirm the dashboard via /feature-forge:forge {epic_dir.name}",
+            f"Verify the member via /feature-forge:forge-verify {feature}",
+            "Commit the surgery (stage the epic subtree and the removed flat dir).",
+        ],
+    }
+
+
 # --------------------------------------------------------------------------- #
 # CLI Dispatch (02 §9)
 # --------------------------------------------------------------------------- #
@@ -1239,6 +1480,10 @@ def _print_status_table(status: RenderStatus) -> None:
             marker = "⚠️ BLOCKING" if row["blockingEpicChangeRequests"] else "⚠️"
             line += f" — {marker} {row['openEpicChangeRequests']} pending epic change(s)"
         print(line)
+    if status["warnings"]:
+        print("Warnings:")
+        for warning in status["warnings"]:
+            print(f"  ⚠️ {warning}")
     if status["actionable"]:
         print(f"Actionable: {', '.join(status['actionable'])}")
     if status["parallelEligible"]:
@@ -1285,6 +1530,25 @@ def _dispatch(args: argparse.Namespace, specs_dir: Path) -> int:
             _print_status_table(status)
         return 0
 
+    if cmd == "adopt-feature":
+        epic_dir = contained_path(specs_dir, args.epic)
+        summary = adopt_feature(
+            epic_dir, specs_dir, args.name, args.charter,
+            _split_list(args.depends_on),
+        )
+        if args.json_output:
+            print(json.dumps(summary, indent=2, ensure_ascii=False))
+        else:
+            print(f"Adopted {summary['feature']!r} into epic {summary['epic']!r}.")
+            print(f"  member dir:      {summary['memberDir']}")
+            print(f"  relocated files: {summary['relocated']}")
+            print(f"  manifest added:  {summary['manifestUpdated']}"
+                  f"{' (already a member)' if summary['wasAlreadyMember'] else ''}")
+            print("Next steps:")
+            for step in summary["nextSteps"]:
+                print(f"  - {step}")
+        return 0
+
     # Mutators ---------------------------------------------------------------
     if cmd in {"add-feature", "remove-feature", "reorder", "set-dep", "set-status"}:
         epic_dir = contained_path(specs_dir, args.epic)
@@ -1358,6 +1622,21 @@ def _build_parser() -> argparse.ArgumentParser:
     add_specs_dir(p_add)
     add_json(p_add)
 
+    # adopt-feature --------------------------------------------------------- #
+    p_adopt = sub.add_parser(
+        "adopt-feature",
+        help="Reconcile a detached standalone feature into an epic member (#126)",
+    )
+    p_adopt.add_argument("epic")
+    p_adopt.add_argument("name")
+    p_adopt.add_argument(
+        "--charter", default=None,
+        help="Charter for the manifest entry when the feature is not yet a member",
+    )
+    p_adopt.add_argument("--depends-on", dest="depends_on", default="", help="Comma list")
+    add_specs_dir(p_adopt)
+    add_json(p_adopt)
+
     # remove-feature -------------------------------------------------------- #
     p_remove = sub.add_parser("remove-feature", help="Remove a member feature")
     p_remove.add_argument("epic")

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

@@ -568,6 +568,7 @@ def write_config(answers: Answers, target: Path, sentinel: Sentinel) -> None:
         "stack": None,
         "typeCheckCommand": None,
         "testCommand": None,
+        "smokeCommand": 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.

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

@@ -21,6 +21,7 @@ cat > "$CONFIG_FILE" << 'EOF'
   "stack": null,
   "typeCheckCommand": null,
   "testCommand": null,
+  "smokeCommand": null,
   "loopIterationMultiplier": 1.5,
   "autoInvokeNextStage": true,
   "contextWindowTokens": null,
@@ -42,6 +43,7 @@ echo "  commitPrefix:        forge"
 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 "  smokeCommand:        null (optional end-to-end smoke; enables impl-verify runnability check)"
 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)"

package/adapters/codex/scripts/forge-root.sh

@@ -21,14 +21,56 @@ is_root() {  # $1 = candidate dir
   [ -f "$1/.feature-forge-bundle.json" ] || [ -f "$1/.claude-plugin/plugin.json" ]
 }
 
+# Completeness gate (#152). A dir can carry the sentinel yet be a partial/stale install —
+# a skill-only extraction, or an install predating the shared-reference fan-out — where the
+# scripts/references the skills load at every stage are absent. Such a root looks usable but
+# runs DEGRADED silently (hand-improvised state schema, skipped Mint Guard + scripted exit).
+# These are the assets a complete install MUST carry beyond the sentinel; a resolved root
+# missing any of them is reported as degraded rather than handed back as if it were whole.
+CORE_ASSETS=(
+  "scripts/forge-session.py"
+  "references/pipeline-state-schema.json"
+  "references/stage-exit-protocol.md"
+)
+
+# Echo the first missing core asset (relative path) for $1, or nothing when complete.
+first_missing_asset() {  # $1 = candidate dir
+  local a
+  for a in "${CORE_ASSETS[@]}"; do
+    [ -f "$1/$a" ] || { printf '%s' "$a"; return 0; }
+  done
+}
+
+# A sentinel-bearing candidate that lacks a core asset is remembered here (first one wins)
+# so a COMPLETE root found later in the probe order still takes precedence; only if the probe
+# ends with no complete root do we report this degraded install (step 4).
+partial_root=""
+partial_missing=""
+
+# Given a candidate that already passed is_root: print + exit 0 if it is complete; otherwise
+# record it as the degraded fallback and return so probing continues. Always returns 0 on the
+# fall-through path so `set -e` never aborts the resolver on a partial candidate.
+accept_root() {  # $1 = candidate dir (already is_root)
+  local miss
+  miss="$(first_missing_asset "$1")"
+  if [ -z "$miss" ]; then
+    printf '%s\n' "$1"
+    exit 0
+  fi
+  if [ -z "$partial_root" ]; then
+    partial_root="$1"
+    partial_missing="$miss"
+  fi
+  return 0
+}
+
 # ── Step 1: self-location — parent of this script's dir is the install root. ─────────────
 # This is the PRIMARY path: a bundle ships its own scripts/forge-root.sh, so the parent of
 # this script's dir is that bundle's root under any agent's layout.
 self_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
 root="$(cd -- "$self_dir/.." && pwd -P)"
 if is_root "$root"; then
-  printf '%s\n' "$root"
-  exit 0
+  accept_root "$root"
 fi
 
 # ── Step 2a: Claude marketplace-cache installs — ~/.claude/plugins/cache/<mp>/<plugin>/<ver>/.
@@ -42,8 +84,7 @@ fi
 while IFS= read -r manifest; do
   candidate="${manifest%/.claude-plugin/plugin.json}"
   if is_root "$candidate"; then
-    printf '%s\n' "$candidate"
-    exit 0
+    accept_root "$candidate"
   fi
 done < <(ls -t "$HOME"/.claude/plugins/cache/*/feature-forge/*/.claude-plugin/plugin.json 2>/dev/null || true)
 
@@ -69,8 +110,7 @@ for candidate in \
   "$PWD/.gemini/extensions/feature-forge" \
 ; do
   if is_root "$candidate"; then
-    printf '%s\n' "$candidate"
-    exit 0
+    accept_root "$candidate"
   fi
 done
 
@@ -78,14 +118,18 @@ done
 # The neutral override works for every agent; CLAUDE_PLUGIN_ROOT is kept only for backwards
 # compatibility with existing Claude installs (C-4).
 if [ -n "${FEATURE_FORGE_ROOT:-}" ] && is_root "$FEATURE_FORGE_ROOT"; then
-  printf '%s\n' "$FEATURE_FORGE_ROOT"
-  exit 0
+  accept_root "$FEATURE_FORGE_ROOT"
 fi
 if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && is_root "$CLAUDE_PLUGIN_ROOT"; then
-  printf '%s\n' "$CLAUDE_PLUGIN_ROOT"
-  exit 0
+  accept_root "$CLAUDE_PLUGIN_ROOT"
 fi
 
-# ── Step 4: failure — actionable message to stderr, exit 1 (REQ-RES-04). ─────────────────
+# ── Step 4: failure. A sentinel-bearing but asset-incomplete root found along the way is a
+# DEGRADED install (#152) — report it distinctly and actionably rather than the generic
+# cannot-locate message, so the operator knows to reinstall/update rather than reconfigure. ─
+if [ -n "$partial_root" ]; then
+  echo "feature-forge: install incomplete/degraded at $partial_root (missing $partial_missing) — reinstall with 'npx @garygentry/feature-forge' (or 'feature-forge update' for a stale install)." >&2
+  exit 1
+fi
 echo "feature-forge: cannot locate install root. Set FEATURE_FORGE_ROOT to the bundle dir, or run from an installed skill dir." >&2
 exit 1

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

@@ -117,8 +117,20 @@ VERIFY_TOKEN_BY_STAGE: Final[dict[str, str]] = {
 
 #: 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).
+#: The authoritative forge-verify status vocabulary. SOURCE OF TRUTH:
+#: references/pipeline-state-schema.json (definitions.verifyEntry.properties.status.enum).
+#: A status outside this set is unrecognized and must not be silently interpreted (#148).
+#: NOTE: epic-manifest.py keeps a byte-identical copy — flat, self-contained scripts have
+#: no shared import module (each is copied verbatim into per-agent adapter bundles).
+KNOWN_VERIFY_STATUSES: Final = frozenset(
+    {"pending", "passed", "findings-reported", "findings-applied", "skipped"}
+)
+#: Verify statuses that count as "resolved" (no outstanding verify needed). A STRICT
+#: subset of KNOWN_VERIFY_STATUSES — not collapsible into it (different meaning).
 _VERIFY_RESOLVED: Final = frozenset({"passed", "findings-applied", "skipped"})
+#: Per-process dedupe for the unknown-verify-status diagnostic (#148) so a single
+#: bogus status is flagged once, not once per verify_state() call in a command.
+_UNKNOWN_VERIFY_WARNED: set[str] = set()
 
 #: Default context window when the model can't be inferred and config is silent.
 _DEFAULT_WINDOW: Final = 200_000
@@ -257,6 +269,25 @@ def _verify_entry(state: dict, verify_key: str) -> dict:
     return entry if isinstance(entry, dict) else {}
 
 
+def _warn_unknown_verify_status(stage_name: str, status: object) -> None:
+    """Emit a one-time stderr diagnostic for an out-of-vocabulary verify status (#148).
+
+    The freshness classifier maps an unrecognized status to "never verified" — correct,
+    but silent, so a typo poisons the downstream gate (e.g. forge-5-loop's dependency
+    check) with no clue. Flagging it here makes the bad value visible where it is read.
+    """
+    key = f"{stage_name}={status!r}"
+    if key in _UNKNOWN_VERIFY_WARNED:
+        return
+    _UNKNOWN_VERIFY_WARNED.add(key)
+    known = ", ".join(sorted(KNOWN_VERIFY_STATUSES))
+    print(
+        f"feature-forge: unknown {stage_name} status {status!r} "
+        f"(treated as unverified; expected one of {known})",
+        file=sys.stderr,
+    )
+
+
 def verify_state(state: dict) -> tuple[str | None, str]:
     """Classify verify freshness for the most-recently-completed stage.
 
@@ -299,6 +330,12 @@ def verify_state(state: dict) -> tuple[str | None, str]:
         if status not in _VERIFY_RESOLVED:
             if status == "findings-reported":
                 return stage, "failing"
+            # An unrecognized status (outside KNOWN_VERIFY_STATUSES) is treated as
+            # "never verified" — defensible, but flag it once so a typo (e.g. the
+            # eye-slip 'findings-resolved') doesn't silently poison the gate that
+            # reads this label (#148). ``pending``/``None`` are known/absent → quiet.
+            if status is not None and status not in KNOWN_VERIFY_STATUSES:
+                _warn_unknown_verify_status(f"forge-verify-{token}", status)
             return stage, "never"
         verified_version = entry.get("verifiedStageVersion")
         stage_version = _stage_version(state, stage)

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

@@ -88,10 +88,18 @@ Use these status indicators:
 
 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`, `verifyCommand`, `verifyStage`, `verifyState`, `autoVerify`, `autoFix`, and `verifyGate` (the resolved gate: `none` → no verify action; `auto` → the §2b catch-up; `standard` → the §3 gate). 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").
+**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`, `autoFix`, and `verifyGate` (the resolved gate: `none` → no verify action; `auto` → the §2b catch-up; `standard` → the §3 gate). 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 the whole pipeline is done, so **route into the Completion hand-off block below instead of dead-ending** (steps 2/2b/3 do not apply — there is no next stage to drive). 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").
 
 **Detached-epic hint (completion of a *standalone* feature, Issue #125).** When `nextStage` is `null` for a feature whose row has no `epic` (a standalone completion), run `discover-feature "{feature}" --json` (via the standard prelude) *before* congratulating. If any candidate has `isEpicMember: true` on another branch, add an **additive, non-blocking** hint — it does not change the completion, only flags a likely split-brain: "⚠️ Heads-up: `{feature}` matches a member of epic `{epic}` on branch `{stateBranch}`. This standalone pipeline may have been forged detached from that epic. To reconcile, see `docs/recovery-detached-epic-member.md` (or continue — this is only a heads-up)." Skip the hint for epic-member rows (their `epic` is non-null) and when discovery surfaces no epic-member candidate.
 
+**Completion hand-off (fires when `nextStage` is `null` AND `forge-6-docs` has run — the pipeline is fully complete, Issue #124).** Do not dead-end on "pipeline is complete" — after congratulating, point the user at the next unit of work. This is a **terminal branch**: the drive steps (2/2b/3) do not run.
+
+- **Epic member** (this feature's `rank-features` row has a non-null `epic`, i.e. its `.pipeline-state.json` carries an `epic` back-pointer): run `epic-manifest.py render-status "{epic}" --specs-dir "{specsDir}" --json` (standard prelude; you likely already have this from the Tier-1 epic rollup — reuse it rather than re-running). Then:
+  - If `actionable` is non-empty, offer the next member via the host's question mechanism: *"Epic '{epic}' has {total−complete} feature(s) left — next up: **{actionable[0].name}** (`{actionable[0].nextCommand}`). Start it now?"* On accept, drive it exactly like a normal next stage (honor `autoInvokeNextStage` + `Skill`-tool availability per step 3's Continue-in-this-session rule; else print `{nextCommand}`). List any remaining `actionable` members as also-available.
+  - If `actionable` is empty but the epic is **not** fully complete (members blocked on unmet `dependsOn`), say so and point at the blockers rather than offering a start.
+  - If the epic is **fully complete** (`rollup.complete == rollup.total`, `total > 0`), congratulate on the whole epic and offer the epic-level architecture doc (`/feature-forge:forge-6-docs` already surfaces this — mention it) and/or that the epic can be marked complete (`/feature-forge:forge {epic}` renders the finished dashboard).
+- **Standalone** (row's `epic` is null): offer to start a fresh feature — *"Start a new feature: `/feature-forge:forge-1-prd <feature-name>` (or group several with `/feature-forge:forge-0-epic <epic-name>`)."* Then, from the `rank-features` `active` list, surface any **other** active pipelines (exclude this just-completed one) as a one-line list with their `nextCommand`s so the user can jump straight back into in-flight work. If the **detached-epic hint above fired** for this feature, lead with that recovery path (`docs/recovery-detached-epic-member.md`) — the split-brain reconcile is the more likely next action than starting something new.
+
 **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="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"