@gobing-ai/spur 0.3.96 → 0.3.97

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

@@ -1,17 +1,7 @@
 #!/usr/bin/env bun
-/**
- * residual-scan — deterministic task-leftover scanner behind feature F96 (ADR-071).
- *
- * 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).
- */
+/** F96 residual IO glue. Pure logic: residual-scan.generated.mjs; contract: task-residual-sweep.md. */
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import * as fs from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { getEnvVars } from '../lib/env';
@@ -40,7 +30,7 @@ function spur(env: ScanEnv, spurBinFlag: string | undefined, args: string[], cwd
 }
 function isRegularFile(path: string): boolean {
     try {
-        return statSync(path).isFile();
+        return fs.statSync(path).isFile();
     } catch {
         return false;
     }
@@ -59,7 +49,7 @@ export function collectAddedLines(root: string, base: string): Array<{ file: str
     const untracked = run('git', ['ls-files', '--others', '--exclude-standard'], root);
     for (const f of untracked.stdout.split('\n')) {
         if (f.length === 0 || !isRegularFile(join(root, f))) continue;
-        for (const [idx, text] of readFileSync(join(root, f), 'utf8').split('\n').entries())
+        for (const [idx, text] of fs.readFileSync(join(root, f), 'utf8').split('\n').entries())
             out.push({ file: f, line: idx + 1, text });
     }
     return out;
@@ -67,7 +57,7 @@ export function collectAddedLines(root: string, base: string): Array<{ file: str
 export function listStagingResidue(tmpDir: string, wbs: string): string[] {
     let names: string[];
     try {
-        names = readdirSync(tmpDir);
+        names = fs.readdirSync(tmpDir);
     } catch {
         return [];
     }
@@ -75,7 +65,7 @@ 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 (!existsSync(path)) return [];
+    if (!fs.existsSync(path)) return [];
     const isDeferral = (e: unknown): e is core.Deferral =>
         typeof e === 'object' &&
         e !== null &&
@@ -83,7 +73,7 @@ function readDeferrals(runDir: string, wbs: string): core.Deferral[] {
         typeof (e as core.Deferral).reason === 'string' &&
         (e as core.Deferral).reason.trim().length > 0;
     try {
-        const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'));
+        const parsed: unknown = JSON.parse(fs.readFileSync(path, 'utf8'));
         return (Array.isArray(parsed) ? parsed : []).filter(isDeferral);
     } catch {
         return [];
@@ -92,7 +82,7 @@ function readDeferrals(runDir: string, wbs: string): core.Deferral[] {
 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 base = fs.existsSync(basePath) ? fs.readFileSync(basePath, 'utf8').trim() : null;
     const stagingResidue = listStagingResidue(tmpDir, wbs);
     const deferrals = readDeferrals(runDir, wbs);
     const addedLines = base === null ? [] : collectAddedLines(root, base);
@@ -126,14 +116,14 @@ function loadTask(env: ScanEnv, spurBinFlag: string | undefined, wbs: string, ro
     return { content: typeof parsed.content === 'string' ? parsed.content : '', featureId };
 }
 function loadVerdict(runDir: string, wbs: string): VerdictFile {
-    return JSON.parse(readFileSync(join(runDir, `${wbs}-verdict.json`), 'utf8'));
+    return JSON.parse(fs.readFileSync(core.recordedVerdictPath(runDir, wbs, fs), 'utf8'));
 }
 function scanMode(opts: ParsedArgs, env: ScanEnv, io: ScanIo): number {
     const runDir = join(opts.root, '.spur', 'run');
-    mkdirSync(runDir, { recursive: true });
+    fs.mkdirSync(runDir, { recursive: true });
     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`);
+    fs.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`,
     );
@@ -141,16 +131,29 @@ function scanMode(opts: ParsedArgs, 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 core.ResidualArtifact;
-    const verdictPath = join(runDir, `${opts.wbs}-verdict.json`);
+    const scan = JSON.parse(
+        fs.readFileSync(join(runDir, `${opts.wbs}-residuals.json`), 'utf8'),
+    ) as core.ResidualArtifact;
+    const target = core.recordedVerdictPath(runDir, opts.wbs, fs);
     const verdict = loadVerdict(runDir, opts.wbs);
     const findingsPath = join(runDir, `${opts.wbs}-test-gate.findings`);
-    const fold = core.foldVerdict(verdict, scan, existsSync(findingsPath) ? readFileSync(findingsPath, 'utf8') : '');
-    writeFileSync(
-        verdictPath,
-        `${JSON.stringify({ ...verdict, verdict: fold.verdict, checks: fold.checks }, null, 2)}\n`,
+    const fold = core.foldVerdict(
+        verdict,
+        scan,
+        fs.existsSync(findingsPath) ? fs.readFileSync(findingsPath, 'utf8') : '',
     );
-    writeFileSync(findingsPath, fold.findings);
+    const bytes = `${JSON.stringify({ ...verdict, verdict: fold.verdict, checks: fold.checks }, null, 2)}\n`;
+    const temporary = `${target}.${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(temporary, bytes, { flag: 'wx' });
+        fs.renameSync(temporary, target);
+    } finally {
+        fs.rmSync(temporary, { force: true });
+    }
+    // The pipeline still consumes the attempt copy after folding; the recorded copy is authoritative.
+    const scratch = join(runDir, `${opts.wbs}-verdict.json`);
+    if (target !== scratch) fs.writeFileSync(scratch, bytes);
+    fs.writeFileSync(findingsPath, fold.findings);
     io.out(
         `residual-fold: ${opts.wbs} verdict=${fold.verdict} residual-sweep=${fold.checks.find((c) => c.name === 'residual-sweep')?.status}\n`,
     );
@@ -163,7 +166,7 @@ function settleMode(opts: ParsedArgs, env: ScanEnv, io: ScanIo): number {
     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'));
+    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 === '') {
@@ -189,7 +192,7 @@ function settleMode(opts: ParsedArgs, env: ScanEnv, io: ScanIo): number {
         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`);
+        fs.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`);
@@ -200,13 +203,13 @@ function settleMode(opts: ParsedArgs, env: ScanEnv, io: ScanIo): number {
     }
     for (const path of listStagingResidue(opts.tmpDir, wbs)) {
         try {
-            rmSync(path, { force: true });
+            fs.rmSync(path, { force: true });
         } catch {
             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`);
+    fs.writeFileSync(residualsPath, `${JSON.stringify({ ...scan, ...prior }, null, 2)}\n`);
     return 0;
 }
 function reportMode(opts: ParsedArgs, env: ScanEnv, io: ScanIo): number {
@@ -217,8 +220,10 @@ function reportMode(opts: ParsedArgs, env: ScanEnv, io: ScanIo): number {
     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;
-    writeFileSync(
+    const attempts = fs.existsSync(attemptFile)
+        ? Number.parseInt(fs.readFileSync(attemptFile, 'utf8').trim() || '0', 10)
+        : 0;
+    fs.writeFileSync(
         join(runDir, `${opts.wbs}-residual-report.md`),
         core.renderReport(opts.wbs, blocking, Number.isNaN(attempts) ? 0 : attempts),
     );

package/plugins/sp/scripts/wrapup-steps.mjs

@@ -3,7 +3,7 @@
 
 // plugins/sp/scripts/wrapup-steps.ts
 import { spawnSync } from "child_process";
-import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
 
 // plugins/sp/lib/env.ts
@@ -114,10 +114,68 @@ function resolveTasks(env, options = {}) {
   if (unresolved) {
     return writeFail(`failed:unresolved or non-completed task (see ${relTasksFile})`);
   }
+  if ((env.feature ?? "") !== "") {
+    const pf = preflightFeature(env, cwd);
+    if (pf)
+      return writeFail(pf);
+  }
   writeFileSync(abs(relStatusFile), `PASS
 `);
   return { status: "PASS", statusFile: relStatusFile, tasksFile: relTasksFile, exitCode: 0 };
 }
+function isFindingList(value) {
+  return Array.isArray(value) && value.every((f) => f !== null && typeof f === "object" && typeof f.severity === "string" && typeof f.code === "string" && f.code.length > 0);
+}
+function sortedUniqueCodes(findings) {
+  const codes = findings.filter((f) => f.severity === "error").map((f) => String(f.code ?? "")).filter((c) => c.length > 0);
+  return [...new Set(codes)].sort();
+}
+function preflightFeature(env, cwd) {
+  const feature = env.feature ?? "";
+  const abs = (p) => cwd ? join(cwd, p) : p;
+  const syncOut = spur(env, ["feature", "sync", feature, "--dry-run", "--json"], { cwd });
+  let sync;
+  if (syncOut.status === 0) {
+    try {
+      const parsed = JSON.parse(syncOut.stdout);
+      if (parsed !== null && typeof parsed === "object")
+        sync = parsed;
+    } catch {}
+  }
+  if (sync === undefined)
+    return "failed:preflight:sync-unreadable";
+  const proposal = sync.proposal;
+  if (proposal === null || typeof proposal !== "object" || Array.isArray(proposal) || proposal.gateBlocked !== undefined && typeof proposal.gateBlocked !== "boolean" || proposal.gateFindings !== undefined && !isFindingList(proposal.gateFindings) || proposal.hops !== undefined && (!Array.isArray(proposal.hops) || !proposal.hops.every((hop) => typeof hop === "string")) || proposal.gateBlocked !== true && (typeof proposal.from !== "string" || typeof proposal.to !== "string")) {
+    return "failed:preflight:sync-unreadable";
+  }
+  if (proposal.gateBlocked === true) {
+    return `failed:preflight:gate-blocked ${sortedUniqueCodes(proposal.gateFindings ?? []).join(",")}`;
+  }
+  const reachesDone = proposal.to === "done" || (proposal.hops ?? []).includes("done");
+  if (!reachesDone)
+    return null;
+  const checkOut = spur(env, ["feature", "check", feature, "--strict", "--as", "done", "--json"], { cwd });
+  let check;
+  try {
+    check = JSON.parse(checkOut.stdout);
+  } catch {
+    return "failed:preflight:check-unreadable";
+  }
+  const payload = Array.isArray(check) && check.length === 1 ? check[0] : check;
+  const findings = payload !== null && typeof payload === "object" ? payload.findings : undefined;
+  if (!isFindingList(findings) || checkOut.status !== 0 && (checkOut.status !== 1 || !findings.some((f) => f.severity === "error"))) {
+    return "failed:preflight:check-unreadable";
+  }
+  const eligible = proposal.from === "verifying" ? findings : findings.filter((f) => !String(f.code ?? "").startsWith("L4.feature-receipt-"));
+  const runId = env.__runId ?? "";
+  if (runId.length > 0) {
+    mkdirSync(abs(join(".spur", "run")), { recursive: true });
+    writeFileSync(abs(join(".spur", "run", `${runId}-wrapup-preflight.json`)), `${JSON.stringify(check)}
+`);
+  }
+  const codes = sortedUniqueCodes(eligible);
+  return codes.length > 0 ? `failed:preflight:done-gate ${codes.join(",")}` : null;
+}
 var ROUTE_REASON_TABLE = {
   fast: "fast:evidence complete+consistent",
   "": "safety:missing evidence (mode empty)",
@@ -239,8 +297,10 @@ function runMetrics(env, options = {}) {
     const frontmatter = parsed.frontmatter !== null && typeof parsed.frontmatter === "object" ? parsed.frontmatter : {};
     const featureId = String(jqPick(frontmatter.feature_id, parsed.feature_id, ""));
     const status2 = String(jqPick(frontmatter.status, parsed.status, "unknown"));
-    const verdictPath = join(".spur", "run", `${wbs}-verdict.json`);
-    const artifactVerdict = verdictOfArtifact(abs(verdictPath));
+    const durable = join(".spur", "memory", "evidence", `${wbs}-verdict.json`);
+    const hasDurable = existsSync(abs(durable));
+    const verdictPath = hasDurable ? durable : join(".spur", "run", `${wbs}-verdict.json`);
+    const artifactVerdict = verdictOfArtifact(abs(verdictPath)) ?? (hasDurable ? "UNKNOWN" : null);
     const trackedVerdict = verdictFromTestingSection(typeof parsed.content === "string" ? parsed.content : "");
     const verdict = artifactVerdict ?? trackedVerdict ?? "UNKNOWN";
     if (verdict === "UNKNOWN") {
@@ -410,6 +470,7 @@ export {
   runMetrics,
   runFeatureTransition,
   resolveTasks,
+  preflightFeature,
   main,
   jqPick,
   classifySync,

package/plugins/sp/scripts/wrapup-steps.ts

@@ -9,6 +9,7 @@
  * the shell-program caps while writing the same `.spur/run` artifacts:
  *   - `<runId>-wrapup-tasks.json`       normalized, deduplicated WBS capture (resolve)
  *   - `<runId>-wrapup-resolve.status`   `PASS`/`FAIL` (resolve)
+ *   - `<runId>-wrapup-preflight.json`   full feature-check JSON (resolve pre-flight, when `feature` is set)
  *   - `<runId>-route-reason.txt`        route reason (route-reason subcommand)
  *   - `.spur/memory/wrapup-metrics.jsonl` one row per task (metrics)
  *   - `<runId>-wrapup-metrics.status`   `PASS`/`FAIL` (metrics)
@@ -30,7 +31,7 @@
  */
 
 import { spawnSync } from 'node:child_process';
-import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { getEnvVars } from '../lib/env';
 import { spurCommand } from '../lib/spur-bin';
@@ -174,10 +175,126 @@ export function resolveTasks(env: WrapupStepsEnv, options: WrapupStepsOptions =
     if (unresolved) {
         return writeFail(`failed:unresolved or non-completed task (see ${relTasksFile})`);
     }
+    if ((env.feature ?? '') !== '') {
+        const pf = preflightFeature(env, cwd);
+        if (pf) return writeFail(pf);
+    }
     writeFileSync(abs(relStatusFile), 'PASS\n');
     return { status: 'PASS', statusFile: relStatusFile, tasksFile: relTasksFile, exitCode: 0 };
 }
 
+interface PreflightFinding {
+    severity: string;
+    code: string;
+}
+
+function isFindingList(value: unknown): value is PreflightFinding[] {
+    return (
+        Array.isArray(value) &&
+        value.every(
+            (f) =>
+                f !== null &&
+                typeof f === 'object' &&
+                typeof f.severity === 'string' &&
+                typeof f.code === 'string' &&
+                f.code.length > 0,
+        )
+    );
+}
+
+interface PreflightSyncPayload {
+    proposal?: {
+        gateBlocked?: boolean;
+        from?: string;
+        to?: string;
+        hops?: string[];
+        gateFindings?: PreflightFinding[];
+    };
+}
+
+function sortedUniqueCodes(findings: PreflightFinding[]): string[] {
+    const codes = findings
+        .filter((f) => f.severity === 'error')
+        .map((f) => String(f.code ?? ''))
+        .filter((c) => c.length > 0);
+    return [...new Set(codes)].sort();
+}
+
+/**
+ * 1033 R2 feature pre-flight for wrapup resolve — runs after the task list resolves and
+ * before any corpus-mutating wrapup state. Returns a `failed:preflight:*` reason on the
+ * first blocking condition, or null when wrapup may proceed. Never writes PASS, never
+ * relaxes the later feature-transition / feature-verify gates, and uses the same `spurBin`
+ * env as `runFeatureTransition`.
+ */
+export function preflightFeature(env: WrapupStepsEnv, cwd?: string): string | null {
+    const feature = env.feature ?? '';
+    const abs = (p: string): string => (cwd ? join(cwd, p) : p);
+
+    const syncOut = spur(env, ['feature', 'sync', feature, '--dry-run', '--json'], { cwd });
+    let sync: PreflightSyncPayload | undefined;
+    if (syncOut.status === 0) {
+        try {
+            const parsed: unknown = JSON.parse(syncOut.stdout);
+            if (parsed !== null && typeof parsed === 'object') sync = parsed as PreflightSyncPayload;
+        } catch {
+            // fall through to the unreadable branch below
+        }
+    }
+    if (sync === undefined) return 'failed:preflight:sync-unreadable';
+    const proposal = sync.proposal;
+    if (
+        proposal === null ||
+        typeof proposal !== 'object' ||
+        Array.isArray(proposal) ||
+        (proposal.gateBlocked !== undefined && typeof proposal.gateBlocked !== 'boolean') ||
+        (proposal.gateFindings !== undefined && !isFindingList(proposal.gateFindings)) ||
+        (proposal.hops !== undefined &&
+            (!Array.isArray(proposal.hops) || !proposal.hops.every((hop) => typeof hop === 'string'))) ||
+        (proposal.gateBlocked !== true && (typeof proposal.from !== 'string' || typeof proposal.to !== 'string'))
+    ) {
+        return 'failed:preflight:sync-unreadable';
+    }
+
+    if (proposal.gateBlocked === true) {
+        return `failed:preflight:gate-blocked ${sortedUniqueCodes(proposal.gateFindings ?? []).join(',')}`;
+    }
+
+    const reachesDone = proposal.to === 'done' || (proposal.hops ?? []).includes('done');
+    if (!reachesDone) return null;
+
+    const checkOut = spur(env, ['feature', 'check', feature, '--strict', '--as', 'done', '--json'], { cwd });
+    let check: unknown;
+    try {
+        check = JSON.parse(checkOut.stdout);
+    } catch {
+        return 'failed:preflight:check-unreadable';
+    }
+    const payload = Array.isArray(check) && check.length === 1 ? check[0] : check;
+    const findings =
+        payload !== null && typeof payload === 'object' ? (payload as { findings?: unknown }).findings : undefined;
+    if (
+        !isFindingList(findings) ||
+        (checkOut.status !== 0 && (checkOut.status !== 1 || !findings.some((f) => f.severity === 'error')))
+    ) {
+        return 'failed:preflight:check-unreadable';
+    }
+    // The verifying onEnter will produce the receipt, so receipt-only errors on a feature
+    // that is not yet verifying would fail every wrapup forever.
+    const eligible =
+        proposal.from === 'verifying'
+            ? findings
+            : findings.filter((f) => !String(f.code ?? '').startsWith('L4.feature-receipt-'));
+
+    const runId = env.__runId ?? '';
+    if (runId.length > 0) {
+        mkdirSync(abs(join('.spur', 'run')), { recursive: true });
+        writeFileSync(abs(join('.spur', 'run', `${runId}-wrapup-preflight.json`)), `${JSON.stringify(check)}\n`);
+    }
+    const codes = sortedUniqueCodes(eligible);
+    return codes.length > 0 ? `failed:preflight:done-gate ${codes.join(',')}` : null;
+}
+
 /**
  * 0944 R3 route-reason map — mirrors the former inline jq object one-for-one, plus the
  * `safety` entry (operator-forced doc-sync). `fast:drift-probe-clean` is NOT in the map:
@@ -362,8 +479,10 @@ export function runMetrics(env: WrapupStepsEnv, options: WrapupStepsOptions = {}
         // fast-forwards and removes the tree, taking the gitignored artifact with it — the tracked
         // `Testing` line `task record` already wrote into the task file is the durable copy. Honest
         // UNKNOWN is the last resort, and it is telemetry, never proof of completion.
-        const verdictPath = join('.spur', 'run', `${wbs}-verdict.json`);
-        const artifactVerdict = verdictOfArtifact(abs(verdictPath));
+        const durable = join('.spur', 'memory', 'evidence', `${wbs}-verdict.json`);
+        const hasDurable = existsSync(abs(durable));
+        const verdictPath = hasDurable ? durable : join('.spur', 'run', `${wbs}-verdict.json`);
+        const artifactVerdict = verdictOfArtifact(abs(verdictPath)) ?? (hasDurable ? 'UNKNOWN' : null);
         const trackedVerdict = verdictFromTestingSection(typeof parsed.content === 'string' ? parsed.content : '');
         const verdict = artifactVerdict ?? trackedVerdict ?? 'UNKNOWN';
         if (verdict === 'UNKNOWN') {

package/plugins/sp/skills/source-driven-development/SKILL.md

@@ -91,6 +91,16 @@ Generate the code and **cite the source** (doc URL + date, or `pkg@version` + th
 point of use or in the task's notes. A claim about external behavior without a citation is
 unverified — flag it as such rather than presenting it as fact.
 
+### Step 5 — Close with a verification verdict
+
+Before finishing, verify the citations for the API/library claims you emitted and close with one
+line: `Verification: HIGH|MEDIUM|LOW — <first failing check and deviation, or 'all checks passed'>`.
+
+- **Citation coverage** — every API/library claim in the output carries a source citation (doc URL + date, or `pkg@version` + file/symbol); no uncited claim is asserted as fact.
+- **Source authority** — each citation points at the pinned version's primary source (installed signature/source, or official docs for the lockfile version), not the latest docs or memory.
+- **Honest confidence** — the stated HIGH/MEDIUM/LOW matches the evidence: HIGH requires a check against the pinned source this session; MEDIUM/LOW items are labeled, and LOW is never presented as fact.
+- **HIGH** — all three checks pass. **MEDIUM** — coverage intact but some citations are off-version (latest docs for a pinned dependency) or secondary-source only. **LOW** — an API/library claim lacks any citation, or a LOW-confidence claim was asserted as fact.
+
 ## Common Rationalizations
 
 | Rationalization | Reality |
@@ -116,6 +126,7 @@ unverified — flag it as such rather than presenting it as fact.
 - [ ] Both questions answered — the API exists **and** is called within its contract.
 - [ ] Claims about external behavior carry a citation (source + date, or `pkg@version` + symbol); unverifiable ones are flagged, not asserted.
 - [ ] Confidence is stated honestly (HIGH/MEDIUM/LOW); nothing at LOW was presented as fact.
+- [ ] Run closes with the Step 5 verdict line: `Verification: HIGH|MEDIUM|LOW — <first failing check and deviation, or 'all checks passed'>`.
 
 ## See also
 

package/plugins/sp/skills/spur-cli/references/tasks/section-editing.md

@@ -58,16 +58,20 @@ exactly: `Background`, `Requirements`, `Acceptance Criteria`, `Q&A`, `Design`, `
 `spur task record 0040 --transition testing` reads `.spur/run/0040-verdict.json`, writes
 `Testing` (per-requirement table), and backfills `Review` (P1–P4 findings table) **only when the
 section is bare** — a standalone compatibility fallback, never an overwrite of the review
-coordinator's authored Review — optionally backfilling a bare `Solution` from `git diff -U0`. It
-never transitions to `done`.
+coordinator's authored Review — optionally backfilling a bare `Solution` from `git diff -U0`.
+Record can also refresh its own earlier Review backfill. The `--transition testing` example stops
+at testing; `--transition done` with a PASS verdict walks the forward lifecycle edges through their
+guards and creates the required pipeline run-link immediately before the done hop.
 
 - **Use `record`** when a verify step produced a verdict artifact — it is the pipeline's record step
   and the deterministic `Testing` writer.
 - **Use `update --section`** when you are authoring a section by hand (planning, design, narrative
   solution) or amending one `record` already wrote.
 
-`record` writes `Testing` unconditionally and `Review` only when bare; a later
-`update --section` overwrites either (file-wins). Both go through the same file-wins atomic write.
+`record` re-reads the verdict on each invocation. PASS/PARTIAL/FAIL artifacts refresh Testing;
+UNKNOWN preserves authored Testing and writes a stub only when Testing is bare. Review remains
+fallback-only: bare content or record's own earlier backfill can be replaced, authored Review cannot.
+A later `update --section` overwrites either section (file-wins). Both use the same atomic write.
 
 ## Which section, when
 
@@ -81,7 +85,7 @@ LLM's job (orchestrated by `sp:spur-dev`); this skill only owns the *mechanism*:
 | `Plan` | before `wip` | the step list |
 | `Solution` | during impl (implement step) | the approach actually taken; L3 `file:line` rule fires once it has real content |
 | `Testing` | testing phase (`record` — deterministic writer) | what was verified and how — gated at `wip→testing` by `check` |
-| `Review` | review phase (`/sp:dev-review` coordinator) | merged SECU findings + verdict — gated at `testing→done` by `check --strict-core` |
+| `Review` | review phase (`/sp:dev-review` coordinator) | merged SECU findings + verdict — gated at `testing→done` by `check --as done` |
 
 Section presence per status is a **runtime contract**, not a table: query
 `spur task sections <wbs> list --json` (permitted present sections) and `spur task check <wbs> --json`

package/plugins/sp/skills/spur-cli/references/workflows.md

@@ -204,7 +204,7 @@ spur workflow run ./workflows/approval.yaml --silent               # errors only
 spur workflow run ./workflows/approval.yaml --verbose              # transitions + correlation diagnostics
 spur workflow run ./workflows/approval.yaml --detail minimal       # tersest human output
 spur workflow run ./workflows/approval.yaml --trace-file           # persist redacted JSONL trace
-spur workflow run ./workflows/approval.yaml --no-log               # opt out of the run record .spur/run/<RUNID>.md + .state.json
+spur workflow run ./workflows/approval.yaml --no-log               # opt out of the run record .spur/memory/runs/<RUNID>.md + .state.json
 spur workflow run ./workflows/approval.yaml --steer                # interactive steering on stdin
 ```
 
@@ -214,7 +214,7 @@ spur workflow run ./workflows/approval.yaml --steer                # interactive
   per-step headers), `full` (transitions + correlation). `--verbose` is shorthand for `--detail full`.
 - **`--trace-file`** appends a redacted, schema-versioned JSONL trace under `.spur/workflow/`
   for post-run analysis - independent of human/JSON output.
-- **`--no-log`** opts out of writing the two-file run record (`.spur/run/<RUNID>.md` + `.state.json`).
+- **`--no-log`** opts out of writing the two-file run record (`.spur/memory/runs/<RUNID>.md` + `.state.json`).
   By default the record is written **and retained** after the run ends; this flag skips it entirely
   (propagates to the `--async` detached worker). No `--keep-log` / delete-by-default exists.
 - **`--steer`** is synchronous and in-process: it cannot combine with `--json` or `--async` (exit `2`).
@@ -285,7 +285,7 @@ not advertise `--json-envelope` because its JSON projection is a kept-raw docume
 | `--verbose` | Include transitions and correlation diagnostics in human progress (implies `--detail full`). |
 | `--detail <level>` | Human detail level: `minimal`, `invocation` (default), or `full`. |
 | `--trace-file` | Append a redacted schema-versioned JSONL trace under `.spur/workflow/`. |
-| `--no-log` | Opt out of writing the two-file run record `.spur/run/<RUNID>.md` + `.state.json` (retained by default; propagates to `--async` workers). |
+| `--no-log` | Opt out of writing the two-file run record `.spur/memory/runs/<RUNID>.md` + `.state.json` (retained by default; propagates to `--async` workers). |
 | `--steer` | Accept in-process steering commands on stdin at declared action boundaries (sync only; incompatible with `--json`/`--async`). |
 
 `validate` and `run` exit non-zero on failure (`run` exits non-zero when the final status is not
@@ -302,7 +302,7 @@ Follow a live run to terminal (human streaming mode):
 ```bash
 spur workflow trace <run-id> --follow            # stream until terminal (default 1000ms poll)
 spur workflow trace <run-id> --follow --poll 500 # poll every 500ms
-spur workflow trace <run-id> --follow --output   # stream .spur/run/<RUNID>.md instead of the DB timeline
+spur workflow trace <run-id> --follow --output   # stream .spur/memory/runs/<RUNID>.md instead of the DB timeline
 spur workflow trace <run-id> --follow --timeout 600000 # bound the watch; timeout → one checkpoint, run continues, exit 1
 ```
 
@@ -316,7 +316,7 @@ spur workflow trace <run-id> --follow --timeout 600000 # bound the watch; timeou
   status and exits `1`. A watch timeout never cancels or relaunches the run; resume by re-running the same
   follow command.
 - **`--output`** swaps the follow source from the structured DB timeline to the human run record
-  (`.spur/run/<RUNID>.md`, tail -f equivalent), streaming new lines as they land and exiting at
+  (`.spur/memory/runs/<RUNID>.md`, tail -f equivalent), streaming new lines as they land and exiting at
   terminal status. A pre-0925 run with only a legacy `<RUNID>.log` is followed in place (read-only
   fallback). It requires `--follow` and a `run-id`, is a human stream (rejects `--json`), and is
   a **distinct source** — it never interleaves with the DB timeline. If no record file appears (e.g. the
@@ -360,15 +360,18 @@ redirecting `agent.run` stages (ADR-047).
 
 - **Stale-run finalization** (existing): bulk-finalizes orphaned `running`/`pending` runs as `failed`.
   `--older-than <minutes>` (default 30) and `--force` (all non-terminal regardless of age) apply here only.
-- **Run-log reclamation** (0429): removes retained `.spur/run/<RUNID>.log` files whose mtime is older
-  than `workflow.logRetentionDays` in `.spur/config.yaml` (default 30 days; integer days, not minutes).
-  Age is the only gate; best-effort deletes never abort the rest. Never touches
-  `.spur/workflow/<RUNID>.jsonl` or `*-partial.md`. Scope stays legacy `.log` names only (0925 R4):
-  the two-file record (`.md` + `.state.json`) is not reclaimed until a pair retention policy exists.
-- **`--logs`** scopes to log reclamation only (skips stale-run finalization). `--dry-run` applies to
-  both scopes (lists what would be removed, writes nothing). `--json` returns
-  `{ olderThanMinutes, dryRun, cleaned, logs: { retentionDays, dryRun, reclaimed, failures } }` (with
-  `--logs`, the reclamation object alone).
+- **Run-log reclamation** (0429): removes expired `.log` files from `.spur/memory/runs/`
+  and legacy `.spur/run/`, using `workflow.logRetentionDays` (default 30 days). Non-terminal
+  runs, including paused/interrupted runs, are protected; ownership lookup failures preserve logs.
+  The two-file record (`.md` + `.state.json`) and partial handoffs are retained.
+- **Checkpoint reclamation**: removes expired terminal checkpoints only when confinement,
+  metadata and run-ownership guards pass. Recoverable runs remain protected.
+- **Migration** (E71): verified lasting scratch data is preserved and references redirected before
+  reclamation. Unsettled imports, live dependencies, malformed files and conflicts retain their sources.
+- **`--logs`** scopes to log reclamation and its migration (skips stale-run finalization and
+  checkpoint reclamation). `--dry-run` reports without copying or deleting. `--json` returns
+  `{ olderThanMinutes, dryRun, cleaned, logs, checkpoints, migration }`; with `--logs`, it returns
+  `{ retentionDays, dryRun, reclaimed, failures, migration }`.
 
 ## Behavior
 

package/plugins/sp/skills/spur-dev/SKILL.md

@@ -206,6 +206,8 @@ section adds what that table has no room for: per-file content summaries and ite
 step (glossary, config companions).** Read Step routing to find "which file for step X"; read below
 for "what's actually in file Y" or for resources that sit outside the step sequence.
 
+- Job transfer: [dump/resume](references/dev-operations.md#11a-job-dump).
+
 - [references/glossary.md](references/glossary.md) — sp's own vocabulary: spine, competency, facade,
   corpus, gate, verdict, noun/verb, half, HITL, WBS, section-write contract — canonical term +
   Avoid list. Owns term definitions only; `cross-cutting.md` owns the process rules that use them.

package/plugins/sp/skills/spur-dev/references/cross-cutting.md

@@ -135,7 +135,9 @@ workflow run` and never redirect silently to `agent.default`. Interactive **omit
 **host-controlled and non-subprocess**, but no longer guarantees host-context execution for every
 model stage (task 0508): an eligible `agent.run` stage — pure-slash input, non-interactive state,
 native subagent with shared-worktree read/write/shell capability, and a task above the
-`estimate_hours` dispatch floor (2026-09-15 subagent-dispatch evaluation; the floor and the
+`estimate_hours` dispatch floor — a small, non-sensitive triage diffstat
+(`.spur/run/<wbs>-diffstat.json`, verify only) keeps that stage host-inline (2026-09-15
+subagent-dispatch evaluation; the floor and the
 resume-over-re-dispatch rule for worker-role continuation stages are owned by
 [inline-pipeline-driver.md](inline-pipeline-driver.md)) — dispatches **once** to that
 native subagent and joins before the driver continues; any pre-dispatch eligibility failure falls