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

package/gsd-core/bin/lib/external-job.cjs

@@ -0,0 +1,287 @@
+"use strict";
+/**
+ * external-job.cts — scheduler-adapter producer module for the async
+ * external-job contract (#1164 / #1105).
+ *
+ * The CORE loop CONSUMES manifests at `.planning/async-jobs/<job>.json`
+ * (#1165 — external_job_waiting half-state); this module is the Capability
+ * half that PRODUCES them. SLURM is the first backend; the design stays
+ * scheduler-pluggable via the `backend` field (planning-artifacts.md).
+ *
+ * Pure helpers (state map, build, validate, parsers) take no I/O; the writer
+ * takes injected `fs` and `clock` seams so tests drive it without touching disk
+ * or wall-clock time (CLAUDE.md clock-seam + injectable-deps conventions).
+ *
+ * Build: `src/*.cts` -> `gsd-core/bin/lib/*.cjs` (ADR-457 build-at-publish).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+// ─── Closed status enum (stability contract — Hyrum's Law) ────────────────────
+const MANIFEST_VERSION = '1.0';
+const MANIFEST_STATUS = [
+    'submitted',
+    'running',
+    'completed-unverified',
+    'failed',
+    'cancelled',
+    'timeout',
+];
+const NON_TERMINAL_STATUSES = ['submitted', 'running'];
+const TERMINAL_FAILURE_STATUSES = ['failed', 'cancelled', 'timeout'];
+// ─── SLURM state -> manifest status ───────────────────────────────────────────
+//
+// Source: SLURM job state codes (squeue/sacct State column). Producers for
+// other backends map their own states onto the closed enum above; this table
+// is SLURM-specific and lives behind the `backend: 'slurm'` field.
+const SLURM_STATE_MAP = {
+    PENDING: 'submitted',
+    CONFIGURING: 'submitted',
+    RUNNING: 'running',
+    COMPLETING: 'running',
+    COMPLETED: 'completed-unverified',
+    FAILED: 'failed',
+    CANCELLED: 'cancelled',
+    TIMEOUT: 'timeout',
+    OUT_OF_MEMORY: 'failed',
+    BOOT_FAIL: 'failed',
+    NODE_FAIL: 'failed',
+    PREEMPTED: 'failed',
+};
+/**
+ * Map a raw SLURM state string to the closed, scheduler-agnostic manifest
+ * status. Case-insensitive; trims whitespace; strips a trailing by-part
+ * ("CANCELLED by 1001" -> "CANCELLED"). Returns `null` for any unknown
+ * state so the caller can decide whether to surface or fail — never guesses
+ * (CLAUDE.md anti-guessing).
+ */
+function mapSlurmState(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const key = raw.trim().toUpperCase();
+    const head = key.split(/\s+/)[0];
+    if (head && Object.prototype.hasOwnProperty.call(SLURM_STATE_MAP, head)) {
+        return SLURM_STATE_MAP[head];
+    }
+    return null;
+}
+const REQUIRED_FIELDS = [
+    'plan_id',
+    'phase',
+    'job_id',
+    'backend',
+    'submit_command',
+    'status',
+    'expected_artifacts',
+    'verification_command',
+    'resume_command',
+];
+function assertString(v, key) {
+    if (typeof v !== 'string' || v.length === 0) {
+        throw new Error(`buildManifest: field "${key}" must be a non-empty string`);
+    }
+}
+const STATUS_LIST = MANIFEST_STATUS;
+/**
+ * Build a versioned, frozen manifest. Stamps `version` and `submitted_at`
+ * (via the injected clock seam) and normalises `terminal_details`:
+ * `null` unless the status is a terminal failure AND details were supplied.
+ * Throws on missing required fields or an out-of-enum status.
+ */
+function buildManifest(input, opts = {}) {
+    const inputRecord = input;
+    for (const key of REQUIRED_FIELDS) {
+        const v = inputRecord[key];
+        if (key === 'expected_artifacts') {
+            if (!Array.isArray(v) || v.length === 0 || !v.every((x) => typeof x === 'string')) {
+                throw new Error('buildManifest: field "expected_artifacts" must be a non-empty string[]');
+            }
+            continue;
+        }
+        assertString(v, key);
+    }
+    if (!STATUS_LIST.includes(input.status)) {
+        throw new Error(`buildManifest: field "status" must be one of ${MANIFEST_STATUS.join(', ')}`);
+    }
+    const clock = opts.clock ?? { nowIso: () => new Date().toISOString() };
+    const isTerminalFailure = TERMINAL_FAILURE_STATUSES.includes(input.status);
+    const terminal_details = isTerminalFailure && input.terminal_details ? input.terminal_details : null;
+    return Object.freeze({
+        version: MANIFEST_VERSION,
+        job_id: input.job_id,
+        plan_id: input.plan_id,
+        phase: input.phase,
+        backend: input.backend,
+        submit_command: input.submit_command,
+        status: input.status,
+        expected_artifacts: [...input.expected_artifacts],
+        verification_command: input.verification_command,
+        resume_command: input.resume_command,
+        submitted_at: clock.nowIso(),
+        terminal_details,
+    });
+}
+/**
+ * Producer-side schema validator — the mirror of the consumer trust boundary
+ * (planning-artifacts.md). Producers MUST emit a manifest this accepts; the
+ * core loop re-validates defensively on read.
+ */
+function validateManifest(value) {
+    if (!value || typeof value !== 'object') {
+        return { ok: false, errors: ['manifest must be an object'] };
+    }
+    const m = value;
+    const errors = [];
+    if (m.version !== MANIFEST_VERSION)
+        errors.push(`version must be "${MANIFEST_VERSION}"`);
+    for (const f of ['job_id', 'plan_id', 'phase', 'backend', 'submit_command', 'verification_command', 'resume_command', 'submitted_at']) {
+        if (typeof m[f] !== 'string' || m[f].length === 0) {
+            errors.push(`field "${f}" must be a non-empty string`);
+        }
+    }
+    if (typeof m.status !== 'string' || !STATUS_LIST.includes(m.status)) {
+        errors.push(`status must be one of ${MANIFEST_STATUS.join(', ')}`);
+    }
+    if (!Array.isArray(m.expected_artifacts) || !m.expected_artifacts.every((x) => typeof x === 'string')) {
+        errors.push('expected_artifacts must be a string[]');
+    }
+    if (m.terminal_details !== null && typeof m.terminal_details !== 'object') {
+        errors.push('terminal_details must be null or an object');
+    }
+    return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+/**
+ * Parse `sbatch --parsable` output. Accepts either a bare job id
+ * (`"12345"`) or the `"12345;clustername"` form. Rejects prose like
+ * `"Submitted batch job 12345"` (that is the non-parsable default format).
+ */
+function parseSbatchParsable(stdout) {
+    if (typeof stdout !== 'string')
+        return { ok: false, kind: 'non_string', raw: String(stdout) };
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return { ok: false, kind: 'empty', raw: stdout };
+    const head = trimmed.split(';')[0].split(/\s+/)[0];
+    if (!/^\d+$/.test(head))
+        return { ok: false, kind: 'not_numeric', raw: trimmed };
+    return { ok: true, job_id: head };
+}
+/**
+ * Parse a single `squeue` line of the form `"<jobid> <state>"`. Returns `null`
+ * for a header or any row that does not have at least two tokens.
+ */
+function parseSqueueLine(line) {
+    if (typeof line !== 'string')
+        return null;
+    const parts = line.trim().split(/\s+/);
+    if (parts.length < 2)
+        return null;
+    const [job_id, state] = parts;
+    if (!/^\d+$/.test(job_id))
+        return null;
+    return { job_id, state };
+}
+/**
+ * Parse a `sacct -P` row given as pre-split columns where index 0 is the job
+ * id and index 1 is the state. Returns `null` for malformed rows.
+ */
+function parseSacctRow(cols) {
+    if (cols.length < 2)
+        return null;
+    const job_id = cols[0];
+    const state = cols[1];
+    if (typeof job_id !== 'string' || typeof state !== 'string')
+        return null;
+    if (!/^\d+$/.test(job_id))
+        return null;
+    return { job_id, state };
+}
+/**
+ * Pure path projection: `.planning/async-jobs/<job_id>.json`.
+ */
+function manifestPath(planningDir, jobId) {
+    return node_path_1.default.join(planningDir, 'async-jobs', `${jobId}.json`);
+}
+function _isNonTerminal(status) {
+    return typeof status === 'string' && NON_TERMINAL_STATUSES.includes(status);
+}
+/**
+ * Write a manifest to `.planning/async-jobs/<job_id>.json`.
+ *
+ * Fail-closed rules (mirror of the consumer contract, planning-artifacts.md):
+ *  - If any existing manifest in the dir shares `plan_id` but has a different
+ *    `job_id` AND is non-terminal -> refuse (`duplicate_plan_id`); dispatching
+ *    again would duplicate the external job.
+ *  - If the target file exists but is not valid JSON -> refuse
+ *    (`malformed_existing`); never silently clobber.
+ *  - Same `job_id` for the same `plan_id` -> allowed (status progression).
+ *  - A prior job for the same `plan_id` that is already terminal -> allowed
+ *    (the duplicate guard only protects against re-dispatching live work).
+ */
+function writeManifest(manifest, planningDir, opts = {}) {
+    const fs = opts.fs ?? node_fs_1.default;
+    const dir = node_path_1.default.join(planningDir, 'async-jobs');
+    const target = manifestPath(planningDir, manifest.job_id);
+    let names;
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        names = fs.readdirSync(dir);
+    }
+    catch (e) {
+        return { ok: false, kind: 'io_error', message: e.message };
+    }
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        const p = node_path_1.default.join(dir, name);
+        let raw;
+        try {
+            raw = String(fs.readFileSync(p));
+        }
+        catch {
+            continue;
+        }
+        let existing;
+        try {
+            existing = JSON.parse(raw);
+        }
+        catch {
+            if (p === target) {
+                return { ok: false, kind: 'malformed_existing', message: `target manifest ${p} is not valid JSON` };
+            }
+            continue;
+        }
+        const samePlan = existing.plan_id === manifest.plan_id;
+        const sameJob = existing.job_id === manifest.job_id;
+        if (samePlan && !sameJob && _isNonTerminal(existing.status)) {
+            return {
+                ok: false,
+                kind: 'duplicate_plan_id',
+                message: `plan_id "${manifest.plan_id}" already has non-terminal job "${String(existing.job_id)}" at ${p}; dispatching again would duplicate the external job`,
+            };
+        }
+    }
+    try {
+        fs.writeFileSync(target, JSON.stringify(manifest, null, 2) + '\n');
+    }
+    catch (e) {
+        return { ok: false, kind: 'io_error', message: e.message };
+    }
+    return { ok: true, path: target };
+}
+module.exports = {
+    MANIFEST_VERSION,
+    MANIFEST_STATUS,
+    NON_TERMINAL_STATUSES,
+    TERMINAL_FAILURE_STATUSES,
+    mapSlurmState,
+    buildManifest,
+    validateManifest,
+    parseSbatchParsable,
+    parseSqueueLine,
+    parseSacctRow,
+    writeManifest,
+    manifestPath,
+};

package/gsd-core/bin/lib/gate-predicate-evaluator.cjs

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * Gate Predicate Evaluator — issue #2008 / ADR-2008
+ *
+ * Pure, deps-injected evaluator for capability gate `check.predicate` blocks.
+ *
+ * Background: the loop-resolver renders active gate hooks (carrying their
+ * `check.predicate` declarations) but, prior to #2008, nothing EVALUATED a
+ * declared predicate for non-built-in capabilities — `check.query` was the only
+ * enforced shape (dispatched via `gsd_run check <query>`), and `check.predicate`
+ * was declaration-only. This module is the generic evaluation path.
+ *
+ * The workflow gate-dispatch calls this evaluator (via the `gsd_run check predicate`
+ * subcommand in check-command-router) for any gate whose `check` carries a
+ * `predicate` instead of a `query`. The evaluator dispatches by `predicate.kind`
+ * and returns the existing `{ block, message }` gate contract. A THROWN error
+ * (malformed predicate / unknown kind) is mapped by the CLI wrapper to a
+ * non-zero check-command exit, which the workflow's two-step gate contract treats
+ * as a step-1 command failure (routed per the gate's `onError`).
+ *
+ * Built-in kind (v1): `command-exit-zero` — run a declared command in a bounded
+ * `sh -c` subprocess at the project root, inheriting the process env; exit 0 =>
+ * pass, non-zero => block, timeout => block. The production runBoundedShell
+ * binding is shell-command-projection.execTool (bounded spawnSync). See ADR-2008
+ * for the full sandbox contract.
+ *
+ * This is a leaf pure module: no fs, no child_process, no config — the subprocess
+ * seam is injected so the evaluator is trivially testable without spawning.
+ */
+// ─── Public constants ─────────────────────────────────────────────────────────
+/** Default command timeout for `command-exit-zero` (30s). Matches execTool default. */
+const COMMAND_EXIT_ZERO_DEFAULT_TIMEOUT_MS = 30_000;
+/** Hard cap on the stderr/stdout tail embedded in the gate `message`. */
+const COMMAND_MAX_OUTPUT_CHARS = 2000;
+/** Hard cap on the declared command length (defense-in-depth against ARGV overflow / abuse). */
+const COMMAND_MAX_LENGTH = 4096;
+/** Predicate kinds this evaluator recognises (extensible — add to KIND_TABLE). */
+const EVALUATOR_KINDS = Object.freeze(['command-exit-zero']);
+/** Placeholders interpolated into a declared command, in addition to sh's own vars. */
+const INTERPOLATION_VAR_NAMES = Object.freeze(['PHASE_NUMBER', 'PHASE_DIR', 'PHASE_REQ_IDS']);
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+const INTERPOLATION_RE = /\$\{(PHASE_NUMBER|PHASE_DIR|PHASE_REQ_IDS)\}/g;
+/** Replace the three known ${PHASE_*} placeholders with context values (undefined => ''). */
+function interpolate(command, ctx) {
+    return command.replace(INTERPOLATION_RE, (_whole, name) => {
+        if (name === 'PHASE_NUMBER')
+            return ctx.phaseNumber ?? '';
+        if (name === 'PHASE_DIR')
+            return ctx.phaseDir ?? '';
+        if (name === 'PHASE_REQ_IDS')
+            return ctx.phaseReqIds ?? '';
+        return '';
+    });
+}
+/** Cap a string at COMMAND_MAX_OUTPUT_CHARS so gate messages stay context-bounded. */
+function trimToMax(s) {
+    return s.length > COMMAND_MAX_OUTPUT_CHARS ? s.slice(0, COMMAND_MAX_OUTPUT_CHARS) : s;
+}
+function isNonEmptyString(v) {
+    return typeof v === 'string' && v.trim().length > 0;
+}
+// ─── Kind: command-exit-zero ──────────────────────────────────────────────────
+function evaluateCommandExitZero(predicate, ctx, deps) {
+    const command = predicate['command'];
+    if (!isNonEmptyString(command)) {
+        throw new Error('command-exit-zero predicate requires a non-empty string "command"');
+    }
+    if (command.length > COMMAND_MAX_LENGTH) {
+        throw new Error(`command-exit-zero predicate "command" exceeds max length ${COMMAND_MAX_LENGTH}`);
+    }
+    let timeoutMs = COMMAND_EXIT_ZERO_DEFAULT_TIMEOUT_MS;
+    const rawTimeout = predicate['timeout'];
+    if (rawTimeout !== undefined) {
+        if (typeof rawTimeout !== 'number' || !Number.isFinite(rawTimeout) || rawTimeout <= 0) {
+            throw new Error('command-exit-zero predicate "timeout" must be a positive finite number (seconds)');
+        }
+        timeoutMs = Math.floor(rawTimeout * 1000);
+    }
+    const interpolated = interpolate(command, ctx);
+    const res = deps.runBoundedShell({ command: interpolated, cwd: ctx.cwd, timeoutMs });
+    if (res.timedOut) {
+        return {
+            block: true,
+            message: trimToMax(`command timed out after ${Math.round(timeoutMs / 1000)}s: ${res.stderr || interpolated}`),
+            details: { kind: 'command-exit-zero', timedOut: true, signal: res.signal },
+        };
+    }
+    if (res.exitCode === 0) {
+        return {
+            block: false,
+            message: 'command exited 0',
+            details: { kind: 'command-exit-zero', exitCode: 0 },
+        };
+    }
+    // Non-zero (incl. null exit from a signal kill) => block. Surface code + stderr/stdout tail.
+    const code = res.exitCode === null ? '<none>' : String(res.exitCode);
+    const tail = trimToMax(res.stderr || res.stdout || '');
+    const message = tail ? `command exited ${code}: ${tail}` : `command exited ${code}`;
+    return {
+        block: true,
+        message: trimToMax(message),
+        details: { kind: 'command-exit-zero', exitCode: res.exitCode, signal: res.signal },
+    };
+}
+// ─── Kind dispatch table ──────────────────────────────────────────────────────
+const KIND_TABLE = {
+    'command-exit-zero': evaluateCommandExitZero,
+};
+// ─── Public entry point ───────────────────────────────────────────────────────
+/**
+ * Evaluate a capability gate `check.predicate`.
+ *
+ * Returns `{ block, message }` for any successfully-recognised predicate.
+ * THROWS for a malformed predicate, missing context/deps, or unknown `kind` —
+ * the CLI wrapper converts a throw into a non-zero check-command exit so the
+ * workflow's `onError` (step-1) contract applies. This keeps the gate fail-closed
+ * without conflating an evaluator bug with a legitimate gate-block decision.
+ */
+function evaluatePredicate(predicate, context, deps) {
+    if (!predicate || typeof predicate !== 'object' || Array.isArray(predicate)) {
+        throw new Error('predicate must be an object');
+    }
+    const ctx = context;
+    if (!ctx || typeof ctx.cwd !== 'string' || ctx.cwd.length === 0) {
+        throw new Error('predicate context requires a non-empty "cwd"');
+    }
+    const d = deps;
+    if (!d || typeof d.runBoundedShell !== 'function') {
+        throw new Error('predicate deps require a "runBoundedShell" function');
+    }
+    const pred = predicate;
+    const kind = pred['kind'];
+    if (typeof kind !== 'string' || kind.length === 0) {
+        throw new Error('predicate.kind must be a non-empty string');
+    }
+    const handler = KIND_TABLE[kind];
+    if (!handler) {
+        throw new Error(`Unknown predicate kind: "${kind}". Known kinds: ${EVALUATOR_KINDS.join(', ')}`);
+    }
+    return handler(pred, ctx, d);
+}
+module.exports = {
+    evaluatePredicate,
+    evaluateCommandExitZero,
+    interpolate,
+    COMMAND_EXIT_ZERO_DEFAULT_TIMEOUT_MS,
+    COMMAND_MAX_OUTPUT_CHARS,
+    COMMAND_MAX_LENGTH,
+    EVALUATOR_KINDS,
+    INTERPOLATION_VAR_NAMES,
+};

package/gsd-core/bin/lib/graphify.cjs

@@ -261,6 +261,29 @@ function countCommitsBetween(cwd, from, to) {
     const n = parseInt(r.stdout.trim(), 10);
     return Number.isFinite(n) ? n : null;
 }
+// ─── Graph location resolution (#1825) ───────────────────────────────────────
+//
+// `graphify.graph_path` (in .planning/config.json) lets one umbrella-level graph
+// serve multiple sibling projects without a per-project mirror. When set, query /
+// status / diff read the configured graph, and the diff snapshot travels with it
+// (alongside graph.json). When unset/blank/non-string, behaviour is byte-identical
+// to the historical `<planningDir>/graphs/graph.json`.
+const GRAPH_FILENAME = 'graph.json';
+const SNAPSHOT_FILENAME = '.last-build-snapshot.json';
+/**
+ * Resolve the absolute graph.json location. Honors `graphify.graph_path` in
+ * config.json (resolved relative to the project root, `cwd`); falls back to the
+ * default `<planningDir>/graphs/graph.json` when unset/blank/non-string.
+ */
+function resolveGraphLocation(cwd, planningDir) {
+    const config = safeReadJson(node_path_1.default.join(planningDir, 'config.json'));
+    const graphify = (config && config['graphify']);
+    const configuredValue = graphify && graphify['graph_path'];
+    if (typeof configuredValue === 'string' && configuredValue.trim().length > 0) {
+        return { graphPath: node_path_1.default.resolve(cwd, configuredValue), configured: true };
+    }
+    return { graphPath: node_path_1.default.join(planningDir, 'graphs', GRAPH_FILENAME), configured: false };
+}
 /**
  * Query the knowledge graph for nodes matching a term, with optional budget cap.
  * Uses seed-then-expand BFS traversal (D-01).
@@ -269,9 +292,11 @@ function graphifyQuery(cwd, term, options = {}) {
     const planningDir = node_path_1.default.join(cwd, '.planning');
     if (!isCapabilityActive('graphify', cwd))
         return disabledResponse();
-    const graphPath = node_path_1.default.join(planningDir, 'graphs', 'graph.json');
+    const { graphPath, configured } = resolveGraphLocation(cwd, planningDir);
     if (!node_fs_1.default.existsSync(graphPath)) {
-        return { error: 'No graph built yet. Run graphify build first.' };
+        return { error: configured
+                ? `Configured graph not found at ${graphPath}. Set graphify.graph_path or run /gsd:graphify build.`
+                : 'No graph built yet. Run graphify build first.' };
     }
     const graph = safeReadJson(graphPath);
     if (!graph) {
@@ -303,9 +328,11 @@ function graphifyStatus(cwd) {
     const planningDir = node_path_1.default.join(cwd, '.planning');
     if (!isCapabilityActive('graphify', cwd))
         return disabledResponse();
-    const graphPath = node_path_1.default.join(planningDir, 'graphs', 'graph.json');
+    const { graphPath, configured } = resolveGraphLocation(cwd, planningDir);
     if (!node_fs_1.default.existsSync(graphPath)) {
-        return { exists: false, message: 'No graph built yet. Run graphify build to create one.' };
+        return { exists: false, message: configured
+                ? `Configured graph not found at ${graphPath}. Set graphify.graph_path or run /gsd:graphify build.`
+                : 'No graph built yet. Run graphify build to create one.' };
     }
     const stat = node_fs_1.default.statSync(graphPath);
     const graph = safeReadJson(graphPath);
@@ -360,8 +387,8 @@ function graphifyDiff(cwd) {
     const planningDir = node_path_1.default.join(cwd, '.planning');
     if (!isCapabilityActive('graphify', cwd))
         return disabledResponse();
-    const snapshotPath = node_path_1.default.join(planningDir, 'graphs', '.last-build-snapshot.json');
-    const graphPath = node_path_1.default.join(planningDir, 'graphs', 'graph.json');
+    const { graphPath } = resolveGraphLocation(cwd, planningDir);
+    const snapshotPath = node_path_1.default.join(node_path_1.default.dirname(graphPath), SNAPSHOT_FILENAME);
     if (!node_fs_1.default.existsSync(snapshotPath)) {
         return { no_baseline: true, message: 'No previous snapshot. Run graphify build first, then build again to generate a diff baseline.' };
     }
@@ -405,7 +432,11 @@ function graphifyBuild(cwd) {
     if (!installed.installed)
         return { error: installed.message };
     const version = checkGraphifyVersion();
-    // Ensure output directory exists (D-05)
+    // Ensure output directory exists (D-05). Build stays project-scoped: the build
+    // skill cp's artifacts into `<planningDir>/graphs/` regardless of graph_path, so
+    // graphs_dir reflects that real destination (not the configured read location).
+    // A shared umbrella graph is built in the umbrella project; sub-projects only
+    // READ it via graphify.graph_path (#1825).
     const graphsDir = node_path_1.default.join(planningDir, 'graphs');
     node_fs_1.default.mkdirSync(graphsDir, { recursive: true });
     // Read build timeout from config -- default 300s per D-02
@@ -428,7 +459,8 @@ function graphifyBuild(cwd) {
  * using platformWriteSync for crash safety.
  */
 function writeSnapshot(cwd) {
-    const graphPath = node_path_1.default.join(cwd, '.planning', 'graphs', 'graph.json');
+    const planningDir = node_path_1.default.join(cwd, '.planning');
+    const { graphPath } = resolveGraphLocation(cwd, planningDir);
     const graph = safeReadJson(graphPath);
     if (!graph)
         return { error: 'Cannot write snapshot: graph.json not parseable' };
@@ -438,7 +470,7 @@ function writeSnapshot(cwd) {
         nodes: graph.nodes || [],
         edges: graph.edges || graph.links || [],
     };
-    const snapshotPath = node_path_1.default.join(cwd, '.planning', 'graphs', '.last-build-snapshot.json');
+    const snapshotPath = node_path_1.default.join(node_path_1.default.dirname(graphPath), SNAPSHOT_FILENAME);
     (0, shell_command_projection_cjs_1.platformWriteSync)(snapshotPath, JSON.stringify(snapshot, null, 2));
     return {
         saved: true,

package/gsd-core/bin/lib/init-command-router.cjs

@@ -39,6 +39,10 @@ function routeInitCommand({ init, args, cwd, raw, error }) {
             },
             'new-project': () => init.cmdInitNewProject(cwd, raw),
             'new-milestone': () => init.cmdInitNewMilestone(cwd, raw),
+            onboard: () => {
+                const namedArgs = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, [], ['fast', 'text']);
+                init.cmdInitOnboard(cwd, raw, { fast: namedArgs['fast'], text: namedArgs['text'] });
+            },
             quick: () => init.cmdInitQuick(cwd, args.slice(2).join(' '), raw),
             'ingest-docs': () => init.cmdInitIngestDocs(cwd, raw),
             resume: () => init.cmdInitResume(cwd, raw),