@gobing-ai/spur 0.3.99 → 0.4.1

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

@@ -443,7 +443,137 @@ function runFeatureTransition(env, options = {}) {
 `);
   return { status: syncStatus, statusFile: relStatusFile, exitCode: 0 };
 }
-var WRAPUP_STEPS_USAGE = "usage: wrapup-steps.ts <resolve|route-reason|metrics|feature-transition>  (env: __runId, tasks, mode, feature, featureGateCmd, spurBin)";
+var DOC_SYNC_SNAPSHOT_SUFFIX = "wrapup-doc-sync-snapshot.txt";
+var DOC_SYNC_SCOPE_STATUS_SUFFIX = "wrapup-doc-sync-scope.status";
+var DOC_SYNC_SUPERSESSION_STATUS_SUFFIX = "wrapup-doc-supersession.status";
+var SUPERSESSION_PIN = "repo-wide-tests/adr-supersession.test.ts";
+var GIT_UNAVAILABLE_MARKER = "# git-unavailable:";
+var SNAPSHOT_MISSING = "snapshot-missing";
+function porcelainPath(line) {
+  const body = line.length >= 3 ? line.slice(3) : line;
+  const arrow = body.indexOf(" -> ");
+  const target = arrow >= 0 ? body.slice(arrow + 4) : body;
+  const trimmed = target.trim();
+  return trimmed.startsWith('"') && trimmed.endsWith('"') && trimmed.length >= 2 ? trimmed.slice(1, -1) : trimmed;
+}
+function isDocSyncAllowedPath(path, allowedExtra) {
+  if (allowedExtra.includes(path))
+    return true;
+  if (!path.startsWith("docs/"))
+    return false;
+  return !path.startsWith("docs/tasks") && !path.startsWith("docs/features");
+}
+function docSyncScopeViolations(snapshot, current, allowedExtra) {
+  const before = new Set(snapshot.split(`
+`).filter((line) => line.trim() !== ""));
+  const paths = new Set;
+  for (const line of current.split(`
+`)) {
+    if (line.trim() === "" || before.has(line))
+      continue;
+    const path = porcelainPath(line);
+    if (!isDocSyncAllowedPath(path, allowedExtra))
+      paths.add(path);
+  }
+  return [...paths].sort();
+}
+function gitPorcelain(cwd) {
+  const result = spawnSync("git", ["status", "--porcelain", "-uall"], {
+    cwd,
+    encoding: "utf8"
+  });
+  if (result.error !== undefined)
+    return { ok: false, listing: "", detail: String(result.error) };
+  if (result.status !== 0)
+    return { ok: false, listing: "", detail: (result.stderr ?? "").trim() };
+  return { ok: true, listing: result.stdout ?? "", detail: "" };
+}
+function wrapupRunPaths(env, cwd) {
+  const runId = env.__runId ?? "";
+  const rel = (suffix) => join(".spur", "run", `${runId}-${suffix}`);
+  return { rel, abs: (suffix) => cwd ? join(cwd, rel(suffix)) : rel(suffix) };
+}
+function docSyncAllowedExtra(env) {
+  const runId = env.__runId ?? "";
+  return [
+    join(".spur", "run", `${runId}-wrapup-learnings.md`),
+    join(".spur", "run", `${runId}-${DOC_SYNC_SNAPSHOT_SUFFIX}`),
+    join(".spur", "run", `${runId}-${DOC_SYNC_SCOPE_STATUS_SUFFIX}`)
+  ];
+}
+function runDocSyncSnapshot(env, options = {}) {
+  const cwd = options.cwd;
+  const paths = wrapupRunPaths(env, cwd);
+  mkdirSync(cwd ? join(cwd, ".spur", "run") : join(".spur", "run"), { recursive: true });
+  writeFileSync(paths.abs(DOC_SYNC_SNAPSHOT_SUFFIX), "");
+  const listing = gitPorcelain(cwd);
+  if (!listing.ok) {
+    writeFileSync(paths.abs(DOC_SYNC_SNAPSHOT_SUFFIX), `${GIT_UNAVAILABLE_MARKER} ${listing.detail}
+`);
+    process.stderr.write(`doc-sync-snapshot: git status unavailable \u2014 scope check skips (${listing.detail})
+`);
+    return { statusFile: paths.rel(DOC_SYNC_SNAPSHOT_SUFFIX), captured: false, exitCode: 0 };
+  }
+  writeFileSync(paths.abs(DOC_SYNC_SNAPSHOT_SUFFIX), listing.listing);
+  return { statusFile: paths.rel(DOC_SYNC_SNAPSHOT_SUFFIX), captured: true, exitCode: 0 };
+}
+function runDocSyncScope(env, options = {}) {
+  const cwd = options.cwd;
+  const paths = wrapupRunPaths(env, cwd);
+  mkdirSync(cwd ? join(cwd, ".spur", "run") : join(".spur", "run"), { recursive: true });
+  const statusFile = paths.rel(DOC_SYNC_SCOPE_STATUS_SUFFIX);
+  const write = (status, detail) => {
+    writeFileSync(paths.abs(DOC_SYNC_SCOPE_STATUS_SUFFIX), `${detail}
+`);
+    if (status !== "PASS")
+      process.stderr.write(`doc-sync-scope: ${detail}
+`);
+    return { status, statusFile, violations: status === "PASS" ? [] : [detail], exitCode: 0 };
+  };
+  const snapshot = readFileSyncSafe(paths.abs(DOC_SYNC_SNAPSHOT_SUFFIX));
+  if (snapshot === null) {
+    return write("scope-violation", `scope-violation: ${SNAPSHOT_MISSING}`);
+  }
+  if (snapshot.startsWith(GIT_UNAVAILABLE_MARKER)) {
+    process.stderr.write(`doc-sync-scope: entry snapshot recorded no git listing \u2014 scope check skipped
+`);
+    return write("PASS", "PASS");
+  }
+  const current = gitPorcelain(cwd);
+  if (!current.ok) {
+    return write("scope-violation", `scope-violation: git-unavailable (${current.detail})`);
+  }
+  const violations = docSyncScopeViolations(snapshot, current.listing, docSyncAllowedExtra(env));
+  if (violations.length === 0)
+    return write("PASS", "PASS");
+  return write("scope-violation", `scope-violation: ${violations.join(" ")}`);
+}
+function runDocSupersessionCheck(env, options = {}) {
+  const cwd = options.cwd;
+  const paths = wrapupRunPaths(env, cwd);
+  mkdirSync(cwd ? join(cwd, ".spur", "run") : join(".spur", "run"), { recursive: true });
+  const statusFile = paths.rel(DOC_SYNC_SUPERSESSION_STATUS_SUFFIX);
+  const pinPath = cwd ? join(cwd, SUPERSESSION_PIN) : SUPERSESSION_PIN;
+  if (!existsSync(pinPath)) {
+    writeFileSync(paths.abs(DOC_SYNC_SUPERSESSION_STATUS_SUFFIX), `PASS
+`);
+    return { status: "PASS", statusFile, exitCode: 0 };
+  }
+  const pin = spawnSync("bun", ["test", SUPERSESSION_PIN], { cwd, encoding: "utf8" });
+  if (pin.status === 0) {
+    writeFileSync(paths.abs(DOC_SYNC_SUPERSESSION_STATUS_SUFFIX), `PASS
+`);
+    return { status: "PASS", statusFile, exitCode: 0 };
+  }
+  writeFileSync(paths.abs(DOC_SYNC_SUPERSESSION_STATUS_SUFFIX), `supersession-pin-failed: ${SUPERSESSION_PIN}
+`);
+  const detail = `${pin.stdout ?? ""}${pin.stderr ?? ""}`.trim();
+  process.stderr.write(`doc-supersession: ${SUPERSESSION_PIN} failed (exit ${String(pin.status ?? 1)}) \u2014 the doc-sync step introduced or kept superseded index content:
+${detail.slice(-2000)}
+`);
+  return { status: "supersession-pin-failed", statusFile, exitCode: 0 };
+}
+var WRAPUP_STEPS_USAGE = "usage: wrapup-steps.ts <resolve|route-reason|metrics|feature-transition|doc-sync-snapshot|doc-sync-scope|doc-supersession>  (env: __runId, tasks, mode, feature, featureGateCmd, spurBin)";
 function main(argv, env = getEnvVars(), options = {}) {
   const sub = argv[0];
   if (sub === "resolve")
@@ -456,6 +586,12 @@ function main(argv, env = getEnvVars(), options = {}) {
   }
   if (sub === "feature-transition")
     return runFeatureTransition(env, options).exitCode;
+  if (sub === "doc-sync-snapshot")
+    return runDocSyncSnapshot(env, options).exitCode;
+  if (sub === "doc-sync-scope")
+    return runDocSyncScope(env, options).exitCode;
+  if (sub === "doc-supersession")
+    return runDocSupersessionCheck(env, options).exitCode;
   process.stderr.write(`${WRAPUP_STEPS_USAGE}
 `);
   return 2;
@@ -469,11 +605,23 @@ export {
   taskStatusOf,
   runMetrics,
   runFeatureTransition,
+  runDocSyncSnapshot,
+  runDocSyncScope,
+  runDocSupersessionCheck,
   resolveTasks,
   preflightFeature,
+  porcelainPath,
   main,
   jqPick,
+  isDocSyncAllowedPath,
+  docSyncScopeViolations,
   classifySync,
   WRAPUP_STEPS_USAGE,
-  WBS_PATTERN
+  WBS_PATTERN,
+  SUPERSESSION_PIN,
+  SNAPSHOT_MISSING,
+  GIT_UNAVAILABLE_MARKER,
+  DOC_SYNC_SUPERSESSION_STATUS_SUFFIX,
+  DOC_SYNC_SNAPSHOT_SUFFIX,
+  DOC_SYNC_SCOPE_STATUS_SUFFIX
 };

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

@@ -14,6 +14,9 @@
  *   - `.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)
+ *   - `<runId>-wrapup-doc-sync-snapshot.txt`  working listing at doc-sync entry (doc-sync-snapshot)
+ *   - `<runId>-wrapup-doc-sync-scope.status`  `PASS`/`scope-violation: <paths>` (doc-sync-scope)
+ *   - `<runId>-wrapup-doc-supersession.status` `PASS`/`supersession-pin-failed: <pin>` (doc-supersession)
  *
  * Environment comes from the workflow vars: `__runId`, `tasks`, `feature`, `featureGateCmd`
  * and `spurBin` (split on whitespace into a command plus prefix args, so
@@ -668,8 +671,204 @@ export function runFeatureTransition(env: WrapupStepsEnv, options: WrapupStepsOp
     return { status: syncStatus, statusFile: relStatusFile, exitCode: 0 };
 }
 
+/** Run-scoped snapshot of the working listing taken at doc-sync entry (1147 R1). */
+export const DOC_SYNC_SNAPSHOT_SUFFIX = 'wrapup-doc-sync-snapshot.txt';
+/** Run-scoped verdict of the post-doc-sync write-scope check (1147 R1). */
+export const DOC_SYNC_SCOPE_STATUS_SUFFIX = 'wrapup-doc-sync-scope.status';
+/** Run-scoped verdict of the post-doc-sync supersession-pin re-run (1147 R2). */
+export const DOC_SYNC_SUPERSESSION_STATUS_SUFFIX = 'wrapup-doc-supersession.status';
+/**
+ * The supersession pins doc-sync must not resurrect (1147 R2). Re-run right after doc-sync so a
+ * re-added delinked index row is attributed to doc-sync instead of to the later `doc-tripwire`
+ * backstop, which stays unchanged.
+ */
+export const SUPERSESSION_PIN = 'repo-wide-tests/adr-supersession.test.ts';
+/** Snapshot marker for "git could not list the tree" — the check then skips instead of guessing. */
+export const GIT_UNAVAILABLE_MARKER = '# git-unavailable:';
+
+/** Snapshot marker the scope check reports when doc-sync's entry snapshot is absent (fail closed). */
+export const SNAPSHOT_MISSING = 'snapshot-missing';
+
+/**
+ * One `git status --porcelain` line → the repo-relative path it names. A rename/copy line
+ * (`R  old -> new`) reports its target, and a quoted path is unquoted (1147 R1).
+ */
+export function porcelainPath(line: string): string {
+    const body = line.length >= 3 ? line.slice(3) : line;
+    const arrow = body.indexOf(' -> ');
+    const target = arrow >= 0 ? body.slice(arrow + 4) : body;
+    const trimmed = target.trim();
+    return trimmed.startsWith('"') && trimmed.endsWith('"') && trimmed.length >= 2 ? trimmed.slice(1, -1) : trimmed;
+}
+
+/**
+ * doc-sync's declared write scope (1147 R1): `docs/**` except the task/feature corpus, the
+ * learnings capture the step declares, and the guard's own snapshot/status bookkeeping (never
+ * doc-sync edits, and present in the listing on a repeated check).
+ */
+export function isDocSyncAllowedPath(path: string, allowedExtra: readonly string[]): boolean {
+    if (allowedExtra.includes(path)) return true;
+    if (!path.startsWith('docs/')) return false;
+    return !path.startsWith('docs/tasks') && !path.startsWith('docs/features');
+}
+
+/**
+ * Paths doc-sync newly dirtied: the current porcelain listing minus the entry snapshot's lines.
+ * A line present in both listings is pre-existing dirt (a sibling task's uncommitted work) and is
+ * never attributed to this pass (1147 R1).
+ */
+export function docSyncScopeViolations(snapshot: string, current: string, allowedExtra: readonly string[]): string[] {
+    const before = new Set(snapshot.split('\n').filter((line) => line.trim() !== ''));
+    const paths = new Set<string>();
+    for (const line of current.split('\n')) {
+        if (line.trim() === '' || before.has(line)) continue;
+        const path = porcelainPath(line);
+        if (!isDocSyncAllowedPath(path, allowedExtra)) paths.add(path);
+    }
+    return [...paths].sort();
+}
+
+/** `git status --porcelain -uall` — the listing both the snapshot and the scope check compare. */
+function gitPorcelain(cwd?: string): { ok: boolean; listing: string; detail: string } {
+    const result = spawnSync('git', ['status', '--porcelain', '-uall'], {
+        cwd,
+        encoding: 'utf8',
+    });
+    if (result.error !== undefined) return { ok: false, listing: '', detail: String(result.error) };
+    if (result.status !== 0) return { ok: false, listing: '', detail: (result.stderr ?? '').trim() };
+    return { ok: true, listing: result.stdout ?? '', detail: '' };
+}
+
+interface WrapupRunPaths {
+    rel: (suffix: string) => string;
+    abs: (suffix: string) => string;
+}
+
+function wrapupRunPaths(env: WrapupStepsEnv, cwd?: string): WrapupRunPaths {
+    const runId = env.__runId ?? '';
+    const rel = (suffix: string): string => join('.spur', 'run', `${runId}-${suffix}`);
+    return { rel, abs: (suffix: string) => (cwd ? join(cwd, rel(suffix)) : rel(suffix)) };
+}
+
+/** The four path shapes this check knows are not doc-sync edits (1147 R1). */
+function docSyncAllowedExtra(env: WrapupStepsEnv): string[] {
+    const runId = env.__runId ?? '';
+    return [
+        join('.spur', 'run', `${runId}-wrapup-learnings.md`),
+        join('.spur', 'run', `${runId}-${DOC_SYNC_SNAPSHOT_SUFFIX}`),
+        join('.spur', 'run', `${runId}-${DOC_SYNC_SCOPE_STATUS_SUFFIX}`),
+    ];
+}
+
+/** Outcome of `doc-sync-snapshot`: the recorded entry listing (or a git-unavailable marker). */
+export interface DocSyncSnapshotResult {
+    statusFile: string;
+    /** True when the listing was captured; false when git could not list the tree. */
+    captured: boolean;
+    exitCode: number;
+}
+
+/**
+ * `doc-sync-snapshot` — record the working listing at doc-sync entry (1147 R1), before the model
+ * query runs, so the post-doc-sync check can attribute only this step's writes. Never aborts: a
+ * git failure is recorded in the snapshot (the check then skips rather than guessing).
+ */
+export function runDocSyncSnapshot(env: WrapupStepsEnv, options: WrapupStepsOptions = {}): DocSyncSnapshotResult {
+    const cwd = options.cwd;
+    const paths = wrapupRunPaths(env, cwd);
+    mkdirSync(cwd ? join(cwd, '.spur', 'run') : join('.spur', 'run'), { recursive: true });
+    // Create the file BEFORE listing so it is present in both listings (never a false violation).
+    writeFileSync(paths.abs(DOC_SYNC_SNAPSHOT_SUFFIX), '');
+    const listing = gitPorcelain(cwd);
+    if (!listing.ok) {
+        writeFileSync(paths.abs(DOC_SYNC_SNAPSHOT_SUFFIX), `${GIT_UNAVAILABLE_MARKER} ${listing.detail}\n`);
+        process.stderr.write(`doc-sync-snapshot: git status unavailable — scope check skips (${listing.detail})\n`);
+        return { statusFile: paths.rel(DOC_SYNC_SNAPSHOT_SUFFIX), captured: false, exitCode: 0 };
+    }
+    writeFileSync(paths.abs(DOC_SYNC_SNAPSHOT_SUFFIX), listing.listing);
+    return { statusFile: paths.rel(DOC_SYNC_SNAPSHOT_SUFFIX), captured: true, exitCode: 0 };
+}
+
+/** Outcome of `doc-sync-scope`: the recorded verdict plus the offending paths it named. */
+export interface DocSyncScopeResult {
+    status: 'PASS' | 'scope-violation';
+    statusFile: string;
+    violations: string[];
+    exitCode: number;
+}
+
+/**
+ * `doc-sync-scope` — the deterministic write-scope guard (1147 R1): diff the working listing
+ * against the entry snapshot and fail the step on any path outside the declared scope. The
+ * violating edits are reported, never reverted (the operator decides); the verdict lives in the
+ * status file so the workflow guard routes on it.
+ */
+export function runDocSyncScope(env: WrapupStepsEnv, options: WrapupStepsOptions = {}): DocSyncScopeResult {
+    const cwd = options.cwd;
+    const paths = wrapupRunPaths(env, cwd);
+    mkdirSync(cwd ? join(cwd, '.spur', 'run') : join('.spur', 'run'), { recursive: true });
+    const statusFile = paths.rel(DOC_SYNC_SCOPE_STATUS_SUFFIX);
+    const write = (status: DocSyncScopeResult['status'], detail: string): DocSyncScopeResult => {
+        writeFileSync(paths.abs(DOC_SYNC_SCOPE_STATUS_SUFFIX), `${detail}\n`);
+        if (status !== 'PASS') process.stderr.write(`doc-sync-scope: ${detail}\n`);
+        return { status, statusFile, violations: status === 'PASS' ? [] : [detail], exitCode: 0 };
+    };
+
+    const snapshot = readFileSyncSafe(paths.abs(DOC_SYNC_SNAPSHOT_SUFFIX));
+    if (snapshot === null) {
+        return write('scope-violation', `scope-violation: ${SNAPSHOT_MISSING}`);
+    }
+    if (snapshot.startsWith(GIT_UNAVAILABLE_MARKER)) {
+        process.stderr.write('doc-sync-scope: entry snapshot recorded no git listing — scope check skipped\n');
+        return write('PASS', 'PASS');
+    }
+    const current = gitPorcelain(cwd);
+    if (!current.ok) {
+        return write('scope-violation', `scope-violation: git-unavailable (${current.detail})`);
+    }
+    const violations = docSyncScopeViolations(snapshot, current.listing, docSyncAllowedExtra(env));
+    if (violations.length === 0) return write('PASS', 'PASS');
+    return write('scope-violation', `scope-violation: ${violations.join(' ')}`);
+}
+
+/** Outcome of `doc-supersession`: the recorded verdict of the supersession-pin re-run. */
+export interface DocSupersessionResult {
+    status: 'PASS' | 'supersession-pin-failed';
+    statusFile: string;
+    exitCode: number;
+}
+
+/**
+ * `doc-supersession` — re-run the supersession pins right after doc-sync (1147 R2). A doc-sync
+ * that resurrects a deliberately delinked index row fails HERE, named with the pin, instead of at
+ * the later repo-wide `doc-tripwire` backstop (which is never weakened). A project without the pin
+ * skips: this check must stay inert outside the spur source repo.
+ */
+export function runDocSupersessionCheck(env: WrapupStepsEnv, options: WrapupStepsOptions = {}): DocSupersessionResult {
+    const cwd = options.cwd;
+    const paths = wrapupRunPaths(env, cwd);
+    mkdirSync(cwd ? join(cwd, '.spur', 'run') : join('.spur', 'run'), { recursive: true });
+    const statusFile = paths.rel(DOC_SYNC_SUPERSESSION_STATUS_SUFFIX);
+    const pinPath = cwd ? join(cwd, SUPERSESSION_PIN) : SUPERSESSION_PIN;
+    if (!existsSync(pinPath)) {
+        writeFileSync(paths.abs(DOC_SYNC_SUPERSESSION_STATUS_SUFFIX), 'PASS\n');
+        return { status: 'PASS', statusFile, exitCode: 0 };
+    }
+    const pin = spawnSync('bun', ['test', SUPERSESSION_PIN], { cwd, encoding: 'utf8' });
+    if (pin.status === 0) {
+        writeFileSync(paths.abs(DOC_SYNC_SUPERSESSION_STATUS_SUFFIX), 'PASS\n');
+        return { status: 'PASS', statusFile, exitCode: 0 };
+    }
+    writeFileSync(paths.abs(DOC_SYNC_SUPERSESSION_STATUS_SUFFIX), `supersession-pin-failed: ${SUPERSESSION_PIN}\n`);
+    const detail = `${pin.stdout ?? ''}${pin.stderr ?? ''}`.trim();
+    process.stderr.write(
+        `doc-supersession: ${SUPERSESSION_PIN} failed (exit ${String(pin.status ?? 1)}) — the doc-sync step introduced or kept superseded index content:\n${detail.slice(-2000)}\n`,
+    );
+    return { status: 'supersession-pin-failed', statusFile, exitCode: 0 };
+}
+
 export const WRAPUP_STEPS_USAGE =
-    'usage: wrapup-steps.ts <resolve|route-reason|metrics|feature-transition>  (env: __runId, tasks, mode, feature, featureGateCmd, spurBin)';
+    'usage: wrapup-steps.ts <resolve|route-reason|metrics|feature-transition|doc-sync-snapshot|doc-sync-scope|doc-supersession>  (env: __runId, tasks, mode, feature, featureGateCmd, spurBin)';
 
 export function main(argv: string[], env: WrapupStepsEnv = getEnvVars(), options: WrapupStepsOptions = {}): number {
     const sub = argv[0];
@@ -680,6 +879,9 @@ export function main(argv: string[], env: WrapupStepsEnv = getEnvVars(), options
         return 0;
     }
     if (sub === 'feature-transition') return runFeatureTransition(env, options).exitCode;
+    if (sub === 'doc-sync-snapshot') return runDocSyncSnapshot(env, options).exitCode;
+    if (sub === 'doc-sync-scope') return runDocSyncScope(env, options).exitCode;
+    if (sub === 'doc-supersession') return runDocSupersessionCheck(env, options).exitCode;
     process.stderr.write(`${WRAPUP_STEPS_USAGE}\n`);
     return 2;
 }

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

@@ -26,7 +26,6 @@ metadata:
 see_also:
   - sp:source-driven-development
   - sp:spur-cli
-  - sp:wayfinder
 ---
 
 # sp:brainstorm — Structured Ideation Workflow
@@ -35,7 +34,6 @@ Generate solution options with trade-offs, recommendations, and confidence scori
 
 **Key distinction:**
 - **`sp:brainstorm`** = Ideation: generate approaches with trade-offs
-- **`sp:wayfinder`** = Wayfinding: chart a multi-session map when the destination itself is foggy
 - **research** = verify and synthesize information (delegate inline by default — see [inline-default contract](../spur-dev/references/cross-cutting.md#inline-default-execution-surface))
 - **`sp:spur-dev`** = Task creation: structured task breakdown (planning half)
 - **`sp:source-driven-development`** = Verification: source-first claim validation
@@ -65,14 +63,13 @@ Activate sp:brainstorm when:
 | "research approaches" | User wants evidence-backed options |
 | "what are my options?" | User wants multiple solutions |
 | "how should I approach X?" | User wants recommendation with reasoning |
-| "wayfind" / "chart a course" | User needs a multi-session investigation map — escalate to `sp:wayfinder` (Phase 2) |
 
 **NOT for:**
 - Pure research (delegate to research skills inline by default; escalate via `spur agent run` only on a subprocess trigger)
 - Task creation without ideation (use `sp:spur-dev` instead)
 - Fact-checking or verification only (use `sp:source-driven-development` instead)
 - Task file operations (use `sp:spur-cli` instead)
-- Multi-session investigation when the destination itself is foggy (use `sp:wayfinder` instead)
+- Multi-session investigation when the destination itself is foggy (recommend `/sp:dev-find-way`; see [Scope Check](#scope-check-end-of-phase-1))
 
 ## Core Principles
 
@@ -317,51 +314,16 @@ non-deterministic intent into a reliable sequence, not bare forwarders (ADR-016)
 
 ---
 
-## Wayfinding Escalation (Phase 2)
+## Scope Check (end of Phase 1)
 
-When the discovery interview (Phase 1 of `/sp:dev-brainstorm`) surfaces that **the destination itself is foggy** — the spec can't be written in one session because too many decisions are unresolved — brainstorm escalates to `sp:wayfinder` instead of proceeding to ideation.
+Before ideation, ask: **"Can this be spec'd in one session, or is the destination itself still foggy?"**
 
-### Scope Check
-
-At the end of Phase 1, before ideation begins, run this scope check:
-
-> **"Can this be spec'd in one session, or is the destination itself still foggy?"**
-
-**Signals that wayfinding is needed:**
-- The topic touches ≥3 subsystems or unknown boundaries
-- Key decisions depend on research not yet done
-- The operator can describe the goal but not the shape of the solution
-- Multiple "it depends" answers in the discovery interview
-- The operator uses fog language: "I'm not sure yet", "we need to explore", "it depends on what we find"
-
-**Signals that standard ideation suffices:**
-- The destination is clear; only the approach is in question
-- All key decisions can be made from existing knowledge
-- The operator can enumerate the constraints and trade-offs
-
-### Escalation Path
-
-When the scope check indicates a foggy destination, offer the escalation:
-
-> *"This is a multi-session investigation. Want me to chart a wayfinder map so we can work through it one decision at a time?"*
-
-The operator **confirms** before wayfinding begins — never silently escalate. A 30-minute quick-answer need might touch a big domain without requiring a multi-session map.
-
-On confirmation, delegate to `sp:wayfinder` for the "Chart the map" mode. The resolved decision tree from Phase 1 seeds the map's **## Notes** and initial **## Not yet specified** sections.
-
-### `--wayfind` Flag
-
-When `/sp:dev-brainstorm` is invoked with `--wayfind`, the scope check is **skipped** — the operator has pre-approved the escalation. After the discovery interview, proceed directly to `sp:wayfinder` charting without the confirmation prompt.
-
-Use `--wayfind` when:
-- The operator already knows this is a multi-session investigation
-- A previous session recommended wayfinding
-- The topic is explicitly exploratory ("explore the solution space for X")
-
-### Integration with the Design Approval Gate
-
-A wayfinding escalation **replaces** the standard ideation output. The map feature (with its destination, notes, fog, and child tickets) is the artifact. The `needs_design` signal is not emitted — wayfinding defers design until the route to the destination is clear. When the last ticket resolves, the final session hands off to standard `sp:brainstorm` → `sp:spec-decomposition` with a now-clear destination.
+Fog signals: the topic touches ≥3 subsystems or unknown boundaries; key decisions depend on research
+not yet done; the operator can name the goal but not the solution's shape; repeated "it depends"
+answers. When they dominate, **stop** — do not ideate toward a destination that isn't there. Report
+the resolved decision tree and recommend `/sp:dev-find-way "<topic>"`, which owns multi-session
+investigation maps. Brainstorm never charts a map itself.
 
 ---
 
-**Remember:** Ideation ≠ Research. Generate approaches with trade-offs. Delegate verification to `sp:source-driven-development`. Delegate synthesis/research inline (escalate to `spur agent run` only on a subprocess trigger). Delegate task creation to `sp:spur-dev`. When the destination itself is foggy, escalate to `sp:wayfinder` — never force a spec that isn't ready.
+**Remember:** Ideation ≠ Research. Generate approaches with trade-offs. Delegate verification to `sp:source-driven-development`. Delegate synthesis/research inline (escalate to `spur agent run` only on a subprocess trigger). Delegate task creation to `sp:spur-dev`. When the destination itself is foggy, stop and recommend `/sp:dev-find-way` — never force a spec that isn't ready.

package/plugins/sp/skills/branch-workflow/SKILL.md

@@ -40,6 +40,7 @@ A git worktree gives you an isolated working directory for a branch without stas
 ```bash
 git worktree add ../<project>-<branch> <branch>
 cd ../<project>-<branch>
+spur projects add . 2>/dev/null || true   # Register in projects.json for the Board project switcher
 ```
 
 **When to use worktrees:**

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

@@ -28,6 +28,7 @@ A git worktree gives you an isolated working directory linked to the same reposi
 ```bash
 git worktree add ../project-hotfix hotfix/critical-fix
 cd ../project-hotfix && bun install --frozen-lockfile
+spur projects add . 2>/dev/null || true   # list it in the Board project switcher
 ```
 
 The worktree directory is created alongside the main project. Name it `<project>-<branch>` for clarity.

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

@@ -104,6 +104,13 @@ only burns wall clock and context budget.
 
 - **Run only targeted probes** to validate your changes: `bun test <file>`,
   `bun test <file> --test-name-pattern "<test>"`, or `bunx tsc --noEmit` on a single package.
+- **Run Spur through this tree's own entry point, never a bare `spur` (task 1110 R2).** Use the
+  invocation the pipeline supplies (`${vars.spurBin}`, e.g. `bun apps/cli/src/index.ts`) from the
+  execution tree — a bare `spur` on `PATH` resolves to the published bundle in `~/.bun/bin` or
+  `~/node_modules`, so a guard, a `task check` or a `task record` silently runs a different build
+  against a different tree. Same rule for the working directory: each shell call starts fresh, so
+  re-select the execution tree inside the call (`cd -- "$TREE"` plus the identity check) instead of
+  relying on a `cd` a previous call left behind.
 - **NEVER run** `bun run test`, `bun run spur-check`, `bun run check`, or any other full-suite /
   project-gate command from inside implement. These belong to the pipeline's `test` hop.
 - **Full-suite budget: at most 2 per task** (task 0436 R2) — counted across the whole task run
@@ -117,7 +124,35 @@ only burns wall clock and context budget.
 - If a targeted probe reveals a failure you cannot fix within implement scope, note it in
   `## Solution` and let the `test` hop's fixall handle it — do not pre-empt the gate.
 
-## Changed-path targeted checks (dependency-aware verification, task 0510 R3)
+### Public-surface probe (task 1135 R1/R6/R8)
+
+Narrow unit tests prove the seam you refactored, not the surface a user calls. Before this stage
+reports done it runs **one end-to-end probe per new or changed public surface** — a CLI verb/flag,
+an HTTP route, or a plugin script entry:
+
+- against a **throwaway project root** (a temp dir), never the repo corpus or the execution tree's
+tracked files;
+- bounded: 120 s per invocation, output capped at 8 KiB, no network beyond the CLI under test;
+- recorded as acceptance evidence: the **exact command** and its **observed output**;
+- a failing probe is evidence, never a reason to mutate the corpus.
+
+A service-layer test suite does **not** satisfy this. The gap it closes is measured: 19 service tests
+green while `task create --feature <verifying>` failed end-to-end (task 1135 Background). If the stage
+changed no public surface, report the single line
+`probe: not-applicable (no public surface changed)` instead.
+
+**Changed-path static self-check (R8)** — over the changed paths only, before reporting done:
+
+- `spur rule run` with the configured pre-check preset (catches a direct `process.env` read, the
+  `env-var-hygiene` rule, and its siblings);
+- `bun run script-contract-check` when a plugin script was touched (a stale generated `.mjs` twin);
+- the paired-script parity test when `package.json` changed (a half-updated `spur-check` /
+  `spur-check-new` chain).
+
+The single full project check stays the pipeline `test` hop's job (see the section above); these are
+changed-path checks, not that gate.
+
+## Changed-path targeted checks (dependency-aware verification, task 0510 R3 / task 1142 R3)
 
 "Run the narrow test first" needs a second half: *which* narrow tests, when a change to a shared
 surface can break a downstream consumer. The matrix below is dependency-aware — domain → app →
@@ -126,6 +161,12 @@ implement. **It augments narrow behavior tests; it never authorizes `bun run spu
 `bun run test`, or another full project check inside implement** — the pipeline's `test` hop owns
 that single full gate.
 
+**Worker iteration check order (task 1142 R3):**
+1. The **changed-path matrix** below (narrow behavior tests + affected consumers);
+2. the resolved `quality-gate` script in `light` mode (source-repo probe, else the installed twin) (biome on changed files, per-workspace typecheck, rule presets `rules:pre`/`rules:post`, related tests).
+
+Neither step takes the host-wide full-gate lock. The full gate is named only for the pipeline's `test` and `test-recheck` hops.
+
 | Changed surface | Required targeted tests | Required typechecks |
 | --- | --- | --- |
 | `packages/domain/src/**` public type/query | affected domain test; affected app service test; affected CLI command test | `@gobing-ai/spur-domain`, `@gobing-ai/spur-app`, `@gobing-ai/spur` |
@@ -143,6 +184,12 @@ that single full gate.
   creep into every plugin edit.
 - Run the applicable rows, then stop: the single full project check belongs to the pipeline's
   `test` hop (`task-pipeline.yaml` `${vars.qualityGateCmd}`).
+- **Mirrored surfaces: an edit lands on all of them.** When the change is one instance of a repeated
+  pattern — the same wiring rule on two runbooks, a signature in both a generator and its generated
+  `.d.mts`, a command chain in both `spur-check` and `spur-check-new` — grep for the siblings and
+  update each in this pass. Two H1-batch cycles (2026-10-08) were spent re-finding exactly this:
+  task 1129 fixed the guard wiring on one runbook and left its sibling, and task 1127 changed
+  `spur-check` while `spur-check-new`'s chain-parity assertion still expected the old chain.
 
 ## Behavior
 

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

@@ -165,7 +165,7 @@ classifies it as external and never raises `L4.stale-line-anchor` for it (R1). D
 that lives in this repo — in-repo evidence MUST use the repo-relative backtick form
 `` `path:line` `` / `` `path:start-end` ``, and citing it in the external form still reports (R2).
 
-**Concrete anchors (0804 R9):** cite existing `file:line`s, never globs — `references/verdict-schema.md`.
+**Concrete anchors (0804 R9):** existing `file:line`s only, never globs, always repo-root-relative — a basename is `L4.anchor-unresolved` at the `--as done` gate (`references/verdict-schema.md`).
 
 ### Step 5 — Acceptance Criteria guard
 
@@ -315,6 +315,11 @@ node "$RESIDUAL" fold <wbs>
 > 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.
 
+> **Keying rule for feature-linked tasks (1086/1089 re-audits).** Key AC rows by the exact feature
+> scenario title (`R1 — …`): feature `Scenario:` titles are declared identities and satisfy L4
+> scenario matching directly. Bare `AC1` fails `ac-identity` on Gherkin AC sections, and checklist
+> labels truncate at the first colon (a `(req: …)` suffix), so the task's own AC title may not resolve.
+
 > **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
@@ -357,9 +362,8 @@ Confidence: HIGH
 The per-requirement traceability table MUST use `| Req | Status | Evidence |` (exactly this header, no `R#`/`R`/`Requirement` variant — `Status` in column 2 — and no extra columns between Req and Status). The Acceptance Criteria table MUST use `| AC | Status | Evidence Type | Evidence |`.
 The answer MUST carry exactly one `Confidence: HIGH|MEDIUM|LOW` line (task 1068): the verifier's stated confidence in the verdict — HIGH = fresh executable evidence + re-read anchors this run; MEDIUM = partial reliance on prior evidence, external/delegated outcomes, or an unstable tree; LOW = key evidence not re-executed. A missing or out-of-vocabulary line fails lint (`confidence-missing` / `confidence-value`) and blocks derivation; the value lands in the verdict artifact's `confidence` field and the recorded `## Testing` section.
 The answer MUST cite a source for external API/library claims in Requirement/AC evidence cells: a cell asserting a scoped-package (`@scope/name`), `node_modules/`, semver-version (`x.y.z`), or backticked function-call (`` `name(args)` ``) claim is rejected with `evidence-citation` unless the SAME cell carries a citation — a repo `path:line(-end)` (backticked or bare), the external named-origin form (@origin `path` line N), or a URL. Cross-cell references ("receipt above") do not count; marker-free receipts ("bun test 398 pass / 0 fail") need no citation.
-**MUST NOT:** place a `Severity` column between `Req` and `Status` in the authoring contract.
-The parser is tolerant of these variants (defense-in-depth), but the authoring contract is
-canonical.
+**MUST NOT:** place a `Severity` column between `Req` and `Status`. The parser tolerates variants
+as defense-in-depth; this contract is canonical.
 
 Under the pipeline, the verifier owns the answer file `.spur/run/<wbs>-verify-answer.txt` (0726
 R3): `Verdict: PARTIAL` first, append one row at a time, replace the verdict line only when all

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

@@ -90,6 +90,9 @@ Before declaring a task `done`, run this lightweight checklist. It catches the m
 - [ ] No `console.log` / `console.error` in production code (use the project logger).
 - [ ] No `--no-verify`, `--force`, or new suppression comments added to bypass gates.
 - [ ] Solution section contains `file:line` citations for every changed file.
+- [ ] API/library claims in changed docs carry a source citation (URL or `path:line`) and an honest
+      confidence level (HIGH/MEDIUM/LOW) per source-driven-development; the deterministic advisory backstop is
+      the `cited-version-strings` / `cited-api-claims` rules (`.spur/rules/docs/sourced-api-claims.yaml`).
 - [ ] Review section has P1–P4 findings table (even if all rows are empty — the table itself proves review happened).
 
 This checklist runs as part of the verify step when the task reaches `testing` status. It does not replace the formal gates — it augments them with between-pipeline hygiene checks.