@gobing-ai/spur 0.3.47 → 0.3.49

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.47",
+    "version": "0.3.49",
     "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,106 @@
+---
+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)** projects *role → tier*;
+its SSOT is `DEFAULT_AGENT_ROLES` in `packages/config/src/index.ts` (task 0572 / ADR-061) — this
+file is the agent/human-facing view plus the plugin-owned command→role mapping. **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
+
+<!-- PROJECTION (task 0572 / ADR-061): the tier/stages half of the block below is a generated view
+     of DEFAULT_AGENT_ROLES in packages/config/src/index.ts — edit that constant, not this file.
+     plugins/sp/tests/roles.test.ts (R9) fails the suite on any drift between the two. The
+     `commands:` half is plugin data (command frontmatter is its SSOT). -->
+
+```yaml
+version: 1
+roles:
+  - id: scribe
+    tier: cheap
+    commands: [dev-gitmsg, dev-handover, dev-daily, dev-history-load, 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-pr-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-feature-change]
+    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 39. 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-feature-change` 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`). Later additions: `dev-history-load`
+is mechanical load+analyze orchestration → scribe; `dev-pr-review` is review orchestration —
+driving the external PR review and triaging its findings folds the `review` stage → reviewer.
+
+**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 — plus parity with
+`DEFAULT_AGENT_ROLES` (R9, 0572): the table above must equal the code SSOT byte-for-byte on
+id/tier/stages. When the table and the registry disagree, fix the table or the registry — never the
+test. When the table and `DEFAULT_AGENT_ROLES` disagree, fix the constant (or regenerate this view).
+A project may re-tier/re-stage a role at config time via `agent.roles` (closed vocabulary) — that
+override never flows back into this file.

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