@garygentry/feature-forge 0.2.11 → 0.2.12

package/adapters/codex/skills/forge-1-prd/SKILL.md

@@ -12,12 +12,30 @@ Create a thorough, requirements-only PRD through relentless structured interview
 
 Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
 
+**`--force-standalone` (forge-1-prd only).** A distinct flag from `--force`: it bypasses only the **Mint Guard** in Step 1 (letting you intentionally fork a name that is a known epic member into a detached standalone feature). It does **not** imply `--force` — prerequisite checks and the Stage-Entry Guard still run. Use it only when you genuinely mean to create a standalone feature that shares a name with an epic member on another branch.
+
 ## Step 1: Read Configuration and Check State
 
 ### Branch Setup (if using git)
 Invoke the **Branch Setup** block in `references/shared-conventions.md` with `{label}` = `{feature}` and `{scope}` = `feature`. It self-gates (skips when not a git repo, when `branchPerFeature` is false, or for an epic member that inherits the epic's branch), detects whether you're on the default branch, and strongly recommends — still optionally — creating `{branchPrefix}{feature}` when you are. Do this before directory resolution.
 
-Set the working directory by invoking the **Feature Directory Resolution** block in `references/shared-conventions.md`, which yields `{resolvedFeatureDir}`. Note one PRD-specific caveat: at PRD time a brand-new standalone feature may have NO directory yet, so resolution is expected to fail `not-found` for a never-started standalone feature — in that case forge-1 creates `{specsDir}/{feature}/` as today. For an epic member the directory already exists (created empty by forge-0-epic with an `epic` back-pointer), so resolution succeeds and yields the nested path.
+Set the working directory by invoking the **Feature Directory Resolution** block in `references/shared-conventions.md`, which yields `{resolvedFeatureDir}`. Note one PRD-specific caveat: at PRD time a brand-new standalone feature may have NO directory yet, so resolution is expected to fail for a never-started standalone feature — as `not-found` (exit 1) when `{specsDir}/` already exists (other features present), or as `specs dir not found` (exit 2) when `{specsDir}/` itself does not exist yet (the very first feature, or a branch that never had a specs tree). In **both** of those "about to create a brand-new standalone" cases forge-1 creates `{specsDir}/{feature}/` as today. (The *other* exit-2 errors — `unsafe-name`, a path-containment escape — are genuine STOPs, never a mint.) For an epic member the directory already exists (created empty by forge-0-epic with an `epic` back-pointer), so resolution succeeds and yields the nested path.
+
+### Mint Guard: refuse to fork a known epic member into a detached standalone (Issue #125)
+
+Run this sub-step **whenever forge-1 is about to mint a brand-new flat standalone `{specsDir}/{feature}/`** — that is, when Feature Directory Resolution returned either `not-found` (exit 1) **or** `specs dir not found` (the exit-2 missing-specs-dir flavor, e.g. a clean default branch that has never had a specs tree). The exit-2 case is the *cleanest* split-brain trigger: on a branch that predates the epic, `{specsDir}/` may not exist at all, yet cross-branch discovery still sees the member on the epic branch. It prevents the split-brain-epic failure where a member of an epic (whose manifest lives on a *different, unmerged* branch) is silently forged as a disjoint standalone feature carrying no `epic` back-pointer. Skip it entirely when resolution succeeded (an epic member's directory already exists — resolution yields the nested path, so this never fires), on the other exit-2 errors (`unsafe-name` / path-containment — those STOP, they never mint), and when `--force-standalone` was passed (see below).
+
+1. Run cross-branch discovery for this exact name (branch-agnostic — it scans all refs regardless of current HEAD):
+   ```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')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" discover-feature "{feature}" --specs-dir "{specsDir}" --json
+   ```
+2. **If any candidate has `isEpicMember: true` → HARD STOP.** This is not the soft switch/fetch/treat-as-new menu from the Feature Directory Resolution block — do **not** create any directory and do **not** fall through to the interview. Emit verbatim (filling `{epic}` and `{stateBranch}` from that candidate's `epic` and `stateBranch`):
+   > `{feature}` is a member of epic `{epic}` (recorded on branch `{stateBranch}`). You appear to be on a branch that does not contain that epic. Switch to `{stateBranch}` and run `/feature-forge:forge-1-prd {feature}` there, or pass `--force-standalone` to intentionally fork a detached standalone feature.
+3. **If candidates exist but none are epic members** → keep today's soft behavior: this is the ordinary cross-branch-discovery case already handled by the Feature Directory Resolution block's **Candidates found** menu (switch / fetch+switch / treat-as-new / stop). Defer to it.
+4. **If nothing was found** (no candidates) → proceed to mint the flat standalone feature as today.
+5. **If `--force-standalone` was passed** → skip this guard entirely, log a one-line warning ("Forking `{feature}` as a detached standalone despite epic membership on `{stateBranch}`"), and proceed to create the flat feature. `--force-standalone` is distinct from `--force` and does **not** imply it (see the Force Mode note below).
 
 After resolution, invoke the **Stage-Entry Guard** block in `references/shared-conventions.md` with `{stage}` = `forge-1-prd`. It classifies re-entry (fresh / interrupted / re-authoring), runs the resume-vs-restart gate and the "create a new version?" warning as applicable, and applies the entry stamp on the authoring paths. For a brand-new standalone feature there is no state file yet, so the guard's **fresh** arm applies with nothing to prompt; the entry stamp lands when the state file is first created in Step 6.
 

package/adapters/codex/skills/forge-4-backlog/SKILL.md

@@ -40,6 +40,8 @@ Resolve the **loop runner** from the `loopRunner` block in `forge.config.json`,
 
 After the prerequisite check, invoke the **Stage-Entry Guard** block in `references/shared-conventions.md` with `{stage}` = `forge-4-backlog` — it detects an interrupted or complete `backlog.json`, runs the resume/restart or new-version gate, and stamps entry before Step 2 loads the specs. (The backlog is a single artifact, so "resume" means: reuse the existing `backlog.json` if the previous run wrote it, rather than re-authoring from scratch.)
 
+Then invoke the **Epic-Member Base Guard** block in `references/shared-conventions.md` (this stage does not run Epic Context Injection, so invoke it explicitly here). It self-gates to a no-op for standalone features; for a nested epic member on a branch that lacks the epic manifest it stops with a home-branch pointer (Issue #125).
+
 **Verification check.** Check whether the specs have been verified. If not, use the host's question mechanism to warn with the cost of skipping: "Specs haven't been verified yet. Recommended: run `/feature-forge:forge-verify {feature}` first — unverified specs can carry gaps or contradictions that get baked into backlog items and only surface mid-loop, where they're far more expensive to fix. Continue anyway?" Offer **Verify first (recommended)** · **Continue without verifying**.
 
 ## Step 2: Load All Specs

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

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

package/adapters/copilot/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/copilot/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/copilot/skills/forge/forge.md

@@ -90,6 +90,8 @@ After rendering a **per-feature** dashboard for an **active** pipeline (skip thi
 
 **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").
 
+**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.
+
 **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')"

package/adapters/copilot/skills/forge-1-prd/forge-1-prd.md

@@ -12,12 +12,30 @@ Create a thorough, requirements-only PRD through relentless structured interview
 
 Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
 
+**`--force-standalone` (forge-1-prd only).** A distinct flag from `--force`: it bypasses only the **Mint Guard** in Step 1 (letting you intentionally fork a name that is a known epic member into a detached standalone feature). It does **not** imply `--force` — prerequisite checks and the Stage-Entry Guard still run. Use it only when you genuinely mean to create a standalone feature that shares a name with an epic member on another branch.
+
 ## Step 1: Read Configuration and Check State
 
 ### Branch Setup (if using git)
 Invoke the **Branch Setup** block in `references/shared-conventions.md` with `{label}` = `{feature}` and `{scope}` = `feature`. It self-gates (skips when not a git repo, when `branchPerFeature` is false, or for an epic member that inherits the epic's branch), detects whether you're on the default branch, and strongly recommends — still optionally — creating `{branchPrefix}{feature}` when you are. Do this before directory resolution.
 
-Set the working directory by invoking the **Feature Directory Resolution** block in `references/shared-conventions.md`, which yields `{resolvedFeatureDir}`. Note one PRD-specific caveat: at PRD time a brand-new standalone feature may have NO directory yet, so resolution is expected to fail `not-found` for a never-started standalone feature — in that case forge-1 creates `{specsDir}/{feature}/` as today. For an epic member the directory already exists (created empty by forge-0-epic with an `epic` back-pointer), so resolution succeeds and yields the nested path.
+Set the working directory by invoking the **Feature Directory Resolution** block in `references/shared-conventions.md`, which yields `{resolvedFeatureDir}`. Note one PRD-specific caveat: at PRD time a brand-new standalone feature may have NO directory yet, so resolution is expected to fail for a never-started standalone feature — as `not-found` (exit 1) when `{specsDir}/` already exists (other features present), or as `specs dir not found` (exit 2) when `{specsDir}/` itself does not exist yet (the very first feature, or a branch that never had a specs tree). In **both** of those "about to create a brand-new standalone" cases forge-1 creates `{specsDir}/{feature}/` as today. (The *other* exit-2 errors — `unsafe-name`, a path-containment escape — are genuine STOPs, never a mint.) For an epic member the directory already exists (created empty by forge-0-epic with an `epic` back-pointer), so resolution succeeds and yields the nested path.
+
+### Mint Guard: refuse to fork a known epic member into a detached standalone (Issue #125)
+
+Run this sub-step **whenever forge-1 is about to mint a brand-new flat standalone `{specsDir}/{feature}/`** — that is, when Feature Directory Resolution returned either `not-found` (exit 1) **or** `specs dir not found` (the exit-2 missing-specs-dir flavor, e.g. a clean default branch that has never had a specs tree). The exit-2 case is the *cleanest* split-brain trigger: on a branch that predates the epic, `{specsDir}/` may not exist at all, yet cross-branch discovery still sees the member on the epic branch. It prevents the split-brain-epic failure where a member of an epic (whose manifest lives on a *different, unmerged* branch) is silently forged as a disjoint standalone feature carrying no `epic` back-pointer. Skip it entirely when resolution succeeded (an epic member's directory already exists — resolution yields the nested path, so this never fires), on the other exit-2 errors (`unsafe-name` / path-containment — those STOP, they never mint), and when `--force-standalone` was passed (see below).
+
+1. Run cross-branch discovery for this exact name (branch-agnostic — it scans all refs regardless of current HEAD):
+   ```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')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-session.py" discover-feature "{feature}" --specs-dir "{specsDir}" --json
+   ```
+2. **If any candidate has `isEpicMember: true` → HARD STOP.** This is not the soft switch/fetch/treat-as-new menu from the Feature Directory Resolution block — do **not** create any directory and do **not** fall through to the interview. Emit verbatim (filling `{epic}` and `{stateBranch}` from that candidate's `epic` and `stateBranch`):
+   > `{feature}` is a member of epic `{epic}` (recorded on branch `{stateBranch}`). You appear to be on a branch that does not contain that epic. Switch to `{stateBranch}` and run `/feature-forge:forge-1-prd {feature}` there, or pass `--force-standalone` to intentionally fork a detached standalone feature.
+3. **If candidates exist but none are epic members** → keep today's soft behavior: this is the ordinary cross-branch-discovery case already handled by the Feature Directory Resolution block's **Candidates found** menu (switch / fetch+switch / treat-as-new / stop). Defer to it.
+4. **If nothing was found** (no candidates) → proceed to mint the flat standalone feature as today.
+5. **If `--force-standalone` was passed** → skip this guard entirely, log a one-line warning ("Forking `{feature}` as a detached standalone despite epic membership on `{stateBranch}`"), and proceed to create the flat feature. `--force-standalone` is distinct from `--force` and does **not** imply it (see the Force Mode note below).
 
 After resolution, invoke the **Stage-Entry Guard** block in `references/shared-conventions.md` with `{stage}` = `forge-1-prd`. It classifies re-entry (fresh / interrupted / re-authoring), runs the resume-vs-restart gate and the "create a new version?" warning as applicable, and applies the entry stamp on the authoring paths. For a brand-new standalone feature there is no state file yet, so the guard's **fresh** arm applies with nothing to prompt; the entry stamp lands when the state file is first created in Step 6.
 

package/adapters/copilot/skills/forge-4-backlog/forge-4-backlog.md

@@ -40,6 +40,8 @@ Resolve the **loop runner** from the `loopRunner` block in `forge.config.json`,
 
 After the prerequisite check, invoke the **Stage-Entry Guard** block in `references/shared-conventions.md` with `{stage}` = `forge-4-backlog` — it detects an interrupted or complete `backlog.json`, runs the resume/restart or new-version gate, and stamps entry before Step 2 loads the specs. (The backlog is a single artifact, so "resume" means: reuse the existing `backlog.json` if the previous run wrote it, rather than re-authoring from scratch.)
 
+Then invoke the **Epic-Member Base Guard** block in `references/shared-conventions.md` (this stage does not run Epic Context Injection, so invoke it explicitly here). It self-gates to a no-op for standalone features; for a nested epic member on a branch that lacks the epic manifest it stops with a home-branch pointer (Issue #125).
+
 **Verification check.** Check whether the specs have been verified. If not, use the host's question mechanism to warn with the cost of skipping: "Specs haven't been verified yet. Recommended: run `/feature-forge:forge-verify {feature}` first — unverified specs can carry gaps or contradictions that get baked into backlog items and only surface mid-loop, where they're far more expensive to fix. Continue anyway?" Offer **Verify first (recommended)** · **Continue without verifying**.
 
 ## Step 2: Load All Specs

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

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

package/adapters/cursor/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/cursor/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,