@gobing-ai/spur 0.4.0 → 0.4.2

package/plugins/sp/scripts/batch-preflight.mjs

@@ -3,6 +3,30 @@ import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // plugins/sp/scripts/batch-preflight.ts
+var NON_ABORTING_PREFLIGHT_CODES = new Set([
+  "L4.scenario-unverified",
+  "L4.verifying-incomplete-tasks"
+]);
+function classifyFeaturePreflightFindings(findings) {
+  const aborting = [];
+  const nonAborting = [];
+  for (const f of findings) {
+    if (f.severity === "error") {
+      if (NON_ABORTING_PREFLIGHT_CODES.has(f.code)) {
+        nonAborting.push(f);
+      } else {
+        aborting.push(f);
+      }
+    } else {
+      nonAborting.push(f);
+    }
+  }
+  return {
+    aborting,
+    nonAborting,
+    shouldAbort: aborting.length > 0
+  };
+}
 function quickReadiness(input) {
   const status = (input.status ?? "").toLowerCase();
   const operation = input.operation;
@@ -190,6 +214,7 @@ function parsePreflightCliArgs(argv) {
   let filteredCount = null;
   let requiredSections = [];
   let presentSections = [];
+  let classifyFeature = null;
   for (let i = 0;i < argv.length; i++) {
     const a = argv[i];
     if (a === "--help" || a === "-h")
@@ -214,7 +239,9 @@ function parsePreflightCliArgs(argv) {
       presentSections = raw.length === 0 ? [] : raw.split(",").map((s) => s.trim()).filter(Boolean);
     } else if (a === "--wbs")
       wbs = argv[++i] ?? wbs;
-    else if (a === "--status")
+    else if (a === "--classify-feature") {
+      classifyFeature = argv[++i] ?? "[]";
+    } else if (a === "--status")
       status = argv[++i] ?? null;
     else if (a === "--deps") {
       const raw = argv[++i] ?? "";
@@ -240,7 +267,8 @@ function parsePreflightCliArgs(argv) {
     force,
     filteredCount,
     requiredSections,
-    presentSections
+    presentSections,
+    classifyFeature
   };
 }
 var PREFLIGHT_CLI_USAGE = `Usage:
@@ -253,6 +281,24 @@ function runPreflightCli(argv) {
   const args = parsePreflightCliArgs(argv);
   if (args.help)
     return { exitCode: 0, stdout: "", stderr: PREFLIGHT_CLI_USAGE };
+  if (args.classifyFeature !== null) {
+    try {
+      const findings = JSON.parse(args.classifyFeature);
+      const res = classifyFeaturePreflightFindings(Array.isArray(findings) ? findings : []);
+      return {
+        exitCode: res.shouldAbort ? 1 : 0,
+        stdout: `${JSON.stringify(res, null, 2)}
+`,
+        stderr: ""
+      };
+    } catch (e) {
+      return {
+        exitCode: 1,
+        stdout: "",
+        stderr: `Invalid JSON for --classify-feature: ${String(e)}`
+      };
+    }
+  }
   if (!args.status)
     return { exitCode: 1, stdout: "", stderr: PREFLIGHT_CLI_USAGE };
   if (args.recovery) {
@@ -327,5 +373,7 @@ export {
   quickReadiness,
   preflightTask,
   parsePreflightCliArgs,
-  PREFLIGHT_CLI_USAGE
+  classifyFeaturePreflightFindings,
+  PREFLIGHT_CLI_USAGE,
+  NON_ABORTING_PREFLIGHT_CODES
 };

package/plugins/sp/scripts/batch-preflight.ts

@@ -25,6 +25,51 @@ export type PreflightResult =
     | { action: 'run'; code?: string; reason?: string }
     | { action: 'skip'; code: string; reason: string; unmetDeps?: string[] };
 
+// ── Feature preflight classification (1132 R4) ──────────────────────────────
+/**
+ * 1132 R4: Codes that are expected pre-run states under `feature check --strict`
+ * and must not abort the batch. Structured classification in code (replaces prose-only).
+ */
+export const NON_ABORTING_PREFLIGHT_CODES = new Set<string>([
+    'L4.scenario-unverified',
+    'L4.verifying-incomplete-tasks',
+]);
+
+export interface FeaturePreflightFinding {
+    layer: string;
+    code: string;
+    severity: string;
+    message: string;
+    section?: string;
+}
+
+export interface FeaturePreflightClassification {
+    aborting: FeaturePreflightFinding[];
+    nonAborting: FeaturePreflightFinding[];
+    shouldAbort: boolean;
+}
+
+export function classifyFeaturePreflightFindings(findings: FeaturePreflightFinding[]): FeaturePreflightClassification {
+    const aborting: FeaturePreflightFinding[] = [];
+    const nonAborting: FeaturePreflightFinding[] = [];
+    for (const f of findings) {
+        if (f.severity === 'error') {
+            if (NON_ABORTING_PREFLIGHT_CODES.has(f.code)) {
+                nonAborting.push(f);
+            } else {
+                aborting.push(f);
+            }
+        } else {
+            nonAborting.push(f);
+        }
+    }
+    return {
+        aborting,
+        nonAborting,
+        shouldAbort: aborting.length > 0,
+    };
+}
+
 // ── Command-aware quick readiness (task 0814 R2) ──────────────────────────────
 // Read-only admission decision for the requested dev operation. Distinguishes
 // runnable / needs-refinement / blocked / skipped / invalid outcomes without
@@ -299,6 +344,8 @@ export interface PreflightCliArgs {
     requiredSections: string[];
     /** Sections actually present in the task. */
     presentSections: string[];
+    /** Feature findings to classify (1132 R4). */
+    classifyFeature: string | null;
 }
 
 export function parsePreflightCliArgs(argv: string[]): PreflightCliArgs {
@@ -314,6 +361,7 @@ export function parsePreflightCliArgs(argv: string[]): PreflightCliArgs {
     let filteredCount: number | null = null;
     let requiredSections: string[] = [];
     let presentSections: string[] = [];
+    let classifyFeature: string | null = null;
 
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
@@ -346,7 +394,9 @@ export function parsePreflightCliArgs(argv: string[]): PreflightCliArgs {
                           .map((s) => s.trim())
                           .filter(Boolean);
         } else if (a === '--wbs') wbs = argv[++i] ?? wbs;
-        else if (a === '--status') status = argv[++i] ?? null;
+        else if (a === '--classify-feature') {
+            classifyFeature = argv[++i] ?? '[]';
+        } else if (a === '--status') status = argv[++i] ?? null;
         else if (a === '--deps') {
             const raw = argv[++i] ?? '';
             deps =
@@ -378,6 +428,7 @@ export function parsePreflightCliArgs(argv: string[]): PreflightCliArgs {
         filteredCount,
         requiredSections,
         presentSections,
+        classifyFeature,
     };
 }
 
@@ -392,6 +443,26 @@ Exit: 0 = run (or recovery hint printed); 2 = skip; 1 = usage.`;
 export function runPreflightCli(argv: string[]): { exitCode: number; stdout: string; stderr: string } {
     const args = parsePreflightCliArgs(argv);
     if (args.help) return { exitCode: 0, stdout: '', stderr: PREFLIGHT_CLI_USAGE };
+
+    // Feature findings classification (1132 R4)
+    if (args.classifyFeature !== null) {
+        try {
+            const findings = JSON.parse(args.classifyFeature);
+            const res = classifyFeaturePreflightFindings(Array.isArray(findings) ? findings : []);
+            return {
+                exitCode: res.shouldAbort ? 1 : 0,
+                stdout: `${JSON.stringify(res, null, 2)}\n`,
+                stderr: '',
+            };
+        } catch (e) {
+            return {
+                exitCode: 1,
+                stdout: '',
+                stderr: `Invalid JSON for --classify-feature: ${String(e)}`,
+            };
+        }
+    }
+
     if (!args.status) return { exitCode: 1, stdout: '', stderr: PREFLIGHT_CLI_USAGE };
 
     if (args.recovery) {

package/plugins/sp/scripts/commit-guard.mjs

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+// @bun
+
+// plugins/sp/scripts/commit-guard.ts
+import { spawnSync } from "child_process";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { join } from "path";
+var COMMIT_GUARD_USAGE = "usage: commit-guard start --run <id> | stage --run <id> [--base <sha>] -- <paths\u2026> | check --run <id>";
+function isBookkeeping(path) {
+  return path === ".spur" || path.startsWith(".spur/");
+}
+function at(options, rel) {
+  return options.cwd ? join(options.cwd, rel) : rel;
+}
+function artifactPath(run) {
+  return join(".spur", "run", `${run}-tree-start.json`);
+}
+function gitOf(options) {
+  if (options.git)
+    return options.git;
+  return (args) => {
+    const run = spawnSync("git", args, { cwd: options.cwd, encoding: "utf8" });
+    return { status: run.status ?? 1, stdout: run.stdout ?? "" };
+  };
+}
+function hashPath(path, git) {
+  const run = git(["hash-object", "--", path]);
+  return run.status === 0 ? run.stdout.trim() : null;
+}
+function parsePorcelainZ(stdout) {
+  const tokens = stdout.split("\x00");
+  const paths = [];
+  for (let i = 0;i < tokens.length; i++) {
+    const entry = tokens[i] ?? "";
+    if (entry.length < 4)
+      continue;
+    const path = entry.slice(3);
+    if (!isBookkeeping(path))
+      paths.push(path);
+    if (/[RC]/.test(entry.slice(0, 2)))
+      i++;
+  }
+  return paths;
+}
+function conflictMarkerLine(content) {
+  let opener = false;
+  for (const line of content.split(`
+`)) {
+    if (/^<{7}( |$)/.test(line))
+      opener = true;
+    else if (/^={7}(\s|$)/.test(line) && opener)
+      return true;
+    else if (/^>{7}( |$)/.test(line))
+      return true;
+  }
+  return opener;
+}
+function changedSinceBase(base, git) {
+  const tracked = git(["diff", "--name-only", base]);
+  const others = git(["ls-files", "--others", "--exclude-standard", "-z"]);
+  if (tracked.status !== 0 || others.status !== 0)
+    return new Set;
+  const clean = (out, sep) => out.split(sep).map((p) => p.trim()).filter((p) => p.length > 0 && !isBookkeeping(p));
+  return new Set([...clean(tracked.stdout, `
+`), ...clean(others.stdout, "\x00")]);
+}
+function readTreeStart(run, options) {
+  try {
+    const parsed = JSON.parse(readFileSync(at(options, artifactPath(run)), "utf8"));
+    if (typeof parsed.head === "string" && Array.isArray(parsed.dirty))
+      return parsed;
+  } catch {}
+  return null;
+}
+function runContext(run, options) {
+  const git = gitOf(options);
+  const start = readTreeStart(run, options);
+  if (!start)
+    return null;
+  let base = options.base ?? "";
+  if (!base) {
+    try {
+      const anchored = readFileSync(at(options, join(".spur", "run", `${run}-base.sha`)), "utf8").trim();
+      if (/^[0-9a-f]{7,40}$/i.test(anchored))
+        base = anchored;
+    } catch {}
+  }
+  if (!base)
+    base = start.head.length > 0 ? start.head : "HEAD";
+  const written = changedSinceBase(base, git);
+  for (const entry of start.dirty)
+    if (hashPath(entry.path, git) === entry.sha)
+      written.delete(entry.path);
+  return { git, base, start, written };
+}
+function missingStart(run) {
+  process.stderr.write(`commit-guard: no ${artifactPath(run)} \u2014 run \`commit-guard start --run ${run}\` first
+`);
+  return 1;
+}
+function runStart(run, options = {}) {
+  const git = gitOf(options);
+  const head = git(["rev-parse", "HEAD"]);
+  const status = git(["status", "--porcelain=v1", "-z"]);
+  if (head.status !== 0 || status.status !== 0) {
+    process.stderr.write(`commit-guard: git probe failed (rev-parse HEAD / status) \u2014 is this a work tree?
+`);
+    return 1;
+  }
+  const snapshot = {
+    head: head.stdout.trim(),
+    dirty: parsePorcelainZ(status.stdout).map((path) => ({ path, sha: hashPath(path, git) }))
+  };
+  const abs = at(options, artifactPath(run));
+  mkdirSync(join(abs, ".."), { recursive: true });
+  writeFileSync(`${abs}.tmp`, `${JSON.stringify(snapshot, null, 2)}
+`);
+  renameSync(`${abs}.tmp`, abs);
+  return 0;
+}
+function conflictingTarget(paths, options, git) {
+  const unmerged = new Set(git(["diff", "--name-only", "--diff-filter=U"]).stdout.split(`
+`).map((p) => p.trim()));
+  for (const path of paths) {
+    if (unmerged.has(path))
+      return `${path} (unmerged)`;
+    try {
+      if (conflictMarkerLine(readFileSync(at(options, path), "utf8")))
+        return `${path} (conflict markers)`;
+    } catch {}
+  }
+  return null;
+}
+function runStage(run, paths, options = {}) {
+  if (paths.length === 0) {
+    process.stderr.write(`${COMMIT_GUARD_USAGE}
+`);
+    return { staged: [], foreign: [], exitCode: 1 };
+  }
+  const context = runContext(run, options);
+  if (!context)
+    return { staged: [], foreign: [], exitCode: missingStart(run) };
+  const conflict = conflictingTarget(paths, options, context.git);
+  if (conflict) {
+    process.stderr.write(`commit-guard: refusing to stage ${conflict}; nothing staged
+`);
+    return { staged: [], foreign: [], exitCode: 3 };
+  }
+  const dirtyAtStart = new Set(context.start.dirty.map((entry) => entry.path));
+  const staged = paths.filter((path) => context.written.has(path));
+  const refused = paths.filter((path) => !context.written.has(path));
+  for (const path of refused) {
+    const why = dirtyAtStart.has(path) ? "foreign \u2014 dirty at start, untouched by this run" : "unchanged since base";
+    process.stderr.write(`commit-guard: refused ${path} (${why})
+`);
+  }
+  if (staged.length > 0 && context.git(["add", "--", ...staged]).status !== 0) {
+    process.stderr.write(`commit-guard: git add failed \u2014 nothing staged
+`);
+    return { staged: [], foreign: [], exitCode: 1 };
+  }
+  const foreign = refused.filter((path) => dirtyAtStart.has(path));
+  process.stdout.write(`${JSON.stringify({ staged, foreign })}
+`);
+  return { staged, foreign, exitCode: refused.length > 0 ? 2 : 0 };
+}
+function runCheck(run, options = {}) {
+  const context = runContext(run, options);
+  if (!context)
+    return missingStart(run);
+  const foreign = [...changedSinceBase(context.base, context.git)].filter((path) => !context.written.has(path)).sort();
+  process.stdout.write(`${JSON.stringify({ foreign })}
+`);
+  return 0;
+}
+function takeFlag(args, name) {
+  const index = args.indexOf(name);
+  const value = index === -1 ? undefined : args[index + 1];
+  const missing = value === undefined || value.startsWith("--");
+  if (index !== -1)
+    args.splice(index, missing ? 1 : 2);
+  return missing ? undefined : value;
+}
+function main(argv, options = {}) {
+  const args = [...argv];
+  takeFlag(args, "--spur-bin");
+  const sub = args.shift();
+  const run = takeFlag(args, "--run");
+  const base = takeFlag(args, "--base");
+  const usage = () => {
+    process.stderr.write(`${COMMIT_GUARD_USAGE}
+`);
+    return 1;
+  };
+  if (!run)
+    return usage();
+  if (sub === "start")
+    return args.length === 0 ? runStart(run, options) : usage();
+  if (sub === "check")
+    return args.length === 0 ? runCheck(run, { ...options, base }) : usage();
+  if (sub === "stage")
+    return runStage(run, args.filter((arg) => arg !== "--"), { ...options, base }).exitCode;
+  return usage();
+}
+{
+  process.exit(main(process.argv.slice(2)));
+}
+export {
+  runStart,
+  runStage,
+  runCheck,
+  parsePorcelainZ,
+  main,
+  conflictMarkerLine,
+  COMMIT_GUARD_USAGE
+};

package/plugins/sp/scripts/commit-guard.ts

@@ -0,0 +1,249 @@
+#!/usr/bin/env bun
+/**
+ * commit-guard — refuse a driver commit that would sweep a *foreign* writer's working-tree changes
+ * (task 1129, feature H1). Incidents: `a94f9f431` (a batch pipeline commit swept another session's
+ * uncommitted files) and `36f274590` (a close-out commit swept two other tasks' files through
+ * `git add -A`). The runbooks already said "stage only what the batch wrote"; nothing enforced it.
+ *
+ * Read/write `.spur/run/<id>-tree-start.json`; stage only the listed paths this run wrote; report
+ * the ones it did not. "Written by this run" = "changed since base" (task-diffstat semantics) minus
+ * start-dirty paths whose content still matches the start snapshot — a path dirty at start and
+ * untouched by the run belongs to another writer. Exit codes: 0 = staged all requested · 2 = some
+ * refused as foreign · 3 = conflict or unmerged target (nothing staged) · 1 = mis-invocation, or a
+ * missing start snapshot (`start` first).
+ *
+ * `node:*` builtins and relative imports only (sp-plugin-standalone); `options.git` is the test
+ * seam; `.spur/` is excluded from both sets (run bookkeeping is not product work — task-diffstat).
+ *
+ * shortcut: a foreign edit to a path that was CLEAN at `start` is indistinguishable from this run's
+ * own write — git records content, not authorship — so it is caught only once it is dirty in the
+ * start snapshot. Upgrade path: a per-run write journal if that case ever recurs.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Base directory for the probes; `git` is the test seam (a fake runner instead of spawning). */
+export interface GuardOptions {
+    cwd?: string;
+    base?: string;
+    git?: GitRunner;
+}
+/** Minimal spawnable git surface — tests fake this to return canned probe output. */
+export interface GitRunResult {
+    status: number;
+    stdout: string;
+}
+export type GitRunner = (args: string[]) => GitRunResult;
+export interface TreeStart {
+    head: string;
+    /** Working-file blob hashes at start; `sha` is null when the path did not exist. */
+    dirty: Array<{ path: string; sha: string | null }>;
+}
+/** `exitCode` is what `main` returns: 0 all staged · 2 some refused · 3 conflict · 1 usage. */
+export type StageResult = { staged: string[]; foreign: string[]; exitCode: number };
+
+export const COMMIT_GUARD_USAGE =
+    'usage: commit-guard start --run <id> | stage --run <id> [--base <sha>] -- <paths…> | check --run <id>';
+
+/** Run bookkeeping is not product work — neither set may contain it (task-diffstat's rule). */
+function isBookkeeping(path: string): boolean {
+    return path === '.spur' || path.startsWith('.spur/');
+}
+/** Probe/artifact paths are repo-relative; `cwd` only anchors them for tests and callers. */
+function at(options: GuardOptions, rel: string): string {
+    return options.cwd ? join(options.cwd, rel) : rel;
+}
+function artifactPath(run: string): string {
+    return join('.spur', 'run', `${run}-tree-start.json`);
+}
+function gitOf(options: GuardOptions): GitRunner {
+    if (options.git) return options.git;
+    return (args: string[]): GitRunResult => {
+        const run = spawnSync('git', args, { cwd: options.cwd, encoding: 'utf8' });
+        return { status: run.status ?? 1, stdout: run.stdout ?? '' };
+    };
+}
+/** Working-file blob hash, or null when the path is absent (`git hash-object` failed). */
+function hashPath(path: string, git: GitRunner): string | null {
+    const run = git(['hash-object', '--', path]);
+    return run.status === 0 ? run.stdout.trim() : null;
+}
+/** Paths from `git status --porcelain=v1 -z` (`XY <path>` entries; a rename's source token is
+ * consumed, not registered). */
+export function parsePorcelainZ(stdout: string): string[] {
+    const tokens = stdout.split('\u0000');
+    const paths: string[] = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const entry = tokens[i] ?? '';
+        if (entry.length < 4) continue;
+        const path = entry.slice(3);
+        if (!isBookkeeping(path)) paths.push(path);
+        if (/[RC]/.test(entry.slice(0, 2))) i++;
+    }
+    return paths;
+}
+/** An unresolved conflict marker: an opener or closer line, or a `=======` between them — a `===`
+ * setext underline in prose is not a marker without an opener. */
+export function conflictMarkerLine(content: string): boolean {
+    let opener = false;
+    for (const line of content.split('\n')) {
+        if (/^<{7}( |$)/.test(line)) opener = true;
+        else if (/^={7}(\s|$)/.test(line) && opener) return true;
+        else if (/^>{7}( |$)/.test(line)) return true;
+    }
+    return opener;
+}
+/** "Changed since base" (task-diffstat semantics): tracked changes + untracked, minus bookkeeping. */
+function changedSinceBase(base: string, git: GitRunner): Set<string> {
+    const tracked = git(['diff', '--name-only', base]);
+    const others = git(['ls-files', '--others', '--exclude-standard', '-z']);
+    if (tracked.status !== 0 || others.status !== 0) return new Set();
+    const clean = (out: string, sep: string): string[] =>
+        out
+            .split(sep)
+            .map((p) => p.trim())
+            .filter((p) => p.length > 0 && !isBookkeeping(p));
+    return new Set([...clean(tracked.stdout, '\n'), ...clean(others.stdout, '\u0000')]);
+}
+function readTreeStart(run: string, options: GuardOptions): TreeStart | null {
+    try {
+        const parsed = JSON.parse(readFileSync(at(options, artifactPath(run)), 'utf8')) as TreeStart;
+        if (typeof parsed.head === 'string' && Array.isArray(parsed.dirty)) return parsed;
+    } catch {
+        /* absent or malformed — the caller fails closed */
+    }
+    return null;
+}
+/** Start snapshot + resolved base + the paths this run wrote: "changed since base", keeping only
+ * start-dirty paths whose content its own edits changed. */
+function runContext(run: string, options: GuardOptions) {
+    const git = gitOf(options);
+    const start = readTreeStart(run, options);
+    if (!start) return null;
+    let base = options.base ?? '';
+    if (!base) {
+        try {
+            const anchored = readFileSync(at(options, join('.spur', 'run', `${run}-base.sha`)), 'utf8').trim();
+            if (/^[0-9a-f]{7,40}$/i.test(anchored)) base = anchored;
+        } catch {
+            /* no precheck anchor — the start head is the base */
+        }
+    }
+    if (!base) base = start.head.length > 0 ? start.head : 'HEAD';
+    const written = changedSinceBase(base, git);
+    for (const entry of start.dirty) if (hashPath(entry.path, git) === entry.sha) written.delete(entry.path);
+    return { git, base, start, written };
+}
+function missingStart(run: string): number {
+    process.stderr.write(`commit-guard: no ${artifactPath(run)} — run \`commit-guard start --run ${run}\` first\n`);
+    return 1;
+}
+/** Fingerprint the tree once, before the run writes anything (R1). */
+export function runStart(run: string, options: GuardOptions = {}): number {
+    const git = gitOf(options);
+    const head = git(['rev-parse', 'HEAD']);
+    const status = git(['status', '--porcelain=v1', '-z']);
+    if (head.status !== 0 || status.status !== 0) {
+        process.stderr.write('commit-guard: git probe failed (rev-parse HEAD / status) — is this a work tree?\n');
+        return 1;
+    }
+    const snapshot: TreeStart = {
+        head: head.stdout.trim(),
+        dirty: parsePorcelainZ(status.stdout).map((path) => ({ path, sha: hashPath(path, git) })),
+    };
+    const abs = at(options, artifactPath(run));
+    mkdirSync(join(abs, '..'), { recursive: true });
+    writeFileSync(`${abs}.tmp`, `${JSON.stringify(snapshot, null, 2)}\n`);
+    renameSync(`${abs}.tmp`, abs); // atomic: a concurrent reader never sees a half-written snapshot
+    return 0;
+}
+/** The first path that is unmerged or carries conflict markers, or null (R4, fail closed). */
+function conflictingTarget(paths: string[], options: GuardOptions, git: GitRunner): string | null {
+    const unmerged = new Set(
+        git(['diff', '--name-only', '--diff-filter=U'])
+            .stdout.split('\n')
+            .map((p) => p.trim()),
+    );
+    for (const path of paths) {
+        if (unmerged.has(path)) return `${path} (unmerged)`;
+        try {
+            if (conflictMarkerLine(readFileSync(at(options, path), 'utf8'))) return `${path} (conflict markers)`;
+        } catch {
+            /* deleted target — nothing to scan */
+        }
+    }
+    return null;
+}
+/** Stage only the listed paths this run wrote (R2) and print `{staged, foreign}` (AC1). */
+export function runStage(run: string, paths: string[], options: GuardOptions = {}): StageResult {
+    if (paths.length === 0) {
+        process.stderr.write(`${COMMIT_GUARD_USAGE}\n`);
+        return { staged: [], foreign: [], exitCode: 1 };
+    }
+    const context = runContext(run, options);
+    if (!context) return { staged: [], foreign: [], exitCode: missingStart(run) };
+    const conflict = conflictingTarget(paths, options, context.git);
+    if (conflict) {
+        process.stderr.write(`commit-guard: refusing to stage ${conflict}; nothing staged\n`);
+        return { staged: [], foreign: [], exitCode: 3 };
+    }
+    const dirtyAtStart = new Set(context.start.dirty.map((entry) => entry.path));
+    const staged = paths.filter((path) => context.written.has(path));
+    const refused = paths.filter((path) => !context.written.has(path));
+    for (const path of refused) {
+        const why = dirtyAtStart.has(path) ? 'foreign — dirty at start, untouched by this run' : 'unchanged since base';
+        process.stderr.write(`commit-guard: refused ${path} (${why})\n`);
+    }
+    if (staged.length > 0 && context.git(['add', '--', ...staged]).status !== 0) {
+        process.stderr.write('commit-guard: git add failed — nothing staged\n');
+        return { staged: [], foreign: [], exitCode: 1 };
+    }
+    const foreign = refused.filter((path) => dirtyAtStart.has(path));
+    process.stdout.write(`${JSON.stringify({ staged, foreign })}\n`);
+    return { staged, foreign, exitCode: refused.length > 0 ? 2 : 0 };
+}
+/** Report the working-tree changes this run did not write, staging nothing (R3). */
+export function runCheck(run: string, options: GuardOptions = {}): number {
+    const context = runContext(run, options);
+    if (!context) return missingStart(run);
+    const foreign = [...changedSinceBase(context.base, context.git)]
+        .filter((path) => !context.written.has(path))
+        .sort();
+    process.stdout.write(`${JSON.stringify({ foreign })}\n`);
+    return 0;
+}
+/** Pull one `--flag value` pair out of argv, or undefined when absent (a missing value is usage). */
+function takeFlag(args: string[], name: string): string | undefined {
+    const index = args.indexOf(name);
+    const value = index === -1 ? undefined : args[index + 1];
+    const missing = value === undefined || value.startsWith('--');
+    if (index !== -1) args.splice(index, missing ? 1 : 2);
+    return missing ? undefined : value;
+}
+export function main(argv: string[], options: GuardOptions = {}): number {
+    const args = [...argv];
+    takeFlag(args, '--spur-bin'); // 0482 R2: pipelines hand every plugin script this flag
+    const sub = args.shift();
+    const run = takeFlag(args, '--run');
+    const base = takeFlag(args, '--base');
+    const usage = (): number => {
+        process.stderr.write(`${COMMIT_GUARD_USAGE}\n`);
+        return 1;
+    };
+    if (!run) return usage();
+    if (sub === 'start') return args.length === 0 ? runStart(run, options) : usage();
+    if (sub === 'check') return args.length === 0 ? runCheck(run, { ...options, base }) : usage();
+    if (sub === 'stage')
+        return runStage(
+            run,
+            args.filter((arg) => arg !== '--'),
+            { ...options, base },
+        ).exitCode;
+    return usage();
+}
+
+if (import.meta.main) {
+    process.exit(main(process.argv.slice(2)));
+}