@gobing-ai/spur 0.3.38 → 0.3.40

package/config/corpus-baseline.json

@@ -1,20 +1,6 @@
 {
     "note": "Accepted `spur task check` / `spur feature check` errors. This is a POLICY file, not a status dump: it is an INPUT to `bun run corpus-check`, so it must be committed — an untracked baseline means the gate behaves differently on every clone and CI, and the first person to meet 8 unexplained failures disables it. Do not move it under `.spur/` (gitignored, ephemeral run artifacts). The gate fails on any error NOT listed here, and ALSO on any entry that no longer reproduces, so this cannot rot into a silent suppression list. Every entry needs a real diagnosis, a reason, and a date — 'pre-existing, not investigated' is not a reason.",
     "entries": [
-        {
-            "kind": "task",
-            "id": "0368",
-            "code": "L3.required-section-placeholder",
-            "reason": "RATCHET DRIFT, not a bypass. Closed 2026-07-28; the rule that flags it landed 2026-08-01 (f373e90b), four days later. It was legally closed under the rules of its day and became non-compliant retroactively. Backfill Testing/Solution or exempt permanently when someone next touches it.",
-            "since": "2026-08-07"
-        },
-        {
-            "kind": "task",
-            "id": "0454",
-            "code": "L3.solution-file-line",
-            "reason": "GENUINE PRE-FIX BYPASS. Closed 2026-08-06, well after the rule existed (2026-07-24), via the `--no-lifecycle` hole closed on 2026-08-07. Its Solution needs one file:line citation. The only entry here representing real unpaid debt.",
-            "since": "2026-08-07"
-        },
         {
             "kind": "feature",
             "id": "F821",

package/config/templates/AGENTS.md

@@ -173,6 +173,12 @@ catalog here or maintain generated per-platform capability copies in the project
 - Surgical changes only — no drive-by refactors or speculative abstractions.
 - Surface changes keep `docs/04_DESIGN.md` in the **same commit** (T3); run `sp:doc-evolve`
   sync-check when unsure.
+- **One writer per working tree.** Two agent sessions in one checkout overwrite each other silently
+  — the symptom reads as a model regression. Parallel agent work uses git worktree isolation (one
+  branch + one tree per agent).
+- **Commit per task.** Start a task on a tree clean of other tasks' implementations; a dirty tree
+  mixes two tasks' evidence into one diff. The pipeline precheck warns (never blocks) with the file
+  list.
 <!-- PROJECT-SPECIFIC: import aliases, forbidden paths, CI rules. -->
 
 ---

package/config/workflows/task-pipeline.yaml

@@ -104,6 +104,12 @@ vars:
   # Max checklist items under ## Plan before size precheck fails (R2, task 0454).
   # Override with `--vars '{"maxImplementPlanItems":"15"}'`.
   maxImplementPlanItems: "8"
+  # Diff-scope guard on the implement hop (R1, task 0487). When the target task
+  # body backticks at least one path, non-corpus changes outside those paths
+  # fail the step by name. New files beside a declared file are allowed. Empty
+  # (default) = on; set to "off" to bypass:
+  # `--vars '{"implementScopeGuard":"off"}'`.
+  implementScopeGuard: ""
 
 states:
   - id: precheck
@@ -114,16 +120,58 @@ states:
     onEnter:
       # Soft doctor — write status and always exit 0 so transitions can branch to
       # `failed` cleanly (same pattern as the quality-gate soft probe).
+      #
+      # R2 (0487): probe BOTH resolved executors ($agent and $implementAgent) and
+      # FAIL on `authenticated: unauthenticated`. Previously only $agent was probed
+      # and auth was informational, so a run whose implement executor had no
+      # provider key sailed through precheck into a guaranteed implement failure
+      # (runs e8cb00e7 / b16bfbf4: "auth: no … API key not found for provider
+      # 'volc'" → precheck ✓). `unknown` auth keeps the old soft behavior — some
+      # agents expose no auth-status verb. `spur agent doctor` CLI exit-code
+      # semantics are deliberately untouched; the gate lives here.
+      # R4 (0487): one divergence line when the two executors differ (legitimate
+      # when only implementAgent is pinned, but it must be visible in the log).
       - kind: shell
         options:
           command: >-
             mkdir -p .spur/run &&
             DOCTOR_FILE=".spur/run/$wbs-precheck-doctor.status" &&
-            if $spurBin agent doctor $agent; then
-              echo PASS > "$DOCTOR_FILE";
+            STATUS=PASS;
+            if [ -n "$implementAgent" ] && [ "$implementAgent" != "$agent" ]; then
+              echo "precheck: agent=$agent implementAgent=$implementAgent (executors diverge)";
+              EXECS="$agent $implementAgent";
             else
-              echo FAIL > "$DOCTOR_FILE";
-            fi &&
+              EXECS="$agent";
+            fi;
+            for EXE in $EXECS; do
+              OUT=$($spurBin agent doctor "$EXE" --json 2>&1) || {
+                echo "precheck: FAIL - doctor exited non-zero for $EXE";
+                echo "$OUT";
+                STATUS=FAIL;
+                continue;
+              };
+              AUTH=$(printf '%s' "$OUT" | jq -r '.agents[0].authenticated // "unknown"' 2>/dev/null || echo unknown);
+              DETAIL=$(printf '%s' "$OUT" | jq -r '.agents[0].modelStatus.detail // ""' 2>/dev/null || echo "");
+              echo "precheck: $EXE auth=$AUTH $DETAIL";
+              if [ "$AUTH" = unauthenticated ]; then
+                echo "precheck: FAIL - executor $EXE is unauthenticated; $DETAIL";
+                STATUS=FAIL;
+              fi;
+            done;
+            echo "$STATUS" > "$DOCTOR_FILE";
+            exit 0
+      # R6 (0487): pre-launch hygiene WARNING (never a block) — starting a task on
+      # a tree already dirty with another task's implementation is how 0485's diff
+      # got swept into 0486's run. Corpus dirs are excluded: the pipeline writes
+      # those itself.
+      - kind: shell
+        options:
+          command: >-
+            DIRTY=$(git status --porcelain -- . ':(exclude)docs/tasks*' ':(exclude)docs/features' 2>/dev/null);
+            if [ -n "$DIRTY" ]; then
+              echo "precheck: WARNING - working tree has uncommitted non-corpus changes; commit or stash before starting a new task:";
+              echo "$DIRTY";
+            fi;
             exit 0
       - kind: note
         options:
@@ -149,13 +197,17 @@ states:
       # R2 (0454): task size precheck — evaluate R-item and Plan-item counts.
       # Writes PASS/FAIL to .spur/run/<wbs>-precheck-size.status. Always exit 0
       # (soft check, like doctor). The precheck→implement guard reads the file.
+      # R3 (0487): `--executor` adds the size-vs-capability gate — a task past the
+      # DEFAULT caps routed to a sub-`capable-1` executor blocks here instead of
+      # burning the full implementTimeoutMs and exiting 3 (run ca130182).
       - kind: shell
         options:
           command: >-
             SIZE_FILE=".spur/run/$wbs-precheck-size.status" &&
             mkdir -p .spur/run &&
             bun plugins/sp/scripts/task-size-precheck.ts "$wbs"
-            --spur-bin "$spurBin" --max-reqs "$maxImplementReqs" --max-plan-items "$maxImplementPlanItems" &&
+            --spur-bin "$spurBin" --max-reqs "$maxImplementReqs" --max-plan-items "$maxImplementPlanItems"
+            --executor "$implementAgent" &&
             exit 0
 
   - id: implement

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.38",
+    "version": "0.3.40",
     "description": "Spur CLI — local-first harness for mainstream coding agents: constraint checking, workflow orchestration, agent health, and history analytics. Bun-native; exposes the `spur` command.",
     "keywords": [
         "spur",

package/spur.js

@@ -62497,7 +62497,12 @@ class AgentService {
       }
     }
     if (args.json) {
-      this.ctx.output.write(toJson({ agents: results }));
+      const executorByName = new Map((executors ?? []).map((e) => [e.name, e]));
+      const rows = results.map((result) => {
+        const executor = executorByName.get(result.agent) ?? { name: result.agent, agent: result.agent };
+        return { ...result, capabilityTier: getExecutorTier(executor) };
+      });
+      this.ctx.output.write(toJson({ agents: rows }));
     } else if (args.agent !== undefined) {
       this.ctx.output.write(renderDoctorDetail(results[0] ?? null));
     } else {
@@ -67989,7 +67994,7 @@ function hasPopulatedPriorityTable(body) {
     const cells = line.split("|");
     if (cells.length < 3)
       continue;
-    const severityIdx = cells.findIndex((c3) => /^\s*P[1-4]\s*$/.test(c3));
+    const severityIdx = cells.findIndex((c3) => /^\s*P[1-4]\b/.test(c3));
     if (severityIdx === -1)
       continue;
     const hasContent = cells.some((c3, i2) => i2 !== severityIdx && !isPlaceholderCell(c3));
@@ -67999,8 +68004,12 @@ function hasPopulatedPriorityTable(body) {
   return false;
 }
 function extractReviewSectionBody(markdown) {
-  const match = markdown.match(/^### Review[ \t]*\n([\s\S]*?)(?=^### |Z)/m);
-  return match ? match[1] ?? "" : null;
+  const heading = markdown.match(/^### Review[ \t]*\n/m);
+  if (!heading)
+    return null;
+  const rest = markdown.slice((heading.index ?? 0) + heading[0].length);
+  const next = rest.match(/^### /m);
+  return next ? rest.slice(0, next.index ?? 0) : rest;
 }
 function isReviewScaffold(body) {
   if (isPlaceholderBody(body))
@@ -71241,6 +71250,7 @@ var init_steering = __esm(() => {
 });
 
 // ../../packages/app/src/workflow/actions/agent-run.ts
+import { tmpdir } from "os";
 import { dirname as dirname14, isAbsolute as isAbsolute3, join as join17 } from "path";
 
 class AgentRunActionRunner {
@@ -71330,6 +71340,7 @@ class AgentRunActionRunner {
     let resumeRetried = false;
     let steeringNote;
     let traced;
+    const diffBaseline = requireDiff === true ? await createGitWorkingTreeSnapshot(cwd, this.agentConfig.excludeGlobs) : undefined;
     try {
       for (;; ) {
         steeringNote = undefined;
@@ -71393,12 +71404,25 @@ class AgentRunActionRunner {
         }
       }
       const stepLabel = context4.stateOrNodeId;
-      if (ok && requireDiff === true && !await gitHasNonCorpusChanges(cwd, this.agentConfig.excludeGlobs)) {
-        return {
-          ok: false,
-          data: buildResultData(exitCode, agentLabel, capture, answer, invocation),
-          error: `agent.run '${stepLabel}' (${agentLabel}) exited 0 but produced zero non-corpus file changes \u2014 empty implement (no-op). The implement agent must change at least one file outside the configured task/feature folders; fix the implement input and re-run the pipeline.`
-        };
+      if (ok && requireDiff === true) {
+        const changed = diffBaseline === undefined ? await gitNonCorpusChangedFiles(cwd, this.agentConfig.excludeGlobs) : await gitChangesSinceSnapshot(cwd, diffBaseline, this.agentConfig.excludeGlobs);
+        if (changed.length === 0) {
+          return {
+            ok: false,
+            data: buildResultData(exitCode, agentLabel, capture, answer, invocation),
+            error: `agent.run '${stepLabel}' (${agentLabel}) exited 0 but produced zero non-corpus file changes \u2014 empty implement (no-op). The implement agent must change at least one file outside the configured task/feature folders; fix the implement input and re-run the pipeline.`
+          };
+        }
+        const wbs = String(context4.vars.wbs ?? "");
+        const guardOff = String(context4.vars.implementScopeGuard ?? "") === "off";
+        const rogue = guardOff ? [] : await findOutOfScopeChanges(cwd, wbs, changed);
+        if (rogue.length > 0) {
+          return {
+            ok: false,
+            data: buildResultData(exitCode, agentLabel, capture, answer, invocation),
+            error: `agent.run '${stepLabel}' (${agentLabel}) changed files outside task ${wbs}'s declared surfaces: ${rogue.join(", ")}. Implement only the target WBS; revert the out-of-scope changes (or name those paths in the task body). Set the run var implementScopeGuard: "off" to bypass.`
+          };
+        }
       }
       if (!ok) {
         await writePartialWorkArtifact(context4, agentLabel, model, traced, cwd, sessionDir);
@@ -71439,7 +71463,10 @@ class AgentRunActionRunner {
           ...steeringNote !== undefined ? { __steeringNote: steeringNote } : {}
         } : undefined
       };
-    } finally {}
+    } finally {
+      if (diffBaseline !== undefined)
+        await deleteSnapshotIndex(diffBaseline);
+    }
   }
 }
 async function discoverSessionId(sessionDir) {
@@ -71647,20 +71674,151 @@ async function gitDiffStat(cwd) {
     return "";
   }
 }
-async function gitHasNonCorpusChanges(cwd, excludeGlobs = ["docs/tasks3/*", "docs/features/*"]) {
+async function createGitWorkingTreeSnapshot(cwd, excludeGlobs = ["docs/tasks3/*", "docs/features/*"]) {
+  const indexFile = join17(tmpdir(), `spur-implement-scope-${crypto.randomUUID()}.index`);
+  const fs3 = createNodeFileSystem3(cwd);
+  let keepIndex = false;
+  try {
+    await fs3.ensureDir(dirname14(indexFile));
+    const env = Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined));
+    env.GIT_INDEX_FILE = indexFile;
+    const executor = new NodeProcessExecutor3;
+    const common4 = { cwd, env, forceBuffered: true, rejectOnError: false };
+    const read = await executor.run({ command: "git", args: ["read-tree", "HEAD"], ...common4 });
+    if (read.exitCode !== 0)
+      return;
+    const excludes = excludeGlobs.map((glob) => `:(exclude)${glob}`);
+    const add = await executor.run({ command: "git", args: ["add", "-A", "--", ".", ...excludes], ...common4 });
+    if (add.exitCode !== 0)
+      return;
+    const tree = await executor.run({ command: "git", args: ["write-tree"], ...common4 });
+    if (tree.exitCode !== 0 || tree.stdout.trim() === "")
+      return;
+    keepIndex = true;
+    return { indexFile, tree: tree.stdout.trim() };
+  } catch {
+    return;
+  } finally {
+    if (!keepIndex && await fs3.exists(indexFile))
+      await fs3.deleteFile(indexFile);
+  }
+}
+async function deleteSnapshotIndex(snapshot) {
+  try {
+    await createNodeFileSystem3().deleteFile(snapshot.indexFile);
+  } catch {}
+}
+async function gitChangesSinceSnapshot(cwd, before, excludeGlobs = ["docs/tasks3/*", "docs/features/*"]) {
+  const after = await createGitWorkingTreeSnapshot(cwd, excludeGlobs);
+  if (after === undefined)
+    return gitNonCorpusChangedFiles(cwd, excludeGlobs);
+  try {
+    const result = await new NodeProcessExecutor3().run({
+      command: "git",
+      args: ["diff", "--name-status", "-z", before.tree, after.tree],
+      cwd,
+      maxOutput: 1024 * 1024,
+      forceBuffered: true,
+      rejectOnError: false
+    });
+    return result.exitCode === 0 ? parseNameStatusPaths(result.stdout) : gitNonCorpusChangedFiles(cwd, excludeGlobs);
+  } finally {
+    await deleteSnapshotIndex(after);
+  }
+}
+function parseNameStatusPaths(stdout) {
+  const fields = stdout.split("\x00").filter(Boolean);
+  const changes = [];
+  for (let i2 = 0;i2 < fields.length; ) {
+    const status = fields[i2++] ?? "";
+    if (/^[RC]/.test(status))
+      i2++;
+    const path9 = fields[i2++] ?? "";
+    if (path9)
+      changes.push({ path: path9, untracked: status === "A" });
+  }
+  return changes;
+}
+async function gitNonCorpusChangedFiles(cwd, excludeGlobs = ["docs/tasks3/*", "docs/features/*"]) {
   try {
     const excludes = excludeGlobs.map((g) => `:(exclude)${g}`);
     const result = await new NodeProcessExecutor3().run({
       command: "git",
-      args: ["status", "--porcelain", "--", ".", ...excludes],
+      args: ["status", "--porcelain", "-uall", "--", ".", ...excludes],
       cwd,
       maxOutput: 1024 * 1024,
       forceBuffered: true,
       rejectOnError: false
     });
-    return result.exitCode === 0 && result.stdout.trim() !== "";
+    if (result.exitCode !== 0)
+      return [];
+    return parsePorcelainPaths(result.stdout);
   } catch {
-    return false;
+    return [];
+  }
+}
+function parsePorcelainPaths(stdout) {
+  const paths = [];
+  for (const line of stdout.split(`
+`)) {
+    if (line.length < 4)
+      continue;
+    let path9 = line.slice(3);
+    const arrow = path9.indexOf(" -> ");
+    if (arrow !== -1)
+      path9 = path9.slice(arrow + 4);
+    path9 = path9.trim().replace(/^"|"$/g, "");
+    if (path9)
+      paths.push({ path: path9, untracked: line.startsWith("??") });
+  }
+  return paths;
+}
+function extractTaskScopeAllowlist(taskMarkdown) {
+  const rules = new Map;
+  for (const match of taskMarkdown.matchAll(/`([^`\n]+)`/g)) {
+    let token = (match[1] ?? "").trim();
+    const prefix = /\/\*+$/.test(token);
+    token = token.replace(/:\d+(-\d+)?$/, "").replace(/\/\*+$/, "").replace(/\/$/, "").replace(/^\.\//, "");
+    if (/\s/.test(token) || token.startsWith("-") || token.startsWith("/") || token.startsWith("../")) {
+      continue;
+    }
+    const isPath = token.includes("/") || /^[\w.-]+\.\w{1,10}$/.test(token);
+    if (!isPath)
+      continue;
+    const isFile = /\.[\w-]{1,10}$/.test(token);
+    const rule = { path: token, prefix: prefix || !isFile };
+    rules.set(`${rule.prefix ? "prefix" : "file"}:${rule.path}`, rule);
+  }
+  return [...rules.values()];
+}
+function isInScope(change, allowlist) {
+  return allowlist.some((rule) => {
+    if (rule.prefix)
+      return change.path === rule.path || change.path.startsWith(`${rule.path}/`);
+    if (change.path === rule.path)
+      return true;
+    return change.untracked && dirname14(change.path) === dirname14(rule.path);
+  });
+}
+async function findOutOfScopeChanges(cwd, wbs, changed) {
+  if (!wbs)
+    return [];
+  try {
+    const fs3 = createNodeFileSystem3(cwd);
+    const locator = TaskLocator.forDirs(fs3, [
+      join17(cwd, "docs", "tasks3"),
+      join17(cwd, "docs", "tasks2"),
+      join17(cwd, "docs", "tasks")
+    ]);
+    const hit = await locator.findByWbs(wbs);
+    if (!hit)
+      return [];
+    const allowlist = extractTaskScopeAllowlist(await fs3.readFile(hit.filePath));
+    if (allowlist.length === 0)
+      return [];
+    return changed.filter((change) => !isInScope(change, allowlist)).map((change) => change.path);
+  } catch {
+    return [];
   }
 }
 function tail(text4, maxChars) {
@@ -72912,26 +73070,30 @@ async function fileExists(path9) {
   return await fs3.exists(path9);
 }
 async function resolveDefaultAgentVar(cwd, callerVars, warn) {
+  const result = {};
+  if (callerVars?.implementAgent === undefined && callerVars?.agent !== undefined) {
+    result.implementAgent = callerVars.agent;
+  }
   let config4;
   try {
     config4 = await loadSpurConfig(cwd);
   } catch {
-    return {};
+    return result;
   }
   const configured = config4.agent?.default;
   if (typeof configured !== "string" || configured.length === 0) {
-    return {};
+    return result;
   }
   const valid = config4.agent?.executors?.some((e) => e.name === configured) === true || resolveAgentName(configured) !== undefined;
   if (!valid) {
     warn(`agent.default "${configured}" does not name a configured executor or agent binary; leaving the pipeline's literal agent in force`);
-    return {};
+    return result;
   }
-  const result = {};
   if (callerVars?.agent === undefined)
     result.agent = configured;
-  if (callerVars?.implementAgent === undefined)
+  if (result.implementAgent === undefined && callerVars?.implementAgent === undefined) {
     result.implementAgent = configured;
+  }
   return result;
 }
 async function resolveWorkflowLogRetentionDays(cwd) {
@@ -81463,7 +81625,7 @@ init_dist6();
 var CLI_CONFIG = {
   binaryName: "spur",
   binaryLabel: "spur",
-  binaryVersion: "0.3.38",
+  binaryVersion: "0.3.40",
   configDir: ".spur",
   configFile: ".spur/config.yaml",
   databaseFile: ".spur/spur.db"
@@ -92879,7 +93041,7 @@ ${result.content}`);
     '`SPUR_PROVENANCE_OVERRIDE=1 spur task update <wbs> done --force-done --reason "\u2026"`.',
     "See the gate checklist (spur-dev/references/gate-checklists.md)."
   ].join(`
-`)).option("--section <name>", "Section name to replace").option("--from-file <path>", "File to read section body from (requires --section)").option("--feature <id>", "Set the feature_id frontmatter field (traceability edge)").option("--priority <p>", "Set the priority frontmatter field (P0\u2013P3)").option("--ac-numbering <mode>", "Set the ac_numbering frontmatter field (task-local) \u2014 opts the task into the Requirements\u2194AC coverage check").option("--no-lifecycle", "Suppress lifecycle workflow run creation (use during pipeline runs to avoid orphaned lifecycle runs)").option("--force-done", "Allow transitioning to `done` even when the verify verdict is not PASS; records an override (task 0292)").option("--reason <text>", "Rationale for a forced-done override (paired with --force-done; persisted as done_reason)").option("--verdict-dir <path>", "Directory holding <wbs>-verdict.json artifacts (default: .spur/run)").option("--folder <path>", "Custom tasks folder").option("--json", "Output machine-readable JSON").action(async (wbs, status, options) => {
+`)).option("--section <name>", "Section name to replace").option("--from-file <path>", "File to read section body from (requires --section)").option("--feature <id>", "Set the feature_id frontmatter field (traceability edge)").option("--priority <p>", "Set the priority frontmatter field (P0\u2013P3)").option("--ac-numbering <mode>", "Set the ac_numbering frontmatter field (task-local) \u2014 opts the task into the Requirements\u2194AC coverage check").option("--no-lifecycle", "Suppress lifecycle workflow run creation (use during pipeline runs to avoid orphaned lifecycle runs)").option("--force-done", "Allow transitioning to `done` even when the verify verdict is not PASS; records an override (task 0292). Waives the verdict only \u2014 the FSM path still applies, so from an earlier status walk the hops first: `todo` \u2192 `wip` \u2192 `testing` \u2192 `done` (each hop runs the structural `spur task check`)").option("--reason <text>", "Rationale for a forced-done override (paired with --force-done; persisted as done_reason)").option("--verdict-dir <path>", "Directory holding <wbs>-verdict.json artifacts (default: .spur/run)").option("--folder <path>", "Custom tasks folder").option("--json", "Output machine-readable JSON").action(async (wbs, status, options) => {
     const svc = await makeService2(context4, options.folder, options.lifecycle === false);
     try {
       if (options.section !== undefined) {