@gobing-ai/spur 0.3.99 → 0.4.1

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

@@ -17,12 +17,12 @@ import { appendFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { getEnvVars } from '../lib/env';
 import type { QualityGateEnv, QualityGateOptions } from '../lib/quality-gate.generated.mjs';
-import { readReceiptStatus, runLightGate, runQualityGate } from '../lib/quality-gate.generated.mjs';
+import { resolveReceiptReuse, runDeferredGate, runLightGate, runQualityGate } from '../lib/quality-gate.generated.mjs';
 
 export * from '../lib/quality-gate.generated.mjs';
 
 export const QUALITY_GATE_USAGE =
-    'usage: quality-gate.ts <run|recheck|light|status>  (env: wbs, qualityGateCmd, gateProbeCmd, proofDigest, runId)';
+    'usage: quality-gate.ts <run|recheck|light|deferred|status>  (env: wbs, qualityGateCmd, gateProbeCmd, proofDigest, runId)';
 
 export function main(
     argv: string[],
@@ -30,7 +30,7 @@ export function main(
     options: QualityGateOptions = {},
 ): number {
     const mode = argv[0];
-    if (mode !== 'run' && mode !== 'recheck' && mode !== 'light' && mode !== 'status') {
+    if (mode !== 'run' && mode !== 'recheck' && mode !== 'light' && mode !== 'deferred' && mode !== 'status') {
         process.stderr.write(`${QUALITY_GATE_USAGE}\n`);
         return 2;
     }
@@ -42,10 +42,26 @@ export function main(
     const env: QualityGateEnv = { ...rawEnv, wbs };
     if (mode === 'light') {
         runLightGate(env);
+    } else if (mode === 'deferred') {
+        // 1111 R1: light tier for per-task feedback, `DEFERRED`/`FAIL` for the status token —
+        // exit 0 on DEFERRED so the YAML's `; exit 0` wrapper and the action result agree.
+        return runDeferredGate(env, options).status === 'DEFERRED' ? 0 : 1;
     } else if (mode === 'status') {
         const runDir = join(options.cwd ?? '.', '.spur', 'run');
-        const verdict = readReceiptStatus(join(runDir, `${env.wbs}-check-receipt.json`), env.proofDigest ?? '');
-        if (verdict.reuse) {
+        // Task 1136 R3: the gate owns its reuse identity — recompute the proof-input fingerprint
+        // before consulting the receipt, so a caller-copied digest can never trigger reuse.
+        const decision = resolveReceiptReuse(
+            join(runDir, `${env.wbs}-check-receipt.json`),
+            env,
+            options.cwd ?? process.cwd(),
+            options.recomputeFingerprint,
+        );
+        const verdict = decision.receiptStatus;
+        if (decision.refusal !== undefined) {
+            const line = `check.reuse-refused — ${decision.refusal}\n`;
+            process.stdout.write(line); // tee: stdout and the log
+            appendFileSync(join(runDir, `${env.wbs}-test-gate.log`), line);
+        } else if (verdict.reuse) {
             // 0940 R3: reuse is observable in the gate log and on stdout (the action result
             // `data`); the `{reuse, reason}` JSON stays the last stdout line for machine readers.
             const line = `check.reused — full-tier receipt reused for input digest ${env.proofDigest ?? ''}\n`;

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

@@ -164,6 +164,43 @@ function scanResiduals(inputs) {
     counts
   };
 }
+function parseDeferralEntries(raw) {
+  const isDeferral = (e) => typeof e === "object" && e !== null && typeof e.id === "string" && typeof e.reason === "string" && e.reason.trim().length > 0;
+  return (Array.isArray(raw) ? raw : []).filter(isDeferral);
+}
+function blockingReviewFindings(taskContent, deferrals) {
+  const rows = parseReviewFindings(taskContent);
+  const tableDeferrals = rows.flatMap((r) => r.deferral === undefined ? [] : [{ id: makeItemId("review-finding", r.location, r.text), reason: r.deferral }]);
+  const items = rows.map((r) => ({
+    category: "review-finding",
+    priority: r.priority,
+    location: r.location,
+    text: r.text
+  }));
+  return classify(items, [...tableDeferrals, ...deferrals]);
+}
+function buildReviewGateArtifact(wbs, taskContent, deferrals) {
+  const items = blockingReviewFindings(taskContent, deferrals);
+  const blocking = items.filter((i) => i.class === "blocking");
+  const counts = { blocking: 0, deferrable: 0, advisory: 0, housekeeping: 0 };
+  for (const item of items)
+    counts[item.class]++;
+  const artifact = {
+    wbs,
+    base: null,
+    scanned: {
+      "review-finding": true,
+      "diff-marker": false,
+      "unchecked-box": false,
+      "staging-residue": false
+    },
+    items,
+    counts
+  };
+  const note = `residual-review-gate: ${wbs} blocking=${counts.blocking}` + (blocking.length > 0 ? ` ids=${blocking.map((i) => i.id).join(",")} anchors=${blockingAnchors(blocking).join(",")}` : "") + `
+`;
+  return { artifact, note };
+}
 function blockingAnchors(items) {
   const anchors = new Set;
   for (const item of items) {
@@ -262,6 +299,31 @@ function verdictDisagreementNote(runDir, wbs, fs) {
   const winner = mtimeOf(fs, durable) > mtimeOf(fs, run) ? "durable" : "run";
   return `residual-fold: ${wbs} verdict copies disagree — run=${run} (${value(run)}) durable=${durable} (${value(durable)})` + ` → chose ${winner} (newer mtime)`;
 }
+function parseScanArgs(argv, cwd, defaultTmpDir) {
+  let mode = "";
+  let wbs = "";
+  let spurBin;
+  let root = cwd;
+  let tmpDir = defaultTmpDir;
+  for (let i = 0;i < argv.length; i++) {
+    const a = argv[i];
+    if (a === undefined)
+      break;
+    if (a === "--spur-bin")
+      spurBin = argv[++i];
+    else if (a === "--root")
+      root = argv[++i] ?? root;
+    else if (a === "--tmp-dir")
+      tmpDir = argv[++i] ?? tmpDir;
+    else if (a === "--help" || a === "-h")
+      return null;
+    else if (mode === "")
+      mode = a;
+    else if (wbs === "")
+      wbs = a;
+  }
+  return mode === "" || wbs === "" ? null : { mode, wbs, spurBin, root, tmpDir };
+}
 
 // plugins/sp/lib/spur-bin.ts
 function spurCommand(spurBin) {
@@ -270,7 +332,7 @@ function spurCommand(spurBin) {
 }
 
 // plugins/sp/scripts/residual-scan.ts
-var RESIDUAL_SCAN_USAGE = "usage: residual-scan.ts <scan|fold|settle|report> <wbs> [--spur-bin <bin>] [--root <dir>] [--tmp-dir <dir>]";
+var RESIDUAL_SCAN_USAGE = "usage: residual-scan.ts <scan|fold|settle|report|review-gate> <wbs> [--spur-bin <bin>] [--root <dir>] [--tmp-dir <dir>]";
 function run(cmd, args, cwd) {
   const result = spawnSync(cmd, args, { cwd, encoding: "utf8" });
   if (result.error !== undefined)
@@ -326,10 +388,8 @@ function readDeferrals(runDir, wbs) {
   const path = join2(runDir, `${wbs}-residual-deferrals.json`);
   if (!fs.existsSync(path))
     return [];
-  const isDeferral = (e) => typeof e === "object" && e !== null && typeof e.id === "string" && typeof e.reason === "string" && e.reason.trim().length > 0;
   try {
-    const parsed = JSON.parse(fs.readFileSync(path, "utf8"));
-    return (Array.isArray(parsed) ? parsed : []).filter(isDeferral);
+    return parseDeferralEntries(JSON.parse(fs.readFileSync(path, "utf8")));
   } catch {
     return [];
   }
@@ -343,31 +403,6 @@ function scanResiduals2(root, wbs, tmpDir, taskContent, _env) {
   const addedLines = base === null ? [] : collectAddedLines(root, base);
   return scanResiduals({ wbs, base, taskContent, addedLines, stagingResidue, deferrals });
 }
-function parseArgs(argv) {
-  let mode = "";
-  let wbs = "";
-  let spurBin;
-  let root = process.cwd();
-  let tmpDir = tmpdir();
-  for (let i = 0;i < argv.length; i++) {
-    const a = argv[i];
-    if (a === undefined)
-      break;
-    if (a === "--spur-bin")
-      spurBin = argv[++i];
-    else if (a === "--root")
-      root = argv[++i] ?? root;
-    else if (a === "--tmp-dir")
-      tmpDir = argv[++i] ?? tmpDir;
-    else if (a === "--help" || a === "-h")
-      return null;
-    else if (mode === "")
-      mode = a;
-    else if (wbs === "")
-      wbs = a;
-  }
-  return mode === "" || wbs === "" ? null : { mode, wbs, spurBin, root, tmpDir };
-}
 function loadTask(env, spurBinFlag, wbs, root) {
   const res = spur(env, spurBinFlag, ["task", "show", wbs, "--json"], root);
   if (res.status !== 0)
@@ -388,6 +423,16 @@ function scanMode(opts, env, io) {
 `);
   return 0;
 }
+function reviewGateMode(opts, env, io) {
+  const runDir = join2(opts.root, ".spur", "run");
+  fs.mkdirSync(runDir, { recursive: true });
+  const { content } = loadTask(env, opts.spurBin, opts.wbs, opts.root);
+  const gate = buildReviewGateArtifact(opts.wbs, content, readDeferrals(runDir, opts.wbs));
+  fs.writeFileSync(join2(runDir, `${opts.wbs}-residuals.json`), `${JSON.stringify(gate.artifact, null, 2)}
+`);
+  io.out(gate.note);
+  return gate.artifact.counts.blocking > 0 ? 1 : 0;
+}
 function foldMode(opts, _env, io) {
   const runDir = join2(opts.root, ".spur", "run");
   const scan = JSON.parse(fs.readFileSync(join2(runDir, `${opts.wbs}-residuals.json`), "utf8"));
@@ -427,12 +472,7 @@ function settleMode(opts, env, io) {
     prior = JSON.parse(fs.readFileSync(residualsPath, "utf8"));
   const deferred = scan.items.filter((i) => i.class === "deferrable");
   if (deferred.length > 0 && prior.followUp === undefined) {
-    if (task.featureId === "") {
-      io.err(`residual-settle: ${wbs} deferrals pending but feature_id unknown; re-run: residual-scan settle ${wbs}
-`);
-      return 0;
-    }
-    const args = ["task", "create", `Residuals from ${wbs}`, "--feature", task.featureId, "--skip-ready", "--json"];
+    const args = ["task", "create", `Residuals from ${wbs}`, "--skip-ready", "--json"];
     const created = spur(env, opts.spurBin, args, opts.root);
     let wbsNew = "";
     try {
@@ -448,7 +488,7 @@ function settleMode(opts, env, io) {
       return 0;
     }
     const rows = deferred.map((i) => `- ${i.id} \u2014 ${i.location}: ${i.text}`);
-    const head = `Source task: ${wbs} (feature ${task.featureId}) \u2014 deferred residuals filed by residual-scan settle.`;
+    const head = `Source task: ${wbs}${task.featureId === "" ? "" : ` (feature ${task.featureId})`} \u2014 deferred residuals filed by residual-scan settle (unlinked: a deferral must not hold the completing feature open).`;
     const bgFile = join2(runDir, `${wbs}-residual-background.md`);
     fs.writeFileSync(bgFile, `${[head, "", ...rows].join(`
 `)}
@@ -497,8 +537,14 @@ function main(argv, env = getEnvVars(), options = {}) {
     err: (line) => process.stderr.write(line)
   };
   const cwd = options.cwd ?? process.cwd();
-  const opts = parseArgs(argv);
-  const modes = { scan: scanMode, fold: foldMode, settle: settleMode, report: reportMode };
+  const opts = parseScanArgs(argv, cwd, tmpdir());
+  const modes = {
+    scan: scanMode,
+    fold: foldMode,
+    settle: settleMode,
+    report: reportMode,
+    "review-gate": reviewGateMode
+  };
   const modeFn = opts === null ? undefined : modes[opts.mode];
   if (opts === null || modeFn === undefined) {
     io.err(`${RESIDUAL_SCAN_USAGE}
@@ -514,8 +560,10 @@ export {
   scanResiduals2 as scanResiduals,
   renderReport,
   recordedVerdictPath,
+  parseScanArgs,
   parseReviewFindings,
   parseDiffMarkers,
+  parseDeferralEntries,
   normalizeAnchor,
   makeItemId,
   main,
@@ -525,6 +573,8 @@ export {
   findUncheckedBoxes,
   collectAddedLines,
   classify,
+  buildReviewGateArtifact,
+  blockingReviewFindings,
   blockingAnchors,
   RESIDUAL_SCAN_USAGE,
   ALLOW_PRAGMA

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

@@ -10,12 +10,12 @@ import { spurCommand } from '../lib/spur-bin';
 
 export * from '../lib/residual-scan.generated.mjs';
 export const RESIDUAL_SCAN_USAGE =
-    'usage: residual-scan.ts <scan|fold|settle|report> <wbs> [--spur-bin <bin>] [--root <dir>] [--tmp-dir <dir>]';
+    'usage: residual-scan.ts <scan|fold|settle|report|review-gate> <wbs> [--spur-bin <bin>] [--root <dir>] [--tmp-dir <dir>]';
 export type ScanEnv = { spurBin?: string } & Record<string, string | undefined>;
 export type ScanIo = { out: (line: string) => void; err: (line: string) => void };
 export type ScanOptions = { cwd?: string; io?: ScanIo };
 type RunResult = { status: number; stdout: string };
-type ParsedArgs = { mode: string; wbs: string; spurBin?: string; root: string; tmpDir: string };
+type ParsedArgs = core.ParsedScanArgs;
 type ModeFn = (o: ParsedArgs, e: ScanEnv, i: ScanIo) => number;
 type ScanTask = { content: string; featureId: string };
 type VerdictFile = { verdict: string; checks: Array<{ name: string; status: string; evidence: string }> };
@@ -66,15 +66,8 @@ export function listStagingResidue(tmpDir: string, wbs: string): string[] {
 function readDeferrals(runDir: string, wbs: string): core.Deferral[] {
     const path = join(runDir, `${wbs}-residual-deferrals.json`);
     if (!fs.existsSync(path)) return [];
-    const isDeferral = (e: unknown): e is core.Deferral =>
-        typeof e === 'object' &&
-        e !== null &&
-        typeof (e as core.Deferral).id === 'string' &&
-        typeof (e as core.Deferral).reason === 'string' &&
-        (e as core.Deferral).reason.trim().length > 0;
     try {
-        const parsed: unknown = JSON.parse(fs.readFileSync(path, 'utf8'));
-        return (Array.isArray(parsed) ? parsed : []).filter(isDeferral);
+        return core.parseDeferralEntries(JSON.parse(fs.readFileSync(path, 'utf8')));
     } catch {
         return [];
     }
@@ -88,24 +81,6 @@ export function scanResiduals(root: string, wbs: string, tmpDir: string, taskCon
     const addedLines = base === null ? [] : collectAddedLines(root, base);
     return core.scanResiduals({ wbs, base, taskContent, addedLines, stagingResidue, deferrals });
 }
-function parseArgs(argv: string[]): ParsedArgs | null {
-    let mode = '';
-    let wbs = '';
-    let spurBin: string | undefined;
-    let root = process.cwd();
-    let tmpDir = tmpdir();
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === undefined) break;
-        if (a === '--spur-bin') spurBin = argv[++i];
-        else if (a === '--root') root = argv[++i] ?? root;
-        else if (a === '--tmp-dir') tmpDir = argv[++i] ?? tmpDir;
-        else if (a === '--help' || a === '-h') return null;
-        else if (mode === '') mode = a;
-        else if (wbs === '') wbs = a;
-    }
-    return mode === '' || wbs === '' ? null : { mode, wbs, spurBin, root, tmpDir };
-}
 function loadTask(env: ScanEnv, spurBinFlag: string | undefined, wbs: string, root: string): ScanTask {
     const res = spur(env, spurBinFlag, ['task', 'show', wbs, '--json'], root);
     if (res.status !== 0) throw new Error(`task show ${wbs} failed`);
@@ -128,6 +103,23 @@ function scanMode(opts: ParsedArgs, env: ScanEnv, io: ScanIo): number {
     );
     return 0;
 }
+/**
+ * Task 1122 R2: the review-time gate — the record sweep's review-finding slice with the same
+ * parse/classify/deferrals (core.buildReviewGateArtifact), applied at the review PASS edges
+ * before verify spends the cycle. Writes the same `<wbs>-residuals.json` artifact the test-fix
+ * hop already appends to the gate log (its remediation input); the record sweep stays the final
+ * authority and overwrites it. Exit 1 on an open P1-P3 finding fails the review PASS edge closed
+ * into review-fail-triage.
+ */
+function reviewGateMode(opts: ParsedArgs, env: ScanEnv, io: ScanIo): number {
+    const runDir = join(opts.root, '.spur', 'run');
+    fs.mkdirSync(runDir, { recursive: true });
+    const { content } = loadTask(env, opts.spurBin, opts.wbs, opts.root);
+    const gate = core.buildReviewGateArtifact(opts.wbs, content, readDeferrals(runDir, opts.wbs));
+    fs.writeFileSync(join(runDir, `${opts.wbs}-residuals.json`), `${JSON.stringify(gate.artifact, null, 2)}\n`);
+    io.out(gate.note);
+    return gate.artifact.counts.blocking > 0 ? 1 : 0;
+}
 function foldMode(opts: ParsedArgs, _env: ScanEnv, io: ScanIo): number {
     const runDir = join(opts.root, '.spur', 'run');
     const scan = JSON.parse(
@@ -170,13 +162,12 @@ function settleMode(opts: ParsedArgs, env: ScanEnv, io: ScanIo): number {
     if (fs.existsSync(residualsPath)) prior = JSON.parse(fs.readFileSync(residualsPath, 'utf8'));
     const deferred = scan.items.filter((i) => i.class === 'deferrable');
     if (deferred.length > 0 && prior.followUp === undefined) {
-        if (task.featureId === '') {
-            io.err(
-                `residual-settle: ${wbs} deferrals pending but feature_id unknown; re-run: residual-scan settle ${wbs}\n`,
-            );
-            return 0;
-        }
-        const args = ['task', 'create', `Residuals from ${wbs}`, '--feature', task.featureId, '--skip-ready', '--json'];
+        // The follow-up is filed UNLINKED: carrying a feature edge to the feature whose run produced
+        // it made that feature's done-gate fail with `L4.verifying-incomplete-tasks` the moment a
+        // residual was deferred (2026-10-04 session, E72/1086→1087), so a deferral must not be able
+        // to block the completing feature. The source task and its feature stay named in the
+        // Background, which keeps the traceability without the lifecycle coupling.
+        const args = ['task', 'create', `Residuals from ${wbs}`, '--skip-ready', '--json'];
         const created = spur(env, opts.spurBin, args, opts.root);
         let wbsNew = '';
         try {
@@ -191,7 +182,7 @@ function settleMode(opts: ParsedArgs, env: ScanEnv, io: ScanIo): number {
             return 0;
         }
         const rows = deferred.map((i) => `- ${i.id} — ${i.location}: ${i.text}`);
-        const head = `Source task: ${wbs} (feature ${task.featureId}) — deferred residuals filed by residual-scan settle.`;
+        const head = `Source task: ${wbs}${task.featureId === '' ? '' : ` (feature ${task.featureId})`} — deferred residuals filed by residual-scan settle (unlinked: a deferral must not hold the completing feature open).`;
         const bgFile = join(runDir, `${wbs}-residual-background.md`);
         fs.writeFileSync(bgFile, `${[head, '', ...rows].join('\n')}\n`);
         const updArgs = ['task', 'update', wbsNew, '--section', 'Background', '--from-file', bgFile];
@@ -237,8 +228,14 @@ export function main(argv: string[], env: ScanEnv = getEnvVars(), options: ScanO
         err: (line) => process.stderr.write(line),
     };
     const cwd = options.cwd ?? process.cwd();
-    const opts = parseArgs(argv);
-    const modes: Record<string, ModeFn> = { scan: scanMode, fold: foldMode, settle: settleMode, report: reportMode };
+    const opts = core.parseScanArgs(argv, cwd, tmpdir());
+    const modes: Record<string, ModeFn> = {
+        scan: scanMode,
+        fold: foldMode,
+        settle: settleMode,
+        report: reportMode,
+        'review-gate': reviewGateMode,
+    };
     const modeFn = opts === null ? undefined : modes[opts.mode];
     if (opts === null || modeFn === undefined) {
         io.err(`${RESIDUAL_SCAN_USAGE}\n`);