@gobing-ai/spur 0.3.84 → 0.3.86

package/config/workflows/wrapup-pipeline.yaml

@@ -13,10 +13,12 @@
 # pauses,
 # even under --auto (Iron Law #6: irreversible action -> surface to human).
 #
-# Shape: start -> task-resolve -> doc-sync -> metrics-record
+# Shape: start -> task-resolve -> doc-sync -> learnings-append -> metrics-record
 #          -> feature-transition (conditional: if vars.feature set)
 #          -> branch-cleanup (conditional: if vars.merge=true)
 #          -> done
+#        doc-sync routes a contract violation to `repair` (cheap, no
+#        re-dispatch — ADR-118 pilot) and an executor failure to `failed`;
 #        task-resolve with a VALIDATED empty list short-circuits to `skipped`;
 #        invalid wrap input, an unresolved/non-completed task, a failed metrics
 #        capture, a failed required sync, or a failed feature gate routes to
@@ -31,7 +33,7 @@
 # merge    — set --vars '{"merge":"true"}' to run branch cleanup (irreversible
 # HITL)
 #   spurBin  — PATH-independent spur invocation (overridden by CLI at run start)
-#   agent    — agent for agent.run steps (default: omp)
+#   agent    — agent for agent.run steps (default: auto → `agent.default` in config)
 #
 # Reliability (aligned with task-pipeline / ADR-043):
 # - Prefer pure slash commands when a command exists; free-form inputs remain
@@ -72,7 +74,7 @@
 "$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
 kind: state-machine
 name: wrapup-pipeline
-version: "3"
+version: "4"
 description: "Post-execution wrap-up: doc-sync (doc drift + learning capture), metrics, feature-transition, branch-cleanup"
 iterationBound: 10
 initialState: start
@@ -168,13 +170,16 @@ states:
       learnings (task 0607 R2: two adjacent agent.run hops merged, count 2 -> 1;
       no operator-decision pause or verdict boundary sits between them). No dedicated
       slash command yet — free-form skill pointer until a /sp:doc-evolve command
-      exists (ADR-043 residual). Capture+shell decoupling preserved: expectFile gates
-      a non-empty capture before the append; append is best-effort soft (empty capture
-      skips without aborting wrap-up).
+      exists (ADR-043 residual). This is the expensive stage; a contract violation
+      (a clean exit that missed its declared answerFile/expectFile post-condition)
+      routes to the cheap `repair` edge instead of a full re-dispatch (ADR-118
+      pilot, 0871) — `onError: continue` lets the transition guards read the
+      agent's result instead of halting the run.
     onEnter:
       # (warn) free-form prompt: no /sp:doc-evolve command surface yet (ADR-043
       # residual, 0607 R2 one-query merge); capture is bounded by expectFile.
       - kind: agent.run
+        onError: continue
         options:
           agent: ${vars.agent}
           input: >-
@@ -192,6 +197,13 @@ states:
           answerFile: .spur/run/${vars.__runId}-wrapup-learnings.md
           expectFile: .spur/run/${vars.__runId}-wrapup-learnings.md
           timeoutMs: ${vars.stepTimeoutMs}
+
+  - id: learnings-append
+    description: >
+      Best-effort soft append of the captured learnings to .spur/memory/learnings.md
+      (0607 R2): an empty capture skips without aborting wrap-up. Runs only after
+      doc-sync's contract held; a contract violation never reaches this state.
+    onEnter:
       # (warn) learnings append is intentionally soft (empty capture skips
       # without aborting wrap-up, 0607 R2).
       - kind: shell
@@ -207,6 +219,21 @@ states:
             fi &&
             exit 0
 
+  - id: repair
+    description: >
+      Contract-violation repair (ADR-118 pilot, 0871): doc-sync's agent.run missed
+      its declared post-condition after a clean exit, so wrap-up does NOT re-dispatch
+      the expensive agent on this attempt. The miss is recorded to a run-scoped
+      repair status and wrap-up proceeds to metrics-record — the run log and action
+      trace already name the violated contract and the observed value.
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run &&
+            printf 'contract-violation: doc-sync learnings capture missed its declared contract — repair skipped re-dispatch (ADR-118 pilot)\n' > ".spur/run/$__runId-wrapup-repair.status" &&
+            exit 0
+
   - id: metrics-record
     description: >
       Append one JSONL row per task to .spur/memory/wrapup-metrics.jsonl deterministically.
@@ -354,10 +381,46 @@ transitions:
     guard:
       kind: always
 
-  # ── linear body: doc-sync -> metrics-record ──
+  # ── doc-sync: contract-first routing (ADR-118 pilot, 0871) ──
+  # Declaration order matters: the contract-violation edge is tried first, then
+  # success (action-ok), then the executor-failure defense (always) — a failed
+  # agent.run reaches these guards because doc-sync's agent.run declares
+  # onError: continue.
   - from: doc-sync
+    to: repair
+    description: >
+      Contract violation (ADR-118): the agent exited 0 but missed its declared
+      post-condition. Route to the cheap repair edge — never re-dispatch the
+      full agent.run on this attempt.
+    trigger: contract-violation
+    guard:
+      kind: contract-violation
+  - from: doc-sync
+    to: learnings-append
+    description: Doc drift repair + learning capture succeeded — append learnings.
+    guard:
+      kind: action-ok
+  - from: doc-sync
+    to: failed
+    description: >
+      Executor failure (non-zero exit, signal, or dispatch error) — keep the
+      existing fail semantics; a contract violation never falls through here
+      because the contract-violation edge is declared first.
+    trigger: executor-failure
+    guard:
+      kind: always
+
+  # ── linear body: learnings-append -> metrics-record ──
+  - from: learnings-append
+    to: metrics-record
+    description: Learning capture appended (or soft-skipped) — record metrics.
+    guard:
+      kind: always
+
+  # ── repair: cheap path, no re-dispatch -> metrics-record ──
+  - from: repair
     to: metrics-record
-    description: Doc drift repair + learning capture complete — record metrics.
+    description: Contract-violation repair recorded — proceed to metrics without re-dispatch.
     guard:
       kind: always
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.84",
+    "version": "0.3.86",
     "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",
@@ -53,14 +53,14 @@
     },
     "devDependencies": {
         "@commander-js/extra-typings": "^14.0.0",
-        "@gobing-ai/ts-db": "^0.4.66",
-        "@gobing-ai/ts-ai-runner": "^0.4.66",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.4.66",
-        "@gobing-ai/ts-infra": "^0.4.66",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.66",
-        "@gobing-ai/ts-rule-engine": "^0.4.66",
-        "@gobing-ai/ts-runtime": "^0.4.66",
-        "@gobing-ai/ts-utils": "^0.4.66",
+        "@gobing-ai/ts-db": "^0.4.67",
+        "@gobing-ai/ts-ai-runner": "^0.4.67",
+        "@gobing-ai/ts-dual-workflow-engine": "^0.4.67",
+        "@gobing-ai/ts-infra": "^0.4.67",
+        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.67",
+        "@gobing-ai/ts-rule-engine": "^0.4.67",
+        "@gobing-ai/ts-runtime": "^0.4.67",
+        "@gobing-ai/ts-utils": "^0.4.67",
         "@types/bun": "1.3.14",
         "@types/figlet": "^1.7.0",
         "@types/node-notifier": "8.0.5",

package/plugins/sp/README.md

@@ -620,14 +620,11 @@ pipeline owns one lifecycle phase:
 
 | Workflow                    | Phase                             | Entry command                     |
 | --------------------------- | --------------------------------- | --------------------------------- |
-| `basic.yaml`                | Generic implement/check/fix       | direct `spur workflow run`        |
 | `feature-lifecycle.yaml`    | Feature status FSM                | `spur feature update`             |
 | `task-lifecycle.yaml`       | Task status FSM                   | `spur task update`                |
 | `task-pipeline.yaml`        | Single-task execution             | `/sp:dev-run`                     |
 | `idea-pipeline.yaml`        | Idea/planning → feature + tasks   | `/sp:dev-idea`, `/sp:dev-plan`    |
-| `feature-dev.yaml`          | Feature umbrella execution        | `/sp:dev-runall --feature`        |
 | `wrapup-pipeline.yaml`      | Post-execution wrap-up            | `/sp:dev-wrap`, `/sp:dev-wrapall` |
-| `docs-pipeline.yaml`        | Docs-only task execution          | `/sp:dev-run --mode implement`    |
 | `wayfinder-resolution.yaml` | Wayfinder ticket resolution loop  | `spur workflow run` (free-form)   |
 
 ### Lifecycle operations

package/plugins/sp/agents/super-planner.md

@@ -97,7 +97,8 @@ You own the spaces **between** task runs:
 You explicitly do **NOT** own step-level execution:
 
 - How an `agent.run` step (implement/test/review/verify) runs is `vars.agent`'s concern - default
-  `omp`, pinned in `task-pipeline.yaml`. `--agent <value>` from the command flows into each
+  `auto` (`agent.default` in config resolves the executor), pinned in `task-pipeline.yaml`.
+  `--agent <value>` from the command flows into each
   per-task `vars.agent`; you forward it, you do not interpret it.
 - You never edit the pipeline YAML, never reach into a step, and never decide how a single
   `agent.run` stage executes. The per-task pipeline is invoked **verbatim**.

package/plugins/sp/hooks/agent-hint.ts

@@ -1,3 +1,4 @@
+import { getEnvVars } from '@gobing-ai/ts-utils';
 /**
  * Shared host-agent identification helpers — the **only** host-agent detection path
  * in the sp plugin hooks.
@@ -22,11 +23,11 @@
  * 3. `TERM_PROGRAM` — terminal identifier (e.g. `claude`, `ghostty`)
  * 4. `SPUR_DEFAULT_AGENT` — configured default agent
  *
- * @param env - environment record (defaults to `process.env`)
+ * @param env - environment record (defaults to `getEnvVars()`)
  * @param fallback - value returned when no candidate matches (defaults to `undefined`)
  */
 export function resolveAgentHint(
-    env: NodeJS.ProcessEnv = process.env,
+    env: NodeJS.ProcessEnv = getEnvVars(),
     fallback: string | undefined = undefined,
 ): string | undefined {
     const candidates = [env.SPUR_AGENT, env.CLAUDE_CODE_ENTRYPOINT, env.TERM_PROGRAM, env.SPUR_DEFAULT_AGENT];
@@ -45,11 +46,11 @@ export function resolveAgentHint(
  * 3. `OPENAI_MODEL` — OpenAI API model
  * 4. `CLAUDE_MODEL` — Claude Code model setting
  *
- * @param env - environment record (defaults to `process.env`)
+ * @param env - environment record (defaults to `getEnvVars()`)
  * @param fallback - value returned when no candidate matches (defaults to `undefined`)
  */
 export function resolveModelHint(
-    env: NodeJS.ProcessEnv = process.env,
+    env: NodeJS.ProcessEnv = getEnvVars(),
     fallback: string | undefined = undefined,
 ): string | undefined {
     const candidates = [env.SPUR_MODEL, env.ANTHROPIC_MODEL, env.OPENAI_MODEL, env.CLAUDE_MODEL];

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

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+
 /**
  * careful-guard — PreToolUse guard for destructive shell commands (task 0215, R3).
  *
@@ -21,6 +22,7 @@
  * adapter. This file owns the Claude Code payload/decision shape only.
  */
 
+import { getEnvVar } from '@gobing-ai/ts-utils';
 import { classifyCommand } from './destructive-policy';
 
 interface ToolPayload {
@@ -43,7 +45,7 @@ function preToolUseDecision(decision: Decision, reason?: string): never {
 }
 
 async function main(): Promise<void> {
-    if (process.env.SPUR_CAREFUL === 'off') preToolUseDecision('allow');
+    if (getEnvVar('SPUR_CAREFUL') === 'off') preToolUseDecision('allow');
 
     const stdinText = await Bun.stdin.text();
     let payload: ToolPayload;

package/plugins/sp/hooks/context-post-tool.ts

@@ -23,6 +23,7 @@
 import { execSync } from 'node:child_process';
 import { appendFileSync, existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
+import { getEnvVar } from '@gobing-ai/ts-utils';
 
 /** Tools recorded by this hook (must match hooks.json PostToolUse matcher). */
 export const ALLOWED_TOOLS = new Set(['Bash', 'Grep', 'Glob', 'Read', 'Write', 'Edit']);
@@ -411,7 +412,7 @@ export function readContextFreshness(contextDir: string): string | null {
 // Entrypoint — thin wrapper; logic lives in {@link recordToolUseEvent} for unit coverage.
 if (import.meta.main) {
     void (async () => {
-        const dir = join(process.env.CLAUDE_PROJECT_DIR ?? process.cwd(), '.spur', 'context');
+        const dir = join(getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd(), '.spur', 'context');
         try {
             const stdinText = await Bun.stdin.text();
             const payload = JSON.parse(stdinText) as ToolPayload;

package/plugins/sp/hooks/context-session-start.ts

@@ -15,6 +15,7 @@
 import { execSync } from 'node:child_process';
 import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { getEnvVar, getEnvVars } from '@gobing-ai/ts-utils';
 import { resolveAgentHint, resolveModelHint } from './agent-hint';
 import { checkContextFreshness } from './context-post-tool';
 
@@ -82,7 +83,7 @@ interface SessionFileBody {
  * a stale file is only reachable from inside a live agent run, where reusing it is the correct
  * answer anyway.
  */
-export function resolveActiveSession(dir: string, now: Date, env: NodeJS.ProcessEnv = process.env): string | null {
+export function resolveActiveSession(dir: string, now: Date, env: NodeJS.ProcessEnv = getEnvVars()): string | null {
     let raw: string;
     try {
         raw = readFileSync(join(dir, '.session.json'), 'utf-8');
@@ -123,7 +124,7 @@ export function resolveActiveSession(dir: string, now: Date, env: NodeJS.Process
  */
 export function recordSessionStart(
     dir: string,
-    env: NodeJS.ProcessEnv = process.env,
+    env: NodeJS.ProcessEnv = getEnvVars(),
     now: () => Date = () => new Date(),
 ): string | null {
     try {
@@ -195,7 +196,7 @@ export function recordSessionStart(
 // Entrypoint — kept minimal so unit coverage focuses on pure helpers above.
 if (import.meta.main) {
     try {
-        recordSessionStart(join(process.env.CLAUDE_PROJECT_DIR ?? process.cwd(), '.spur', 'context'));
+        recordSessionStart(join(getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd(), '.spur', 'context'));
     } catch {
         /* fail-open */
     }

package/plugins/sp/hooks/context-session-stop.ts

@@ -17,6 +17,7 @@
 
 import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
+import { getEnvVar } from '@gobing-ai/ts-utils';
 
 interface LedgerEvent {
     session: string;
@@ -53,7 +54,7 @@ function exitOk(): never {
 }
 
 async function main(): Promise<void> {
-    const dir = join(process.env.CLAUDE_PROJECT_DIR ?? process.cwd(), '.spur', 'context');
+    const dir = join(getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd(), '.spur', 'context');
 
     const sessionFile = join(dir, '.session.json');
     if (!existsSync(sessionFile)) exitOk();

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

@@ -23,6 +23,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSy
 import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { getEnvVar, getEnvVars } from '@gobing-ai/ts-utils';
 import { resolveAgentHint as resolveAgentHintShared, resolveModelHint as resolveModelHintShared } from '../agent-hint';
 import { classifyCommand } from '../destructive-policy';
 import { couldBeTaskFile } from '../task-file-policy';
@@ -81,7 +82,7 @@ function resolveSpurTaskOwnership(filePath: string): TaskOwnership {
         spawnSync(cmd, args, { cwd: process.cwd(), encoding: 'utf-8', timeout: 8000 });
 
     // 1. SPUR_BIN env override (may include args) or `spur` on PATH
-    const envBin = process.env.SPUR_BIN || 'spur';
+    const envBin = getEnvVar('SPUR_BIN') || 'spur';
     const envParts = envBin.split(' ');
     let res = run(envParts[0] ?? 'spur', [...envParts.slice(1), 'task', 'resolve', filePath, '--strict', '--json']);
     // Only 0 (owned) / 1 (unowned) are valid spur exit codes; 127 (interpreter
@@ -203,8 +204,8 @@ function initSession(): void {
         const sessionId = generateSessionId();
         const session = {
             session_id: sessionId,
-            agent: resolveAgentHintShared(process.env, 'pi'),
-            model: resolveModelHintShared(process.env),
+            agent: resolveAgentHintShared(getEnvVars(), 'pi'),
+            model: resolveModelHintShared(getEnvVars()),
             started_at: new Date().toISOString(),
         };
         writeFileSync(sessionFilePath(), `${JSON.stringify(session, null, 2)}\n`);

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

@@ -20,6 +20,7 @@
  */
 
 import { spawnSync } from 'node:child_process';
+import { getEnvVar } from '@gobing-ai/ts-utils';
 import { couldBeTaskFile } from './task-file-policy';
 
 interface ToolPayload {
@@ -40,7 +41,7 @@ function preToolUseDecision(decision: 'allow' | 'deny', reason?: string): never
 
 /** Resolve whether a path is owned by a Spur task via `spur task resolve --strict --json`. */
 function resolveSpurTaskOwnership(filePath: string, cwd: string): TaskOwnership {
-    const spurBin = process.env.SPUR_BIN || 'spur';
+    const spurBin = getEnvVar('SPUR_BIN') || 'spur';
     const parts = spurBin.split(' ');
     const cmd = parts[0] ?? 'spur';
     const args = [...parts.slice(1), 'task', 'resolve', filePath, '--strict', '--json'];
@@ -54,7 +55,7 @@ function resolveSpurTaskOwnership(filePath: string, cwd: string): TaskOwnership
 }
 
 async function main(): Promise<void> {
-    if (process.env.SPUR_WRITE_GUARD === 'off') preToolUseDecision('allow');
+    if (getEnvVar('SPUR_WRITE_GUARD') === 'off') preToolUseDecision('allow');
 
     const stdinText = await Bun.stdin.text();
     let payload: ToolPayload;
@@ -73,7 +74,7 @@ async function main(): Promise<void> {
     // 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());
+    const ownership = resolveSpurTaskOwnership(filePath, getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd());
     if (ownership === 'owned') {
         preToolUseDecision(
             'deny',