@gobing-ai/spur 0.3.92 → 0.3.93

package/plugins/sp/scripts/wrapup-drift-probe.ts

@@ -0,0 +1,258 @@
+#!/usr/bin/env bun
+/**
+ * wrapup-drift-probe — deterministic doc-ownership drift probe behind the wrapup-pipeline
+ * task-resolve onEnter (task 0944, feature D64, ADR-115 composition budgets).
+ *
+ * Reads the validated wrapup capture `.spur/run/<runId>-wrapup-tasks.json` (never raw
+ * vars.tasks — 0783 contract), runs `spur task show <wbs> --json` per member, collects the
+ * changed paths from each task's `### Solution` file:line map, and writes:
+ *   - `<runId>-drift-probe.json`  `{ clean: boolean, reasons: string[], paths: string[] }`
+ *   - `<runId>-mode.txt`          projected wrapup mode: `fast` when clean, empty otherwise
+ *
+ * The probe runs ONLY when the caller left `mode` empty; a caller-set mode is projected
+ * verbatim by the workflow wrapper and this script is never invoked (0944 R3).
+ *
+ * Dirty (clean=false, mode stays empty → the safety route) whenever ANY changed path
+ * matches a doc-owned surface (AGENTS.md doc map + docs/99_PROJECT_CONSTITUTION.md
+ * ownership table), or a task's Solution section is empty or unparseable (fail safe —
+ * a wrapup without a readable change map must still reach doc-sync). Paths under the
+ * task/feature corpus are never treated as drift.
+ *
+ * Node-builtin imports only; the spur lookup is a spawnable `SpurRunner` so tests can
+ * fake it; `main(argv, env, options)` is the same injection point the workflow wrapper
+ * and its node twin exercise. Always exits 0 after probing; only an empty `__runId`
+ * (mis-invocation) exits 1.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getEnvVars } from '../lib/env';
+
+export interface DriftProbeEnv {
+    __runId?: string;
+    spurBin?: string;
+    [key: string]: string | undefined;
+}
+
+export interface DriftProbeOptions {
+    /** Base directory for `.spur/run`; defaults to the process cwd. */
+    cwd?: string;
+}
+
+/** Minimal spawnable spur surface — tests fake this to return canned `task show` output. */
+export interface SpurShowResult {
+    status: number;
+    stdout: string;
+}
+export type SpurRunner = (args: string[]) => SpurShowResult;
+
+export interface DriftProbeResult {
+    clean: boolean;
+    reasons: string[];
+    paths: string[];
+    probeFile: string;
+    modeFile: string;
+    /** Exit code the workflow wrapper observes (only an empty __runId is a hard failure). */
+    exitCode: number;
+}
+
+/**
+ * Doc-owned surfaces (0944 R2): a changed path under any of these means doc-sync must
+ * still run. Mirrors the AGENTS.md documentation map and the
+ * docs/99_PROJECT_CONSTITUTION.md ownership table: contracts / cli commands / config /
+ * migrations / workflow YAML / plugin commands, skills and hooks / root manifest / the
+ * authoritative docs (00_ADR, 03_ARCHITECTURE, 04_DESIGN, docs/design). docs/tasks* and
+ * docs/features/* (the corpus) are intentionally absent — they are never drift.
+ *
+ * WHY join('config', 'workflows'): rule sp-runtime-path forbids the literal
+ * config/<dir> in runtime source; this constant is a drift TARGET (Solution
+ * change-map paths against the build-time SSOT), not a runtime config read.
+ */
+const WORKFLOWS_GLOB = `${join('config', 'workflows')}/**`;
+export const DOC_OWNED_SURFACES = [
+    'packages/contracts/**',
+    'apps/cli/src/commands/**',
+    'packages/config/src/**',
+    'drizzle/*.sql',
+    WORKFLOWS_GLOB,
+    'plugins/sp/commands/**',
+    'plugins/sp/skills/**',
+    'plugins/sp/hooks/**',
+    'package.json',
+    'docs/00_ADR.md',
+    'docs/03_ARCHITECTURE.md',
+    'docs/04_DESIGN.md',
+    'docs/design/**',
+] as const;
+
+/**
+ * Top-level workspace entries from the AGENTS.md stack layout. A changed path whose first
+ * segment is none of these is a new top-level workspace directory — doc-owned by default.
+ * Single-segment paths (root files) are not directories and are exempt.
+ */
+const KNOWN_TOP_LEVEL = new Set([
+    'apps',
+    'packages',
+    'plugins',
+    'config',
+    'docs',
+    'drizzle',
+    'scripts',
+    'vendors',
+    'package.json',
+    'bun.lock',
+    'bunfig.toml',
+]);
+
+/** Corpus paths (task/feature records) are never drift — excluded before surface matching. */
+const CORPUS_PREFIXES = ['docs/tasks', 'docs/features/'];
+
+/** `### Solution` section of a task record (tolerates `##`–`####` heading depth). */
+export function solutionSectionOf(content: string): string | null {
+    const heading = /^#{2,4}\s+Solution\s*$/m.exec(content);
+    if (!heading) return null;
+    const rest = content.slice(heading.index + heading[0].length);
+    const next = /^#{2,4}\s+\S/m.exec(rest);
+    return next ? rest.slice(0, next.index) : rest;
+}
+
+const CHANGE_ENTRY = /`([^`\r\n]+):(\d+)(?:-\d+)?`/g;
+
+/** Backticked `path:line` (or `path:line-range`) tokens from a Solution section. */
+export function changedPathsOf(section: string | null): string[] {
+    if (section === null) return [];
+    const paths: string[] = [];
+    for (const match of section.matchAll(CHANGE_ENTRY)) {
+        const path = match[1];
+        // Path-like: no whitespace and at least one separator or dotted suffix, so prose
+        // backticks never masquerade as change-map entries.
+        if (/\s/.test(path)) continue;
+        if (!path.includes('/') && !path.includes('.')) continue;
+        paths.push(path);
+    }
+    return paths;
+}
+
+function surfaceRegex(glob: string): RegExp {
+    const escaped = glob
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replaceAll('**', '\u0000')
+        .replaceAll('*', '[^/]*')
+        .replaceAll('\u0000', '.*');
+    return new RegExp(`^${escaped}$`);
+}
+
+const SURFACE_MATCHERS = DOC_OWNED_SURFACES.map((glob) => ({ glob, regex: surfaceRegex(glob) }));
+
+/** 0944 R2 surface match: doc-owned glob, corpus exclusion, new top-level directory. */
+export function driftReasonForPath(path: string): string | null {
+    if (CORPUS_PREFIXES.some((prefix) => path.startsWith(prefix))) return null;
+    if (path.includes('/') && !KNOWN_TOP_LEVEL.has(path.split('/')[0])) {
+        return 'new top-level workspace directory';
+    }
+    const match = SURFACE_MATCHERS.find((entry) => entry.regex.test(path));
+    return match ? `matches doc-owned surface ${match.glob}` : null;
+}
+
+function defaultSpurRunner(env: DriftProbeEnv, cwd?: string): SpurRunner {
+    const parts = (env.spurBin ?? 'spur').split(/\s+/).filter((part) => part.length > 0);
+    return (args: string[]): SpurShowResult => {
+        const run = spawnSync(parts[0], [...parts.slice(1), ...args], {
+            cwd,
+            encoding: 'utf8',
+            env: getEnvVars(),
+        });
+        return { status: run.status ?? 1, stdout: run.stdout ?? '' };
+    };
+}
+
+/**
+ * `probe` — classify the wrapup as clean (pure application-code change, no doc-owned
+ * surface touched) or dirty, and project the wrapup mode. Fail safe: every lookup or
+ * parse problem is a dirty probe, never a silent clean.
+ */
+export function runDriftProbe(
+    env: DriftProbeEnv,
+    options: DriftProbeOptions = {},
+    spur = defaultSpurRunner(env, options.cwd),
+): DriftProbeResult {
+    const cwd = options.cwd;
+    const runId = env.__runId ?? '';
+    if (runId.length === 0) {
+        process.stderr.write('wrapup-drift-probe: __runId is empty — refusing the legacy fixed-path fallback\n');
+        return { clean: false, reasons: [], paths: [], probeFile: '', modeFile: '', exitCode: 1 };
+    }
+    const relProbeFile = join('.spur', 'run', `${runId}-drift-probe.json`);
+    const relModeFile = join('.spur', 'run', `${runId}-mode.txt`);
+    const relTasksFile = join('.spur', 'run', `${runId}-wrapup-tasks.json`);
+    const abs = (p: string): string => (cwd ? join(cwd, p) : p);
+    mkdirSync(abs(join('.spur', 'run')), { recursive: true });
+    // Write the dirty projection first so a crash mid-probe fails safe (mode stays empty).
+    writeFileSync(abs(relModeFile), '\n');
+
+    const finish = (clean: boolean, reasons: string[], paths: string[]): DriftProbeResult => {
+        writeFileSync(abs(relProbeFile), `${JSON.stringify({ clean, reasons, paths })}\n`);
+        writeFileSync(abs(relModeFile), clean ? 'fast\n' : '\n');
+        return { clean, reasons, paths, probeFile: relProbeFile, modeFile: relModeFile, exitCode: 0 };
+    };
+
+    let tasks: unknown;
+    try {
+        tasks = JSON.parse(readFileSync(abs(relTasksFile), 'utf8'));
+    } catch {
+        tasks = undefined;
+    }
+    if (!Array.isArray(tasks) || !tasks.every((wbs) => typeof wbs === 'string')) {
+        process.stderr.write(
+            'wrapup-drift-probe: normalized task capture is missing or corrupted — failing safe (dirty)\n',
+        );
+        return finish(false, ['normalized task capture missing or corrupted'], []);
+    }
+
+    const reasons: string[] = [];
+    const allPaths = new Set<string>();
+    for (const wbs of tasks as string[]) {
+        const shown = spur(['task', 'show', wbs, '--json']);
+        if (shown.status !== 0) {
+            reasons.push(`${wbs}: task show failed (status=${shown.status})`);
+            continue;
+        }
+        let content: unknown;
+        try {
+            content = JSON.parse(shown.stdout).content;
+        } catch {
+            content = undefined;
+        }
+        if (typeof content !== 'string') {
+            reasons.push(`${wbs}: task show output unparseable`);
+            continue;
+        }
+        const changedPaths = changedPathsOf(solutionSectionOf(content));
+        if (changedPaths.length === 0) {
+            reasons.push(`${wbs}: Solution empty or unparseable`);
+            continue;
+        }
+        for (const path of changedPaths) {
+            if (CORPUS_PREFIXES.some((prefix) => path.startsWith(prefix))) continue;
+            allPaths.add(path);
+            const drift = driftReasonForPath(path);
+            if (drift) reasons.push(`${wbs}: ${path} ${drift}`);
+        }
+    }
+    return finish(reasons.length === 0, reasons, [...allPaths].sort());
+}
+
+export const WRAPUP_DRIFT_PROBE_USAGE = 'usage: wrapup-drift-probe  (env: __runId, spurBin)';
+
+export function main(argv: string[], env: DriftProbeEnv = getEnvVars(), options: DriftProbeOptions = {}): number {
+    if (argv.length > 0) {
+        process.stderr.write(`${WRAPUP_DRIFT_PROBE_USAGE}\n`);
+        return 2;
+    }
+    return runDriftProbe(env, options).exitCode;
+}
+
+if (import.meta.main) {
+    process.exit(main(process.argv.slice(2)));
+}

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

@@ -116,6 +116,62 @@ function resolveTasks(env, options = {}) {
 `);
   return { status: "PASS", statusFile: relStatusFile, tasksFile: relTasksFile, exitCode: 0 };
 }
+var ROUTE_REASON_TABLE = {
+  fast: "fast:evidence complete+consistent",
+  "": "safety:missing evidence (mode empty)",
+  unknown: "safety:unknown evidence quality",
+  conflict: "safety:conflicting evidence",
+  safety: "safety:operator-forced doc-sync"
+};
+function writeRouteReason(env, options = {}) {
+  const cwd = options.cwd;
+  const runId = env.__runId ?? "";
+  if (runId.length === 0) {
+    process.stderr.write(`task-resolve: __runId is empty \u2014 refusing to write a route reason
+`);
+    return { reason: "", reasonFile: "", exitCode: 1 };
+  }
+  mkdirSync(cwd ? join(cwd, ".spur", "run") : join(".spur", "run"), { recursive: true });
+  mkdirSync(cwd ? join(cwd, ".spur", "memory") : join(".spur", "memory"), { recursive: true });
+  const relReasonFile = join(".spur", "run", `${runId}-route-reason.txt`);
+  const abs = (p) => cwd ? join(cwd, p) : p;
+  const statusFile = join(".spur", "run", `${runId}-wrapup-resolve.status`);
+  if (readFileSyncSafe(abs(statusFile))?.trim() === "FAIL") {
+    return { reason: "", reasonFile: relReasonFile, exitCode: 0 };
+  }
+  let taskCount = -1;
+  try {
+    const parsed = JSON.parse(readFileSync(abs(join(".spur", "run", `${runId}-wrapup-tasks.json`)), "utf8"));
+    if (Array.isArray(parsed))
+      taskCount = parsed.length;
+  } catch {}
+  let probeClean = false;
+  try {
+    const probe = JSON.parse(readFileSync(abs(join(".spur", "run", `${runId}-drift-probe.json`)), "utf8"));
+    probeClean = probe?.clean === true;
+  } catch {}
+  const mode = env.mode ?? "";
+  let reason;
+  if (taskCount === 0) {
+    reason = "skipped:empty task list";
+  } else if (mode === "fast" && probeClean) {
+    reason = "fast:drift-probe-clean";
+  } else {
+    reason = ROUTE_REASON_TABLE[mode] ?? `safety:unrecognized evidence (mode=${mode})`;
+  }
+  writeFileSync(abs(relReasonFile), `${reason}
+`);
+  appendFileSync(abs(join(".spur", "memory", "wrapup-routes.log")), `${runId} ${reason}
+`);
+  return { reason, reasonFile: relReasonFile, exitCode: 0 };
+}
+function readFileSyncSafe(path) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}
 function runMetrics(env, options = {}) {
   const cwd = options.cwd;
   const runId = env.__runId ?? "";
@@ -325,11 +381,13 @@ function runFeatureTransition(env, options = {}) {
 `);
   return { status: syncStatus, statusFile: relStatusFile, exitCode: 0 };
 }
-var WRAPUP_STEPS_USAGE = "usage: wrapup-steps.ts <resolve|metrics|feature-transition>  (env: __runId, tasks, feature, featureGateCmd, spurBin)";
+var WRAPUP_STEPS_USAGE = "usage: wrapup-steps.ts <resolve|route-reason|metrics|feature-transition>  (env: __runId, tasks, mode, feature, featureGateCmd, spurBin)";
 function main(argv, env = getEnvVars(), options = {}) {
   const sub = argv[0];
   if (sub === "resolve")
     return resolveTasks(env, options).exitCode;
+  if (sub === "route-reason")
+    return writeRouteReason(env, options).exitCode;
   if (sub === "metrics") {
     runMetrics(env, options);
     return 0;
@@ -344,6 +402,7 @@ function main(argv, env = getEnvVars(), options = {}) {
   process.exit(main(process.argv.slice(2)));
 }
 export {
+  writeRouteReason,
   taskStatusOf,
   spurCommand,
   runMetrics,

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

@@ -3,12 +3,13 @@
  * wrapup-steps — deterministic wrap-up capture, metrics and feature sync behind the
  * wrapup-pipeline wrappers (task 0824, feature I21, governance §1.2 composition budgets).
  *
- * Reproduces the former wrapup-pipeline `task-resolve:onEnter:0`, `metrics-record:onEnter:0`
- * and `feature-transition:onEnter:0` shell programs one-for-one so the workflow stays inside
+ * Reproduces the former wrapup-pipeline `task-resolve:onEnter:0`, `task-resolve:onEnter:1`
+ * (route-reason writer, moved here in 0944), `metrics-record:onEnter:0` and
+ * `feature-transition:onEnter:0` shell programs one-for-one so the workflow stays inside
  * 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>-route-reason.txt`        route reason (written by the workflow route writer)
+ *   - `<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)
  *   - `<runId>-wrapup-sync.status`      `PASS`/`FAIL` (feature-transition)
@@ -185,6 +186,89 @@ export function resolveTasks(env: WrapupStepsEnv, options: WrapupStepsOptions =
     return { status: 'PASS', statusFile: relStatusFile, tasksFile: relTasksFile, exitCode: 0 };
 }
 
+/**
+ * 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:
+ * it is only claimable when the drift probe itself classified the wrapup clean.
+ */
+const ROUTE_REASON_TABLE: Record<string, string> = {
+    fast: 'fast:evidence complete+consistent',
+    '': 'safety:missing evidence (mode empty)',
+    unknown: 'safety:unknown evidence quality',
+    conflict: 'safety:conflicting evidence',
+    safety: 'safety:operator-forced doc-sync',
+};
+
+export interface RouteReasonResult {
+    reason: string;
+    reasonFile: string;
+    exitCode: number;
+}
+
+/**
+ * `route-reason` — derive the task-resolve route reason from the validated capture, the
+ * projected mode and the drift probe verdict (0944). A resolve FAIL keeps its own reason
+ * (nothing is written, exit 0). A missing or corrupted capture never yields a `skipped`
+ * or `fast:drift-probe-clean` claim. The log line is run-attributed (0770).
+ */
+export function writeRouteReason(env: WrapupStepsEnv, options: WrapupStepsOptions = {}): RouteReasonResult {
+    const cwd = options.cwd;
+    const runId = env.__runId ?? '';
+    if (runId.length === 0) {
+        process.stderr.write('task-resolve: __runId is empty — refusing to write a route reason\n');
+        return { reason: '', reasonFile: '', exitCode: 1 };
+    }
+    mkdirSync(cwd ? join(cwd, '.spur', 'run') : join('.spur', 'run'), { recursive: true });
+    mkdirSync(cwd ? join(cwd, '.spur', 'memory') : join('.spur', 'memory'), { recursive: true });
+    const relReasonFile = join('.spur', 'run', `${runId}-route-reason.txt`);
+    const abs = (p: string): string => (cwd ? join(cwd, p) : p);
+
+    const statusFile = join('.spur', 'run', `${runId}-wrapup-resolve.status`);
+    if (readFileSyncSafe(abs(statusFile))?.trim() === 'FAIL') {
+        // The failed reason stands; the failed edge already owns the run.
+        return { reason: '', reasonFile: relReasonFile, exitCode: 0 };
+    }
+
+    // A missing/corrupted capture stays at -1: never 0, so no skipped claim can be invented.
+    let taskCount = -1;
+    try {
+        const parsed: unknown = JSON.parse(
+            readFileSync(abs(join('.spur', 'run', `${runId}-wrapup-tasks.json`)), 'utf8'),
+        );
+        if (Array.isArray(parsed)) taskCount = parsed.length;
+    } catch {
+        // treated as uncountable below
+    }
+    let probeClean = false;
+    try {
+        const probe: unknown = JSON.parse(readFileSync(abs(join('.spur', 'run', `${runId}-drift-probe.json`)), 'utf8'));
+        probeClean = (probe as { clean?: unknown } | null)?.clean === true;
+    } catch {
+        // no probe verdict — the map decides
+    }
+
+    const mode = env.mode ?? '';
+    let reason: string;
+    if (taskCount === 0) {
+        reason = 'skipped:empty task list';
+    } else if (mode === 'fast' && probeClean) {
+        reason = 'fast:drift-probe-clean';
+    } else {
+        reason = ROUTE_REASON_TABLE[mode] ?? `safety:unrecognized evidence (mode=${mode})`;
+    }
+    writeFileSync(abs(relReasonFile), `${reason}\n`);
+    appendFileSync(abs(join('.spur', 'memory', 'wrapup-routes.log')), `${runId} ${reason}\n`);
+    return { reason, reasonFile: relReasonFile, exitCode: 0 };
+}
+
+function readFileSyncSafe(path: string): string | null {
+    try {
+        return readFileSync(path, 'utf8');
+    } catch {
+        return null;
+    }
+}
+
 export interface MetricsResult {
     status: 'PASS' | 'FAIL';
     statusFile: string;
@@ -448,11 +532,12 @@ export function runFeatureTransition(env: WrapupStepsEnv, options: WrapupStepsOp
 }
 
 export const WRAPUP_STEPS_USAGE =
-    'usage: wrapup-steps.ts <resolve|metrics|feature-transition>  (env: __runId, tasks, feature, featureGateCmd, spurBin)';
+    'usage: wrapup-steps.ts <resolve|route-reason|metrics|feature-transition>  (env: __runId, tasks, mode, feature, featureGateCmd, spurBin)';
 
 export function main(argv: string[], env: WrapupStepsEnv = getEnvVars(), options: WrapupStepsOptions = {}): number {
     const sub = argv[0];
     if (sub === 'resolve') return resolveTasks(env, options).exitCode;
+    if (sub === 'route-reason') return writeRouteReason(env, options).exitCode;
     if (sub === 'metrics') {
         runMetrics(env, options);
         return 0;

package/plugins/sp/skills/brainstorm/SKILL.md

@@ -137,6 +137,8 @@ template, source-citation format) is needed only inside each phase, not at the p
 2. IDEATE   → Generate 2-3 approaches with trade-offs (delegate research inline; escalate via spur agent run on a trigger)
 3. OUTPUT   → Structured markdown (Overview → Approaches → Recommendations → Next Steps),
               delivered incrementally; saved to docs/plans/YYYY-MM-DD-<topic>-brainstorm.md
+              with the spur-dev plan frontmatter (kind: plan, tags: [brainstorm, …]) plus
+              needs_design/run_id; keeps its own sections and the required ## Design Summary
 ```
 
 ## Design Approval Gate

package/plugins/sp/skills/brainstorm/references/workflows.md

@@ -158,10 +158,25 @@ DO NOT implement research directly. Delegate to specialized skills:
 
 ### Output Template
 
+Frontmatter follows the spur-dev
+[document-authoring vocabulary](../../spur-dev/references/document-authoring.md#frontmatter-vocabulary);
+`needs_design` and `run_id` are brainstorm keys kept beside it. The body keeps this brainstorm shape,
+not the plan template's sections.
+
 ```markdown
-# Brainstorm: [Topic]
+---
+kind: plan
+title: "Brainstorm: [Topic]"
+status: proposed
+created_at: YYYY-MM-DD
+updated_at: YYYY-MM-DD
+related: []          # owning feature/task ids when known
+tags: [brainstorm]   # then feature ids, then ≤2 area tags
+needs_design: true
+run_id: <run id, omit when none>
+---
 
-**Date:** YYYY-MM-DD
+# Brainstorm: [Topic]
 
 ## Overview
 

package/plugins/sp/skills/code-verification/SKILL.md

@@ -261,8 +261,8 @@ the deterministic Testing writer `spur task record` (section authorship never ha
 # write .spur/run/<wbs>-verdict.json (shape in references/verdict-schema.md), then:
 # F96 residual sweep (observe-only): scan + fold BEFORE record, under every --fix mode.
 RESIDUAL=$(superskill script path sp residual-scan.mjs)
-node "$RESIDUAL" scan --wbs <wbs> --base .spur/run/<wbs>-base.sha
-node "$RESIDUAL" fold --wbs <wbs> --verdict .spur/run/<wbs>-verdict.json
+node "$RESIDUAL" scan <wbs>
+node "$RESIDUAL" fold <wbs>
 spur task record <wbs> --verdict-file .spur/run/<wbs>-verdict.json  # renders ## Testing
 ```
 

package/plugins/sp/skills/code-verification/references/secu-review.md

@@ -82,8 +82,9 @@ verdict artifact so quality failures are not lost behind a requirements-only PAS
 
 Before declaring a task `done`, run this lightweight checklist. It catches the most common oversights that survive the formal pipeline gates:
 
-- [ ] All tests pass (`bun run test` exits 0).
-- [ ] Lint clean (`bun run lint` exits 0).
+- [ ] Check receipt `.spur/run/<wbs>-check-receipt.json` reports `reuse: true` for the current
+      digest via `quality-gate.ts status`; run `bun run spur-check` only when it reports stale or
+      missing (0940).
 - [ ] No `TODO` or `FIXME` without a linked task WBS.
 - [ ] `git status` shows only intentional changes (no debug artifacts, no temp files).
 - [ ] No `console.log` / `console.error` in production code (use the project logger).

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

@@ -0,0 +1,112 @@
+---
+name: spur-check
+description: 'Two-tier check primitive for the sp pipeline: light (changed-scope biome, per-workspace typecheck, related tests) during development; full (bun run spur-check) once at the quality boundary. Reads/writes fingerprint-bound check receipts (.spur/run/<wbs>-check-receipt.json) and reuses a PASS full receipt only at the same proof digest.'
+license: Apache-2.0
+version: 1.0.0
+metadata:
+  author: spur
+  platforms: "claude-code,codex,openclaw,opencode,antigravity,pi"
+  category: check-execution
+  interactions:
+    - pipeline
+  operations:
+    - check
+    - accumulate
+    - reuse
+  openclaw:
+    emoji: "🧾"
+see_also:
+  - sp:spur-dev
+  - sp:spur-cli
+  - sp:code-verification
+---
+
+# sp:spur-check — the two-tier check primitive (ADR-124)
+
+One check primitive with two tiers behind the shipped `quality-gate` script
+([task 0939](../../../../docs/tasks5/0939_add-the-two-tier-spur-check-primitive-with-fingerprint-bound.md),
+[workflow catalogue refactor §4](../../../../docs/design/workflow-catalogue-refactor.md)): light
+checks accumulate during development, the full chain runs once at the quality boundary, and every
+gate writes a fingerprint-bound receipt that downstream stages read instead of re-running checks.
+
+## Tiers
+
+| Tier | Mode | When | Scope |
+| --- | --- | --- | --- |
+| `light` | `quality-gate.ts light` | after each implement/fix edit | `bunx biome check` on the changed files (`git diff --name-only HEAD` + untracked), `bun run typecheck` per touched workspace, and related tests (`<ws>/src/**/x.ts` → `<ws>/tests/**/x.test.ts` filename mapping) run via `cd <ws> && bun test …` — never from the repo root, whose bunfig preload does not apply inside the workspace |
+| `full` | `quality-gate.ts run` | once at the task quality boundary (`test`) | today's chain: `bun run lint` + `bun run test-pre-check` + `bun run test` + `bun run test-post-check` (=`bun run spur-check`), with bounded findings, SQLite-busy retry, and the `recheck` probe |
+
+Soft-fail contract: both tiers always exit 0; the verdict lives in files (`*-test-gate.status`,
+receipt `status`), never in the exit code.
+
+## Receipt
+
+`.spur/run/<wbs>-check-receipt.json`, schema `check-receipt/v1`:
+
+```json
+{
+  "schemaVersion": "check-receipt/v1",
+  "wbs": "0939",
+  "runId": "pipeline-0939",
+  "tier": "full",
+  "inputDigest": "<proof-input digest>",
+  "checks": [{ "id": "test", "cmd": "…", "status": "PASS", "durationMs": 0, "logPath": "…" }],
+  "status": "PASS",
+  "completedAt": "2026-09-25T00:00:00.000Z"
+}
+```
+
+- `inputDigest` is the shared `ProofInputFingerprint` (task markdown + git tree of tracked
+  sources). The plugin never computes it — the pipeline captures it with the `proof.fingerprint`
+  action into `env.proofDigest` (ADR-124: no second fingerprint, no `@gobing-ai/*` import);
+  standalone callers use `inline-run-setup.ts --fingerprint`.
+- Only `run`/`full` writes a reusable receipt. Without a digest, `run` writes no receipt and says
+  so in the gate log. The gate executes `qualityGateCmd` as one unit, so the full receipt carries a
+  single `test` row for the whole chain; `lint`, `typecheck`, `test-pre-check`,
+  `test-post-check` name the chain steps the full tier covers.
+- `light` merges its rows under `tier: light` and skips any sub-check already `PASS` in a light
+  receipt at the same `{id, inputDigest}` (accumulation). Light rows never make a receipt
+  reusable for review.
+
+## Reuse rule
+
+Check `status` mode before re-running a gate. Resolve the shipped script through the superskill
+runtime (shipped surfaces never hard-code repo paths):
+
+```bash
+QG="$(superskill script path sp quality-gate.mjs)"
+bun "$QG" status   # env: wbs, proofDigest → prints {"reuse":…,"reason":…}
+```
+
+`reuse: true` only when the receipt is `status: PASS`, `tier: full`, and `inputDigest` equals the
+current digest. Otherwise the reason is one of `missing | failed | stale | light-only`:
+
+- `missing` — no readable receipt (or foreign schema version)
+- `failed` — last full run failed
+- `stale` — digest mismatch (or no current digest supplied)
+- `light-only` — a valid PASS receipt that came from the light tier
+
+Only `full` may satisfy a review/verify/record boundary: "review only after a green full gate" is
+preserved by construction. `recheck` stays the no-progress probe path for fix loops.
+
+## Composition
+
+- **Pipeline:** `sp:spur-dev` runs `run` at `test` and `recheck` at `test-recheck`; light mode
+  belongs to implement/fix edits, not to the gate state.
+- **Fix loops:** `/sp:dev-fixall --gate-log` consumes `<wbs>-test-gate.log` (and the bounded
+  `<wbs>-test-gate.findings` anchors) after a red gate; it never writes receipts. A green fixall
+  output still requires a fresh `run` receipt before review.
+- **Verification:** `sp:code-verification` and the review checklists read the receipt (status
+  mode) instead of re-running `bun run test`.
+- **Feature scope:** `spur-check-feature` remains the ADR-119 repo-wide pass; this primitive is
+  task-local. A public `spur check` verb is out of scope without separate consent.
+
+## Gotchas
+
+1. **Never value-import `@gobing-ai/*` into the script** — the plugin standalone contract fails
+   the install; the digest arrives via `env.proofDigest`.
+2. **Never run light tests from the repo root** — the workspace `bunfig.toml` preload (coverage,
+   thresholds) only applies inside the workspace; `cd <ws> && bun test …` is the contract.
+3. **Light is a filter, not a boundary** — unmapped files (root-level scripts, non-src layouts)
+   are simply not covered by light; the full tier is the safety net. Do not widen the mapping
+   without an ADR.

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

@@ -116,7 +116,7 @@ reference for the half you're operating; do not duplicate its content here.
 | Feature check gate         | planning  | `spur feature check`                                                                      | [planning-workflow.md](references/planning-workflow.md)                                                                                 |
 | Decomposition (dispatch)   | planning  | `task-batch.schema.json`                                                                  | `sp:spec-decomposition` competency — the spine dispatches, does not inline                                                              |
 | Batch-create gate          | planning  | `spur task batch-create`                                                                  | [planning-workflow.md](references/planning-workflow.md)                                                                                 |
-| Design doc                 | planning  | — (prompt work; §4.5/T9)                                                                  | [planning-workflow.md](references/planning-workflow.md)                                                                                 |
+| Design doc | planning | — (§4.5/T9) | [document-authoring.md](references/document-authoring.md) |
 | Refine                     | planning  | `spur task update --section`                                                              | [planning-workflow.md](references/planning-workflow.md)                                                                                 |
 | Batch refine               | planning  | `sp:dev-refineall` → per-task `refine`                                                    | [dev-operations.md](references/dev-operations.md) § refineall · [planning-workflow.md](references/planning-workflow.md)                 |
 | Task selection             | execution | `spur task list`                                                                          | [execution-workflow.md](references/execution-workflow.md)                                                                               |
@@ -246,6 +246,7 @@ for "what's actually in file Y" or for resources that sit outside the step seque
 - `idea-pipeline.yaml` — the front-half state machine (absorbed the retired
   planning-pipeline in D5-K; `/sp:dev-plan` routes here, ADR-072).
 - `templates/bdd/gherkin.md` — the BDD scenario template.
+- `templates/plan.md` and `templates/design.md` — plan and design starting points.
 
 ## Platform Notes