@garygentry/feature-forge 0.2.11 → 0.2.13

package/adapters/GENERATION-REPORT.md

@@ -131,6 +131,7 @@ These files are transported byte-for-byte from canon into every `adapters/<agent
 - `scripts/forge-root.sh` → `adapters/<agent>/scripts/forge-root.sh` (mode 0755, byte-identical — REQ-GEN-05).
 - the whole repo-root `references/` tree (all root files plus the `stacks/` and `templates/specs-hygiene/` subtrees) → `adapters/<agent>/references/` (verbatim — REQ-GEN-04 / D5).
 - each skill's own `references/` subdir → `adapters/<agent>/skills/<name>/references/` (verbatim, where present).
+- each bundle-root SHARED reference a skill cites (e.g. `references/shared-conventions.md`, `references/stacks/`) → that skill's `adapters/<agent>/skills/<name>/references/` (verbatim), so a bare `references/X` prose read resolves skill-local on every install layout — including the non-plugin Claude tree with no `${CLAUDE_PLUGIN_ROOT}` (#132).
 
 Regenerate all adapter output with `python3 scripts/build-adapters.py`.
 

package/adapters/claude/.feature-forge-bundle.json

@@ -1,6 +1,6 @@
 {
   "name": "feature-forge",
-  "version": "0.12.6",
+  "version": "0.12.8",
   "agent": "claude",
   "generatedBy": "python3 scripts/build-adapters.py"
 }

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

@@ -51,6 +51,11 @@
       "type": ["string", "null"],
       "description": "Command to run tests. Null until set. Examples: 'bun test', 'pytest', 'go test ./...'. Used in acceptance criteria and verification."
     },
+    "smokeCommand": {
+      "type": ["string", "null"],
+      "default": null,
+      "description": "Optional end-to-end smoke command that boots the wired application entrypoint and drives one happy-path request, exiting 0 on success. DISTINCT from testCommand (unit tests, which may self-bootstrap) and loopRunner.runCommand (the loop launcher). Consumed by impl-verify's runnability check (CHECK-I21): when set it is executed (pass iff exit 0); when null the check degrades to an advisory not-applicable finding, never a hard fail (mirrors how a null typeCheckCommand is treated). Examples: 'npm run smoke', './scripts/smoke.sh', 'curl -fsS localhost:3000/health'."
+    },
     "loopIterationMultiplier": {
       "type": "number",
       "default": 1.5,

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

@@ -159,6 +159,28 @@ python3 "$R/scripts/epic-manifest.py" \
 
 If `render-status` fails, proceed with **only** EPIC.md + charter (a corrupt manifest must not silently inject stale dep specs — REQ-ROBUST-02): on **exit 1**, parse the `{findings[]}` JSON from stdout and surface each; on **exit 2**, surface the plain `Error:` line from stderr verbatim. Do not attempt to parse findings JSON on an exit-2 failure (stdout is empty).
 
+**After injecting context, invoke the Epic-Member Base Guard block below** (it self-gates to a no-op for standalone features and features that do not resolve as a nested member).
+
+## Epic-Member Base Guard
+
+Defense-in-depth for the split-brain-epic failure (Issue #125). Invoke this block in the authoring stages (`forge-1-prd`..`forge-4-backlog`) once the feature has resolved — right after **Epic Context Injection** for the stages that run it (`forge-1-prd`..`forge-3-specs`), and right after **Feature Directory Resolution** for `forge-4-backlog`. It confirms that a **resolved nested epic member** actually sits on a branch that contains the epic's manifest. Without this, a member reached from a branch cut *before* the epic-manifest commit (or that otherwise lacks it) would author specs against an epic decomposition that is not present — the exact drift that produces a disjoint, split-brain member. **Skip if not a git repo or `branchPerFeature` is false.**
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_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')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" check-epic-base --feature "{feature}" --specs-dir "{specsDir}" --json
+```
+
+Act on the emitted `action`:
+- **`none`** — a standalone feature (no epic to check) or the manifest is present on the current branch. Proceed silently. This is the no-op path for standalone features (REQ-COMPAT-01), so standalone behavior is unchanged.
+- **`not-resolved`** — the feature does not resolve on the current branch. Proceed silently (the caller's own resolution already handled that case).
+- **`warn-detached-base`** — a nested member resolves here but the epic's `epic-manifest.json` is **absent on this branch**. **STOP** unless `--force` was passed, and surface verbatim (filling `{epic}` and `{homeBranch}` from the payload's `epic` and `homeBranch`):
+  > `{feature}` is a member of epic `{epic}`, but this branch does not contain the epic manifest (`{specsDir}/{epic}/epic-manifest.json`). This base predates or lacks the epic. Switch to the epic's home branch `{homeBranch}` and re-run, or pass `--force` to author against a detached base anyway.
+
+  With `--force`, log a one-line warning ("Authoring `{feature}` against a detached epic base — manifest not on this branch") and proceed, consistent with the other guards.
+
+If the helper is unavailable (a non-Claude host without the resolver), skip this block — it is best-effort defense in depth, not a hard prerequisite.
+
 ## Pipeline State Protocol
 
 Write pipeline state conforming to `references/pipeline-state-schema.json`. Always update `updatedAt` when modifying pipeline state.

package/adapters/claude/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
@@ -1195,6 +1196,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)
 # --------------------------------------------------------------------------- #
@@ -1285,6 +1460,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 +1552,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/claude/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/claude/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/claude/scripts/forge-session.py

@@ -11,6 +11,8 @@ root navigator:
     python3 forge-session.py discover-feature [NAME | --all] [--specs-dir DIR] [--json]
     python3 forge-session.py reconcile-branch --feature F [--specs-dir DIR] \
         [--config FILE] [--epic E] [--json]
+    python3 forge-session.py check-epic-base --feature F [--specs-dir DIR] \
+        [--config FILE] [--epic E] [--json]
     python3 forge-session.py stage-exit --feature F --stage S [--specs-dir DIR] \
         [--config FILE] [--epic E] [--next-feature N] [--host claude|generic] [--json]
 
@@ -45,7 +47,17 @@ concluding it was never started. When nothing is found locally it also asks
 `git ls-remote --heads origin` about branches a single-branch clone never
 fetched, and emits the exact `git fetch`/`git switch` commands a caller could
 run. It is strictly read-only — it never checks anything out itself — and
-like `doctor` it always exits 0 and degrades to data.
+like `doctor` it always exits 0 and degrades to data. Each candidate also
+carries `epic`/`isEpicMember`, so a caller minting a new standalone feature can
+refuse when the name is a known epic member discoverable on another branch
+(the split-brain-epic guard, Issue #125).
+
+`check-epic-base` is the defense-in-depth companion: given a feature that
+resolves to a nested epic member on the current branch, it confirms the epic's
+`epic-manifest.json` is actually present on HEAD. When it is absent, the member
+was reached from a branch that predates or lacks the manifest commit (a detached
+base) and the command emits `warn-detached-base` with the member's recorded home
+branch. Read-only; always exits 0.
 
 `stage-exit` computes everything an authoring stage's closing used to derive
 in prose (the Scripted Stage Exit, `references/stage-exit-protocol.md`):
@@ -848,6 +860,26 @@ def _read_state_at_ref(ref: str, path: str) -> dict:
     return parsed if isinstance(parsed, dict) else {}
 
 
+def _epic_membership(path: str, specs_rel: str, state: dict) -> tuple[str | None, bool]:
+    """Derive ``(epic, isEpicMember)`` for a discovered candidate.
+
+    A candidate is an epic member when its state carries an ``epic`` back-pointer
+    **or** its path is nested (``{specsDir}/{epic}/{name}/.pipeline-state.json``).
+    Nested-ness is structurally authoritative; the ``epic`` field is the recorded
+    back-pointer. When the state lacks the field, the nested directory name is used
+    so the signal is never "member of epic None".
+    """
+    prefix = specs_rel + "/"
+    nested_epic: str | None = None
+    if path.startswith(prefix):
+        segments = path[len(prefix):].split("/")
+        if len(segments) == 3:  # [epic, name, state-file]
+            nested_epic = segments[0]
+    epic = state.get("epic")
+    epic = epic if isinstance(epic, str) and epic else nested_epic
+    return epic, bool(nested_epic) or bool(epic)
+
+
 def _list_refs(pattern: str) -> list[tuple[str, str]]:
     """Return ``(short_ref, committer_date)`` pairs under a ref namespace."""
     raw = _git_output([
@@ -908,6 +940,7 @@ def discover_feature(name: str, specs_dir: str) -> dict:
             state_branch = state.get("branch")
             state_branch = state_branch if isinstance(state_branch, str) else None
             updated = state.get("updatedAt")
+            epic, is_epic_member = _epic_membership(path, specs_rel, state)
             matched_branches.add(branch)
             candidates.append({
                 "branch": branch,
@@ -918,6 +951,8 @@ def discover_feature(name: str, specs_dir: str) -> dict:
                 "stateBranchMatches": state_branch == branch,
                 "currentStage": state.get("currentStage"),
                 "pipelineStatus": state.get("pipelineStatus", "active"),
+                "epic": epic,
+                "isEpicMember": is_epic_member,
                 "updatedAt": updated if isinstance(updated, str) else None,
                 "commitDate": commit_date or None,
                 "isCurrentBranch": branch == current_branch,
@@ -988,6 +1023,8 @@ def _print_discover(payload: dict) -> None:
             marks.append("remote-tracking")
         if not cand["stateBranchMatches"] and cand["stateBranch"]:
             marks.append(f"state records branch {cand['stateBranch']}")
+        if cand.get("isEpicMember"):
+            marks.append(f"member of epic {cand.get('epic') or '?'}")
         suffix = f"  ({'; '.join(marks)})" if marks else ""
         print(
             f"  {cand['branch']}: stage={cand['currentStage'] or '?'} "
@@ -1054,6 +1091,7 @@ def discover_all(specs_dir: str) -> dict:
             state = _read_state_at_ref(ref, path)
             state_branch = state.get("branch")
             state_branch = state_branch if isinstance(state_branch, str) else None
+            epic, is_epic_member = _epic_membership(path, specs_rel, state)
             seen.append({
                 "branch": branch,
                 "remoteTracking": is_remote,
@@ -1062,6 +1100,8 @@ def discover_all(specs_dir: str) -> dict:
                 "stateBranchMatches": state_branch == branch,
                 "currentStage": state.get("currentStage"),
                 "pipelineStatus": state.get("pipelineStatus", "active"),
+                "epic": epic,
+                "isEpicMember": is_epic_member,
                 "commitDate": commit_date or None,
                 "isCurrentBranch": branch == current_branch,
                 "switchCommand": f"git switch {branch}",
@@ -1097,6 +1137,8 @@ def _print_discover_all(payload: dict) -> None:
                 marks.append("remote-tracking")
             if not cand["stateBranchMatches"] and cand["stateBranch"]:
                 marks.append(f"state records branch {cand['stateBranch']}")
+            if cand.get("isEpicMember"):
+                marks.append(f"member of epic {cand.get('epic') or '?'}")
             suffix = f"  ({'; '.join(marks)})" if marks else ""
             print(f"  {cand['branch']}: stage={cand['currentStage'] or '?'} "
                   f"status={cand['pipelineStatus']}{suffix}")
@@ -1191,6 +1233,77 @@ def _print_reconcile(payload: dict) -> None:
         print(f"  → write state branch := {payload['newBranch']}  ({payload['statePath']})")
 
 
+# --------------------------------------------------------------------------- #
+# Epic-member base guard (Issue #125) — detached-base detection
+# --------------------------------------------------------------------------- #
+
+
+def check_epic_base(
+    name: str, specs_dir: Path, config_path: Path, epic: str | None = None
+) -> dict:
+    """Verify the current HEAD actually contains the epic manifest for a nested member.
+
+    Defense-in-depth for the split-brain-epic failure (Issue #125): when a feature
+    resolves to a nested epic-member directory but the epic's ``epic-manifest.json``
+    is absent from the current checkout, the member stub was reached from a branch
+    that predates (or otherwise lacks) the manifest commit — a detached base. This
+    is read-only: it emits a decision; the caller stops or warns.
+
+    Actions:
+    - ``none`` — not a git repo, a standalone feature (no epic to check), or the
+      manifest is present on HEAD. Nothing to do.
+    - ``not-resolved`` — the feature does not resolve on the current branch.
+    - ``warn-detached-base`` — nested member resolves here but the manifest is
+      missing on HEAD; ``homeBranch`` is the member stub's recorded ``branch``.
+    """
+    base = {
+        "feature": name,
+        "gitRepo": True,
+        "epic": epic,
+        "isEpicMember": False,
+        "manifestOnHead": None,
+        "homeBranch": None,
+    }
+    if _git_output(["rev-parse", "--git-dir"]) is None:
+        return {**base, "gitRepo": False, "action": "none",
+                "reason": "not a git repository"}
+    config = _load_config(config_path)
+    row = next(
+        (r for r in build_rows(specs_dir, config)
+         if r["name"] == name and (epic is None or r["epic"] == epic)),
+        None,
+    )
+    if row is None:
+        return {**base, "action": "not-resolved",
+                "reason": "feature state does not resolve on the current branch — "
+                          "use discover-feature to locate it"}
+    member_epic = row["epic"]
+    if not member_epic:
+        return {**base, "action": "none",
+                "reason": "standalone feature — no epic base to check"}
+    base = {**base, "epic": member_epic, "isEpicMember": True,
+            "homeBranch": row["branch"]}
+    manifest = specs_dir / member_epic / MANIFEST_FILENAME
+    if manifest.is_file():
+        return {**base, "manifestOnHead": True, "action": "none",
+                "reason": f"epic manifest present on the current branch "
+                          f"({member_epic}/{MANIFEST_FILENAME})"}
+    return {**base, "manifestOnHead": False, "action": "warn-detached-base",
+            "reason": f"member of epic {member_epic!r} resolves here, but "
+                      f"{member_epic}/{MANIFEST_FILENAME} is absent on the current "
+                      f"branch — this base predates or lacks the epic manifest"}
+
+
+def _print_check_epic_base(payload: dict) -> None:
+    """Human-readable check-epic-base report."""
+    if not payload["gitRepo"]:
+        print(f"check-epic-base {payload['feature']}: not a git repository")
+        return
+    print(f"check-epic-base {payload['feature']}: {payload['action']} — {payload['reason']}")
+    if payload["action"] == "warn-detached-base":
+        print(f"  → switch to the epic's home branch: {payload['homeBranch'] or '(unknown)'}")
+
+
 # --------------------------------------------------------------------------- #
 # Scripted Stage Exit
 # --------------------------------------------------------------------------- #
@@ -1587,6 +1700,16 @@ def main() -> int:
     p_recon.add_argument("--epic", default=None, help="Epic name for a nested member")
     p_recon.add_argument("--json", action="store_true", dest="json_output")
 
+    p_base = sub.add_parser(
+        "check-epic-base",
+        help="Verify HEAD contains the epic manifest for a resolved nested member",
+    )
+    p_base.add_argument("--feature", required=True, help="Feature name")
+    p_base.add_argument("--specs-dir", default="./specs", help="Specs directory")
+    p_base.add_argument("--config", default="./forge.config.json", help="forge.config.json path")
+    p_base.add_argument("--epic", default=None, help="Epic name for a nested member")
+    p_base.add_argument("--json", action="store_true", dest="json_output")
+
     p_exit = sub.add_parser(
         "stage-exit", help="Emit the Scripted Stage Exit directives + NEXT-STEPS block"
     )
@@ -1667,6 +1790,16 @@ def main() -> int:
                 _print_reconcile(payload)
             return 0
 
+        if args.cmd == "check-epic-base":
+            payload = check_epic_base(
+                args.feature, Path(args.specs_dir), Path(args.config), args.epic
+            )
+            if args.json_output:
+                print(json.dumps(payload, indent=2, ensure_ascii=False))
+            else:
+                _print_check_epic_base(payload)
+            return 0
+
         if args.cmd == "stage-exit":
             payload = stage_exit(
                 args.feature,

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

@@ -89,7 +89,17 @@ 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` 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 `AskUserQuestion`: *"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