testguard-cli 0.16.0 → 0.18.0

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

package/src/init/templates/SKILL.md

@@ -54,6 +54,21 @@ sections already listing this project.
 
 ## The one source of truth
 
+Missing source-link advisories in claims/status never replace `next`, change
+verdicts or prove intent. Exact anchors remain checked without annotations.
+Origin summaries are likewise informational: status counts current declared
+claims; evidence/briefs count recorded declarations and records, including
+mixed sources. Source kinds are not authenticated independence. Never use an
+origin label to waive a survivor.
+Optional source links: `testguard claims --annotate --claim <ID>` is a read-only
+file-header preview. Only with explicit permission to edit source, rerun with
+`--apply`; each invocation recomputes its plan. Review refusals and partial
+failures, and retain the reported private recovery originals. Never automatically
+remove an existing lock or roll back over user edits. Placement is file-level,
+not symbol ownership, verified behavior or authenticated intent. Missing links
+do not disable exact fault-anchor checks. Authoring never replaces the status
+operating loop or writes canonical claims/evidence/baselines.
+
 ```bash
 testguard status --json
 ```
@@ -76,6 +91,18 @@ Exit codes: `0` clean · `1` unproven claims (or drift, or unclaimed changes) ·
 
 ## Every change needs a claim
 
+Scaffold proposes mechanical faults, not intended behavior. New drafts declare
+`source.kind: inferred` even when grouped by an annotation. Before adopting a
+draft, ask for the intended observable behavior from a requirement, ADR, bug or
+incident independently of the implementation: inputs, expected outcome and
+forbidden outcome. Record the supplied source kind/ref; when unavailable, keep
+inferred and say the intent remains unestablished. Do not promote origin because
+an annotation exists or tests pass. References are opaque, not authenticated;
+verification commands never fetch them. Preserve existing supplied metadata.
+Review each proposal against that intent, then probe. Do not paraphrase the code
+and call that independent intent, or automatically move drafts into canonical
+claims.
+
 `probe` verifies only the claims that exist; it is silent about unclaimed
 code by construction. So, for every source file you create or change:
 
@@ -108,6 +135,14 @@ code by construction. So, for every source file you create or change:
 
 ## The fix loop
 
+For independently supplied intent in an existing disposable draft, use
+`testguard scaffold <source...> --into <draft.json> --claim <existing-ID> --json`
+to preview appended faults without writes. Omit `--json` only when explicitly
+authorized to update that draft; private recovery is retained. Never use a
+canonical claims/evidence/baseline path. Preserve intended behavior and declared
+origin; generated faults are not independent intent or verification. Review the
+faults and probe the selected draft before promoting it to canonical claims.
+
 1. `testguard status --json` → take `next.target`.
 2. Write the test. It must **fail when the fault is applied and pass on HEAD**. To check the first half by hand: apply `find` → `replace` in the target file, run the defender, restore.
 3. `testguard admit <test-file> --claim <ID>` — the two gates as one verb, on your uncommitted test, without touching the tree: `ADMITTED` (exit 0) means the test is green on HEAD and fails on every fault of the claim, 3/3; `NOT ADMITTED` (exit 1) names the first blocking fault and what to do. `--fault <FID>` judges one fault; `--confirm 1` gives a fast **provisional** `ADMITTED?` that must be confirmed at 3 before you commit. (`testguard probe --claim <ID> --include-dirty` is the same run with the full report.)

package/src/probe/attribution.mjs

@@ -11,8 +11,17 @@
  * worktree is. Everything it needs is passed in.
  */
 
+import { isDeepStrictEqual } from 'node:util';
+
 const isKill = (r) => r.outcome === 'fail' && (r.assertionFailures ?? 0) > 0;
 
+/** Compare only the claim metadata actually recorded in evidence. */
+export function sameClaimMetadata(recorded, current) {
+  if (!recorded || !current) return false;
+  const metadata = ({ id, statement, severity, source, producedBy }) => ({ id, statement, severity, source, producedBy });
+  return isDeepStrictEqual(metadata(recorded), metadata(current));
+}
+
 /**
  * Fold one escalation run into the running attribution state.
  *
@@ -118,6 +127,7 @@ export function defenderSelection(claim, fault) {
 
 export function isReusable(prior, current) {
   if (!prior || !prior.subject?.contentHash) return false;
+  if (current.claim && !sameClaimMetadata(prior.claim, current.claim)) return false;
   // A record that exists because the probe threw is a statement about the run,
   // not about the code. Reusing it would make one disturbed run permanent.
   if (prior.detail?.reason === 'probe-error') return false;

package/src/probe/contention.mjs

@@ -37,9 +37,13 @@ export function processList({ platform = process.platform, run = spawnSync } = {
   try {
     const r = platform === 'win32'
       ? run('wmic', ['process', 'get', 'ProcessId,CommandLine', '/format:csv'], { encoding: 'utf8', timeout: 5000 })
-      : run('ps', ['-Ao', 'pid=,args='], { encoding: 'utf8', timeout: 5000 });
+      : run('ps', ['-Ao', 'pid=,ppid=,stat=,args='], { encoding: 'utf8', timeout: 5000 });
     if (r.status !== 0 || !r.stdout) return [];
     return r.stdout.split('\n').map((line) => {
+      if (platform !== 'win32') {
+        const row = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/.exec(line);
+        if (row) return { pid: Number(row[1]), ppid: Number(row[2]), stat: row[3], command: row[4].trim() };
+      }
       const m = platform === 'win32' ? /^[^,]*,(.*),(\d+)\s*$/.exec(line) : /^\s*(\d+)\s+(.*)$/.exec(line);
       if (!m) return null;
       const [pid, command] = platform === 'win32' ? [m[2], m[1]] : [m[1], m[2]];
@@ -57,8 +61,22 @@ export function processList({ platform = process.platform, run = spawnSync } = {
  */
 export function detectContention({ self = process.pid, alive = defaultAlive, ...opts } = {}) {
   const rows = processList(opts);
+  const owned = new Set([self]);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const row of rows) {
+      if (owned.has(row.ppid) && !owned.has(row.pid)) { owned.add(row.pid); changed = true; }
+    }
+  }
+  const ancestors = new Set();
+  let parent = rows.find((row) => row.pid === self)?.ppid;
+  while (parent && !ancestors.has(parent)) {
+    ancestors.add(parent);
+    parent = rows.find((row) => row.pid === parent)?.ppid;
+  }
   const runners = rows
-    .filter((p) => p.pid !== self && RUNNER_RE.test(p.command) && !SELF_RE.test(p.command))
+    .filter((p) => !owned.has(p.pid) && !ancestors.has(p.pid) && !p.stat?.startsWith('Z') && RUNNER_RE.test(p.command) && (p.ppid !== undefined || !SELF_RE.test(p.command)))
     // `ps` lists the grep/ps itself and any shell wrapper; a runner's command
     // line always names its own binary, so require it to look like an exec.
     .filter((p) => !/^\s*(ps|grep|wmic)\b/.test(p.command))

package/src/probe/cost.mjs

@@ -92,10 +92,11 @@ export function defenderCosts(records) {
  * turns a twenty-four-minute gate into a one-minute one, and until a report
  * names the file nobody knows which test to split.
  */
-export function costReport(records) {
+export function costReport(records, { run } = {}) {
   const claims = claimCosts(records);
   const defenders = defenderCosts(records);
   return {
+    ...(run?.measurements ? { measurements: { ...run.measurements } } : {}),
     totalMs: claims.reduce((a, c) => a + c.ms, 0),
     totalRuns: claims.reduce((a, c) => a + c.runs, 0),
     reusedRecords: records.filter((r) => r.reusedFrom).length,
@@ -118,6 +119,10 @@ export const formatMs = secs;
  */
 export function renderCost(report, { limit = 10 } = {}) {
   const out = [];
+  if (report.measurements) {
+    const m = report.measurements;
+    out.push(`actual elapsed ${secs(m.elapsedMs)}; fresh runners ${secs(m.runnerMs)} across ${m.runnerInvocations} invocations; setup/discovery/other overhead ${secs(m.overheadMs)}`);
+  }
   if (!report.records) return 'no evidence records — run `testguard probe` first; cost is read back from the runs it records.';
   out.push(`${report.records} fault record${report.records === 1 ? '' : 's'} cost ${secs(report.totalMs)} across ${report.totalRuns} defender runs${report.reusedRecords ? ` (${report.reusedRecords} reused; their runs are what they cost when reuse does not apply)` : ''}.`);
   out.push('');

package/src/probe/inject.mjs

@@ -1,3 +1,4 @@
+import { registerCleanup } from './runners/lifecycle.mjs';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
@@ -19,12 +20,7 @@ function restoreAll() {
 function installHandlers() {
   if (handlersInstalled) return;
   handlersInstalled = true;
-  for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
-    process.on(sig, () => {
-      restoreAll();
-      process.exit(130);
-    });
-  }
+  registerCleanup(restoreAll, { priority: 1 });
   process.on('uncaughtException', (err) => {
     restoreAll();
     throw err;