@gobing-ai/spur 0.3.92 → 0.3.93

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

@@ -13,14 +13,36 @@
  *
  * Modes:
  *   run     reset the attempt counter, truncate the log, execute the gate loop
- *   recheck truncate the log, execute the probe first (probe failure is the gate
- *           failure, the gate loop is skipped), then execute the gate loop
+ *   recheck truncate the log; a full-tier FAIL receipt at the current digest is a
+ *           no-progress skip straight to the FAIL write (0940 R2), otherwise the probe
+ *           runs first (probe failure is the gate failure, the gate loop is skipped),
+ *           then the gate loop
+ *   light   changed-scope tier (task 0939, ADR-124): biome on the changed files,
+ *           per-workspace typecheck, and filename-mapped related tests run inside
+ *           their workspace; merges rows under `tier: light`, soft-fails
+ *   status  print `{reuse, reason}` for the task's receipt and exit 0
  *
  * Retry contract: a failed attempt is retried (up to 5 total attempts) only when its
  * output matches a SQLite busy/locked error; the delay defaults to 10 seconds and is
  * overridable via `SPUR_QUALITY_GATE_RETRY_DELAY_MS` (tests).
  *
- * Environment: `wbs` (required), `qualityGateCmd`, `gateProbeCmd` (recheck), `proofDigest`.
+ * 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
+ * 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
+ * the same `{id, inputDigest}` is skipped, and light rows never make a receipt reusable for
+ * review — `status` reuses only `PASS` + `tier: full` + matching digest. Reuse observability
+ * (0940 R3): `status` reuse and light accumulation emit `check.reused`, and the no-progress
+ * recheck emits `check.skipped-no-progress`, in the gate log and on stdout (the action result
+ * `data`); both surfaces run this same script, so there is no surface branch.
+ *
+ * Standalone contract: the digest is consumed, never computed — the pipeline captures it with
+ * `proof.fingerprint` into `env.proofDigest`; standalone callers use
+ * `inline-run-setup.ts --fingerprint`. No `@gobing-ai/*` value imports.
+ *
+ * Environment: `wbs` (required), `qualityGateCmd`, `gateProbeCmd` (recheck), `proofDigest`,
+ * `runId` (receipt identity; falls back to `pipeline-<wbs>`).
  * Soft-fail contract: the process always exits 0; the verdict lives in the status file.
  *
  * Node-builtin imports only; pure helpers are exported for unit testing (ADR-065).
@@ -65,6 +87,8 @@ export interface QualityGateEnv {
     qualityGateCmd?: string;
     gateProbeCmd?: string;
     proofDigest?: string;
+    /** Receipt run identity; `pipeline-<wbs>` when absent (task-pipeline convention). */
+    runId?: string;
     [key: string]: string | undefined;
 }
 
@@ -80,6 +104,8 @@ export interface QualityGateResult {
     findingsFile: string;
     statusFile: string;
     attemptFile: string;
+    /** Written only by `run` with `proofDigest` set (0939 R2). */
+    receiptFile?: string;
 }
 
 export function isTransientLock(attemptOutput: string): boolean {
@@ -156,6 +182,323 @@ export function scanCoverageShortfalls(logText: string, threshold: CoverageThres
     return [...shortfalls.values()];
 }
 
+// ─── Check receipts + light tier (task 0939, ADR-124) ───
+
+export const RECEIPT_SCHEMA_VERSION = 'check-receipt/v1';
+
+export type ReceiptTier = 'full' | 'light';
+export type CheckStatus = 'PASS' | 'FAIL';
+/** Frozen non-reuse reasons of `status` mode (0939 R3). */
+export type ReceiptReuseReason = 'missing' | 'failed' | 'stale' | 'light-only';
+
+export interface CheckReceiptRow {
+    id: string;
+    cmd: string;
+    status: CheckStatus;
+    durationMs: number;
+    logPath: string;
+}
+
+export interface CheckReceipt {
+    schemaVersion: 'check-receipt/v1';
+    wbs: string;
+    runId: string;
+    tier: ReceiptTier;
+    inputDigest: string;
+    checks: CheckReceiptRow[];
+    status: CheckStatus;
+    completedAt: string;
+}
+
+export interface ReceiptReadStatus {
+    reuse: boolean;
+    /** `'ok'` only when reuse holds; otherwise one of the frozen reasons. */
+    reason: ReceiptReuseReason | 'ok';
+}
+
+export interface BuildReceiptInput {
+    wbs: string;
+    runId: string;
+    tier: ReceiptTier;
+    inputDigest: string;
+    checks: CheckReceiptRow[];
+    /** ISO-8601 completion timestamp; injected so receipts stay reproducible in tests. */
+    completedAt: string;
+}
+
+/** Stamp `check-receipt/v1`; the overall status derives from the rows (no rows → PASS). */
+export function buildReceipt(input: BuildReceiptInput): CheckReceipt {
+    return {
+        schemaVersion: RECEIPT_SCHEMA_VERSION,
+        wbs: input.wbs,
+        runId: input.runId,
+        tier: input.tier,
+        inputDigest: input.inputDigest,
+        checks: input.checks,
+        status: input.checks.every((row) => row.status === 'PASS') ? 'PASS' : 'FAIL',
+        completedAt: input.completedAt,
+    };
+}
+
+/** Parse a check receipt; `null` when absent, unreadable, or corrupt. */
+function readReceipt(receiptPath: string): CheckReceipt | null {
+    try {
+        return JSON.parse(readFileSync(receiptPath, 'utf8')) as CheckReceipt;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * 0940 R2 — no-progress recheck shape: a full-tier FAIL receipt bound to the current proof-input
+ * digest, i.e. the fix pass changed nothing tracked and the full chain can only reproduce the
+ * failure. `readReceiptStatus` cannot express this decision (a FAIL receipt is `reason: 'failed'`
+ * at every digest), so the two fields are compared directly. Light-tier receipts and any digest
+ * mismatch never skip — the probe and full gate run unchanged (anti-pattern: reusing a light
+ * receipt, or comparing against a digest captured before `test-fix`).
+ */
+export function receiptFailsAtDigest(receipt: CheckReceipt | null, currentDigest: string): boolean {
+    return (
+        receipt !== null &&
+        receipt.schemaVersion === RECEIPT_SCHEMA_VERSION &&
+        receipt.tier === 'full' &&
+        receipt.status === 'FAIL' &&
+        currentDigest.length > 0 &&
+        receipt.inputDigest === currentDigest
+    );
+}
+
+/**
+ * Reuse verdict for `.spur/run/<wbs>-check-receipt.json` against the current proof-input digest.
+ * Evaluated missing → failed → stale → light-only; reuse requires `PASS` + `tier: full` + digest
+ * match, so light rows can never flip a receipt reusable (0939 invariant).
+ */
+export function readReceiptStatus(receiptPath: string, currentDigest: string): ReceiptReadStatus {
+    const receipt = readReceipt(receiptPath);
+    if (receipt === null || receipt.schemaVersion !== RECEIPT_SCHEMA_VERSION) {
+        return { reuse: false, reason: 'missing' };
+    }
+    if (receipt.status !== 'PASS') return { reuse: false, reason: 'failed' };
+    if (currentDigest.length === 0 || receipt.inputDigest !== currentDigest) {
+        return { reuse: false, reason: 'stale' };
+    }
+    if (receipt.tier !== 'full') return { reuse: false, reason: 'light-only' };
+    return { reuse: true, reason: 'ok' };
+}
+
+const TEST_FILE_PATTERN = /\.test\.tsx?$/;
+
+export interface LightScope {
+    files: string[];
+    workspaces: string[];
+    tests: string[];
+}
+
+/**
+ * The bun workspace a changed file belongs to: the shortest directory prefix below the repo root
+ * that holds a package.json (`apps/*`, `packages/*`). Null for root-level files, which no
+ * workspace owns. Pure via the injected `exists` predicate.
+ */
+function workspaceOf(file: string, exists: (p: string) => boolean): string | null {
+    const segments = file.split('/');
+    for (let depth = 1; depth < segments.length; depth++) {
+        const prefix = segments.slice(0, depth).join('/');
+        if (exists(`${prefix}/package.json`)) return prefix;
+    }
+    return null;
+}
+
+/**
+ * Light-tier scope from changed repo-relative paths: every touched workspace plus the related
+ * tests. `<ws>/src/**x.ts` maps to `<ws>/tests/**x.test.ts` by filename (refine decision —
+ * deterministic and cheap; the import graph is not consulted), and a changed `*.test.ts` under a
+ * workspace includes itself. The full tier stays the safety net for everything the mapping
+ * misses. Unmapped-but-existing candidates are dropped by the `exists` check.
+ */
+export function lightScope(changedFiles: string[], exists: (p: string) => boolean = existsSync): LightScope {
+    const files: string[] = [];
+    const workspaces = new Set<string>();
+    const tests = new Set<string>();
+    for (const file of changedFiles) {
+        files.push(file);
+        const workspace = workspaceOf(file, exists);
+        if (workspace === null) continue;
+        workspaces.add(workspace);
+        const rest = file.slice(workspace.length + 1);
+        if (rest.startsWith('src/')) {
+            const candidate = `${workspace}/tests/${rest.slice('src/'.length).replace(/\.tsx?$/, (ext) => `.test${ext}`)}`;
+            if (exists(candidate)) tests.add(candidate);
+        } else if (rest.startsWith('tests/') && TEST_FILE_PATTERN.test(rest)) {
+            tests.add(file);
+        }
+    }
+    return { files, workspaces: [...workspaces].sort(), tests: [...tests].sort() };
+}
+
+export interface LightCheckPlan {
+    id: string;
+    cmd: string;
+}
+
+/** Does the workspace package.json declare a `typecheck` script? (fs default; tests inject.) */
+export function workspaceHasTypecheck(workspace: string): boolean {
+    try {
+        const pkg = JSON.parse(readFileSync(join(workspace, 'package.json'), 'utf8')) as {
+            scripts?: { typecheck?: string };
+        };
+        return typeof pkg.scripts?.typecheck === 'string';
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * The light sub-checks for a scope, in run order: `format-lint:changed` (biome, repo root),
+ * `typecheck:<ws>` per workspace declaring the script, `test:<ws>` per workspace with related
+ * tests. Tests always run through `cd <ws> &&` — never from the repo root, whose bunfig preload
+ * does not apply inside the workspace.
+ */
+export function planLightChecks(
+    scope: LightScope,
+    hasTypecheck: (workspace: string) => boolean = workspaceHasTypecheck,
+): LightCheckPlan[] {
+    const plans: LightCheckPlan[] = [];
+    if (scope.files.length > 0) {
+        plans.push({ id: 'format-lint:changed', cmd: `bunx biome check ${scope.files.join(' ')}` });
+    }
+    for (const workspace of scope.workspaces) {
+        if (hasTypecheck(workspace)) {
+            plans.push({ id: `typecheck:${workspace}`, cmd: `cd ${workspace} && bun run typecheck` });
+        }
+    }
+    const testsByWorkspace = new Map<string, string[]>();
+    for (const test of scope.tests) {
+        const workspace = test.slice(0, test.indexOf('/tests/'));
+        const paths = testsByWorkspace.get(workspace) ?? [];
+        paths.push(test.slice(workspace.length + 1));
+        testsByWorkspace.set(workspace, paths);
+    }
+    for (const [workspace, paths] of testsByWorkspace) {
+        plans.push({ id: `test:${workspace}`, cmd: `cd ${workspace} && bun test ${paths.join(' ')}` });
+    }
+    return plans;
+}
+
+/** Changed paths for the light tier: `git diff --name-only HEAD` plus untracked; existing only. */
+function gitChangedFiles(cwd: string | undefined): string[] {
+    const abs = (p: string): string => (cwd ? join(cwd, p) : p);
+    const changed = new Set<string>();
+    for (const cmd of ['git diff --name-only HEAD', 'git ls-files --others --exclude-standard']) {
+        const result = runShellCommand(cmd, cwd);
+        for (const line of result.output.split('\n')) {
+            const file = line.trim();
+            if (file.length > 0 && existsSync(abs(file))) changed.add(file);
+        }
+    }
+    return [...changed].sort();
+}
+
+function receiptRunId(env: QualityGateEnv): string {
+    return (env.runId ?? '').length > 0 ? (env.runId as string) : `pipeline-${env.wbs}`;
+}
+
+export interface LightGateResult {
+    status: CheckStatus;
+    scope: LightScope;
+    checks: CheckReceiptRow[];
+    logFile: string;
+    receiptFile: string;
+}
+
+/**
+ * Light tier (0939 R1): run the planned sub-checks, merge their rows into the receipt under
+ * `tier: light`, exit soft. A sub-check already PASS in a light receipt at the same
+ * `{id, inputDigest}` is skipped (accumulation, AC1); prior rows whose id left the plan are
+ * dropped with the rest of the old receipt.
+ */
+export function runLightGate(env: QualityGateEnv, options: QualityGateOptions = {}): LightGateResult {
+    const cwd = options.cwd;
+    const abs = (p: string): string => (cwd ? join(cwd, p) : p);
+    const runDir = join('.spur', 'run');
+    mkdirSync(abs(runDir), { recursive: true });
+    const logFile = join(runDir, `${env.wbs}-light-gate.log`);
+    const receiptFile = join(runDir, `${env.wbs}-check-receipt.json`);
+    writeFileSync(abs(logFile), '');
+
+    const digest = env.proofDigest ?? '';
+    const scope = lightScope(gitChangedFiles(cwd), (p) => existsSync(abs(p)));
+    // Bind the fs predicates to the gate cwd, not the process cwd (tests run gates in fixtures).
+    const plans = planLightChecks(scope, (workspace) => workspaceHasTypecheck(abs(workspace)));
+
+    const reusable = new Map<string, CheckReceiptRow>();
+    let preserveFullReceipt = false;
+    if (digest.length > 0) {
+        try {
+            const prior = JSON.parse(readFileSync(abs(receiptFile), 'utf8')) as CheckReceipt;
+            if (prior?.schemaVersion === RECEIPT_SCHEMA_VERSION && prior.inputDigest === digest) {
+                if (prior.tier === 'full') {
+                    // A full-tier receipt at the same digest is boundary evidence read by status
+                    // mode (0940/0943); light must never demote it to a tier-light receipt.
+                    preserveFullReceipt = true;
+                } else {
+                    for (const row of prior.checks ?? []) if (row.status === 'PASS') reusable.set(row.id, row);
+                }
+            }
+        } catch {
+            // No prior receipt (or unreadable) — every planned sub-check runs.
+        }
+    }
+
+    const checks: CheckReceiptRow[] = [];
+    let skipped = 0;
+    for (const plan of plans) {
+        const priorRow = reusable.get(plan.id);
+        if (priorRow !== undefined) {
+            checks.push(priorRow);
+            skipped++;
+            // 0940 R3: accumulation reuse is observable in the gate log and on stdout (the
+            // action result `data`); both surfaces run this same script.
+            const line = `--- light ${plan.id}: check.reused — skipped (PASS at the same input digest)\n`;
+            process.stdout.write(line); // tee: stdout and the log
+            appendFileSync(abs(logFile), line);
+            continue;
+        }
+        const startedAtMs = Date.now();
+        const result = runShellCommand(plan.cmd, cwd);
+        const durationMs = Date.now() - startedAtMs;
+        const status: CheckStatus = result.code === 0 ? 'PASS' : 'FAIL';
+        appendFileSync(abs(logFile), `--- light ${plan.id}: ${status} (${durationMs}ms)\n${result.output}`);
+        checks.push({ id: plan.id, cmd: plan.cmd, status, durationMs, logPath: logFile });
+    }
+
+    const receipt = buildReceipt({
+        wbs: env.wbs,
+        runId: receiptRunId(env),
+        tier: 'light',
+        inputDigest: digest,
+        checks,
+        completedAt: new Date().toISOString(),
+    });
+    if (preserveFullReceipt) {
+        // Light ran for its log; the file keeps the full-tier receipt untouched.
+        appendFileSync(
+            abs(logFile),
+            '--- light receipt: not written — the full-tier receipt at the same input digest is preserved\n',
+        );
+        process.stdout.write(
+            `light gate ${receipt.status} (${scope.files.length} changed files; checks: ${checks.length},` +
+                ` skipped: ${skipped}; receipt: ${receiptFile} preserved (full tier); log: ${logFile})\n`,
+        );
+    } else {
+        writeFileSync(abs(receiptFile), `${JSON.stringify(receipt, null, 2)}\n`);
+        process.stdout.write(
+            `light gate ${receipt.status} (${scope.files.length} changed files; checks: ${checks.length},` +
+                ` skipped: ${skipped}; receipt: ${receiptFile}; log: ${logFile})\n`,
+        );
+    }
+    return { status: receipt.status, scope, checks, logFile, receiptFile };
+}
+
 function retryDelayMs(env: QualityGateEnv): number {
     const raw = Number.parseInt(env[RETRY_DELAY_MS_ENV] ?? '', 10);
     return Number.isFinite(raw) && raw >= 0 ? raw : RETRY_DELAY_MS_DEFAULT;
@@ -201,12 +544,28 @@ export function runQualityGate(
     // run: `echo 0 > "$ATTEMPT_FILE" && : > "$LOG_FILE"`; recheck: truncate only.
     writeFileSync(abs(logFile), '');
     if (mode === 'run') writeFileSync(abs(attemptFile), '0\n');
+    const gateStartedAtMs = Date.now();
 
     let gateRc = 0;
     let gateAttempt = 0;
 
+    // 0940 R2 — no-progress skip, before the probe: a full-tier FAIL receipt at the current
+    // proof-input digest means the fix pass changed nothing tracked, so the full chain can only
+    // reproduce the failure. The marker tees to stdout (the action result `data`) and the log,
+    // then the shared FAIL path below writes findings/status/verdict exactly as a red gate does.
+    // The attempt counter is pipeline-owned (only the test-fix hop increments it; `recheck` never
+    // touches it), so the existing cap still bounds the loop.
+    const noProgressSkip =
+        mode === 'recheck' && receiptFailsAtDigest(readReceipt(abs(rel('-check-receipt.json'))), env.proofDigest ?? '');
+    if (noProgressSkip) {
+        const line = `check.skipped-no-progress — full-tier FAIL receipt at input digest ${env.proofDigest ?? ''}; recheck skipped\n`;
+        process.stdout.write(line); // tee: stdout and the log
+        appendFileSync(abs(logFile), line);
+        gateRc = 1;
+    }
+
     // recheck probe: a probe failure is the gate failure; the gate loop is skipped.
-    if (mode === 'recheck' && (env.gateProbeCmd ?? '').length > 0) {
+    if (mode === 'recheck' && !noProgressSkip && (env.gateProbeCmd ?? '').length > 0) {
         const probe = runShellCommand(env.gateProbeCmd ?? '', cwd);
         writeFileSync(abs(`${logFile}.probe`), probe.output);
         gateRc = probe.code;
@@ -263,15 +622,42 @@ export function runQualityGate(
     writeFileSync(abs(statusFile), `${status}\n`);
     appendFileSync(abs(logFile), `proof-digest: ${env.proofDigest ?? ''}\n`);
 
-    return { status, attempts: gateAttempt, logFile, findingsFile, statusFile, attemptFile };
+    // 0939 R2: only `run` writes the full-tier receipt, and only with a digest to bind it to.
+    let receiptFile: string | undefined;
+    if (mode === 'run') {
+        if ((env.proofDigest ?? '').length > 0) {
+            receiptFile = join(runDir, `${env.wbs}-check-receipt.json`);
+            const receipt = buildReceipt({
+                wbs: env.wbs,
+                runId: receiptRunId(env),
+                tier: 'full',
+                inputDigest: env.proofDigest ?? '',
+                checks: [
+                    {
+                        id: 'test',
+                        cmd: env.qualityGateCmd ?? '',
+                        status,
+                        durationMs: Date.now() - gateStartedAtMs,
+                        logPath: logFile,
+                    },
+                ],
+                completedAt: new Date().toISOString(),
+            });
+            writeFileSync(abs(receiptFile), `${JSON.stringify(receipt, null, 2)}\n`);
+        } else {
+            appendFileSync(abs(logFile), 'check-receipt: not written — env `proofDigest` is not set\n');
+        }
+    }
+
+    return { status, attempts: gateAttempt, logFile, findingsFile, statusFile, attemptFile, receiptFile };
 }
 
 export const QUALITY_GATE_USAGE =
-    'usage: quality-gate.ts <run|recheck>  (env: wbs, qualityGateCmd, gateProbeCmd, proofDigest)';
+    'usage: quality-gate.ts <run|recheck|light|status>  (env: wbs, qualityGateCmd, gateProbeCmd, proofDigest, runId)';
 
-export function main(argv: string[], env: QualityGateEnv = getEnvVars()): number {
+export function main(argv: string[], env: QualityGateEnv = getEnvVars(), options: QualityGateOptions = {}): number {
     const mode = argv[0];
-    if (mode !== 'run' && mode !== 'recheck') {
+    if (mode !== 'run' && mode !== 'recheck' && mode !== 'light' && mode !== 'status') {
         process.stderr.write(`${QUALITY_GATE_USAGE}\n`);
         return 2;
     }
@@ -279,7 +665,22 @@ export function main(argv: string[], env: QualityGateEnv = getEnvVars()): number
         process.stderr.write('quality-gate: env `wbs` is required\n');
         return 2;
     }
-    runQualityGate(mode, env);
+    if (mode === 'light') {
+        runLightGate(env);
+    } 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) {
+            // 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`;
+            process.stdout.write(line); // tee: stdout and the log
+            appendFileSync(join(runDir, `${env.wbs}-test-gate.log`), line);
+        }
+        process.stdout.write(`${JSON.stringify(verdict)}\n`);
+    } else {
+        runQualityGate(mode, env);
+    }
     return 0;
 }
 

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

@@ -18,6 +18,9 @@ var RESIDUAL_SCAN_USAGE = "usage: residual-scan.ts <scan|fold|settle|report> <wb
 var MARKER_PATTERN = /TODO|FIXME|XXX|HACK/;
 var PRIORITY_PATTERN = /^P[1-4]/;
 var NONE_FINDING = /^(none|\u2014)$/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;
 var ANCHOR_PATTERN = /[A-Za-z0-9_./-]+\.[A-Za-z]+:[0-9]+/g;
 var RANGE_ANCHOR = /([A-Za-z0-9_./-]+\.[A-Za-z]+):([0-9]+)-[0-9]+/g;
 var EXCLUDED_PATHS = ["docs/tasks", "docs/features/", ".spur/"];
@@ -68,6 +71,7 @@ function parseReviewFindings(taskContent) {
     }
     const findingCol = header.findIndex((h) => h.trim() === "Finding");
     const locationCol = header.findIndex((h) => h.trim() === "Location");
+    const dispositionCol = header.findIndex((h) => DISPOSITION_HEADER.test(h.trim()));
     i++;
     const sep = lines[i];
     if (sep !== undefined && /^\s*\|[\s:|-]+\|\s*$/.test(sep))
@@ -79,8 +83,10 @@ function parseReviewFindings(taskContent) {
       const cells = splitRow(row);
       const priority = (cells[priorityCol] ?? "").trim();
       const finding = (cells[findingCol] ?? "").trim();
-      if (PRIORITY_PATTERN.test(priority) && !NONE_FINDING.test(finding) && finding.length > 0) {
-        out.push({ priority, location: locationOf(cells[locationCol] ?? "", finding), text: finding });
+      const disposition = dispositionCol === -1 ? "" : (cells[dispositionCol] ?? "").trim();
+      if (PRIORITY_PATTERN.test(priority) && !NONE_FINDING.test(finding) && finding.length > 0 && !RESOLVED_DISPOSITION.test(disposition)) {
+        const location = locationOf(cells[locationCol] ?? "", finding);
+        out.push(DEFERRED_DISPOSITION.test(disposition) ? { priority, location, text: finding, deferral: disposition } : { priority, location, text: finding });
       }
       i++;
     }
@@ -193,7 +199,9 @@ function scanResiduals(root, wbs, tmpDir, taskContent, _env) {
   const runDir = join(root, ".spur", "run");
   const basePath = join(runDir, `${wbs}-base.sha`);
   const base = existsSync(basePath) ? readFileSync(basePath, "utf8").trim() : null;
-  const review = parseReviewFindings(taskContent).map((r) => ({
+  const reviewRows = parseReviewFindings(taskContent);
+  const tableDeferrals = reviewRows.flatMap((r) => r.deferral === undefined ? [] : [{ id: makeItemId("review-finding", r.location, r.text), reason: r.deferral }]);
+  const review = reviewRows.map((r) => ({
     category: "review-finding",
     priority: r.priority,
     location: r.location,
@@ -214,7 +222,7 @@ function scanResiduals(root, wbs, tmpDir, taskContent, _env) {
     location: p,
     text: p
   }));
-  const items = classify([...review, ...markers, ...boxes, ...residue], readDeferrals(runDir, wbs));
+  const items = classify([...review, ...markers, ...boxes, ...residue], [...tableDeferrals, ...readDeferrals(runDir, wbs)]);
   const counts = { blocking: 0, deferrable: 0, advisory: 0, housekeeping: 0 };
   for (const item of items)
     counts[item.class]++;

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

@@ -65,6 +65,9 @@ export interface ScanOptions {
 const MARKER_PATTERN = /TODO|FIXME|XXX|HACK/;
 const PRIORITY_PATTERN = /^P[1-4]/;
 const NONE_FINDING = /^(none|—)$/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;
 const ANCHOR_PATTERN = /[A-Za-z0-9_./-]+\.[A-Za-z]+:[0-9]+/g;
 /** `path:12-18` range anchor → single-line `path:12`. */
 const RANGE_ANCHOR = /([A-Za-z0-9_./-]+\.[A-Za-z]+):([0-9]+)-[0-9]+/g;
@@ -108,12 +111,16 @@ export function locationOf(locationCell: string, finding: string): string {
 /**
  * Extract review-finding rows: any `### Review` section table whose header carries a
  * Priority column. Rows need `^P[1-4]` priority and a finding other than `none`/`—`.
+ * A disposition column (Disposition/Action/Status/Resolution/Fixed) is honored: `FIXED`/
+ * `RESOLVED`/`DONE` rows are dropped; `DEFER` rows carry the cell as an in-table deferral reason.
  */
-export function parseReviewFindings(taskContent: string): Array<{ priority: string; location: string; text: string }> {
+export function parseReviewFindings(
+    taskContent: string,
+): 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 out: Array<{ priority: string; location: string; text: string }> = [];
+    const out: Array<{ priority: string; location: string; text: string; deferral?: string }> = [];
     const lines = body.split('\n');
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
@@ -127,6 +134,7 @@ export function parseReviewFindings(taskContent: string): Array<{ priority: stri
         }
         const findingCol = header.findIndex((h) => h.trim() === 'Finding');
         const locationCol = header.findIndex((h) => h.trim() === 'Location');
+        const dispositionCol = header.findIndex((h) => DISPOSITION_HEADER.test(h.trim()));
         i++; // skip header
         const sep = lines[i];
         if (sep !== undefined && /^\s*\|[\s:|-]+\|\s*$/.test(sep)) i++; // skip separator
@@ -136,8 +144,19 @@ export function parseReviewFindings(taskContent: string): Array<{ priority: stri
             const cells = splitRow(row);
             const priority = (cells[priorityCol] ?? '').trim();
             const finding = (cells[findingCol] ?? '').trim();
-            if (PRIORITY_PATTERN.test(priority) && !NONE_FINDING.test(finding) && finding.length > 0) {
-                out.push({ priority, location: locationOf(cells[locationCol] ?? '', finding), text: finding });
+            const disposition = dispositionCol === -1 ? '' : (cells[dispositionCol] ?? '').trim();
+            if (
+                PRIORITY_PATTERN.test(priority) &&
+                !NONE_FINDING.test(finding) &&
+                finding.length > 0 &&
+                !RESOLVED_DISPOSITION.test(disposition)
+            ) {
+                const location = locationOf(cells[locationCol] ?? '', finding);
+                out.push(
+                    DEFERRED_DISPOSITION.test(disposition)
+                        ? { priority, location, text: finding, deferral: disposition }
+                        : { priority, location, text: finding },
+                );
             }
             i++;
         }
@@ -295,7 +314,11 @@ export function scanResiduals(
     const runDir = join(root, '.spur', 'run');
     const basePath = join(runDir, `${wbs}-base.sha`);
     const base = existsSync(basePath) ? readFileSync(basePath, 'utf8').trim() : null;
-    const review = parseReviewFindings(taskContent).map((r) => ({
+    const reviewRows = parseReviewFindings(taskContent);
+    const tableDeferrals = reviewRows.flatMap((r) =>
+        r.deferral === undefined ? [] : [{ id: makeItemId('review-finding', r.location, r.text), reason: r.deferral }],
+    );
+    const review = reviewRows.map((r) => ({
         category: 'review-finding' as const,
         priority: r.priority,
         location: r.location,
@@ -319,7 +342,10 @@ export function scanResiduals(
         location: p,
         text: p,
     }));
-    const items = classify([...review, ...markers, ...boxes, ...residue], readDeferrals(runDir, wbs));
+    const items = classify(
+        [...review, ...markers, ...boxes, ...residue],
+        [...tableDeferrals, ...readDeferrals(runDir, wbs)],
+    );
     const counts = { blocking: 0, deferrable: 0, advisory: 0, housekeeping: 0 };
     for (const item of items) counts[item.class]++;
     return {