@gobing-ai/spur 0.3.94 → 0.3.95

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.94",
+    "version": "0.3.95",
     "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics.",
     "extensions": {
         "pi": ["./hooks/pi/guard-extension.ts"]

package/plugins/sp/scripts/daily-summary/daily-summary.mjs

@@ -44,7 +44,7 @@ function parseArgs(argv = process.argv.slice(2)) {
   for (let i = 0;i < args.length; i++) {
     const arg = args[i];
     if (arg === "--date" && i + 1 < args.length) {
-      options.date = args[++i];
+      options.date = args[++i] ?? options.date;
     } else if (arg === "--dry-run") {
       options.dryRun = true;
     } else if (arg === "--output" && i + 1 < args.length) {
@@ -270,8 +270,8 @@ async function getGitCommits(date) {
       } else if (currentCommit && line.includes("\t")) {
         const parts = line.split("\t");
         if (parts.length >= 3) {
-          const insertions = parseInt(parts[0], 10) || 0;
-          const deletions = parseInt(parts[1], 10) || 0;
+          const insertions = parseInt(parts[0] ?? "", 10) || 0;
+          const deletions = parseInt(parts[1] ?? "", 10) || 0;
           currentCommit.filesChanged = (currentCommit.filesChanged ?? 0) + 1;
           currentCommit.insertions = (currentCommit.insertions ?? 0) + insertions;
           currentCommit.deletions = (currentCommit.deletions ?? 0) + deletions;

package/plugins/sp/scripts/daily-summary/daily-summary.ts

@@ -130,7 +130,7 @@ export function parseArgs(argv: string[] = process.argv.slice(2)): CliOptions {
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
         if (arg === '--date' && i + 1 < args.length) {
-            options.date = args[++i];
+            options.date = args[++i] ?? options.date;
         } else if (arg === '--dry-run') {
             options.dryRun = true;
         } else if (arg === '--output' && i + 1 < args.length) {
@@ -451,8 +451,8 @@ export async function getGitCommits(date: string): Promise<GitCommit[]> {
                 // This is a numstat line (files changed)
                 const parts = line.split('\t');
                 if (parts.length >= 3) {
-                    const insertions = parseInt(parts[0], 10) || 0;
-                    const deletions = parseInt(parts[1], 10) || 0;
+                    const insertions = parseInt(parts[0] ?? '', 10) || 0;
+                    const deletions = parseInt(parts[1] ?? '', 10) || 0;
                     currentCommit.filesChanged = (currentCommit.filesChanged ?? 0) + 1;
                     currentCommit.insertions = (currentCommit.insertions ?? 0) + insertions;
                     currentCommit.deletions = (currentCommit.deletions ?? 0) + deletions;

package/plugins/sp/scripts/dogfood-testing/detect-pipeline-driving.mjs

@@ -133,6 +133,8 @@ function parseCliArgs(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/dogfood-testing/detect-pipeline-driving.ts

@@ -296,6 +296,7 @@ export function parseCliArgs(argv: string[]): CliArgs {
 
     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/dogfood-testing/validate-report.mjs

@@ -22,8 +22,8 @@ function countLedgerDataRows(markdown) {
   return Math.max(rows.length - 1, 0);
 }
 function declaredExecutedSteps(markdown) {
-  const match = markdown.match(/\*\*Steps:\*\*\s*\d+\s+derived,\s*(\d+)\s+executed/);
-  return match ? Number.parseInt(match[1], 10) : null;
+  const match = markdown.match(/\*\*Steps:\*\*\s*\d+\s+derived,\s*(\d+)\s+executed/)?.[1];
+  return match ? Number.parseInt(match, 10) : null;
 }
 var UNKNOWN_CELLS = new Set(["~unknown", "unknown", "—", "-", "?", "n/a", "~n/a"]);
 var CACHE_SHARE_TOLERANCE = 1;
@@ -46,15 +46,15 @@ function parseTokenCell(cell) {
   const t = cell.trim();
   if (UNKNOWN_CELLS.has(t))
     return null;
-  const m = t.match(/~?(\d+)/);
-  return m ? Number.parseInt(m[1], 10) : null;
+  const m = t.match(/~?(\d+)/)?.[1];
+  return m ? Number.parseInt(m, 10) : null;
 }
 function parsePctCell(cell) {
   const t = cell.trim();
   if (UNKNOWN_CELLS.has(t))
     return null;
-  const m = t.match(/(\d+(?:\.\d+)?)\s*%/);
-  return m ? Number.parseFloat(m[1]) : null;
+  const m = t.match(/(\d+(?:\.\d+)?)\s*%/)?.[1];
+  return m ? Number.parseFloat(m) : null;
 }
 function ledgerCostRows(markdown) {
   const body = sectionBody(markdown, /^### 3\. Monitor Ledger\s*$/m);
@@ -104,7 +104,7 @@ function validateCostEvidence(markdown, errors) {
   }
   for (const scope of pctScopes) {
     for (const m of scope.matchAll(/(\d+(?:\.\d+)?)\s*%/g)) {
-      const pct = Number.parseFloat(m[1]);
+      const pct = Number.parseFloat(m[1] ?? "");
       if (pct < 0 || pct > 100)
         errors.push(`impossible_percentage:${m[0].trim()}`);
     }
@@ -194,6 +194,8 @@ function parseValidateCliArgs(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/dogfood-testing/validate-report.ts

@@ -50,8 +50,8 @@ function countLedgerDataRows(markdown: string): number | null {
 }
 
 function declaredExecutedSteps(markdown: string): number | null {
-    const match = markdown.match(/\*\*Steps:\*\*\s*\d+\s+derived,\s*(\d+)\s+executed/);
-    return match ? Number.parseInt(match[1], 10) : null;
+    const match = markdown.match(/\*\*Steps:\*\*\s*\d+\s+derived,\s*(\d+)\s+executed/)?.[1];
+    return match ? Number.parseInt(match, 10) : null;
 }
 
 // ── Cost evidence contract (task 0913, R2) ──────────────────────────────────
@@ -97,15 +97,15 @@ interface LedgerCostRow {
 function parseTokenCell(cell: string): number | null {
     const t = cell.trim();
     if (UNKNOWN_CELLS.has(t)) return null;
-    const m = t.match(/~?(\d+)/);
-    return m ? Number.parseInt(m[1], 10) : null;
+    const m = t.match(/~?(\d+)/)?.[1];
+    return m ? Number.parseInt(m, 10) : null;
 }
 
 function parsePctCell(cell: string): number | null {
     const t = cell.trim();
     if (UNKNOWN_CELLS.has(t)) return null;
-    const m = t.match(/(\d+(?:\.\d+)?)\s*%/);
-    return m ? Number.parseFloat(m[1]) : null;
+    const m = t.match(/(\d+(?:\.\d+)?)\s*%/)?.[1];
+    return m ? Number.parseFloat(m) : null;
 }
 
 function ledgerCostRows(markdown: string): LedgerCostRow[] {
@@ -169,7 +169,7 @@ function validateCostEvidence(markdown: string, errors: string[]): void {
     }
     for (const scope of pctScopes) {
         for (const m of scope.matchAll(/(\d+(?:\.\d+)?)\s*%/g)) {
-            const pct = Number.parseFloat(m[1]);
+            const pct = Number.parseFloat(m[1] ?? '');
             if (pct < 0 || pct > 100) errors.push(`impossible_percentage:${m[0].trim()}`);
         }
     }
@@ -291,6 +291,7 @@ export function parseValidateCliArgs(argv: string[]): ValidateCliArgs {
     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') json = true;
         else if (a === '--file') file = argv[++i] ?? null;

package/plugins/sp/scripts/feature-sync-bounded.mjs

@@ -103,8 +103,9 @@ through unchanged.
 
 Exit: 0 = sync handled (applied / no-op / suppressed-blocked / live-blocked).`;
 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}`;
@@ -118,6 +119,8 @@ function parseBoundedSyncCliArgs(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/feature-sync-bounded.ts

@@ -251,7 +251,8 @@ Exit: 0 = sync handled (applied / no-op / suppressed-blocked / live-blocked).`;
  * keeps ad-hoc invocations from silently hitting a stale PATH install.
  */
 export 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));
@@ -268,6 +269,7 @@ export function parseBoundedSyncCliArgs(argv: string[]): BoundedSyncCliArgs {
 
     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 === '--spur-bin') spurBin = argv[++i] ?? spurBin;

package/plugins/sp/scripts/feature-verification-steps.ts

@@ -45,12 +45,12 @@ const SAFE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 
 /** Shape of the generated inline bundle / repo app source this script consumes. */
 interface VerificationModule {
-    startFeatureVerificationReceipt: typeof import('../../packages/app/src/workflow/feature-verification-receipt')['startFeatureVerificationReceipt'];
-    completeFeatureVerificationReceipt: typeof import('../../packages/app/src/workflow/feature-verification-receipt')['completeFeatureVerificationReceipt'];
-    captureFeatureReceiptDigest: typeof import('../../packages/app/src/workflow/feature-verification-receipt')['captureFeatureReceiptDigest'];
-    resolveWorkflowDefinition: typeof import('../../packages/app/src/workflow/workflow-resolver')['resolveWorkflowDefinition'];
-    splitLaunchCommand: typeof import('../../packages/app/src/workflow/split-launch-command')['splitLaunchCommand'];
-    openInlineRunProjectDb: typeof import('../../packages/app/src/services/inline-run-setup')['openInlineRunProjectDb'];
+    startFeatureVerificationReceipt: typeof import('../../../packages/app/src/workflow/feature-verification-receipt')['startFeatureVerificationReceipt'];
+    completeFeatureVerificationReceipt: typeof import('../../../packages/app/src/workflow/feature-verification-receipt')['completeFeatureVerificationReceipt'];
+    captureFeatureReceiptDigest: typeof import('../../../packages/app/src/workflow/feature-verification-receipt')['captureFeatureReceiptDigest'];
+    resolveWorkflowDefinition: typeof import('../../../packages/app/src/workflow/workflow-resolver')['resolveWorkflowDefinition'];
+    splitLaunchCommand: typeof import('../../../packages/app/src/workflow/split-launch-command')['splitLaunchCommand'];
+    openInlineRunProjectDb: typeof import('../../../packages/app/src/services/inline-run-setup')['openInlineRunProjectDb'];
     ArtifactDao: new (
         adapter: never,
     ) => { record: (input: { runId: string; path: string; kind: string }) => Promise<unknown> };

package/plugins/sp/scripts/history-anatomy-cache.mjs

@@ -290,9 +290,9 @@ function checkReportStructure(reportMarkdown) {
     const knownRows = findingsBody.match(new RegExp(`^\\|\\s*(?:${catAlt}):[^|]+`, "gm")) ?? [];
     const invalidRows = findingsBody.match(/^\|\s*([^|:\s][^|:]*):[^|]+/gm) ?? [];
     for (const row of [...new Set([...knownRows, ...invalidRows])]) {
-      const segMatch = row.match(/^\|\s*([^:|]+):/);
-      if (segMatch && !FINDING_CATEGORIES.includes(segMatch[1].trim())) {
-        problems.push(`finding-invalid-key-category:${segMatch[1].trim()}`);
+      const seg = row.match(/^\|\s*([^:|]+):/)?.[1];
+      if (seg !== undefined && !FINDING_CATEGORIES.includes(seg.trim())) {
+        problems.push(`finding-invalid-key-category:${seg.trim()}`);
       }
       const rowLower = row.toLowerCase();
       for (const field of FINDING_FIELDS) {

package/plugins/sp/scripts/history-anatomy-cache.ts

@@ -375,9 +375,9 @@ export function checkReportStructure(reportMarkdown: string): { ok: boolean; pro
         for (const row of [...new Set([...knownRows, ...invalidRows])]) {
             // 0686/I9: a pipe row outside the closed first-segment set fails by name instead of
             // being skipped silently by the legacy regex.
-            const segMatch = row.match(/^\|\s*([^:|]+):/);
-            if (segMatch && !(FINDING_CATEGORIES as readonly string[]).includes(segMatch[1].trim())) {
-                problems.push(`finding-invalid-key-category:${segMatch[1].trim()}`);
+            const seg = row.match(/^\|\s*([^:|]+):/)?.[1];
+            if (seg !== undefined && !(FINDING_CATEGORIES as readonly string[]).includes(seg.trim())) {
+                problems.push(`finding-invalid-key-category:${seg.trim()}`);
             }
             // Case-insensitive on BOTH sides — camelCase triage fields otherwise never match a
             // lowercased row.
@@ -630,7 +630,7 @@ export function validateSelector(opts: {
     output?: string;
 }): SelectorValidation {
     const errors: string[] = [];
-    const has = (v?: string) => v !== undefined && v !== '';
+    const has = (v?: string): v is string => v !== undefined && v !== '';
     const val = (v?: string) => (has(v) ? v : null);
     const mode = has(opts.mode) ? opts.mode : 'daily';
     if (mode !== 'daily' && mode !== 'ad-hoc') {

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

@@ -30,7 +30,7 @@ function usage() {
   console.error("       bun plugins/sp/scripts/inline-run-setup.ts --fingerprint --task-file <path> [--feature-file <path>] [--spur-bin <path>]");
   console.error("       bun plugins/sp/scripts/inline-run-setup.ts --action --run-id <id> --node <state> --kind <kind> " + "--status <done|failed> --ok <true|false> --duration-ms <n> [--spur-bin <path>]");
   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> [--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>]");
   process.exit(2);
@@ -154,6 +154,9 @@ async function printFingerprint(taskFile, featureFile, spurBin) {
   return 0;
 }
 var CLOSE_STATUSES = new Set(["done", "failed", "paused"]);
+function isCloseStatus(status) {
+  return CLOSE_STATUSES.has(status);
+}
 var TERMINAL_REASONS = new Set([
   "done",
   "paused-operator",
@@ -166,6 +169,9 @@ var TERMINAL_REASONS = new Set([
   "retry-exhausted"
 ]);
 var ACTION_STATUSES = new Set(["done", "failed"]);
+function isActionStatus(status) {
+  return ACTION_STATUSES.has(status);
+}
 function runRecordLogPath(runDir, runId) {
   const markdownPath = join(runDir, `${runId}.md`);
   const legacyLogPath = join(runDir, `${runId}.log`);
@@ -258,7 +264,7 @@ async function runDecideMode(input) {
   }
   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 })}
+  process.stdout.write(`${JSON.stringify({ runId: input.runId, node: input.node, ...outcome, ok: true })}
 `);
   appendRunLogLine(input.runId, `decide node=${input.node} value=${outcome.value ?? ""} source=${outcome.source ?? "default"} reason=${outcome.reason ?? ""}`);
   return await runTraceMode({
@@ -276,7 +282,11 @@ async function runPersistOutMode(input) {
   try {
     const { entry } = resolveAppEntry(input.spurBin);
     const app = await import(entry);
-    const result = await app.persistWorktreeRuns({ fromWorkdir: input.from, toWorkdir: process.cwd() });
+    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 })}
 `);
     return 0;
@@ -299,7 +309,7 @@ async function main() {
   let runId = "";
   let file = "";
   let fingerprint = false;
-  let taskFile = "";
+  const taskFiles = [];
   let featureFile = "";
   let action = false;
   let close = false;
@@ -323,7 +333,7 @@ async function main() {
     else if (argv[i] === "--fingerprint")
       fingerprint = true;
     else if (argv[i] === "--task-file")
-      taskFile = argv[++i] ?? "";
+      taskFiles.push(argv[++i] ?? "");
     else if (argv[i] === "--feature-file")
       featureFile = argv[++i] ?? "";
     else if (argv[i] === "--action")
@@ -354,12 +364,12 @@ async function main() {
       spurBin = argv[++i] ?? spurBin;
   }
   if (fingerprint) {
-    if (runId !== "" || file !== "" || taskFile.trim() === "")
+    if (runId !== "" || file !== "" || taskFiles.length !== 1 || (taskFiles[0] ?? "").trim() === "")
       usage();
-    process.exit(await printFingerprint(taskFile, featureFile, spurBin));
+    process.exit(await printFingerprint(taskFiles[0] ?? "", featureFile, spurBin));
   }
   if (decide) {
-    if (action || close || fingerprint || file !== "" || taskFile !== "")
+    if (action || close || fingerprint || file !== "" || taskFiles.length > 0)
       usage();
     if (runId.trim() === "" || node.trim() === "" || optionsJson.trim() === "")
       usage();
@@ -368,11 +378,11 @@ async function main() {
     process.exit(await runDecideMode({ runId, node, optionsFile: optionsJson, spurBin }));
   }
   if (persistOut) {
-    if (fingerprint || decide || action || close || runId !== "" || file !== "" || taskFile !== "")
+    if (fingerprint || decide || action || close || runId !== "" || file !== "")
       usage();
-    if (from.trim() === "")
+    if (from.trim() === "" || taskFiles.some((taskFile) => taskFile.trim() === ""))
       usage();
-    process.exit(await runPersistOutMode({ from, spurBin }));
+    process.exit(await runPersistOutMode({ from, taskFiles, spurBin }));
   }
   if (action || close) {
     if (action && close)
@@ -382,7 +392,7 @@ async function main() {
     if (!SAFE_RUN_ID_RE.test(runId))
       refuseUnsafeRunId(runId);
     if (close) {
-      if (!CLOSE_STATUSES.has(status))
+      if (!isCloseStatus(status))
         usage();
       if (reason.trim() === "") {
         if (status === "failed")
@@ -404,7 +414,7 @@ async function main() {
     }
     if (node.trim() === "" || kind.trim() === "")
       usage();
-    if (!ACTION_STATUSES.has(status))
+    if (!isActionStatus(status))
       usage();
     if (okRaw !== "true" && okRaw !== "false")
       usage();

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

@@ -34,7 +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> [--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).
@@ -56,8 +56,12 @@
  * `--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).
- * Idempotent; collisions are reported as `skipped[{id,reason}]`, never overwrites. Exit 0 =
- * persisted (possibly with skips); exit 1 = fail closed — the driver routes to WT-5 and
+ * 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.
@@ -112,7 +116,7 @@ function usage(): never {
         '       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> [--spur-bin <path>]',
+        '       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, ' +
@@ -329,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`.
@@ -350,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';
@@ -362,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;
@@ -553,7 +572,7 @@ 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(
@@ -574,23 +593,34 @@ async function runDecideMode(input: {
 }
 
 /**
- * `--persist-out --from <worktree-path>` (task 0975 R1): 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 idempotence and the conflict skips. 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).
+ * `--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; spurBin: string }): Promise<number> {
+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() });
+        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) {
@@ -612,7 +642,7 @@ 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;
@@ -632,7 +662,7 @@ 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;
@@ -651,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
@@ -663,18 +694,20 @@ 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. Runs with cwd = the invoking tree.
+    // 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 !== '' || taskFile !== '') usage();
-        if (from.trim() === '') usage();
-        process.exit(await runPersistOutMode({ from, spurBin }));
+        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) {
@@ -682,7 +715,7 @@ async function main(): Promise<void> {
         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() === '') {
@@ -705,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

@@ -410,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") {