@gobing-ai/spur 0.3.96 → 0.3.98

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/code-implementation/SKILL.md

@@ -184,7 +184,7 @@ reproduce → isolate → minimal fix → regression guard.
 
 - Writing code without having read the immediate callers of what you're changing.
 - A `## Solution` section that lists files but not what changed or why.
-- A `## Solution` section with file references that are not in backtick `` `path:line` `` form (L3 requirement: `` `packages/app/src/foo.ts:123` `` or `` `packages/app/src/bar.ts:10-20` ``; paths from repo root).
+- A `## Solution` section with file references that are not in backtick `` `path:line` `` form (L3 requirement: `` `packages/app/src/foo.ts:123` `` or `` `packages/app/src/bar.ts:10-20` ``; paths from repo root). Non-repo paths (external packages, `@scope/...`) can never resolve repo-relative — cite them in the frozen external-evidence form instead: `Evidence: @gobing-ai/ts-x \`src/persistence.ts\` line 108` (origin and line number OUTSIDE the backticks). Wrong: `` `@gobing-ai/ts-x/src/persistence.ts:108` `` — the L4 gate fails it as an unresolvable anchor (task 1055).
 - A new abstraction with exactly one caller and no second use in sight.
 - The diff touches files unrelated to the task's scope.
 - The diff touches another WBS's surfaces, or the pass reads sibling `todo` / `wip` task files.

package/plugins/sp/skills/conflict-finding/SKILL.md

@@ -249,7 +249,7 @@ Thin wrapper: `Skill(skill="sp:conflict-finding", args="$ARGUMENTS")`.
 - Silently omitting a selected pillar or a tool failure (no coverage accounting).
 - Claiming "comprehensive" when `coverage.complete` is false.
 - Any mutation in audit mode, or automatic mutation merely because `--resolve` is present.
-- Editing a derived projection before its authority.
+- Editing a derived projection before correcting a defective authority, or changing a correct authority merely to repair its stale projection.
 - Adding a production analyzer, index/cache/database, dependency, or dedicated subagent in v1.
 
 ## Reference files

package/plugins/sp/skills/conflict-finding/references/authority-resolution.md

@@ -206,13 +206,15 @@ authority it governs:
 | Owner | Repair route | Governs (claim types) |
 |-------|--------------|----------------------|
 | Task/feature corpus | `sp:spur-cli` / `spur task` / `spur feature`; never direct file writes | Task obligation/status, feature goal and AC |
-| Numbered docs and AGENTS projections | `sp:doc-evolve`; authority first, derived projections second | Process rules, structural decision, product scope, architecture, command surface |
+| Numbered docs and AGENTS projections | `sp:doc-evolve`; inspect authority first, correct it only if defective, then repair affected projections | Process rules, structural decision, product scope, architecture, command surface |
 | Source/tests | create/use a Spur task and route through `sp:spur-dev` / build competencies | Implementation behavior, architecture mechanism |
 | Command/skill capability source | Superskill command/skill lifecycle in the owning plugin source | Command/API/schema surface |
 | Ambiguous authority | **stop** for an operator decision; do not mutate either side | (all, when unresolved) |
 
-Never edit a derived projection before its authority. The authority column of §2 is always the
-owner surface's source of truth; a projection is brought into line with it, not the reverse.
+Inspect the governing authority before repairing a derived projection. Correct the authority first
+only when it is defective and the correction is authorized; otherwise leave it unchanged and repair
+the projection. The authority column of §2 remains the owner surface's source of truth; a projection
+is brought into line with it, not the reverse.
 
 ## 7. Worked examples
 

package/plugins/sp/skills/conflict-finding/references/remediation-routing.md

@@ -113,13 +113,13 @@ between "the audit said X" and "the file now says Y."
 Each approved repair is dispatched through the artifact's **owner surface** — the harness path that
 owns writes to that artifact — not a direct file write. Authority for a repair is the same
 authority model as the audit ([./authority-resolution.md](./authority-resolution.md)): for a given
-subject + claim type, one artifact is normative; derived projections are updated only after their
-authority.
+subject + claim type, one artifact is normative. Inspect it first; correct it only if defective and
+authorized, then update affected projections. A correct authority needs no edit for a stale projection.
 
 | Owner | Repair route | Never |
 |-------|--------------|-------|
 | Task/feature corpus | `sp:spur-cli` — `spur task` / `spur feature` (with `--section`, `--from-file`, `--json` as needed) | Direct file writes to task/feature files. |
-| Numbered docs and AGENTS projections | `sp:doc-evolve` — **authority first, derived projections second** (see below) | Editing `docs/05_FEATURES.md` or an `AGENTS.md` projection before its authoritative source is fixed. |
+| Numbered docs and AGENTS projections | `sp:doc-evolve` — inspect authority first; correct it only if defective, then repair affected projections (see below) | Changing correct authority to repair a stale projection, or projecting a defective authority before its authorized correction. |
 | Source / tests | Create or use a **Spur task** and route through `sp:spur-dev` / build competencies (`sp:code-implementation`, `sp:code-testing`), **unless** the active session already has explicit implementation authority for the change. | Bare in-place edits to source/tests without a task or explicit authority. |
 | Command/skill capability source | Superskill command/skill **lifecycle** (`superskill command …` / `superskill skill …` scaffold/validate/evaluate/refine) in the owning plugin source. | Hand-editing capability source outside the Superskill lifecycle. |
 | Ambiguous authority | **Stop for an operator decision.** Do not mutate either side. | Choosing a winner, editing both sides, or forcing a global ranking. |
@@ -148,12 +148,13 @@ item; never route around it with a direct write.
 
 ### 3.2 Numbered docs and AGENTS projections
 
-Documentation repairs follow **authority first, derived projections second**. If a derived
+Documentation repairs **inspect authority first**. If a derived
 projection (`docs/04_DESIGN.md`, `docs/05_FEATURES.md`, `AGENTS.md`, templates) has drifted from its
 authority (`docs/00_ADR.md`, `docs/01_PRD.md`, `docs/03_ARCHITECTURE.md`,
-`docs/99_PROJECT_CONSTITUTION.md`), the repair fixes the **authority** first, then re-derives the
-projection via `sp:doc-evolve`. Editing a projection without its authority is a prohibited
-anti-pattern (see §6).
+`docs/99_PROJECT_CONSTITUTION.md`), leave a correct authority unchanged and repair the stale
+projection via `sp:doc-evolve`. If the authority itself is defective, correct it first within the
+approved scope, then update affected projections. Incomparable authority still requires an operator
+decision; projection drift alone never authorizes changing the governing contract (see §6).
 
 `sp:doc-evolve` owns the numbered-doc/projection lifecycle: sync checks, contract verification,
 frontmatter checks, and derived-doc refresh. A doc repair is dispatched to it; it is not hand-applied.
@@ -244,7 +245,7 @@ These are the explicit boundaries for remediation. Each is a hard violation, not
 | Anti-pattern | Why it is prohibited |
 |--------------|----------------------|
 | **Automatic mutation merely because `--resolve` is present** | `--resolve` only opens the workflow; it never authorizes automatic repair. Confirmation + freshness + owner surface are all required. |
-| **Editing a derived projection before its authority** | A projection (`docs/04`/`docs/05`, `AGENTS.md`, templates) is not the source of truth; fixing it without its authority (`ADR`/`PRD`/constitution) leaves the real conflict in place. Authority first. |
+| **Changing correct authority for projection drift** | A stale projection is repaired against its governing contract. Correct authority only when defective and authorized; then update affected projections. |
 | **Broad cleanup outside confirmed findings** | Only the artifacts named by confirmed, freshness-checked findings are touched. No opportunistic refactors or doc "improvements" while repairing. |
 | **Ambiguity silently resolved** | Ambiguous/missing authority stops for an operator decision; it is never forced through a global ranking or a guessed owner. |
 | **Partial failure silently continued** | A failed repair is reported, not papered over; siblings are not marked successful and the run does not roll forward silently. |

package/plugins/sp/skills/doc-evolve/SKILL.md

@@ -100,9 +100,10 @@ rg --files apps packages                       # real modules
 git log -1 --format='%ci' -- docs/04_DESIGN.md     # last touch vs. recent surface changes
 ```
 
-**Repair protocol (§7):** fix the authoritative statement first, then affected detail/index/entry
-files. Preserve ADR numbers, original titles/dates and decision history; editorial condensation
-follows §6.1, while actual reversals need a superseding decision. Record findings in a task/report.
+**Repair protocol (§7):** inspect the governing statement first. Correct it only if defective and
+authorized, then update affected detail/index/entry files; otherwise leave the authority unchanged
+and repair its stale projections. Preserve ADR numbers, original titles/dates and decision history;
+editorial condensation follows §6.1, while actual reversals need a superseding decision. Record findings in a task/report.
 Routine lessons go to existing learning/context storage (§8); no automatic constitution edits.
 
 Output a **drift report**: per finding, `{ doc, what code says, what the doc says, authority, repair

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

@@ -42,13 +42,16 @@ for `Plan`, `Acceptance Criteria`, hand-authored `Solution`, and any narrative s
    spur task update 0040 --section Review --from-file /tmp/review.md
    ```
 
-3. The whole `### Review` body is now that file's contents. To amend rather than overwrite, read
-   the current body (`spur task show 0040`), edit the temp file to the full desired state, and
-   replace again — there is no append mode for ordinary sections.
+3. The whole `### Review` body is now that file's contents. To amend rather than overwrite, either
+   read the current body (`spur task show 0040`), edit the temp file to the full desired state, and
+   replace again — or pass `--append` (task 1057) to write the file's body after the existing
+   section content (existing content + one blank line + new body; surrounding whitespace trimmed; an empty/missing section is
+   created). `--append` requires `--section` and never replaces on its own.
 
 **`Q&A` is the exception.** `--section "Q&A"` APPENDS a timestamped `#### Q&A entry — <ISO>`
 block rather than replacing the section. Start the body with `<!-- qa:replace -->` to replace it
-wholesale.
+wholesale. Explicit `--append` on `Q&A` uses the generic append (no timestamped wrapper); the
+`<!-- qa:replace -->` marker still wins and forces wholesale replace.
 
 `--section` **requires** `--from-file` (exit `2` otherwise). Section names match the DD-08 headings
 exactly: `Background`, `Requirements`, `Acceptance Criteria`, `Q&A`, `Design`, `Plan`, `Solution`, `Root Cause`, `Testing`, `Review`, `References`, `History`, `Notes` (universal sections are `History`, `References`, `Notes`; `Root Cause` is carried by the `issue` template variant).
@@ -58,16 +61,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 +88,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`