testguard-cli 0.16.0 → 0.18.0

package/src/claims/annotation-placement.mjs

@@ -0,0 +1,357 @@
+import { constants, chmodSync, closeSync, fsyncSync, fstatSync, ftruncateSync, lstatSync, mkdtempSync, openSync, readSync, realpathSync, renameSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { validate } from '../../spec/lib/validate.mjs';
+import { locate } from '../probe/inject.mjs';
+import { sha256 } from '../util/hash.mjs';
+
+const SUPPORTED = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx', '.py']);
+const SKIP = new Set(['node_modules', 'dist', 'coverage', 'test', 'tests', '__tests__']);
+const CLAIM_ID = /^[A-Za-z0-9]+(?:[._][A-Za-z0-9]+)*-[A-Za-z0-9._-]*[A-Za-z0-9]$/;
+const MAX_BYTES = 2 * 1024 * 1024;
+const MAX_PLAN_BYTES = 16 * 1024 * 1024;
+
+function canonicalRoot(projectDir) {
+  const requested = resolve(projectDir);
+  try {
+    // Keep a directly symlinked root for admission to refuse; parent aliases
+    // are resolved once so plans bind the actual explicitly selected root.
+    if (lstatSync(requested).isSymbolicLink()) return requested;
+    return realpathSync(requested);
+  } catch { return requested; }
+}
+
+function containedRelative(file) {
+  return file !== '..' && !file.startsWith(`..${sep}`) && !isAbsolute(file);
+}
+
+function selectedClaimsPath(root, projectDir, claimsPath) {
+  const fromSelected = relative(resolve(projectDir), resolve(claimsPath));
+  return containedRelative(fromSelected) ? resolve(root, fromSelected) : resolve(claimsPath);
+}
+
+export function recoveryBase(root) {
+  const base = realpathSync(tmpdir());
+  if (containedRelative(relative(root, base))) throw new Error('recovery directory must be outside the project');
+  return base;
+}
+
+/** Admission precedes reads: do not follow even an ancestor symlink. */
+function admittedPath(root, file, { source = true } = {}) {
+  const parts = file.split('/');
+  if (file.includes('\\') || parts.some((p) => !p || p === '.' || p === '..') || resolve(root, file) !== join(root, ...parts)) return { reason: 'unsafe-path' };
+  if (source && (parts.some((p) => p.startsWith('.') || SKIP.has(p)) || /\.(test|spec)\.[cm]?[jt]sx?$/.test(file))) return { reason: 'excluded-target' };
+  if (source && !SUPPORTED.has(extname(file))) return { reason: 'unsupported-source' };
+  let path = root;
+  try {
+    const base = lstatSync(root);
+    if (base.isSymbolicLink() || !base.isDirectory()) return { reason: 'symlink-target' };
+    for (let i = 0; i < parts.length; i++) {
+      path = join(path, parts[i]);
+      const stat = lstatSync(path);
+      if (stat.isSymbolicLink()) return { reason: 'symlink-target' };
+      if (i < parts.length - 1) {
+        if (!stat.isDirectory()) return { reason: 'not-regular-file' };
+        try { lstatSync(join(path, 'testguard.claims.json')); return { reason: 'nested-project' }; }
+        catch (error) { if (error.code !== 'ENOENT') throw error; }
+      } else {
+        if (!stat.isFile() || stat.nlink !== 1) return { reason: 'not-regular-file' };
+        if (stat.size > MAX_BYTES) return { reason: 'source-too-large' };
+        return { path, stat };
+      }
+    }
+  } catch (error) {
+    if (error.code === 'ENOENT') return { reason: 'target-missing' };
+    return { reason: 'target-unreadable' };
+  }
+}
+
+function readSource(path, expected) {
+  const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try { return readDescriptor(fd, expected); }
+  finally { closeSync(fd); }
+}
+
+function readDescriptor(fd, expected) {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.nlink !== 1 || stat.dev !== expected.dev || stat.ino !== expected.ino || stat.size !== expected.size || stat.mtimeMs !== expected.mtimeMs) return { reason: 'target-changed' };
+    const buffer = Buffer.alloc(MAX_BYTES + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const count = readSync(fd, buffer, length, buffer.length - length, length);
+      if (!count) break;
+      length += count;
+    }
+    const bytes = buffer.subarray(0, length);
+    const after = fstatSync(fd);
+    if (bytes.length > MAX_BYTES || bytes.length !== stat.size || after.size !== stat.size || after.mtimeMs !== stat.mtimeMs) return { reason: 'target-changed' };
+    let source;
+    try { source = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes); }
+    catch { return { reason: 'invalid-encoding' }; }
+    if (source.includes('\0')) return { reason: 'invalid-encoding' };
+    const bare = source.replaceAll('\r\n', '');
+    if (bare.includes('\r') || (source.includes('\r\n') && bare.includes('\n'))) return { reason: 'mixed-newlines' };
+    return { source, sourceHash: sha256(bytes), newline: source.includes('\r\n') ? '\r\n' : '\n', identity: { dev: stat.dev, ino: stat.ino, mode: stat.mode } };
+}
+
+/** Only leading line-comment headers are witnesses, never quoted code text. */
+function hasAnnotation(source, id, python) {
+  for (const line of source.split(/\r?\n/)) {
+    const text = line.replace(/^\uFEFF/, '').trimStart();
+    if (!text || text.startsWith('#!')) continue;
+    if (!text.startsWith(python ? '#' : '//')) break;
+    if ([...text.matchAll(/@claim\s+([^\s]+)/g)].some((match) => match[1] === id)) return true;
+  }
+  return false;
+}
+
+function header(source, ids, python, newline) {
+  let offset = source.startsWith('\uFEFF') ? 1 : 0;
+  const lines = source.slice(offset).split(newline);
+  let protectedLines = lines[0].startsWith('#!') ? 1 : 0;
+  if (python) {
+    for (let i = 0; i < Math.min(2, lines.length); i++) {
+      if (/^\s*#.*coding\s*[:=]\s*[-\w.]+/.test(lines[i])) protectedLines = i + 1;
+    }
+  }
+  for (let i = 0; i < protectedLines; i++) offset += lines[i].length + (i < lines.length - 1 ? newline.length : 0);
+  const prefix = source.slice(0, offset);
+  const separator = protectedLines && !prefix.endsWith(newline) ? newline : '';
+  return prefix + separator + ids.map((id) => `${python ? '#' : '//'} @claim ${id}${newline}`).join('') + source.slice(offset);
+}
+
+/** Internal read-only plan. Not an evidence document or a successful apply. */
+export function planAnnotationPlacement({ projectDir, claims, claimIds = [] }) {
+  if (!validate('claims', claims).ok) throw new Error('claims must conform before annotation placement');
+  if (!Array.isArray(claimIds) || claimIds.some((id) => typeof id !== 'string')) throw new Error('claim selection must be an array of IDs');
+  const selected = new Set(claimIds);
+  for (const id of selected) if (!claims.claims.some((c) => c.id === id)) throw new Error(`unknown claim ${id}`);
+  const root = canonicalRoot(projectDir);
+  const targets = new Map();
+  const selectedClaims = claims.claims.filter((c) => !selected.size || selected.has(c.id));
+  for (const claim of selectedClaims) {
+    for (const fault of claim.faults) {
+      const file = fault.file ?? `(claim ${claim.id} without a target)`;
+      if (!targets.has(file)) targets.set(file, []);
+      targets.get(file).push({ claim, fault });
+    }
+  }
+  const files = [], refused = [];
+  let admittedBytes = 0;
+  for (const [file, entries] of [...targets].sort(([a], [b]) => a.localeCompare(b))) {
+    const ids = [...new Set(entries.map(({ claim }) => claim.id))].sort();
+    const refuse = (reason) => refused.push({ file, claimIds: ids, reason });
+    if (ids.some((id) => !CLAIM_ID.test(id))) { refuse('unsupported-claim-id'); continue; }
+    if (entries.some(({ fault }) => (fault.method ?? 'fault-injection') !== 'fault-injection')) { refuse('unsupported-method'); continue; }
+    const target = admittedPath(root, file);
+    if (target.reason) { refuse(target.reason); continue; }
+    if (admittedBytes + target.stat.size > MAX_PLAN_BYTES) { refuse('plan-source-budget'); continue; }
+    admittedBytes += target.stat.size;
+    let input;
+    try { input = readSource(target.path, target.stat); }
+    catch { refuse('target-unreadable'); continue; }
+    if (input.reason) { refuse(input.reason); continue; }
+    const invalid = entries.map(({ fault }) => locate(input.source, fault)).find((anchor) => anchor.status !== 'ok');
+    if (invalid) { refuse(invalid.status); continue; }
+    const python = extname(file) === '.py';
+    const missing = ids.filter((id) => !hasAnnotation(input.source, id, python));
+    const proposed = missing.length ? header(input.source, missing, python, input.newline) : input.source;
+    const proposedBytes = Buffer.byteLength(proposed, 'utf8');
+    if (proposedBytes > MAX_BYTES) { refuse('proposed-source-too-large'); continue; }
+    const growth = Math.max(0, proposedBytes - target.stat.size);
+    if (admittedBytes + growth > MAX_PLAN_BYTES) { refuse('plan-source-budget'); continue; }
+    admittedBytes += growth;
+    files.push({ file, claimIds: ids, sourceHash: input.sourceHash, identity: input.identity, source: input.source, proposed, changed: proposed !== input.source });
+  }
+  return { projectDir: root, selectedClaimIds: selectedClaims.map((c) => c.id).sort(), claimsHash: sha256(JSON.stringify(claims)), files, refused, applicable: refused.length === 0 };
+}
+
+/** Recompute before authoring. Never trust a saved proposal or hash alone. */
+export function revalidateAnnotationPlan({ projectDir, claims, plan }) {
+  if (!plan || plan.projectDir !== canonicalRoot(projectDir) || !Array.isArray(plan.selectedClaimIds)) return { current: false, reason: 'plan-invalid' };
+  if (!validate('claims', claims).ok || plan.claimsHash !== sha256(JSON.stringify(claims))) return { current: false, reason: 'claims-changed' };
+  let fresh;
+  try { fresh = planAnnotationPlacement({ projectDir, claims, claimIds: plan.selectedClaimIds }); }
+  catch { return { current: false, reason: 'plan-invalid' }; }
+  if (!fresh.applicable) return { current: false, reason: 'plan-refused' };
+  if (!isDeepStrictEqual(plan, fresh)) return { current: false, reason: 'plan-changed' };
+  return { current: true, plan: fresh };
+}
+
+/** Bounded preview input; an external claims file never authorizes an apply. */
+export function loadAnnotationClaims(claimsPath) {
+  const selectedRoot = dirname(resolve(claimsPath));
+  const root = canonicalRoot(selectedRoot);
+  return currentClaims(root, selectedClaimsPath(root, selectedRoot, claimsPath));
+}
+
+function currentClaims(root, claimsPath) {
+  const file = relative(root, resolve(claimsPath)).split(sep).join('/');
+  const target = admittedPath(root, file, { source: false });
+  if (target.reason) throw new Error(`claims path refused: ${target.reason}`);
+  const input = readSource(target.path, target.stat);
+  if (input.reason) throw new Error(`claims read refused: ${input.reason}`);
+  try { return JSON.parse(input.source); }
+  catch { throw new Error('claims file contains invalid JSON'); }
+}
+
+/** Exclusive creation and byte ownership: never reclaim a possibly live lock. */
+export function authoringLock(root) {
+  const path = join(root, '.testguard-annotations.lock');
+  let fd;
+  try { fd = openSync(path, constants.O_RDWR | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600); }
+  catch (error) { if (error.code === 'EEXIST') throw new Error('annotation authoring lock already exists'); throw error; }
+  const identity = fstatSync(fd);
+  const content = Buffer.from(JSON.stringify({ pid: process.pid, token: randomUUID() }));
+  let result;
+  const assertOwned = () => {
+    if (result) throw new Error('annotation authoring lock released');
+    const current = lstatSync(path);
+    const bytes = Buffer.alloc(content.length + 1);
+    const count = readSync(fd, bytes, 0, bytes.length, 0);
+    if (current.isSymbolicLink() || current.nlink !== 1 || current.dev !== identity.dev || current.ino !== identity.ino || count !== content.length || !bytes.subarray(0, count).equals(content)) throw new Error('annotation authoring lock changed');
+  };
+  const release = () => {
+    if (result) return result;
+    try {
+      const current = lstatSync(path);
+      const bytes = Buffer.alloc(content.length + 1);
+      const count = readSync(fd, bytes, 0, bytes.length, 0);
+      if (current.isSymbolicLink() || current.nlink !== 1 || current.dev !== identity.dev || current.ino !== identity.ino || count !== content.length || !bytes.subarray(0, count).equals(content)) {
+        result = { released: false, reason: 'lock-changed' };
+      } else { unlinkSync(path); result = { released: true }; }
+    } catch (error) { result = { released: false, reason: error.code === 'ENOENT' ? 'lock-changed' : 'lock-release-failed' }; }
+    finally { closeSync(fd); }
+    return result;
+  };
+  try { writeFileSync(fd, content); }
+  catch (error) {
+    // No other actor may use this exclusively-created file yet. Still verify
+    // inode ownership rather than unlinking an arbitrary replacement.
+    try {
+      const current = lstatSync(path);
+      if (!current.isSymbolicLink() && current.dev === identity.dev && current.ino === identity.ino) unlinkSync(path);
+    } finally { closeSync(fd); }
+    throw error;
+  }
+  return { release, assertOwned };
+}
+
+export function persistRecovery(path, bytes) {
+  const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
+  try { writeFileSync(fd, bytes); fsyncSync(fd); }
+  finally { closeSync(fd); }
+}
+
+/** Only fresh internal plan containers enter this boundary, never caller objects. */
+function freezePrepared(value) {
+  if (value && typeof value === 'object') {
+    for (const child of Object.values(value)) freezePrepared(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+/** Prepare recoverable authoring. This function never rewrites source files. */
+export function prepareAnnotationApply({ projectDir, claimsPath, plan }) {
+  const root = canonicalRoot(projectDir);
+  const claimsFile = selectedClaimsPath(root, projectDir, claimsPath);
+  // Establish safe claims/root admission before creating even a lock.
+  currentClaims(root, claimsFile);
+  const lock = authoringLock(root);
+  let recoveryDir;
+  try {
+    const claims = currentClaims(root, claimsFile);
+    const checked = revalidateAnnotationPlan({ projectDir: root, claims, plan });
+    if (!checked.current) throw new Error(`annotation preview refused: ${checked.reason}`);
+    if (checked.plan.files.some((file) => resolve(root, file.file) === claimsFile)) throw new Error('claims file cannot be an annotation target');
+    recoveryDir = mkdtempSync(join(recoveryBase(root), 'testguard-annotation-recovery-'));
+    chmodSync(recoveryDir, 0o700);
+    const files = checked.plan.files.filter((file) => file.changed).map((file, index) => {
+      const original = `${index}.original`;
+      persistRecovery(join(recoveryDir, original), Buffer.from(file.source, 'utf8'));
+      return { file: file.file, original, sourceHash: file.sourceHash, proposedHash: sha256(Buffer.from(file.proposed, 'utf8')), identity: file.identity };
+    });
+    const manifest = { state: 'prepared', projectDir: root, claimsPath: claimsFile, claimsHash: checked.plan.claimsHash, files };
+    persistRecovery(join(recoveryDir, 'manifest.json'), Buffer.from(JSON.stringify(manifest)));
+    return freezePrepared({ ready: true, plan: checked.plan, claimsPath: claimsFile, recoveryDir, release: lock.release, assertOwned: lock.assertOwned });
+  } catch (error) {
+    if (recoveryDir) error.recoveryDir = recoveryDir;
+    error.lockRelease = lock.release();
+    throw error;
+  }
+}
+
+/** Explicit internal authoring: recoverable descriptor writes, never automatic rollback. */
+export function applyAnnotationPlacement({ projectDir, claimsPath, plan }) {
+  const handle = prepareAnnotationApply({ projectDir, claimsPath, plan });
+  const root = handle.plan.projectDir;
+  const files = handle.plan.files.filter((file) => file.changed);
+  const report = { state: 'applied', changed: [], touched: [], unchanged: handle.plan.files.filter((file) => !file.changed).map((file) => file.file), failed: [], recoveryDir: handle.recoveryDir };
+  let activeFile = null, stage = 'all-target-preflight';
+  const checkClaims = () => {
+    handle.assertOwned();
+    const claims = currentClaims(root, handle.claimsPath);
+    if (!validate('claims', claims).ok || sha256(JSON.stringify(claims)) !== handle.plan.claimsHash) throw new Error('claims changed before source write');
+    return claims;
+  };
+  try {
+    const checked = revalidateAnnotationPlan({ projectDir: root, claims: checkClaims(), plan: handle.plan });
+    if (!checked.current) throw new Error(`annotation write preflight refused: ${checked.reason}`);
+    if (files.length) {
+      stage = 'started-journal';
+      persistRecovery(join(handle.recoveryDir, 'started.json'), Buffer.from(JSON.stringify({ files: files.map((file) => file.file) })));
+    }
+    for (const [index, file] of files.entries()) {
+      activeFile = file.file; stage = 'target-preflight';
+      checkClaims();
+      const target = admittedPath(root, file.file);
+      if (target.reason) throw new Error(`target refused: ${target.reason}`);
+      const fd = openSync(target.path, constants.O_RDWR | (constants.O_NOFOLLOW ?? 0));
+      try {
+        const input = readDescriptor(fd, target.stat);
+        if (input.reason || input.sourceHash !== file.sourceHash || !isDeepStrictEqual(input.identity, file.identity)) throw new Error('target changed before source write');
+        const current = admittedPath(root, file.file);
+        if (current.reason || current.stat.dev !== file.identity.dev || current.stat.ino !== file.identity.ino || current.stat.mode !== file.identity.mode) throw new Error('target path changed before source write');
+        handle.assertOwned();
+        const bytes = Buffer.from(file.proposed, 'utf8');
+        stage = 'source-write'; report.touched.push(file.file);
+        let offset = 0;
+        while (offset < bytes.length) {
+          const count = writeSync(fd, bytes, offset, bytes.length - offset, offset);
+          if (!Number.isInteger(count) || count <= 0 || count > bytes.length - offset) throw new Error('source write made no valid progress');
+          offset += count;
+        }
+        ftruncateSync(fd, bytes.length);
+        fsyncSync(fd);
+        stage = 'write-verification';
+        const output = readDescriptor(fd, fstatSync(fd));
+        const after = admittedPath(root, file.file);
+        if (output.reason || output.sourceHash !== sha256(bytes) || !isDeepStrictEqual(output.identity, file.identity) || after.reason || after.stat.dev !== file.identity.dev || after.stat.ino !== file.identity.ino) throw new Error('source write verification failed');
+        report.changed.push(file.file);
+      } finally { closeSync(fd); }
+      stage = 'completion-journal';
+      persistRecovery(join(handle.recoveryDir, `${index}.applied.json`), Buffer.from(JSON.stringify({ file: file.file, proposedHash: sha256(Buffer.from(file.proposed, 'utf8')) })));
+    }
+  } catch (error) {
+    report.state = report.touched.length ? 'partial' : 'refused';
+    report.failed.push({ file: activeFile, stage, reason: error.message });
+  } finally {
+    report.lockRelease = handle.release();
+    if (!report.lockRelease.released && !report.failed.length) {
+      report.state = report.touched.length ? 'partial' : 'refused';
+      report.failed.push({ file: null, stage: 'lock-release', reason: report.lockRelease.reason });
+    }
+  }
+  try {
+    persistRecovery(join(handle.recoveryDir, 'result.pending.json'), Buffer.from(JSON.stringify(report)));
+    renameSync(join(handle.recoveryDir, 'result.pending.json'), join(handle.recoveryDir, 'result.json'));
+  }
+  catch (error) {
+    report.state = report.touched.length ? 'partial' : 'refused';
+    report.failed.push({ file: null, stage: 'result-journal', reason: error.message });
+  }
+  return freezePrepared(report);
+}

package/src/claims/annotations.mjs

@@ -1,4 +1,4 @@
-import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { readFileSync, readdirSync, existsSync, opendirSync, openSync, fstatSync, readSync, closeSync, constants } from 'node:fs';
 import { join, extname } from 'node:path';
 
 const SCAN_EXT = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx', '.py', '.go', '.rs', '.java', '.kt', '.md']);
@@ -6,7 +6,7 @@ const SKIP_DIRS = new Set(['node_modules', 'dist', 'coverage']);
 const TEST_FILE = /\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)(tests?|__tests__)\//;
 // An annotation id must contain a hyphen (REDACT-001, TG-KILL-NEEDS-N). Prose
 // such as "@claim annotations" is not an annotation.
-const RE = /@claim\s+([A-Za-z0-9]+(?:[._]?[A-Za-z0-9]+)*-[A-Za-z0-9._-]*[A-Za-z0-9])\b/g;
+const RE = /@claim\s+([A-Za-z0-9]+(?:[._][A-Za-z0-9]+)*-[A-Za-z0-9._-]*[A-Za-z0-9])\b/g;
 
 /**
  * Source files worth scanning: skips hidden directories (tooling), dependency
@@ -57,3 +57,62 @@ export function reconcile(claims, annotations) {
     annotated: [...declared.keys()].filter((id) => annotated.has(id)),
   };
 }
+
+/** Lexical links aid discovery, never verification or provenance authentication. */
+export function annotationAdvisory(claims, annotations, { customClaims = false } = {}) {
+  const linked = new Set(annotations.map((a) => a.id));
+  const missingIds = [...new Set(claims.claims.map((c) => c.id))].filter((id) => !linked.has(id)).sort();
+  return {
+    missingIds,
+    notes: missingIds.length ? [
+      `ANNOTATION ADVISORY: ${missingIds.length} declared claim ID${missingIds.length === 1 ? '' : 's'} lack a scanned source link. Discoverability and annotation reconciliation are reduced; exact fault anchors remain checked.`,
+      ...missingIds.map((id) => `Missing source annotation: ${id}`),
+      'Optional read-only preview in the selected project: testguard claims --annotate. Placement is not verification or authenticated intent; review before explicitly applying.',
+      ...(customClaims ? ['Preserve the original --claims argument when running that preview; the default claims file is not this selection.'] : []),
+    ] : [],
+  };
+}
+
+/** Advice cannot turn unrelated file failures or excessive reads into status failure. */
+export function projectAnnotationAdvisory(projectDir, claims, options) {
+  const annotations = [];
+  let entries = 0; let files = 0; let bytes = 0;
+  const visit = (dir, rel, depth) => {
+    if (depth > 64) throw new Error('scan incomplete');
+    const directory = opendirSync(dir);
+    try {
+      let e;
+      while ((e = directory.readSync())) {
+        if (++entries > 10000) throw new Error('scan incomplete');
+        const file = rel ? `${rel}/${e.name}` : e.name;
+        if (e.isDirectory()) {
+          if (e.name.startsWith('.') || SKIP_DIRS.has(e.name) || existsSync(join(dir, e.name, 'testguard.claims.json'))) continue;
+          visit(join(dir, e.name), file, depth + 1);
+        } else if (e.isFile() && SCAN_EXT.has(extname(e.name)) && !TEST_FILE.test(file)) {
+          if (++files > 1000) throw new Error('scan incomplete');
+          const fd = openSync(join(dir, e.name), constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+          try {
+            const stat = fstatSync(fd);
+            const limit = Math.min(256 * 1024, 2 * 1024 * 1024 - bytes);
+            if (!stat.isFile() || stat.nlink !== 1 || stat.size > limit) throw new Error('scan incomplete');
+            const buffer = Buffer.alloc(limit + 1);
+            let read = 0; let n;
+            while ((n = readSync(fd, buffer, read, buffer.length - read, null))) {
+              read += n;
+              if (read > limit) throw new Error('scan incomplete');
+            }
+            bytes += read;
+            const text = new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, read));
+            text.split('\n').forEach((line, i) => {
+              for (const m of line.matchAll(RE)) annotations.push({ id: m[1], file, line: i + 1 });
+            });
+          } finally { closeSync(fd); }
+        }
+      }
+    } finally { directory.closeSync(); }
+  };
+  try { visit(projectDir, '', 0); return annotationAdvisory(claims, annotations, options); }
+  catch {
+    return { missingIds: [], notes: ['ANNOTATION ADVISORY unavailable: source scan was incomplete or exceeded its resource limits. No missing-ID conclusion was made; verification state and next action are unchanged.'] };
+  }
+}

package/src/cli.mjs

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

package/src/commands/admit.mjs

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