@gobing-ai/spur 0.3.93 → 0.3.95

package/plugins/sp/scripts/inline-run-setup.ts

@@ -34,6 +34,7 @@
  *   bun plugins/sp/scripts/inline-run-setup.ts --decide --run-id <id> --node <state> --options-json <file> [--spur-bin <path>]
  *       --status <done|failed> --ok <true|false> --duration-ms <n> [--spur-bin <path>]
  *   bun plugins/sp/scripts/inline-run-setup.ts --close --run-id <id> --status <done|failed|paused> [--reason <terminal-reason>] [--spur-bin <path>]
+ *   bun plugins/sp/scripts/inline-run-setup.ts --persist-out --from <worktree-path> [--task-file <path>]... [--spur-bin <path>]
  *
  * The `--fingerprint` mode prints the engine's proof-input digest for the given spec files and
  * creates nothing (task 0862 R5).
@@ -51,6 +52,18 @@
  * decision is still `ok: true` — the run continues — so exit 0 covers every model-level
  * outcome; only an invalid options schema exits 1 (fail closed).
  *
+ * The `--persist-out --from <worktree-path>` mode (task 0975 R1) is the WT-4a step a
+ * `--worktree` run executes BEFORE teardown: it copies the worktree's run provenance — the
+ * `runs`/`action_runs`/`phase_runs`/`transition_runs`/`workflow_states` rows and the two-file
+ * run records — into THIS tree's project DB and `.spur/run/` (cwd = the invoking tree).
+ * Repeatable `--task-file <path>` (0984 R2) forwards each merged task file so the app service
+ * also copies/verifies the `.spur/run/<file>` evidence that file cites; citation selection,
+ * safe-path validation and conflict behavior live entirely in the app service. Idempotent;
+ * collisions are reported as `skipped[{id,reason}]`, never overwrites. Exit 0 = persisted
+ * (possibly with skips); exit 1 = fail closed — an unreadable/unsafe/over-cap/unresolved
+ * citation or a divergent cited file fails the pass too — the driver routes to WT-5 and
+ * retains the worktree; usage errors exit 2.
+ *
  * Exit 2 is reserved for usage errors.
  *
  * Env: SPUR_BIN
@@ -102,6 +115,13 @@ function usage(): never {
     console.error(
         '       bun plugins/sp/scripts/inline-run-setup.ts --close --run-id <id> --status <done|failed|paused> [--reason <terminal-reason>] [--spur-bin <path>]',
     );
+    console.error(
+        '       bun plugins/sp/scripts/inline-run-setup.ts --persist-out --from <worktree-path> [--task-file <path>]... [--spur-bin <path>]',
+    );
+    console.error(
+        '       terminal-reason is a closed enum (0937 R2): done, paused-operator, failed-check, failed-agent, ' +
+            'failed-timeout, failed-guard, cancelled, interrupted, retry-exhausted',
+    );
     console.error(
         '       bun plugins/sp/scripts/inline-run-setup.ts --decide --run-id <id> --node <state> --options-json <file> [--spur-bin <path>]',
     );
@@ -313,7 +333,12 @@ async function printFingerprint(taskFile: string, featureFile: string, spurBin:
 }
 
 /** Terminal statuses the inline driver may declare when closing its run row. */
-const CLOSE_STATUSES = new Set(['done', 'failed', 'paused']);
+const CLOSE_STATUSES: ReadonlySet<string> = new Set<'done' | 'failed' | 'paused'>(['done', 'failed', 'paused']);
+
+/** Narrow an argv `--status` to the close vocabulary (`CLOSE_STATUSES`). */
+function isCloseStatus(status: string): status is 'done' | 'failed' | 'paused' {
+    return CLOSE_STATUSES.has(status);
+}
 
 /**
  * 0937 R2: closed terminal-reason vocabulary the driver may declare on `--close`.
@@ -334,7 +359,12 @@ const TERMINAL_REASONS = new Set([
 ]);
 
 /** Finalize statuses — a finish emission is terminal, so only done|failed are valid (0868 #4). */
-const ACTION_STATUSES = new Set(['done', 'failed']);
+const ACTION_STATUSES: ReadonlySet<string> = new Set<'done' | 'failed'>(['done', 'failed']);
+
+/** Narrow an argv `--status` to the finalize vocabulary (`ACTION_STATUSES`). */
+function isActionStatus(status: string): status is 'done' | 'failed' {
+    return ACTION_STATUSES.has(status);
+}
 
 /** Input for the ADR-117 emission modes (`--action` / `--close`). */
 import type { WorkflowActionTraceWriter } from '@gobing-ai/spur-app';
@@ -346,7 +376,12 @@ interface TraceModeInput {
     readonly kind: string;
     /** Declared terminal reason (0937 R2) — validated against TERMINAL_REASONS before this point. */
     readonly reason?: string;
-    readonly status: string;
+    /**
+     * Trace status: the finalize vocabulary plus the close-only `paused` (`CLOSE_STATUSES`).
+     * Both are assignable to the engine's `WorkflowStatus`; the plugin cannot import that
+     * type (standalone contract), so the literal union stands in for it.
+     */
+    readonly status: 'done' | 'failed' | 'paused';
     readonly ok: boolean;
     readonly durationMs: number;
     readonly spurBin: string;
@@ -371,7 +406,7 @@ function runRecordLogPath(runDir: string, runId: string): string {
  * exit immediately after), and never throws: an unwritable log must not wedge the run
  * (ADR-117 R3).
  */
-function appendTraceFailureLine(runId: string, detail: string): void {
+function appendRunLogLine(runId: string, detail: string): void {
     try {
         const runDir = join(process.cwd(), '.spur', 'run');
         if (!existsSync(runDir)) mkdirSync(runDir, { recursive: true });
@@ -393,7 +428,7 @@ function appendTraceFailureLine(runId: string, detail: string): void {
 async function runTraceMode(input: TraceModeInput): Promise<number> {
     const operation = input.close ? 'run.close' : 'action.finish';
     const fail = (error: string): number => {
-        appendTraceFailureLine(
+        appendRunLogLine(
             input.runId,
             `trace-emission-failed operation=${operation} run=${input.runId}` +
                 `${input.node === '' ? '' : ` node=${input.node}`}${input.kind === '' ? '' : ` kind=${input.kind}`}: ${error}`,
@@ -420,7 +455,7 @@ async function runTraceMode(input: TraceModeInput): Promise<number> {
         projectDb = await app.openInlineRunProjectDb(process.cwd());
         const writer = app.createWorkflowActionTraceWriter(projectDb.adapter, (failure: unknown) => {
             const detail = failure as { operation?: string; error?: string };
-            appendTraceFailureLine(
+            appendRunLogLine(
                 input.runId,
                 `trace-emission-failed operation=${detail.operation ?? operation} run=${input.runId}: ${detail.error ?? 'unknown error'}`,
             );
@@ -443,6 +478,18 @@ async function runTraceMode(input: TraceModeInput): Promise<number> {
             const failure = result.failure as { error?: string };
             return fail(failure.error ?? 'unknown trace emission failure');
         }
+        if (input.close && input.status === 'done' && result.actionRows === 0) {
+            // A run finalized `done` with ZERO recorded action rows is a bookkeeping defect
+            // (task 0975 R2): the row is already terminal — closeRun ran above — but the
+            // driver must surface this instead of reporting a clean close, and must never
+            // backfill rows. Exit 1 with the named code; the run record carries the finding.
+            const error = `run ${input.runId} closed done with zero action_runs rows`;
+            appendRunLogLine(input.runId, `trace-close-failed run=${input.runId}: ${error}`);
+            process.stdout.write(
+                `${JSON.stringify({ ok: false, runId: input.runId, error, code: 'NO_ACTION_ROWS', actionRows: 0 })}\n`,
+            );
+            return 1;
+        }
         process.stdout.write(`${JSON.stringify({ ...result, runId: input.runId })}\n`);
         return 0;
     } catch (error) {
@@ -450,7 +497,7 @@ async function runTraceMode(input: TraceModeInput): Promise<number> {
             // The run row must exist before --close can mark it terminal (R6); a missing row
             // is a loud correctness failure, not a best-effort emission failure (finding #4).
             const message = error instanceof Error ? error.message : String(error);
-            appendTraceFailureLine(input.runId, `trace-close-failed run=${input.runId}: ${message}`);
+            appendRunLogLine(input.runId, `trace-close-failed run=${input.runId}: ${message}`);
             process.stdout.write(
                 `${JSON.stringify({ ok: false, runId: input.runId, error: message, code: 'RUN_NOT_FOUND' })}\n`,
             );
@@ -485,6 +532,7 @@ async function runDecideMode(input: {
         value?: string;
         degraded?: boolean;
         reason?: string;
+        source?: 'model' | 'default';
         backend?: string | null;
         confidence?: number | null;
         resultFile?: string;
@@ -524,7 +572,13 @@ async function runDecideMode(input: {
         return decideFailed(error instanceof Error ? error.message : String(error));
     }
     if (!outcome.ok) return decideFailed(outcome.error ?? 'decide failed without an error message');
-    process.stdout.write(`${JSON.stringify({ ok: true, runId: input.runId, node: input.node, ...outcome })}\n`);
+    process.stdout.write(`${JSON.stringify({ runId: input.runId, node: input.node, ...outcome, ok: true })}\n`);
+    // 0976 R2: the run log names the decision's provenance, so a declared-default fallback is
+    // never read as a model decision. Best-effort through the same run-log appender.
+    appendRunLogLine(
+        input.runId,
+        `decide node=${input.node} value=${outcome.value ?? ''} source=${outcome.source ?? 'default'} reason=${outcome.reason ?? ''}`,
+    );
     // Trace row is best-effort, exactly like --action: an emission failure never wedges the run.
     return await runTraceMode({
         runId: input.runId,
@@ -538,6 +592,44 @@ async function runDecideMode(input: {
     });
 }
 
+/**
+ * `--persist-out --from <worktree-path>` (task 0975 R1; `--task-file` per 0984 R2): resolve
+ * the app through the shared chain and copy the worktree's inline-run provenance into THIS
+ * tree. No persistence policy lives here — the app's `persistWorktreeRuns` (→ domain
+ * `transferRunTables`) owns the DB transfer, the citation selection/copy rules, the
+ * idempotence and the conflict skips; this delegate only forwards the merged task file
+ * paths. Success prints `{ok:true,persisted:<n>,skipped:[…]}` and exits 0; any failure
+ * prints `{ok:false,error}` and exits 1 (the driver routes to WT-5 and retains the
+ * worktree).
+ */
+async function runPersistOutMode(input: {
+    from: string;
+    taskFiles: readonly string[];
+    spurBin: string;
+}): Promise<number> {
+    try {
+        const { entry } = resolveAppEntry(input.spurBin);
+        const app = (await import(entry)) as {
+            persistWorktreeRuns: (i: {
+                fromWorkdir: string;
+                toWorkdir: string;
+                taskFiles?: readonly string[];
+            }) => Promise<{ ok: true; persisted: number; skipped: ReadonlyArray<{ id: string; reason: string }> }>;
+        };
+        const result = await app.persistWorktreeRuns({
+            fromWorkdir: input.from,
+            toWorkdir: process.cwd(),
+            ...(input.taskFiles.length > 0 ? { taskFiles: input.taskFiles } : {}),
+        });
+        process.stdout.write(`${JSON.stringify({ ok: true, persisted: result.persisted, skipped: result.skipped })}\n`);
+        return 0;
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stdout.write(`${JSON.stringify({ ok: false, error: message })}\n`);
+        return 1;
+    }
+}
+
 async function main(): Promise<void> {
     // The portable Node twin has no workspace imports; SQLite still uses Spur's existing Bun runtime.
     if (!process.versions.bun) {
@@ -550,11 +642,13 @@ async function main(): Promise<void> {
     let runId = '';
     let file = '';
     let fingerprint = false;
-    let taskFile = '';
+    const taskFiles: string[] = [];
     let featureFile = '';
     let action = false;
     let close = false;
     let decide = false;
+    let persistOut = false;
+    let from = '';
     let optionsJson = '';
     let node = '';
     let kind = '';
@@ -568,11 +662,13 @@ async function main(): Promise<void> {
         if (argv[i] === '--run-id') runId = argv[++i] ?? '';
         else if (argv[i] === '--file') file = argv[++i] ?? '';
         else if (argv[i] === '--fingerprint') fingerprint = true;
-        else if (argv[i] === '--task-file') taskFile = argv[++i] ?? '';
+        else if (argv[i] === '--task-file') taskFiles.push(argv[++i] ?? '');
         else if (argv[i] === '--feature-file') featureFile = argv[++i] ?? '';
         else if (argv[i] === '--action') action = true;
         else if (argv[i] === '--close') close = true;
         else if (argv[i] === '--decide') decide = true;
+        else if (argv[i] === '--persist-out') persistOut = true;
+        else if (argv[i] === '--from') from = argv[++i] ?? '';
         else if (argv[i] === '--options-json') optionsJson = argv[++i] ?? '';
         else if (argv[i] === '--node') node = argv[++i] ?? '';
         else if (argv[i] === '--kind') kind = argv[++i] ?? '';
@@ -585,9 +681,10 @@ async function main(): Promise<void> {
 
     // Two mutually exclusive modes share this entry point: create/attach a run (run-id + file), or
     // print the proof digest for the inline driver (task 0862 R5). Mixing them is a usage error.
+    // `--task-file` belongs to the fingerprint (exactly one) and persist-out (zero or more) modes.
     if (fingerprint) {
-        if (runId !== '' || file !== '' || taskFile.trim() === '') usage();
-        process.exit(await printFingerprint(taskFile, featureFile, spurBin));
+        if (runId !== '' || file !== '' || taskFiles.length !== 1 || (taskFiles[0] ?? '').trim() === '') usage();
+        process.exit(await printFingerprint(taskFiles[0] ?? '', featureFile, spurBin));
     }
 
     // ADR-117 emission modes (task 0868): the inline driver reports one completed action
@@ -597,18 +694,28 @@ async function main(): Promise<void> {
     // fingerprint, and trace modes; it requires the run id (filename-guarded), the state id
     // for the trace row, and the options JSON file.
     if (decide) {
-        if (action || close || fingerprint || file !== '' || taskFile !== '') usage();
+        if (action || close || fingerprint || file !== '' || taskFiles.length > 0) usage();
         if (runId.trim() === '' || node.trim() === '' || optionsJson.trim() === '') usage();
         if (!SAFE_RUN_ID_RE.test(runId)) refuseUnsafeRunId(runId);
         process.exit(await runDecideMode({ runId, node, optionsFile: optionsJson, spurBin }));
     }
 
+    // Worktree provenance persist-out (task 0975 R1): mutually exclusive with every other
+    // mode; requires the source worktree path and accepts zero or more merged task files
+    // (0984 R2) whose cited `.spur/run/` evidence the app service copies/verifies. Runs
+    // with cwd = the invoking tree.
+    if (persistOut) {
+        if (fingerprint || decide || action || close || runId !== '' || file !== '') usage();
+        if (from.trim() === '' || taskFiles.some((taskFile) => taskFile.trim() === '')) usage();
+        process.exit(await runPersistOutMode({ from, taskFiles, spurBin }));
+    }
+
     if (action || close) {
         if (action && close) usage();
         if (runId.trim() === '' || status.trim() === '') usage();
         if (!SAFE_RUN_ID_RE.test(runId)) refuseUnsafeRunId(runId);
         if (close) {
-            if (!CLOSE_STATUSES.has(status)) usage();
+            if (!isCloseStatus(status)) usage();
             // 0937 R2: a failed close requires a declared reason, and any declared reason
             // must be a closed-enum value — both fail loudly BEFORE any write happens.
             if (reason.trim() === '') {
@@ -631,7 +738,7 @@ async function main(): Promise<void> {
             );
         }
         if (node.trim() === '' || kind.trim() === '') usage();
-        if (!ACTION_STATUSES.has(status)) usage();
+        if (!isActionStatus(status)) usage();
         // `--ok` and `--duration-ms` are required and exact for the action mode
         // (review finding #2): a miscased `--ok True` or an omitted `--duration-ms`
         // must be a loud usage error, never a silently-defaulted `ok=0` /

package/plugins/sp/scripts/pr-reviewing.mjs

@@ -50,6 +50,8 @@ function parseArgs(argv) {
   const booleans = new Set;
   for (let i = 0;i < rest.length; i++) {
     const tok = rest[i];
+    if (tok === undefined)
+      continue;
     if (BOOL_FLAGS.has(tok)) {
       booleans.add(tok);
     } else if (VALUE_FLAGS.has(tok)) {

package/plugins/sp/scripts/pr-reviewing.ts

@@ -169,6 +169,7 @@ export function parseArgs(argv: readonly string[]): ParsedArgs {
     const booleans = new Set<string>();
     for (let i = 0; i < rest.length; i++) {
         const tok = rest[i];
+        if (tok === undefined) continue;
         if (BOOL_FLAGS.has(tok)) {
             booleans.add(tok);
         } else if (VALUE_FLAGS.has(tok)) {

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

@@ -154,6 +154,9 @@ function lightScope(changedFiles, exists = existsSync) {
   }
   return { files, workspaces: [...workspaces].sort(), tests: [...tests].sort() };
 }
+function shQuote(arg) {
+  return /^[\w./@+-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`;
+}
 function workspaceHasTypecheck(workspace) {
   try {
     const pkg = JSON.parse(readFileSync(join(workspace, "package.json"), "utf8"));
@@ -165,11 +168,11 @@ function workspaceHasTypecheck(workspace) {
 function planLightChecks(scope, hasTypecheck = workspaceHasTypecheck) {
   const plans = [];
   if (scope.files.length > 0) {
-    plans.push({ id: "format-lint:changed", cmd: `bunx biome check ${scope.files.join(" ")}` });
+    plans.push({ id: "format-lint:changed", cmd: `bunx biome check ${scope.files.map(shQuote).join(" ")}` });
   }
   for (const workspace of scope.workspaces) {
     if (hasTypecheck(workspace)) {
-      plans.push({ id: `typecheck:${workspace}`, cmd: `cd ${workspace} && bun run typecheck` });
+      plans.push({ id: `typecheck:${workspace}`, cmd: `cd ${shQuote(workspace)} && bun run typecheck` });
     }
   }
   const testsByWorkspace = new Map;
@@ -180,7 +183,10 @@ function planLightChecks(scope, hasTypecheck = workspaceHasTypecheck) {
     testsByWorkspace.set(workspace, paths);
   }
   for (const [workspace, paths] of testsByWorkspace) {
-    plans.push({ id: `test:${workspace}`, cmd: `cd ${workspace} && bun test ${paths.join(" ")}` });
+    plans.push({
+      id: `test:${workspace}`,
+      cmd: `cd ${shQuote(workspace)} && bun test ${paths.map(shQuote).join(" ")}`
+    });
   }
   return plans;
 }
@@ -376,7 +382,7 @@ function runQualityGate(mode, env, options = {}) {
   appendFileSync(abs(logFile), `proof-digest: ${env.proofDigest ?? ""}
 `);
   let receiptFile;
-  if (mode === "run") {
+  if (!noProgressSkip) {
     if ((env.proofDigest ?? "").length > 0) {
       receiptFile = join(runDir, `${env.wbs}-check-receipt.json`);
       const receipt = buildReceipt({
@@ -404,17 +410,19 @@ function runQualityGate(mode, env, options = {}) {
   return { status, attempts: gateAttempt, logFile, findingsFile, statusFile, attemptFile, receiptFile };
 }
 var QUALITY_GATE_USAGE = "usage: quality-gate.ts <run|recheck|light|status>  (env: wbs, qualityGateCmd, gateProbeCmd, proofDigest, runId)";
-function main(argv, env = getEnvVars(), options = {}) {
+function main(argv, rawEnv = getEnvVars(), options = {}) {
   const mode = argv[0];
   if (mode !== "run" && mode !== "recheck" && mode !== "light" && mode !== "status") {
     process.stderr.write(`${QUALITY_GATE_USAGE}
 `);
     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 = { ...rawEnv, wbs };
   if (mode === "light") {
     runLightGate(env);
   } else if (mode === "status") {
@@ -439,6 +447,7 @@ function main(argv, env = getEnvVars(), options = {}) {
 export {
   workspaceHasTypecheck,
   tailLines,
+  shQuote,
   scanCoverageShortfalls,
   runShellCommand,
   runQualityGate,

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

@@ -26,8 +26,8 @@
  * output matches a SQLite busy/locked error; the delay defaults to 10 seconds and is
  * overridable via `SPUR_QUALITY_GATE_RETRY_DELAY_MS` (tests).
  *
- * Check receipts (task 0939, ADR-124): `run` writes `.spur/run/<wbs>-check-receipt.json`
- * (`check-receipt/v1`) when `proofDigest` is set; without a digest no receipt is written and the
+ * Check receipts (task 0939, ADR-124): `run` and `recheck` write `.spur/run/<wbs>-check-receipt.json`
+ * (`check-receipt/v1`) when `proofDigest` is set (a no-progress skip keeps the receipt it matched); without a digest no receipt is written and the
  * log says why. The gate executes `qualityGateCmd` as one unit, so the full-tier receipt carries
  * a single `test` row for the whole `bun run spur-check` chain (lint | typecheck | test-pre-check
  * | test | test-post-check). `light` accumulates: a sub-check already PASS in a light receipt at
@@ -335,6 +335,15 @@ export function lightScope(changedFiles: string[], exists: (p: string) => boolea
     return { files, workspaces: [...workspaces].sort(), tests: [...tests].sort() };
 }
 
+/**
+ * Quote one argument for `sh -c`. Changed-file names come from the working tree (untracked files
+ * included), so an unquoted `x$(cmd).ts` would run `cmd` and a space would split the argument.
+ * Plain paths pass through unchanged to keep receipts readable.
+ */
+export function shQuote(arg: string): string {
+    return /^[\w./@+-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+
 export interface LightCheckPlan {
     id: string;
     cmd: string;
@@ -364,11 +373,11 @@ export function planLightChecks(
 ): LightCheckPlan[] {
     const plans: LightCheckPlan[] = [];
     if (scope.files.length > 0) {
-        plans.push({ id: 'format-lint:changed', cmd: `bunx biome check ${scope.files.join(' ')}` });
+        plans.push({ id: 'format-lint:changed', cmd: `bunx biome check ${scope.files.map(shQuote).join(' ')}` });
     }
     for (const workspace of scope.workspaces) {
         if (hasTypecheck(workspace)) {
-            plans.push({ id: `typecheck:${workspace}`, cmd: `cd ${workspace} && bun run typecheck` });
+            plans.push({ id: `typecheck:${workspace}`, cmd: `cd ${shQuote(workspace)} && bun run typecheck` });
         }
     }
     const testsByWorkspace = new Map<string, string[]>();
@@ -379,7 +388,10 @@ export function planLightChecks(
         testsByWorkspace.set(workspace, paths);
     }
     for (const [workspace, paths] of testsByWorkspace) {
-        plans.push({ id: `test:${workspace}`, cmd: `cd ${workspace} && bun test ${paths.join(' ')}` });
+        plans.push({
+            id: `test:${workspace}`,
+            cmd: `cd ${shQuote(workspace)} && bun test ${paths.map(shQuote).join(' ')}`,
+        });
     }
     return plans;
 }
@@ -622,9 +634,12 @@ export function runQualityGate(
     writeFileSync(abs(statusFile), `${status}\n`);
     appendFileSync(abs(logFile), `proof-digest: ${env.proofDigest ?? ''}\n`);
 
-    // 0939 R2: only `run` writes the full-tier receipt, and only with a digest to bind it to.
+    // 0939 R2: the gate writes the full-tier receipt only with a digest to bind it to. 0976 R1:
+    // `recheck` persists the receipt it evaluated too, so a second recheck at the same digest can
+    // take the no-progress skip. A skip leaves the FAIL receipt it matched untouched — a skip never
+    // rewrites a receipt, so it can never launder FAIL into PASS.
     let receiptFile: string | undefined;
-    if (mode === 'run') {
+    if (!noProgressSkip) {
         if ((env.proofDigest ?? '').length > 0) {
             receiptFile = join(runDir, `${env.wbs}-check-receipt.json`);
             const receipt = buildReceipt({
@@ -655,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

@@ -17,7 +17,7 @@ function getEnvVars() {
 var RESIDUAL_SCAN_USAGE = "usage: residual-scan.ts <scan|fold|settle|report> <wbs> [--spur-bin <bin>] [--root <dir>] [--tmp-dir <dir>]";
 var MARKER_PATTERN = /TODO|FIXME|XXX|HACK/;
 var PRIORITY_PATTERN = /^P[1-4]/;
-var NONE_FINDING = /^(none|\u2014)$/i;
+var NONE_FINDING = /^(none( found)?|no (findings?|issues?)( found)?|\u2014)\s*(\(.*\))?\.?$/i;
 var DISPOSITION_HEADER = /^(Disposition|Action|Status|Resolution|Fixed)$/i;
 var RESOLVED_DISPOSITION = /^(FIXED|RESOLVED|DONE)\b/i;
 var DEFERRED_DISPOSITION = /^DEFER(RED)?\b/i;
@@ -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

@@ -64,7 +64,8 @@ export interface ScanOptions {
 
 const MARKER_PATTERN = /TODO|FIXME|XXX|HACK/;
 const PRIORITY_PATTERN = /^P[1-4]/;
-const NONE_FINDING = /^(none|—)$/i;
+// Placeholder "no finding" cells, optionally with a trailing "(…)" note; "None of X…" is a real finding.
+const NONE_FINDING = /^(none( found)?|no (findings?|issues?)( found)?|—)\s*(\(.*\))?\.?$/i;
 const DISPOSITION_HEADER = /^(Disposition|Action|Status|Resolution|Fixed)$/i;
 const RESOLVED_DISPOSITION = /^(FIXED|RESOLVED|DONE)\b/i;
 const DEFERRED_DISPOSITION = /^DEFER(RED)?\b/i;
@@ -104,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);
 }
 
 /**
@@ -119,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++) {