@gobing-ai/spur 0.3.72 → 0.3.73

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/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"