testguard-cli 0.16.0 → 0.17.0

package/src/cli.mjs

@@ -20,6 +20,8 @@ import { mcpCommand } from './commands/mcp.mjs';
 import { admitCommand } from './commands/admit.mjs';
 import { sweepCommand } from './commands/sweep.mjs';
 import { concernsCommand } from './commands/concerns.mjs';
+import { originPolicyRequest } from './probe/origin-policy.mjs';
+import { draftAppendRequest, intentInputRequest } from './scaffold/request.mjs';
 
 const VERSION = JSON.parse(readFileSync(join(fileURLToPath(import.meta.url), '..', '..', 'package.json'), 'utf8')).version;
 const ISSUES = 'https://github.com/raccioly/testguard/issues';
@@ -44,10 +46,12 @@ probe
   --claims <path>      claims file             (default: <dir>/testguard.claims.json)
   --confirm <n>        runs per verdict        (default: 3)
   --budget <ms>        wall clock per run      (default: 120000)
-  --command-budget <ms> cooperative measurement deadline for probe, sweep, or replay. Caps async children; expiry exits 2 and writes no partial result
+  --command-budget <ms> cooperative measurement deadline for probe, sweep, replay, or admit. Caps async children; expiry exits 2 and writes no partial result
   --out <path>         evidence file           (default: <dir>/.testguard/evidence.json)
   --baseline <path>    baseline to gate against (default: <dir>/.testguard/baseline.json if present)
   --severity <level>   gate only at or above   (default: low)
+  --require-origin <kinds> complete confirmed probe only; repeatable comma-separated declared source kinds.
+                       No kind authenticates independence. Policy failures ignore baseline debt and severity floors.
   --ref <commit>       probe this commit in the scratch worktree (default: HEAD). An explicit --ref is honoured even when
                        defender/target files are dirty: a warning names them, the evidence records them (repo.ignoredDirty)
   --ignore-dirty       probe HEAD as committed although defender/target files are dirty (same warning and record)
@@ -69,6 +73,7 @@ probe
   --node-modules <dir> node_modules to link into the scratch worktree (or TESTGUARD_NODE_MODULES)
   --python <path>      Python interpreter for .py defenders (or TESTGUARD_PYTHON; default: $VIRTUAL_ENV, then the project's
                        .venv/venv, then python3 on PATH). Resolved against your working tree, never the scratch worktree.
+  --workers <n>        maximum built-in runner workers (default: 1); Python remains serial
   --serial             run one test file at a time (vitest --no-file-parallelism, jest --runInBand, playwright --workers=1,
                        pytest -p no:xdist);
                        use it when another test runner is already running — probe warns and records the contention either way
@@ -80,13 +85,19 @@ probe
   --json               the status document plus this run's result (records, newSinceBaseline, exitCode)
 
 scaffold   --claim <ID> (put every proposal under this claim; copies it if it exists)  --out <path>  --json
+           --from-document <local-text-path> OR --from-fix <full-commit-ID> inspects read-only authoring inputs;
+           no positional sources or other options except --json/help/version. Stdout only; verification not performed.
+           Document text is not emitted; fix counts retain exclusions. Next: supply independent intent, then review/probe.
+           <source...> --into <existing-draft.json> --claim <ID> appends faults to supplied intent;
+           --json previews without writes. Without --json, updates only that draft with private recovery.
+           No --out/--claims or unrelated options; never canonical claims/evidence/baseline. Unproven until reviewed/probed.
 sweep      --changed <ref> (required unless --save-paths; CI bases and a safe local default are detected)  --cap <n>
            --concern <ID>    aim the sweep by one of this project's concerns: its targets and its fault classes.
                              testguard concerns lists them. --save-paths is sugar for the built-in SAVE-PERSISTS
            --save-paths      sweep every file that WRITES TO STORAGE instead of the diff, and report the surface as the
                              denominator: "120 writes across 38 files, swept 12". A clean sweep over an unstated
                              denominator is a sample of unknown size, not a guarantee that saving works
-           --include-dirty  --exclude <glob>  --confirm <n>  --budget <ms>  --command-budget <ms>  --max <n>  --out <path>  --json
+           --include-dirty  --exclude <glob>  --confirm <n>  --budget <ms>  --command-budget <ms>  --workers <n>  --serial  --max <n>  --out <path>  --json
            the cold start: no claim and no concern needed. Everything it proposes is a DRAFT — it never writes testguard.claims.json,
            and its evidence never replaces .testguard/evidence.json. exit 1 on a fault that survived, or a file no test imports
            shapes: if-guard → if (false) · single-line guard/mutation removed · return <check> → return true
@@ -95,14 +106,16 @@ sweep      --changed <ref> (required unless --save-paths; CI bases and a safe lo
 mcp        no options. JSON-RPC 2.0 over stdio; five READ-ONLY tools (status, brief, claims, evidence, next_command).
            Nothing here runs a probe: next_command hands back the shell line for you to run where the person can see it.
            Register it with your harness — testguard init --mcp prints the config for Claude Code, Cursor and Codex.
-replay     --since <range>   commit range to search for fix commits (HEAD~50..HEAD, a tag, origin/main..HEAD)
+replay     --workers <n> (default 1)  --serial  --budget <ms> (per run)
+           --since <range>   commit range to search for fix commits (HEAD~50..HEAD, a tag, origin/main..HEAD)
            --max <n>         replay at most n fixes (they are slow: one worktree and N runs each)
            --confirm <n>     runs per verdict (default 3); a flaky failure reads as "the suite caught it", so mixed runs are never caught
            --command-budget <ms> cooperative measurement deadline; expiry writes neither replay nor calibration, so an unmeasured suffix cannot look clean
            --out <path>       replay document (default: <dir>/.testguard/replay.json); the calibration goes beside it
            reports, never gates: a bug that escaped is history, not a regression in this change
                    · one-line JSX element removed · on<Event> handler prop dropped
-admit      --claim <ID> (required)  --fault <FID> (one fault only)  --confirm <n>  --json
+admit      --workers <n> (default 1)  --serial  --budget <ms>  --command-budget <ms>
+           --claim <ID> (required)  --fault <FID> (one fault only)  --confirm <n>  --json
            ADMITTED (exit 0) only when every fault of the claim is killed N/N by defenders that are green N/N; anything else is NOT ADMITTED (exit 1) and names the first blocking fault
            the test must be a declared or discovered defender of the claim (exit 3 otherwise); evidence goes to .testguard/evidence-partial.json
 gate       --changed <ref>   measure the change since merge-base(ref, HEAD); auto-detected in GitHub Actions / GitLab CI
@@ -112,6 +125,9 @@ gate       --changed <ref>   measure the change since merge-base(ref, HEAD); aut
            --ignore <path>   ignore file (default: <dir>/testguard.ignore.json; kind=path entries excuse files, with a reason)
            exit 0 every changed source file is claimed or excused · 1 unclaimed file · 2 cannot evaluate · 3 no reference
 claims     --check-anchors   locate every fault without running tests; JS/MJS and Python replacements are syntax-checked in memory
+           --annotate       read-only file-header preview (JS/TS/Python); --claim <ID,ID> selects claims
+           --apply          explicit annotation writes, only with --annotate; retains private recovery on partial failure
+           authoring is not verification; each invocation recomputes its plan. Results are stdout-only, never --out
            --json includes anchorChecks; exit 1 when an anchor is missing/ambiguous or a supported replacement does not compile
 status     --json (exit 0 clean · 1 unproven/stale/unclaimed/invalid anchors · 2 nothing to probe yet)
            --evidence <path>  read this evidence instead of .testguard/evidence.json (e.g. CI's, fetched as an artifact); staleness is still computed from the recorded input hashes, and both commits are named
@@ -162,8 +178,12 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
     parsed = parseArgs({
       args: argv,
       allowPositionals: true,
+      tokens: true,
       options: {
         claims: { type: 'string' },
+        into: { type: 'string', multiple: true },
+        'from-document': { type: 'string', multiple: true },
+        'from-fix': { type: 'string', multiple: true },
         confirm: { type: 'string', default: '3' },
         budget: { type: 'string', default: '120000' },
         'command-budget': { type: 'string' },
@@ -174,8 +194,10 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
         max: { type: 'string', default: '20' },
         ref: { type: 'string' },
         'ignore-dirty': { type: 'boolean', default: false },
+        workers: { type: 'string', default: '1' },
         serial: { type: 'boolean', default: false },
         claim: { type: 'string', multiple: true },
+        'require-origin': { type: 'string', multiple: true },
         fault: { type: 'string' },
         'include-dirty': { type: 'boolean', default: false },
         changed: { type: 'string' },
@@ -209,6 +231,8 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
         markdown: { type: 'boolean', default: false },
         cost: { type: 'boolean', default: false },
         'check-anchors': { type: 'boolean', default: false },
+        annotate: { type: 'boolean', default: false },
+        apply: { type: 'boolean', default: false },
         progress: { type: 'string' },
         help: { type: 'boolean', short: 'h', default: false },
         version: { type: 'boolean', short: 'v', default: false },
@@ -239,6 +263,17 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
     io.out(commandUsage(command));
     return 0;
   }
+  if ((values.annotate || values.apply) && command !== 'claims') {
+    io.err('--annotate and --apply are only valid on claims');
+    return 3;
+  }
+  try { originPolicyRequest(values, command); }
+  catch (e) { io.err(e.message); return 3; }
+  const suppliedOptions = parsed.tokens.filter((token) => token.kind === 'option').map((token) => token.name);
+  try { intentInputRequest({ command, values, suppliedOptions, files: positionals.slice(1) }); }
+  catch (e) { io.err(e.message); return 3; }
+  try { draftAppendRequest({ command, values, suppliedOptions, files: positionals.slice(1) }); }
+  catch (e) { io.err(e.message); return 3; }
   if (![...RUNNER_NAMES, 'auto'].includes(values.runner)) {
     io.err(`--runner must be one of ${RUNNER_NAMES.join(', ')} or auto`);
     return 3;
@@ -249,7 +284,7 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
   }
   try {
     const projectDir = command === 'scaffold' || command === 'admit' ? resolve('.') : resolve(dirArg ?? '.');
-    return await handler({ projectDir, file: dirArg, values, version: VERSION }, io);
+    return await handler({ projectDir, file: dirArg, files: positionals.slice(1), values, suppliedOptions, version: VERSION }, io);
   } catch (e) {
     if (e instanceof ClaimsError || e instanceof PreconditionError || e instanceof GitError || e instanceof SpecDocError) {
       io.err(`error: ${e.message}`);

package/src/commands/admit.mjs

@@ -1,3 +1,4 @@
+import { createCommandBudget, parseCommandBudget } from '../command-budget.mjs';
 import { existsSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
@@ -45,6 +46,14 @@ export async function admitCommand({ file, values, version }, io) {
   }
   const confirmRuns = Number(values.confirm);
   const budgetMs = Number(values.budget);
+  const commandBudgetMs = parseCommandBudget(values['command-budget']);
+  if (commandBudgetMs === null) { io.err('--command-budget must be at least 1000 milliseconds'); return 3; }
+  const commandBudget = createCommandBudget(commandBudgetMs);
+  const workers = Number(values.workers ?? 1);
+  if (!Number.isSafeInteger(workers) || workers < 1) {
+    io.err('--workers must be a positive safe integer');
+    return 3;
+  }
   if (!Number.isInteger(confirmRuns) || confirmRuns < 1 || !Number.isInteger(budgetMs) || budgetMs < 1000) {
     io.err('--confirm must be a positive integer and --budget at least 1000');
     return 3;
@@ -84,6 +93,9 @@ export async function admitCommand({ file, values, version }, io) {
     claims: { ...all, claims: [{ ...claim, faults }] },
     confirmRuns,
     budgetMs,
+    commandBudget,
+    workers,
+    serial: values.serial || workers === 1,
     mode: 'worktree',
     includeDirty: true,
     only: [claimId],
@@ -96,6 +108,7 @@ export async function admitCommand({ file, values, version }, io) {
   });
   if (process.stderr.isTTY && !values.quiet && !values.json) process.stderr.write('\r\x1b[K');
   const outPath = values.out ? resolve(values.out) : join(projectDir, '.testguard', 'evidence-partial.json');
+  commandBudget?.assertOpen();
   writeSpecDoc('evidence', outPath, evidence);
 
   const decision = decideAdmission(evidence.records);

package/src/commands/annotations.mjs

@@ -0,0 +1,67 @@
+import { planAnnotationPlacement, applyAnnotationPlacement, loadAnnotationClaims } from '../claims/annotation-placement.mjs';
+import { validate } from '../../spec/lib/validate.mjs';
+import { SpecDocError } from '../evidence/writer.mjs';
+
+/** Authoring is explicitly selected, never an inspection side effect. */
+export async function annotationsCommand({ projectDir, path, values, suppliedOptions = Object.keys(values), version }, io) {
+  const allowed = new Set(['claims', 'claim', 'annotate', 'apply', 'json']);
+  if (!values.annotate || suppliedOptions.some((key) => !allowed.has(key))) {
+    io.err('--apply requires --annotate; annotation authoring cannot combine inspection/output switches');
+    return 3;
+  }
+  const claimIds = (values.claim ?? []).flatMap((value) => value.split(','));
+  let claims;
+  try {
+    claims = loadAnnotationClaims(path);
+    if (!validate('claims', claims).ok) throw new Error('claims must conform before annotation placement');
+  }
+  catch { io.err('annotation input refused: claims could not be safely loaded or validated'); return 2; }
+  if (claimIds.some((id) => !id || !claims.claims.some((claim) => claim.id === id))) {
+    io.err('--claim must name existing non-empty claim IDs');
+    return 3;
+  }
+  const plan = planAnnotationPlacement({ projectDir, claims, claimIds });
+  const doc = {
+    schemaVersion: 1, tool: { name: 'testguard', version }, mode: values.apply ? 'apply' : 'preview',
+    state: plan.applicable ? 'preview' : 'refused', selected: plan.selectedClaimIds,
+    targets: plan.files.map(({ file, claimIds, changed }) => ({ file, claimIds, action: changed ? 'add' : 'unchanged' })),
+    refused: plan.refused,
+  };
+  if (values.apply) {
+    doc.state = 'refused';
+    doc.outcome = { changed: [], touched: [], unchanged: plan.files.filter((f) => !f.changed).map((f) => f.file), failed: [] };
+    if (plan.applicable) {
+      try {
+        const report = applyAnnotationPlacement({ projectDir, claimsPath: path, plan });
+        doc.state = report.state;
+        doc.outcome = {
+          changed: report.changed, touched: report.touched, unchanged: report.unchanged,
+          failed: report.failed.map(publicFailure), recoveryDir: report.recoveryDir,
+          lockRelease: { released: report.lockRelease.released, ...(report.lockRelease.reason ? { reason: 'owned lock release could not be verified' } : {}) },
+        };
+      } catch (error) {
+        doc.outcome.failed.push(publicFailure({ file: null, stage: 'preparation' }));
+        if (error.recoveryDir) doc.outcome.recoveryDir = error.recoveryDir;
+        if (error.lockRelease) doc.outcome.lockRelease = { released: error.lockRelease.released, ...(error.lockRelease.reason ? { reason: 'owned lock release could not be verified' } : {}) };
+      }
+    }
+  }
+  const checked = validate('annotations', doc);
+  if (!checked.ok) throw new SpecDocError(`annotation result does not conform: ${checked.errors.map((e) => `${e.path}: ${e.message}`).join('; ')}`);
+  if (values.json) io.out(JSON.stringify(doc, null, 2));
+  else {
+    io.out(`Annotation ${doc.mode}: ${doc.state} — file-level authoring, not verification or intent authentication.`);
+    for (const t of doc.targets) io.out(`  ${t.action} ${t.file}: ${t.claimIds.join(', ')}`);
+    for (const r of doc.refused) io.out(`  REFUSED ${r.file}: ${r.reason}`);
+    for (const f of doc.outcome?.failed ?? []) io.out(`  FAILED ${f.file ?? '(operation)'} [${f.stage}]: ${f.reason}`);
+    if (doc.outcome?.recoveryDir) io.out(`Recovery originals retained: ${doc.outcome.recoveryDir}`);
+    if (doc.mode === 'preview' && doc.state === 'preview') io.out('No files changed. Review this selection, then rerun with --apply; the plan is recomputed against current files.');
+  }
+  return doc.state === 'preview' || doc.state === 'applied' ? 0 : 2;
+}
+
+// Raw syscall messages may contain absolute source paths. Keep them in the
+// private recovery journal, never the public authoring document.
+function publicFailure({ file, stage }) {
+  return { file, stage, reason: `Annotation ${stage} failed; inspect private recovery details when available.` };
+}

package/src/commands/claims.mjs

@@ -1,6 +1,6 @@
 import { resolve } from 'node:path';
 import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
-import { scanAnnotations, reconcile } from '../claims/annotations.mjs';
+import { scanAnnotations, reconcile, annotationAdvisory } from '../claims/annotations.mjs';
 import { resolveDefenders } from '../probe/runners/shared.mjs';
 import { discoverDefendersDetailed } from '../probe/discover.mjs';
 import { classifyDefenders } from '../probe/mocks.mjs';
@@ -11,6 +11,7 @@ import { readSpecDoc } from '../evidence/writer.mjs';
 import { existsSync } from 'node:fs';
 import { checkAnchors, renderAnchorChecks } from '../claims/anchors.mjs';
 import { defenderSelection } from '../probe/attribution.mjs';
+import { annotationsCommand } from './annotations.mjs';
 
 /** A selection warning is not a verdict: only a fresh probe can defend it. */
 export function defenderNarrowing(projectDir, claims, records) {
@@ -32,11 +33,13 @@ export function defenderNarrowing(projectDir, claims, records) {
   return warnings;
 }
 
-export async function claimsCommand({ projectDir, values, version }, io) {
+export async function claimsCommand({ projectDir, values, suppliedOptions, version }, io) {
   const path = values.claims ? resolve(values.claims) : defaultClaimsPath(projectDir);
+  if (values.annotate || values.apply) return annotationsCommand({ projectDir, path, values, suppliedOptions, version }, io);
   const claims = loadClaims(path);
   const annotations = scanAnnotations(projectDir);
   const drift = reconcile(claims, annotations);
+  const advisory = annotationAdvisory(claims, annotations, { customClaims: Boolean(values.claims) });
   const anchorChecks = values['check-anchors']
     ? await checkAnchors(projectDir, claims, { python: values.python ? resolve(values.python) : undefined })
     : undefined;
@@ -54,16 +57,17 @@ export async function claimsCommand({ projectDir, values, version }, io) {
   const prior = (values.cost || hasOverrides) && existsSync(ev) ? readSpecDoc('evidence', ev) : undefined;
   const narrowedDefenders = hasOverrides && prior ? defenderNarrowing(projectDir, claims, prior.records) : [];
   if (values.cost) {
-    cost = prior ? costReport(prior.records) : undefined;
+    cost = prior ? costReport(prior.records, { run: prior.run }) : undefined;
     if (!cost && !values.json) io.err(`no evidence at ${ev} — run \`testguard probe\` first; cost is derived from the run durations it records`);
   }
 
   if (values.json) {
-    io.out(JSON.stringify({ path, claims, annotations, drift, ...(hasOverrides ? { narrowedDefenders } : {}), ...(anchorChecks ? { anchorChecks } : {}), ...(removed ? { removed } : {}), ...(cost ? { cost } : {}) }, null, 2));
+    io.out(JSON.stringify({ path, claims, annotations, drift, annotationAdvisory: advisory, ...(hasOverrides ? { narrowedDefenders } : {}), ...(anchorChecks ? { anchorChecks } : {}), ...(removed ? { removed } : {}), ...(cost ? { cost } : {}) }, null, 2));
   } else {
     const annotated = new Set(drift.annotated);
     io.out(`${claims.claims.length} claims in ${path} — ${annotated.size} carry a @claim annotation in source (test files are not scanned)`);
     io.out('');
+    for (const note of advisory.notes) io.out(note);
     const signalLines = [];
     for (const c of claims.claims) {
       const declared = c.defendedBy?.length > 0;

package/src/commands/probe.mjs

@@ -4,13 +4,16 @@ import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
 import { probe } from '../probe/probe.mjs';
 import { writeSpecDoc, readSpecDoc } from '../evidence/writer.mjs';
 import { gate } from '../baseline/baseline.mjs';
-import { renderRecord, renderSummary, sortForReport, PROVISIONAL_WARNING } from '../render.mjs';
+import { renderRecord, renderSummary, sortForReport, PROVISIONAL_WARNING, renderOriginPolicy } from '../render.mjs';
 import { computeStatus } from '../status/status.mjs';
 import { resolveChangedRef, withChangedRef } from '../gate/changed.mjs';
 import { costReport, renderCost } from '../probe/cost.mjs';
 import { progressMode, stageReporter, clearStageLine, recordEvent, isProgressMode, progressStream } from '../probe/progress.mjs';
 import { validate } from '../../spec/lib/validate.mjs';
 import { createCommandBudget, parseCommandBudget } from '../command-budget.mjs';
+import { originPolicyRequest, evaluateOriginPolicy } from '../probe/origin-policy.mjs';
+import { readNativeTestUniverse } from '../probe/universe.mjs';
+import { originPolicyInputsFresh } from '../probe/policy-freshness.mjs';
 export const provisionalEvidencePath = (projectDir) => join(projectDir, '.testguard', 'evidence-provisional.json');
 
 export const evidencePath = (projectDir) => join(projectDir, '.testguard', 'evidence.json');
@@ -35,8 +38,16 @@ export function partialScope(only, records) {
 }
 
 export async function probeCommand({ projectDir, values, version }, io) {
+  let eligibleKinds;
+  try { eligibleKinds = originPolicyRequest(values); }
+  catch (e) { io.err(e.message); return 3; }
   const confirmRuns = Number(values.confirm);
   const budgetMs = Number(values.budget);
+  const workers = Number(values.workers ?? 1);
+  if (!Number.isSafeInteger(workers) || workers < 1) {
+    io.err('--workers must be a positive safe integer');
+    return 3;
+  }
   const commandBudgetMs = parseCommandBudget(values['command-budget']);
   if (!Number.isInteger(confirmRuns) || confirmRuns < 1 || !Number.isInteger(budgetMs) || budgetMs < 1000) {
     io.err('--confirm must be a positive integer and --budget at least 1000');
@@ -94,12 +105,13 @@ export async function probeCommand({ projectDir, values, version }, io) {
     previous,
     confirmRuns,
     budgetMs,
+    workers,
+    serial: values.serial || workers === 1,
     commandBudget,
     mode: values['in-place'] ? 'in-place' : 'worktree',
     ref: values.ref ?? 'HEAD',
     refExplicit: values.ref !== undefined,
     ignoreDirty: values['ignore-dirty'],
-    serial: values.serial,
     onWarn: (m) => io.err(`warning: ${m}`),
     runnerCommand: values['runner-cmd'],
     runnerName: values.runner,
@@ -123,17 +135,47 @@ export async function probeCommand({ projectDir, values, version }, io) {
     },
   });
   commandBudget?.assertOpen();
+  if (eligibleKinds) {
+    let universe;
+    // Custom commands carry a static universe, which cannot establish this
+    // native policy boundary. Discovery failures are unavailability, not kills.
+    if (!values['runner-cmd']) {
+      try {
+        universe = await readNativeTestUniverse({
+          projectDir, sourceDir: projectDir, runnerName: values.runner,
+          python: values.python ? resolve(values.python) : undefined,
+          budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs,
+          budgetFor: () => commandBudget?.runBudget(budgetMs) ?? budgetMs,
+          assertOpen: () => commandBudget?.assertOpen(),
+        });
+      } catch { /* An absent binding can never pass policy. */ }
+    }
+    commandBudget?.assertOpen();
+    const currentClaims = loadClaims(values.claims ? resolve(values.claims) : defaultClaimsPath(projectDir));
+    const fresh = originPolicyInputsFresh({ projectDir, claims: currentClaims, evidence, universe });
+    evidence.originPolicy = evaluateOriginPolicy({ claims: currentClaims, evidence, eligibleKinds, fresh });
+  }
+  commandBudget?.assertOpen();
   writeSpecDoc('evidence', outPath, evidence);
 
   const g = gate(evidence.records, baseline, { severityFloor: values.severity });
+  const policy = evidence.originPolicy;
+  const exitCode = policy?.state === 'unavailable' ? 2 : policy?.state === 'failed' || g.new.length > 0 ? 1 : 0;
   const scope = partialScope(only, evidence.records);
   if (values.json) {
-    const status = withChangedRef(resolveChangedRef({ explicit: values.changed, projectDir }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'], evidence: outPath }), io.err);
-    const doc = { ...status, run: { id: evidence.run.id, evidence: outPath, provisional, records: evidence.records.length, newSinceBaseline: g.new.length, exitCode: g.new.length > 0 ? 1 : 0, ...(scope ? { scope } : {}) }, ...(values.cost ? { cost: costReport(evidence.records) } : {}) };
+    const status = withChangedRef(resolveChangedRef({ explicit: values.changed, projectDir }), (changedRef) => computeStatus({
+      projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'], evidence: outPath,
+      paths: {
+        claims: values.claims ? resolve(values.claims) : defaultClaimsPath(projectDir),
+        evidence: outPath, provisional: provisionalEvidencePath(projectDir),
+        baseline: values.baseline ? resolve(values.baseline) : baselinePath(projectDir),
+      },
+    }), io.err);
+    const doc = { ...status, ...(policy ? { originPolicy: policy } : {}), run: { id: evidence.run.id, evidence: outPath, provisional, records: evidence.records.length, newSinceBaseline: g.new.length, exitCode, ...(policy ? { originPolicy: policy } : {}), ...(scope ? { scope } : {}) }, ...(values.cost ? { cost: costReport(evidence.records, { run: evidence.run }) } : {}) };
     const result = validate('status', doc);
     if (!result.ok) throw new Error(`probe JSON document does not conform: ${result.errors.map((e) => `${e.path}: ${e.message}`).join('; ')}`);
     io.out(JSON.stringify(doc, null, 2));
-    return g.new.length > 0 ? 1 : 0;
+    return exitCode;
   }
   if (!values.quiet && baseline) {
     io.out('');
@@ -146,12 +188,13 @@ export async function probeCommand({ projectDir, values, version }, io) {
     if (killed) io.out(`  ${killed} killed (not listed; --verbose to see them)`);
   }
   io.out(renderSummary(evidence.records, evidence.run) + (baseline ? ` ${g.new.length} new since baseline, ${g.baselined.length} baselined.` : ' No baseline.'));
+  if (policy) io.out(renderOriginPolicy(policy, { basis: 'current' }));
   if (values.cost) {
     io.out('');
-    io.out(renderCost(costReport(evidence.records)));
+    io.out(renderCost(costReport(evidence.records, { run: evidence.run })));
     io.out('');
   }
   io.out(`evidence: ${outPath}${scope ? ` (partial: ${scope.requestedCount} claim${scope.requestedCount === 1 ? '' : 's'} requested, ${scope.probedCount} probed: --claim ${scope.requestedClaims.join(',')}; not the canonical evidence file)` : provisional ? ' (provisional; not the canonical evidence file)' : ''}`);
   if (provisional && !values.quiet) io.err(PROVISIONAL_WARNING(confirmRuns));
-  return g.new.length > 0 ? 1 : 0;
+  return exitCode;
 }

package/src/commands/replay.mjs

@@ -14,6 +14,11 @@ export async function replayCommand({ projectDir, values, version }, io) {
   }
   const confirmRuns = Number(values.confirm);
   const budgetMs = Number(values.budget);
+  const workers = Number(values.workers ?? 1);
+  if (!Number.isSafeInteger(workers) || workers < 1) {
+    io.err('--workers must be a positive safe integer');
+    return 3;
+  }
   const commandBudgetMs = parseCommandBudget(values['command-budget']);
   const limit = values.max ? Number(values.max) : undefined;
   if (!Number.isInteger(confirmRuns) || confirmRuns < 1 || !Number.isInteger(budgetMs) || budgetMs < 1000) {
@@ -31,6 +36,8 @@ export async function replayCommand({ projectDir, values, version }, io) {
     range,
     confirmRuns,
     budgetMs,
+    workers,
+    serial: values.serial || workers === 1,
     commandBudget,
     runnerCommand: values['runner-cmd'],
     runnerName: values.runner,

package/src/commands/scaffold.mjs

@@ -1,11 +1,58 @@
 import { existsSync } from 'node:fs';
 import { join, resolve, relative, basename, extname } from 'node:path';
 import { scaffoldFile } from '../scaffold/scaffold.mjs';
+import { intentHandoff } from '../scaffold/intent.mjs';
 import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
 import { writeSpecDoc } from '../evidence/writer.mjs';
 import { PreconditionError } from '../probe/worktree.mjs';
+import { draftAppendRequest, intentInputRequest } from '../scaffold/request.mjs';
+import { planIntentInput } from '../scaffold/plan-intent-input.mjs';
+import { planDraftAppend } from '../scaffold/plan-append.mjs';
+import { applyDraftAppend } from '../scaffold/apply-append.mjs';
 
-export async function scaffoldCommand({ projectDir, file, values, version }, io) {
+export async function scaffoldCommand({ projectDir, file, files = file ? [file] : [], values, suppliedOptions = [], version }, io) {
+  let input;
+  try { input = intentInputRequest({ command: 'scaffold', values, suppliedOptions, files }); }
+  catch (error) { io.err(error.message); return 3; }
+  if (input) {
+    try {
+      const plan = planIntentInput({ projectDir, command: 'scaffold', values, suppliedOptions, files, toolVersion: version });
+      if (values.json) io.out(plan.output.trimEnd());
+      else {
+        io.out(`authoring input inspection (${input.kind}); verification not performed`);
+        if (input.kind === 'fix') {
+          const counts = plan.doc.input.counts;
+          io.out(`${counts.total} changed paths: ${counts.supported} supported, ${counts.deleted} deleted, ${counts.unsupported} unsupported, ${counts.excluded} excluded`);
+        }
+        io.out('Next: supply independent intent, review proposed faults, then probe. Input inspection is not verification.');
+      }
+      return 0;
+    } catch (error) { io.err(`intent input refused: ${error.message}`); return 2; }
+  }
+  let append;
+  try { append = draftAppendRequest({ command: 'scaffold', values, suppliedOptions, files }); }
+  catch (error) { io.err(error.message); return 3; }
+  if (append) {
+    try {
+      const request = { ...append, projectDir, toolVersion: version };
+      const plan = planDraftAppend(request);
+      if (values.json) {
+        writeSpecDoc('claims', plan.draft.path, plan.doc, { publish: output => io.out(output.trimEnd()) });
+        return 0;
+      }
+      const report = applyDraftAppend({ request, plan });
+      if (!report.ok) {
+        io.err(`draft append ${report.state}: ${report.failed.map(f => `${f.stage}: ${f.reason}`).join('; ')}; write attempted: ${report.writeAttempted}; bytes written: ${report.bytesWritten}`);
+        if (report.recoveryDir) io.err(`private recovery: ${report.recoveryDir}`);
+        return 2;
+      }
+      io.out(`unproven draft ${report.state}: ${plan.draft.path} (${plan.stats.appended} appended faults)`);
+      if (report.recoveryDir) io.out(`private recovery: ${report.recoveryDir}`);
+      io.out('Next: review the proposed faults against supplied intent, then probe the draft. Authoring is not verification.');
+      return 0;
+    } catch (error) { io.err(`draft append refused: ${error.message}`); return 2; }
+  }
+  if (files.length > 1) { io.err('ordinary scaffold accepts one source file; use --into for multiple sources'); return 3; }
   if (!file) {
     io.err('usage: testguard scaffold <source-file> [--claim <ID>] [--out <path>] [--json]');
     return 3;
@@ -38,6 +85,6 @@ export async function scaffoldCommand({ projectDir, file, values, version }, io)
   io.out(`${stats.proposals} proposed fault${stats.proposals === 1 ? '' : 's'} in ${stats.claims} draft claim${stats.claims === 1 ? '' : 's'} for ${rel}${shapes ? ` — ${shapes}` : ''}`);
   io.out(stats.defendedBy.length ? `defendedBy prefilled from imports: ${stats.defendedBy.join(', ')}` : 'no test file imports this module; probing the draft as-is will report NOCOVER');
   io.out(`draft: ${outPath}`);
-  io.out('Next: replace each TODO statement, drop proposals that are not claims, then move the claims into testguard.claims.json.');
+  io.out(`Next: ${intentHandoff} Replace each TODO statement, drop proposals that do not express the intended claim, then review before moving the claims into testguard.claims.json.`);
   return 0;
 }

package/src/commands/sweep.mjs

@@ -32,6 +32,11 @@ export async function sweepCommand({ projectDir, values, version }, io) {
   const mode = values['save-paths'] ? 'save-paths' : 'changed';
   const confirmRuns = Number(values.confirm);
   const budgetMs = Number(values.budget);
+  const workers = Number(values.workers ?? 1);
+  if (!Number.isSafeInteger(workers) || workers < 1) {
+    io.err('--workers must be a positive safe integer');
+    return 3;
+  }
   const commandBudgetMs = parseCommandBudget(values['command-budget']);
   if (!Number.isInteger(confirmRuns) || confirmRuns < 1 || !Number.isInteger(budgetMs) || budgetMs < 1000) {
     io.err('--confirm must be a positive integer and --budget at least 1000');
@@ -77,6 +82,8 @@ export async function sweepCommand({ projectDir, values, version }, io) {
       cap,
       confirmRuns,
       budgetMs,
+      workers,
+      serial: values.serial || workers === 1,
       commandBudget,
       runnerCommand: values['runner-cmd'],
       runnerName: values.runner,

package/src/evidence/writer.mjs

@@ -1,3 +1,4 @@
+import { assertNotCancelled } from '../probe/runners/lifecycle.mjs';
 import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { validate } from '../../spec/lib/validate.mjs';
@@ -13,18 +14,25 @@ function describe(kind, path, result) {
  * Write a spec document — but only if it conforms. The tool is held to its
  * own spec at the moment of output, not by a separate test someone might skip.
  */
-export function writeSpecDoc(kind, path, doc) {
+export function writeSpecDoc(kind, path, doc, { publish } = {}) {
+  assertNotCancelled();
   const result = validate(kind, doc);
   if (!result.ok) throw new SpecDocError('refusing to write: ' + describe(kind, path, result));
+  const output = JSON.stringify(doc, null, 2) + '\n';
+  if (publish !== undefined) {
+    if (typeof publish !== 'function') throw new TypeError('publish must be a function');
+    return publish(output);
+  }
   mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, JSON.stringify(doc, null, 2) + '\n');
+  writeFileSync(path, output);
 }
 
 /** Read a spec document, refusing one that does not conform. */
-export function readSpecDoc(kind, path) {
+export function readSpecDoc(kind, path, { source } = {}) {
   let doc;
   try {
-    doc = JSON.parse(readFileSync(path, 'utf8'));
+    if (source !== undefined && typeof source !== 'string') throw new Error('source must be a string');
+    doc = JSON.parse(source === undefined ? readFileSync(path, 'utf8') : source);
   } catch (e) {
     throw new SpecDocError(`cannot read ${kind} document ${path}: ${e.message}`);
   }

package/src/git.mjs

@@ -7,7 +7,7 @@ import { randomBytes } from 'node:crypto';
 export class GitError extends Error {}
 
 export function gitRaw(args, cwd, env) {
-  const r = spawnSync('git', args, { cwd, encoding: 'utf8', env: env ? { ...process.env, ...env } : process.env });
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8', timeout: 30_000, maxBuffer: 16 * 1024 * 1024, env: env ? { ...process.env, ...env } : process.env });
   if (r.status !== 0) throw new GitError(`git ${args.join(' ')}: ${(r.stderr || r.stdout).trim()}`);
   return r.stdout;
 }
@@ -27,7 +27,7 @@ export function headSha(dir, ref = 'HEAD') {
 
 /** Is `ancestor` reachable from `ref`? False when either does not resolve. */
 export function isAncestor(dir, ancestor, ref = 'HEAD') {
-  return spawnSync('git', ['merge-base', '--is-ancestor', ancestor, ref], { cwd: dir }).status === 0;
+  return spawnSync('git', ['merge-base', '--is-ancestor', ancestor, ref], { cwd: dir, timeout: 30_000 }).status === 0;
 }
 
 /** True when any of `paths` (repo-relative; empty = whole tree) has uncommitted changes. */
@@ -59,7 +59,7 @@ export function snapshotWorkingTree(repo) {
 }
 
 export function removeWorktree(repo, dest) {
-  spawnSync('git', ['worktree', 'remove', '--force', dest], { cwd: repo });
+  spawnSync('git', ['worktree', 'remove', '--force', dest], { cwd: repo, timeout: 30_000 });
   rmSync(dest, { recursive: true, force: true });
-  spawnSync('git', ['worktree', 'prune'], { cwd: repo });
+  spawnSync('git', ['worktree', 'prune'], { cwd: repo, timeout: 30_000 });
 }