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

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-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/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

@@ -195,6 +195,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 +277,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 +684,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 +852,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;