@opengsd/gsd-core 1.7.0-rc.2 → 1.7.0-rc.4

package/commands/gsd/map-codebase.md

@@ -9,7 +9,7 @@ allowed-tools:
   - Grep
   - Write
   - Agent
-requires: [config, new-project, plan-phase]
+requires: [config, new-project, plan-phase, onboard]
 ---
 
 <objective>
@@ -42,7 +42,7 @@ Parse the first token of $ARGUMENTS:
 Check for .planning/STATE.md - loads context if project already initialized
 
 **This command can run:**
-- Before /gsd:new-project (brownfield codebases) - creates codebase map first
+- Via /gsd:onboard for first-time brownfield setup - creates codebase map first
 - After /gsd:new-project (greenfield codebases) - updates codebase map as code evolves
 - Anytime to refresh codebase understanding
 </context>
@@ -51,7 +51,7 @@ Check for .planning/STATE.md - loads context if project already initialized
 **Use map-codebase for:**
 - Brownfield projects before initialization (understand existing code first)
 - Refreshing codebase map after significant changes
-- Onboarding to an unfamiliar codebase
+- Refreshing or deepening an onboarded codebase map
 - Before major refactoring (understand current state)
 - When STATE.md references outdated codebase info
 
@@ -71,7 +71,7 @@ Check for .planning/STATE.md - loads context if project already initialized
 4. Wait for agents to complete, collect confirmations (NOT document contents)
 5. Verify all 7 documents exist with line counts
 6. Commit codebase map
-7. Offer next steps (typically: /gsd:new-project or /gsd:plan-phase)
+7. Offer next steps (typically: /gsd:onboard, /gsd:new-project, or /gsd:plan-phase)
 </process>
 
 <success_criteria>

package/commands/gsd/mempalace-capture.md

@@ -56,7 +56,7 @@ On any error or timeout, stop and let the phase continue -- capture is best-effo
 
 1. **Dedup first.** Interactive: `mempalace_check_duplicate` on the artifact's deterministic drawer id. Headless: rely on `mempalace mine`'s content-hash idempotency.
 2. **Add the drawer (verbatim).** File the exact artifact text into `room: <room>` of `wing: <wing>` with provenance (`source_file`, phase id). Interactive: `mempalace_add_drawer`. Headless: `mempalace mine <path> --wing <wing> --room <room>`.
-3. **Mirror KG facts** when `config.mempalace.mirror_kg` is true: extract decision/delivery facts and `mempalace_kg_add` them with `valid_from` = the phase date (e.g. `(<project>, decided, <decision>)` from CONTEXT; `(<phase>, delivered, <capability>)` from SUMMARY). Only `augment` is currently wired, so these are an *additive* mirror of `.planning/graphs/`. (`kg_backend`/`replace` are forward-declared and behave as `augment` today.)
+3. **Mirror KG facts** when `config.mempalace.mirror_kg` is true: extract decision/delivery facts and `mempalace_kg_add` them with `valid_from` = the phase date (e.g. `(<project>, decided, <decision>)` from CONTEXT; `(<phase>, delivered, <capability>)` from SUMMARY). Under `augment` these are an *additive* mirror of GSD's native `.planning/graphs/`. Under `kg_backend`/`replace` the palace KG is the *authoritative* fact store — GSD still produces `.planning/graphs/` through its normal graphify, so an unreachable palace never loses a fact.
 4. Re-running a phase MUST NOT create duplicate drawers (deterministic ids + `check_duplicate`).
 
 ## Step 4 -- Report

package/commands/gsd/mempalace-recall.md

@@ -48,13 +48,17 @@ This step is `onError: skip` at `plan:pre` -- recall never blocks planning.
 ## Step 2 -- Resolve wing, mode, and transport
 
 1. **Wing.** Use `config.mempalace.wing` if non-empty; otherwise derive from `config.project_code`; otherwise fall back to the repository directory name.
-2. **Mode.** Read `config.mempalace.memory_mode` (`augment` | `kg_backend` | `replace`, default `augment`). Only `augment` is wired today, so recall always treats the palace as additive; `kg_backend`/`replace` are forward-declared and behave as `augment`.
+2. **Mode.** Read `config.mempalace.memory_mode` (`augment` | `kg_backend` | `replace`, default `augment`). It sets how authoritative the palace is during recall:
+   - `augment` — the palace is an *additional* layer; read native memory (`.planning/graphs/`, STATE) too and treat the palace as supplementary.
+   - `kg_backend` — for knowledge-graph facts, query the palace's temporal KG *first, as the primary source*; fall back to `.planning/graphs/` when the palace is unreachable. Non-KG drawer recall stays additive.
+   - `replace` — resolve recall *through the palace as the source of truth*; consult native artifacts only as a fallback when the palace is unreachable.
+   In every mode an unreachable palace degrades to native memory — recall never blocks (`onError: skip`).
 3. **Transport.** Prefer the **MCP tools** (`mempalace_*`) in interactive runs *when your MemPalace MCP server is registered and your runtime permits those tools*. Otherwise — headless/cron/autonomous runs, or runtimes that don't grant the MemPalace MCP tools — use the **CLI** (`mempalace wake-up`, `mempalace search`), which this skill's `Bash` allow-tool always covers. If neither is reachable, go to Step 4.
 4. **Topic.** Read the phase `CONTEXT.md` (the consumed artifact). Derive a short search query from its title, goal, and key decisions.
 
 ## Step 3 -- Retrieve (read-only)
 
-All calls in this step are side-effect-free. On any error or timeout, stop retrieving and write whatever was gathered (or the stub) -- never raise.
+All calls in this step are side-effect-free. On any error or timeout, stop retrieving and write whatever was gathered (or the stub) -- never raise. This skill reads only the palace; GSD's planner reads native memory (`.planning/graphs/`, STATE) regardless. So under `kg_backend`/`replace` an unreachable palace falls back to that native memory automatically — reflect that in the stub (Step 4) rather than implying memory is gone.
 
 1. **Wake up** (cheap, ~600--900 tokens):
    - Interactive: read the wing identity/summary, then `mempalace_search`.
@@ -62,7 +66,7 @@ All calls in this step are side-effect-free. On any error or timeout, stop retri
 2. **Targeted search:**
    - Interactive: `mempalace_search(query=<topic>, wing=<wing>)`.
    - Headless: `mempalace search "<topic>" --wing <wing>`.
-3. **Knowledge-graph facts** (when `config.mempalace.mirror_kg` is true): `mempalace_kg_query` / `mempalace_kg_timeline` for decisions relevant to the topic and their validity windows. Only `augment` is currently wired, so the palace KG *supplements* GSD's native `.planning/graphs/` — do not treat it as the sole source. (`kg_backend`/`replace` are forward-declared and behave as `augment` today.)
+3. **Knowledge-graph facts** (when `config.mempalace.mirror_kg` is true): `mempalace_kg_query` / `mempalace_kg_timeline` for decisions relevant to the topic and their validity windows. Under `augment` the palace KG *supplements* GSD's native `.planning/graphs/` — combine both, do not treat the palace as the sole source. Under `kg_backend` or `replace` the palace KG is the *primary* graph source — query it first and use `.planning/graphs/` only as a fallback when the palace is unreachable.
 4. **Dedup** the returned drawers/facts; keep the top results.
 
 ## Step 4 -- Write MEMORY-RECALL.md
@@ -86,12 +90,12 @@ _Wing: <wing> · Mode: <mode> · Transport: <mcp|cli>_
 - <surprise> — <provenance>
 ```
 
-When MemPalace is unreachable, write the stub and continue:
+When MemPalace is unreachable, write the stub and continue. Under `kg_backend`/`replace`, name the native fallback so the planner knows memory is not gone — only un-augmented by the palace this run:
 
 ```markdown
 # Memory Recall (MemPalace)
 
-_MemPalace unavailable at recall time — proceeding without recalled memory._
+_MemPalace unavailable at recall time — falling back to GSD native memory (`.planning/graphs/`, STATE). No palace recall this run._
 ```
 
 ## Anti-Patterns

package/commands/gsd/next.md

@@ -0,0 +1,29 @@
+---
+name: gsd:next
+description: Smart entry — detect project state and route to the right next GSD action.
+effort: low
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - SlashCommand
+  - AskUserQuestion
+---
+<objective>
+GSD smart entry — the state-aware front door. Detect what's going on in this project, then present a short menu of the right next actions and dispatch to one.
+
+This is a launcher/router only. It never does the work itself. It reads project + workflow state via `gsd-tools smart-entry --json`, shows a situation-appropriate menu, and hands off to an existing GSD command.
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/smart-entry.md
+@~/.claude/gsd-core/references/ui-brand.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Follow ~/.claude/gsd-core/workflows/smart-entry.md. Detect the situation, present the menu, and dispatch exactly one command. Then stop.
+</process>

package/commands/gsd/ns-project.md

@@ -5,7 +5,7 @@ argument-hint: ""
 allowed-tools:
   - Read
   - Skill
-requires: [new-project, new-milestone, complete-milestone, audit-milestone, milestone-summary, import, ingest-docs, profile-user, review-backlog]
+requires: [new-project, onboard, new-milestone, complete-milestone, audit-milestone, milestone-summary, import, ingest-docs, profile-user, review-backlog]
 ---
 
 Route to the appropriate project / milestone skill based on the user's intent.
@@ -15,6 +15,7 @@ inline as part of `gsd-audit-milestone`'s output.
 | User wants | Invoke |
 |---|---|
 | Start a new project | gsd-new-project |
+| Onboard an existing codebase | gsd-onboard |
 | Create a new milestone | gsd-new-milestone |
 | Complete the current milestone | gsd-complete-milestone |
 | Audit a milestone for issues | gsd-audit-milestone |

package/commands/gsd/ns-workflow.md

@@ -5,13 +5,15 @@ argument-hint: ""
 allowed-tools:
   - Read
   - Skill
-requires: [discuss-phase, spec-phase, plan-phase, execute-phase, verify-work, phase, progress, ultraplan-phase, plan-review-convergence, add-tests, ai-integration-phase, autonomous, fast, mvp-phase, quick]
+requires: [discuss-phase, spec-phase, plan-phase, execute-phase, verify-work, phase, progress, next, ultraplan-phase, plan-review-convergence, add-tests, ai-integration-phase, autonomous, fast, mvp-phase, quick]
 ---
 
 Route to the appropriate phase-pipeline skill based on the user's intent.
 Sub-skill names below are post-#2790 consolidated targets — `gsd-phase`
 absorbs the former add/insert/remove/edit-phase commands and `gsd-progress`
-absorbs the former next/do commands.
+absorbs the former next/do workflow-advance commands. The reclaimed
+`gsd-next` target is the state-aware smart-entry launcher, not the retired
+workflow-advance command.
 
 | User wants | Invoke |
 |---|---|
@@ -22,6 +24,7 @@ absorbs the former next/do commands.
 | Verify built features through UAT | gsd-verify-work |
 | Add / insert / remove / edit a phase | gsd-phase |
 | Advance to the next logical step | gsd-progress |
+| Open the state-aware smart-entry launcher | gsd-next |
 | Offload planning to the ultraplan cloud | gsd-ultraplan-phase |
 | Cross-AI plan review convergence loop | gsd-plan-review-convergence |
 | Generate tests for a completed phase | gsd-add-tests |

package/commands/gsd/onboard.md

@@ -0,0 +1,46 @@
+---
+name: gsd:onboard
+description: Guide existing codebase onboarding through mapping, doc ingest, and planning setup
+argument-hint: "[--fast] [--text]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+requires: [config, new-project, map-codebase, ingest-docs, manager]
+---
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API.
+</runtime_note>
+
+<objective>
+Guide brownfield onboarding for an existing codebase by routing through the existing GSD primitives in the safe order: codebase map → docs ingest → project initialization → onboarding summary.
+
+**Creates or confirms:**
+- `.planning/codebase/` — evidence-backed codebase map from `/gsd:map-codebase`
+- `.planning/PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md` — project setup from `/gsd:new-project` or `/gsd:ingest-docs`
+- `.planning/onboarding/SUMMARY.md` — lightweight index of what was learned and the next command
+
+**Non-goals:** This command does not execute phases, ship work, or overwrite existing planning artifacts without an explicit gate.
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/onboard.md
+@~/.claude/gsd-core/references/ui-brand.md
+@~/.claude/gsd-core/references/gate-prompts.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+
+Flags:
+- `--fast` — prefer `/gsd:map-codebase --fast` for the mapping handoff; the complete map is still required before `/gsd:new-project`.
+- `--text` — use plain-text numbered lists instead of TUI menus.
+</context>
+
+<process>
+Execute the onboard workflow end-to-end. Preserve all safety gates, text-mode fallbacks, idempotency checks, and top-level handoff rules for nested interactive commands.
+</process>

package/gsd-core/bin/ensure-runtime-build.cjs

@@ -0,0 +1,246 @@
+'use strict';
+
+/**
+ * Self-healing runtime build (#2002).
+ *
+ * The GSD runtime CLI (gsd-tools.cjs) require()s ~150 compiled modules from
+ * ./lib/*.cjs. Per ADR-457 ("build-at-publish") those are build artifacts:
+ * compiled from src/*.cts by `npm run build:lib` (tsc -p tsconfig.build.json),
+ * gitignored, and shipped prebuilt in the npm tarball via the prepack /
+ * prepublishOnly lifecycle scripts.
+ *
+ * The Claude Code plugin-marketplace channel does NOT go through `npm publish`
+ * or bin/install.js. Claude Code materializes the git tag tree into its plugin
+ * cache and at most runs `npm install --ignore-scripts`, so neither `prepare`
+ * nor `build:lib` ever fires. The compiled ./lib/*.cjs therefore never exist on
+ * that path and every CLI command dies at module load with
+ * `Cannot find module './lib/cli-exit.cjs'`.
+ *
+ * This module heals that: before gsd-tools.cjs require()s ./lib, if the compiled
+ * output is absent it invokes tsc once — lock-guarded so the many parallel
+ * gsd-tools shell-outs a workflow performs do not race the build — then lets the
+ * requires proceed. On the npm path the artifacts already exist, so the common
+ * case is a single fs.existsSync check and a no-op.
+ *
+ * Deliberately depends on nothing under ./lib (that tree is precisely what may
+ * be missing) — only on Node built-ins.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+// The first module gsd-tools.cjs require()s, and a gitignored build artifact
+// (so it is absent on a raw git-tag checkout even though ~11 other bin/lib/*.cjs
+// are git-tracked). tsconfig.build.json sets noEmitOnError:true, so tsc is
+// all-or-nothing: if this file exists, the whole tree was emitted.
+const SENTINEL = 'cli-exit.cjs';
+
+/** Directory holding the compiled ./lib/*.cjs, relative to this file. */
+function defaultLibDir() {
+  return path.join(__dirname, 'lib');
+}
+
+/**
+ * Package root (holds tsconfig.build.json + node_modules). This file lives at
+ * <root>/gsd-core/bin/ensure-runtime-build.cjs, so the root is two levels up —
+ * true for both the dev repo layout and the marketplace plugin-cache checkout
+ * (…/<version>/gsd-core/bin/ensure-runtime-build.cjs).
+ */
+function defaultPackageRoot() {
+  return path.resolve(__dirname, '..', '..');
+}
+
+/**
+ * Resolve the tsc entry SCRIPT (not the .bin/tsc shim). We run it as
+ * `node <tsc.js>` so behaviour is identical on POSIX and Windows and does not
+ * depend on a shell or on the .cmd shim. Returns null when TypeScript is not
+ * installed under packageRoot.
+ */
+function resolveTscScript(packageRoot) {
+  try {
+    return require.resolve('typescript/bin/tsc', { paths: [packageRoot] });
+  } catch {
+    return null;
+  }
+}
+
+function isBuilt(libDir) {
+  return fs.existsSync(path.join(libDir, SENTINEL));
+}
+
+/** Synchronous sleep with no dependencies, portable across platforms. */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.max(0, ms));
+}
+
+/**
+ * Raised when the runtime library is missing and cannot be auto-built. The
+ * message is user-facing and actionable; callers print `.message` (not a stack).
+ */
+class RuntimeBuildError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'RuntimeBuildError';
+    this.code = 'GSD_RUNTIME_BUILD_FAILED';
+  }
+}
+
+/**
+ * Ensure the compiled ./lib/*.cjs exist, building them once if absent.
+ *
+ * Idempotent and safe to call concurrently from many processes. When another
+ * process holds the build lock, this one waits for the build to finish rather
+ * than launching a competing tsc.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.libDir]        Override the compiled-output directory.
+ * @param {string} [opts.packageRoot]   Override the tsconfig/node_modules root.
+ * @param {string|null} [opts.tscScript] Override tsc resolution (null = "absent").
+ * @param {function} [opts.spawn]       Override spawnSync (for tests).
+ * @param {function} [opts.log]         Override the progress logger.
+ * @param {number} [opts.waitTimeoutMs] Max wait for a peer build (default 120s).
+ * @param {number} [opts.pollMs]        Poll interval while waiting (default 100ms).
+ * @param {function} [opts.onPoll]      Test hook invoked before each wait-poll.
+ * @returns {{built: true, healed: boolean, waited?: boolean}}
+ * @throws {RuntimeBuildError} when the library is absent and cannot be built.
+ */
+function ensureRuntimeBuild(opts = {}) {
+  const libDir = opts.libDir || defaultLibDir();
+  const packageRoot = opts.packageRoot || defaultPackageRoot();
+  const spawn = opts.spawn || spawnSync;
+  const log = opts.log || ((m) => process.stderr.write(m + '\n'));
+  const waitTimeoutMs = opts.waitTimeoutMs != null ? opts.waitTimeoutMs : 120000;
+  const pollMs = opts.pollMs != null ? opts.pollMs : 100;
+
+  // Fast path: already built (the npm-registry install and every subsequent run).
+  if (isBuilt(libDir)) return { built: true, healed: false };
+
+  const tsconfig = path.join(packageRoot, 'tsconfig.build.json');
+  if (!fs.existsSync(tsconfig)) {
+    throw new RuntimeBuildError(
+      'GSD runtime library is not built and cannot be auto-built: ' +
+        `${tsconfig} not found. Run \`npm run build:lib\` in the gsd-core package.`,
+    );
+  }
+
+  const tscScript =
+    opts.tscScript !== undefined ? opts.tscScript : resolveTscScript(packageRoot);
+  if (!tscScript) {
+    throw new RuntimeBuildError(
+      `GSD runtime library is not built (missing ${path.join(libDir, SENTINEL)}) ` +
+        'and TypeScript is unavailable to build it. Run ' +
+        `\`npm install && npm run build:lib\` in the gsd-core package (${packageRoot}).`,
+    );
+  }
+
+  // libDir may not exist yet on a totally fresh tree; create it so the lock and
+  // tsc output have a home.
+  fs.mkdirSync(libDir, { recursive: true });
+  const lockDir = path.join(libDir, '.build.lock');
+
+  let haveLock = acquireLock(lockDir);
+  if (!haveLock) {
+    // A peer process is building. Wait for the sentinel rather than racing tsc.
+    const deadline = Date.now() + waitTimeoutMs;
+    while (!isBuilt(libDir)) {
+      if (typeof opts.onPoll === 'function') opts.onPoll();
+      if (isBuilt(libDir)) break;
+      if (Date.now() > deadline) break; // peer wedged/crashed — take over below
+      sleepSync(pollMs);
+    }
+    if (isBuilt(libDir)) return { built: true, healed: true, waited: true };
+    // Peer never finished; try to take over the (stale) lock.
+    haveLock = acquireLock(lockDir);
+    if (!haveLock && !isBuilt(libDir)) {
+      throw new RuntimeBuildError(
+        `GSD runtime build did not complete within ${waitTimeoutMs}ms and the ` +
+          `build lock (${lockDir}) is held by another process. Remove it and run ` +
+          '`npm run build:lib` if this persists.',
+      );
+    }
+    if (isBuilt(libDir)) return { built: true, healed: true, waited: true };
+  }
+
+  try {
+    log('gsd: runtime library not built — compiling once (tsc -p tsconfig.build.json)…');
+    // Heal only runs when the build is genuinely absent/broken, so force a full
+    // emit: a stale incremental cache from a partial build would make tsc report
+    // success without re-emitting the (still-missing) sentinel.
+    forceFullEmit(packageRoot, tsconfig);
+    const res = spawn(process.execPath, [tscScript, '-p', tsconfig], {
+      cwd: packageRoot,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf8',
+    });
+    if (!res || res.status !== 0) {
+      const detail = ((res && (res.stderr || res.stdout)) || '').toString().trim();
+      throw new RuntimeBuildError(
+        `GSD runtime build failed (tsc exit ${res ? res.status : 'unknown'}). ` +
+          `Run \`npm run build:lib\` in ${packageRoot} to see the error.` +
+          (detail ? `\n${detail}` : ''),
+      );
+    }
+  } finally {
+    releaseLock(lockDir);
+  }
+
+  if (!isBuilt(libDir)) {
+    throw new RuntimeBuildError(
+      `GSD runtime build ran but ${path.join(libDir, SENTINEL)} is still missing. ` +
+        `Run \`npm run build:lib\` in ${packageRoot}.`,
+    );
+  }
+  return { built: true, healed: true };
+}
+
+/**
+ * Delete tsc's incremental build cache so the heal re-emits every module. The
+ * cache path defaults to tsconfig.build.tsbuildinfo (per tsconfig.build.json)
+ * but is read from the config when overridden. Best-effort: a missing or
+ * unreadable config just falls back to the default and a missing cache is fine.
+ */
+function forceFullEmit(packageRoot, tsconfigPath) {
+  let rel = 'tsconfig.build.tsbuildinfo';
+  try {
+    const cfg = JSON.parse(fs.readFileSync(tsconfigPath, 'utf8'));
+    if (cfg && cfg.compilerOptions && cfg.compilerOptions.tsBuildInfoFile) {
+      rel = cfg.compilerOptions.tsBuildInfoFile;
+    }
+  } catch {
+    /* unreadable/JSONC config — use the default cache path */
+  }
+  try {
+    fs.rmSync(path.resolve(packageRoot, rel), { force: true });
+  } catch {
+    /* best effort */
+  }
+}
+
+/** Atomically acquire the build lock. Returns true on success. */
+function acquireLock(lockDir) {
+  try {
+    fs.mkdirSync(lockDir); // atomic — throws EEXIST if a peer holds it
+    return true;
+  } catch (e) {
+    if (e && e.code === 'EEXIST') return false;
+    throw e;
+  }
+}
+
+/** Best-effort lock release. */
+function releaseLock(lockDir) {
+  try {
+    fs.rmSync(lockDir, { recursive: true, force: true });
+  } catch {
+    /* best effort — a leftover lock is recovered by the wait-then-takeover path */
+  }
+}
+
+module.exports = {
+  ensureRuntimeBuild,
+  resolveTscScript,
+  isBuilt,
+  RuntimeBuildError,
+  SENTINEL,
+};

package/gsd-core/bin/gsd-tools.cjs

@@ -179,14 +179,23 @@
  *
  * Loop Extension Point Queries (ADR-857 phase 3c):
  *   loop render-hooks <point>            Resolve + render active Capability hooks at a loop point
+ *                                        [--config-dir <path>] [--runtime <r>] [--active-cap <capId>]
  *                                        Returns JSON envelope { point, activeHooks, rendered }
  *                                        Valid points: discuss:pre/post, plan:pre/post,
  *                                        execute:pre/wave:pre/wave:post/post, verify:pre/post, ship:pre/post
+ *                                        --runtime: override the auto-detected runtime (#2003) so the config
+ *                                                   dir resolves to that runtime's home even when
+ *                                                   .planning/config.json persists a different runtime.
  *
  * Capability State (ADR-857 phase 4b):
- *   capability state [--config-dir <path>]  Resolve per-capability install/surface/hook-activation state
+ *   capability state [--config-dir <path>] [--runtime <r>]  Resolve per-capability install/surface/hook-activation state
  *                                           Returns JSON envelope { runtimeConfigDir, capabilities[] }
  *                                           --config-dir: runtime config dir (default: auto-detect current runtime)
+ *                                           --runtime: override the auto-detected runtime (#2003); bypasses the
+ *                                                      GSD_RUNTIME → config.runtime → 'claude' precedence so a
+ *                                                      repo with a persisted runtime can still resolve another
+ *                                                      runtime's config dir (e.g. driving Claude Code from a
+ *                                                      repo that persists runtime:"codex").
  *
  * GSD-2 Migration:
  *   from-gsd2 [--path <dir>] [--force] [--dry-run]
@@ -195,6 +204,24 @@
 
 const fs = require('fs');
 const path = require('path');
+
+// #2002 — self-healing runtime build. The compiled ./lib/*.cjs modules this
+// entrypoint require()s below are gitignored build artifacts (ADR-457), shipped
+// prebuilt in the npm tarball. The Claude Code plugin-marketplace channel never
+// runs `npm run build:lib` or bin/install.js, so on that path they can be
+// absent and every command dies at module load. Compile them once (lock-guarded,
+// idempotent, a no-op when already built) before the ./lib requires run.
+const { ensureRuntimeBuild } = require('./ensure-runtime-build.cjs');
+try {
+  ensureRuntimeBuild();
+} catch (bootErr) {
+  process.stderr.write((bootErr && bootErr.message ? bootErr.message : String(bootErr)) + '\n');
+  // Fatal bootstrap failure before the CLI's ExitError/runMain machinery (which
+  // lives in ./lib) is available to load, so a direct exit is the only option.
+  // eslint-disable-next-line n/no-process-exit
+  process.exit(1);
+}
+
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 const io = require('./lib/io.cjs');
 const { error, ERROR_REASON, setJsonErrorMode, output } = io;
@@ -259,6 +286,7 @@ const { routePhasesCommand } = require('./lib/phases-command-router.cjs');
 const { routeValidateCommand } = require('./lib/validate-command-router.cjs');
 const { routeRoadmapCommand } = require('./lib/roadmap-command-router.cjs');
 const { routeAgentCommand } = require('./lib/agent-command-router.cjs');
+const smartEntryMod = require('./lib/smart-entry.cjs');
 const { routeCheckCommand } = require('./lib/check-command-router.cjs');
 const { routeTaskCommand } = require('./lib/task-command-router.cjs');
 const { parseNamedArgs, parseMultiwordArg } = require('./lib/command-arg-projection.cjs');
@@ -665,7 +693,7 @@ async function main() {
     'from-gsd2, frontmatter, gap-analysis, generate-claude-md, generate-claude-profile, ' +
     'generate-dev-preferences, generate-slug, graphify, history-digest, init, intel, ' +
     'capability, classify-confidence, git, learnings, list-seeds, list-todos, loop, milestone, package-legitimacy, phase, phase-plan-index, phases, profile-questionnaire, ' +
-    'profile-sample, progress, project-instruction-file, prompt-budget, requirements, research-plan, research-store, resolve-granularity, resolve-model, roadmap, scaffold, state, ' +
+    'profile-sample, progress, project-instruction-file, prompt-budget, requirements, research-plan, research-store, resolve-granularity, resolve-model, roadmap, scaffold, smart-entry, state, ' +
     'task, template, user-story, validate, verify, verify-path-exists, verify-summary, eval, workstream, worktree\n\n' +
     'Global flags:\n' +
     '  --raw              Emit raw output without post-processing\n' +
@@ -833,6 +861,11 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       break;
     }
 
+    case 'smart-entry': {
+      smartEntryMod.runSmartEntry(cwd, args, raw);
+      break;
+    }
+
     case 'check': {
       routeCheckCommand({ args, cwd, raw });
       break;
@@ -1574,9 +1607,28 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
           }
           loopActiveCap = value;
         }
+        // --runtime <r> (#2003): explicit runtime override so the config-dir
+        // resolution bypasses the persisted-runtime fallback (GSD_RUNTIME →
+        // config.runtime). Mirrors the --config-dir dual-form (--runtime X /
+        // --runtime=X) and the capability-set --runtime precedent.
+        let loopRuntime = undefined;
+        const runtimeEqArg = args.find(arg => arg.startsWith('--runtime='));
+        const runtimeIdx = args.indexOf('--runtime');
+        if (runtimeEqArg) {
+          const value = runtimeEqArg.slice('--runtime='.length).trim();
+          if (!value) error('Missing value for --runtime', ERROR_REASON ? ERROR_REASON.USAGE : undefined);
+          loopRuntime = value;
+        } else if (runtimeIdx !== -1) {
+          const value = args[runtimeIdx + 1];
+          if (!value || value.startsWith('--')) {
+            error('Missing value for --runtime', ERROR_REASON ? ERROR_REASON.USAGE : undefined);
+          }
+          loopRuntime = value;
+        }
         loopResolver.cmdLoopRenderHooks(cwd, args[2], raw, {
           configDir: loopConfigDir ? path.resolve(loopConfigDir) : undefined,
           activeCap: loopActiveCap,
+          runtime: loopRuntime,
         });
       } else {
         error(
@@ -1728,7 +1780,24 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
           configDir = configDirVal;
         }
         const resolvedConfigDir = configDir ? path.resolve(configDir) : null;
-        capabilityState.cmdCapabilityState(cwd, resolvedConfigDir, raw, {});
+        // --runtime <r> (#2003): explicit runtime override so the config-dir
+        // resolution bypasses the persisted-runtime fallback. Dual-form like
+        // --config-dir (--runtime X / --runtime=X).
+        let stateRuntime = undefined;
+        const stateRuntimeEqArg = args.find(arg => arg.startsWith('--runtime='));
+        const stateRuntimeIdx = args.indexOf('--runtime');
+        if (stateRuntimeEqArg) {
+          const value = stateRuntimeEqArg.slice('--runtime='.length).trim();
+          if (!value) error('Missing value for --runtime', ERROR_REASON ? ERROR_REASON.USAGE : undefined);
+          stateRuntime = value;
+        } else if (stateRuntimeIdx !== -1) {
+          const value = args[stateRuntimeIdx + 1];
+          if (!value || value.startsWith('--')) {
+            error('Missing value for --runtime', ERROR_REASON ? ERROR_REASON.USAGE : undefined);
+          }
+          stateRuntime = value;
+        }
+        capabilityState.cmdCapabilityState(cwd, resolvedConfigDir, raw, { runtime: stateRuntime });
       } else if (capSubcommand === 'set') {
         // capability set <id> [--on|--off|--enable|--disable] [--gate <key>=<bool>]... [--config-dir <dir>] [--runtime <r>] [--scope <s>]
         const capId = args[2];