@gobing-ai/spur 0.3.46 → 0.3.48

package/plugins/sp/hooks/careful-guard.ts

@@ -16,8 +16,13 @@
  * emits an `allow` decision. A broken guard must never wedge an agent tool call.
  *
  * **Escape hatch:** `SPUR_CAREFUL=off` short-circuits to allow.
+ *
+ * Classification itself lives in `destructive-policy.ts` — one policy, every platform
+ * adapter. This file owns the Claude Code payload/decision shape only.
  */
 
+import { classifyCommand } from './destructive-policy';
+
 interface ToolPayload {
     tool_name?: string;
     tool_input?: { command?: string };
@@ -37,86 +42,6 @@ function preToolUseDecision(decision: Decision, reason?: string): never {
     process.exit(0);
 }
 
-/** Well-known rebuildable caches a `rm -rf` may target without a warning. */
-const SAFE_RM_TARGET =
-    /^(?:\.?\/)?(?:[\w.@-]+\/)*(?:node_modules|dist|\.next|coverage|build|\.turbo|\.cache|\.parcel-cache|out)\/?\*?$/;
-
-/**
- * Expand an argument string into the set of flags it sets, splitting short-flag
- * clusters into their individual letters: `-Rf --force` → `{R, f, --force}`.
- *
- * Matching flags with ad-hoc regexes per call site is what let `rm -R` through —
- * `-\w*r` only ever matched the lowercase spelling, even though `man rm` defines
- * `-r` as "Equivalent to -R". Parsing once, case-preserved, makes that class of
- * miss unrepresentable: a caller names every spelling it cares about explicitly.
- */
-function parseFlags(args: string): Set<string> {
-    const flags = new Set<string>();
-    for (const token of args.trim().split(/\s+/)) {
-        if (token.length < 2 || !token.startsWith('-') || token === '--') continue;
-        if (token.startsWith('--')) {
-            flags.add(token.split('=')[0] as string); // `--force=x` → `--force`
-            continue;
-        }
-        for (const ch of token.slice(1)) flags.add(ch);
-    }
-    return flags;
-}
-
-/** True when a `rm` invocation is both recursive and forced (any flag spelling). */
-function isRecursiveForceRm(args: string): boolean {
-    const flags = parseFlags(args);
-    // POSIX rm accepts -r and -R interchangeably; --recursive is the GNU long form.
-    const recursive = flags.has('r') || flags.has('R') || flags.has('--recursive');
-    const force = flags.has('f') || flags.has('--force');
-    return recursive && force;
-}
-
-/** True when every non-flag target of a `rm` invocation is a known-safe cache path. */
-function rmTargetsAllSafe(args: string): boolean {
-    const targets = args
-        .trim()
-        .split(/\s+/)
-        .filter((t) => t.length > 0 && !t.startsWith('-'));
-    if (targets.length === 0) return false;
-    return targets.every((t) => SAFE_RM_TARGET.test(t));
-}
-
-/** Always-warn destructive patterns (no safe exception). */
-const DESTRUCTIVE: Array<{ label: string; re: RegExp }> = [
-    {
-        label: 'a SQL DROP/TRUNCATE (DROP TABLE/DATABASE, TRUNCATE)',
-        re: /\b(?:DROP\s+(?:TABLE|DATABASE)|TRUNCATE(?:\s+TABLE)?)\b/i,
-    },
-    { label: 'a force push (git push --force / -f)', re: /\bgit\s+push\b[^\n]*(?:--force(?!-with-lease)|\s-f\b)/i },
-    {
-        // `git push origin +main` forces that ref without any --force flag.
-        label: 'a force push via a + refspec (git push … +ref)',
-        re: /\bgit\s+push\b[^\n]*\s\+[\w./-]+/i,
-    },
-    { label: 'a hard reset (git reset --hard)', re: /\bgit\s+reset\b[^\n]*--hard\b/i },
-    {
-        label: 'a working-tree discard (git checkout . / git restore .)',
-        re: /\bgit\s+(?:checkout|restore)\s+(?:--\s+)?\.(?:\s|$)/i,
-    },
-    { label: 'a cluster delete (kubectl delete)', re: /\bkubectl\s+delete\b/i },
-    { label: 'a docker prune (docker system prune)', re: /\bdocker\s+system\s+prune\b/i },
-];
-
-/** Return a human label for the destructive command, or null when the command is safe. */
-function classifyCommand(command: string): string | null {
-    for (const rmMatch of command.matchAll(/\brm\b([^\n&|;]*)/g)) {
-        const args = rmMatch[1] ?? '';
-        if (isRecursiveForceRm(args) && !rmTargetsAllSafe(args)) {
-            return 'a recursive force remove (rm -rf)';
-        }
-    }
-    for (const { label, re } of DESTRUCTIVE) {
-        if (re.test(command)) return label;
-    }
-    return null;
-}
-
 async function main(): Promise<void> {
     if (process.env.SPUR_CAREFUL === 'off') preToolUseDecision('allow');
 

package/plugins/sp/hooks/destructive-policy.ts

@@ -0,0 +1,146 @@
+/**
+ * destructive-policy — the single destructive-command classifier shared by every
+ * platform guard (task 0215 R3; extracted from `careful-guard.ts`).
+ *
+ * **Why this module exists.** The policy used to live inline in `careful-guard.ts`
+ * (Claude Code) and was re-implemented with hand-rolled regexes in
+ * `pi/guard-extension.ts` (Pi). The two drifted: the Pi copy allowed
+ * `rm -rf node_modules /etc/nginx`, `rm -R --force /var/data`, `git push -f`, and
+ * `git push origin +main` — all of which the Claude matrix pins as `ask` — while
+ * warning on `git push --force-with-lease` and `rm -f config.json`, which it pins as
+ * `allow`. Seven of ten pinned cases diverged. A safety control with one
+ * implementation per platform is a safety control that is wrong on all but one of
+ * them, so the policy is defined once, here, and every adapter imports it.
+ *
+ * Adapters own **I/O only** (payload shape, how a prompt is raised). They must not
+ * re-derive classification.
+ */
+
+/**
+ * Well-known rebuildable caches a `rm -rf` may target without a warning.
+ *
+ * Project-relative only — the leading `/` this used to accept made the exception
+ * match by *basename anywhere on the filesystem*, so `rm -rf /Users/me/dist` was
+ * treated as routine. Escaping targets are rejected by {@link escapesProject}
+ * before this is consulted; keeping the anchor tight is belt-and-braces.
+ */
+const SAFE_RM_TARGET =
+    /^(?:\.\/)?(?:[\w.@-]+\/)*(?:node_modules|dist|\.next|coverage|build|\.turbo|\.cache|\.parcel-cache|out)\/?\*?$/;
+
+/**
+ * True when a target points outside the project tree: an absolute path, a `~`
+ * home path, or one that walks out via `..`.
+ *
+ * Recursive deletion inside the project is routine (build caches, scratch dirs) and
+ * recoverable from git; recursive deletion *outside* it is neither, whatever the
+ * directory happens to be named. This is the axis that decides a bare `rm -r`,
+ * which is otherwise unguarded — `rm -r ./tmpdir` stays routine while
+ * `rm -r /Users/me/photos` prompts.
+ */
+function escapesProject(target: string): boolean {
+    const t = target.replace(/^['"]|['"]$/g, '');
+    if (t.startsWith('/') || t.startsWith('~')) return true;
+    if (t.startsWith('$')) return true; // `$HOME/...`, `"$HOME"/...` — unknown expansion
+    return t.split('/').includes('..');
+}
+
+/**
+ * Expand an argument string into the set of flags it sets, splitting short-flag
+ * clusters into their individual letters: `-Rf --force` → `{R, f, --force}`.
+ *
+ * Matching flags with ad-hoc regexes per call site is what let `rm -R` through —
+ * `-\w*r` only ever matched the lowercase spelling, even though `man rm` defines
+ * `-r` as "Equivalent to -R". Parsing once, case-preserved, makes that class of
+ * miss unrepresentable: a caller names every spelling it cares about explicitly.
+ */
+export function parseFlags(args: string): Set<string> {
+    const flags = new Set<string>();
+    for (const token of args.trim().split(/\s+/)) {
+        if (token.length < 2 || !token.startsWith('-') || token === '--') continue;
+        if (token.startsWith('--')) {
+            flags.add(token.split('=')[0] as string); // `--force=x` → `--force`
+            continue;
+        }
+        for (const ch of token.slice(1)) flags.add(ch);
+    }
+    return flags;
+}
+
+/** True when a `rm` invocation is both recursive and forced (any flag spelling). */
+export function isRecursiveForceRm(args: string): boolean {
+    const flags = parseFlags(args);
+    // POSIX rm accepts -r and -R interchangeably; --recursive is the GNU long form.
+    const recursive = flags.has('r') || flags.has('R') || flags.has('--recursive');
+    const force = flags.has('f') || flags.has('--force');
+    return recursive && force;
+}
+
+/**
+ * True when **every** non-flag target of a `rm` invocation is a known-safe cache
+ * path. Every, not some: `rm -rf node_modules /etc/nginx` must still warn, and a
+ * substring test over the whole argument string (the Pi copy's approach) let one
+ * cache path whitelist every other target in the same command.
+ */
+export function rmTargetsAllSafe(args: string): boolean {
+    const targets = rmTargets(args);
+    if (targets.length === 0) return false;
+    return targets.every((t) => SAFE_RM_TARGET.test(t));
+}
+
+/** Non-flag targets of a `rm` invocation. */
+function rmTargets(args: string): string[] {
+    return args
+        .trim()
+        .split(/\s+/)
+        .filter((t) => t.length > 0 && !t.startsWith('-'));
+}
+
+/** Always-warn destructive patterns (no safe exception). */
+const DESTRUCTIVE: Array<{ label: string; re: RegExp }> = [
+    {
+        label: 'a SQL DROP/TRUNCATE (DROP TABLE/DATABASE, TRUNCATE)',
+        re: /\b(?:DROP\s+(?:TABLE|DATABASE)|TRUNCATE(?:\s+TABLE)?)\b/i,
+    },
+    { label: 'a force push (git push --force / -f)', re: /\bgit\s+push\b[^\n]*(?:--force(?!-with-lease)|\s-f\b)/i },
+    {
+        // `git push origin +main` forces that ref without any --force flag.
+        label: 'a force push via a + refspec (git push … +ref)',
+        re: /\bgit\s+push\b[^\n]*\s\+[\w./-]+/i,
+    },
+    { label: 'a hard reset (git reset --hard)', re: /\bgit\s+reset\b[^\n]*--hard\b/i },
+    {
+        label: 'a working-tree discard (git checkout . / git restore .)',
+        re: /\bgit\s+(?:checkout|restore)\s+(?:--\s+)?\.(?:\s|$)/i,
+    },
+    {
+        // `git clean` destroys UNTRACKED files — nothing in git to recover them from,
+        // which makes it the least recoverable command in this family. `-n`/`--dry-run`
+        // only lists, so the prompt is gated on the force flag git itself requires.
+        label: 'an untracked-file delete (git clean -f)',
+        re: /\bgit\s+clean\b[^\n]*(?:\s-[a-zA-Z]*f|\s--force\b)/i,
+    },
+    { label: 'a cluster delete (kubectl delete)', re: /\bkubectl\s+delete\b/i },
+    { label: 'a docker prune (docker system prune)', re: /\bdocker\s+system\s+prune\b/i },
+];
+
+/** Return a human label for the destructive command, or null when the command is safe. */
+export function classifyCommand(command: string): string | null {
+    for (const rmMatch of command.matchAll(/\brm\b([^\n&|;]*)/g)) {
+        const args = rmMatch[1] ?? '';
+        const flags = parseFlags(args);
+        const recursive = flags.has('r') || flags.has('R') || flags.has('--recursive');
+        // A recursive delete reaching outside the project prompts whether or not
+        // `--force` was passed: `rm -r` deletes a whole tree without prompting for
+        // any writable file, and nothing outside the project is recoverable from git.
+        if (recursive && rmTargets(args).some(escapesProject)) {
+            return 'a recursive remove outside the project (rm -r on an absolute, ~, or ../ path)';
+        }
+        if (isRecursiveForceRm(args) && !rmTargetsAllSafe(args)) {
+            return 'a recursive force remove (rm -rf)';
+        }
+    }
+    for (const { label, re } of DESTRUCTIVE) {
+        if (re.test(command)) return label;
+    }
+    return null;
+}

package/plugins/sp/hooks/pi/guard-extension.ts

@@ -24,12 +24,17 @@ import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { resolveAgentHint as resolveAgentHintShared, resolveModelHint as resolveModelHintShared } from '../agent-hint';
+import { classifyCommand } from '../destructive-policy';
+import { couldBeTaskFile } from '../task-file-policy';
 
 // ─── Constants ───────────────────────────────────────────────────────────
 
-const SPUR_CONTEXT_DIR = join(process.cwd(), '.spur', 'context');
-const SESSION_FILE = join(SPUR_CONTEXT_DIR, '.session.json');
-const LEDGER_FILE = join(SPUR_CONTEXT_DIR, 'token-ledger.jsonl');
+// Resolved per call, not cached at module load: Pi's cwd is fixed for the
+// process lifetime, and lazy resolution keeps the extension testable (tests
+// chdir into a temp project before driving handlers).
+const spurContextDir = (): string => join(process.cwd(), '.spur', 'context');
+const sessionFilePath = (): string => join(spurContextDir(), '.session.json');
+const ledgerFilePath = (): string => join(spurContextDir(), 'token-ledger.jsonl');
 const REDACTION_CAP = 4096;
 const SUMMARY_MAX_CHARS = 200;
 
@@ -101,33 +106,12 @@ function resolveSpurTaskOwnership(filePath: string): TaskOwnership {
     return 'unknown';
 }
 
-// Destructive command patterns (mirrors careful-guard.ts)
-const DESTRUCTIVE_PATTERNS: RegExp[] = [
-    /\brm\s+(?:-[rRf]*[rf]+\s*|\s*--recursive\s*)/,
-    /\bDROP\s+(?:TABLE|DATABASE)\b/i,
-    /\bTRUNCATE\b/i,
-    /\bgit\s+push\s+--force\b/,
-    /\bgit\s+reset\s+--hard\b/,
-    /\bgit\s+checkout\s+\.\b/,
-    /\bgit\s+restore\s+\.\b/,
-    /\bkubectl\s+delete\b/,
-    /\bdocker\s+system\s+prune\b/,
-];
-
-// Safe destructive paths (rm -rf of build caches is routine)
-const SAFE_CACHE_PATTERNS = [/node_modules/, /dist\b/, /\.next\b/, /coverage\b/, /build\b/, /\.turbo\b/, /\.cache\b/];
-
-function isDestructiveCommand(command: string): boolean {
-    return DESTRUCTIVE_PATTERNS.some((p) => p.test(command));
-}
-
-function isSafeDestructivePath(command: string): boolean {
-    // Check if rm -rf targets a known safe cache directory
-    const rmMatch = command.match(/\brm\s+(?:-[rRf]*[rf]+\s*|\s*--recursive\s*)(.+)/);
-    if (!rmMatch) return false;
-    const target = rmMatch[1] ?? '';
-    return SAFE_CACHE_PATTERNS.some((p) => p.test(target));
-}
+// Destructive-command classification is imported from `../destructive-policy`, the
+// single cross-platform policy. This file previously carried its own regex copy; it
+// diverged from the Claude matrix on 7 of 10 pinned cases (it allowed
+// `rm -rf node_modules /etc/nginx`, `rm -R --force /var/data`, `git push -f` and
+// `git push origin +main`, and warned on `git push --force-with-lease`). Do not
+// re-introduce a local copy — add cases to `destructive-policy.test.ts` instead.
 
 // ─── Token ledger helpers (mirrors context-post-tool.ts) ──────────────────
 
@@ -172,7 +156,7 @@ function redactText(text: string): string {
 
 function appendToLedger(event: ToolEvent, command: string | undefined): void {
     try {
-        if (!existsSync(SPUR_CONTEXT_DIR)) return;
+        if (!existsSync(spurContextDir())) return;
         const sessionId = readSessionId();
         if (!sessionId) return;
 
@@ -189,7 +173,7 @@ function appendToLedger(event: ToolEvent, command: string | undefined): void {
             timestamp: new Date().toISOString(),
         });
 
-        appendFileSync(LEDGER_FILE, `${ledgerEntry}\n`);
+        appendFileSync(ledgerFilePath(), `${ledgerEntry}\n`);
     } catch {
         // fail-open: skip ledger writes on error
     }
@@ -197,8 +181,8 @@ function appendToLedger(event: ToolEvent, command: string | undefined): void {
 
 function readSessionId(): string | undefined {
     try {
-        if (!existsSync(SESSION_FILE)) return undefined;
-        const data = JSON.parse(readFileSync(SESSION_FILE, 'utf-8')) as { session_id?: string };
+        if (!existsSync(sessionFilePath())) return undefined;
+        const data = JSON.parse(readFileSync(sessionFilePath(), 'utf-8')) as { session_id?: string };
         return data.session_id;
     } catch {
         return undefined;
@@ -215,7 +199,7 @@ function generateSessionId(): string {
 
 function initSession(): void {
     try {
-        mkdirSync(SPUR_CONTEXT_DIR, { recursive: true });
+        mkdirSync(spurContextDir(), { recursive: true });
         const sessionId = generateSessionId();
         const session = {
             session_id: sessionId,
@@ -223,7 +207,7 @@ function initSession(): void {
             model: resolveModelHintShared(process.env),
             started_at: new Date().toISOString(),
         };
-        writeFileSync(SESSION_FILE, `${JSON.stringify(session, null, 2)}\n`);
+        writeFileSync(sessionFilePath(), `${JSON.stringify(session, null, 2)}\n`);
 
         // Append session_start event to ledger
         const startEntry = JSON.stringify({
@@ -233,7 +217,7 @@ function initSession(): void {
             model: session.model,
             timestamp: session.started_at,
         });
-        appendFileSync(LEDGER_FILE, `${startEntry}\n`);
+        appendFileSync(ledgerFilePath(), `${startEntry}\n`);
     } catch {
         // fail-open
     }
@@ -241,16 +225,16 @@ function initSession(): void {
 
 function cleanupSession(): void {
     try {
-        if (!existsSync(SESSION_FILE)) return;
-        const session = JSON.parse(readFileSync(SESSION_FILE, 'utf-8')) as { session_id?: string };
+        if (!existsSync(sessionFilePath())) return;
+        const session = JSON.parse(readFileSync(sessionFilePath(), 'utf-8')) as { session_id?: string };
         const sessionId = session.session_id;
 
         // Compute rollup totals from ledger
         let reads = 0;
         let writes = 0;
         let tokens = 0;
-        if (sessionId && existsSync(LEDGER_FILE)) {
-            for (const line of readFileSync(LEDGER_FILE, 'utf-8').split('\n')) {
+        if (sessionId && existsSync(ledgerFilePath())) {
+            for (const line of readFileSync(ledgerFilePath(), 'utf-8').split('\n')) {
                 if (!line.trim()) continue;
                 try {
                     const evt = JSON.parse(line) as { session?: string; type?: string; tokens?: number };
@@ -273,10 +257,10 @@ function cleanupSession(): void {
             tokens,
             timestamp: new Date().toISOString(),
         });
-        appendFileSync(LEDGER_FILE, `${endEntry}\n`);
+        appendFileSync(ledgerFilePath(), `${endEntry}\n`);
 
         // Cleanup session file
-        rmSync(SESSION_FILE, { force: true });
+        rmSync(sessionFilePath(), { force: true });
     } catch {
         // fail-open
     }
@@ -292,7 +276,9 @@ export default function (pi: ExtensionAPI): void {
             const input = event.input as Record<string, unknown> | undefined;
             // Pi's write/edit tools use `path` (not Claude Code's `file_path`)
             const filePath = resolveInputPath(input);
-            if (filePath && resolveSpurTaskOwnership(filePath) === 'owned') {
+            // Skip the `spur task resolve` subprocess for paths that cannot name a
+            // task file (shared predicate — see task-file-policy.ts).
+            if (filePath && couldBeTaskFile(filePath) && resolveSpurTaskOwnership(filePath) === 'owned') {
                 const msg = `Denied: ${filePath} is a Spur task file. Use 'spur task update' instead.`;
                 ctx.ui.notify(msg, 'error');
                 return { block: true, reason: msg };
@@ -303,8 +289,9 @@ export default function (pi: ExtensionAPI): void {
         if (event.toolName === 'bash') {
             const input = event.input as Record<string, unknown> | undefined;
             const command = typeof input?.command === 'string' ? input.command : '';
-            if (command && isDestructiveCommand(command) && !isSafeDestructivePath(command)) {
-                const msg = `Warning: destructive command: ${command.slice(0, 120)}`;
+            const hit = command ? classifyCommand(command) : null;
+            if (hit !== null) {
+                const msg = `Warning: destructive command — ${hit}: ${command.slice(0, 120)}`;
                 ctx.ui.notify(msg, 'warning');
                 // Ask for confirmation
                 const ok = await ctx.ui.confirm('Destructive command', msg);

package/plugins/sp/hooks/task-file-policy.ts

@@ -0,0 +1,31 @@
+/**
+ * task-file-policy — the cheap local answer to "could this path possibly be a
+ * task file?", shared by every platform's write guard.
+ *
+ * **Why this exists.** The write guards decide ownership by shelling
+ * `spur task resolve --strict --json`, which costs a full CLI start — measured
+ * 119-122ms with an installed binary, 187-238ms source-local — on *every* `Write`
+ * and `Edit` tool call, the overwhelming majority of which target ordinary source
+ * files that could never be task files. This predicate skips the subprocess for
+ * those without weakening the guard.
+ *
+ * **Why it cannot produce a false allow.** `--strict` resolution matches a corpus
+ * file through `TASK_FILENAME_RE` in `packages/app/src/services/task-locator.ts`
+ * (`^(\d{4})_(.+)\.md$`), so a basename failing that pattern can never be reported
+ * owned. This predicate is the same test, applied locally. If the corpus filename
+ * convention ever changes, this must change with it — `task-file-policy.test.ts`
+ * pins the two together.
+ */
+
+/** The corpus task filename convention: `<4-digit wbs>_<slug>.md`. */
+const TASK_FILENAME_RE = /^(\d{4})_(.+)\.md$/;
+
+/**
+ * True when `filePath`'s basename could name a task file. A `false` result is
+ * authoritative — no `spur task resolve --strict` call is needed. A `true` result
+ * only means "ask the CLI"; folder membership is still the CLI's decision.
+ */
+export function couldBeTaskFile(filePath: string): boolean {
+    const basename = filePath.split(/[\\/]/).pop() ?? '';
+    return TASK_FILENAME_RE.test(basename);
+}

package/plugins/sp/hooks/task-write-guard.ts

@@ -20,6 +20,7 @@
  */
 
 import { spawnSync } from 'node:child_process';
+import { couldBeTaskFile } from './task-file-policy';
 
 interface ToolPayload {
     tool_name?: string;
@@ -68,6 +69,9 @@ async function main(): Promise<void> {
 
     const filePath = payload.tool_input?.file_path ?? '';
     if (filePath === '') preToolUseDecision('allow');
+    // Skip the `spur task resolve` subprocess (~120ms) for paths whose basename
+    // cannot name a task file — that is every ordinary source edit.
+    if (!couldBeTaskFile(filePath)) preToolUseDecision('allow');
 
     const ownership = resolveSpurTaskOwnership(filePath, process.env.CLAUDE_PROJECT_DIR ?? process.cwd());
     if (ownership === 'owned') {

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.46",
+    "version": "0.3.48",
     "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics.",
     "extensions": {
         "pi": ["./hooks/pi/guard-extension.ts"]

package/plugins/sp/references/roles.md

@@ -0,0 +1,93 @@
+---
+name: roles
+description: "Layer-1 role→tier table for /sp:dev-* dispatch — four roles (scribe, coder, reviewer, planner), one per tier; command→role mapping closed over plugins/sp/commands/; stage-floor reconciliation. Consumed by sp:spur-dev, sp:spur-cli, sp:code-verification."
+see_also:
+  - spur-dev
+  - spur-cli
+  - code-verification
+---
+
+# Roles — the Layer-1 role-to-tier table
+
+The executor-selection contract is two layers. **Layer 1 (this file)** maps *role → tier* and is
+owned by plugin `sp`; **Layer 2** maps *tier → executor* and is owned by the operator in
+`.spur/config.yaml`. This file never names an executor, a model, or a vendor — it declares only
+what tier a role's work needs, and the operator's config decides which executor serves that tier.
+
+The vocabulary is four roles, one per tier:
+
+| Role | Tier | Stage floor source |
+| --- | --- | --- |
+| `scribe` | cheap | changelog (`min_tier: cheap`) |
+| `coder` | standard | implement / test / wrap (`min_tier: standard`) |
+| `reviewer` | capable-1 | verify / review / dogfood (highest fold `capable-1`) |
+| `planner` | capable-2 | plan / refine / brainstorm (highest fold `capable-2`) |
+
+**The one-role-per-tier property is the invariant**, not a coincidence: two roles sharing a tier
+resolve to the same eligible executor set and are one role with two names. A proposed fifth role
+must bring a fifth tier. The tiers are the live vocabulary
+`cheap | standard | capable-1 | capable-2 | capable-3` (packages/config/src/index.ts).
+
+This table supersedes the eight-intention vocabulary recorded in task 0344 § Solution D1/D2. That
+decision named eight intentions, but against the stage registry they carried only four distinct
+tier floors (`plan` capable-2; `verify`/`dogfood` capable-1; `changelog` cheap; everything else
+standard) — four of the eight names had no routing consequence. The four roles below are that
+collapse, named as people so they stay addressable in `--agent`.
+
+## The table
+
+```yaml
+version: 1
+roles:
+  - id: scribe
+    tier: cheap
+    commands: [dev-gitmsg, dev-handover, dev-daily, dev-changelog, dev-refresh, rule-add, rule-refine, workflow-add, workflow-refine, spur-init]
+    stages: [changelog]
+  - id: coder
+    tier: standard
+    commands: [dev-run, dev-unit, dev-debug, dev-simplify, dev-fixall, dev-reverse, dev-wrap, dev-wrapall, dev-gtd]
+    stages: [implement, test, wrap]
+  - id: reviewer
+    tier: capable-1
+    commands: [dev-verify, dev-verifyall, dev-review, dev-dogfood, rule-scan, dev-find-conflict, dev-find-issue]
+    stages: [verify, review, dogfood]
+  - id: planner
+    tier: capable-2
+    commands: [dev-plan, dev-refine, dev-brainstorm, dev-idea, dev-runall, dev-parallel, dev-next, dev-arch, dev-refineall, dev-find-next, dev-featurechange]
+    stages: [plan, refine, brainstorm]
+```
+
+`commands` is the closed command→role mapping: every file under `plugins/sp/commands/` appears in
+exactly one row, and a new command must be added to exactly one row (or bring a fifth role with a
+fifth tier). `stages` lists the canonical stages the role folds (ids from
+`REGISTERED_CANONICAL_STAGES` in `packages/domain/src/stage-registry/schema.ts`); a role's `tier`
+must not sit below the highest `min_tier` among its folded stages.
+
+## Role annotations
+
+- **`scribe` (cheap).** Writing derived text — commit messages, changelogs, handovers, daily
+  summaries — plus template scaffolding (`spur init`, rule/workflow authoring). Mechanical,
+  high-volume, cheap-tier work. Folds the `changelog` stage.
+- **`coder` (standard).** Implementation and delivery: running the pipeline, unit tests, debugging,
+  simplification, fix-everything sweeps, reverse engineering, wrap-up, and the end-to-end
+  delivery flow (`dev-gtd`). Folds `implement`, `test`, `wrap`.
+- **`reviewer` (capable-1).** Verification and analysis: per-task verify/review, batch verify,
+  dogfooding, anti-pattern scanning (`rule-scan`), and the two audit commands (`dev-find-conflict`,
+  `dev-find-issue`) — those analyse rather than transcribe, which is why they sit here and not
+  under `scribe`. Folds `verify`, `review`, `dogfood`.
+- **`planner` (capable-2).** The planning half: feature planning, requirement refinement (single
+  and batch), brainstorm, idea intake, batch run/parallel orchestration, next-step routing,
+  architecture survey, feature-frontier prioritization, and feature-tree restructure. Folds `plan`,
+  `refine`, `brainstorm`.
+
+**Placement notes (directory closure, task 0535).** The decided four-row table listed 31 commands;
+the live `plugins/sp/commands/` directory has 37. The six additional commands were placed by the
+same stage logic: `dev-refineall` folds `refine` → planner; `dev-find-next` is planning-side
+frontier work → planner; `dev-featurechange` is planning-half corpus surgery on the feature tree →
+planner; `dev-gtd` is the execution/delivery flow → coder; `dev-find-conflict` and `dev-find-issue`
+are audits/analysis → reviewer (same reasoning as `rule-scan`).
+
+**Consistency is a test, not a convention.** `plugins/sp/tests/roles.test.ts` parses this YAML and
+asserts the tier-distinctness, command closure, stage-floor, and boundary invariants against the
+real command directory, the real stage registry, and the real operator config. When the table and
+the registry disagree, fix the table or the registry — never the test.

package/plugins/sp/scripts/feature-sync-bounded.ts

@@ -20,8 +20,9 @@
  */
 
 import { createHash } from 'node:crypto';
-import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 // ── Local types (match packages/app FeatureService shapes; no package import) ───────────
 
@@ -241,9 +242,24 @@ through unchanged.
 
 Exit: 0 = sync handled (applied / no-op / suppressed-blocked / live-blocked).`;
 
+/**
+ * Resolve the spur CLI command in a monorepo-safe way:
+ * --spur-bin > SPUR_BIN > monorepo-local CLI entry > PATH `spur`.
+ * The plugin's own CI always passes an explicit --spur-bin; this fallback chain
+ * keeps ad-hoc invocations from silently hitting a stale PATH install.
+ */
+export function defaultSpurBin(): string {
+    if (process.env.SPUR_BIN) return process.env.SPUR_BIN;
+    // scripts/ -> plugins/sp/ -> <repo>/apps/cli/src/index.ts (fileURLToPath — raw pathname breaks
+    // on %-encoded paths, e.g. spaces in the checkout directory)
+    const local = fileURLToPath(new URL('../../../apps/cli/src/index.ts', import.meta.url));
+    if (existsSync(local)) return `bun ${local}`;
+    return 'spur';
+}
+
 export function parseBoundedSyncCliArgs(argv: string[]): BoundedSyncCliArgs {
     let featureId = '';
-    let spurBin = 'spur';
+    let spurBin = defaultSpurBin();
     let runDir = '.spur/run';
     let json = false;
     let help = false;
@@ -412,6 +428,16 @@ function invokeLiveSync(
         // Unparseable sync output — surface it raw rather than guessing.
         return { exitCode: r.exitCode, stdout: r.stdout, stderr: '' };
     }
+    // Shape guard (review finding 1): a parseable envelope that is not a FeatureSyncResult
+    // (missing `proposal`) must fail loudly with a message, not a TypeError in
+    // classifySyncResult. Mirrors the validation the read side already performs.
+    if (!result || typeof result !== 'object' || !result.proposal) {
+        return {
+            exitCode: r.exitCode,
+            stdout: r.stdout,
+            stderr: 'unrecognized feature sync envelope: missing proposal',
+        };
+    }
 
     // If we have no fingerprint (pre-check fallback path), recompute minimal signals so we can
     // still persist a blocked record. Missing signals yield an empty-string fingerprint, which