testguard-cli 0.16.0 → 0.17.0

package/src/scaffold/fix-paths.mjs

@@ -0,0 +1,90 @@
+import { extname } from 'node:path';
+
+const PRIVATE = new Set(['.local', '.wolf', '.git', '.testguard', 'graphify-out']);
+const SUPPORTED = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx', '.py']);
+function refuse(reason) { throw new Error(`fix inventory refused: ${reason}`); }
+function safePath(file) {
+  if (!file || file.includes('\\') || /[\x00-\x1f\x7f-\x9f]/.test(file) || file.split('/').some(part => !part || part === '.' || part === '..') || /^[A-Za-z]:/.test(file)) refuse('unsafe-path');
+  if (Buffer.byteLength(file) > 4096) refuse('path-byte-limit');
+  return file;
+}
+
+export function validateFixProjectPrefix(prefix) {
+  if (typeof prefix !== 'string') refuse('unsafe-project-prefix');
+  if (!prefix) return prefix;
+  safePath(prefix);
+  if (prefix.split('/').some(part => PRIVATE.has(part))) refuse('excluded-project');
+  return prefix;
+}
+
+/** Complete historical marker union only; current filesystem admission remains separate. */
+export function parseFixProjectMarkers(parentRaw, commitRaw, { projectPrefix = '' } = {}) {
+  validateFixProjectPrefix(projectPrefix);
+  const projects = new Set();
+  for (const raw of [parentRaw, commitRaw]) {
+    if (!Buffer.isBuffer(raw)) refuse('buffer-required');
+    if (raw.length > 128 * 1024) refuse('output-byte-limit');
+    let listing;
+    try { listing = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true }).decode(raw); }
+    catch { refuse('invalid-utf8'); }
+    if (listing && !listing.endsWith('\0')) refuse('truncated-output');
+    const files = listing ? listing.slice(0, -1).split('\0') : [];
+    if (files.length > 4096) refuse('tree-name-count-limit');
+    const namesSeen = new Set();
+    for (const name of files) {
+      const file = safePath(name);
+      if (namesSeen.has(file)) refuse('duplicate-path');
+      namesSeen.add(file);
+      if (!file.endsWith('/testguard.claims.json')) continue;
+      const project = file.slice(0, -'/testguard.claims.json'.length);
+      projects.add(project);
+      if (projects.size > 256) refuse('project-count-limit');
+    }
+  }
+  if (projectPrefix) {
+    const descendants = [...projects].filter(project => project.startsWith(`${projectPrefix}/`));
+    projects.clear();
+    for (const project of descendants) projects.add(project.slice(projectPrefix.length + 1));
+  }
+  return Object.freeze([...projects].filter(project => !project.split('/').some(part => PRIVATE.has(part))).sort());
+}
+
+/** Decode complete raw Git data only; supplied exclusions are not discovery authority. */
+export function parseFixChangedPaths(raw, { nestedProjects = [], objectIdWidth, projectPrefix = '' } = {}) {
+  validateFixProjectPrefix(projectPrefix);
+  if (!Buffer.isBuffer(raw)) refuse('buffer-required');
+  if (objectIdWidth !== undefined && objectIdWidth !== 40 && objectIdWidth !== 64) refuse('invalid-object-width');
+  if (raw.length > 128 * 1024) refuse('output-byte-limit');
+  if (!Array.isArray(nestedProjects) || nestedProjects.length > 256) refuse('project-count-limit');
+  const projects = nestedProjects.map(safePath);
+  let text;
+  try { text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(raw); }
+  catch { refuse('invalid-utf8'); }
+  if (text && !text.endsWith('\0')) refuse('truncated-output');
+  const parts = text ? text.slice(0, -1).split('\0') : [];
+  if (parts.length % 2) refuse('malformed-record');
+  if (parts.length / 2 > 256) refuse('path-count-limit');
+  const paths = [], seen = new Set();
+  const counts = { total: 0, supported: 0, deleted: 0, unsupported: 0, excluded: 0 };
+  for (let i = 0; i < parts.length; i += 2) {
+    const match = /^:([0-7]{6}) ([0-7]{6}) ([a-f0-9]{40}|[a-f0-9]{64}) ([a-f0-9]{40}|[a-f0-9]{64}) ([AMDT])$/.exec(parts[i]);
+    if (!match || match[3].length !== match[4].length) refuse('malformed-record');
+    const [, oldMode, newMode, oldId, newId, status] = match;
+    if (objectIdWidth !== undefined && oldId.length !== objectIdWidth) refuse('object-width-mismatch');
+    const oldZero = /^0+$/.test(oldId), newZero = /^0+$/.test(newId);
+    if ((oldMode === '000000') !== oldZero || (newMode === '000000') !== newZero ||
+      (status === 'A' ? !oldZero || newZero : status === 'D' ? oldZero || !newZero : oldZero || newZero)) refuse('inconsistent-identity');
+    const repositoryFile = safePath(parts[i + 1]);
+    if (projectPrefix && !repositoryFile.startsWith(`${projectPrefix}/`)) refuse('out-of-scope-path');
+    const file = projectPrefix ? repositoryFile.slice(projectPrefix.length + 1) : repositoryFile;
+    if (seen.has(file)) refuse('duplicate-path');
+    seen.add(file); counts.total++;
+    if (file.split('/').some(part => PRIVATE.has(part)) || projects.some(project => file === project || file.startsWith(`${project}/`))) {
+      counts.excluded++; continue;
+    }
+    const disposition = status === 'D' ? 'deleted' : !['100644', '100755'].includes(newMode) || !SUPPORTED.has(extname(file)) ? 'unsupported' : 'supported';
+    counts[disposition]++;
+    paths.push(Object.freeze({ file, status, oldMode, newMode, oldId, newId, disposition }));
+  }
+  return Object.freeze({ paths: Object.freeze(paths), counts: Object.freeze(counts) });
+}

package/src/scaffold/intent.mjs

@@ -0,0 +1,2 @@
+// Authoring advice, not an authenticated origin or a verification result.
+export const intentHandoff = 'Supply intended observable behavior from a requirement, ADR, bug or incident independently of the implementation: name inputs, expected outcome and forbidden outcome. Record the supplied source kind/ref; when unavailable, keep inferred. Source references and annotations are not authenticated intent. Review each proposal against that intent before probing.';

package/src/scaffold/open-append.mjs

@@ -0,0 +1,44 @@
+import { constants, closeSync, fstatSync, openSync } from 'node:fs';
+import { isDeepStrictEqual } from 'node:util';
+import { planDraftAppend } from './plan-append.mjs';
+import { prepareDraftAppend } from './prepare-append.mjs';
+
+/** Acquire a checked descriptor; no draft writes and no implicit truncation. */
+export function openDraftAppend({ request, plan }) {
+  const prepared = prepareDraftAppend({ request, plan });
+  let fd, closed = false, releaseResult;
+  function release() {
+    if (closed) return releaseResult;
+    closed = true;
+    let closeError;
+    try { if (fd !== undefined) closeSync(fd); } catch (error) { closeError = error; }
+    let lockRelease;
+    try { lockRelease = prepared.release(); }
+    catch (error) { lockRelease = { released: false, reason: 'lock-release-failed', error: error.message }; }
+    releaseResult = closeError ? { released: false, reason: 'descriptor-close-failed', error: closeError.message, lockRelease } : lockRelease;
+    return releaseResult;
+  }
+  function assertCurrent() {
+    if (closed) throw new Error('draft append descriptor closed');
+    prepared.assertOwned();
+    if (!isDeepStrictEqual(planDraftAppend(request), prepared.plan)) throw new Error('draft append inputs changed before write');
+    if (fd !== undefined) {
+      const stat = fstatSync(fd);
+      if (!stat.isFile() || stat.nlink !== 1 || Object.entries(prepared.plan.draft.identity).some(([key, value]) => stat[key] !== value)) throw new Error('draft append descriptor changed');
+    }
+    prepared.assertOwned();
+  }
+  try {
+    assertCurrent();
+    if (prepared.plan.changed) {
+      if (constants.O_NOFOLLOW === undefined) throw new Error('draft append nofollow unavailable');
+      fd = openSync(prepared.plan.draft.path, constants.O_RDWR | constants.O_NOFOLLOW);
+      assertCurrent();
+    }
+    return Object.freeze({ ...prepared, fd, assertCurrent, release });
+  } catch (error) {
+    if (prepared.recoveryDir) error.recoveryDir = prepared.recoveryDir;
+    error.lockRelease = release();
+    throw error;
+  }
+}

package/src/scaffold/plan-append.mjs

@@ -0,0 +1,37 @@
+import { isDeepStrictEqual } from 'node:util';
+import { admitDraftAppend } from './admission.mjs';
+import { appendDraft } from './append.mjs';
+import { scaffoldFile } from './scaffold.mjs';
+
+const MAX_PROPOSALS = 4096;
+const MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
+
+function boundedLimit(value, ceiling, name) {
+  if (!Number.isSafeInteger(value) || value < 0 || value > ceiling) throw new Error(`${name} must be a non-negative safe integer no greater than ${ceiling}`);
+  return value;
+}
+
+function outputOf(doc, maxOutputBytes) {
+  const output = JSON.stringify(doc, null, 2) + '\n';
+  if (Buffer.byteLength(output, 'utf8') > maxOutputBytes) throw new Error('draft append output byte limit exceeded');
+  return output;
+}
+
+/** Read-only generation. Lower internal limits may tighten, never raise caps. */
+export function planDraftAppend({ maxProposals = MAX_PROPOSALS, maxOutputBytes = MAX_OUTPUT_BYTES, toolVersion = '0.0.0', ...request }) {
+  boundedLimit(maxProposals, MAX_PROPOSALS, 'maxProposals');
+  boundedLimit(maxOutputBytes, MAX_OUTPUT_BYTES, 'maxOutputBytes');
+  const inputs = admitDraftAppend(request);
+  let doc = structuredClone(inputs.draft.doc);
+  let output = outputOf(doc, maxOutputBytes);
+  let generated = 0;
+  const initialFaults = doc.claims.find((claim) => claim.id === inputs.claimId).faults.length;
+  for (const input of inputs.sources) {
+    const proposed = scaffoldFile({ projectDir: inputs.projectDir, file: input.file, source: input.source, claimId: inputs.claimId, toolVersion, maxProposals: maxProposals - generated });
+    generated += proposed.stats.proposals;
+    doc = appendDraft({ draft: doc, proposals: proposed.doc, claimId: inputs.claimId });
+    output = outputOf(doc, maxOutputBytes);
+  }
+  const appended = doc.claims.find((claim) => claim.id === inputs.claimId).faults.length - initialFaults;
+  return { ...inputs, doc, output, changed: !isDeepStrictEqual(doc, inputs.draft.doc), stats: { targets: inputs.sources.length, generated, appended } };
+}

package/src/scaffold/plan-intent-input.mjs

@@ -0,0 +1,38 @@
+import { performance } from 'node:perf_hooks';
+import { intentInputRequest } from './request.mjs';
+import { admitIntentDocument } from './admission.mjs';
+import { readScopedFixCommitInventory } from './fix-input.mjs';
+import { writeSpecDoc } from '../evidence/writer.mjs';
+
+function freezeOwned(value) {
+  if (value && typeof value === 'object') {
+    for (const child of Object.values(value)) freezeOwned(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+/** Validated read-only metadata, not a claim, a measurement or write authorization. */
+export function planIntentInput({ projectDir, command = 'scaffold', values, suppliedOptions = [], files = [], toolVersion = '0.0.0', budgetMs = 5000 }) {
+  if (!Number.isSafeInteger(budgetMs) || budgetMs < 1 || budgetMs > 5000) throw new Error('intent input invalid-budget');
+  const started = performance.now();
+  const request = intentInputRequest({ command, values, suppliedOptions, files });
+  if (!request) throw new Error('intent input requires an explicit mode');
+  const remaining = Math.floor(budgetMs - (performance.now() - started));
+  if (remaining < 1) throw new Error('intent input deadline');
+  let input;
+  if (request.kind === 'document') {
+    const admitted = admitIntentDocument({ projectDir, file: request.file });
+    input = { kind: 'document', file: admitted.file, hash: admitted.hash, bytes: admitted.identity.size };
+  } else {
+    input = { kind: 'fix', ...readScopedFixCommitInventory({ projectDir, commit: request.commit, budgetMs: remaining }) };
+  }
+  const doc = { schemaVersion: 1, tool: { name: 'testguard', version: toolVersion }, purpose: 'authoring-input', verification: 'not-performed', next: 'supply-independent-intent', input };
+  let output;
+  writeSpecDoc('authoring-input', 'read-only input preview', doc, { publish: bytes => {
+    if (Buffer.byteLength(bytes) > 1024 * 1024) throw new Error('intent input output byte limit exceeded');
+    output = bytes;
+  } });
+  if (performance.now() - started >= budgetMs) throw new Error('intent input deadline');
+  return freezeOwned({ doc, output });
+}

package/src/scaffold/prepare-append.mjs

@@ -0,0 +1,46 @@
+import { chmodSync, mkdtempSync } from 'node:fs';
+import { join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { authoringLock, persistRecovery, recoveryBase } from '../claims/annotation-placement.mjs';
+import { sha256 } from '../util/hash.mjs';
+import { planDraftAppend } from './plan-append.mjs';
+
+function freezeOwned(value) {
+  if (value && typeof value === 'object') {
+    for (const child of Object.values(value)) freezeOwned(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+/** Preparation only: current-plan replay and recovery, never draft writes. */
+export function prepareDraftAppend({ request, plan }) {
+  const initial = planDraftAppend(request);
+  if (!isDeepStrictEqual(initial, plan)) throw new Error('draft append plan changed');
+  if (!initial.changed) return freezeOwned({ ready: true, plan: initial, release: () => ({ released: true }), assertOwned: () => {} });
+  // All cooperative source/draft authoring in the checkout shares this lock.
+  const lock = authoringLock(initial.projectDir);
+  let recoveryDir;
+  try {
+    const fresh = planDraftAppend(request);
+    if (!isDeepStrictEqual(fresh, initial)) throw new Error('draft append plan changed under lock');
+    lock.assertOwned();
+    recoveryDir = mkdtempSync(join(recoveryBase(fresh.projectDir), 'testguard-draft-recovery-'));
+    chmodSync(recoveryDir, 0o700);
+    persistRecovery(join(recoveryDir, 'draft.original'), Buffer.from(fresh.draft.source, 'utf8'));
+    const manifest = {
+      state: 'prepared', projectDir: fresh.projectDir, draftPath: fresh.draft.path,
+      claimId: fresh.claimId, sourceHash: fresh.draft.hash,
+      proposedHash: sha256(Buffer.from(fresh.output, 'utf8')), identity: fresh.draft.identity,
+      sources: fresh.sources.map(({ file, hash, identity }) => ({ file, hash, identity })),
+    };
+    persistRecovery(join(recoveryDir, 'manifest.json'), Buffer.from(JSON.stringify(manifest), 'utf8'));
+    lock.assertOwned();
+    return freezeOwned({ ready: true, plan: fresh, recoveryDir, release: lock.release, assertOwned: lock.assertOwned });
+  } catch (error) {
+    if (recoveryDir) error.recoveryDir = recoveryDir;
+    try { error.lockRelease = lock.release(); }
+    catch (releaseError) { error.lockRelease = { released: false, reason: 'lock-release-failed', error: releaseError.message }; }
+    throw error;
+  }
+}

package/src/scaffold/request.mjs

@@ -0,0 +1,30 @@
+/** Token-aware CLI admission; defaults are not explicit user options. */
+export function draftAppendRequest({ command, values, suppliedOptions = [], files = [] }) {
+  if (values.into === undefined) return null;
+  if (command !== 'scaffold') throw new Error('--into is only valid on scaffold');
+  const allowed = new Set(['into', 'claim', 'json', 'help', 'version']);
+  const conflict = suppliedOptions.find(name => !allowed.has(name));
+  if (conflict || values.out !== undefined || values.claims !== undefined) throw new Error(`--into cannot use --${conflict || (values.out !== undefined ? 'out' : 'claims')}`);
+  if (!Array.isArray(values.into) || values.into.length !== 1 || !values.into[0]?.trim() || values.into[0] !== values.into[0].trim()) throw new Error('--into requires exactly one existing draft path');
+  if (!Array.isArray(values.claim) || values.claim.length !== 1 || !values.claim[0]?.trim() || values.claim[0].includes(',') || values.claim[0] !== values.claim[0].trim()) throw new Error('--into requires exactly one --claim <existing-ID>');
+  if (!files.length) throw new Error('--into requires at least one source file');
+  return { draftPath: values.into[0], claimId: values.claim[0], files };
+}
+
+/** Internal read-only input selection; public CLI exposure requires its report contract. */
+export function intentInputRequest({ command, values, suppliedOptions = [], files = [] }) {
+  const modes = ['from-document', 'from-fix'].filter(name => values[name] !== undefined);
+  if (!modes.length) return null;
+  if ('scaffold' !== command) throw new Error('intent input is only valid on scaffold');
+  if (modes.length !== 1) throw new Error('select exactly one input mode');
+  const allowed = new Set(['from-document', 'from-fix', 'json', 'help', 'version']);
+  const conflict = suppliedOptions.find(name => !allowed.has(name)) ?? ['into', 'claim', 'claims', 'out'].find(name => values[name] !== undefined);
+  if (conflict) throw new Error(`intent input cannot use --${conflict}`);
+  if (files.length) throw new Error('intent input cannot use positional source files');
+  const mode = modes[0], selectors = values[mode];
+  if (!Array.isArray(selectors) || selectors.length !== 1 || typeof selectors[0] !== 'string' || !selectors[0] || selectors[0] !== selectors[0].trim() || selectors[0].includes('\0')) throw new Error('intent input requires exactly one nonempty trimmed selector');
+  const selector = selectors[0];
+  if (Buffer.byteLength(selector) > 4096) throw new Error('intent input selector-byte-limit');
+  if (mode === 'from-fix' && !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(selector)) throw new Error('intent input requires full-object-id');
+  return Object.freeze(mode === 'from-document' ? { kind: 'document', file: selector } : { kind: 'fix', commit: selector });
+}

package/src/scaffold/scaffold.mjs

@@ -1,5 +1,5 @@
 import { readFileSync } from 'node:fs';
-import { basename, extname, join } from 'node:path';
+import { join } from 'node:path';
 import { proposalsForLine, functionHead, functionParams } from './producers.mjs';
 import * as py from './producers.python.mjs';
 import { locate } from '../probe/inject.mjs';
@@ -15,8 +15,6 @@ const NO_FIELD_DROPS = /\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)(__tests__|__fixtures
 // change which proposals a JavaScript file gets.
 const NO_FIELD_DROPS_PY = /(^|\/)(test[^/]*\.py|[^/]*_test\.py|conftest\.py)$|(^|\/)(tests?|__fixtures__|fixtures|migrations)\//;
 
-const idPart = (s) => s.replace(/[^A-Za-z0-9]+/g, '-').replace(/^-+|-+$/g, '').toUpperCase();
-
 const isPython = (file) => file.endsWith('.py');
 
 /**
@@ -136,10 +134,13 @@ function anchorFor(source, find, offset) {
  * with `producedBy: { producer: "derived" }` and TODO statements a human must
  * replace. Never touches the real claims file.
  */
-export function scaffoldFile({ projectDir, file, claimId, existingClaims, toolVersion = '0.0.0' }) {
-  const source = readFileSync(join(projectDir, file), 'utf8');
+export function scaffoldFile({ projectDir, file, claimId, existingClaims, toolVersion = '0.0.0', source: admittedSource, maxProposals }) {
+  if (maxProposals !== undefined && (!Number.isSafeInteger(maxProposals) || maxProposals < 0)) throw new Error('maxProposals must be a non-negative safe integer');
+  if (admittedSource !== undefined && typeof admittedSource !== 'string') throw new Error('source must be a string');
+  // Internal authoring can scan bytes already admitted through a descriptor.
+  // Legacy callers still read the file; supplied empty text never falls back.
+  const source = admittedSource === undefined ? readFileSync(join(projectDir, file), 'utf8') : admittedSource;
   const lines = source.split('\n');
-  const stem = idPart(basename(file, extname(file)));
   const producedBy = { producer: 'derived', by: `testguard scaffold ${toolVersion}` };
 
   const groups = new Map(); // key → { id, proposals[] , annotated }
@@ -150,28 +151,40 @@ export function scaffoldFile({ projectDir, file, claimId, existingClaims, toolVe
 
   const fieldDrops = !(isPython(file) ? NO_FIELD_DROPS_PY : NO_FIELD_DROPS).test(file);
   const scan = isPython(file) ? scanPython : scanJs;
-  const proposals = scan({ source, lines, fieldDrops, keep: (fault) => usableProposal(source, fault), anchor: (find, offset) => anchorFor(source, find, offset) });
+  let accepted = 0;
+  const keep = (fault) => {
+    if (!usableProposal(source, fault)) return false;
+    if (maxProposals !== undefined && accepted >= maxProposals) throw new Error('scaffold proposal limit exceeded');
+    accepted++;
+    return true;
+  };
+  const proposals = scan({ source, lines, fieldDrops, keep, anchor: (find, offset) => anchorFor(source, find, offset) });
 
   const existing = new Map((existingClaims?.claims ?? []).map((c) => [c.id, c]));
   const usedIds = new Set();
   for (const p of proposals) {
     const key = claimId ? '__all__' : p.annotation ?? p.fn ?? '__file__';
-    let id = claimId ?? p.annotation ?? `${stem}-${p.fn ? idPart(p.fn) : 'FILE'}`;
+    let id = claimId ?? p.annotation ?? null;
     groupFor(key, id).proposals.push(p);
   }
 
   const defendedBy = discoverDefenders(projectDir, file);
   const claims = [];
+  const reservedIds = new Set([...existing.keys(), ...[...groups.values()].map(g => g.id).filter(id => id !== null)]);
+  let placeholder = 1;
   for (const g of groups.values()) {
     let id = g.id;
+    if (id === null) {
+      do { id = `TODO-CLAIM-${placeholder++}`; } while (reservedIds.has(id) || usedIds.has(id));
+    }
     while (usedIds.has(id)) id += '-2';
     usedIds.add(id);
     const base = existing.get(id);
     const fnLabel = g.proposals[0].fn ? `\`${g.proposals[0].fn}\`` : 'this file';
     const claim = {
       id,
-      statement: base?.statement ?? `TODO: state what ${fnLabel} in ${file} guarantees (${g.proposals.length} proposed fault${g.proposals.length === 1 ? '' : 's'}; keep or drop each)`,
-      source: base?.source ?? { kind: 'manual', ref: `testguard scaffold ${file}` },
+      statement: base?.statement ?? `TODO: supply intended observable behavior for ${fnLabel} in ${file} from a requirement, ADR, bug or incident: inputs, expected outcome and forbidden outcome (${g.proposals.length} proposed fault${g.proposals.length === 1 ? '' : 's'}; keep or drop each against that intent)`,
+      source: base?.source ?? { kind: 'inferred', ref: `testguard scaffold ${file}` },
       severity: base?.severity ?? 'medium',
       producedBy: base?.producedBy ?? producedBy,
       ...(base?.defendedBy?.length ? { defendedBy: base.defendedBy } : defendedBy.length ? { defendedBy } : {}),

package/src/status/status.mjs

@@ -1,17 +1,21 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { existsSync, readFileSync, lstatSync, realpathSync } from 'node:fs';
+import { join, relative, isAbsolute, sep } from 'node:path';
 import { readSpecDoc } from '../evidence/writer.mjs';
 import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
 import { gate } from '../baseline/baseline.mjs';
 import { hashFile, sha256 } from '../util/hash.mjs';
 import { resolveDefenders } from '../probe/runners/shared.mjs';
 import { discoverDefenders } from '../probe/discover.mjs';
-import { defenderSelection } from '../probe/attribution.mjs';
-import { coAuthorshipWarning, sortForReport } from '../render.mjs';
+import { defenderSelection, sameClaimMetadata } from '../probe/attribution.mjs';
+import { coAuthorshipWarning, sortForReport, renderOrigins, renderOriginPolicy } from '../render.mjs';
+import { evaluateOriginPolicy } from '../probe/origin-policy.mjs';
+import { declaredOriginSummary } from '../../spec/lib/origins.mjs';
+import { intentHandoff } from '../scaffold/intent.mjs';
 import { computeChangedGate, defaultIgnorePath } from '../gate/changed.mjs';
 import { headSha, isAncestor } from '../git.mjs';
 import { checkAnchorLocations } from '../claims/anchors.mjs';
 import { computeClaimedSurface, needsClaimExpansion } from './surface.mjs';
+import { projectAnnotationAdvisory } from '../claims/annotations.mjs';
 
 export const faultContentHash = (fault) => sha256(`${fault.find}\n${fault.replace}`);
 
@@ -44,7 +48,7 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
     tool: { name: 'testguard', version: toolVersion },
     generatedAt,
     state: 'no-claims',
-    next: { action: 'scaffold', command: 'testguard scaffold <source-file>', why: 'No testguard.claims.json in this project. Scaffold proposes faults for a file; state what each guarantees, then probe.' },
+    next: { action: 'scaffold', command: 'testguard scaffold <source-file>', why: `No testguard.claims.json in this project. Scaffold proposes mechanical faults, not intent. ${intentHandoff}` },
     provisional: false,
     counts: { claims: 0, faults: 0 },
     stale: [],
@@ -71,14 +75,14 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
   }
   const unclaimedWhy = () => {
     const files = changes.uncovered.map((u) => u.file);
-    return `${files.length} changed file${files.length === 1 ? '' : 's'} since ${changes.ref} carr${files.length === 1 ? 'ies' : 'y'} no claim and no excusing ignore entry: ${files.slice(0, 3).join(', ')}${files.length > 3 ? ', …' : ''}. State the claim before writing more code — TestGuard is silent about unclaimed code by construction.`;
+    return `${files.length} changed file${files.length === 1 ? '' : 's'} since ${changes.ref} carr${files.length === 1 ? 'ies' : 'y'} no claim and no excusing ignore entry: ${files.slice(0, 3).join(', ')}${files.length > 3 ? ', …' : ''}. State the claim before writing more code — TestGuard is silent about unclaimed code by construction. ${intentHandoff}`;
   };
 
   if (!existsSync(paths.claims)) {
     doc.surface = computeClaimedSurface({ projectDir });
     const candidate = doc.surface.rankedUnclaimed[0];
     if (candidate && !changes?.uncovered.length) {
-      doc.next = { action: 'scaffold', command: `testguard scaffold ${candidate.file}`, why: `${doc.surface.sourceModules} source module${doc.surface.sourceModules === 1 ? '' : 's'} exist and none carries a claim. Start with ${candidateReason(doc.surface, candidate)}.`, file: candidate.file };
+      doc.next = { action: 'scaffold', command: `testguard scaffold ${candidate.file}`, why: `${doc.surface.sourceModules} source module${doc.surface.sourceModules === 1 ? '' : 's'} exist and none carries a claim. Start with ${candidateReason(doc.surface, candidate)}. ${intentHandoff}`, file: candidate.file };
     }
     if (changes?.uncovered.length) {
       const u = changes.uncovered[0];
@@ -89,11 +93,13 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
   doc.paths.claims = rel(paths.claims);
 
   const claims = loadClaims(paths.claims);
+  doc.origins = declaredOriginSummary(claims.claims);
+  if (claims.claims.length) doc.notes.push(...projectAnnotationAdvisory(projectDir, claims, { customClaims: paths.claims !== defaultClaimsPath(projectDir) }).notes);
   doc.counts.claims = claims.claims.length;
   doc.counts.faults = claims.claims.reduce((n, c) => n + c.faults.length, 0);
   doc.surface = computeClaimedSurface({ projectDir, claims });
   if (claims.claims.length === 0 && !changes?.uncovered.length) {
-    doc.next = { action: 'scaffold', command: 'testguard scaffold <source-file>', why: 'No claims have been declared; no verification was performed. State a claim before probing.' };
+    doc.next = { action: 'scaffold', command: 'testguard scaffold <source-file>', why: `No claims have been declared; no verification was performed. ${intentHandoff}` };
     return doc;
   }
   const faultIndex = new Map();
@@ -140,6 +146,9 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
   doc.paths.evidence = rel(evidenceFile);
   doc.evidenceSource = evidenceOverride ? 'provided' : 'local';
   const evidence = readSpecDoc('evidence', evidenceFile);
+  // Offline status cannot collect native runner/configuration membership.
+  // Only reuse the selection; a saved pass is never current freshness proof.
+  if (evidence.originPolicy) doc.originPolicy = evaluateOriginPolicy({ claims, evidence, eligibleKinds: evidence.originPolicy.eligibleKinds, fresh: false });
   // A verdict is about a commit. When the evidence describes a different one,
   // say both: "looks right and is not" is the failure mode this prevents.
   doc.evidenceHead = evidence.run.repo.snapshot ?? evidence.run.repo.head;
@@ -162,10 +171,24 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
 
   // ── Staleness: does the evidence still describe this claims file and this tree? ──
   const probed = new Map(evidence.records.map((r) => [`${r.claim.id}/${r.subject.id}`, r]));
+  const discoveryHashCache = new Map();
   for (const key of faultIndex.keys()) if (!probed.has(key)) doc.stale.push(`fault ${key} has never been probed`);
   for (const [key, r] of probed) {
     const cur = faultIndex.get(key);
     if (!cur) { doc.stale.push(`fault ${key} was probed but is no longer in the claims file`); continue; }
+    if (!sameClaimMetadata(r.claim, cur.claim)) doc.stale.push(`claim metadata for ${key} changed since it was probed`);
+    for (const [file, recordedHash] of Object.entries(r.inputs.discoveryHashes ?? {})) {
+      if (!discoveryHashCache.has(file)) {
+        let currentHash = null;
+        try {
+          const path = join(projectDir, file);
+          const inside = relative(realpathSync(projectDir), realpathSync(path));
+          if (!isAbsolute(inside) && inside !== '..' && !inside.startsWith(`..${sep}`) && lstatSync(path).isFile()) currentHash = hashFile(path);
+        } catch { /* Missing/unreadable discovery inputs are stale, not fresh. */ }
+        discoveryHashCache.set(file, currentHash);
+      }
+      if (discoveryHashCache.get(file) !== recordedHash) doc.stale.push(`${file} discovery input changed or became unavailable since ${key} was probed`);
+    }
     if (r.subject.contentHash && r.subject.contentHash !== faultContentHash(cur.fault)) {
       doc.changedFaults.push({ claimId: cur.claim.id, subjectId: cur.fault.id, previousVerdict: r.verdict, file: cur.fault.file });
       doc.stale.push(`fault ${key} changed since it was probed (was ${r.verdict})`);
@@ -264,7 +287,7 @@ export function computeStatus({ projectDir, toolVersion = '0.0.0', generatedAt =
     doc.next = {
       action: 'claim',
       command: `testguard scaffold ${candidate.file}`,
-      why: `The existing claims are defended, but only ${doc.surface.claimedModules} of ${doc.surface.sourceModules} source modules carry a claim. Expand the denominator at ${candidateReason(doc.surface, candidate)}.`,
+      why: `The existing claims are defended, but only ${doc.surface.claimedModules} of ${doc.surface.sourceModules} source modules carry a claim. Expand the denominator at ${candidateReason(doc.surface, candidate)}. ${intentHandoff}`,
       file: candidate.file,
     };
   }
@@ -278,6 +301,8 @@ export function renderStatus(doc) {
   }
   lines.push(`state: ${doc.state}${doc.provisional ? ' (provisional)' : ''} — ${doc.counts.claims} claims / ${doc.counts.faults} faults` + (doc.counts.byVerdict ? `; ${Object.entries(doc.counts.byVerdict).map(([k, v]) => `${v} ${k}`).join(', ')}; ${doc.counts.new ?? 0} new, ${doc.counts.baselined ?? 0} baselined` : '')
   );
+  if (doc.origins) lines.push(renderOrigins(doc.origins));
+  if (doc.originPolicy) lines.push(renderOriginPolicy(doc.originPolicy, { basis: 'offline' }));
   if (doc.surface) {
     const s = doc.surface;
     const history = s.history.available ? `last ${s.history.commitsRead} commit${s.history.commitsRead === 1 ? '' : 's'}` : 'git history unavailable';

package/src/sweep/pool.mjs

@@ -0,0 +1,33 @@
+import { validate } from '../../spec/lib/validate.mjs';
+
+const check = (doc) => {
+  const result = validate('claims', doc);
+  if (!result.ok) throw new Error(`non-conforming sweep draft: ${result.errors.map((e) => `${e.path}: ${e.message}`).join('; ')}`);
+};
+
+/** Keep per-file drafts distinct before selection, without changing callers. */
+export function poolDrafts(drafts) {
+  for (const draft of drafts) check(draft);
+  const pooled = structuredClone(drafts);
+  const entries = pooled.flatMap((draft) => draft.claims.map((claim) => ({ claim, originalId: claim.id, file: claim.faults[0].file ?? '' })));
+  entries.sort((a, b) => a.file.localeCompare(b.file) || a.originalId.localeCompare(b.originalId));
+  const reserved = new Set(entries.map((entry) => entry.originalId));
+  const used = new Set();
+  const nextFor = new Map();
+  for (const { claim, originalId } of entries) {
+    let id = originalId;
+    if (used.has(id)) {
+      let n = nextFor.get(originalId) ?? 2;
+      do {
+        const suffix = `-${n++}`;
+        id = originalId.slice(0, 128 - suffix.length) + suffix;
+      } while (reserved.has(id) || used.has(id));
+      nextFor.set(originalId, n);
+    }
+    claim.id = id;
+    used.add(id);
+  }
+  for (const draft of pooled) check(draft);
+  check({ schemaVersion: 1, claims: pooled.flatMap((draft) => draft.claims) });
+  return pooled;
+}

package/src/sweep/sweep.mjs

@@ -34,6 +34,7 @@ import { existsSync } from 'node:fs';
 import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
 import { computeChangedGate } from '../gate/changed.mjs';
 import { scaffoldFile } from '../scaffold/scaffold.mjs';
+import { poolDrafts } from './pool.mjs';
 import { selectFaults, onWritePath, capFor } from '../supply/select.mjs';
 import { learnedProductivity } from '../supply/feedback.mjs';
 import { loadConcerns, concernById, targetsFor, filterByConcern } from '../supply/concerns.mjs';
@@ -163,6 +164,8 @@ export async function sweep({
   confirmRuns = 3,
   budgetMs = 120_000,
   commandBudget,
+  workers = 1,
+  serial = workers === 1,
   runnerCommand,
   runnerName,
   nodeModules,
@@ -206,9 +209,8 @@ export async function sweep({
   const cPath = claimsPath ?? defaultClaimsPath(projectDir);
   const existingClaims = existsSync(cPath) ? loadClaims(cPath) : { claims: [] };
 
-  const candidates = [];
   const skipped = [];
-  const drafts = [];
+  const rawDrafts = [];
   for (const file of targets) {
     commandBudget?.assertOpen();
     let result;
@@ -225,9 +227,10 @@ export async function sweep({
       skipped.push({ file, reason: 'no line in this file matches a fault producer' });
       continue;
     }
-    drafts.push(result.doc);
-    for (const claim of result.doc.claims) for (const fault of claim.faults) candidates.push({ claim, fault });
+    rawDrafts.push(result.doc);
   }
+  const drafts = poolDrafts(rawDrafts);
+  const candidates = drafts.flatMap((draft) => draft.claims.flatMap((claim) => claim.faults.map((fault) => ({ claim, fault }))));
 
   // What the defenders of this surface are CAPABLE of proving, before anything
   // is probed. A test that replaced the database can prove the call shape and
@@ -259,6 +262,8 @@ export async function sweep({
       claims: { schemaVersion: 1, claims },
       confirmRuns,
       budgetMs,
+      workers,
+      serial,
       commandBudget,
       mode: 'worktree',
       includeDirty,