testguard-cli 0.15.1 → 0.17.0

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';
@@ -5,6 +6,7 @@ import { probe } from '../probe/probe.mjs';
 import { writeSpecDoc } from '../evidence/writer.mjs';
 import { resolveDefenders } from '../probe/runners/shared.mjs';
 import { discoverDefenders } from '../probe/discover.mjs';
+import { defenderSelection } from '../probe/attribution.mjs';
 import { PreconditionError } from '../probe/worktree.mjs';
 import { hintFor } from '../brief/brief.mjs';
 import { formatVerdict, PROVISIONAL_WARNING } from '../render.mjs';
@@ -44,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;
@@ -62,11 +72,15 @@ export async function admitCommand({ file, values, version }, io) {
 
   // The named test must be a defender of the claim, declared or discovered;
   // otherwise `killed` below would be someone else's test doing the work.
-  const declared = claim.defendedBy?.length ? resolveDefenders(projectDir, claim.defendedBy) : null;
-  const isDefender = declared ? declared.includes(testRel) : faults.some((f) => discoverDefenders(projectDir, f.file).includes(testRel));
+  const selections = faults.map((f) => {
+    const { requested } = defenderSelection(claim, f);
+    return { requested, resolved: requested.length ? resolveDefenders(projectDir, requested) : discoverDefenders(projectDir, f.file) };
+  });
+  const declared = selections.every((s) => s.requested.length) ? selections[0].requested : null;
+  const isDefender = selections.some((s) => s.resolved.includes(testRel));
   if (!isDefender) {
     io.err(declared
-      ? `${testRel} is not a defender of ${claimId}. Add it: "defendedBy": [${[...claim.defendedBy, testRel].map((d) => JSON.stringify(d)).join(', ')}] in testguard.claims.json, then run admit again.`
+      ? `${testRel} is not a defender of ${claimId}. Add it: "defendedBy": [${[...declared, testRel].map((d) => JSON.stringify(d)).join(', ')}] on the selected fault or its inherited claim in testguard.claims.json, then run admit again.`
       : `${testRel} does not import ${[...new Set(faults.map((f) => f.file))].join(' or ')}, so it cannot be discovered as a defender of ${claimId}. Import the module under test, or declare "defendedBy": ["${testRel}"] on the claim.`);
     return 3;
   }
@@ -79,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],
@@ -91,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';
@@ -10,12 +10,36 @@ import { costReport, renderCost } from '../probe/cost.mjs';
 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';
 
-export async function claimsCommand({ projectDir, values, version }, io) {
+/** A selection warning is not a verdict: only a fresh probe can defend it. */
+export function defenderNarrowing(projectDir, claims, records) {
+  const prior = new Map(records.map((r) => [`${r.claim.id}/${r.subject.id}`, r]));
+  const warnings = [];
+  for (const c of claims.claims) {
+    const inherited = c.defendedBy?.length ? resolveDefenders(projectDir, c.defendedBy) : [];
+    for (const f of c.faults) {
+      const record = prior.get(`${c.id}/${f.id}`);
+      if (!Object.hasOwn(f, 'defendedBy') || record?.verdict !== 'killed') continue;
+      const { requested } = defenderSelection(c, f);
+      const resolved = requested.length ? resolveDefenders(projectDir, requested) : discoverDefendersDetailed(projectDir, f.file).canDetect;
+      if (record.defenders.selectionSource === 'fault' && JSON.stringify(record.defenders.requested) === JSON.stringify(requested) && JSON.stringify([...record.defenders.resolved].sort()) === JSON.stringify([...resolved].sort())) continue;
+      if (resolved.length < inherited.length && resolved.every((d) => inherited.includes(d))) {
+        warnings.push({ claimId: c.id, faultId: f.id, inherited, resolved });
+      }
+    }
+  }
+  return warnings;
+}
+
+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;
@@ -28,24 +52,39 @@ export async function claimsCommand({ projectDir, values, version }, io) {
 
   // Cost is read back out of evidence the probe already wrote; it never runs a test.
   let cost;
+  const ev = values.evidence ? resolve(values.evidence) : evidencePath(projectDir);
+  const hasOverrides = claims.claims.some((c) => c.faults.some((f) => Object.hasOwn(f, 'defendedBy')));
+  const prior = (values.cost || hasOverrides) && existsSync(ev) ? readSpecDoc('evidence', ev) : undefined;
+  const narrowedDefenders = hasOverrides && prior ? defenderNarrowing(projectDir, claims, prior.records) : [];
   if (values.cost) {
-    const ev = values.evidence ? resolve(values.evidence) : evidencePath(projectDir);
-    cost = existsSync(ev) ? costReport(readSpecDoc('evidence', ev).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, ...(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;
       const targets = [...new Set(c.faults.map((f) => f.file))];
       let cover;
-      if (declared) {
+      if (c.faults.some((f) => Object.hasOwn(f, 'defendedBy'))) {
+        const selected = new Set();
+        for (const f of c.faults) {
+          const selection = defenderSelection(c, f);
+          const defenders = selection.requested.length ? resolveDefenders(projectDir, selection.requested) : discoverDefendersDetailed(projectDir, f.file).canDetect;
+          defenders.forEach((d) => selected.add(d));
+          const m = classifyDefenders(projectDir, f.file, defenders);
+          for (const s of m.signals) signalLines.push({ claim: c.id, target: f.file, ...s });
+          io.out(`  ${c.id}/${f.id}: ${selection.selectionSource}${selection.requested.length ? '' : ' (discovery)'} — ${defenders.join(', ') || 'NO DEFENDER'}`);
+        }
+        cover = `${selected.size} selected defender${selected.size === 1 ? '' : 's'}`;
+      } else if (declared) {
         const defenders = resolveDefenders(projectDir, c.defendedBy);
         const mocking = new Set();
         for (const t of targets) { const m = classifyDefenders(projectDir, t, defenders); m.mocking.forEach((f) => mocking.add(f)); for (const s of m.signals) signalLines.push({ claim: c.id, target: t, ...s }); }
@@ -70,6 +109,7 @@ export async function claimsCommand({ projectDir, values, version }, io) {
     if (drift.undeclared.length || drift.stale.length) io.out('');
     for (const a of drift.undeclared) io.out(`UNDECLARED   @claim ${a.id} at ${a.file}:${a.line} has no entry in the claims file — a claim with no fault model`);
     for (const c of drift.stale) io.out(`STALE        ${c.id} is annotation-sourced but no source file carries @claim ${c.id}`);
+    for (const w of narrowedDefenders) io.out(`NARROWED-DEFENDERS  ${w.claimId}/${w.faultId} selects ${w.resolved.length} of ${w.inherited.length} inherited defenders after a prior kill — re-probe; the old kill does not prove the narrower selection.`);
     if (removed) {
       io.out('');
       io.out(renderRemoved(removed));

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/gate/changed.mjs

@@ -5,6 +5,7 @@ import { loadClaims, defaultClaimsPath, ClaimsError } from '../claims/load.mjs';
 import { readSpecDoc } from '../evidence/writer.mjs';
 import { resolveDefenders } from '../probe/runners/shared.mjs';
 import { discoverDefenders } from '../probe/discover.mjs';
+import { defenderSelection } from '../probe/attribution.mjs';
 import { IS_PY_TEST } from '../probe/pyimports.mjs';
 import { globToRegExp } from '../util/glob.mjs';
 
@@ -228,7 +229,10 @@ export function computeChangedGate({ projectDir, ref, includeDirty = false, excl
   const defenderFiles = new Map(); // test file → claimIds
   for (const c of claims.claims) {
     for (const f of c.faults) faultFiles.set(f.file, [...new Set([...(faultFiles.get(f.file) ?? []), c.id])]);
-    const defenders = c.defendedBy?.length ? resolveDefenders(projectDir, c.defendedBy) : [...new Set(c.faults.flatMap((f) => discoverDefenders(projectDir, f.file)))];
+    const defenders = [...new Set(c.faults.flatMap((f) => {
+      const { requested } = defenderSelection(c, f);
+      return requested.length ? resolveDefenders(projectDir, requested) : discoverDefenders(projectDir, f.file);
+    }))];
     for (const d of defenders) defenderFiles.set(d, [...new Set([...(defenderFiles.get(d) ?? []), c.id])]);
   }
 

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 });
 }

package/src/init/init.mjs

@@ -56,6 +56,12 @@ Before writing or changing tests, run \`testguard status --json [dir]\` and foll
 The full operating loop and the verdict table are in \`.claude/skills/testguard/SKILL.md\`.
 Never make a fault die by editing \`testguard.claims.json\`; write the test. Claim edits are recorded in the evidence.
 
+Once per AI session, identify the exact CLI used (project-local first, then repository-root, then PATH) and read its \`--version\`.
+If network policy permits, check \`npm view testguard-cli dist-tags.latest --json --fetch-retries=0 --fetch-timeout=5000\` once; this is optional AI advice, not a CLI or hook network call.
+Compare stable versions numerically by SemVer; do not downgrade or replace a prerelease/development checkout. If a newer stable version exists, suggest it and ask before updating, respecting pins and the original package manager.
+Never install automatically or alter lockfiles/CI pins without approval. On an unavailable check, continue without claiming up-to-date; keep advice separate from evidence, verdicts and exit codes. Do not repeat a declined suggestion this session.
+Existing copied skills and sections are preserved by ordinary init; review and merge template changes manually, or use \`init --force\` only with approval to overwrite the skill.
+
 ${lines.join('\n')}
 ${AGENTS_END}`;
 }