@gobing-ai/spur 0.3.94 → 0.3.95

package/plugins/sp/scripts/script-root.ts

@@ -0,0 +1,195 @@
+#!/usr/bin/env bun
+/**
+ * script-root — run-start script-resolution identity for the sp pipelines (task 0960 R2).
+ *
+ * WHY: the pipeline YAML ships to every consumer, but its script probes resolved
+ * `plugins/sp/scripts/` **project-first**. A consumer that hand-vendored a stale copy then ran
+ * a different revision than the installed twin, mixing revisions across steps that write and
+ * read the same cross-step artifacts (status files, verdicts, proof digests). The probe is
+ * dogfooding-only, so it is now gated on `config/plugin-scripts.json` — a marker that lives
+ * outside `plugins/sp/`, so copying the plugin tree cannot reproduce it.
+ *
+ * This script records *which* tree a run resolved, once, before any step executes:
+ *   `.spur/run/<runId>-script-root.json`  `{ mode, source, dir, scriptSetDigest }`
+ *
+ * - `source-repo` — the marker is present; the project's live `plugins/sp/scripts/` is the
+ *   resolved tree (the dogfood path).
+ * - `installed` — no marker; the tree is `dirname(superskill script path sp script-root.mjs
+ *   --json .path)`, with `source` from the same probe. One stderr warning names a dead
+ *   vendored `plugins/sp/scripts/` dir that is no longer executed.
+ * - `unresolved` — nothing resolved. Written with an `error` and **exit 0**: a missing
+ *   optional script must stay a per-step fail-closed outcome, never a run-wide abort (R3).
+ *
+ * `scriptSetDigest` is one sha256 over the sorted `name:sha256` list of the resolved dir's
+ * regular files (non-recursive) — the installed staging has no version file, so this answers
+ * "which revision produced this run?" without a Superskill change.
+ *
+ * Node/bun builtins and the vendored `../lib/env` gateway only — bundled standalone by
+ * `superskill install`, so no `@gobing-ai/*` value imports (task 0669).
+ */
+
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { getEnvVars } from '../lib/env';
+
+export type ScriptRootMode = 'source-repo' | 'installed' | 'unresolved';
+
+export interface ScriptRoot {
+    mode: ScriptRootMode;
+    source?: string;
+    dir?: string;
+    scriptSetDigest?: string;
+    error?: string;
+}
+
+export interface ScriptRootResult extends ScriptRoot {
+    resultFile: string;
+    exitCode: number;
+}
+
+export interface ScriptRootEnv {
+    __runId?: string;
+    [key: string]: string | undefined;
+}
+
+/** Resolved script descriptor from `superskill script path sp <rel> --json`. */
+export interface ResolvedScript {
+    path?: string;
+    source?: string;
+}
+
+export interface ScriptRootOptions {
+    /** Base directory for `.spur/run` and the project marker; defaults to process cwd. */
+    cwd?: string;
+    /** Test seam: run `superskill script path sp script-root.mjs --json`. */
+    resolveScript?: (rel: string) => ResolvedScript | null;
+    /** Test seam: the one-warning sink. */
+    warn?: (message: string) => void;
+}
+
+/** Marker that identifies the Spur source repo (owned by script-contract-check, outside plugins/sp). */
+export const SOURCE_REPO_MARKER = join('config', 'plugin-scripts.json');
+/** The project-first tree the dogfood probes execute. */
+export const PROJECT_SCRIPTS_DIR = join('plugins', 'sp', 'scripts');
+/** The rel the installed twin resolves under (its own staging name). */
+export const SCRIPT_ROOT_TWIN_REL = 'script-root.mjs';
+
+function defaultResolveScript(cwd?: string): (rel: string) => ResolvedScript | null {
+    return (rel: string): ResolvedScript | null => {
+        const run = spawnSync('superskill', ['script', 'path', 'sp', rel, '--json'], {
+            cwd,
+            encoding: 'utf8',
+            env: getEnvVars(),
+        });
+        if (run.status !== 0 || !run.stdout) return null;
+        const lastLine = run.stdout.trim().split('\n').pop() ?? '';
+        try {
+            const parsed = JSON.parse(lastLine) as ResolvedScript;
+            return typeof parsed.path === 'string' && parsed.path.length > 0 ? parsed : null;
+        } catch {
+            return null;
+        }
+    };
+}
+
+/** sha256 over the sorted `name:sha256` list of `dir`'s regular files (non-recursive). */
+export function digestScriptSet(dir: string, cwd?: string): string {
+    const abs = cwd ? join(cwd, dir) : dir;
+    const names = readdirSync(abs)
+        .filter((name) => {
+            try {
+                return statSync(join(abs, name)).isFile();
+            } catch {
+                return false;
+            }
+        })
+        .sort();
+    const list = names.map(
+        (name) =>
+            `${name}:${createHash('sha256')
+                .update(readFileSync(join(abs, name)))
+                .digest('hex')}`,
+    );
+    return `sha256:${createHash('sha256').update(list.join('\n')).digest('hex')}`;
+}
+
+/**
+ * Resolve the run's script root and write `.spur/run/<runId>-script-root.json`.
+ * Never aborts: every failure is recorded as `mode: "unresolved"` with exit 0 (R3).
+ */
+export function runScriptRoot(env: ScriptRootEnv, options: ScriptRootOptions = {}): ScriptRootResult {
+    const cwd = options.cwd;
+    const runId = env.__runId ?? env.runId ?? '';
+    const relResult = join('.spur', 'run', `${runId}-script-root.json`);
+    const abs = (p: string): string => (cwd ? join(cwd, p) : p);
+    const warn = options.warn ?? ((message: string): void => void process.stderr.write(`${message}\n`));
+    mkdirSync(abs(join('.spur', 'run')), { recursive: true });
+
+    const write = (row: ScriptRoot): ScriptRootResult => {
+        writeFileSync(abs(relResult), `${JSON.stringify(row)}\n`);
+        return { ...row, resultFile: relResult, exitCode: 0 };
+    };
+
+    // Source repo: the project's live tree is the resolved tree (R6).
+    if (existsSync(abs(SOURCE_REPO_MARKER))) {
+        try {
+            return write({
+                mode: 'source-repo',
+                source: 'project',
+                dir: PROJECT_SCRIPTS_DIR,
+                scriptSetDigest: digestScriptSet(PROJECT_SCRIPTS_DIR, cwd),
+            });
+        } catch (error) {
+            return write({ mode: 'unresolved', error: `source-repo digest failed: ${String(error)}` });
+        }
+    }
+
+    // Installed: resolve the twin, and name a dead vendored dir that is no longer executed.
+    if (existsSync(abs(PROJECT_SCRIPTS_DIR))) {
+        warn(
+            `script-root: ignoring vendored ${PROJECT_SCRIPTS_DIR}/ (no ${SOURCE_REPO_MARKER} marker) — ` +
+                `steps resolve the installed twin via 'superskill script path sp <rel>'`,
+        );
+    }
+    const resolve = options.resolveScript ?? defaultResolveScript(cwd);
+    const resolved = resolve(SCRIPT_ROOT_TWIN_REL);
+    if (!resolved?.path) {
+        return write({
+            mode: 'unresolved',
+            error: `'superskill script path sp ${SCRIPT_ROOT_TWIN_REL}' resolved nothing`,
+        });
+    }
+    const dir = dirname(resolved.path);
+    try {
+        return write({
+            mode: 'installed',
+            source: resolved.source ?? 'unknown',
+            dir,
+            scriptSetDigest: digestScriptSet(dir),
+        });
+    } catch (error) {
+        return write({ mode: 'unresolved', error: `installed digest failed: ${String(error)}` });
+    }
+}
+
+export const SCRIPT_ROOT_USAGE = 'usage: script-root --run-id <id>';
+
+export function main(argv: string[], env: ScriptRootEnv = getEnvVars(), options: ScriptRootOptions = {}): number {
+    let runId = env.__runId ?? '';
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--run-id') {
+            runId = argv[i + 1] ?? '';
+            i++;
+            continue;
+        }
+        process.stderr.write(`${SCRIPT_ROOT_USAGE}\n`);
+        return 2;
+    }
+    return runScriptRoot({ ...env, __runId: runId }, options).exitCode;
+}
+
+if (import.meta.main) {
+    process.exit(main(process.argv.slice(2)));
+}

package/plugins/sp/scripts/stage-registry-adapter.ts

@@ -1281,7 +1281,7 @@ function resolveFeature(input: ResolutionInput): StageResolution {
             reasonKind: 'dispatch',
             requiresConfirmation: row.requiresConfirmation,
             chain: false,
-            dispatchCommand: dispatchCmd,
+            dispatchCommand: dispatchCmd ?? null,
             nextObservableOutcome: row.rowId === 'B6' ? 'feature transition or wrap' : undefined,
         };
     }

package/plugins/sp/scripts/task-evidence-precheck.ts

@@ -59,7 +59,8 @@ function usage(): never {
 }
 
 function defaultSpurBin(): string {
-    if (getEnvVar('SPUR_BIN')) return getEnvVar('SPUR_BIN');
+    const fromEnv = getEnvVar('SPUR_BIN');
+    if (fromEnv) return fromEnv;
     const local = fileURLToPath(new URL('../../../apps/cli/src/index.ts', import.meta.url));
     if (existsSync(local)) return `bun ${local}`;
     return 'spur';
@@ -71,6 +72,7 @@ function parseArgs(argv: string[]): { wbs: string; spurBin: string } {
     let i = 0;
     while (i < argv.length) {
         const arg = argv[i];
+        if (arg === undefined) break;
         if (arg === '--spur-bin') {
             spurBin = argv[i + 1] ?? defaultSpurBin();
             i += 2;
@@ -109,7 +111,7 @@ function writeStatus(wbs: string, status: 'PASS' | 'FAIL'): void {
     writeFileSync(join(statusDir, `${wbs}-precheck-evidence.status`), `${status}\n`);
 }
 
-function fail(wbs: string, reasons: string[]): void {
+function fail(wbs: string, reasons: string[]): never {
     writeStatus(wbs, 'FAIL');
     console.error(`task-evidence-precheck: FAIL`);
     for (const r of reasons) {

package/plugins/sp/scripts/task-size-precheck.ts

@@ -89,7 +89,8 @@ function usage(): never {
  * keeps ad-hoc invocations from silently hitting a stale PATH install.
  */
 function defaultSpurBin(): string {
-    if (getEnvVar('SPUR_BIN')) return getEnvVar('SPUR_BIN');
+    const fromEnv = getEnvVar('SPUR_BIN');
+    if (fromEnv) return fromEnv;
     // scripts/ -> plugins/sp/ -> <repo>/apps/cli/src/index.ts (fileURLToPath — raw pathname breaks
     // on %-encoded paths, e.g. spaces in the checkout directory)
     const local = fileURLToPath(new URL('../../../apps/cli/src/index.ts', import.meta.url));
@@ -115,6 +116,7 @@ function parseArgs(argv: string[]): {
     let i = 0;
     while (i < argv.length) {
         const arg = argv[i];
+        if (arg === undefined) break;
         if (arg === '--spur-bin') {
             spurBin = argv[i + 1] ?? defaultSpurBin();
             i += 2;

package/plugins/sp/scripts/validate-commands.ts

@@ -66,7 +66,7 @@ function parseCommand(filePath: string, name: string): ParsedCommand {
     // Extract frontmatter between --- delimiters
     const fmMatch = raw.match(/^---\n([\s\S]*?)\n---/);
     const body = fmMatch ? raw.slice(fmMatch[0].length).trim() : raw;
-    const fm = fmMatch ? fmMatch[1] : '';
+    const fm = fmMatch?.[1] ?? '';
 
     const description = extractYamlField(fm, 'description');
     const argumentHint = extractYamlField(fm, 'argument-hint');
@@ -124,9 +124,9 @@ function parseCommand(filePath: string, name: string): ParsedCommand {
 /** Extract a plain YAML string field (handles quoted and unquoted). */
 function extractYamlField(fm: string, key: string): string | undefined {
     const re = new RegExp(`^${key}:\\s*(.+)$`, 'm');
-    const m = fm.match(re);
-    if (!m) return undefined;
-    const value = m[1].trim();
+    const m = fm.match(re)?.[1];
+    if (m === undefined) return undefined;
+    const value = m.trim();
     // Unquote double-quoted YAML scalars
     if (value.startsWith('"') && value.endsWith('"')) {
         return value.slice(1, -1).replace(/\\"/g, '"');
@@ -137,9 +137,9 @@ function extractYamlField(fm: string, key: string): string | undefined {
 /** Extract a YAML flow list ["A", "B"]. */
 function extractYamlList(fm: string, key: string): string[] | undefined {
     const re = new RegExp(`^${key}:\\s*\\[(.*)\\]$`, 'm');
-    const m = fm.match(re);
-    if (!m) return undefined;
-    return [...m[1].matchAll(/"([^"]*)"/g)].map((q) => q[1]);
+    const m = fm.match(re)?.[1];
+    if (m === undefined) return undefined;
+    return [...m.matchAll(/"([^"]*)"/g)].map((q) => q[1] ?? '');
 }
 
 const ALLOWED_HEADINGS: Record<string, true> = { Usage: true, Implementation: true };
@@ -262,7 +262,7 @@ function checkTargetResolution(cmd: ParsedCommand, skillsDir: string, root: stri
 
     // Extract ## Implementation section content
     const implPart = cmd.body.split(/^## Implementation\n/m)[1] ?? '';
-    const implSection = implPart.split(/\n## (?!Usage)/m)[0].trim();
+    const implSection = (implPart.split(/\n## (?!Usage)/m)[0] ?? '').trim();
 
     // Skill() calls: Skill(skill="sp:NAME",
     // The name charset must stay at least as wide as any name a skill directory can
@@ -270,7 +270,7 @@ function checkTargetResolution(cmd: ParsedCommand, skillsDir: string, root: stri
     // would pass a genuinely unresolved reference rather than report it.
     const skillCalls = [...implSection.matchAll(/Skill\(skill="sp:([a-z][a-z0-9-]*)"/g)];
     for (const ref of skillCalls) {
-        const skillName = ref[1];
+        const skillName = ref[1] ?? '';
         const skillPath = join(skillsDir, skillName, 'SKILL.md');
         if (!existsSync(skillPath)) {
             violations.push({
@@ -304,7 +304,7 @@ function checkTargetResolution(cmd: ParsedCommand, skillsDir: string, root: stri
     // Procedure reference + anchor — markdown links with anchors in Implementation
     const anchorRefs = [...implSection.matchAll(/\[([^\]]*)\]\(([^)]*#([^)]*))\)/g)];
     for (const ref of anchorRefs) {
-        const filePart = ref[2].split('#')[0];
+        const filePart = (ref[2] ?? '').split('#')[0] ?? '';
         const anchor = ref[3];
         // Resolve relative paths from commands/ directory
         const resolved = resolve(join(root, 'plugins', 'sp', 'commands'), filePart);
@@ -414,7 +414,7 @@ function parseMarkdownTable(section: string): MarkdownTable | null {
             .replace(/\|$/, '')
             .split(/(?<!\\)\|/)
             .map((c) => c.trim().replace(/\\\|/g, '|'));
-    const header = split(tableLines[0]);
+    const header = split(tableLines[0] ?? '');
     // Skip the separator row (--- cells).
     const dataRows = tableLines
         .slice(1)
@@ -430,7 +430,7 @@ function parseMarkdownTable(section: string): MarkdownTable | null {
 function extractHintTokens(hint: string): { positionals: string[]; flags: string[] } {
     const positionals = [...hint.matchAll(/<[^>]+>/g)].map((m) => m[0]);
     // Flags: capture the `--flag` literal, ignoring the value placeholder that follows.
-    const flags = [...hint.matchAll(/(--[a-z][a-z0-9-]*)/g)].map((m) => m[1]);
+    const flags = [...hint.matchAll(/(--[a-z][a-z0-9-]*)/g)].map((m) => m[1] ?? '');
     // Deduplicate while preserving order.
     return {
         positionals: [...new Set(positionals)],

package/plugins/sp/scripts/validate-flag-contracts.ts

@@ -71,7 +71,7 @@ function sectionBetween(raw: string, startRe: RegExp, nextHeading: '## ' | '###
 function extractFlags(text: string): Set<string> {
     const flags = new Set<string>();
     for (const m of text.matchAll(/(--[a-z][a-z-]*)/g)) {
-        flags.add(m[1]);
+        flags.add(m[1] ?? '');
     }
     return flags;
 }
@@ -80,7 +80,7 @@ function extractFlags(text: string): Set<string> {
 function deprecatedFlagSet(hint: string): Set<string> {
     const out = new Set<string>();
     for (const m of hint.matchAll(/(--[a-z][a-z-]*)\s*\(deprecated\)/g)) {
-        out.add(m[1]);
+        out.add(m[1] ?? '');
     }
     return out;
 }
@@ -104,7 +104,7 @@ function glossaryEntries(glossaryRaw: string): GlossaryEntry[] {
     const entryRe = /^### `(--[a-z][a-z-]*)[^\n]*$/gm;
     for (const m of glossaryRaw.matchAll(entryRe)) {
         const flag = m[1];
-        if (m.index === undefined) continue;
+        if (flag === undefined || m.index === undefined) continue;
         const bodyStart = m.index + m[0].length;
         const next = glossaryRaw.indexOf('\n### ', bodyStart);
         const body = next === -1 ? glossaryRaw.slice(bodyStart) : glossaryRaw.slice(bodyStart, next);
@@ -132,8 +132,8 @@ function glossaryDeclaringClaims(glossaryRaw: string): Map<string, Set<string>>
     for (const { flag, firstParagraph } of glossaryEntries(glossaryRaw)) {
         const names = new Set<string>();
         for (const paren of firstParagraph.matchAll(/\(([^)]*)\)/g)) {
-            for (const n of paren[1].matchAll(/`(dev-[a-z-]+)`/g)) {
-                names.add(n[1]);
+            for (const n of (paren[1] ?? '').matchAll(/`(dev-[a-z-]+)`/g)) {
+                names.add(n[1] ?? '');
             }
         }
         if (names.size >= 2) claims.set(flag, names);
@@ -210,7 +210,7 @@ function commandTableDefaults(commandRaw: string): Map<string, string> {
     if (!start || start.index === undefined) return out;
     const from = start.index + start[0].length;
     const next = commandRaw.indexOf('\n## ', from);
-    const table = (next === -1 ? commandRaw.slice(from) : commandRaw.slice(from, next)).split(/\n\s*\n/)[0];
+    const table = (next === -1 ? commandRaw.slice(from) : commandRaw.slice(from, next)).split(/\n\s*\n/)[0] ?? '';
     // Split on unescaped pipes only (same as validate-commands.ts parseMarkdownTable),
     // then unescape `\|` → `|` per cell.
     const split = (row: string): string[] =>
@@ -223,10 +223,11 @@ function commandTableDefaults(commandRaw: string): Map<string, string> {
         const trimmed = line.trim();
         if (!trimmed.startsWith('|')) continue;
         const cells = split(trimmed);
-        if (cells.length < 3 || cells[0].startsWith('---') || cells[0] === 'Flag') continue;
-        const flag = cells[0].replace(/`/g, '').split(/\s/)[0];
+        const first = cells[0] ?? '';
+        if (cells.length < 3 || first.startsWith('---') || first === 'Flag') continue;
+        const flag = first.replace(/`/g, '').split(/\s/)[0] ?? '';
         if (!flag.startsWith('--')) continue;
-        out.set(flag, cells[2].replace(/[`*]/g, '').trim());
+        out.set(flag, (cells[2] ?? '').replace(/[`*]/g, '').trim());
     }
     return out;
 }
@@ -237,7 +238,7 @@ function commandToOpHeader(opsRaw: string): Map<string, string> {
     const rowRe = /^\|\s*(\d+[a-z]?)\s*\|\s*([a-z-]+)\s*\|\s*`(dev-[a-z-]+)`/;
     for (const line of opsRaw.split('\n')) {
         const m = line.match(rowRe);
-        if (m) map.set(m[3], `${m[1]}. ${m[2]}`);
+        if (m) map.set(m[3] ?? '', `${m[1] ?? ''}. ${m[2] ?? ''}`);
     }
     return map;
 }
@@ -249,17 +250,18 @@ function opsSectionDefaults(sectionBody: string): Map<string, { value: string; c
         // Pair each default marker with the flag mentioned immediately before it on the line.
         const flags: Array<{ name: string; index: number }> = [];
         for (const m of line.matchAll(/`(--[a-z][a-z-]*)(?: <[^>]+>)?`/g)) {
-            flags.push({ name: m[1], index: m.index });
+            flags.push({ name: m[1] ?? '', index: m.index });
         }
         for (const m of line.matchAll(/\(default:?\s*\*?\*?`?([^`);]+?)\s*`?[;)]/g)) {
-            const value = m[1].replace(/[`*]/g, '').trim();
+            const value = (m[1] ?? '').replace(/[`*]/g, '').trim();
             const preceding = flags.filter((f) => f.index < m.index).pop();
             if (!preceding) continue;
             out.set(preceding.name, { value, claim: line.trim() });
         }
         // `X (default)` trailing form (e.g. "**`full`** (default):" in Modes prose).
         for (const m of line.matchAll(/`([^`]+)`\s*\(default\)/g)) {
-            out.set(m[1], { value: m[1], claim: line.trim() });
+            const v = m[1] ?? '';
+            out.set(v, { value: v, claim: line.trim() });
         }
     }
     return out;
@@ -369,11 +371,12 @@ export function extractValueBehaviorTable(
             .replace(/^\||\|$/g, '')
             .split('|')
             .map((c) => c.trim());
-        if (cells.length < 3 || cells[0].startsWith('---') || cells[0] === 'Value') continue;
-        const valueCell = cells[0].replace(/`/g, '').trim();
-        const value = valueCell.split(/\s/)[0];
+        const first = cells[0] ?? '';
+        if (cells.length < 3 || first.startsWith('---') || first === 'Value') continue;
+        const valueCell = first.replace(/`/g, '').trim();
+        const value = valueCell.split(/\s/)[0] ?? '';
         if (value !== 'inline' && value !== 'auto' && value !== '<name>') continue;
-        const behavior = normalizeSurfaceCell(cells[2]);
+        const behavior = normalizeSurfaceCell(cells[2] ?? '');
         out.set(value, { ...behavior, defaultWhenOmitted: /default when omitted/i.test(valueCell) });
     }
     return out.size === 3 ? out : null;
@@ -395,9 +398,10 @@ export function extractTriggerTable(crossCuttingRaw: string): string[] | null {
             .replace(/^\||\|$/g, '')
             .split('|')
             .map((c) => c.trim());
-        if (cells.length < 3 || cells[0].startsWith('---')) continue;
-        if (cells[0] === 'Trigger') continue;
-        rows.push(cells[0].replace(/\*\*/g, '').replace(/\.\s*$/, ''));
+        const first = cells[0] ?? '';
+        if (cells.length < 3 || first.startsWith('---')) continue;
+        if (first === 'Trigger') continue;
+        rows.push(first.replace(/\*\*/g, '').replace(/\.\s*$/, ''));
     }
     return rows.length >= 4 ? rows : null;
 }
@@ -414,8 +418,12 @@ function adrAgentClaims(adrRaw: string): Map<string, SurfaceBehavior> | null {
             conditional: false,
             defaultWhenOmitted: false,
         });
-        out.set('auto', { surfaces: new Set(['subprocess']), conditional: false });
-        out.set('<name>', { surfaces: new Set(['inline', 'subprocess']), conditional: true });
+        out.set('auto', { surfaces: new Set(['subprocess']), conditional: false, defaultWhenOmitted: false });
+        out.set('<name>', {
+            surfaces: new Set(['inline', 'subprocess']),
+            conditional: true,
+            defaultWhenOmitted: false,
+        });
         return out;
     }
     // Slice from the `## ADR-041` heading to the next `## ADR-` heading or end of input
@@ -429,7 +437,11 @@ function adrAgentClaims(adrRaw: string): Map<string, SurfaceBehavior> | null {
     const out = new Map<string, SurfaceBehavior>();
     // Rule sentence: "if the named executor is … inline; otherwise … subprocess" → <name> conditional.
     if (/the work happens inline;\s*otherwise it dispatches a subprocess/.test(section)) {
-        out.set('<name>', { surfaces: new Set(['inline', 'subprocess']), conditional: true });
+        out.set('<name>', {
+            surfaces: new Set(['inline', 'subprocess']),
+            conditional: true,
+            defaultWhenOmitted: false,
+        });
     }
     // Collapse mapping: `--subprocess` → `--agent <target>`. The target value's behavior is
     // claimed by the mapping itself — parse the target generically so a drifted mapping
@@ -438,12 +450,12 @@ function adrAgentClaims(adrRaw: string): Map<string, SurfaceBehavior> | null {
     // `--subprocess` is matched explicitly (`` `--subprocess` `` in the source).
     const subprocessTarget = section.match(/--subprocess`\s*→\s*`--agent ([a-z]+)/)?.[1];
     if (subprocessTarget === 'auto') {
-        out.set('auto', { surfaces: new Set(['subprocess']), conditional: false });
+        out.set('auto', { surfaces: new Set(['subprocess']), conditional: false, defaultWhenOmitted: false });
     } else if (subprocessTarget === 'inline') {
-        out.set('auto', { surfaces: new Set(['inline']), conditional: false });
+        out.set('auto', { surfaces: new Set(['inline']), conditional: false, defaultWhenOmitted: false });
     }
     if (/--inline`\s*→\s*`--agent inline/.test(section)) {
-        out.set('inline', { surfaces: new Set(['inline']), conditional: false });
+        out.set('inline', { surfaces: new Set(['inline']), conditional: false, defaultWhenOmitted: false });
     }
     return out.size === 0 ? null : out;
 }
@@ -637,8 +649,8 @@ export function checkAgentSsotIntegrity(files: ReadonlyMap<string, string>): Fla
         for (const block of tableBlocks) {
             const valuesFound = new Set<string>();
             for (const row of block) {
-                const firstCell = row.replace(/^\|/, '').split('|')[0].replace(/`/g, '').trim();
-                const token = firstCell.split(/\s/)[0].toLowerCase();
+                const firstCell = (row.replace(/^\|/, '').split('|')[0] ?? '').replace(/`/g, '').trim();
+                const token = (firstCell.split(/\s/)[0] ?? '').toLowerCase();
                 if (token === 'inline' || token === 'auto' || token === '<name>') {
                     valuesFound.add(token);
                 }
@@ -684,7 +696,7 @@ export function headingAnchors(raw: string): Set<string> {
     const anchors = new Set<string>();
     for (const line of raw.split('\n')) {
         const m = line.match(/^#{1,6}\s+(.*)$/);
-        if (m) anchors.add(headingSlug(m[1]));
+        if (m) anchors.add(headingSlug(m[1] ?? ''));
     }
     return anchors;
 }
@@ -704,7 +716,7 @@ export function checkSsotAnchorsResolve(crossCuttingRaw: string, files: Readonly
     for (const [filename, raw] of files) {
         const seen = new Set<string>();
         for (const m of raw.matchAll(/cross-cutting\.md#([\w-]+)/g)) {
-            const anchor = m[1];
+            const anchor = m[1] ?? '';
             if (anchors.has(anchor) || seen.has(anchor)) continue;
             seen.add(anchor);
             violations.push({

package/plugins/sp/scripts/verify-answer-lint.ts

@@ -42,7 +42,8 @@ function usage(): never {
 }
 
 function defaultSpurBin(): string {
-    if (getEnvVar('SPUR_BIN')) return getEnvVar('SPUR_BIN');
+    const fromEnv = getEnvVar('SPUR_BIN');
+    if (fromEnv) return fromEnv;
     const local = fileURLToPath(new URL('../../../apps/cli/src/index.ts', import.meta.url));
     if (existsSync(local)) return `bun ${local}`;
     return 'spur';
@@ -55,6 +56,7 @@ function parseArgs(argv: string[]): { wbs: string; answer: string; spurBin: stri
     let i = 0;
     while (i < argv.length) {
         const arg = argv[i];
+        if (arg === undefined) break;
         if (arg === '--spur-bin') {
             spurBin = argv[i + 1] ?? defaultSpurBin();
             i += 2;

package/plugins/sp/scripts/workflow-step-profile.mjs

@@ -176,8 +176,9 @@ function formatStepProfileHuman(profile) {
 `;
 }
 function defaultSpurBin() {
-  if (getEnvVar("SPUR_BIN"))
-    return getEnvVar("SPUR_BIN");
+  const fromEnv = getEnvVar("SPUR_BIN");
+  if (fromEnv)
+    return fromEnv;
   const local = fileURLToPath(new URL("../../../apps/cli/src/index.ts", import.meta.url));
   if (existsSync(local))
     return `bun ${local}`;
@@ -196,6 +197,8 @@ function parseStepProfileCliArgs(argv) {
   let help = false;
   for (let i = 0;i < argv.length; i++) {
     const a = argv[i];
+    if (a === undefined)
+      continue;
     if (a === "--help" || a === "-h")
       help = true;
     else if (a === "--json")

package/plugins/sp/scripts/workflow-step-profile.ts

@@ -322,7 +322,8 @@ export interface StepProfileCliArgs {
  * --spur-bin > SPUR_BIN > monorepo-local CLI entry > PATH `spur`.
  */
 export function defaultSpurBin(): string {
-    if (getEnvVar('SPUR_BIN')) return getEnvVar('SPUR_BIN');
+    const fromEnv = getEnvVar('SPUR_BIN');
+    if (fromEnv) return fromEnv;
     const local = fileURLToPath(new URL('../../../apps/cli/src/index.ts', import.meta.url));
     if (existsSync(local)) return `bun ${local}`;
     return 'spur';
@@ -343,6 +344,7 @@ export function parseStepProfileCliArgs(argv: string[]): StepProfileCliArgs {
 
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
+        if (a === undefined) continue;
         if (a === '--help' || a === '-h') help = true;
         else if (a === '--json') json = true;
         else if (a === '--last') last = positiveInt(argv[++i], last);

package/plugins/sp/scripts/wrapup-drift-probe.mjs

@@ -57,6 +57,8 @@ function changedPathsOf(section) {
   const paths = [];
   for (const match of section.matchAll(CHANGE_ENTRY)) {
     const path = match[1];
+    if (path === undefined)
+      continue;
     if (/\s/.test(path))
       continue;
     if (!path.includes("/") && !path.includes("."))
@@ -73,7 +75,8 @@ var SURFACE_MATCHERS = DOC_OWNED_SURFACES.map((glob) => ({ glob, regex: surfaceR
 function driftReasonForPath(path) {
   if (CORPUS_PREFIXES.some((prefix) => path.startsWith(prefix)))
     return null;
-  if (path.includes("/") && !KNOWN_TOP_LEVEL.has(path.split("/")[0])) {
+  const top = path.split("/")[0];
+  if (path.includes("/") && top !== undefined && !KNOWN_TOP_LEVEL.has(top)) {
     return "new top-level workspace directory";
   }
   const match = SURFACE_MATCHERS.find((entry) => entry.regex.test(path));
@@ -82,7 +85,7 @@ function driftReasonForPath(path) {
 function defaultSpurRunner(env, cwd) {
   const parts = (env.spurBin ?? "spur").split(/\s+/).filter((part) => part.length > 0);
   return (args) => {
-    const run = spawnSync(parts[0], [...parts.slice(1), ...args], {
+    const run = spawnSync(parts[0] ?? "spur", [...parts.slice(1), ...args], {
       cwd,
       encoding: "utf8",
       env: getEnvVars()

package/plugins/sp/scripts/wrapup-drift-probe.ts

@@ -125,6 +125,7 @@ export function changedPathsOf(section: string | null): string[] {
     const paths: string[] = [];
     for (const match of section.matchAll(CHANGE_ENTRY)) {
         const path = match[1];
+        if (path === undefined) continue;
         // Path-like: no whitespace and at least one separator or dotted suffix, so prose
         // backticks never masquerade as change-map entries.
         if (/\s/.test(path)) continue;
@@ -148,7 +149,8 @@ const SURFACE_MATCHERS = DOC_OWNED_SURFACES.map((glob) => ({ glob, regex: surfac
 /** 0944 R2 surface match: doc-owned glob, corpus exclusion, new top-level directory. */
 export function driftReasonForPath(path: string): string | null {
     if (CORPUS_PREFIXES.some((prefix) => path.startsWith(prefix))) return null;
-    if (path.includes('/') && !KNOWN_TOP_LEVEL.has(path.split('/')[0])) {
+    const top = path.split('/')[0];
+    if (path.includes('/') && top !== undefined && !KNOWN_TOP_LEVEL.has(top)) {
         return 'new top-level workspace directory';
     }
     const match = SURFACE_MATCHERS.find((entry) => entry.regex.test(path));
@@ -158,7 +160,7 @@ export function driftReasonForPath(path: string): string | null {
 function defaultSpurRunner(env: DriftProbeEnv, cwd?: string): SpurRunner {
     const parts = (env.spurBin ?? 'spur').split(/\s+/).filter((part) => part.length > 0);
     return (args: string[]): SpurShowResult => {
-        const run = spawnSync(parts[0], [...parts.slice(1), ...args], {
+        const run = spawnSync(parts[0] ?? 'spur', [...parts.slice(1), ...args], {
             cwd,
             encoding: 'utf8',
             env: getEnvVars(),