@gobing-ai/spur 0.3.91 → 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/branch-workflow/SKILL.md

@@ -81,6 +81,7 @@ git push
 ```bash
 git branch -d feature/<slug>        # Delete merged branch
 git worktree remove ../<project>-feature-<slug>  # Remove worktree if used
+spur projects remove ../<project>-feature-<slug> 2>/dev/null || true # Deregister from projects.json if registered
 git worktree prune                  # Clean up stale worktree references
 ```
 

package/plugins/sp/skills/branch-workflow/references/worktree-patterns.md

@@ -46,6 +46,7 @@ Shows all worktrees with their branches and paths.
 
 ```bash
 git worktree remove ../project-hotfix
+spur projects remove ../project-hotfix 2>/dev/null || true
 ```
 
 ### Prune (clean up stale references)
@@ -83,6 +84,7 @@ After removing a worktree, run `git worktree prune` and `git gc` to reclaim spac
 
 ```bash
 git worktree remove ../old-worktree
+spur projects remove ../old-worktree 2>/dev/null || true
 git worktree prune
 git gc --aggressive
 ```

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

@@ -52,6 +52,23 @@ When this skill is entered via `/sp:dev-run --mode implement <wbs>` (the form
 The structural guard is the slash form itself (`--mode implement`). Prose in the workflow YAML
 `agent.run` `input` is the wrong place for this rule; it belongs here and in `dev-run.md`.
 
+## Escalation contract (task 0933, implement step only)
+
+When the pipeline runs implement headless, you have a bounded channel to surface a question
+instead of guessing. The rules, in decision order:
+
+- **Decide without asking** when the answer follows from the task's frozen Design /
+  Requirements / Q&A, the project and global instructions, or the codebase itself. Ambiguity
+  you can resolve from evidence is not a question.
+- **Escalate only when a requirement or design ambiguity would change scope, correctness, or
+  authorization.** Style preferences, implementation details, and curiosity are not escalations.
+- **To escalate:** write ONE concise question — with options and a recommendation — to the
+  escalation file, then exit 0 **without further edits**. The pipeline pauses the run and an
+  operator answers; the transcript of prior Q/A pairs lives at the `--escalation-file` path
+  (the ask loop is bounded, default 2 — a third pause fails the task).
+- **Read `--escalation-file` if it exists and treat its answers as binding.** They are the
+  operator's recorded decisions for this pass, not suggestions.
+
 ## One WBS per implement pass (task 0487 R1)
 
 The target WBS is the **only** task you implement. Sibling tasks in the corpus are context you do

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

@@ -259,13 +259,34 @@ the deterministic Testing writer `spur task record` (section authorship never ha
 
 ```bash
 # 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>
+node "$RESIDUAL" fold <wbs>
 spur task record <wbs> --verdict-file .spur/run/<wbs>-verdict.json  # renders ## Testing
 ```
 
+> **Residual fold (F96).** `scan` reads `.spur/run/` artifacts and writes `residuals.json` +
+> `residual-report.md`; `fold` rewrites the **just-written** verdict artifact's `residual-sweep`
+> check in place (PASS → PARTIAL when a blocking residual exists), so `record` transcribes the
+> downgraded verdict — a manual verify cannot certify what the pipeline would reject. Resolve the
+> script via `superskill script path sp residual-scan.mjs`; shipped surfaces never reference
+> `plugins/sp/scripts/` directly (script-contract-check rule 4). When the task reaches `done`
+> through `--next`, run `residual-scan settle` (links follow-up tasks; best-effort).
+
 > **Corrections: the answer file is the source of truth.** `spur task record` re-transcribes
 > `## Testing` from the verdict artifact — direct `--section Testing` writes are futile. Fix
 > `.spur/run/<wbs>-verify-answer.txt` → `spur task verdict <wbs> --from-answer <file>` → re-record.
 
+> **Scenario-key carry-forward (standalone `--force` re-verifies).** When you author a fresh
+> verdict artifact for a task whose `## Testing` already carries feature scenario-title rows
+> (`Scenario: <title>` / `AC-N` keys with MET status), **copy those rows into the new artifact**
+> keyed the same way — record re-transcribes `## Testing` wholesale, so a fresh artifact keyed by
+> bare `R1`-style ids drops the scenario keys `spur feature check` needs for satisfaction
+> (`L4.scenario-unverified` regresses; 0921/D63). Since 0936, `record` warns on stderr (exit 0)
+> for each dropped MET-matched scenario key and when the new rows match no feature scenario —
+> treat those warnings as a re-key instruction, not noise.
+
 > **Do not write `## Review` directly, ever.** The `## Review` section is owned by the
 > `review` coordinator (`/sp:dev-review` → `sp:super-reviewer`), which merges
 > `functional-review` + `code-verification` review mode + `code-improvement` fragments. The

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/code-verification/references/verdict-schema.md

@@ -136,6 +136,7 @@ Wave C verification can emit the following additive `checks[]` rows:
 | `evidence-rule-pass` | All behavior-bearing AC rows had executable evidence or were explicitly non-behavioral. |
 | `evidence-rule-failed` | One or more MET behavior-bearing AC rows lacked `test` / `command` evidence and were downgraded to PARTIAL. |
 | `cli-golden-path-present` | CLI-surface tasks supplied, or failed to supply, one golden-path command evidence row. |
+| `residual-sweep` | Post-verdict residual scan (F96): `fail` when blocking leftovers exist (P1–P3 findings, added diff markers, unchecked boxes); evidence lists blocking/deferrable/advisory/housekeeping counts plus blocking and deferrable item ids. A `fail` downgrades an otherwise-PASS verdict to PARTIAL via the fold step. |
 
 ## How the gate reads it
 

package/plugins/sp/skills/dogfood-testing/SKILL.md

@@ -194,8 +194,9 @@ On **every** step resolve:
 
 The final report MUST include a `### 3. Monitor Ledger` section containing those rows (cardinality:
 row count == the declared executed steps). Cardinality, full methodology, column contract,
-token/cache estimation, multi-source Cost honesty, the cache-health finding rule, and the
-**cache-conservation discipline** live in
+token/context-reuse estimation, multi-source Cost honesty, the evidence-based reuse and
+pipeline-provenance observation rules (supported 0912 baseline findings, owner handoffs,
+INSUFFICIENT_EVIDENCE limits — task 0913), and the **cache-conservation discipline** live in
 **[monitor-ledger.md](references/monitor-ledger.md)** — apply conservation while monitoring; low
 cache% is usually the driver re-fetching data it already holds.
 
@@ -532,7 +533,8 @@ Do NOT:
 - [references/report-template.md](references/report-template.md) — report section contract,
   mandatory footer, task-sink L3 rule.
 - [references/monitor-ledger.md](references/monitor-ledger.md) — live-ledger column contract,
-  token/cache estimation, cache-health finding rule.
+  token/context-reuse estimation, evidence-based reuse observation rule, pipeline-run provenance
+  observation rules.
 
 ## Platform Notes