@garygentry/feature-forge 0.2.12 → 0.2.14

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.7",
+  "version": "0.12.9",
   "agent": "claude",
   "generatedBy": "python3 scripts/build-adapters.py"
 }

package/adapters/claude/references/epic-manifest-schema.json

@@ -74,6 +74,11 @@
           "type": "array",
           "items": { "$ref": "#/definitions/consumedContract" },
           "description": "What this feature relies on from its dependencies (REQ-EPIC-03). May be empty."
+        },
+        "mutatesShared": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "OPTIONAL precision hint for cross-member coupling detection (#144): project-root-relative file/glob paths this feature writes or migrates that are shared across the epic (e.g. a corpus a sibling's tests pin). When present, forge-verify CHECK-E10 uses it directly; when absent, CHECK-E10 falls back to grepping specs/backlog for mutated paths. Not a dependency edge — declarative only. May be omitted entirely."
         }
       }
     },

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

@@ -274,6 +274,18 @@ This write is **left uncommitted**: it is staged and committed as part of this s
 
 **Incremental artifact tracking:** When a stage writes multiple files (e.g. forge-3-specs writing a suite of spec documents), update the `stages.{stage}.artifacts` array in `.pipeline-state.json` after writing each file — not just at stage completion. This is what makes the Interrupted inventory above precise about which files were successfully written.
 
+## Stage-Completion Re-check
+
+Invoke this block **at the head of any post-entry step that writes a stage artifact or runs the Scripted Stage Exit** — the Stage-Entry Guard runs only once, at the top of the skill. A **resumed or pasted mid-stage instruction** (e.g. "continue {stage}: write TRACEABILITY.md, run the stage exit") enters *below* the entry guard, so nothing re-checks completion before it overwrites a committed artifact and re-fires a finished exit — data-destructive if followed literally. This re-check is the idempotency backstop for that path. `{stage}` is the invoking skill's id.
+
+**Re-read** `stages.{stage}` in `{resolvedFeatureDir}/.pipeline-state.json`, then classify by **provenance** — a legitimate completion runs in the same session that applied this stage's Entry Stamp; a replayed continuation finds a finished stage it did not produce:
+
+1. **Proceed** when `stages.{stage}.status` is `"in-progress"` (this session's Entry Stamp — you are finishing the run you started) or absent/`pending`. Run the write / exit normally.
+
+2. **Detect-and-refuse** when ALL of these hold: `stages.{stage}.status ∈ {"complete", "stale"}` **AND** the stage's artifacts (incl. `TRACEABILITY.md` for forge-3-specs) exist on disk **AND** a `commitHash` is recorded for the stage **AND** you did **not** author this stage earlier in the current session. This is a stale/replayed continuation of an already-finished, committed stage. Do **not** overwrite the artifact or re-run the exit. Route instead to the **Stage-Entry Guard**'s *Re-authoring* path: surface the same `AskUserQuestion` warning ("A completed {stage} artifact already exists for '{feature}' (v{n}{, marked stale}). Continuing will create a new version. Proceed?"). Only on explicit confirmation re-enter from the Entry Stamp (the version bumps at exit); otherwise **stop** and report that the stage is already complete — cite the recorded `commitHash` and offer `/feature-forge:forge {feature}` to see true state.
+
+When you cannot confirm you authored the current run, treat it as a replay and refuse: a false refuse costs one confirmation click; a false proceed overwrites a committed artifact and re-churns a stage version. `--force` follows Force Mode (skip the gate, treat as a deliberate re-author).
+
 ## Force Mode
 
 If the user passes `--force` as an argument, skip prerequisite validation with a warning:

package/adapters/claude/references/stacks/_generic.md

@@ -79,6 +79,27 @@ Replace stack-specific checks with these generic equivalents:
 | "JSDoc on every field" | "Documentation comments on every field" |
 | "tsconfig.json extends root" | "Build configuration follows project conventions" |
 
+### Runtime Entrypoints & Bootstrap-Wiring Sites
+
+Used by `CHECK-I22` (a runtime-required bootstrap needs a **non-test** caller on one of these) and
+`CHECK-I23` (a heavy init wired into a **universal** bootstrap entry should move to a lazier site).
+Since no dedicated profile applies, identify these by role rather than exact filename:
+
+- **Runtime entrypoints (a legitimate non-test call site):** the process/main entry the build's
+  run command actually launches (from the CI/`Makefile`/manifest "start" target), an HTTP/RPC handler
+  or route, a scheduled/worker task, or a CLI subcommand — **not** a file in the project's test
+  directory or matching its test-file convention.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** any
+  module/hook the framework runs **once per process before serving** — a startup/lifecycle hook, an
+  import-time initializer, a global preload, or a shared test-setup module that bootstraps production
+  graphs. Side effects here run on every process start (and, under a dev/watch runtime, on every
+  reload).
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** database/ORM
+  clients and connection pools, message/queue clients, telemetry/observability SDKs, or a broad
+  whole-service-layer import. An init pulling any of these into a universal bootstrap entry is the
+  CHECK-I23 pattern — recommend lazy initialization at the first handler/worker that needs the graph,
+  not eagerly at process start.
+
 ## Acceptance Criteria Patterns
 
 Use these placeholder patterns in backlog items. Replace `{typeCheckCommand}`, `{testCommand}`, and `{module}` with values from `forge.config.json` and the project structure:

package/adapters/claude/references/stacks/go.md

@@ -84,6 +84,25 @@ When examining a Go project, check for:
 - **Formatting**: `gofmt -l .` or `goimports -l .` (should produce no output)
 - **Module tidiness**: `go mod tidy` (ensures `go.mod` and `go.sum` are consistent)
 
+### Runtime Entrypoints & Bootstrap-Wiring Sites
+
+Used by `CHECK-I22` (a runtime-required bootstrap needs a **non-test** caller on one of these) and
+`CHECK-I23` (a heavy init wired into a **universal** bootstrap entry should move to a lazier site).
+
+- **Runtime entrypoints (a legitimate non-test call site):** `func main()` in a `package main` under
+  `cmd/…` or the module root, an HTTP handler registered on a `*http.ServeMux` / router, a gRPC service
+  registration, or a worker/consumer goroutine started from `main` — not a `*_test.go` file.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** a package-level
+  `func init()` that constructs heavy clients, package-level `var` initializers that dial/connect at
+  import time, or a single `bootstrap`/`wire` module `main` calls before serving. `init()` and
+  package-var side effects run on **every** binary start, before `main` gets control.
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** DB drivers/pools
+  (`database/sql` + a driver, `pgx`, `gorm`, `mongo-driver`), message/queue clients (`sarama`/Kafka,
+  `amqp`, `go-redis`), telemetry SDKs (`go.opentelemetry.io/*`, `sentry-go`), or a broad internal
+  service package. An `init()` or package-var that dials any of these is the CHECK-I23 pattern —
+  recommend a `sync.Once` lazy constructor invoked from the first handler that needs it, not an
+  eager package-level connect.
+
 ## Testing
 
 - **Framework**: `testing` stdlib package

package/adapters/claude/references/stacks/python.md

@@ -111,6 +111,27 @@ async def refresh_session_token(
 - **Import validation**: `mypy` with `--strict` or `--disallow-untyped-defs` catches missing type annotations
 - **Module export validation**: `__all__` lists in `__init__.py` match spec's public API
 
+### Runtime Entrypoints & Bootstrap-Wiring Sites
+
+Used by `CHECK-I22` (a runtime-required bootstrap needs a **non-test** caller on one of these) and
+`CHECK-I23` (a heavy init wired into a **universal** bootstrap entry should move to a lazier site).
+
+- **Runtime entrypoints (a legitimate non-test call site):** a `if __name__ == "__main__":` block, a
+  `[project.scripts]` console-script target in `pyproject.toml`, an ASGI/WSGI app object
+  (`app = FastAPI()` / Django `wsgi.py` / `asgi.py`), a route/view/handler, a Celery/RQ task module, or
+  a management command — not a `test_*.py` / `conftest.py`.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** a package
+  `__init__.py` that eagerly instantiates heavy clients at import time, a framework startup hook
+  (FastAPI `lifespan` / `@app.on_event("startup")`, Django `AppConfig.ready()`, a Gunicorn/uvicorn
+  `--preload` module), or a `conftest.py` that bootstraps production graphs. Import-time side effects
+  here run on every process start.
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** DB/ORM engines
+  (`sqlalchemy.create_engine`, `psycopg`, Django ORM, `pymongo`, `redis`), task queues (`celery`,
+  `rq`, `kafka`), telemetry SDKs (`opentelemetry`, `sentry_sdk`), or a whole-service-layer package
+  import. An init pulling any of these at a universal entry is the CHECK-I23 pattern — recommend lazy
+  init (module-level `@lru_cache` factory, `Depends()` provider, or first-use lazy import) at the
+  handler that needs it.
+
 ## Testing
 
 - **Framework**: pytest (with `conftest.py` for fixtures)

package/adapters/claude/references/stacks/rust.md

@@ -90,6 +90,25 @@ When examining a Rust project, check for:
 - **Formatting**: `cargo fmt --check` (ensures code matches `rustfmt` style)
 - **Unsafe audit**: `cargo geiger` (if security-sensitive — counts unsafe blocks)
 
+### Runtime Entrypoints & Bootstrap-Wiring Sites
+
+Used by `CHECK-I22` (a runtime-required bootstrap needs a **non-test** caller on one of these) and
+`CHECK-I23` (a heavy init wired into a **universal** bootstrap entry should move to a lazier site).
+
+- **Runtime entrypoints (a legitimate non-test call site):** `fn main()` in `main.rs` or a `[[bin]]`
+  target, an async runtime entry (`#[tokio::main]`), an HTTP handler registered on an axum/actix/warp
+  router, or a worker task spawned from `main` — not a `#[cfg(test)]` module or a `tests/` integration
+  file.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** a `lazy_static!`
+  / `once_cell::sync::Lazy` static that eagerly constructs heavy clients, a single `bootstrap`/`setup`
+  fn `main` calls before serving, or a `#[ctor]`-style pre-`main` initializer. A `Lazy` static is only
+  a risk when it is *forced* at startup rather than on first use.
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** DB pools
+  (`sqlx::Pool`, `diesel`, `deadpool`, `mongodb`), message/queue clients (`rdkafka`, `lapin`,
+  `redis`), telemetry SDKs (`opentelemetry`, `sentry`), or a broad internal service crate. Constructing
+  any of these eagerly at a universal entry is the CHECK-I23 pattern — recommend a `OnceCell`/`Lazy`
+  forced on **first use** by the handler that needs it, not at process start.
+
 ## Testing
 
 - **Framework**: Built-in test harness (`#[test]`, `#[cfg(test)]`)

package/adapters/claude/references/stacks/typescript.md

@@ -64,6 +64,29 @@ When examining a TypeScript project, check for:
 - **Cross-package type checks**: `bun run typecheck` (or equivalent) passes for both the feature package AND packages that depend on it
 - **Import path validation**: All import paths resolve correctly per the `exports` map in `package.json`
 
+### Runtime Entrypoints & Bootstrap-Wiring Sites
+
+Used by `CHECK-I22` (a runtime-required bootstrap needs a **non-test** caller on one of these) and
+`CHECK-I23` (a heavy init wired into a **universal** bootstrap entry should move to a lazier site).
+
+- **Runtime entrypoints (a legitimate non-test call site):** a `package.json` `bin` / CLI `main`; a
+  server entry that actually starts listening (`src/server.ts`, `src/index.ts` invoking `listen`); a
+  worker/consumer file; and for Next.js — `middleware.ts`, `app/**/route.ts` route handlers,
+  `app/**/{page,layout,template}.tsx`, server actions, and `instrumentation.ts`. Express/Hono/Fastify:
+  the file that constructs the app and calls `.listen()`.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** Next.js
+  `instrumentation.ts` / `instrumentation.js` (its `register()` runs once per server process before
+  any request), an app-server preload/`register`/`--import` hook, a root `app/layout.tsx` that
+  eagerly imports server singletons, and global test setup (`vitest.setup.ts`, `jest.setup.ts`) if it
+  bootstraps production graphs. Wiring a heavy init here loads it on **every** cold start (and, under
+  the dev server, on every module re-evaluation).
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** DB/ORM clients
+  (`drizzle-orm`, `@prisma/client`, `pg`, `mongoose`, `kysely`), queue/worker libs (`bullmq`, `bull`,
+  `kafkajs`, `ioredis`), telemetry/observability SDKs (`@opentelemetry/*`, `@sentry/node`), and a
+  whole-service-layer barrel (`import * as services from "@repo/services"`). An init that pulls any of
+  these into a universal bootstrap entry is the CHECK-I23 pattern — recommend lazy init at the first
+  route/handler/worker that needs it.
+
 ## Testing
 
 - **Framework**: Vitest (most common in modern TS), Jest, or testing-library

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
@@ -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/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)"