@gobing-ai/spur 0.3.71 → 0.3.73

package/plugins/sp/scripts/daily-summary/daily-summary.ts

@@ -59,6 +59,30 @@ export interface UserAnnotations {
     pending: string;
 }
 
+export interface HistoryLoopFinding {
+    toolName: string;
+    argsDigest: string;
+    repeats: number;
+    sessionId: string;
+    fromSeq?: number;
+    toSeq?: number;
+    wastedTokens: number;
+}
+
+export interface HistoryHealthSummary {
+    toolCalls: number;
+    toolErrors: number;
+    errorRatePct: number;
+    loops: HistoryLoopFinding[];
+    redundantCalls: number;
+    wastedTokens: number;
+    remediationProposals: Array<{
+        key: string;
+        title: string;
+        command: string;
+    }>;
+}
+
 export interface DailySummary {
     date: string;
     platforms: string[];
@@ -77,6 +101,8 @@ export interface DailySummary {
     };
     commits: GitCommit[];
     annotations: UserAnnotations;
+    /** Health metrics and loop findings from Spur history analytics. */
+    historyHealth?: HistoryHealthSummary;
     /** Path to the newest history report artifact (R7), resolved from the
      * `.spur/reports/history/latest.json` pointer. Omitted when no report exists. */
     historyReportPath?: string;
@@ -257,6 +283,120 @@ export async function getCcusageData(date: string): Promise<CcusageData | null>
     }
 }
 
+// ─── Spur History Health Integration ──────────────────────────────────────────
+
+export async function getSpurHistoryHealth(
+    date: string,
+    dbPath = '.spur/spur.db',
+): Promise<HistoryHealthSummary | null> {
+    try {
+        const resolvedPath = resolve(process.cwd(), dbPath);
+        if (!existsSync(resolvedPath)) {
+            return null;
+        }
+
+        const { Database } = await import('bun:sqlite');
+        const db = new Database(resolvedPath, { readonly: true });
+
+        try {
+            // 1. Query execution loop findings
+            const loopTable = db
+                .query<{ name: string }, [string]>("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?")
+                .get('history_board_loop_findings');
+
+            let loops: HistoryLoopFinding[] = [];
+            if (loopTable) {
+                const rows = db
+                    .query<
+                        {
+                            tool_name: string;
+                            args_digest: string;
+                            repeats: number;
+                            session_id: string;
+                            first_seq: number;
+                            last_seq: number;
+                            started_at: string | null;
+                        },
+                        [string]
+                    >(
+                        `SELECT tool_name, args_digest, repeats, session_id, first_seq, last_seq, started_at
+                         FROM history_board_loop_findings
+                         WHERE started_at IS NULL OR started_at LIKE ?
+                         ORDER BY repeats DESC
+                         LIMIT 20`,
+                    )
+                    .all(`${date}%`);
+
+                loops = rows.map((r) => ({
+                    toolName: r.tool_name,
+                    argsDigest: r.args_digest || 'repeated execution',
+                    repeats: r.repeats,
+                    sessionId: r.session_id,
+                    fromSeq: r.first_seq,
+                    toSeq: r.last_seq,
+                    wastedTokens: r.repeats * 250,
+                }));
+            }
+
+            // 2. Query tool calls and errors
+            let toolCalls = 0;
+            let toolErrors = 0;
+            const toolTable = db
+                .query<{ name: string }, [string]>("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?")
+                .get('history_board_tool_5m');
+
+            if (toolTable) {
+                const stats = db
+                    .query<{ calls: number | null; errors: number | null }, [string]>(
+                        `SELECT SUM(calls) AS calls, SUM(errors) AS errors
+                         FROM history_board_tool_5m
+                         WHERE bucket_start LIKE ?`,
+                    )
+                    .get(`${date}%`);
+
+                toolCalls = stats?.calls ?? 0;
+                toolErrors = stats?.errors ?? 0;
+            }
+
+            const redundantCalls = loops.reduce((acc, l) => acc + Math.max(0, l.repeats - 1), 0);
+            const wastedTokens = loops.reduce((acc, l) => acc + l.wastedTokens, 0);
+            const errorRatePct = toolCalls > 0 ? (toolErrors / toolCalls) * 100 : 0;
+
+            // 3. Generate auto-healing remediation proposals
+            const remediationProposals: Array<{ key: string; title: string; command: string }> = [];
+
+            for (const lp of loops.slice(0, 5)) {
+                const cleanTool = lp.toolName.replace(/[^a-zA-Z0-9_-]/g, '_');
+                const key = `repetition:${cleanTool}:${lp.argsDigest.slice(0, 16)}`;
+                const title = `Break execution loop in ${lp.toolName} (${lp.repeats} repeats)`;
+                const command = `spur task create "<title>" --feature <id> && spur task update <wbs> --section Plan --from-file <path>`;
+                remediationProposals.push({ key, title, command });
+            }
+
+            if (toolCalls > 0 && errorRatePct > 10) {
+                const key = 'reliability:tooling:high-error-rate';
+                const title = `Investigate high tool error rate (${errorRatePct.toFixed(1)}%)`;
+                const command = `spur task create "<title>" --feature <id> && spur task update <wbs> --section Plan --from-file <path>`;
+                remediationProposals.push({ key, title, command });
+            }
+
+            return {
+                toolCalls,
+                toolErrors,
+                errorRatePct,
+                loops,
+                redundantCalls,
+                wastedTokens,
+                remediationProposals,
+            };
+        } finally {
+            db.close();
+        }
+    } catch {
+        return null;
+    }
+}
+
 // ─── Git Integration ─────────────────────────────────────────────────────────
 
 export async function getGitCommits(date: string): Promise<GitCommit[]> {
@@ -477,6 +617,61 @@ export function generateMarkdown(summary: DailySummary): string {
         lines.push('');
     }
 
+    // Execution Loops & Health Findings
+    if (summary.historyHealth) {
+        const hh = summary.historyHealth;
+        lines.push('## Execution Loops & Health Findings');
+        lines.push('');
+
+        if (hh.loops.length === 0 && hh.toolCalls === 0) {
+            lines.push('- **Status:** ✅ Clean — No execution loops or tool calls recorded for this date.');
+            lines.push('');
+        } else {
+            lines.push('| Metric | Value |');
+            lines.push('|--------|-------|');
+            lines.push(`| Tool Invocations | ${hh.toolCalls.toLocaleString()} |`);
+            lines.push(`| Tool Errors | ${hh.toolErrors.toLocaleString()} (${hh.errorRatePct.toFixed(1)}%) |`);
+            lines.push(`| Detected Loops (Repeats ≥ 3) | ${hh.loops.length} |`);
+            lines.push(`| Redundant Invocations | ${hh.redundantCalls.toLocaleString()} |`);
+            lines.push(`| Estimated Wasted Tokens | ${hh.wastedTokens.toLocaleString()} |`);
+            lines.push('');
+
+            if (hh.loops.length > 0) {
+                lines.push('### Detected Execution Loops');
+                lines.push('');
+                for (const lp of hh.loops.slice(0, 10)) {
+                    const seqInfo = lp.fromSeq && lp.toSeq ? ` (steps #${lp.fromSeq} → #${lp.toSeq})` : '';
+                    const argsHint =
+                        lp.argsDigest === '74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b'
+                            ? 'empty/unrecorded arguments'
+                            : lp.argsDigest.length > 28
+                              ? `${lp.argsDigest.slice(0, 24)}...`
+                              : lp.argsDigest;
+                    lines.push(
+                        `- \`${lp.toolName || 'unknown'}\` × **${lp.repeats} repeats** in session \`${lp.sessionId}\`${seqInfo}`,
+                    );
+                    lines.push(`  - *Args hint:* \`${argsHint}\` (~${lp.wastedTokens.toLocaleString()} wasted tokens)`);
+                }
+                lines.push('');
+            }
+
+            if (hh.remediationProposals.length > 0) {
+                lines.push('### Auto-Healing Remediation Proposals');
+                lines.push('');
+                lines.push('To remediate root causes and prevent recurring token waste, execute:');
+                lines.push('');
+                lines.push('```bash');
+                for (const prop of hh.remediationProposals) {
+                    lines.push(`# ${prop.title} [${prop.key}]`);
+                    lines.push(prop.command);
+                    lines.push('');
+                }
+                lines.push('```');
+                lines.push('');
+            }
+        }
+    }
+
     // History report path (R7 — surfaces the newest nightly-run artifact).
     if (summary.historyReportPath) {
         lines.push('## History Report');
@@ -598,6 +793,13 @@ export async function buildDailySummary(options: CliOptions): Promise<DailySumma
         result.gitActivity = gitActivity;
     }
 
+    // Query Spur history health (loops, tool errors, and auto-healing proposals)
+    const historyHealth = await getSpurHistoryHealth(options.date);
+    if (historyHealth && (historyHealth.loops.length > 0 || historyHealth.toolCalls > 0)) {
+        result.historyHealth = historyHealth;
+        platforms.push('Spur History');
+    }
+
     return result;
 }
 

package/plugins/sp/scripts/inline-pipeline-parity-check.ts

@@ -0,0 +1,185 @@
+#!/usr/bin/env bun
+/**
+ * inline-pipeline-parity-check — two-sided gate between the inline pipeline
+ * driver's documented action/guard set and the resolved action/guard sets in
+ * `.spur/workflows/task-pipeline.yaml` and `.spur/workflows/idea-pipeline.yaml`
+ * (task 0755 R2/R3).
+ *
+ * The driver reference at `plugins/sp/skills/spur-dev/references/inline-pipeline-driver.md`
+ * documents the set of action and guard kinds it implements. The two runtime
+ * pipelines are the only consumers the driver needs to keep in step with. The
+ * check is a symmetric set diff: an element present in one and absent in the
+ * other fails the check and names the element.
+ *
+ * The set is defined in {@link DOCUMENTED} below; the driver's markdown list is
+ * the human mirror. Update both when the driver adds or drops a kind.
+ *
+ * Usage:
+ *   bun plugins/sp/scripts/inline-pipeline-parity-check.ts
+ *     [--root <path>]               default: repo root
+ *
+ * Exit code: 0 when the sets agree; 1 on any divergence. Violations are printed
+ * to stderr; a summary to stdout.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+
+/** Documented action and guard set. Must stay in lockstep with the
+ *  "Supported action and guard set (0755 R2 parity contract)" section in
+ *  `plugins/sp/skills/spur-dev/references/inline-pipeline-driver.md`. The
+ *  driver supports a kind if ANY workflow in `.spur/workflows/*.yaml` uses
+ *  it (the driver applies to any selected pipeline per its reference doc). */
+const DOCUMENTED = {
+    actions: new Set([
+        'shell',
+        'note',
+        'doctor.probe',
+        'file.read.into-var',
+        'hitl.confirm',
+        'agent.run',
+        'proof.fingerprint',
+        'run.artifact',
+        'command.gate',
+    ]),
+    guards: new Set(['always', 'shell']),
+} as const;
+
+/** Directory of workflow definitions the driver is responsible for. */
+const WORKFLOW_DIR = join('config', 'workflows');
+
+/** Walk a state list and yield every `kind:` value found in `onEnter` action
+ *  lists. Skips the top-level workflow `kind:` (e.g. `state-machine`). */
+function collectActionKinds(states: unknown): Set<string> {
+    const out = new Set<string>();
+    if (!Array.isArray(states)) return out;
+    for (const state of states) {
+        if (typeof state !== 'object' || state === null) continue;
+        const onEnter = (state as { onEnter?: unknown }).onEnter;
+        if (!Array.isArray(onEnter)) continue;
+        for (const action of onEnter) {
+            if (typeof action !== 'object' || action === null) continue;
+            const kind = (action as { kind?: unknown }).kind;
+            if (typeof kind === 'string') out.add(kind);
+        }
+    }
+    return out;
+}
+
+/** Walk a transition list and yield every `guard.kind` value. */
+function collectGuardKinds(transitions: unknown): Set<string> {
+    const out = new Set<string>();
+    if (!Array.isArray(transitions)) return out;
+    for (const transition of transitions) {
+        if (typeof transition !== 'object' || transition === null) continue;
+        const guard = (transition as { guard?: { kind?: unknown } }).guard;
+        const kind = guard?.kind;
+        if (typeof kind === 'string') out.add(kind);
+    }
+    return out;
+}
+
+/** Symmetric set diff. Returns elements in `a` but not in `b`, and vice versa. */
+function diff<T>(a: Set<T>, b: Set<T>): { onlyInA: T[]; onlyInB: T[] } {
+    const onlyInA: T[] = [];
+    const onlyInB: T[] = [];
+    for (const x of a) if (!b.has(x)) onlyInA.push(x);
+    for (const x of b) if (!a.has(x)) onlyInB.push(x);
+    return { onlyInA, onlyInB };
+}
+
+function parseArgs(argv: string[]): { root: string } {
+    let root = resolve('.');
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--root' && i + 1 < argv.length) {
+            root = resolve(argv[++i] ?? '.');
+        } else if (arg === '--help' || arg === '-h') {
+            process.stdout.write('Usage: bun inline-pipeline-parity-check.ts [--root <path>]\n');
+            process.exit(0);
+        }
+    }
+    return { root };
+}
+
+function listWorkflowFiles(dir: string): string[] {
+    let entries: string[];
+    try {
+        entries = readdirSync(dir);
+    } catch {
+        return [];
+    }
+    return entries.filter((e) => e.endsWith('.yaml')).map((e) => join(dir, e));
+}
+
+async function main(): Promise<number> {
+    const { root } = parseArgs(process.argv.slice(2));
+    const errors: string[] = [];
+
+    const workflowDir = join(root, WORKFLOW_DIR);
+    if (!statSync(workflowDir, { throwIfNoEntry: false })) {
+        process.stderr.write(`inline-pipeline-parity-check: workflow directory not found: ${workflowDir}\n`);
+        return 1;
+    }
+
+    const files = listWorkflowFiles(workflowDir);
+    if (files.length === 0) {
+        process.stderr.write(`inline-pipeline-parity-check: no .yaml workflows found in ${workflowDir}\n`);
+        return 1;
+    }
+
+    const unionActions = new Set<string>();
+    const unionGuards = new Set<string>();
+    const perFileKinds: { path: string; actions: Set<string>; guards: Set<string> }[] = [];
+
+    for (const path of files) {
+        let parsed: unknown;
+        try {
+            parsed = parseYaml(readFileSync(path, 'utf8'));
+        } catch (err) {
+            errors.push(`${path}: failed to parse (${err instanceof Error ? err.message : String(err)})`);
+            continue;
+        }
+        if (typeof parsed !== 'object' || parsed === null) {
+            continue;
+        }
+        const def = parsed as { states?: unknown; transitions?: unknown };
+        const actions = collectActionKinds(def.states);
+        const guards = collectGuardKinds(def.transitions);
+        perFileKinds.push({ path, actions, guards });
+        for (const a of actions) unionActions.add(a);
+        for (const g of guards) unionGuards.add(g);
+    }
+
+    const actionDiff = diff(unionActions, DOCUMENTED.actions);
+    const guardDiff = diff(unionGuards, DOCUMENTED.guards);
+
+    for (const x of actionDiff.onlyInA) {
+        const usedIn = perFileKinds.filter((f) => f.actions.has(x)).map((f) => f.path);
+        errors.push(`action kind "${x}" used in YAML (${usedIn.join(', ')}) but absent from inline-pipeline-driver.md`);
+    }
+    for (const x of actionDiff.onlyInB) {
+        errors.push(`action kind "${x}" documented in inline-pipeline-driver.md but never used in any workflow`);
+    }
+    for (const x of guardDiff.onlyInA) {
+        const usedIn = perFileKinds.filter((f) => f.guards.has(x)).map((f) => f.path);
+        errors.push(`guard kind "${x}" used in YAML (${usedIn.join(', ')}) but absent from inline-pipeline-driver.md`);
+    }
+    for (const x of guardDiff.onlyInB) {
+        errors.push(`guard kind "${x}" documented in inline-pipeline-driver.md but never used in any workflow`);
+    }
+
+    if (errors.length > 0) {
+        process.stderr.write(`inline-pipeline-parity-check: ${errors.length} divergence(s)\n`);
+        for (const e of errors) process.stderr.write(`  - ${e}\n`);
+        return 1;
+    }
+
+    process.stdout.write(
+        `inline-pipeline-parity-check: ok (${unionActions.size} actions, ${unionGuards.size} guards agree across ${files.length} workflows)\n`,
+    );
+    return 0;
+}
+
+process.exit(await main());

package/plugins/sp/scripts/task-evidence-precheck.ts

@@ -145,7 +145,7 @@ function main(): void {
 
     const dbPath = join(process.cwd(), '.spur', 'spur.db');
     if (!existsSync(dbPath)) {
-        fail(wbs, [`spur database not found at ${dbPath} — run a real history import first`]);
+        fail(wbs, [`local spur database not found at ${dbPath} — run a real history import first`]);
     }
 
     let count: number;

package/plugins/sp/scripts/verify-answer-lint.ts

@@ -269,6 +269,10 @@ function extractAcIdentities(taskContent: string, featureContent: string | null)
         const leading = label.split(/\s+/)[0] ?? '';
         if (leading && leading !== label) identities.add(leading);
     }
+    for (const m of section.matchAll(/^[ \t]*Scenario:\s*(.+)\s*$/gm)) {
+        const title = (m[1] ?? '').trim();
+        if (title) identities.add(title);
+    }
     if (featureContent !== null) {
         for (const m of featureContent.matchAll(/^[ \t]*Scenario:\s*(.+)\s*$/gm)) {
             const title = (m[1] ?? '').trim();

package/plugins/sp/skills/spur-cli/references/workflows/authoring-workflows.md

@@ -229,3 +229,26 @@ verifying shape, or stand in a `note` action until the path is proven, then swap
       `agent.run` input referencing a command rather than a raw prompt, guards a single predicate
       ([workflow-fit-and-tuning.md](workflow-fit-and-tuning.md#3-node-simplicity-budget)).
 - [ ] Validates clean AND dry-run reaches the expected terminal state.
+
+## Optional version literal (task 0756)
+
+Both dialects accept an optional root `version` field. The literal is **behavior-neutral** — it
+exists as an identity tag, not a routing key. The contract:
+
+- **Absent** → reported as `unversioned`. The default for all 11 shipped definitions.
+- **Present, non-empty string** → reported as `explicit(<literal>)`. The literal is wrapped in
+  parentheses verbatim — no parsing, no ordering, no compatibility check.
+- **Present, empty string (`version: ""`)** → **rejected** with a diagnostic naming the empty
+  value. The rejection lives in the resolve/preflight seam
+  (`packages/app/src/workflow/workflow-resolver.ts`), not in the dialect JSON schemas: those carry
+  `minLength: 1` for editors and Ajv consumers, but the load path validates against the engine's
+  Zod schema, which has no minimum. Move the check upstream once
+  `@gobing-ai/ts-dual-workflow-engine` ships `z.string().min(1)` on the root version.
+
+The literal folds into the definition digest (`packages/app/src/workflow/composition-baseline.ts`),
+so a version-only edit changes the digest with zero behavior change. `show` and `trace` do **not**
+surface the literal by default — the digest stays the rendered run identity (D8 decision D5).
+
+**No registry, no semver parser, no compatibility engine.** A future-major requirement needs
+objective evidence: a consumer that branches on version, or a real drift incident the digest
+diagnostic could not disambiguate. Neither exists today.

package/plugins/sp/skills/spur-dev/references/inline-pipeline-driver.md

@@ -1,6 +1,8 @@
 ---
 name: inline-pipeline-driver
 description: "Interactive host-session interpreter for Spur state-machine pipelines: execute the existing FSM without a workflow agent subprocess while preserving actions, guards, artifacts, and provenance."
+owner: spur-dev-maintainers
+retirement-criterion: "The per-task interpreter retires once the engine covers per-task execution for /sp:dev-runall with real terminal runs and the parity check (plugins/sp/scripts/inline-pipeline-parity-check.ts) is green (D8 decision D7). Batch orchestration wrapper may remain."
 see_also:
   - spur-dev
   - execution-workflow
@@ -9,6 +11,24 @@ see_also:
 
 # Inline Pipeline Driver
 
+**Owner:** `spur-dev-maintainers` (per task 0755 R1). Reach the named owner via the frontmatter; no need to read the originating task.
+
+**Retirement criterion (0755 R5, D8 decision D7):** the per-task interpreter retires once the engine covers per-task execution for `/sp:dev-runall` with real terminal runs **and** the parity check (this doc's documented action/guard set ≡ the resolved action/guard set of every `.spur/workflows/*.yaml`) is green. Recording the criterion is part of this task; acting on it is not — that is a separate A3-gate decision.
+
+## Supported action and guard set (0755 R2 parity contract)
+
+The action and guard kinds this driver implements. The parity check
+(`plugins/sp/scripts/inline-pipeline-parity-check.ts`) compares this set against
+the resolved actions and guards of every `.spur/workflows/*.yaml`; any element present
+in one and absent in the other fails the check. Add a new kind here when the driver
+implements it; remove the entry when the corresponding kind is dropped from the YAML.
+
+**Actions:** `shell` · `note` · `doctor.probe` · `file.read.into-var` · `hitl.confirm` · `agent.run` · `proof.fingerprint` · `run.artifact` · `command.gate`
+
+**Guards (transitions):** `always` · `shell`
+
+## What this driver is
+
 This driver is the interactive control-inversion path granted by ADR-047. It applies when an
 interactive `/sp:dev-run --mode full`, sequential `/sp:dev-runall`, `/sp:dev-idea`, or
 `/sp:dev-plan` invocation omits `--agent` or passes `--agent inline`. A named executor,

package/schemas/spur-config.schema.json

@@ -92,6 +92,41 @@
                         "enabled": {
                             "type": "boolean",
                             "description": "Enable the scheduled-task runner. OFF by default for CLI (run-once)."
+                        },
+                        "jobs": {
+                            "type": "array",
+                            "description": "Declarative scheduled commands (task 0734). Each entry registers one scheduler tick that enqueues a `scheduler.custom` queue job running `command` through `/bin/sh -c`. Normalized and validated by @gobing-ai/ts-infra runNodeApplication before the server starts.",
+                            "items": {
+                                "type": "object",
+                                "required": ["name", "command"],
+                                "properties": {
+                                    "name": {
+                                        "type": "string",
+                                        "minLength": 1,
+                                        "description": "Job name, unique across the list after trimming. Reported as the `scheduler.custom:<name>` display name on scheduler.job.executed."
+                                    },
+                                    "command": {
+                                        "type": "string",
+                                        "minLength": 1,
+                                        "description": "Shell command run by `/bin/sh -c` with the project root as cwd. Trusted operator input \u2014 never logged."
+                                    },
+                                    "intervalMinutes": {
+                                        "type": "integer",
+                                        "minimum": 1,
+                                        "maximum": 35791,
+                                        "description": "Fixed interval in minutes. Mutually exclusive with `cron`. The upper bound is the Node timer ceiling (2147483647 ms)."
+                                    },
+                                    "cron": {
+                                        "type": "string",
+                                        "minLength": 1,
+                                        "description": "Five-field cron expression (minute hour day-of-month month day-of-week) evaluated in local time. Mutually exclusive with `intervalMinutes`."
+                                    }
+                                },
+                                "oneOf": [
+                                    { "required": ["intervalMinutes"], "not": { "required": ["cron"] } },
+                                    { "required": ["cron"], "not": { "required": ["intervalMinutes"] } }
+                                ]
+                            }
                         }
                     }
                 }

package/schemas/state-machine-workflow.schema.json

@@ -17,7 +17,9 @@
             "minLength": 1
         },
         "version": {
-            "type": "string"
+            "type": "string",
+            "minLength": 1,
+            "description": "Optional behavior-neutral identity tag (0756). Absent = unversioned; present = a non-empty opaque literal surfaced as explicit(<literal>). Not parsed, ordered, or compatibility-checked; no registry."
         },
         "description": {
             "type": "string"

package/schemas/transition-flow-workflow.schema.json

@@ -17,7 +17,9 @@
             "minLength": 1
         },
         "version": {
-            "type": "string"
+            "type": "string",
+            "minLength": 1,
+            "description": "Optional behavior-neutral identity tag (0756). Absent = unversioned; present = a non-empty opaque literal surfaced as explicit(<literal>). Not parsed, ordered, or compatibility-checked; no registry."
         },
         "description": {
             "type": "string"