@gobing-ai/spur 0.3.80 → 0.3.82

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.80",
+    "version": "0.3.82",
     "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics.",
     "extensions": {
         "pi": ["./hooks/pi/guard-extension.ts"]

package/plugins/sp/scripts/feature-dev-precheck.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+// @bun
+
+// plugins/sp/scripts/feature-dev-precheck.ts
+import { spawnSync } from "child_process";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+var BLOCKING_STATUSES = ["backlog", "wip", "testing", "blocked"];
+var KNOWN_STATUSES = ["todo", "done", "cancelled", ...BLOCKING_STATUSES];
+function identityRc(featureId, runId) {
+  return featureId && runId ? 0 : 1;
+}
+function featureIdentityMatches(raw, featureId) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return false;
+  }
+  return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) && parsed.id === featureId;
+}
+function rosterIsNonEmptyArray(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return false;
+  }
+  return Array.isArray(parsed) && parsed.length > 0;
+}
+function rosterContractHolds(rows) {
+  const seen = new Set;
+  for (const row of rows) {
+    if (row === null || typeof row !== "object")
+      return false;
+    if (typeof row.wbs !== "string" || row.wbs.length === 0)
+      return false;
+    if (seen.has(row.wbs))
+      return false;
+    seen.add(row.wbs);
+    if (typeof row.status !== "string" || !KNOWN_STATUSES.includes(row.status)) {
+      return false;
+    }
+  }
+  return true;
+}
+function hasBlockingStatus(rows) {
+  return rows.some((row) => typeof row.status === "string" && BLOCKING_STATUSES.includes(row.status));
+}
+function freezeTodoList(rows) {
+  return rows.filter((row) => row.status === "todo" && typeof row.wbs === "string").map((row) => row.wbs).sort().join(",");
+}
+function spurCommand(spurBin) {
+  const parts = (spurBin ?? "spur").trim().split(/\s+/).filter((p) => p.length > 0);
+  return { cmd: parts[0] ?? "spur", prefix: parts.slice(1) };
+}
+function readFileSyncRaw(path) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+function runFeatureDevPrecheck(env, options = {}) {
+  const cwd = options.cwd;
+  const runDir = join(".spur", "run");
+  mkdirSync(cwd ? join(cwd, runDir) : runDir, { recursive: true });
+  const abs = (p) => cwd ? join(cwd, p) : p;
+  const featureFile = join(runDir, `${env.__runId ?? ""}-feature-dev-feature.json`);
+  const rosterFile = join(runDir, `${env.__runId ?? ""}-feature-dev-roster.json`);
+  const tasksFile = join(runDir, `${env.__runId ?? ""}-feature-dev-tasks.txt`);
+  const statusFile = join(runDir, `${env.__runId ?? ""}-feature-dev-precheck.status`);
+  const featureId = env.featureId ?? "";
+  rmSync(abs(statusFile), { force: true });
+  const { cmd, prefix } = spurCommand(env.spurBin);
+  const read = (args, target) => {
+    const result = spawnSync(cmd, [...prefix, ...args], {
+      cwd,
+      encoding: "utf8",
+      ...options.env ? { env: { ...process.env, ...options.env } } : {}
+    });
+    if (result.error !== undefined) {
+      writeFileSync(abs(target), `spawn failed: ${result.error.message}
+`);
+      return 127;
+    }
+    writeFileSync(abs(target), `${result.stdout ?? ""}${result.stderr ?? ""}`);
+    return result.status ?? 1;
+  };
+  const idRc = identityRc(featureId, env.__runId);
+  const showRc = idRc === 0 ? read(["feature", "show", featureId, "--json"], featureFile) : 1;
+  const listRc = idRc === 0 && showRc === 0 && featureIdentityMatches(readFileSyncRaw(abs(featureFile)), featureId) ? read(["task", "list", "--feature", featureId, "--json"], rosterFile) : 1;
+  const fail = (message) => {
+    process.stderr.write(`${message}
+`);
+    writeFileSync(abs(statusFile), `FAIL
+`);
+    return { status: "FAIL", featureFile, rosterFile, tasksFile, statusFile, tasks: "" };
+  };
+  if (idRc !== 0 || showRc !== 0 || listRc !== 0) {
+    return fail(`feature-dev precheck: missing featureId/runId, unknown feature '${featureId}', or unreadable roster (rc ${idRc}/${showRc}/${listRc}) \u2014 supply an existing planned feature via /sp:dev-plan or /sp:dev-idea; nothing was auto-created or re-planned`);
+  }
+  const rosterRaw = readFileSyncRaw(abs(rosterFile));
+  if (!rosterIsNonEmptyArray(rosterRaw)) {
+    return fail(`feature-dev precheck: roster at ${rosterFile} is malformed, not an array, or empty \u2014 plan the feature first via /sp:dev-plan; refusing to replan or run an empty batch`);
+  }
+  const rows = JSON.parse(rosterRaw);
+  if (!rosterContractHolds(rows)) {
+    return fail(`feature-dev precheck: roster has empty/duplicate/mismatched WBS identities or unknown statuses at ${rosterFile} \u2014 repair the task corpus; refusing to batch a broken roster`);
+  }
+  if (hasBlockingStatus(rows)) {
+    return fail("feature-dev precheck: linked task(s) are backlog/wip/testing/blocked \u2014 refine or resume them through their own task pipelines before batching; refusing to launch overlapping work");
+  }
+  const tasks = freezeTodoList(rows);
+  writeFileSync(abs(tasksFile), tasks);
+  writeFileSync(abs(statusFile), `PASS
+`);
+  return { status: "PASS", featureFile, rosterFile, tasksFile, statusFile, tasks };
+}
+var FEATURE_DEV_PRECHECK_USAGE = "usage: feature-dev-precheck.ts  (env: featureId, __runId, optional spurBin) \u2014 no subcommands";
+function main(argv, env = process.env) {
+  if (argv.length > 0) {
+    process.stderr.write(`${FEATURE_DEV_PRECHECK_USAGE}
+`);
+    return 2;
+  }
+  runFeatureDevPrecheck(env);
+  return 0;
+}
+{
+  process.exit(main(process.argv.slice(2)));
+}
+export {
+  spurCommand,
+  runFeatureDevPrecheck,
+  rosterIsNonEmptyArray,
+  rosterContractHolds,
+  main,
+  identityRc,
+  hasBlockingStatus,
+  freezeTodoList,
+  featureIdentityMatches,
+  KNOWN_STATUSES,
+  FEATURE_DEV_PRECHECK_USAGE,
+  BLOCKING_STATUSES
+};

package/plugins/sp/scripts/feature-dev-precheck.ts

@@ -0,0 +1,238 @@
+#!/usr/bin/env bun
+/**
+ * feature-dev-precheck — portable identity/roster gate behind the feature-dev pipeline
+ * precheck (task 0825, feature I21, governance §1.1 composition budgets).
+ *
+ * Ports the former `feature-dev.yaml` `precheck:onEnter:0` shell program one-for-one so the
+ * workflow stays inside the shell-program caps while writing the same `.spur/run` artifacts:
+ *   - `<runId>-feature-dev-feature.json`    merged `feature show` capture (stdout + stderr)
+ *   - `<runId>-feature-dev-roster.json`     merged `task list --feature` capture
+ *   - `<runId>-feature-dev-tasks.txt`       frozen sorted todo WBS list, comma-joined
+ *   - `<runId>-feature-dev-precheck.status` `PASS`/`FAIL`
+ *
+ * Failure ladder (first failing check wins, message to stderr, FAIL status):
+ *   1. identity/roster read failure — missing featureId/runId, unknown feature, or a
+ *      non-zero rc from any of the three reads (message carries the rc triple);
+ *   2. roster not a non-empty JSON array;
+ *   3. roster contract breach — empty/duplicate/non-string WBS identities or a status
+ *      outside todo/done/cancelled/backlog/wip/testing/blocked;
+ *   4. refinement-blocking statuses present (backlog/wip/testing/blocked).
+ *
+ * Environment: `featureId`, `__runId` (required), `spurBin` (split on whitespace into a
+ * command plus prefix args). Soft-fail contract: the process always exits 0; the verdict
+ * lives in the status file. Node-builtin imports only; pure helpers are exported for unit
+ * testing (ADR-065).
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Statuses that must be refined/resumed through their own pipelines before batching. */
+export const BLOCKING_STATUSES = ['backlog', 'wip', 'testing', 'blocked'] as const;
+
+/** Every status a roster row may carry (anything else fails the structural contract). */
+export const KNOWN_STATUSES = ['todo', 'done', 'cancelled', ...BLOCKING_STATUSES] as const;
+
+export interface FeatureDevPrecheckEnv {
+    featureId?: string;
+    __runId?: string;
+    spurBin?: string;
+    [key: string]: string | undefined;
+}
+
+export interface FeatureDevPrecheckOptions {
+    /** Base directory for `.spur/run`; defaults to the process cwd (CLI behavior). */
+    cwd?: string;
+    /** Extra environment for the spawned CLI reads (merged over process.env). */
+    env?: Record<string, string>;
+}
+
+export interface FeatureDevPrecheckResult {
+    status: 'PASS' | 'FAIL';
+    featureFile: string;
+    rosterFile: string;
+    tasksFile: string;
+    statusFile: string;
+    /** Frozen todo list; empty string on FAIL. */
+    tasks: string;
+}
+
+export interface RosterRow {
+    wbs: unknown;
+    status: unknown;
+}
+
+/** Identity gate: rc 0 when featureId and __runId are both non-empty, else 1. */
+export function identityRc(featureId: string | undefined, runId: string | undefined): number {
+    return featureId && runId ? 0 : 1;
+}
+
+/**
+ * jq `type == "object" and .id == $id` port: parsed JSON must be a non-array object whose
+ * `.id` equals the supplied feature id.
+ */
+export function featureIdentityMatches(raw: string, featureId: string): boolean {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch {
+        return false;
+    }
+    return (
+        typeof parsed === 'object' &&
+        parsed !== null &&
+        !Array.isArray(parsed) &&
+        (parsed as { id?: unknown }).id === featureId
+    );
+}
+
+/** jq roster-shape port: parsed JSON must be a non-empty array. */
+export function rosterIsNonEmptyArray(raw: string): boolean {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch {
+        return false;
+    }
+    return Array.isArray(parsed) && parsed.length > 0;
+}
+
+/** jq WBS-identity/status contract port: non-empty string wbs, unique, known statuses. */
+export function rosterContractHolds(rows: RosterRow[]): boolean {
+    const seen = new Set<string>();
+    for (const row of rows) {
+        if (row === null || typeof row !== 'object') return false;
+        if (typeof row.wbs !== 'string' || row.wbs.length === 0) return false;
+        if (seen.has(row.wbs)) return false;
+        seen.add(row.wbs);
+        if (typeof row.status !== 'string' || !(KNOWN_STATUSES as readonly string[]).includes(row.status)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/** jq blocking-status port: any backlog/wip/testing/blocked member. */
+export function hasBlockingStatus(rows: RosterRow[]): boolean {
+    return rows.some(
+        (row) => typeof row.status === 'string' && (BLOCKING_STATUSES as readonly string[]).includes(row.status),
+    );
+}
+
+/** jq `sort | join(",")` port over the todo subset: codepoint-sorted, comma-joined, no newline. */
+export function freezeTodoList(rows: RosterRow[]): string {
+    return rows
+        .filter((row) => row.status === 'todo' && typeof row.wbs === 'string')
+        .map((row) => row.wbs as string)
+        .sort()
+        .join(',');
+}
+
+/** `spurBin` splits on whitespace into a command plus prefix args (PATH-independent runs). */
+export function spurCommand(spurBin: string | undefined): { cmd: string; prefix: string[] } {
+    const parts = (spurBin ?? 'spur')
+        .trim()
+        .split(/\s+/)
+        .filter((p) => p.length > 0);
+    return { cmd: parts[0] ?? 'spur', prefix: parts.slice(1) };
+}
+
+function readFileSyncRaw(path: string): string {
+    try {
+        return readFileSync(path, 'utf8');
+    } catch {
+        return '';
+    }
+}
+
+export function runFeatureDevPrecheck(
+    env: FeatureDevPrecheckEnv,
+    options: FeatureDevPrecheckOptions = {},
+): FeatureDevPrecheckResult {
+    const cwd = options.cwd;
+    const runDir = join('.spur', 'run');
+    mkdirSync(cwd ? join(cwd, runDir) : runDir, { recursive: true });
+    const abs = (p: string): string => (cwd ? join(cwd, p) : p);
+    const featureFile = join(runDir, `${env.__runId ?? ''}-feature-dev-feature.json`);
+    const rosterFile = join(runDir, `${env.__runId ?? ''}-feature-dev-roster.json`);
+    const tasksFile = join(runDir, `${env.__runId ?? ''}-feature-dev-tasks.txt`);
+    const statusFile = join(runDir, `${env.__runId ?? ''}-feature-dev-precheck.status`);
+    const featureId = env.featureId ?? '';
+
+    rmSync(abs(statusFile), { force: true });
+
+    const { cmd, prefix } = spurCommand(env.spurBin);
+    /** Spawn one CLI read; merged output into the artifact, 127 on a spawn error (exec loss). */
+    const read = (args: string[], target: string): number => {
+        const result = spawnSync(cmd, [...prefix, ...args], {
+            cwd,
+            encoding: 'utf8',
+            ...(options.env ? { env: { ...process.env, ...options.env } } : {}),
+        });
+        if (result.error !== undefined) {
+            writeFileSync(abs(target), `spawn failed: ${result.error.message}\n`);
+            return 127;
+        }
+        writeFileSync(abs(target), `${result.stdout ?? ''}${result.stderr ?? ''}`);
+        return result.status ?? 1;
+    };
+
+    const idRc = identityRc(featureId, env.__runId);
+    const showRc = idRc === 0 ? read(['feature', 'show', featureId, '--json'], featureFile) : 1;
+    const listRc =
+        idRc === 0 && showRc === 0 && featureIdentityMatches(readFileSyncRaw(abs(featureFile)), featureId)
+            ? read(['task', 'list', '--feature', featureId, '--json'], rosterFile)
+            : 1;
+
+    const fail = (message: string): FeatureDevPrecheckResult => {
+        process.stderr.write(`${message}\n`);
+        writeFileSync(abs(statusFile), 'FAIL\n');
+        return { status: 'FAIL', featureFile, rosterFile, tasksFile, statusFile, tasks: '' };
+    };
+
+    if (idRc !== 0 || showRc !== 0 || listRc !== 0) {
+        return fail(
+            `feature-dev precheck: missing featureId/runId, unknown feature '${featureId}', or unreadable roster (rc ${idRc}/${showRc}/${listRc}) — supply an existing planned feature via /sp:dev-plan or /sp:dev-idea; nothing was auto-created or re-planned`,
+        );
+    }
+
+    const rosterRaw = readFileSyncRaw(abs(rosterFile));
+    if (!rosterIsNonEmptyArray(rosterRaw)) {
+        return fail(
+            `feature-dev precheck: roster at ${rosterFile} is malformed, not an array, or empty — plan the feature first via /sp:dev-plan; refusing to replan or run an empty batch`,
+        );
+    }
+    const rows = JSON.parse(rosterRaw) as RosterRow[];
+    if (!rosterContractHolds(rows)) {
+        return fail(
+            `feature-dev precheck: roster has empty/duplicate/mismatched WBS identities or unknown statuses at ${rosterFile} — repair the task corpus; refusing to batch a broken roster`,
+        );
+    }
+    if (hasBlockingStatus(rows)) {
+        return fail(
+            'feature-dev precheck: linked task(s) are backlog/wip/testing/blocked — refine or resume them through their own task pipelines before batching; refusing to launch overlapping work',
+        );
+    }
+
+    const tasks = freezeTodoList(rows);
+    writeFileSync(abs(tasksFile), tasks);
+    writeFileSync(abs(statusFile), 'PASS\n');
+    return { status: 'PASS', featureFile, rosterFile, tasksFile, statusFile, tasks };
+}
+
+export const FEATURE_DEV_PRECHECK_USAGE =
+    'usage: feature-dev-precheck.ts  (env: featureId, __runId, optional spurBin) — no subcommands';
+
+export function main(argv: string[], env: FeatureDevPrecheckEnv = process.env): number {
+    if (argv.length > 0) {
+        process.stderr.write(`${FEATURE_DEV_PRECHECK_USAGE}\n`);
+        return 2;
+    }
+    runFeatureDevPrecheck(env);
+    return 0;
+}
+
+if (import.meta.main) {
+    process.exit(main(process.argv.slice(2)));
+}

package/plugins/sp/scripts/idea-handoff.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// @bun
+
+// plugins/sp/scripts/idea-handoff.ts
+var libUrl = new URL("../lib/idea-handoff.generated.mjs", import.meta.url).href;
+async function loadHandoffLib() {
+  return await import(libUrl);
+}
+var IDEA_HANDOFF_USAGE = "usage: idea-handoff.ts  (env: __runId, featureId, optional spurBin) \u2014 no subcommands";
+async function main(argv, env = process.env) {
+  if (argv.length > 0) {
+    process.stderr.write(`${IDEA_HANDOFF_USAGE}
+`);
+    return 2;
+  }
+  const { runIdeaHandoffCli } = await loadHandoffLib();
+  const outcome = await runIdeaHandoffCli(env);
+  return outcome.exitCode;
+}
+{
+  process.exit(await main(process.argv.slice(2)));
+}
+export {
+  main,
+  loadHandoffLib,
+  IDEA_HANDOFF_USAGE
+};

package/plugins/sp/scripts/idea-handoff.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env bun
+/**
+ * idea-handoff — portable entrypoint for the idea-pipeline finalization (task 0824, feature I21).
+ *
+ * ADR-065 standard plugin script: the workflow wrapper prefers the monorepo writer
+ * (`bun packages/app/src/workflow/idea-handoff-cli.ts`) and falls back to this script's
+ * registered `.mjs` twin under bare `node`, so a seeded project with no monorepo checkout
+ * still finalizes the handoff (run-scoped report + task-deps ordering + roster refresh) and
+ * fails closed (exit 1) when neither writer resolves.
+ *
+ * The behavior lives in the generated bundle `../lib/idea-handoff.generated.mjs`, produced by
+ * `bun run build:plugin-lib` from `packages/app/src/workflow/idea-handoff-cli.ts` — the same
+ * source the monorepo branch executes, so both branches share one contract (0604/0824).
+ * Declarations: `../lib/idea-handoff.generated.d.mts`. The bundle is imported by computed URL
+ * on purpose: `superskill script convert` must NOT inline it (its tree carries one
+ * `Bun.spawn` site in a ts-runtime streaming path this workflow never exercises), so the
+ * twin stays a thin node-runnable loader over the committed runtime asset.
+ *
+ * Environment: `__runId`, `featureId`, optional `spurBin`. Missing required vars exit 1
+ * (mis-invocation is failed-closed, never a silent skip).
+ */
+
+const libUrl = new URL('../lib/idea-handoff.generated.mjs', import.meta.url).href;
+
+export async function loadHandoffLib(): Promise<typeof import('../lib/idea-handoff.generated.mjs')> {
+    return (await import(libUrl)) as typeof import('../lib/idea-handoff.generated.mjs');
+}
+
+export const IDEA_HANDOFF_USAGE =
+    'usage: idea-handoff.ts  (env: __runId, featureId, optional spurBin) — no subcommands';
+
+export async function main(argv: string[], env: NodeJS.ProcessEnv = process.env): Promise<number> {
+    if (argv.length > 0) {
+        process.stderr.write(`${IDEA_HANDOFF_USAGE}\n`);
+        return 2;
+    }
+    const { runIdeaHandoffCli } = await loadHandoffLib();
+    const outcome = await runIdeaHandoffCli(env as { __runId?: string; featureId?: string; spurBin?: string });
+    return outcome.exitCode;
+}
+
+if (import.meta.main) {
+    process.exit(await main(process.argv.slice(2)));
+}

package/plugins/sp/scripts/inline-run-setup.ts

@@ -29,6 +29,10 @@
  *
  * Usage:
  *   bun plugins/sp/scripts/inline-run-setup.ts --run-id <id> --file <definition> [--spur-bin <path>]
+ *   bun plugins/sp/scripts/inline-run-setup.ts --fingerprint --task-file <path> [--feature-file <path>] [--spur-bin <path>]
+ *
+ * The `--fingerprint` mode prints the engine's proof-input digest for the given spec files and
+ * creates nothing (task 0862 R5).
  *
  * Env: SPUR_BIN
  */
@@ -56,7 +60,10 @@ function usage(): never {
     console.error(
         'Usage: bun plugins/sp/scripts/inline-run-setup.ts --run-id <id> --file <definition> [--spur-bin <path>]',
     );
-    process.exit(1);
+    console.error(
+        '       bun plugins/sp/scripts/inline-run-setup.ts --fingerprint --task-file <path> [--feature-file <path>] [--spur-bin <path>]',
+    );
+    process.exit(2);
 }
 
 /**
@@ -122,16 +129,77 @@ function writeOutcome(runId: string, outcome: SetupOutcome): void {
     writeFileSync(join(runDir, `${runId}-inline-setup.json`), `${JSON.stringify(outcome, null, 4)}\n`);
 }
 
+/**
+ * `--fingerprint` mode (task 0862 R5): print the engine's proof-input digest for a task file
+ * (plus optional feature file) instead of creating a run, so the inline driver can capture the
+ * fresh digest bound `run.artifact` registration checks against.
+ *
+ * The digest itself comes from the exported app functions — never reimplemented here — and the
+ * options mirror `ProofFingerprintActionRunner` (cwd, spec contents, fileSystem; no `--expect`).
+ * Returns the process exit code: 0 printed, 1 read/resolve failure.
+ */
+async function printFingerprint(taskFile: string, featureFile: string, spurBin: string): Promise<number> {
+    const { entry, repoRoot, chain } = resolveAppEntry(spurBin);
+    if (entry === null || repoRoot === null) {
+        console.error(
+            `inline-run-setup: FAIL — no monorepo checkout of spur is reachable via ${chain}. ` +
+                'The proof-input digest must be computed by the app service; a bundle-only install cannot do it.',
+        );
+        return 1;
+    }
+    const app = (await import(entry)) as {
+        computeProofInputFingerprint: (options: Record<string, unknown>) => Promise<string>;
+        readProofInputContents: (
+            fileSystem: unknown,
+            workdir: string,
+            options: { taskFile?: unknown; featureFile?: unknown },
+        ) => Promise<{ ok: true; taskContent?: string; featureContent?: string } | { ok: false; error: string }>;
+    };
+
+    const workdir = process.cwd();
+    // `undefined` fs takes readProofInputContents' node-filesystem default — the same default its
+    // sibling createGitAlternateTree applies, and the same Node FS the CLI's runner injects.
+    const inputs = await app.readProofInputContents(undefined, workdir, {
+        taskFile,
+        ...(featureFile.trim() !== '' ? { featureFile } : {}),
+    });
+    if (!inputs.ok) {
+        console.error(`inline-run-setup: FAIL — ${inputs.error}`);
+        return 1;
+    }
+
+    const digest = await app.computeProofInputFingerprint({
+        cwd: workdir,
+        ...(inputs.taskContent !== undefined ? { taskContent: inputs.taskContent } : {}),
+        ...(inputs.featureContent !== undefined ? { featureContent: inputs.featureContent } : {}),
+    });
+    process.stdout.write(`${digest}\n`);
+    return 0;
+}
+
 async function main(): Promise<void> {
     let runId = '';
     let file = '';
+    let fingerprint = false;
+    let taskFile = '';
+    let featureFile = '';
     let spurBin = process.env.SPUR_BIN ?? '';
     const argv = process.argv.slice(2);
     for (let i = 0; i < argv.length; i++) {
         if (argv[i] === '--run-id') runId = argv[++i] ?? '';
         else if (argv[i] === '--file') file = argv[++i] ?? '';
+        else if (argv[i] === '--fingerprint') fingerprint = true;
+        else if (argv[i] === '--task-file') taskFile = argv[++i] ?? '';
+        else if (argv[i] === '--feature-file') featureFile = argv[++i] ?? '';
         else if (argv[i] === '--spur-bin') spurBin = argv[++i] ?? spurBin;
     }
+
+    // Two mutually exclusive modes share this entry point: create/attach a run (run-id + file), or
+    // print the proof digest for the inline driver (task 0862 R5). Mixing them is a usage error.
+    if (fingerprint) {
+        if (runId !== '' || file !== '' || taskFile.trim() === '') usage();
+        process.exit(await printFingerprint(taskFile, featureFile, spurBin));
+    }
     if (runId.trim() === '' || file.trim() === '') usage();
     if (!SAFE_RUN_ID_RE.test(runId)) refuseUnsafeRunId(runId);