@garygentry/feature-forge 0.2.5 → 0.2.7

package/adapters/cursor/skills/forge-init/forge-init.mdc

@@ -10,7 +10,7 @@ alwaysApply: false
 Run the initialization script to create `forge.config.json` with default settings:
 
 ```bash
-R="$(bash -c 'for d in "$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')"
+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; }
 bash "$R/scripts/forge-init.sh"
 ```

package/adapters/cursor/skills/forge-verify/forge-verify.mdc

@@ -9,7 +9,14 @@ alwaysApply: false
 
 Analyze feature artifacts for completeness, consistency, and quality. Produce structured, actionable findings designed for a fresh-context agent to apply.
 
-## Subagent Delegation
+## Which role are you? (read this first)
+
+This skill is loaded in two different roles. Determine yours before proceeding:
+
+- **You ARE the `forge-verifier` subagent** — you were dispatched via the host's subagent mechanism, you have read-only tools (Read, Glob, Grep, Bash) and **no** Agent/host's subagent mechanism, and this skill is pre-loaded in your context. **SKIP "Subagent Delegation (parent orchestrator only)" and "Synthesize" below — those describe how a *parent* dispatches *you*, not work for you to do.** Do **not** dispatch anything, do **not** try to spawn a verifier. Go straight to **Prerequisites → Steps 1–6**, execute the checks yourself, and **return your findings as your response** (the parent writes the document to disk). Dispatching a subagent from here is the classic self-referential loop — never do it.
+- **You are the parent orchestrator** — a navigator (`/feature-forge:forge`), a stage skill's in-stage auto-verify, or a direct `/feature-forge:forge-verify` invocation, and you have the host's subagent mechanism. Use "Subagent Delegation" to dispatch the `forge-verifier` subagent, then "Synthesize" to assemble and write the document.
+
+## Subagent Delegation (parent orchestrator only)
 
 This skill is delegated to the `forge-verifier` subagent via the host's subagent mechanism. The verifier subagent has:
 - **Read-only tools** (Read, Glob, Grep, Bash) — it cannot accidentally modify specs
@@ -249,7 +256,7 @@ Do NOT mark as `findings-applied` — that happens after the fix pass.
 - For specs verification, also run the deterministic traceability validator to supplement agent-driven traceability checks. Include any uncovered requirements or orphaned references as findings:
 
 ```bash
-R="$(bash -c 'for d in "$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')"
+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/validate-traceability.py" {resolvedFeatureDir}/PRD.md {resolvedFeatureDir}/ --json
 ```

package/adapters/cursor/skills/forge-verify/references/verification-checklists.md

@@ -192,7 +192,7 @@ findings to E01/E02/E03/E08. Then perform the judgment checks E04–E07 by readi
 manifest, EPIC.md, and completed members' specs.
 
 ```bash
-R="$(bash -c 'for d in "$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')"
+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/epic-manifest.py" validate "{epic}" --specs-dir "{specsDir}" --json
 ```

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

@@ -1,6 +1,6 @@
 {
   "name": "feature-forge",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "agent": "gemini",
   "generatedBy": "python3 scripts/build-adapters.py"
 }

package/adapters/gemini/agents/forge-verifier.md

@@ -12,6 +12,8 @@ You are the "second set of eyes." You receive artifacts (PRDs, tech specs, imple
 
 You have READ-ONLY access. You cannot and should not modify any files. Your output is returned as your response — the parent agent handles writing the findings document to disk.
 
+**You ARE the verifier — you never dispatch one.** You have no Agent/host's subagent mechanism. Your pre-loaded `forge-verify` skill contains a "Subagent Delegation (parent orchestrator only)" section describing how a *parent* dispatches a `forge-verifier` — that guidance is for the parent, not for you. Ignore it: do not attempt to delegate, spawn a subagent, or return a "verification is running / will surface shortly" placeholder. Execute the verification checks yourself and return the findings block. Delegating from here is a self-referential loop that produces no work and no findings artifact.
+
 ## How You Work
 
 1. Read the pipeline state file to understand what stage the feature is at

package/adapters/gemini/gemini-extension.json

@@ -4,7 +4,7 @@
     "regenerate": "python3 scripts/build-adapters.py"
   },
   "name": "feature-forge",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "skills": [
     {
       "name": "forge-0-epic",

package/adapters/gemini/references/portable-root.md

@@ -12,7 +12,7 @@ against the fenced block here, byte-for-byte.
 ## Canonical bootstrap prelude
 
 ```bash
-R="$(bash -c 'for d in "$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')"
+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; }
 ```
 
@@ -24,25 +24,34 @@ makes several calls, add the prelude once and reuse `$R` for each. A fresh block
 prelude (per-block re-resolution). Worked example:
 
 ```bash
-R="$(bash -c 'for d in "$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')"
+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/epic-manifest.py" render-status "{epic}" --specs-dir "{specsDir}" --json
 ```
 
 ## Invariants (do NOT "fix" these)
 
-1. **Probes paths, not the env var.** The prelude's `for d in …` enumerates directory paths to
-   locate an executable `forge-root.sh`; it contains no plugin-root environment variable. That is what lets
-   a prelude occurrence satisfy the "zero residual var in canonical surfaces" rule while staying
-   portable.
+1. **First hint is the Claude plugin-root env var; the rest are paths.** The prelude's
+   `for d in …` list leads with the `CLAUDE_PLUGIN_ROOT` env var (in default-empty `:-` form)
+   — the exact bundle dir Claude exports in every marketplace/plugin session — followed by the
+   directory-path candidates. The hint gives exact, glob-free resolution on any current/future
+   Claude layout (no version-skew window); when unset it expands to empty and is harmlessly
+   skipped, so other hosts fall through to the path candidates unchanged. This is the **one
+   sanctioned** appearance of that variable in canonical surfaces: spec-purity rule 3 allows it
+   by stripping the byte-pinned prelude before its residual-var scan (so a stray var anywhere
+   else — including the default-empty form — still fails), and `forge-agent-adapters-build`
+   translates it to `FEATURE_FORGE_ROOT` for non-Claude bundles (which `forge-root.sh` already
+   prefers). The exact literal is shown only in the fenced prelude above and audited in
+   `vendor-construct-inventory.md`.
 2. **First-discoverable-resolver-wins.** The `exec` inside the `$(…)` command substitution means
    the loop stops at the first directory holding an executable `forge-root.sh` and delegates ALL
    final root resolution to that script. The `for` list is a discovery order for `forge-root.sh`
    itself, not a fallback chain for the plugin root. Removing the `exec` to "keep looping" is a
    regression — once `exec`'d, the loop is replaced by the resolver process and never advances.
-3. **Prelude candidate set is an agent-neutral bootstrap subset.** The prelude's `for d` list
-   exists only to bootstrap-discover `forge-root.sh`; the authoritative multi-root probe lives in
-   `forge-root.sh` step 2. The list enumerates install roots across agents — the Claude
+3. **Prelude candidate set is an agent-neutral bootstrap subset (after the env hint).** The
+   prelude's `for d` list exists only to bootstrap-discover `forge-root.sh`; the authoritative
+   multi-root probe lives in `forge-root.sh` step 2. After the leading env-var hint (invariant 1),
+   the list enumerates install roots across agents — the Claude
    skill/plugin dirs — including the marketplace-cache layout
    `~/.claude/plugins/cache/<marketplace>/feature-forge/<version>/`, listed before the
    single-star plugins glob so a versioned cache install always beats the marketplace clone —

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

@@ -81,7 +81,7 @@ Extract these config values (use defaults if not present):
 Before any file I/O against a feature's artifacts, resolve its directory through the deterministic helper rather than hardcoding `{specsDir}/{feature}/`. This makes flat (`{specsDir}/{feature}/`) and nested (`{specsDir}/{epic}/{feature}/`) layouts both resolve from a bare feature name (REQ-DIR-03), with standalone features behaving exactly as today.
 
 ```bash
-R="$(bash -c 'for d in "$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')"
+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; }
 resolvedFeatureDir=$(python3 "$R/scripts/epic-manifest.py" \
   resolve "<feature>" --specs-dir "<specsDir>")
@@ -96,7 +96,7 @@ In both failure cases, do not fall back to a guessed path.
 **On `not-found`, check other branches before stopping.** With `branchPerFeature`, the feature's directory (and its `.pipeline-state.json`) may exist only on its topic branch — invisible from the default branch of a fresh clone. Before concluding the pipeline does not exist, run the read-only cross-branch discovery:
 
 ```bash
-R="$(bash -c 'for d in "$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')"
+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" discover-feature "<feature>" --specs-dir "<specsDir>" --json
 ```
@@ -124,7 +124,7 @@ Whenever a stage creates the specs tree for the first time (the first PRD or epi
 Run this after creating the feature/epic directory, before the stage's git commit:
 
 ```bash
-R="$(bash -c 'for d in "$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')"
+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; }
 mkdir -p "<specsDir>"
 [ -f "<specsDir>/AGENTS.md" ] || cp "$R/references/templates/specs-hygiene/AGENTS.md" "<specsDir>/AGENTS.md"
@@ -151,7 +151,7 @@ After resolving the feature directory, check the feature's `.pipeline-state.json
 To obtain the manifest contracts and the live completion status of each dependency in one deterministic call, run `render-status` and read the per-feature `status` and the `consumes`/`exposes` arrays rather than re-deriving them:
 
 ```bash
-R="$(bash -c 'for d in "$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')"
+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/epic-manifest.py" \
   render-status "<epic>" --specs-dir "<specsDir>" --json
@@ -194,6 +194,23 @@ Invoke this block at the **very start** of a pipeline entry point — `forge-1-p
 
 **Record the branch.** After this block resolves, write the resulting branch name to the feature's `.pipeline-state.json` top-level `branch` field (create/update it when the state file is first written for this stage). Downstream stages and `forge-5-loop` read it to detect drift back onto the default branch.
 
+## Branch Reconciliation
+
+The recorded `branch` is a **self-healing hint, not gospel.** A hosted environment (Claude.ai remote, cloud agents) can impose an arbitrary session branch (e.g. `claude/<slug>`) that Branch Setup silently records; the user may then move the work to the intended topic branch, leaving the recorded field stale. Every branch-aware mechanism (the `forge-5-loop` guard, `discover-feature`) keys off that field, so a stale value actively misleads — the loop would offer to switch you *back* to the imposed branch. Invoke this block from `forge-5-loop`'s pre-flight (and any stage that acts on the recorded branch) to reconcile deterministically. 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" reconcile-branch --feature "{feature}" --specs-dir "{specsDir}" --json
+```
+
+Act on the emitted `action` (source of truth is where the state actually resolves, not the recorded field):
+- **`adopt-current`** — you are on a non-default topic branch where the state resolves, and the recorded `branch` differs (a stale/imposed value). Write `newBranch` into the state `branch` field with a **visible one-line note** ("recorded branch was `{stateBranch}`; work is on `{currentBranch}` — updating to match") — never silently, and **never push the user back** to the recorded branch (offer that only as a plain alternative).
+- **`warn-drift`** — you are on the **default** branch and the state records a topic branch. Via `AskUserQuestion`, strongly recommend creating/switching to `{branchPrefix}{feature}` (then record it), still allowing **proceed on the default branch**. Never hard-stop.
+- **`none`** / **`not-resolved`** — nothing to do; proceed.
+
+If the helper is unavailable (non-Claude host without the resolver), fall back to the manual check: current branch differs from recorded → adopt the current branch unless it is the default, in which case recommend creating `{branchPrefix}{feature}`.
+
 ## Git Commit Protocol
 
 When `gitCommitAfterStage` is true, follow this exact order to avoid state inconsistency.

package/adapters/gemini/references/stage-exit-protocol.md

@@ -57,7 +57,7 @@ placeholders the skill resolves before running the command, exactly as elsewhere
 **Close this stage with the Scripted Stage Exit** (contract: `references/stage-exit-protocol.md`; do not improvise a "Next steps" list). Run:
 
 ```bash
-R="$(bash -c 'for d in "$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')"
+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" stage-exit {stage-exit-args} --specs-dir "{specsDir}" --host claude
 ```
@@ -85,12 +85,16 @@ navigator):
 
 1. **Clean-room verify (require-clean).** Dispatch the clean-room `forge-verifier`
    subagent from this session in require-clean mode — the same path the navigator uses
-   (`skills/forge-verify/SKILL.md`). It inherits none of this session's context, so no
-   `/clear` is needed and only a compact digest returns. **Clean-room unavailable** (no
-   `Agent` tool, `forge-verifier` not dispatchable, or a sentinel returned): do **not**
-   run inline — leave verify **pending** so the navigator catch-up fires on a later
-   Claude-host `/feature-forge:forge`, print the `verifyCommand` for the user to run,
-   and continue to the NEXT-STEPS block.
+   (`skills/forge-verify/SKILL.md`). Dispatch it **synchronously and await its digest
+   inline** — do **not** run it in the background or announce it as "still running";
+   the digest and any fix decision must land in this session. It inherits none of this
+   session's context, so no `/clear` is needed and only a compact digest returns.
+   **Clean-room unavailable** (no `Agent` tool, `forge-verifier` not dispatchable) **or
+   a non-answer returned** (the verifier returned a placeholder / "still running" /
+   delegation message instead of a findings block): do **not** run inline and do **not**
+   silently accept the non-answer as a pass — leave verify **pending** so the navigator
+   catch-up fires on a later Claude-host `/feature-forge:forge`, print the
+   `verifyCommand` for the user to run, and continue to the NEXT-STEPS block.
 2. **Verify passed / no findings** → the fresh verify state is recorded by the
    clean-room run; continue to the NEXT-STEPS block.
 3. **Verify found findings** →

package/adapters/gemini/references/vendor-construct-inventory.md

@@ -25,6 +25,7 @@ vocabulary defined in `00-core-definitions.md` §8. No free-form values are perm
 | `argument-hint` (top-level frontmatter key) | 10 `skills/*/SKILL.md` (all skills **except** `forge-init`) | `relocated` | Claude-specific vendor key (constraint C-2). Moved verbatim to `metadata.argument-hint` per REQ-VND-01 (see `02-frontmatter-purity-and-inventory.md` §2). Value byte-identical; `description` untouched. |
 | `${CLAUDE_PLUGIN_ROOT}` — canonical invocations + prose | 23 occurrences across 9 canonical surfaces: `skills/forge-0-epic/SKILL.md` (12), `skills/forge/SKILL.md` (3), `skills/forge-5-loop/SKILL.md` (1), `skills/forge-6-docs/SKILL.md` (1), `skills/forge-init/SKILL.md` (1), `skills/forge-verify/SKILL.md` (1), `skills/forge-verify/references/verification-checklists.md` (1), `references/shared-conventions.md` (2), `agents/forge-verifier.md` (1) | `routed-through-resolver` | Claude-only env var. Routed through the byte-identical bootstrap prelude + `scripts/forge-root.sh` per REQ-RES-03. Mechanics owned by `03-portable-root-resolver.md`; recorded here for audit completeness. |
 | `${CLAUDE_PLUGIN_ROOT}` — sanctioned residual | 1 occurrence in `scripts/forge-root.sh` (env-fallback, REQ-RES-02 step 3) | `preserved-as-spec-allowed` | The single sanctioned residual: the resolver's documented Claude-compat fallback (REQ-RES-03 / REQ-RES-05). Exempt from the residual-var scan (`00-core-definitions.md` §6 `RESIDUAL_VAR_EXEMPT`). |
+| `${CLAUDE_PLUGIN_ROOT:-}` — bootstrap-prelude first-hint (Chunk 2b) | 1 occurrence per prelude across every canonical stamp site (the byte-pinned `BOOTSTRAP_PRELUDE`) | `preserved-as-spec-allowed` | The prelude's first resolver candidate — exact, glob-free root resolution on any Claude layout; expands to empty and is skipped when unset. Rule 3 allows it by stripping the byte-pinned prelude before its scan (detection is by `${CLAUDE_PLUGIN_ROOT` prefix, so the `:-}` default form is not an escape hatch elsewhere). `forge-agent-adapters-build` translates it to `${FEATURE_FORGE_ROOT:-}` in non-Claude bundles. |
 | `${CLAUDE_PLUGIN_ROOT}` — in `hooks/hooks.json` | 1 occurrence in `hooks/hooks.json` | `out-of-canon` | Non-canonical Claude artifact (REQ-VND-04). Not a canonical surface; exempt from the REQ-RES-03 scan. Left in place. |
 | `hooks/hooks.json` SessionStart wiring | 1 file (`hooks/hooks.json`) — Claude `SessionStart` → `bash ${CLAUDE_PLUGIN_ROOT}/scripts/session-check.sh` | `out-of-canon` | Claude-specific plugin hook wiring (REQ-VND-04, decision D3). Preserved + documented so `forge-agent-adapters-build` treats it as a Claude artifact, not portable canon. |
 | (contingency) any other vendor invocation directive | none found in the audit | — | REQ-VND-02 contingency did not fire (see Notes). If one is later surfaced, add a row with `removed` or `out-of-canon` per `02-frontmatter-purity-and-inventory.md` §3. |

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

@@ -8,7 +8,9 @@ root navigator:
     python3 forge-session.py context-usage [--config FILE] [--window N] \
         [--threshold F] [--json]
     python3 forge-session.py doctor [--specs-dir DIR] [--config FILE] [--json]
-    python3 forge-session.py discover-feature NAME [--specs-dir DIR] [--json]
+    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 stage-exit --feature F --stage S [--specs-dir DIR] \
         [--config FILE] [--epic E] [--next-feature N] [--host claude|generic] [--json]
 
@@ -135,6 +137,7 @@ class FeatureRow(TypedDict):
     verifyState: str
     autoVerify: bool
     autoFix: bool
+    verifyGate: str
 
 
 class UsageError(Exception):
@@ -357,6 +360,16 @@ def build_rows(specs_dir: Path, config: dict | None = None) -> list[FeatureRow]:
             "verifyState": vlabel,
             "autoVerify": effective_auto_verify,
             "autoFix": global_auto_fix and effective_auto_verify,
+            # Single resolved verify-gate classification (5b — one exit computation,
+            # mirroring stage-exit's `verifyGate`): the navigator reads this instead of
+            # re-deriving from verifyPending + autoVerify in prose. `auto` = the §2b
+            # catch-up runs it unattended; `standard` = the §3 gate (degrades to
+            # manual-print on a non-Claude host); `none` = nothing outstanding.
+            "verifyGate": (
+                "none" if not verify_pending
+                else "auto" if effective_auto_verify
+                else "standard"
+            ),
         })
     # Sort by updatedAt desc; rows without a parseable timestamp sort last.
     rows.sort(
@@ -659,11 +672,18 @@ def doctor_report(specs_dir: Path, config_path: Path) -> dict:
     # --show-current (not rev-parse HEAD) so an unborn branch (fresh repo,
     # no commits yet) still reports its name instead of failing.
     current_branch = _git_output(["branch", "--show-current"])
+    default_branch = _default_branch()
     rows = build_rows(specs_dir, config)
     features = []
     for row in rows:
         backlog = _backlog_path(config, row["name"], row["epic"], specs_dir)
         state_branch = row["branch"]
+        mismatch = bool(state_branch and current_branch and state_branch != current_branch)
+        # Classify a mismatch: on a topic branch it is adoptable (imposed/session-branch
+        # drift, Chunk 6); on the default branch it is real drift-back, only a warning.
+        branch_reconcile = None
+        if mismatch:
+            branch_reconcile = "warn-drift" if current_branch == default_branch else "adopt-current"
         features.append({
             "name": row["name"],
             "epic": row["epic"],
@@ -676,6 +696,7 @@ def doctor_report(specs_dir: Path, config_path: Path) -> dict:
                 if state_branch and current_branch
                 else None
             ),
+            "branchReconcile": branch_reconcile,
             "backlogPath": str(backlog),
             "backlogExists": backlog.is_file(),
         })
@@ -720,7 +741,12 @@ def _print_doctor(report: dict) -> None:
         label = feat["name"] + (f" [{feat['epic']}]" if feat["epic"] else "")
         branch = feat["stateBranch"] or "?"
         if feat["branchMatchesState"] is False:
-            branch += " (MISMATCH vs current)"
+            if feat.get("branchReconcile") == "adopt-current":
+                branch += " (MISMATCH — reconcile: adopt current branch)"
+            elif feat.get("branchReconcile") == "warn-drift":
+                branch += " (MISMATCH — on default branch; create a topic branch)"
+            else:
+                branch += " (MISMATCH vs current)"
         backlog = "exists" if feat["backlogExists"] else "MISSING"
         print(
             f"  - {label}: stage={feat['currentStage']} "
@@ -937,6 +963,193 @@ def _print_discover(payload: dict) -> None:
         print(f"      switch: {cand['switchCommand']}")
 
 
+def _all_state_paths_in_ref(ref: str, specs_rel: str) -> list[tuple[str, str]]:
+    """Every feature-shaped ``.pipeline-state.json`` in one ref as ``(path, feature)``.
+
+    The ``--all`` counterpart to ``_state_paths_in_ref``: same flat/nested bound
+    (``{specsDir}/{name}/…`` or ``{specsDir}/{epic}/{name}/…``) but for every
+    feature, not one named one.
+    """
+    listing = _git_output(["ls-tree", "-r", "--name-only", ref, "--", specs_rel])
+    if not listing:
+        return []
+    hits: list[tuple[str, str]] = []
+    prefix = specs_rel + "/"
+    for path in listing.splitlines():
+        if not path.startswith(prefix) or not path.endswith("/" + PIPELINE_STATE_FILENAME):
+            continue
+        segments = path[len(prefix):].split("/")
+        if len(segments) == 2:          # [name, state-file] (flat)
+            hits.append((path, segments[0]))
+        elif len(segments) == 3:        # [epic, name, state-file] (nested)
+            hits.append((path, segments[1]))
+    return hits
+
+
+def discover_all(specs_dir: str) -> dict:
+    """Discover EVERY feature's pipeline state across all branches (read-only, Chunk 5c).
+
+    The empty-dashboard counterpart to ``discover-feature <name>``: enumerates every
+    feature-shaped state across local heads + remote-tracking refs and groups the
+    candidates by feature, so a fresh clone / default-branch session can see the whole
+    branch-scattered pipeline set instead of nothing. Never mutates anything.
+    """
+    if _git_output(["rev-parse", "--git-dir"]) is None:
+        return {"gitRepo": False, "currentBranch": None, "features": []}
+    current_branch = _git_output(["branch", "--show-current"])
+    specs_rel = _specs_rel(specs_dir)
+    refs = [(ref, date, False) for ref, date in _list_refs("refs/heads")]
+    refs += [(ref, date, True) for ref, date in _list_refs("refs/remotes")]
+
+    by_feature: dict[str, list[dict]] = {}
+    for ref, commit_date, is_remote in refs:
+        branch = ref.split("/", 1)[1] if is_remote else ref
+        if is_remote and (not branch or branch == "HEAD"):
+            continue
+        for path, feature in _all_state_paths_in_ref(ref, specs_rel):
+            seen = by_feature.setdefault(feature, [])
+            if any(c["branch"] == branch for c in seen):
+                continue  # a local head already yielded this branch's state
+            state = _read_state_at_ref(ref, path)
+            state_branch = state.get("branch")
+            state_branch = state_branch if isinstance(state_branch, str) else None
+            seen.append({
+                "branch": branch,
+                "remoteTracking": is_remote,
+                "path": path,
+                "stateBranch": state_branch,
+                "stateBranchMatches": state_branch == branch,
+                "currentStage": state.get("currentStage"),
+                "pipelineStatus": state.get("pipelineStatus", "active"),
+                "commitDate": commit_date or None,
+                "isCurrentBranch": branch == current_branch,
+                "switchCommand": f"git switch {branch}",
+            })
+
+    def _rank(cand: dict) -> tuple:
+        ts = _parse_ts(cand["commitDate"]) or datetime.min.replace(tzinfo=timezone.utc)
+        return (not cand["stateBranchMatches"], cand["remoteTracking"], -ts.timestamp())
+
+    features = []
+    for feature in sorted(by_feature):
+        cands = sorted(by_feature[feature], key=_rank)
+        features.append({"feature": feature, "candidates": cands})
+    return {"gitRepo": True, "currentBranch": current_branch, "features": features}
+
+
+def _print_discover_all(payload: dict) -> None:
+    """Human-readable ``discover-feature --all`` report."""
+    if not payload["gitRepo"]:
+        print("discover-feature --all: not a git repository — nothing to scan")
+        return
+    if not payload["features"]:
+        print("discover-feature --all: no pipeline state found on any local or "
+              "remote-tracking branch")
+        return
+    for feat in payload["features"]:
+        print(f"{feat['feature']}:")
+        for cand in feat["candidates"]:
+            marks = []
+            if cand["isCurrentBranch"]:
+                marks.append("current branch")
+            if cand["remoteTracking"]:
+                marks.append("remote-tracking")
+            if not cand["stateBranchMatches"] and cand["stateBranch"]:
+                marks.append(f"state records branch {cand['stateBranch']}")
+            suffix = f"  ({'; '.join(marks)})" if marks else ""
+            print(f"  {cand['branch']}: stage={cand['currentStage'] or '?'} "
+                  f"status={cand['pipelineStatus']}{suffix}")
+            if not cand["isCurrentBranch"]:
+                print(f"      switch: {cand['switchCommand']}")
+
+
+# --------------------------------------------------------------------------- #
+# Branch reconciliation (Chunk 6) — imposed/session-branch drift
+# --------------------------------------------------------------------------- #
+
+
+def _default_branch() -> str | None:
+    """The repo's default branch: origin/HEAD target, else `main`/`master` if present."""
+    ref = _git_output(["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"])
+    if ref:
+        return ref.rsplit("/", 1)[-1]
+    for cand in ("main", "master"):
+        if _git_output(["rev-parse", "--verify", "--quiet", f"refs/heads/{cand}"]) is not None:
+            return cand
+    return None
+
+
+def reconcile_branch(
+    name: str, specs_dir: Path, config_path: Path, epic: str | None = None
+) -> dict:
+    """Decide whether a feature's recorded ``branch`` should adopt the current branch.
+
+    Read-only: it emits a decision; the caller performs any state write. A hosted
+    environment (Claude.ai remote, cloud agents) imposes an arbitrary session branch
+    that Branch Setup silently records; when the user moves to the intended branch the
+    recorded ``branch`` goes stale and every branch-aware mechanism keys off it. This
+    reconciler treats *where the state actually resolves* as the source of truth, with a
+    default-branch guardrail so genuine drift-back-to-default is still surfaced, not
+    silently adopted.
+    """
+    if _git_output(["rev-parse", "--git-dir"]) is None:
+        return {"feature": name, "gitRepo": False, "reconcile": False,
+                "action": "none", "reason": "not a git repository"}
+    current = _git_output(["branch", "--show-current"])
+    default = _default_branch()
+    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,
+    )
+    state_path = None
+    if row is not None:
+        parent = specs_dir / row["epic"] / name if row["epic"] else specs_dir / name
+        state_path = str(parent / PIPELINE_STATE_FILENAME)
+    base = {
+        "feature": name,
+        "gitRepo": True,
+        "currentBranch": current,
+        "defaultBranch": default,
+        "stateBranch": row["branch"] if row else None,
+        "resolvesOnCurrentBranch": row is not None,
+        "statePath": state_path,
+        "newBranch": None,
+    }
+    if current is None:
+        return {**base, "reconcile": False, "action": "none",
+                "reason": "no current branch (detached HEAD or unborn branch)"}
+    if row is None:
+        return {**base, "reconcile": False, "action": "not-resolved",
+                "reason": "feature state does not resolve on the current branch — "
+                          "use discover-feature to locate it"}
+    state_branch = base["stateBranch"]
+    if state_branch == current:
+        return {**base, "reconcile": False, "action": "none",
+                "reason": "recorded branch already matches the current branch"}
+    if current == default:
+        return {**base, "reconcile": False, "action": "warn-drift",
+                "reason": f"on the default branch ({default}); recording it would commit "
+                          "here — create/switch to a topic branch instead of reconciling"}
+    detail = (f"recorded branch {state_branch!r} differs from the current topic branch"
+              if state_branch else "no branch recorded")
+    return {**base, "reconcile": True, "action": "adopt-current", "newBranch": current,
+            "reason": f"{detail}; the feature state resolves here, so adopt the current branch"}
+
+
+def _print_reconcile(payload: dict) -> None:
+    """Human-readable reconcile-branch report."""
+    if not payload["gitRepo"]:
+        print(f"reconcile-branch {payload['feature']}: not a git repository")
+        return
+    print(f"reconcile-branch {payload['feature']}: {payload['action']} — {payload['reason']}")
+    print(f"  current={payload['currentBranch']} recorded={payload['stateBranch'] or '(none)'} "
+          f"default={payload['defaultBranch']}")
+    if payload["reconcile"]:
+        print(f"  → write state branch := {payload['newBranch']}  ({payload['statePath']})")
+
+
 # --------------------------------------------------------------------------- #
 # Scripted Stage Exit
 # --------------------------------------------------------------------------- #
@@ -1230,10 +1443,23 @@ def main() -> int:
     p_disc = sub.add_parser(
         "discover-feature", help="Find a feature's pipeline state across all branches"
     )
-    p_disc.add_argument("name", help="Feature name to discover")
+    p_disc.add_argument("name", nargs="?", default=None,
+                        help="Feature name to discover (omit with --all)")
+    p_disc.add_argument("--all", action="store_true", dest="discover_all",
+                        help="Discover every feature across all branches (empty-dashboard)")
     p_disc.add_argument("--specs-dir", default="./specs", help="Specs directory")
     p_disc.add_argument("--json", action="store_true", dest="json_output")
 
+    p_recon = sub.add_parser(
+        "reconcile-branch",
+        help="Decide whether a feature's recorded branch should adopt the current branch",
+    )
+    p_recon.add_argument("--feature", required=True, help="Feature name")
+    p_recon.add_argument("--specs-dir", default="./specs", help="Specs directory")
+    p_recon.add_argument("--config", default="./forge.config.json", help="forge.config.json path")
+    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_exit = sub.add_parser(
         "stage-exit", help="Emit the Scripted Stage Exit directives + NEXT-STEPS block"
     )
@@ -1290,11 +1516,28 @@ def main() -> int:
             return 0
 
         if args.cmd == "discover-feature":
-            payload = discover_feature(args.name, args.specs_dir)
+            if args.discover_all:
+                payload = discover_all(args.specs_dir)
+                printer = _print_discover_all
+            elif args.name:
+                payload = discover_feature(args.name, args.specs_dir)
+                printer = _print_discover
+            else:
+                parser.error("discover-feature requires a NAME or --all")
+            if args.json_output:
+                print(json.dumps(payload, indent=2, ensure_ascii=False))
+            else:
+                printer(payload)
+            return 0
+
+        if args.cmd == "reconcile-branch":
+            payload = reconcile_branch(
+                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_discover(payload)
+                _print_reconcile(payload)
             return 0
 
         if args.cmd == "stage-exit":