@gobing-ai/spur 0.3.95 → 0.3.96

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

@@ -2,179 +2,49 @@
 /**
  * residual-scan — deterministic task-leftover scanner behind feature F96 (ADR-071).
  *
- * Contract owner: docs/design/task-residual-sweep.md. Model-free detection; writes only
- * under `.spur/run/` (observe-only). Four modes:
- *   scan   <wbs>  write `.spur/run/<wbs>-residuals.json`
- *   fold   <wbs>  fold blocking residuals into `<wbs>-verdict.json` (residual-sweep check,
- *                  PASS→PARTIAL downgrade) and `<wbs>-test-gate.findings`
- *   settle <wbs>  file one follow-up task for deferrables; delete `/tmp/<wbs>-*` residue
- *   report <wbs>  write `.spur/run/<wbs>-residual-report.md` when the verdict's
- *                  residual-sweep check failed; print the recovery line
- *
- * Environment: `spurBin` (CLI resolution, mirrors wrapup-steps `spurCommand`).
- * Pure helpers (parsers, classify, foldVerdict, renderReport) are exported for unit
- * testing; node/bun builtin imports only (plugin standalone contract).
+ * Contract owner: docs/design/task-residual-sweep.md. IO glue only (task 1003 R5): argv, git/spur spawning, file
+ * IO, and the four modes; parsing/classification/folding/reporting live in the generated standalone bundle
+ * `plugins/sp/lib/residual-scan.generated.mjs` (source: packages/app/src/services/residual-scan.ts), re-exported via
+ * `export *`; the local `scanResiduals` wrapper (old 5-arg IO signature) shadows the core of the same name.
+ * Modes: scan <wbs> (write `.spur/run/<wbs>-residuals.json`); fold <wbs> (fold blocking residuals into
+ * `<wbs>-verdict.json` with PASS→PARTIAL downgrade + `<wbs>-test-gate.findings`); settle <wbs> (file one follow-up
+ * task for deferrables, delete `/tmp/<wbs>-*` residue); report <wbs> (write `<wbs>-residual-report.md` when the residual-sweep check failed).
  */
-
 import { spawnSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { getEnvVars } from '../lib/env';
+import * as core from '../lib/residual-scan.generated.mjs';
+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>]';
-
-export type ResidualCategory = 'review-finding' | 'diff-marker' | 'unchecked-box' | 'staging-residue';
-export type ResidualClass = 'blocking' | 'deferrable' | 'advisory' | 'housekeeping';
-
-export interface ResidualItem {
-    id: string;
-    category: ResidualCategory;
-    class: ResidualClass;
-    priority?: string;
-    location: string;
-    text: string;
-}
-
-export interface ResidualArtifact {
-    wbs: string;
-    base: string | null;
-    scanned: Record<ResidualCategory, boolean>;
-    items: ResidualItem[];
-    counts: { blocking: number; deferrable: number; advisory: number; housekeeping: number };
-}
-
-export interface ScanEnv {
-    spurBin?: string;
-    [key: string]: string | undefined;
-}
-
-export interface ScanIo {
-    out: (line: string) => void;
-    err: (line: string) => void;
-}
-
-export interface ScanOptions {
-    cwd?: string;
-    /** Injectable output sinks; defaults to process streams (tests inject no-ops to keep reporter output clean). */
-    io?: ScanIo;
-}
-
-const MARKER_PATTERN = /TODO|FIXME|XXX|HACK/;
-const PRIORITY_PATTERN = /^P[1-4]/;
-// 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;
-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;
-const EXCLUDED_PATHS = ['docs/tasks', 'docs/features/', '.spur/'];
-export const ALLOW_PRAGMA = 'residual-scan:allow';
-
-/** `spurBin` splits on whitespace into command + prefix args (same as wrapup-steps). */
-export function spurCommand(spurBin: string | undefined): { cmd: string; prefix: string[] } {
-    const parts = (spurBin ?? 'spur')
-        .trim()
-        .split(/\s+/)
-        .filter((p) => p.length > 0);
-    return { cmd: parts[0] ?? 'spur', prefix: parts.slice(1) };
-}
-
-function run(cmd: string, args: string[], cwd: string): { status: number; stdout: string } {
+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 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 }> };
+function run(cmd: string, args: string[], cwd: string): RunResult {
     const result = spawnSync(cmd, args, { cwd, encoding: 'utf8' });
     if (result.error !== undefined) return { status: result.status ?? 1, stdout: '' };
     return { status: result.status ?? 1, stdout: result.stdout ?? '' };
 }
-
-export function makeItemId(category: ResidualCategory, location: string, text: string): string {
-    const normalized = text.trim().replace(/\s+/g, ' ');
-    const hex = createHash('sha256').update(`${location}${normalized}`).digest('hex');
-    return `${category}:${hex.slice(0, 8)}`;
-}
-
-/** `path:12-18` → `path:12` (anchor normalization from the design doc). */
-export function normalizeAnchor(location: string): string {
-    return location.replace(RANGE_ANCHOR, '$1:$2');
-}
-
-/** Normalize a finding cell to an anchor: Location column, else first backticked `path:line`. */
-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(/`([^`]+)`/)?.[1];
-    return backtick === undefined ? '' : normalizeAnchor(backtick);
+function spur(env: ScanEnv, spurBinFlag: string | undefined, args: string[], cwd: string): RunResult {
+    const { cmd, prefix } = spurCommand(spurBinFlag ?? env.spurBin);
+    return run(cmd, [...prefix, ...args], cwd);
 }
-
-/**
- * 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; 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; deferral?: string }> = [];
-    const lines = body.split('\n');
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        if (line === undefined || !line.trimStart().startsWith('|')) continue;
-        const header = splitRow(line);
-        const priorityCol = header.findIndex((h) => h.trim() === 'Priority');
-        if (priorityCol === -1) {
-            // Not a Priority table; skip its separator + body rows.
-            while (i + 1 < lines.length && lines[i + 1]?.trimStart().startsWith('|')) i++;
-            continue;
-        }
-        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
-        while (i < lines.length) {
-            const row = lines[i];
-            if (row === undefined || !row.trimStart().startsWith('|')) break;
-            const cells = splitRow(row);
-            const priority = (cells[priorityCol] ?? '').trim();
-            const finding = (cells[findingCol] ?? '').trim();
-            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++;
-        }
+function isRegularFile(path: string): boolean {
+    try {
+        return statSync(path).isFile();
+    } catch {
+        return false;
     }
-    return out;
 }
-
-function splitRow(line: string): string[] {
-    return line
-        .trim()
-        .replace(/^\|/, '')
-        .replace(/\|$/, '')
-        .split('|')
-        .map((c) => c.trim());
-}
-
-/** Added lines (`<file>:<line>:<text>`) from `git diff --unified=0 <base>` plus untracked files. */
 export function collectAddedLines(root: string, base: string): Array<{ file: string; line: number; text: string }> {
     const out: Array<{ file: string; line: number; text: string }> = [];
     const diff = run('git', ['diff', '--unified=0', base], root);
@@ -182,52 +52,18 @@ export function collectAddedLines(root: string, base: string): Array<{ file: str
     let newLine = 0;
     for (const line of diff.stdout.split('\n')) {
         if (line.startsWith('+++ b/')) file = line.slice(6);
-        else if (line.startsWith('@@')) {
-            const m = line.match(/\+[0-9]+/);
-            newLine = m === null ? newLine : Number.parseInt(m[0].slice(1), 10);
-        } else if (line.startsWith('+') && !line.startsWith('+++')) {
-            out.push({ file, line: newLine, text: line.slice(1) });
-            newLine++;
-        }
+        else if (line.startsWith('@@')) newLine = Number.parseInt((line.match(/\+[0-9]+/) ?? ['+0'])[0].slice(1), 10);
+        else if (line.startsWith('+') && !line.startsWith('+++'))
+            out.push({ file, line: newLine++, text: line.slice(1) });
     }
     const untracked = run('git', ['ls-files', '--others', '--exclude-standard'], root);
     for (const f of untracked.stdout.split('\n')) {
-        if (f.length === 0) continue;
-        try {
-            if (!statSync(join(root, f)).isFile()) continue;
-        } catch {
-            continue;
-        }
-        const content = readFileSync(join(root, f), 'utf8').split('\n');
-        content.forEach((text, idx) => {
+        if (f.length === 0 || !isRegularFile(join(root, f))) continue;
+        for (const [idx, text] of readFileSync(join(root, f), 'utf8').split('\n').entries())
             out.push({ file: f, line: idx + 1, text });
-        });
     }
     return out;
 }
-
-/** TODO/FIXME/XXX/HACK markers on added lines, honoring path exclusions + allow pragma. */
-export function parseDiffMarkers(
-    addedLines: Array<{ file: string; line: number; text: string }>,
-): Array<{ location: string; text: string }> {
-    return addedLines
-        .filter((l) => !EXCLUDED_PATHS.some((p) => l.file.startsWith(p)))
-        .filter((l) => !l.text.includes(ALLOW_PRAGMA))
-        .filter((l) => MARKER_PATTERN.test(l.text))
-        .map((l) => ({ location: `${l.file}:${l.line}`, text: l.text.trim() }));
-}
-
-/** `- [ ]` lines in the task file. */
-export function findUncheckedBoxes(taskContent: string): Array<{ location: string; text: string }> {
-    const path = 'task-file';
-    return taskContent
-        .split('\n')
-        .map((text, idx) => ({ text: text.trim(), line: idx + 1 }))
-        .filter((l) => l.text.startsWith('- [ ]'))
-        .map((l) => ({ location: `${path}:${l.line}`, text: l.text }));
-}
-
-/** Regular files matching `<tmpDir>/<wbs>-*`. */
 export function listStagingResidue(tmpDir: string, wbs: string): string[] {
     let names: string[];
     try {
@@ -235,206 +71,34 @@ export function listStagingResidue(tmpDir: string, wbs: string): string[] {
     } catch {
         return [];
     }
-    return names
-        .filter((n) => n.startsWith(`${wbs}-`))
-        .filter((n) => {
-            try {
-                return statSync(join(tmpDir, n)).isFile();
-            } catch {
-                return false;
-            }
-        })
-        .map((n) => join(tmpDir, n));
-}
-
-interface Deferral {
-    id: string;
-    reason: string;
+    return names.filter((n) => n.startsWith(`${wbs}-`) && isRegularFile(join(tmpDir, n))).map((n) => join(tmpDir, n));
 }
-
-function readDeferrals(runDir: string, wbs: string): Deferral[] {
+function readDeferrals(runDir: string, wbs: string): core.Deferral[] {
     const path = join(runDir, `${wbs}-residual-deferrals.json`);
     if (!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(readFileSync(path, 'utf8'));
-        if (!Array.isArray(parsed)) return [];
-        return parsed.filter(
-            (e): e is Deferral =>
-                typeof e === 'object' &&
-                e !== null &&
-                typeof (e as Deferral).id === 'string' &&
-                typeof (e as Deferral).reason === 'string' &&
-                (e as Deferral).reason.trim().length > 0,
-        );
+        return (Array.isArray(parsed) ? parsed : []).filter(isDeferral);
     } catch {
         return [];
     }
 }
-
-/**
- * Classification: P1–P3 findings, diff markers and unchecked boxes are blocking; P4 is
- * advisory; staging residue is housekeeping. A deferral entry with a non-empty reason
- * reclassifies a P3 finding or diff marker as deferrable — never P1/P2 or unchecked boxes.
- */
-export function classify(
-    items: Array<Omit<ResidualItem, 'id' | 'class'> & { category: ResidualCategory }>,
-    deferrals: Deferral[],
-): ResidualItem[] {
-    const deferred = new Map(deferrals.map((d) => [d.id, d.reason]));
-    return items.map((item) => {
-        const id = makeItemId(item.category, item.location, item.text);
-        let klass: ResidualClass;
-        if (item.category === 'review-finding') klass = item.priority?.startsWith('P4') ? 'advisory' : 'blocking';
-        else if (item.category === 'staging-residue') klass = 'housekeeping';
-        else klass = 'blocking';
-        if (klass === 'blocking' && item.category !== 'unchecked-box') {
-            const p3Like =
-                item.category === 'diff-marker' ||
-                (item.category === 'review-finding' && (item.priority ?? '').startsWith('P3'));
-            const reason = deferred.get(id);
-            if (p3Like && reason !== undefined && reason.trim().length > 0) klass = 'deferrable';
-        }
-        return {
-            id,
-            category: item.category,
-            class: klass,
-            priority: item.priority,
-            location: item.location,
-            text: item.text,
-        };
-    });
-}
-
-export function scanResiduals(
-    root: string,
-    wbs: string,
-    tmpDir: string,
-    taskContent: string,
-    _env: ScanEnv,
-): ResidualArtifact {
+export function scanResiduals(root: string, wbs: string, tmpDir: string, taskContent: string, _env: ScanEnv) {
     const runDir = join(root, '.spur', 'run');
     const basePath = join(runDir, `${wbs}-base.sha`);
     const base = existsSync(basePath) ? readFileSync(basePath, 'utf8').trim() : null;
-    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,
-        text: r.text,
-    }));
-    const markers =
-        base === null
-            ? []
-            : parseDiffMarkers(collectAddedLines(root, base)).map((m) => ({
-                  category: 'diff-marker' as const,
-                  location: m.location,
-                  text: m.text,
-              }));
-    const boxes = findUncheckedBoxes(taskContent).map((b) => ({
-        category: 'unchecked-box' as const,
-        location: b.location,
-        text: b.text,
-    }));
-    const residue = listStagingResidue(tmpDir, wbs).map((p) => ({
-        category: 'staging-residue' as const,
-        location: p,
-        text: p,
-    }));
-    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 {
-        wbs,
-        base,
-        scanned: {
-            'review-finding': true,
-            'diff-marker': base !== null,
-            'unchecked-box': true,
-            'staging-residue': true,
-        },
-        items,
-        counts,
-    };
-}
-
-/** Blocking locations that match the `file.ext:line` findings-anchor shape. */
-export function blockingAnchors(items: ResidualItem[]): string[] {
-    const anchors = new Set<string>();
-    for (const item of items) {
-        if (item.class !== 'blocking') continue;
-        for (const m of normalizeAnchor(item.location).matchAll(ANCHOR_PATTERN)) anchors.add(m[0]);
-    }
-    return [...anchors];
-}
-
-export interface FoldResult {
-    verdict: 'PASS' | 'PARTIAL' | 'FAIL';
-    checks: Array<{ name: string; status: string; evidence: string }>;
-    findings: string;
-}
-
-/**
- * Fold the scan into a verdict: replace the `residual-sweep` check (fail when blocking > 0),
- * downgrade PASS→PARTIAL when blocking > 0 (PARTIAL/FAIL unchanged), and merge blocking
- * anchors into the gate findings (unique, sorted, cap 20). Idempotent.
- */
-export function foldVerdict(
-    verdict: { verdict: string; checks: Array<{ name: string; status: string; evidence: string }> },
-    scan: ResidualArtifact,
-    existingFindings: string,
-    maxFindings = 20,
-): FoldResult {
-    const blocking = scan.items.filter((i) => i.class === 'blocking');
-    const deferrable = scan.items.filter((i) => i.class === 'deferrable');
-    const evidence =
-        `blocking=${blocking.length} deferrable=${deferrable.length} advisory=${scan.counts.advisory} housekeeping=${scan.counts.housekeeping}` +
-        (blocking.length > 0 ? `; blocking ids: ${blocking.map((i) => i.id).join(', ')}` : '') +
-        (deferrable.length > 0 ? `; deferrable ids: ${deferrable.map((i) => i.id).join(', ')}` : '');
-    const checks = verdict.checks.filter((c) => c.name !== 'residual-sweep');
-    checks.push({ name: 'residual-sweep', status: blocking.length > 0 ? 'fail' : 'pass', evidence });
-    const merged = new Set([
-        ...existingFindings.split(/\s+/).filter((a) => a.length > 0),
-        ...blockingAnchors(scan.items),
-    ]);
-    const findings = [...merged]
-        .sort()
-        .slice(0, maxFindings)
-        .map((a) => `${a} `)
-        .join('');
-    let verdictStatus: FoldResult['verdict'] = verdict.verdict === 'PASS' ? 'PASS' : 'FAIL';
-    if (verdict.verdict === 'PARTIAL') verdictStatus = 'PARTIAL';
-    else if (verdict.verdict === 'FAIL') verdictStatus = 'FAIL';
-    else if (blocking.length > 0) verdictStatus = 'PARTIAL';
-    return { verdict: verdictStatus, checks, findings };
-}
-
-/** Render the recovery report for blocking items. */
-export function renderReport(wbs: string, items: ResidualItem[], attemptCount: number): string {
-    const lines = [
-        `# Residual report — ${wbs}`,
-        '',
-        `Attempt: ${attemptCount}`,
-        '',
-        '| Category | Class | Location | Text |',
-        '| --- | --- | --- | --- |',
-    ];
-    for (const item of items) {
-        lines.push(`| ${item.category} | ${item.class} | ${item.location} | ${item.text.replace(/\|/g, '\\|')} |`);
-    }
-    return `${lines.join('\n')}\n`;
+    const stagingResidue = listStagingResidue(tmpDir, wbs);
+    const deferrals = readDeferrals(runDir, wbs);
+    const addedLines = base === null ? [] : collectAddedLines(root, base);
+    return core.scanResiduals({ wbs, base, taskContent, addedLines, stagingResidue, deferrals });
 }
-
-// ── impure modes ─────────────────────────────────────────────────────────────
-
-function parseArgs(
-    argv: string[],
-): { mode: string; wbs: string; spurBin?: string; root: string; tmpDir: string } | null {
+function parseArgs(argv: string[]): ParsedArgs | null {
     let mode = '';
     let wbs = '';
     let spurBin: string | undefined;
@@ -450,192 +114,131 @@ function parseArgs(
         else if (mode === '') mode = a;
         else if (wbs === '') wbs = a;
     }
-    if (mode === '' || wbs === '') return null;
-    return { mode, wbs, spurBin, root, tmpDir };
-}
-
-function spur(
-    env: ScanEnv,
-    spurBinFlag: string | undefined,
-    args: string[],
-    cwd: string,
-): { status: number; stdout: string } {
-    return run(
-        spurCommand(spurBinFlag ?? env.spurBin).cmd,
-        [...spurCommand(spurBinFlag ?? env.spurBin).prefix, ...args],
-        cwd,
-    );
+    return mode === '' || wbs === '' ? null : { mode, wbs, spurBin, root, tmpDir };
 }
-
-function loadTask(
-    env: ScanEnv,
-    spurBinFlag: string | undefined,
-    wbs: string,
-    root: string,
-): { content: string; featureId: string } {
+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`);
-    const parsed = JSON.parse(res.stdout) as Record<string, unknown>;
-    const content = typeof parsed.content === 'string' ? parsed.content : '';
-    const fm = parsed.frontmatter;
+    type TaskJson = { content?: unknown; feature_id?: unknown; frontmatter?: { feature_id?: unknown } | null };
+    const parsed = JSON.parse(res.stdout) as TaskJson;
     const featureId =
-        typeof parsed.feature_id === 'string'
-            ? parsed.feature_id
-            : fm !== null && typeof fm === 'object' && typeof (fm as Record<string, unknown>).feature_id === 'string'
-              ? ((fm as Record<string, unknown>).feature_id as string)
-              : '';
-    return { content, featureId };
+        [parsed.feature_id, parsed.frontmatter?.feature_id].find((v): v is string => typeof v === 'string') ?? '';
+    return { content: typeof parsed.content === 'string' ? parsed.content : '', featureId };
 }
-
-function loadVerdict(
-    runDir: string,
-    wbs: string,
-): { verdict: string; checks: Array<{ name: string; status: string; evidence: string }> } {
+function loadVerdict(runDir: string, wbs: string): VerdictFile {
     return JSON.parse(readFileSync(join(runDir, `${wbs}-verdict.json`), 'utf8'));
 }
-
-function scanMode(opts: NonNullable<ReturnType<typeof parseArgs>>, env: ScanEnv, io: ScanIo): number {
-    const task = loadTask(env, opts.spurBin, opts.wbs, opts.root);
+function scanMode(opts: ParsedArgs, env: ScanEnv, io: ScanIo): number {
     const runDir = join(opts.root, '.spur', 'run');
     mkdirSync(runDir, { recursive: true });
-    const artifact = scanResiduals(opts.root, opts.wbs, opts.tmpDir, task.content, env);
+    const { content } = loadTask(env, opts.spurBin, opts.wbs, opts.root);
+    const artifact = scanResiduals(opts.root, opts.wbs, opts.tmpDir, content, env);
     writeFileSync(join(runDir, `${opts.wbs}-residuals.json`), `${JSON.stringify(artifact, null, 2)}\n`);
     io.out(
         `residual-scan: ${opts.wbs} blocking=${artifact.counts.blocking} deferrable=${artifact.counts.deferrable} advisory=${artifact.counts.advisory} housekeeping=${artifact.counts.housekeeping}\n`,
     );
     return 0;
 }
-
-function foldMode(opts: NonNullable<ReturnType<typeof parseArgs>>, _env: ScanEnv, io: ScanIo): number {
+function foldMode(opts: ParsedArgs, _env: ScanEnv, io: ScanIo): number {
     const runDir = join(opts.root, '.spur', 'run');
-    const scan = JSON.parse(readFileSync(join(runDir, `${opts.wbs}-residuals.json`), 'utf8')) as ResidualArtifact;
+    const scan = JSON.parse(readFileSync(join(runDir, `${opts.wbs}-residuals.json`), 'utf8')) as core.ResidualArtifact;
     const verdictPath = join(runDir, `${opts.wbs}-verdict.json`);
     const verdict = loadVerdict(runDir, opts.wbs);
     const findingsPath = join(runDir, `${opts.wbs}-test-gate.findings`);
-    const existing = existsSync(findingsPath) ? readFileSync(findingsPath, 'utf8') : '';
-    const folded = foldVerdict(verdict, scan, existing);
+    const fold = core.foldVerdict(verdict, scan, existsSync(findingsPath) ? readFileSync(findingsPath, 'utf8') : '');
     writeFileSync(
         verdictPath,
-        `${JSON.stringify({ ...verdict, verdict: folded.verdict, checks: folded.checks }, null, 2)}\n`,
+        `${JSON.stringify({ ...verdict, verdict: fold.verdict, checks: fold.checks }, null, 2)}\n`,
     );
-    writeFileSync(findingsPath, folded.findings);
+    writeFileSync(findingsPath, fold.findings);
     io.out(
-        `residual-fold: ${opts.wbs} verdict=${folded.verdict} residual-sweep=${folded.checks.find((c) => c.name === 'residual-sweep')?.status}\n`,
+        `residual-fold: ${opts.wbs} verdict=${fold.verdict} residual-sweep=${fold.checks.find((c) => c.name === 'residual-sweep')?.status}\n`,
     );
     return 0;
 }
-
-function settleMode(opts: NonNullable<ReturnType<typeof parseArgs>>, env: ScanEnv, io: ScanIo): number {
-    const task = loadTask(env, opts.spurBin, opts.wbs, opts.root);
+function settleMode(opts: ParsedArgs, env: ScanEnv, io: ScanIo): number {
+    const wbs = opts.wbs;
+    const task = loadTask(env, opts.spurBin, wbs, opts.root);
     const runDir = join(opts.root, '.spur', 'run');
-    const scan = scanResiduals(opts.root, opts.wbs, opts.tmpDir, task.content, env);
-    const residualsPath = join(runDir, `${opts.wbs}-residuals.json`);
+    const scan = scanResiduals(opts.root, wbs, opts.tmpDir, task.content, env);
+    const residualsPath = join(runDir, `${wbs}-residuals.json`);
+    let prior: Partial<core.ResidualArtifact & { followUp?: string }> = {};
+    if (existsSync(residualsPath)) prior = JSON.parse(readFileSync(residualsPath, 'utf8'));
     const deferred = scan.items.filter((i) => i.class === 'deferrable');
-    const prior = existsSync(residualsPath)
-        ? (JSON.parse(readFileSync(residualsPath, 'utf8')) as Partial<ResidualArtifact & { followUp?: string }>)
-        : {};
     if (deferred.length > 0 && prior.followUp === undefined) {
         if (task.featureId === '') {
             io.err(
-                `residual-settle: ${opts.wbs} deferrals pending but feature_id unknown; re-run: residual-scan settle ${opts.wbs}\n`,
+                `residual-settle: ${wbs} deferrals pending but feature_id unknown; re-run: residual-scan settle ${wbs}\n`,
             );
             return 0;
         }
-        const created = spur(
-            env,
-            opts.spurBin,
-            ['task', 'create', `Residuals from ${opts.wbs}`, '--feature', task.featureId, '--skip-ready', '--json'],
-            opts.root,
-        );
-        if (created.status !== 0) {
-            io.err(`residual-settle: task create failed; re-run: residual-scan settle ${opts.wbs}\n`);
-            return 0;
-        }
+        const args = ['task', 'create', `Residuals from ${wbs}`, '--feature', task.featureId, '--skip-ready', '--json'];
+        const created = spur(env, opts.spurBin, args, opts.root);
         let wbsNew = '';
         try {
-            const parsed = JSON.parse(created.stdout) as Record<string, unknown>;
-            const pick = (o: Record<string, unknown>): string => (typeof o.wbs === 'string' ? o.wbs : '');
-            wbsNew =
-                pick(parsed) ||
-                (parsed.data !== null && typeof parsed.data === 'object'
-                    ? pick(parsed.data as Record<string, unknown>)
-                    : '');
+            const parsed = JSON.parse(created.stdout) as { wbs?: unknown; data?: { wbs?: unknown } | null };
+            const data = typeof parsed.data === 'object' && parsed.data !== null ? parsed.data : {};
+            wbsNew = [parsed.wbs, data.wbs].find((v): v is string => typeof v === 'string') ?? '';
         } catch {
             wbsNew = '';
         }
-        if (wbsNew === '') {
-            io.err(`residual-settle: could not read created task wbs; re-run: residual-scan settle ${opts.wbs}\n`);
+        if (created.status !== 0 || wbsNew === '') {
+            io.err(`residual-settle: task create failed or unreadable wbs; re-run: residual-scan settle ${wbs}\n`);
             return 0;
         }
-        const bg = [
-            `Source task: ${opts.wbs} (feature ${task.featureId}) — deferred residuals filed by residual-scan settle.`,
-            '',
-            ...deferred.map((i) => `- ${i.id} — ${i.location}: ${i.text}`),
-        ].join('\n');
-        const bgFile = join(runDir, `${opts.wbs}-residual-background.md`);
-        writeFileSync(bgFile, `${bg}\n`);
-        const upd = spur(
-            env,
-            opts.spurBin,
-            ['task', 'update', wbsNew, '--section', 'Background', '--from-file', bgFile],
-            opts.root,
-        );
-        if (upd.status !== 0) {
-            io.err(`residual-settle: background write failed; re-run: residual-scan settle ${opts.wbs}\n`);
+        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 bgFile = join(runDir, `${wbs}-residual-background.md`);
+        writeFileSync(bgFile, `${[head, '', ...rows].join('\n')}\n`);
+        const updArgs = ['task', 'update', wbsNew, '--section', 'Background', '--from-file', bgFile];
+        if (spur(env, opts.spurBin, updArgs, opts.root).status !== 0) {
+            io.err(`residual-settle: background write failed; re-run: residual-scan settle ${wbs}\n`);
             return 0;
         }
         prior.followUp = wbsNew;
         io.out(`residual-settle: filed follow-up ${wbsNew} for ${deferred.length} deferred item(s)\n`);
     }
-    // Cleanup: only regular files `<tmpDir>/<wbs>-*`. Never directories, never other prefixes.
-    for (const path of listStagingResidue(opts.tmpDir, opts.wbs)) {
+    for (const path of listStagingResidue(opts.tmpDir, wbs)) {
         try {
             rmSync(path, { force: true });
         } catch {
-            io.err(`residual-settle: could not remove ${path}; re-run: residual-scan settle ${opts.wbs}\n`);
+            io.err(`residual-settle: could not remove ${path}; re-run: residual-scan settle ${wbs}\n`);
             return 0;
         }
     }
     writeFileSync(residualsPath, `${JSON.stringify({ ...scan, ...prior }, null, 2)}\n`);
     return 0;
 }
-
-function reportMode(opts: NonNullable<ReturnType<typeof parseArgs>>, env: ScanEnv, io: ScanIo): number {
+function reportMode(opts: ParsedArgs, env: ScanEnv, io: ScanIo): number {
     const runDir = join(opts.root, '.spur', 'run');
-    const verdict = loadVerdict(runDir, opts.wbs);
-    const sweep = verdict.checks.find((c) => c.name === 'residual-sweep');
+    const sweep = loadVerdict(runDir, opts.wbs).checks.find((c) => c.name === 'residual-sweep');
     if (sweep === undefined || sweep.status !== 'fail') return 0;
-    const task = loadTask(env, opts.spurBin, opts.wbs, opts.root);
-    const scan = scanResiduals(opts.root, opts.wbs, opts.tmpDir, task.content, env);
+    const { content } = loadTask(env, opts.spurBin, opts.wbs, opts.root);
+    const scan = scanResiduals(opts.root, opts.wbs, opts.tmpDir, content, env);
     const blocking = scan.items.filter((i) => i.class === 'blocking');
     const attemptFile = join(runDir, `${opts.wbs}-test-fix-attempt`);
     const attempts = existsSync(attemptFile) ? Number.parseInt(readFileSync(attemptFile, 'utf8').trim() || '0', 10) : 0;
-    const reportPath = join(runDir, `${opts.wbs}-residual-report.md`);
-    writeFileSync(reportPath, renderReport(opts.wbs, blocking, Number.isNaN(attempts) ? 0 : attempts));
+    writeFileSync(
+        join(runDir, `${opts.wbs}-residual-report.md`),
+        core.renderReport(opts.wbs, blocking, Number.isNaN(attempts) ? 0 : attempts),
+    );
     io.out(`Recovery: fix the items in .spur/run/${opts.wbs}-residual-report.md, then /sp:dev-run ${opts.wbs}\n`);
     return 0;
 }
-
 export function main(argv: string[], env: ScanEnv = getEnvVars(), options: ScanOptions = {}): number {
     const io: ScanIo = options.io ?? {
         out: (line) => process.stdout.write(line),
         err: (line) => process.stderr.write(line),
     };
+    const cwd = options.cwd ?? process.cwd();
     const opts = parseArgs(argv);
-    if (opts === null) {
+    const modes: Record<string, ModeFn> = { scan: scanMode, fold: foldMode, settle: settleMode, report: reportMode };
+    const modeFn = opts === null ? undefined : modes[opts.mode];
+    if (opts === null || modeFn === undefined) {
         io.err(`${RESIDUAL_SCAN_USAGE}\n`);
         return 2;
     }
-    const cwd = options.cwd ?? process.cwd();
-    const resolved = { ...opts, root: opts.root.startsWith('/') ? opts.root : join(cwd, opts.root) };
-    if (resolved.mode === 'scan') return scanMode(resolved, env, io);
-    if (resolved.mode === 'fold') return foldMode(resolved, env, io);
-    if (resolved.mode === 'settle') return settleMode(resolved, env, io);
-    if (resolved.mode === 'report') return reportMode(resolved, env, io);
-    io.err(`${RESIDUAL_SCAN_USAGE}\n`);
-    return 2;
-}
-
-if (import.meta.main) {
-    process.exit(main(process.argv.slice(2)));
+    const resolved: ParsedArgs = { ...opts, root: opts.root.startsWith('/') ? opts.root : join(cwd, opts.root) };
+    return modeFn(resolved, env, io);
 }
+if (import.meta.main) process.exit(main(process.argv.slice(2)));