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

package/scripts/research-profiles.cjs

@@ -24,7 +24,7 @@ const PROFILES = [
       'Researches domain ecosystem before roadmap creation. Produces files in .planning/research/ consumed during roadmap creation. Spawned by /gsd:new-project or /gsd:new-milestone orchestrators.',
     color: 'cyan',
     tools:
-      'Read, Write, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*, mcp__perplexity__*',
+      'Read, Write, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__plugin_context7_context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*, mcp__perplexity__*',
     requiredIncludes: [
       '@~/.claude/gsd-core/references/research-documentation-lookup.md',
       '@~/.claude/gsd-core/references/research-philosophy.md',
@@ -46,7 +46,7 @@ const PROFILES = [
       'Researches how to implement a phase before planning. Produces RESEARCH.md consumed by gsd-planner. Spawned by /gsd:plan-phase orchestrator.',
     color: 'cyan',
     tools:
-      'Read, Write, Edit, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*, mcp__perplexity__*',
+      'Read, Write, Edit, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__plugin_context7_context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*, mcp__perplexity__*',
     requiredIncludes: [
       '@~/.claude/gsd-core/references/research-documentation-lookup.md',
       '@~/.claude/gsd-core/references/research-philosophy.md',
@@ -68,7 +68,7 @@ const PROFILES = [
     description:
       'Researches a single gray area decision and returns a structured comparison table with rationale. Spawned by discuss-phase advisor mode.',
     color: 'cyan',
-    tools: 'Read, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*',
+    tools: 'Read, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__plugin_context7_context7__*',
     requiredIncludes: [
       '@~/.claude/gsd-core/references/research-documentation-lookup.md',
     ],
@@ -84,7 +84,7 @@ const PROFILES = [
       'Researches a chosen AI framework\'s official docs to produce implementation-ready guidance — best practices, syntax, core patterns, and pitfalls distilled for the specific use case. Writes the Framework Quick Reference and Implementation Guidance sections of AI-SPEC.md. Spawned by /gsd:ai-integration-phase orchestrator.',
     color: 'green',
     tools:
-      'Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch, mcp__context7__*',
+      'Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch, mcp__context7__*, mcp__plugin_context7_context7__*',
     requiredIncludes: [
       '@~/.claude/gsd-core/references/research-documentation-lookup.md',
     ],
@@ -101,7 +101,7 @@ const PROFILES = [
       'Researches the business domain and real-world application context of the AI system being built. Surfaces domain expert evaluation criteria, industry-specific failure modes, regulatory context, and what "good" looks like for practitioners in this field — before the eval-planner turns it into measurable rubrics. Spawned by /gsd:ai-integration-phase orchestrator.',
     color: 'purple',
     tools:
-      'Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*',
+      'Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__plugin_context7_context7__*',
     requiredIncludes: [
       '@~/.claude/gsd-core/references/research-documentation-lookup.md',
     ],
@@ -117,7 +117,7 @@ const PROFILES = [
       'Produces UI-SPEC.md design contract for frontend phases. Reads upstream artifacts, detects design system state, asks only unanswered questions. Spawned by /gsd:ui-phase orchestrator.',
     color: 'purple',
     tools:
-      'Read, Write, Edit, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*',
+      'Read, Write, Edit, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__plugin_context7_context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*',
     requiredIncludes: [
       '@~/.claude/gsd-core/references/research-documentation-lookup.md',
     ],

package/scripts/run-tests.cjs

@@ -119,6 +119,51 @@ function ensureBuiltArtifacts(overrides = {}) {
     }
   }
 }
+
+// hooks/dist/ is gitignored (.gitignore) and NOT built by `prepare`
+// (npm run build:lib only) — only the full `build`/`prepublishOnly` scripts run
+// build:hooks. So on a clean checkout + `npm ci` (fresh CI, incl. the scoped
+// test lane) hooks/dist starts absent. Install tests (e.g.
+// bug-3683-workflow-colon-namespace-leak) spawn `install.js --<runtime> --local`
+// which copies hooks from hooks/dist/ and then verifyInstalled() hard-fails if
+// the target hooks dir is empty. build-hooks.js `build()` creates DIST_DIR
+// empty and fills it file-by-file, so the FIRST on-demand build (triggered by
+// whichever concurrent install test's before() hook runs first) exposes a
+// window where hooks/dist exists but is empty/partial. A concurrently-spawned
+// install reader observes zero hooks -> "Failed to install hooks: directory is
+// empty" -> intermittent scoped-lane failure (full lanes dodge it only by luck
+// of a hooks-builder finishing early). Building hooks/dist ONCE here — the same
+// upfront chokepoint as ensureBuiltArtifacts, single-process with no concurrent
+// readers — fully populates dist before any test runs, closing the first-build
+// empty window everywhere (CI scoped/unit shards + local). Subsequent on-demand
+// rebuilds only atomically replace individual files (per-file rename in
+// build-hooks.js) and never re-empty the dir, so they stay safe.
+function ensureBuiltHooks(overrides = {}) {
+  const { existsSync, statSync } = require('fs');
+  const root = overrides.root || join(__dirname, '..');
+  const distDir = overrides.distDir || join(root, 'hooks', 'dist');
+  const hookNames = overrides.hookNames || require('./build-hooks.js').HOOKS_TO_COPY;
+  const runBuild = overrides.runBuild || (() => {
+    execFileSync(process.execPath, [join(root, 'scripts', 'build-hooks.js')], {
+      cwd: root,
+      stdio: 'inherit',
+    });
+  });
+
+  // dist is "complete" only if every expected hook exists as a non-empty file.
+  // Absent dir, empty dir, or a missing/zero-byte hook all trigger a rebuild.
+  const complete = existsSync(distDir) && hookNames.every((hook) => {
+    const p = join(distDir, hook);
+    try {
+      return existsSync(p) && statSync(p).size > 0;
+    } catch {
+      return false;
+    }
+  });
+  if (!complete) {
+    runBuild();
+  }
+}
 const MARKED_SUITES = ['integration', 'install', 'security', 'slow'];
 
 // Recursively collect *.test.cjs files under dir, returning paths relative to dir.
@@ -454,6 +499,11 @@ function main() {
   // Build the gitignored bin/lib artifact if absent, before any test requires it.
   ensureBuiltArtifacts();
 
+  // Build the gitignored hooks/dist artifact once, before any concurrent install
+  // test spawns install.js and reads it — closes the first-build empty-dir race
+  // that intermittently failed the scoped CI lane (see ensureBuiltHooks above).
+  ensureBuiltHooks();
+
   // Hermeticity: in-process tests resolve `.planning` via planningDir(cwd), which
   // honours GSD_PROJECT/GSD_WORKSTREAM. A developer shell inside a GSD workstream
   // exports GSD_WORKSTREAM, which would redirect fixture STATE.md reads away from
@@ -512,9 +562,19 @@ function main() {
   const MAX_CMDLINE_CHARS = process.env.RUN_TESTS_MAX_CMDLINE_CHARS
     ? Number(process.env.RUN_TESTS_MAX_CMDLINE_CHARS)
     : 28000; // headroom below the 32,767 Windows ceiling
+  // A full-lane shard (~171 files) fit in ONE chunk at the old cap of 180, so the
+  // entire shard's wall-clock ran against a single per-chunk timeout. On the slow
+  // Windows runner the install-heavy files in a shard (e.g. install-minimal-hooks
+  // .test.cjs alone runs ~250 cases doing dozens of real installs) push that single
+  // chunk past the 600s per-chunk backstop — killed mid-run while still making slow
+  // progress (verified: no leaked handle / hang; --test-force-exit exits leaks
+  // cleanly, so the timeout was pure slowness, NOT the leak the kill message guesses).
+  // The per-chunk timeout is sized for a "healthy chunk (~4-5 min)"; keep chunks at
+  // roughly half a shard so each gets its own fresh 600s budget and a fresh node
+  // process (also relieving per-process memory pressure from 170+ files at once).
   const MAX_FILES_PER_CHUNK = process.env.RUN_TESTS_MAX_FILES_PER_CHUNK
     ? Number(process.env.RUN_TESTS_MAX_FILES_PER_CHUNK)
-    : 180;
+    : 90;
 
   // node:test does not exit until the event loop drains. A unit test that leaks
   // an open handle (un-terminated Worker, un-killed child_process, ref'd timer)
@@ -580,9 +640,12 @@ function main() {
       if (timedOut) {
         console.error(
           `run-tests: chunk ${i + 1}/${chunks.length} exceeded the per-chunk timeout ` +
-            `of ${chunkTimeoutMs}ms and was killed — a test in this chunk is likely leaking ` +
+            `of ${chunkTimeoutMs}ms and was killed. Two possible causes: (1) a test leaks ` +
             `an open handle (un-terminated Worker, un-killed child process, or ref'd timer) ` +
-            `so node --test never exits. Files: ${chunks[i]
+            `so node --test never exits — but --test-force-exit already guards that, so if it ` +
+            `is enabled suspect (2) the chunk is legitimately too slow for the budget (too ` +
+            `many/too-heavy files packed together). Check whether output kept flowing until ` +
+            `the kill (slow) vs stopped early (hang) before assuming a leak. Files: ${chunks[i]
               .map(f => f.split(/[\\/]/).pop())
               .join(' ')}`,
         );
@@ -600,4 +663,4 @@ if (require.main === module) {
   runMain(main);
 }
 
-module.exports = { suiteOf, ensureBuiltArtifacts, parseShardArg, selectShard };
+module.exports = { suiteOf, ensureBuiltArtifacts, ensureBuiltHooks, parseShardArg, selectShard };

package/scripts/slurm-adapter.cjs

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * slurm-adapter.cjs — SLURM scheduler-adapter helper for the external-job
+ * capability (#1164 / #1105).
+ *
+ * Thin CLI: runs bounded sbatch / squeue / sacct subprocesses and delegates
+ * all parsing, manifest build/validate, and fail-closed writing to the pure
+ * module (gsd-core/bin/lib/external-job.cjs). The pure module is fully unit-
+ * tested; this script is the operator surface that needs a real cluster.
+ *
+ * Subcommands:
+ *   submit  --plan <plan_id> --phase <phase> --expected <path>[,<path>] \
+ *           --verify <cmd> --resume <cmd> -- <sbatch...>
+ *   poll    --job <job_id> [--plan <plan_id>]
+ *   show    --job <job_id>            (surface manifest status + commands; no auto-run)
+ *
+ * Trust boundary: this script never auto-runs verification_command or
+ * resume_command from a manifest (planning-artifacts.md). `show` prints them
+ * for explicit operator confirmation.
+ */
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+const m = require('../gsd-core/bin/lib/external-job.cjs');
+
+// #1164 refinements B + C: the adapter now resolves external_job.* settings
+// through the canonical capability-config seam (resolveConfigKey in
+// capability-activation.cjs), which walks loadConfig -> workstream config.json
+// -> root config.json -> registry configSchema default. Env vars remain the
+// top-precedence override so cluster operators can tune without editing config.
+const { resolveConfigKey } = require('../gsd-core/bin/lib/capability-activation.cjs');
+const FALLBACK_SUBMIT_TIMEOUT_MS = 30000;
+const FALLBACK_POLL_TIMEOUT_MS = 15000;
+const FALLBACK_ARTIFACT_DIR = 'Artifacts/jobs';
+
+/**
+ * Resolve the external_job.* runtime settings. Pure given {config, env,
+ * registry}; degrades to hardcoded fallbacks if the registry/config are absent
+ * so the adapter never unbounds a subprocess (CLAUDE.md bounded-subprocess).
+ *
+ * Precedence: env override > nested config value > registry default > fallback.
+ */
+function resolveExternalJobSettings({ cwd, env, config, registry } = {}) {
+    const reg = registry || {};
+    let cfg = config;
+    if (cfg === undefined) {
+        try {
+            cfg = require('../gsd-core/bin/lib/config-loader.cjs').loadConfig(cwd);
+        } catch {
+            cfg = {}; // resolveConfigKey still falls back to the registry default
+        }
+    }
+    const e = env || {};
+    const submitEnv = e.GSD_SLURM_SUBMIT_TIMEOUT_MS;
+    const pollEnv = e.GSD_SLURM_POLL_TIMEOUT_MS;
+    const artifactEnv = e.GSD_EXTERNAL_JOB_ARTIFACT_DIR;
+    const submit = submitEnv ? Number(submitEnv)
+        : _num(resolveConfigKey('external_job.submit_timeout_ms', { config: cfg, cwd, registry: reg }), FALLBACK_SUBMIT_TIMEOUT_MS);
+    const poll = pollEnv ? Number(pollEnv)
+        : _num(resolveConfigKey('external_job.poll_timeout_ms', { config: cfg, cwd, registry: reg }), FALLBACK_POLL_TIMEOUT_MS);
+    const artifactDir = artifactEnv
+        || _str(resolveConfigKey('external_job.artifact_dir', { config: cfg, cwd, registry: reg }), FALLBACK_ARTIFACT_DIR);
+    return { submitTimeoutMs: submit, pollTimeoutMs: poll, artifactDir };
+}
+
+function _num(res, fallback) {
+    const v = res && res.found ? res.value : undefined;
+    return typeof v === 'number' && Number.isFinite(v) ? v : fallback;
+}
+function _str(res, fallback) {
+    const v = res && res.found ? res.value : undefined;
+    return typeof v === 'string' && v.length > 0 ? v : fallback;
+}
+
+function usage() {
+  return [
+    'usage: slurm-adapter.cjs <submit|poll|show> ...',
+    '  submit --plan <id> --phase <n> --expected <p1,p2> --verify <cmd> --resume <cmd> -- sbatch --parsable ...',
+    '  poll   --job <job_id> [--plan <plan_id>]',
+    '  show   --job <job_id>',
+  ].join('\n');
+}
+
+function parseFlags(argv) {
+  const out = {};
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') { out['--'] = argv.slice(i + 1); break; }
+    if (a.startsWith('--')) {
+      const v = argv[i + 1];
+      out[a.slice(2)] = v;
+      i++;
+    } else {
+      rest.push(a);
+    }
+  }
+  out._ = rest;
+  return out;
+}
+
+function findPlanningDir(start) {
+  let dir = path.resolve(start || process.cwd());
+  for (let i = 0; i < 10; i++) {
+    if (fs.existsSync(path.join(dir, '.planning'))) return path.join(dir, '.planning');
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new ExitError(1, 'could not locate a .planning directory (walked up 10 levels)');
+}
+
+function cmdSubmit(flags) {
+  const plan = flags.plan;
+  const phase = flags.phase;
+  const sbatchCmd = flags['--'];
+  if (!plan || phase === undefined || !Array.isArray(sbatchCmd) || sbatchCmd.length === 0) {
+    throw new ExitError(1, 'submit requires --plan, --phase, and an sbatch command after --\n' + usage());
+  }
+  const expected = (flags.expected || '').split(',').map((s) => s.trim()).filter(Boolean);
+  if (expected.length === 0) throw new ExitError(1, 'submit requires --expected (comma-separated artifact paths)');
+  const verify = flags.verify;
+  const resume = flags.resume || ('/gsd:execute-phase ' + phase);
+  if (!verify) throw new ExitError(1, 'submit requires --verify (the command that verifies job output)');
+
+  // Resolve settings from config/env before any subprocess (env > config > default).
+  const planningDir = findPlanningDir();
+  const settings = resolveExternalJobSettings({
+    cwd: path.dirname(planningDir),
+    env: process.env,
+  });
+
+  let stdout;
+  try {
+    stdout = execFileSync(sbatchCmd[0], sbatchCmd.slice(1), {
+      encoding: 'utf8',
+      timeout: settings.submitTimeoutMs,
+      maxBuffer: 1024 * 1024,
+    });
+  } catch (e) {
+    throw new ExitError(1, 'sbatch failed: ' + (e.message || String(e)));
+  }
+  const parsed = m.parseSbatchParsable(stdout);
+  if (!parsed.ok) {
+    throw new ExitError(1, 'could not parse sbatch --parsable output (kind=' + parsed.kind + '): ' + parsed.raw);
+  }
+  const manifest = m.buildManifest({
+    plan_id: plan,
+    phase,
+    job_id: parsed.job_id,
+    backend: 'slurm',
+    submit_command: sbatchCmd.join(' '),
+    status: 'submitted',
+    expected_artifacts: expected,
+    verification_command: verify,
+    resume_command: resume,
+  });
+  const res = m.writeManifest(manifest, planningDir);
+  if (!res.ok) {
+    throw new ExitError(1, 'writeManifest refused (' + res.kind + '): ' + res.message);
+  }
+  process.stdout.write('submitted job ' + parsed.job_id + ' for plan ' + plan + '\n');
+  process.stdout.write('manifest: ' + res.path + '\n');
+  process.stdout.write('artifact_dir: ' + settings.artifactDir + '\n');
+  process.stdout.write('state: external_job_waiting (SUMMARY deferred)\n');
+}
+
+function cmdPoll(flags) {
+  const jobId = flags.job;
+  if (!jobId) throw new ExitError(1, 'poll requires --job <job_id>\n' + usage());
+  const planningDir = findPlanningDir();
+  const settings = resolveExternalJobSettings({
+    cwd: path.dirname(planningDir),
+    env: process.env,
+  });
+  const manifestFile = m.manifestPath(planningDir, jobId);
+  if (!fs.existsSync(manifestFile)) {
+    throw new ExitError(1, 'no manifest for job ' + jobId + ' at ' + manifestFile);
+  }
+  const existing = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
+
+  let rawState = null;
+  try {
+    const out = execFileSync('squeue', ['-h', '-j', jobId, '-o', '%i %T'], {
+      encoding: 'utf8', timeout: settings.pollTimeoutMs, maxBuffer: 1024 * 1024,
+    }).trim();
+    const line = out.split('\n')[0];
+    const parsed = m.parseSqueueLine(line || '');
+    if (parsed) rawState = parsed.state;
+  } catch (_e) { /* squeue empty/failed — fall back to sacct */ }
+  if (!rawState) {
+    try {
+      const out = execFileSync('sacct', ['-X', '-P', '-j', jobId, '-o', 'JobID,State'], {
+        encoding: 'utf8', timeout: settings.pollTimeoutMs, maxBuffer: 1024 * 1024,
+      }).trim();
+      for (const line of out.split('\n').slice(1)) {
+        const parsed = m.parseSacctRow(line.split('|'));
+        if (parsed) { rawState = parsed.state; break; }
+      }
+    } catch (e) {
+      throw new ExitError(1, 'both squeue and sacct failed: ' + (e.message || String(e)));
+    }
+  }
+  const mapped = m.mapSlurmState(rawState || '');
+  if (!mapped) throw new ExitError(1, 'unmapped SLURM state "' + rawState + '" — not guessing; inspect manually');
+
+  const updated = m.buildManifest(
+    Object.assign({}, existing, { status: mapped, terminal_details: existing.terminal_details || null }),
+    { clock: { nowIso: () => existing.submitted_at } },
+  );
+  const res = m.writeManifest(updated, planningDir);
+  if (!res.ok) throw new ExitError(1, 'writeManifest refused (' + res.kind + '): ' + res.message);
+  process.stdout.write(JSON.stringify({ job_id: jobId, slurm_state: rawState, manifest_status: mapped, path: res.path }) + '\n');
+}
+
+function formatShowReport(manifest) {
+  const lines = [];
+  lines.push('job ' + manifest.job_id + ' (plan ' + manifest.plan_id + ', backend ' + manifest.backend + ')');
+  lines.push('status: ' + manifest.status);
+  if (manifest.terminal_details) {
+    lines.push('terminal_details: ' + JSON.stringify(manifest.terminal_details));
+  }
+  // Trust boundary: surface commands for confirmation, never auto-run.
+  lines.push('');
+  lines.push('Manifest commands (UNTRUSTED — confirm before running):');
+  lines.push('  submit_command:       ' + manifest.submit_command);
+  lines.push('  verification_command: ' + manifest.verification_command);
+  lines.push('  resume_command:       ' + manifest.resume_command);
+  return lines.join('\n') + '\n';
+}
+
+function cmdShow(flags) {
+  const jobId = flags.job;
+  if (!jobId) throw new ExitError(1, 'show requires --job <job_id>\n' + usage());
+  const planningDir = findPlanningDir();
+  const manifestFile = m.manifestPath(planningDir, jobId);
+  if (!fs.existsSync(manifestFile)) {
+    throw new ExitError(1, 'no manifest for job ' + jobId + ' at ' + manifestFile);
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
+  process.stdout.write(formatShowReport(manifest));
+}
+
+function main() {
+  const [, , sub, ...rest] = process.argv;
+  const flags = parseFlags(rest);
+  if (sub === 'submit') cmdSubmit(flags);
+  else if (sub === 'poll') cmdPoll(flags);
+  else if (sub === 'show') cmdShow(flags);
+  else throw new ExitError(1, usage());
+  return 0;
+}
+
+if (require.main === module) {
+  runMain(main);
+}
+
+module.exports = {
+  parseFlags,
+  findPlanningDir,
+  resolveExternalJobSettings,
+  formatShowReport,
+  ExitError,
+};

package/scripts/sync-manifest-versions.cjs

@@ -21,18 +21,67 @@ const { execFileSync } = require('child_process');
 
 const ROOT = path.resolve(__dirname, '..');
 
-// Single source of truth: runtime-integration manifests whose top-level `version`
-// MUST track package.json. Add a new manifest here so `npm version` keeps it in
-// sync — the regression guard test (issue 844) fails if you forget.
+// Single source of truth: runtime-integration manifests whose `version` field
+// MUST track package.json. Each entry names the manifest path plus the dotted
+// path to the version field inside that JSON document. Top-level `version` is
+// the default (plugin.json); the Claude plugin
+// marketplace manifest carries its canonical version at plugins[0].version
+// (the schema-canonical location runtimes read — issue #1855).
+//
+// Add a new manifest here so `npm version` keeps it in sync — the regression
+// guard test (issue 844) fails if you forget.
+// #1928: gemini-extension.json was removed with the gemini runtime (Google
+// sunset Gemini CLI 2026-06-18); it is no longer a registered manifest.
 const VERSIONED_MANIFESTS = [
-  '.claude-plugin/plugin.json',
-  'gemini-extension.json',
+  { path: '.claude-plugin/plugin.json', versionKey: 'version' },
+  { path: '.claude-plugin/marketplace.json', versionKey: 'plugins.0.version' },
+  { path: 'vscode/package.json', versionKey: 'version' },
 ];
 
+// Convenience: just the registered paths, for consumers that only need to
+// iterate files (e.g. the issue-844 regression-guard ALLOWED set).
+const VERSIONED_MANIFEST_PATHS = VERSIONED_MANIFESTS.map((e) => e.path);
+
 function readJson(p) {
   return JSON.parse(fs.readFileSync(p, 'utf8'));
 }
 
+// Property names that must never be traversed/assigned through a dotted path —
+// the prototype-pollution triple. Mirrors the _isSafePropKey CodeQL barrier used
+// elsewhere in the repo. Versions are hand-authored descriptors, but the helpers
+// are exported, so guard them before reuse across a trust boundary.
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+function assertSafePath(dotPath) {
+  for (const seg of String(dotPath).split('.')) {
+    if (UNSAFE_KEYS.has(seg)) {
+      throw new Error(`refusing to traverse reserved property "${seg}" in version path "${dotPath}"`);
+    }
+  }
+}
+
+// Read a dotted path ('plugins.0.version') from a parsed JSON document.
+// Returns undefined if any intermediate is missing. Array indices are plain
+// numeric keys, so 'plugins.0.version' resolves obj.plugins[0].version.
+// Reserved properties (__proto__/constructor/prototype) are rejected.
+function getByPath(obj, dotPath) {
+  assertSafePath(dotPath);
+  return String(dotPath).split('.').reduce((cur, key) => (cur == null ? cur : cur[key]), obj);
+}
+
+// Write a value at a dotted path. Intermediate nodes must already exist (every
+// registered manifest is hand-authored with its version slot present, so this
+// never needs to materialize a path). Reserved properties are rejected. Kept
+// trivial — no eval, no creation.
+function setByPath(obj, dotPath, value) {
+  assertSafePath(dotPath);
+  const parts = String(dotPath).split('.');
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    cur = cur[parts[i]];
+  }
+  cur[parts[parts.length - 1]] = value;
+}
+
 function getPackageVersion(root) {
   const r = root || ROOT;
   return readJson(path.join(r, 'package.json')).version;
@@ -44,13 +93,13 @@ function syncManifestVersions(opts) {
   const root = (opts && opts.root) || ROOT;
   const v = (opts && opts.version) != null ? opts.version : getPackageVersion(root);
   const changed = [];
-  for (const rel of VERSIONED_MANIFESTS) {
-    const abs = path.join(root, rel);
+  for (const entry of VERSIONED_MANIFESTS) {
+    const abs = path.join(root, entry.path);
     const manifest = readJson(abs);
-    if (manifest.version !== v) {
-      manifest.version = v;
+    if (getByPath(manifest, entry.versionKey) !== v) {
+      setByPath(manifest, entry.versionKey, v);
       fs.writeFileSync(abs, JSON.stringify(manifest, null, 2) + '\n');
-      changed.push(rel);
+      changed.push(entry.path);
     }
   }
   return changed;
@@ -61,9 +110,10 @@ function findDrift(opts) {
   const root = (opts && opts.root) || ROOT;
   const v = (opts && opts.version) != null ? opts.version : getPackageVersion(root);
   const drift = [];
-  for (const rel of VERSIONED_MANIFESTS) {
-    const found = readJson(path.join(root, rel)).version;
-    if (found !== v) drift.push({ manifest: rel, found, expected: v });
+  for (const entry of VERSIONED_MANIFESTS) {
+    const manifest = readJson(path.join(root, entry.path));
+    const found = getByPath(manifest, entry.versionKey);
+    if (found !== v) drift.push({ manifest: entry.path, found, expected: v });
   }
   return drift;
 }
@@ -143,7 +193,7 @@ function stageManifests(opts) {
     console.warn('sync-manifest-versions: not a git work tree; skipping staging.');
     return;
   }
-  const toStage = [...VERSIONED_MANIFESTS, ...listCapabilityManifests({ root })];
+  const toStage = [...VERSIONED_MANIFEST_PATHS, ...listCapabilityManifests({ root })];
   try {
     execFileSync('git', ['add', '--', ...toStage], { cwd: root, stdio: ['ignore', 'ignore', 'pipe'] });
   } catch (err) {
@@ -154,6 +204,9 @@ function stageManifests(opts) {
 
 module.exports = {
   VERSIONED_MANIFESTS,
+  VERSIONED_MANIFEST_PATHS,
+  getByPath,
+  setByPath,
   syncManifestVersions,
   findDrift,
   getPackageVersion,

package/skills/gsd-mempalace-capture/SKILL.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/skills/gsd-mempalace-recall/SKILL.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/skills/gsd-next/SKILL.md

@@ -0,0 +1,30 @@
+---
+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/skills/gsd-ns-workflow/SKILL.md

@@ -10,7 +10,9 @@ allowed-tools:
 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 |
 |---|---|
@@ -21,6 +23,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 |