@gobing-ai/spur 0.3.93 → 0.3.95

package/plugins/sp/scripts/script-contract-check.ts

@@ -4,7 +4,7 @@
  * (task 0600, feature I, ADR-065).
  *
  * Enforces superskill's standard plugin script contract across plugins/sp:
- * 1. A 'standard' entry must have a valid .mjs twin not older than its .ts source.
+ * 1. A 'standard' entry must have a valid .mjs twin byte-identical to a fresh convert of its .ts source.
  * 2. A .mjs twin on disk must be registered under a 'standard' entry (never 'repo-only' or unlisted).
  * 3. Every script file under plugins/sp/scripts/ must have a manifest entry (two-sided).
  * 4. No shipped surface (commands/, skills/, agents/, README.md) may reference 'bun plugins/sp/scripts/'.
@@ -18,8 +18,10 @@
  * Exit code: 0 on success, 1 on any violation.
  */
 
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
 
 export type ScriptContractType = 'standard' | 'repo-only';
 
@@ -42,6 +44,8 @@ export interface Violation {
         | 'unexpected_twin'
         | 'unregistered_script'
         | 'forbidden_invocation'
+        | 'converter_unavailable'
+        | 'gobing_ai_import'
         | 'incomplete';
     target: string;
     message: string;
@@ -116,12 +120,24 @@ export function listDiskScripts(scriptsDir: string): { tsFiles: string[]; mjsFil
 
 export function scanShippedSurfaces(pluginDir: string): Array<{ file: string; line: number; content: string }> {
     const matches: Array<{ file: string; line: number; content: string }> = [];
-    const forbiddenPattern = 'bun plugins/sp/scripts/';
-
-    const searchDirs = ['commands', 'skills', 'agents'];
-    const singleFiles = ['README.md'];
+    const guardMarker = 'config/plugin-scripts.json';
+
+    // 0960 R5: the probe shapes the guard idiom introduces, plus the legacy literal. A hit is
+    // legal only when its line (or, for a YAML command block, its folded block) names the
+    // source-repo marker — otherwise it is a project-first probe that shadows the installed
+    // twin in a consumer.
+    const projectFirstPatterns = [
+        /\[ -f "?plugins\/sp\/scripts\//,
+        /\b[A-Z_]*S(?:CRIPT)?="?plugins\/sp\/scripts\//,
+        /\bbun plugins\/sp\/scripts\//,
+    ];
+    const isHit = (line: string): boolean => projectFirstPatterns.some((pattern) => pattern.test(line));
+
+    function push(file: string, line: number, content: string): void {
+        matches.push({ file, line, content: content.trim() });
+    }
 
-    function scanFile(filePath: string): void {
+    function scanLines(filePath: string): void {
         if (!existsSync(filePath)) return;
         let text: string;
         try {
@@ -132,13 +148,72 @@ export function scanShippedSurfaces(pluginDir: string): Array<{ file: string; li
         const lines = text.split('\n');
         for (let i = 0; i < lines.length; i++) {
             const line = lines[i] ?? '';
-            if (line.includes(forbiddenPattern)) {
-                matches.push({
-                    file: filePath,
-                    line: i + 1,
-                    content: line.trim(),
-                });
+            const trimmed = line.trim();
+            if (trimmed.startsWith('#')) continue; // comment lines are not executable probes
+            if (!isHit(line)) continue;
+            if (line.includes(guardMarker)) continue; // same-line source-repo guard
+            push(filePath, i + 1, trimmed);
+        }
+    }
+
+    /**
+     * 0960 R5: the repo-root workflow definitions also ship, and their shell lives in folded
+     * `command:` blocks. A guard on one physical line legalizes the invocation on the next, so
+     * the block — not the line — is the unit of judgment. Markdown prose references (backticked
+     * paths with no `[ -f` / assignment / `bun ` prefix) never match the patterns, so they stay
+     * legal.
+     */
+    function scanYamlCommands(filePath: string): void {
+        if (!existsSync(filePath)) return;
+        let text: string;
+        try {
+            text = readFileSync(filePath, 'utf8');
+        } catch {
+            return;
+        }
+        const lines = text.split('\n');
+        let i = 0;
+        while (i < lines.length) {
+            const line = lines[i] ?? '';
+            const blockKey = /^(\s*)command:\s*(?:>[+-]?|\|[+-]?)?\s*$/.exec(line);
+            const inlineKey = /^(\s*)command:\s+(.+)$/.exec(line);
+            if (blockKey) {
+                const indent = (blockKey[1] ?? '').length;
+                const block: Array<{ no: number; text: string }> = [];
+                let j = i + 1;
+                while (j < lines.length) {
+                    const next = lines[j] ?? '';
+                    if (next.trim() === '') {
+                        block.push({ no: j + 1, text: next });
+                        j++;
+                        continue;
+                    }
+                    const nextIndent = (next.match(/^\s*/)?.[0] ?? '').length;
+                    if (nextIndent <= indent) break;
+                    block.push({ no: j + 1, text: next });
+                    j++;
+                }
+                if (!block.some((b) => b.text.includes(guardMarker))) {
+                    for (const b of block) {
+                        const trimmed = b.text.trim();
+                        if (trimmed.startsWith('#')) continue;
+                        if (!isHit(b.text)) continue;
+                        if (b.text.includes(guardMarker)) continue;
+                        push(filePath, b.no, trimmed);
+                    }
+                }
+                i = j;
+                continue;
             }
+            if (inlineKey) {
+                const value = inlineKey[2] ?? '';
+                if (!line.trim().startsWith('#') && isHit(value) && !value.includes(guardMarker)) {
+                    push(filePath, i + 1, line.trim());
+                }
+                i++;
+                continue;
+            }
+            i++;
         }
     }
 
@@ -163,16 +238,27 @@ export function scanShippedSurfaces(pluginDir: string): Array<{ file: string; li
                 st.isFile() &&
                 (entry.endsWith('.md') || entry.endsWith('.json') || entry.endsWith('.yaml') || entry.endsWith('.yml'))
             ) {
-                scanFile(fullPath);
+                scanLines(fullPath);
             }
         }
     }
 
-    for (const d of searchDirs) {
+    for (const d of ['commands', 'skills', 'agents']) {
         walk(join(pluginDir, d));
     }
-    for (const f of singleFiles) {
-        scanFile(join(pluginDir, f));
+    scanLines(join(pluginDir, 'README.md'));
+
+    // 0960 R5: the workflow tree is repo-only (resolved from pluginDir/../..); a consumer's own
+    // workflow definitions are not this rule's subject.
+    const workflowsDir = resolve(pluginDir, '..', '..', 'config', 'workflows');
+    let workflowFiles: string[] = [];
+    try {
+        workflowFiles = readdirSync(workflowsDir).filter((name) => name.endsWith('.yaml') || name.endsWith('.yml'));
+    } catch {
+        workflowFiles = [];
+    }
+    for (const name of workflowFiles.sort()) {
+        scanYamlCommands(join(workflowsDir, name));
     }
 
     return matches;
@@ -206,8 +292,9 @@ function findGobingAiValueImports(dir: string): { file: string; line: number }[]
             const lines = readFileSync(full, 'utf8').split('\n');
             let stmtStart = 0;
             for (let i = 0; i < lines.length; i++) {
-                if (/^\s*(?:import|export)\b/.test(lines[i])) stmtStart = i;
-                if (/(?:from\s*|import\s*|import\s*\(\s*)['"]@gobing-ai\//.test(lines[i])) {
+                const line = lines[i] ?? '';
+                if (/^\s*(?:import|export)\b/.test(line)) stmtStart = i;
+                if (/(?:from\s*|import\s*|import\s*\(\s*)['"]@gobing-ai\//.test(line)) {
                     const opener = lines.slice(stmtStart, i + 1).join(' ');
                     if (!/^\s*(?:import|export)\s+type\b/.test(opener)) {
                         hits.push({ file: full, line: i + 1 });
@@ -219,7 +306,35 @@ function findGobingAiValueImports(dir: string): { file: string; line: number }[]
     return hits;
 }
 
-export function validateContract(manifest: ScriptManifest, scriptsDir: string, pluginDir: string): Violation[] {
+/** Regenerates a standard script's twin into `outPath`; false when conversion could not run. */
+export type ConvertTwin = (rel: string, outPath: string) => boolean;
+
+/**
+ * The real converter: `superskill script convert sp <rel> --out <outPath>` run from the repo
+ * root, because `convert` resolves `plugins/<plugin>/scripts/<rel>` against the process cwd.
+ * Returns false — never throws — on spawn error, non-zero exit, or a missing output file, and
+ * records the command plus stderr in `lastError` for the `converter_unavailable` violation.
+ */
+export function spawnConvertTwin(repoRoot: string, bin = 'superskill'): ConvertTwin & { lastError?: string } {
+    const convert: ConvertTwin & { lastError?: string } = (rel, outPath) => {
+        const args = ['script', 'convert', 'sp', rel, '--out', outPath];
+        const res = spawnSync(bin, args, { cwd: repoRoot, encoding: 'utf-8' });
+        if (res.error || res.status !== 0 || !existsSync(outPath)) {
+            const detail = (res.stderr ?? '').trim() || res.error?.message || `exit ${res.status}`;
+            convert.lastError = `${bin} ${args.join(' ')}: ${detail}`;
+            return false;
+        }
+        return true;
+    };
+    return convert;
+}
+
+export function validateContract(
+    manifest: ScriptManifest,
+    scriptsDir: string,
+    pluginDir: string,
+    opts: { convertTwin?: ConvertTwin } = {},
+): Violation[] {
     const violations: Violation[] = [];
     const { tsFiles, mjsFiles } = listDiskScripts(scriptsDir);
 
@@ -236,37 +351,51 @@ export function validateContract(manifest: ScriptManifest, scriptsDir: string, p
         manifestMap.set(entry.rel, entry);
     }
 
-    // Rule 1: standard entries must have valid .mjs twins not older than the .ts source.
-    // mtime is only meaningful when a build genuinely ran: a `git worktree add` stamps
-    // every checked-out file within the same millisecond, and the lexicographic write
-    // order (`tool.mjs` < `tool.ts`) makes the twin spuriously "older" by <1ms. Tolerate
-    // sub-second deltas so a fresh checkout is never flagged; real build staleness is
-    // seconds-to-minutes, far beyond this window (task 0606 R1 eval-worktree blocker).
-    const STALE_TWIN_TOLERANCE_MS = 1000;
-    for (const entry of manifest.entries) {
-        if (entry.rel && entry.contract === 'standard') {
-            const expectedTwinRel = entry.twin ?? entry.rel.replace(/\.ts$/, '.mjs');
-            const twinPath = join(scriptsDir, expectedTwinRel);
-            const tsPath = join(scriptsDir, entry.rel);
-
-            if (!existsSync(twinPath)) {
-                violations.push({
-                    kind: 'missing_twin',
-                    target: entry.rel,
-                    message: `standard script ${entry.rel} is missing its .mjs twin (${expectedTwinRel})`,
-                });
-            } else if (existsSync(tsPath)) {
-                const tsStat = statSync(tsPath);
-                const twinStat = statSync(twinPath);
-                if (twinStat.mtimeMs < tsStat.mtimeMs - STALE_TWIN_TOLERANCE_MS) {
+    // Rule 1: standard entries must have a .mjs twin byte-identical to a fresh convert.
+    // mtime is never consulted: git does not store mtimes, so a committed stale twin looks
+    // freshly checked-out in every clone and worktree. Only regenerating the twin proves it
+    // matches its source (task 0970; replaces the 0606 sub-second mtime tolerance).
+    const twinTmpDir = mkdtempSync(join(tmpdir(), 'script-twin-'));
+    try {
+        const convertTwin = opts.convertTwin ?? spawnConvertTwin(resolve(pluginDir, '..', '..'));
+        let converterDown = false;
+        for (const entry of manifest.entries) {
+            if (entry.rel && entry.contract === 'standard') {
+                const expectedTwinRel = entry.twin ?? entry.rel.replace(/\.ts$/, '.mjs');
+                const twinPath = join(scriptsDir, expectedTwinRel);
+                const tsPath = join(scriptsDir, entry.rel);
+
+                if (!existsSync(twinPath)) {
                     violations.push({
-                        kind: 'stale_twin',
+                        kind: 'missing_twin',
                         target: entry.rel,
-                        message: `standard script .mjs twin ${expectedTwinRel} is older than source ${entry.rel}`,
+                        message: `standard script ${entry.rel} is missing its .mjs twin (${expectedTwinRel})`,
                     });
+                } else if (existsSync(tsPath) && !converterDown) {
+                    const outPath = join(twinTmpDir, expectedTwinRel);
+                    mkdirSync(dirname(outPath), { recursive: true });
+                    if (!convertTwin(entry.rel, outPath)) {
+                        // One violation, then stop: a broken converter is one environment failure,
+                        // not 17 stale twins. It never silently passes (task 0970 R3).
+                        const detail = (convertTwin as { lastError?: string }).lastError;
+                        violations.push({
+                            kind: 'converter_unavailable',
+                            target: entry.rel,
+                            message: `could not regenerate ${expectedTwinRel} from ${entry.rel}${detail ? ` — ${detail}` : ''}; twin content cannot be verified`,
+                        });
+                        converterDown = true;
+                    } else if (!readFileSync(outPath).equals(readFileSync(twinPath))) {
+                        violations.push({
+                            kind: 'stale_twin',
+                            target: entry.rel,
+                            message: `standard script .mjs twin ${expectedTwinRel} does not match a fresh convert of ${entry.rel} — run bun run build:scripts`,
+                        });
+                    }
                 }
             }
         }
+    } finally {
+        rmSync(twinTmpDir, { recursive: true, force: true });
     }
 
     // Rule 2: committed .mjs files must belong to a 'standard' entry

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

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// @bun
+
+// plugins/sp/scripts/script-root.ts
+import { spawnSync } from "child_process";
+import { createHash } from "crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+
+// plugins/sp/lib/env.ts
+function getEnvVars() {
+  return process.env;
+}
+
+// plugins/sp/scripts/script-root.ts
+var SOURCE_REPO_MARKER = join("config", "plugin-scripts.json");
+var PROJECT_SCRIPTS_DIR = join("plugins", "sp", "scripts");
+var SCRIPT_ROOT_TWIN_REL = "script-root.mjs";
+function defaultResolveScript(cwd) {
+  return (rel) => {
+    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(`
+`).pop() ?? "";
+    try {
+      const parsed = JSON.parse(lastLine);
+      return typeof parsed.path === "string" && parsed.path.length > 0 ? parsed : null;
+    } catch {
+      return null;
+    }
+  };
+}
+function digestScriptSet(dir, cwd) {
+  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(`
+`)).digest("hex")}`;
+}
+function runScriptRoot(env, options = {}) {
+  const cwd = options.cwd;
+  const runId = env.__runId ?? env.runId ?? "";
+  const relResult = join(".spur", "run", `${runId}-script-root.json`);
+  const abs = (p) => cwd ? join(cwd, p) : p;
+  const warn = options.warn ?? ((message) => void process.stderr.write(`${message}
+`));
+  mkdirSync(abs(join(".spur", "run")), { recursive: true });
+  const write = (row) => {
+    writeFileSync(abs(relResult), `${JSON.stringify(row)}
+`);
+    return { ...row, resultFile: relResult, exitCode: 0 };
+  };
+  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)}` });
+    }
+  }
+  if (existsSync(abs(PROJECT_SCRIPTS_DIR))) {
+    warn(`script-root: ignoring vendored ${PROJECT_SCRIPTS_DIR}/ (no ${SOURCE_REPO_MARKER} marker) \u2014 ` + `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)}` });
+  }
+}
+var SCRIPT_ROOT_USAGE = "usage: script-root --run-id <id>";
+function main(argv, env = getEnvVars(), options = {}) {
+  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}
+`);
+    return 2;
+  }
+  return runScriptRoot({ ...env, __runId: runId }, options).exitCode;
+}
+{
+  process.exit(main(process.argv.slice(2)));
+}
+export {
+  runScriptRoot,
+  main,
+  digestScriptSet,
+  SOURCE_REPO_MARKER,
+  SCRIPT_ROOT_USAGE,
+  SCRIPT_ROOT_TWIN_REL,
+  PROJECT_SCRIPTS_DIR
+};

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;