@gobing-ai/spur 0.3.94 → 0.3.95

package/plugins/sp/scripts/quality-gate.ts

@@ -670,16 +670,22 @@ export function runQualityGate(
 export const QUALITY_GATE_USAGE =
     'usage: quality-gate.ts <run|recheck|light|status>  (env: wbs, qualityGateCmd, gateProbeCmd, proofDigest, runId)';
 
-export function main(argv: string[], env: QualityGateEnv = getEnvVars(), options: QualityGateOptions = {}): number {
+export function main(
+    argv: string[],
+    rawEnv: Partial<QualityGateEnv> = getEnvVars(),
+    options: QualityGateOptions = {},
+): number {
     const mode = argv[0];
     if (mode !== 'run' && mode !== 'recheck' && mode !== 'light' && mode !== 'status') {
         process.stderr.write(`${QUALITY_GATE_USAGE}\n`);
         return 2;
     }
-    if ((env.wbs ?? '').length === 0) {
+    const wbs = rawEnv.wbs ?? '';
+    if (wbs.length === 0) {
         process.stderr.write('quality-gate: env `wbs` is required\n');
         return 2;
     }
+    const env: QualityGateEnv = { ...rawEnv, wbs };
     if (mode === 'light') {
         runLightGate(env);
     } else if (mode === 'status') {

package/plugins/sp/scripts/residual-scan.mjs

@@ -47,14 +47,14 @@ function locationOf(locationCell, finding) {
   const cell = locationCell.trim().replace(/`/g, "");
   if (cell.length > 0 && cell !== "\u2014")
     return normalizeAnchor(cell);
-  const backtick = finding.match(/`([^`]+)`/);
-  return backtick === null ? "" : normalizeAnchor(backtick[1]);
+  const backtick = finding.match(/`([^`]+)`/)?.[1];
+  return backtick === undefined ? "" : normalizeAnchor(backtick);
 }
 function parseReviewFindings(taskContent) {
   const section = taskContent.split(/^### Review\b/m)[1];
   if (section === undefined)
     return [];
-  const body = section.split(/^### /m)[0];
+  const body = section.split(/^### /m)[0] ?? "";
   const out = [];
   const lines = body.split(`
 `);

package/plugins/sp/scripts/residual-scan.ts

@@ -105,8 +105,8 @@ export function normalizeAnchor(location: string): string {
 export function locationOf(locationCell: string, finding: string): string {
     const cell = locationCell.trim().replace(/`/g, '');
     if (cell.length > 0 && cell !== '—') return normalizeAnchor(cell);
-    const backtick = finding.match(/`([^`]+)`/);
-    return backtick === null ? '' : normalizeAnchor(backtick[1]);
+    const backtick = finding.match(/`([^`]+)`/)?.[1];
+    return backtick === undefined ? '' : normalizeAnchor(backtick);
 }
 
 /**
@@ -120,7 +120,7 @@ export function parseReviewFindings(
 ): Array<{ priority: string; location: string; text: string; deferral?: string }> {
     const section = taskContent.split(/^### Review\b/m)[1];
     if (section === undefined) return [];
-    const body = section.split(/^### /m)[0];
+    const body = section.split(/^### /m)[0] ?? '';
     const out: Array<{ priority: string; location: string; text: string; deferral?: string }> = [];
     const lines = body.split('\n');
     for (let i = 0; i < lines.length; i++) {

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
+};