@gobing-ai/spur 0.3.94 → 0.3.95

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.94",
+    "version": "0.3.95",
     "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",
@@ -24,12 +24,16 @@
         "spur": "spur.js"
     },
     "exports": {
-        "./schemas/*": "./schemas/*"
+        "./schemas/*": "./schemas/*",
+        "./board": {
+            "types": "./board/index.d.ts"
+        }
     },
     "files": [
         "spur.js",
         "config",
         "schemas",
+        "board",
         "web",
         "README.md",
         "plugins/",
@@ -45,7 +49,7 @@
         "dev": "bun run src/index.ts",
         "build": "bun run ../../scripts/spur-dev.ts build-cli",
         "build:binaries": "bun run ../../scripts/spur-dev.ts build-binaries",
-        "build:bundle": "bun run ../../scripts/spur-dev.ts bundle-web && bun build src/index.ts --target=bun --outfile spur.js && bun run ../../scripts/spur-dev.ts bundle-config config && bun run ../../scripts/spur-dev.ts bundle-plugins",
+        "build:bundle": "bun run ../../scripts/spur-dev.ts bundle-web && bun run ../../scripts/spur-dev.ts emit-board-types && bun build src/index.ts --target=bun --outfile spur.js && bun run ../../scripts/spur-dev.ts bundle-config config && bun run ../../scripts/spur-dev.ts bundle-plugins",
         "test": "bun test tests --coverage --coverage-dir=../../.coverage --pass-with-no-tests",
         "typecheck": "tsc --noEmit",
         "prepack": "bun run build:bundle",
@@ -53,14 +57,14 @@
     },
     "devDependencies": {
         "@commander-js/extra-typings": "^14.0.0",
-        "@gobing-ai/ts-db": "^0.5.9",
-        "@gobing-ai/ts-ai-runner": "^0.5.9",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.5.9",
-        "@gobing-ai/ts-infra": "^0.5.9",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.5.9",
-        "@gobing-ai/ts-rule-engine": "^0.5.9",
-        "@gobing-ai/ts-runtime": "^0.5.9",
-        "@gobing-ai/ts-utils": "^0.5.9",
+        "@gobing-ai/ts-db": "^0.5.11",
+        "@gobing-ai/ts-ai-runner": "^0.5.11",
+        "@gobing-ai/ts-dual-workflow-engine": "^0.5.11",
+        "@gobing-ai/ts-infra": "^0.5.11",
+        "@gobing-ai/ts-llm-jsonl-importer": "^0.5.11",
+        "@gobing-ai/ts-rule-engine": "^0.5.11",
+        "@gobing-ai/ts-runtime": "^0.5.11",
+        "@gobing-ai/ts-utils": "^0.5.11",
         "@types/bun": "1.3.14",
         "@types/figlet": "^1.7.0",
         "@types/node-notifier": "8.0.5",

package/plugins/sp/commands/dev-verify.md

@@ -40,10 +40,13 @@ See `sp:code-verification` § Shippable readiness gate.
 
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
 - `Skill(skill="sp:code-verification", args="verify $ARGUMENTS")`
-- **Residual sweep (F96 R1):** after the verify answer is written and `task verdict` derives
-  `.spur/run/<wbs>-verdict.json`, run `residual-scan scan` + `fold` (observe-only; folds the
-  verdict's `residual-sweep` check, PASS → PARTIAL when a blocking residual exists) — under every
-  `--fix` mode — before `spur task record`. Resolve the script via `superskill script path sp
+- **Residual sweep (F96 R1, post-record since 0987):** after `task verdict` derives
+  `.spur/run/<wbs>-verdict.json` and `spur task record` has flipped the verdict-proven R/AC boxes,
+  run `residual-scan scan` + `fold` (observe-only; folds the verdict's `residual-sweep` check,
+  PASS → PARTIAL when a blocking residual exists) — under every `--fix` mode — then, only on a
+  downgrade, re-run `spur task record <wbs> --verdict-file .spur/run/<wbs>-verdict.json` so Testing
+  carries the final verdict. Same order as the pipeline `record` state (0983): scanning before
+  record reads unticked-but-proven boxes and folds a clean PASS to PARTIAL. Resolve the script via `superskill script path sp
   residual-scan.mjs`; never reference `plugins/sp/scripts/` in shipped surfaces
   (script-contract-check rule 4). When the task reaches `done` through `--next`, run
   `residual-scan settle` (best-effort). On a folded PARTIAL: the bounded remediation loop has

package/plugins/sp/commands/dev-verifyall.md

@@ -72,8 +72,9 @@ Without `--fix all`, shippable is not evaluated (optional note: use `--fix all`
 - Batch orchestration: `Skill(skill="sp:spur-dev", args="verifyall $ARGUMENTS")`
 - Per-task verification (inner): `Skill(skill="sp:code-verification", args="verify <wbs> $SHARED_FLAGS")`
 - Shippable gate: once after the batch (same skill § Shippable readiness gate)
-- **Residual sweep (F96 R1, per task):** same contract as `/sp:dev-verify` — after each task's
-  verdict artifact is derived, run `residual-scan scan` + `fold` (under every `--fix` mode) before
-  `spur task record`; on reaching `done` via `--next`, run `settle`. Script resolution:
+- **Residual sweep (F96 R1, per task, post-record since 0987):** same contract as
+  `/sp:dev-verify` — after each task's verdict artifact is derived and `spur task record` has
+  flipped its verdict-proven boxes, run `residual-scan scan` + `fold` (under every `--fix` mode),
+  and re-record only on a downgrade; on reaching `done` via `--next`, run `settle`. Script resolution:
   `superskill script path sp residual-scan.mjs` (never `plugins/sp/scripts/` —
   script-contract-check rule 4).

package/plugins/sp/commands/dev-wrap.md

@@ -17,7 +17,7 @@ Wraps the **wrapup-pipeline.yaml** workflow.
 | `--agent` `<inline\|auto\|name>` | Who runs the wrap's model-bearing steps. Wrap is workflow-backed (headless): `omit` and `--agent inline` resolve identically per task 0687 — tier substitution under objective trigger 3 (durable auditable run record required) with a warning naming the substituted executor; `auto` tier-resolves an executor; a name pins that executor into `vars.agent`. | inline |
 | `--auto` | Skip objective HITL gates. | off |
 | `--merge` | Merge the wrap branch. | off |
-| `--dry-run` | Render the wrap without writing. | off |
+| `--dry-run` | Validate and walk transitions without executing actions. Conditional states therefore resolve to their declared failure edges (their guard files are never written), so a render ending in `failed` is **not** a run failure — it reports "this state's route cannot be decided without running it". Use a real run to preview a route. | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 

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

@@ -34,7 +34,7 @@ export const REDACTION_CAP_BYTES = 4096;
 /** Max command/pattern summary length before ellipsis (chars). */
 export const SUMMARY_MAX_CHARS = 200;
 
-interface ToolPayload {
+export interface ToolPayload {
     session_id?: string;
     tool_name?: string;
     tool_input?: {
@@ -115,7 +115,7 @@ export function redactText(text: string, capBytes: number = REDACTION_CAP_BYTES)
     if (bytes.length <= capBytes) return s;
     // Truncate on byte boundary then append marker
     let end = capBytes;
-    while (end > 0 && (bytes[end] & 0xc0) === 0x80) end--;
+    while (end > 0 && ((bytes[end] ?? 0) & 0xc0) === 0x80) end--;
     return `${new TextDecoder().decode(bytes.subarray(0, end))}…[truncated]`;
 }
 

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

@@ -126,6 +126,7 @@ export function recordSessionStart(
     dir: string,
     env: NodeJS.ProcessEnv = getEnvVars(),
     now: () => Date = () => new Date(),
+    agentFallback?: string,
 ): string | null {
     try {
         mkdirSync(dir, { recursive: true });
@@ -140,7 +141,7 @@ export function recordSessionStart(
     const pad = (n: number) => String(n).padStart(2, '0');
     const sessionId = `session-${at.toISOString().slice(0, 10)}-${pad(at.getHours())}${pad(at.getMinutes())}`;
     const ts = at.toISOString();
-    const agent = resolveAgentHint(env);
+    const agent = resolveAgentHint(env, agentFallback);
     const model = resolveModelHint(env);
 
     const sessionBody: Record<string, unknown> = {

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

@@ -49,30 +49,30 @@ function computeSessionTotals(
     return { reads, writes, tokens };
 }
 
-function exitOk(): never {
-    process.exit(0);
-}
-
-async function main(): Promise<void> {
-    const dir = join(getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd(), '.spur', 'context');
-
+/**
+ * Finalize one session (task 0969 R3): read the `.session.json` pointer, compute the session's
+ * rollup totals, append the `session_end` row, remove the pointer (best-effort) and return the
+ * event. Shared by this hook's entrypoint and Pi's `session_shutdown` so both hosts roll up
+ * identically. Returns null on every fail-open path.
+ */
+export function recordSessionEnd(dir: string, now: () => Date = () => new Date()): Record<string, unknown> | null {
     const sessionFile = join(dir, '.session.json');
-    if (!existsSync(sessionFile)) exitOk();
+    if (!existsSync(sessionFile)) return null;
 
     let sessionId = '';
     try {
         const session = JSON.parse(readFileSync(sessionFile, 'utf-8')) as { session?: string };
         sessionId = session.session ?? '';
     } catch {
-        exitOk();
+        return null;
     }
 
-    if (!sessionId) exitOk();
+    if (!sessionId) return null;
 
     const totals = computeSessionTotals(join(dir, 'token-ledger.jsonl'), sessionId);
 
     const event = {
-        ts: new Date().toISOString(),
+        ts: now().toISOString(),
         session: sessionId,
         type: 'session_end' as const,
         totals,
@@ -81,7 +81,7 @@ async function main(): Promise<void> {
     try {
         appendFileSync(join(dir, 'token-ledger.jsonl'), `${JSON.stringify(event)}\n`);
     } catch {
-        exitOk();
+        return null;
     }
 
     try {
@@ -90,7 +90,15 @@ async function main(): Promise<void> {
         // cleanup is best-effort
     }
 
-    exitOk();
+    return event;
 }
 
-void main().catch(exitOk);
+// Entrypoint: run the shared core, then exit 0 (fail-open) as this hook always has.
+if (import.meta.main) {
+    try {
+        recordSessionEnd(join(getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd(), '.spur', 'context'));
+    } catch {
+        /* fail-open: every error path exits 0 */
+    }
+    process.exit(0);
+}

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

@@ -7,9 +7,12 @@
  * Implements:
  *   - task-write-guard  (tool_call → block Write/Edit to Spur task files)
  *   - careful-guard     (tool_call → warn on destructive Bash commands)
- *   - context-post-tool (tool_result → append to token-ledger.jsonl)
- *   - context-session-start (session_start → init .session.json)
- *   - context-session-stop  (session_shutdown → rollup + cleanup)
+ *   - context-post-tool (tool_result → shared recordToolUseEvent)
+ *   - context-session-start (session_start → shared recordSessionStart)
+ *   - context-session-stop  (session_shutdown → shared recordSessionEnd)
+ *
+ * The ledger and session cores are shared with the Claude hooks (task 0969): this
+ * extension only normalizes Pi event shapes and adapts them to those cores.
  *
  * Installation:
  *   Add to ~/.pi/agent/settings.json packages:
@@ -19,13 +22,14 @@
  */
 
 import { spawnSync } from 'node:child_process';
-import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, realpathSync } from 'node:fs';
 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 '../../lib/env';
-import { resolveAgentHint as resolveAgentHintShared, resolveModelHint as resolveModelHintShared } from '../agent-hint';
-import { cappedByteLength, truncateSummary } from '../context-post-tool';
+import { recordToolUseEvent, type ToolPayload } from '../context-post-tool';
+import { recordSessionStart } from '../context-session-start';
+import { recordSessionEnd } from '../context-session-stop';
 import { classifyCommand } from '../destructive-policy';
 import { couldBeTaskFile } from '../task-file-policy';
 
@@ -35,8 +39,6 @@ import { couldBeTaskFile } from '../task-file-policy';
 // 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');
 
 // ─── Helpers ─────────────────────────────────────────────────────────────
 
@@ -113,137 +115,86 @@ function resolveSpurTaskOwnership(filePath: string): TaskOwnership {
 // `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) ──────────────────
-
-interface ToolEvent {
-    session_id?: string;
-    tool_name?: string;
-    tool_input?: Record<string, unknown>;
-}
-
-// Summaries persist to disk, so they go through the same scrubber as the Claude hook —
-// the local copy this replaced stored the raw command (secrets included) as `summary`.
-function summarizeToolEvent(event: ToolEvent): string {
-    const input = event.tool_input ?? {};
-    const candidates = [input.file_path, input.command, input.pattern, input.glob_pattern, input.glob, input.path];
-    for (const c of candidates) {
-        if (typeof c === 'string' && c.trim()) return truncateSummary(c);
-    }
-    return `(${event.tool_name ?? 'unknown'})`;
-}
-
-function appendToLedger(event: ToolEvent, command: string | undefined): void {
-    try {
-        if (!existsSync(spurContextDir())) return;
-        const sessionId = readSessionId();
-        if (!sessionId) return;
-
-        const summary = summarizeToolEvent(event);
-        const tokens = command ? Math.ceil(cappedByteLength(command) / 4) : 0;
-        const input = event.tool_input ?? {};
-        // Pi tool names are lowercase (`read`) and its write/edit tools take `path`, not `file_path`.
-        const path = typeof input.file_path === 'string' ? input.file_path : input.path;
-
-        const ledgerEntry = JSON.stringify({
-            session: sessionId,
-            type: event.tool_name?.toLowerCase() === 'read' ? 'read' : 'write',
-            tool: event.tool_name,
-            file: typeof path === 'string' ? path : undefined,
-            summary,
-            tokens,
-            ts: new Date().toISOString(),
-        });
-
-        appendFileSync(ledgerFilePath(), `${ledgerEntry}\n`);
-    } catch {
-        // fail-open: skip ledger writes on error
-    }
-}
-
-function readSessionId(): string | undefined {
-    try {
-        if (!existsSync(sessionFilePath())) return undefined;
-        const data = JSON.parse(readFileSync(sessionFilePath(), 'utf-8')) as { session_id?: string };
-        return data.session_id;
-    } catch {
-        return undefined;
-    }
-}
-
-// ─── Session helpers (agent/model hints from agent-hint.ts; mirrors context-session-stop.ts) ─
-
-function generateSessionId(): string {
-    const timestamp = Date.now().toString(36);
-    const random = Math.random().toString(36).slice(2, 10);
-    return `${timestamp}-${random}`;
-}
-
-function initSession(): void {
-    try {
-        mkdirSync(spurContextDir(), { recursive: true });
-        const sessionId = generateSessionId();
-        const session = {
-            session_id: sessionId,
-            agent: resolveAgentHintShared(getEnvVars(), 'pi'),
-            model: resolveModelHintShared(getEnvVars()),
-            started_at: new Date().toISOString(),
-        };
-        writeFileSync(sessionFilePath(), `${JSON.stringify(session, null, 2)}\n`);
-
-        // Append session_start event to ledger
-        const startEntry = JSON.stringify({
-            session: sessionId,
-            type: 'session_start',
-            agent: session.agent,
-            model: session.model,
-            ts: session.started_at,
-        });
-        appendFileSync(ledgerFilePath(), `${startEntry}\n`);
-    } catch {
-        // fail-open
+// ─── Pi → Claude payload normalization (task 0969 R1) ─────────────────────
+
+/** Pi tool name → the Claude tool name the shared core records. */
+const PI_TO_CLAUDE: Record<string, string> = {
+    read: 'Read',
+    write: 'Write',
+    edit: 'Edit',
+    bash: 'Bash',
+    grep: 'Grep',
+    find: 'Glob',
+};
+
+/** Join the text parts of a Pi tool_result `content` payload. */
+function piContentText(content: unknown): string {
+    if (typeof content === 'string') return content;
+    if (!Array.isArray(content)) return '';
+    const parts: string[] = [];
+    for (const part of content) {
+        if (part && typeof part === 'object' && typeof (part as { text?: unknown }).text === 'string') {
+            parts.push((part as { text: string }).text);
+        }
     }
+    return parts.join('\n');
 }
 
-function cleanupSession(): void {
-    try {
-        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(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 };
-                    if (evt.session !== sessionId) continue;
-                    if (evt.type === 'read') reads++;
-                    else if (evt.type === 'write') writes++;
-                    if (evt.tokens) tokens += evt.tokens;
-                } catch {
-                    // skip unparseable lines
-                }
-            }
+/**
+ * Pure Pi-event → Claude-{@link ToolPayload} adapter. An unmapped tool returns null so the
+ * shared core writes no row (R1's row filter). Search tools keep `path` (never `file_path`)
+ * because the core treats `file_path` as the written file, not a search root.
+ */
+export function normalizePiToolEvent(
+    toolName: string,
+    input: Record<string, unknown> | undefined,
+    content?: unknown,
+): ToolPayload | null {
+    const mapped = PI_TO_CLAUDE[toolName];
+    if (mapped === undefined) return null;
+    const i = input ?? {};
+    const str = (value: unknown): string => (typeof value === 'string' ? value : '');
+    const path = str(i.path) || str(i.file_path);
+    const text = piContentText(content);
+    const tool_response = text.length > 0 ? { content: text } : undefined;
+
+    switch (mapped) {
+        case 'Read':
+            return { tool_name: mapped, tool_input: { file_path: path }, tool_response };
+        case 'Write':
+            return { tool_name: mapped, tool_input: { file_path: path, content: str(i.content) }, tool_response };
+        case 'Edit': {
+            const edits = Array.isArray(i.edits) ? (i.edits as Array<Record<string, unknown>>) : [];
+            return {
+                tool_name: mapped,
+                tool_input: {
+                    file_path: path,
+                    old_string: edits.map((e) => str(e.oldText)).join(''),
+                    new_string: edits.map((e) => str(e.newText)).join(''),
+                },
+                tool_response,
+            };
         }
-
-        // Append session_end event
-        const endEntry = JSON.stringify({
-            session: sessionId,
-            type: 'session_end',
-            reads,
-            writes,
-            tokens,
-            ts: new Date().toISOString(),
-        });
-        appendFileSync(ledgerFilePath(), `${endEntry}\n`);
-
-        // Cleanup session file
-        rmSync(sessionFilePath(), { force: true });
-    } catch {
-        // fail-open
+        case 'Grep':
+            return {
+                tool_name: mapped,
+                tool_input: {
+                    pattern: str(i.pattern),
+                    ...(path ? { path } : {}),
+                    ...(str(i.glob) ? { glob: str(i.glob) } : {}),
+                },
+                tool_response,
+            };
+        case 'Glob':
+            return {
+                tool_name: mapped,
+                tool_input: { pattern: str(i.pattern), ...(path ? { path } : {}) },
+                tool_response,
+            };
+        case 'Bash':
+            return { tool_name: mapped, tool_input: { command: str(i.command) }, tool_response };
+        default:
+            return null;
     }
 }
 
@@ -284,27 +235,35 @@ export default function (pi: ExtensionAPI): void {
         return {};
     });
 
-    // ── context-post-tool: append to token-ledger.jsonl ───────────────
+    // ── context-post-tool: shared recordToolUseEvent (task 0969 R1) ──
     pi.on('tool_result', async (event) => {
-        const input = event.input as Record<string, unknown> | undefined;
-        const command = typeof input?.command === 'string' ? input.command : undefined;
-        appendToLedger(
-            {
-                session_id: readSessionId(),
-                tool_name: event.toolName,
-                tool_input: input as Record<string, unknown>,
-            },
-            command,
-        );
+        try {
+            const payload = normalizePiToolEvent(
+                event.toolName,
+                event.input as Record<string, unknown> | undefined,
+                (event as { content?: unknown }).content,
+            );
+            if (payload) recordToolUseEvent(spurContextDir(), payload);
+        } catch {
+            // fail-open
+        }
     });
 
-    // ── context-session-start: init session tracking ─────────────────
+    // ── context-session-start: shared recordSessionStart (R2) ────────
     pi.on('session_start', async () => {
-        initSession();
+        try {
+            recordSessionStart(spurContextDir(), getEnvVars(), undefined, 'pi');
+        } catch {
+            // fail-open
+        }
     });
 
-    // ── context-session-stop: rollup + cleanup ───────────────────────
+    // ── context-session-stop: shared recordSessionEnd (R3) ──────────
     pi.on('session_shutdown', async () => {
-        cleanupSession();
+        try {
+            recordSessionEnd(spurContextDir());
+        } catch {
+            // fail-open
+        }
     });
 }