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

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

@@ -24,15 +24,16 @@ const ROOT = path.resolve(__dirname, '..');
 // 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, gemini-extension.json); the Claude plugin
+// 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 = [
   { path: '.claude-plugin/plugin.json', versionKey: 'version' },
-  { path: 'gemini-extension.json', versionKey: 'version' },
   { path: '.claude-plugin/marketplace.json', versionKey: 'plugins.0.version' },
   { path: 'vscode/package.json', versionKey: 'version' },
 ];

package/scripts/sync-runtime-launcher.cjs

@@ -343,9 +343,12 @@ function transformFile(content, preamble) {
     }
   }
 
-  // Insert preamble into the first gsd_run block only
+  // Insert preamble into the first gsd_run block only — UNLESS this file
+  // delegates to the shared resolver reference (@-include). Delegating files keep
+  // the stripped blocks (any inline preamble removed) but never get one inserted.
+  const delegates = delegatesToResolverReference(content);
   const finalBlocks = strippedBlocks.map((stripped, bi) => {
-    if (bi === firstGsdRunBlockIdx) {
+    if (!delegates && bi === firstGsdRunBlockIdx) {
       return insertPreamble(stripped, preamble);
     }
     return stripped;
@@ -374,6 +377,21 @@ function escapeRegExp(str) {
   return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+/**
+ * A file "delegates to the shared resolver" when it pulls the canonical gsd_run
+ * preamble in from gsd-core/references/gsd-run-resolver.md via an @-include
+ * instead of inlining the snippet (see onboard.md / issue #1990).
+ *
+ * These files must NOT carry an inline preamble: the resolver reference ships the
+ * one canonical copy, and onboard-command.test.cjs asserts the inline form is
+ * absent. transformFile still STRIPS any inline preamble from them (so a stray
+ * copy is removed) but never re-inserts one — mirroring the exemption in
+ * runtime-launcher-parity.test.cjs (subtest B / B2).
+ */
+function delegatesToResolverReference(content) {
+  return content.includes('references/gsd-run-resolver.md');
+}
+
 // Main
 function main() {
   const preamble = loadPreamble();

package/skills/gsd-map-codebase/SKILL.md

@@ -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/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-project/SKILL.md

@@ -14,6 +14,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/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 |

package/skills/gsd-onboard/SKILL.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
+---
+
+<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/gemini-extension.json

@@ -1,6 +0,0 @@
-{
-  "name": "gsd-core",
-  "version": "1.7.0-rc.2",
-  "description": "GSD Core — a meta-prompting, context engineering, and spec-driven development system for AI coding agents. Loads gsd's operating context into every Gemini CLI session.",
-  "contextFileName": "GEMINI.md"
-}