harness-everything 0.13.0 → 0.15.0

package/contract-integrity/scripts/audit.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 'use strict';
 
+const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
+const { spawnSync } = require('child_process');
 const { evaluateEvidence } = require('../../tdd/scripts/quality-gate');
 
 const VERSION = '1.0.0';
@@ -57,6 +59,181 @@ function stable(value) {
   return Object.fromEntries(Object.keys(value).sort().map(key => [key, stable(value[key])]));
 }
 
+function sha256File(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+function realpath(file) {
+  return fs.realpathSync.native ? fs.realpathSync.native(file) : fs.realpathSync(file);
+}
+
+function containedPath(root, target) {
+  const relative = path.relative(root, target);
+  return relative === '' ||
+    (relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative));
+}
+
+function gitRevision(workspace) {
+  if (!workspace) return null;
+  const result = spawnSync('git', ['rev-parse', 'HEAD'], {
+    cwd: workspace,
+    encoding: 'utf8',
+    windowsHide: true,
+  });
+  return result.status === 0 ? String(result.stdout || '').trim() || null : null;
+}
+
+function artifactFingerprints(trace, workspace) {
+  if (!workspace) return [];
+  const root = path.resolve(workspace);
+  let realRoot;
+  try {
+    if (fs.lstatSync(root).isSymbolicLink()) throw new Error('linked-root');
+    realRoot = realpath(root);
+  } catch (_) {
+    return (trace?.artifacts || []).map(artifact => ({
+      id: artifact.id, path: artifact.path, sha256: null, missing: true, reason: 'workspace-unavailable',
+    }));
+  }
+  return (trace?.artifacts || []).map(artifact => {
+    const full = path.resolve(root, artifact.path);
+    if (!containedPath(root, full)) {
+      return { id: artifact.id, path: artifact.path, sha256: null, missing: true, reason: 'escaped-path' };
+    }
+    let current = root;
+    for (const segment of path.relative(root, full).split(path.sep).filter(Boolean)) {
+      current = path.join(current, segment);
+      if (!fs.existsSync(current)) {
+        return { id: artifact.id, path: artifact.path, sha256: null, missing: true, reason: 'missing' };
+      }
+      if (fs.lstatSync(current).isSymbolicLink()) {
+        return { id: artifact.id, path: artifact.path, sha256: null, missing: true, reason: 'linked-path' };
+      }
+    }
+    let physical;
+    try { physical = realpath(full); }
+    catch (_) {
+      return { id: artifact.id, path: artifact.path, sha256: null, missing: true, reason: 'missing' };
+    }
+    if (!containedPath(realRoot, physical) || !fs.lstatSync(physical).isFile()) {
+      return { id: artifact.id, path: artifact.path, sha256: null, missing: true, reason: 'escaped-path' };
+    }
+    return { id: artifact.id, path: artifact.path, sha256: sha256File(physical), missing: false };
+  });
+}
+
+function buildProvenance(args, trace) {
+  const workspace = args.workspace ? path.resolve(args.workspace) : null;
+  return {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    auditVersion: VERSION,
+    nodeVersion: process.version,
+    command: 'node contract-integrity/scripts/audit.js <trace> [--tdd-evidence <evidence>] [--workspace <workspace>]',
+    gitRevision: gitRevision(workspace || process.cwd()),
+    workspaceIsolation: unique((trace?.probes || []).map(probe => probe.workspaceIsolation).filter(Boolean)),
+    workspace: workspace ? { root: workspace } : null,
+    inputs: {
+      trace: { sha256: sha256File(path.resolve(args.input)) },
+      tddEvidence: args.tddEvidence ? { sha256: sha256File(path.resolve(args.tddEvidence)) } : null,
+    },
+    artifacts: artifactFingerprints(trace, workspace),
+  };
+}
+
+function verifyFreshReport(report, args, trace, currentAudit = null) {
+  const reasons = [];
+  if (!isObject(report?.provenance) || !isObject(report.provenance.inputs)) {
+    return { fresh: false, authorizesCompletion: false, reasons: ['report-provenance-missing'] };
+  }
+  const currentTraceHash = sha256File(path.resolve(args.input));
+  if (report.provenance.inputs.trace?.sha256 !== currentTraceHash) reasons.push('trace-changed-since-audit');
+  const currentTddHash = args.tddEvidence ? sha256File(path.resolve(args.tddEvidence)) : null;
+  const reportedTddHash = report.provenance.inputs.tddEvidence?.sha256 || null;
+  if (currentTddHash !== reportedTddHash) reasons.push('tdd-evidence-changed-since-audit');
+  if (!currentAudit || currentAudit.result !== 'PASS' || currentAudit.completionGate !== 'PASS' || currentAudit.errors?.length) {
+    reasons.push('current-audit-not-pass');
+  }
+
+  const tracedArtifacts = Array.isArray(trace?.artifacts) ? trace.artifacts : [];
+  if (tracedArtifacts.length > 0) {
+    if (!args.workspace) {
+      reasons.push('workspace-required-for-artifact-freshness');
+    } else {
+      const reportedRoot = report.provenance.workspace?.root;
+      if (!reportedRoot) {
+        reasons.push('report-workspace-unbound');
+      } else if (path.resolve(reportedRoot) !== path.resolve(args.workspace)) {
+        reasons.push('workspace-changed-since-audit');
+      }
+
+      const priorArtifacts = Array.isArray(report.provenance.artifacts) ? report.provenance.artifacts : [];
+      const prior = new Map();
+      for (const item of priorArtifacts) {
+        if (item?.id && !prior.has(item.id)) prior.set(item.id, item);
+        else if (item?.id) reasons.push(`artifact-fingerprint-duplicate:${item.id}`);
+      }
+      const current = new Map(artifactFingerprints(trace, args.workspace).map(item => [item.id, item]));
+      for (const artifact of tracedArtifacts) {
+        const before = prior.get(artifact.id);
+        const now = current.get(artifact.id);
+        if (!before || before.path !== artifact.path || before.missing || !before.sha256) {
+          reasons.push(`artifact-fingerprint-missing:${artifact.id}`);
+          continue;
+        }
+        if (!now || now.missing || now.sha256 !== before.sha256) {
+          reasons.push(`artifact-changed-since-audit:${artifact.id}`);
+        }
+      }
+      if (priorArtifacts.length !== tracedArtifacts.length) {
+        reasons.push('artifact-fingerprint-set-incomplete');
+      }
+    }
+  }
+  return {
+    fresh: reasons.length === 0,
+    authorizesCompletion: reasons.length === 0 && report.completionGate === 'PASS' && report.result === 'PASS',
+    reasons: unique(reasons),
+  };
+}
+
+function repairGuidance(requirements) {
+  const priorityOrder = { BLOCKER: 0, HIGH: 1, MEDIUM: 2 };
+  const recommendations = [];
+  const add = (priority, req, code, action) => recommendations.push({
+    priority,
+    requirementId: req.requirementId,
+    sourceRef: req.sourceRef || null,
+    code,
+    action,
+  });
+
+  for (const req of requirements) {
+    if (req.lifecycleStatus !== 'CURRENT') continue;
+    if (req.drift.includes('SOURCE_CONFLICT')) add('BLOCKER', req, 'resolve-source-conflict', 'Resolve the authoritative source conflict before changing tests or implementation.');
+    if (req.drift.includes('SOURCE_DEFECT')) add('BLOCKER', req, 'repair-source-defect', 'Repair or explicitly supersede the defective authoritative source before completion.');
+    if (req.protection.status === 'SURVIVED') add('BLOCKER', req, 'strengthen-weak-oracle', 'Strengthen the requirement-linked observable assertion so every required contract probe is killed for the expected reason.');
+    if (req.drift.includes('STALE_SPEC')) add('HIGH', req, 'update-living-spec', 'Update the living specification and requirement revision before accepting behavior that moved ahead of the contract.');
+    if (req.drift.includes('STALE_TEST')) add('HIGH', req, 'refresh-requirement-tests', 'Update requirement-linked tests and RED evidence against the current living specification.');
+    if (req.drift.includes('STALE_IMPLEMENTATION')) add('HIGH', req, 'refresh-implementation-evidence', 'Attach implementation evidence for the current requirement revision and rerun verification.');
+    if (req.drift.includes('UNTRACED_CHANGE')) add('HIGH', req, 'repair-contract-lineage', 'Restore ADR/spec/ticket/test/implementation lineage for this requirement before completion.');
+    if (req.protection.status === 'NOT_EVALUATED') add('HIGH', req, 'execute-required-probes', 'Execute every predeclared required contract probe in an isolated supported adapter or retain NOT_EVALUATED.');
+    if (req.completeness.result !== 'PASS' || req.completeness.score < 100) add('HIGH', req, 'complete-tdd-evidence', 'Repair the existing #58 completeness evidence; do not compensate with protection score.');
+  }
+
+  const seen = new Set();
+  return recommendations
+    .filter(item => {
+      const key = `${item.requirementId}:${item.code}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    })
+    .sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority] ||
+      String(a.requirementId).localeCompare(String(b.requirementId)) ||
+      a.code.localeCompare(b.code));
+}
+
 function validateTrace(input) {
   const errors = [];
   if (!isObject(input)) return ['trace root must be an object'];
@@ -385,6 +562,7 @@ function evaluateTrace(trace, options = {}) {
       requirementId: requirement.requirementId,
       revision: requirement.revision,
       lifecycleStatus: requirement.status,
+      sourceRef: currentSpec ? `${currentSpec.path}#${requirement.requirementId}` : null,
       drift: unique(statuses),
       reasonCodes: lineage.reasons,
       completeness: quality,
@@ -429,6 +607,7 @@ function evaluateTrace(trace, options = {}) {
     },
     driftCounts,
     requirements: reportRequirements,
+    repairGuidance: repairGuidance(reportRequirements),
     graph: {
       nodes: [
         ...(trace?.artifacts || []).map(artifact => ({ id: artifact.id, kind: artifact.kind, status: artifact.status, path: artifact.path })),
@@ -458,9 +637,22 @@ function markdown(report) {
   for (const req of report.requirements) {
     lines.push(`| ${req.requirementId} | ${req.revision} | ${req.drift.join(', ')} | ${req.completeness.score} | ${req.protection.status} | ${req.gateEligible ? 'PASS' : 'FAIL'} |`);
   }
+  if (report.repairGuidance?.length) {
+    lines.push('', '## Repair Guidance', '');
+    for (const item of report.repairGuidance) {
+      lines.push(`- **${item.priority}** ${item.requirementId}${item.sourceRef ? ` (${item.sourceRef})` : ''}: ${item.action} [${item.code}]`);
+    }
+  }
   if (report.errors.length) {
     lines.push('', '## Errors', '', ...report.errors.map(error => `- ${error}`));
   }
+  if (report.provenance) {
+    lines.push('', '## Provenance', '');
+    lines.push(`- Audit version: ${report.provenance.auditVersion}`);
+    lines.push(`- Git revision: ${report.provenance.gitRevision || 'unknown'}`);
+    lines.push(`- Trace SHA-256: ${report.provenance.inputs?.trace?.sha256 || 'unknown'}`);
+    lines.push(`- TDD evidence SHA-256: ${report.provenance.inputs?.tddEvidence?.sha256 || 'none'}`);
+  }
   lines.push('', '## Evidence boundary', '');
   lines.push('- Completeness is derived by the existing #58 evaluator; aggregate scores supplied by agents are ignored.');
   lines.push('- Protection counts only predeclared required probes. Extra/padded probes do not raise a requirement score.');
@@ -470,13 +662,15 @@ function markdown(report) {
 }
 
 function parseArgs(argv) {
-  const args = { input: null, tddEvidence: null, output: null, markdown: null };
+  const args = { input: null, tddEvidence: null, output: null, markdown: null, workspace: null, verifyFresh: null };
   for (let i = 0; i < argv.length; i++) {
     const token = argv[i];
     if (!args.input && !token.startsWith('--')) args.input = token;
     else if (token === '--tdd-evidence') args.tddEvidence = argv[++i];
     else if (token === '--output') args.output = argv[++i];
     else if (token === '--markdown') args.markdown = argv[++i];
+    else if (token === '--workspace') args.workspace = argv[++i];
+    else if (token === '--verify-fresh') args.verifyFresh = argv[++i];
     else throw new Error(`unknown argument: ${token}`);
   }
   return args;
@@ -487,7 +681,7 @@ function runCli(argv) {
   try { args = parseArgs(argv.slice(2)); }
   catch (error) { console.error(`Contract Integrity: FAIL\n- ${error.message}`); return 2; }
   if (!args.input) {
-    console.error('Usage: node contract-integrity/scripts/audit.js <trace.json> [--tdd-evidence <#58-evidence.json>] [--output report.json] [--markdown report.md]');
+    console.error('Usage: node contract-integrity/scripts/audit.js <trace.json> [--tdd-evidence <#58-evidence.json>] [--workspace <root>] [--output report.json] [--markdown report.md] [--verify-fresh prior-report.json]');
     return 2;
   }
 
@@ -501,7 +695,33 @@ function runCli(argv) {
     return 2;
   }
 
+  if (args.verifyFresh) {
+    let prior;
+    try { prior = readJson(args.verifyFresh); }
+    catch (error) {
+      console.error(`Contract Integrity Freshness: FAIL\n- ${error.message}`);
+      return 2;
+    }
+    const currentAudit = evaluateTrace(trace, { tddEvidence });
+    const freshness = verifyFreshReport(prior, args, trace, currentAudit);
+    console.log(`Contract Integrity Freshness: ${freshness.authorizesCompletion ? 'PASS' : 'FAIL'}`);
+    for (const reason of freshness.reasons) console.error(`- ${reason}`);
+    return freshness.authorizesCompletion ? 0 : 1;
+  }
+
   const report = evaluateTrace(trace, { tddEvidence });
+  report.provenance = buildProvenance(args, trace);
+  if (args.workspace) {
+    const missing = report.provenance.artifacts.filter(item => item.missing);
+    if (trace.mode === 'strict' && missing.length) {
+      report.result = 'FAIL';
+      report.completionGate = 'FAIL';
+      report.gateEligible = false;
+      report.errors.push(...missing.map(item => item.reason === 'linked-path'
+        ? `provenance artifact linked-path: ${item.id} -> ${item.path}`
+        : `provenance artifact missing from workspace: ${item.id} -> ${item.path}`));
+    }
+  }
   console.log(`Contract Integrity: ${report.result}`);
   console.log(`Scores: completeness=${report.scores.completenessScore} protection=${report.scores.protectionScore} integrity=${report.scores.contractIntegrityScore}`);
   console.log(`Gate: ${report.completionGate}`);
@@ -527,10 +747,13 @@ if (require.main === module) process.exit(runCli(process.argv));
 module.exports = {
   DRIFT,
   VERSION,
+  buildProvenance,
   classifyLineage,
   evaluateTrace,
   markdown,
+  repairGuidance,
   protectionForRequirement,
   runCli,
   validateTrace,
+  verifyFreshReport,
 };

package/contract-integrity/scripts/node-probe-adapter.js

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const VERSION = '1.0.0';
+const ADAPTER = 'node-npm-v1';
+const STRATEGIES = new Set(['env', 'replace']);
+const DEFAULT_TIMEOUT_MS = 30000;
+const MAX_TIMEOUT_MS = 120000;
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function safeRelative(value) {
+  if (typeof value !== 'string' || !value.trim() || path.isAbsolute(value)) return false;
+  const normalized = value.replace(/\\/g, '/');
+  return normalized !== '..' && !normalized.startsWith('../') && !normalized.includes('/../') && !normalized.includes('\0');
+}
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(String(value || ''), 'utf8').digest('hex');
+}
+
+function validatePlan(plan) {
+  const errors = [];
+  if (!isObject(plan)) return ['probe plan must be an object'];
+  if (plan.schemaVersion !== VERSION) errors.push(`schemaVersion must be ${VERSION}`);
+  if (plan.adapter !== ADAPTER) errors.push(`adapter must be ${ADAPTER}`);
+  if (typeof plan.script !== 'string' || !/^[A-Za-z0-9:_-]+$/.test(plan.script)) errors.push('script must be an npm script name');
+  if (!Array.isArray(plan.probes) || plan.probes.length === 0) errors.push('probes must be a non-empty array');
+  const ids = new Set();
+  for (const [index, probe] of (Array.isArray(plan.probes) ? plan.probes : []).entries()) {
+    const p = `probes[${index}]`;
+    if (!isObject(probe)) { errors.push(`${p} must be an object`); continue; }
+    for (const field of ['probeId', 'requirementId', 'sourceSection', 'strategy', 'expectedFailureContains']) {
+      if (typeof probe[field] !== 'string' || !probe[field].trim()) errors.push(`${p}.${field} is required`);
+    }
+    if (probe.probeId && ids.has(probe.probeId)) errors.push(`${p}.probeId is duplicated: ${probe.probeId}`);
+    if (probe.probeId) ids.add(probe.probeId);
+    if (!STRATEGIES.has(probe.strategy)) errors.push(`${p}.strategy must be env or replace`);
+    if (probe.strategy === 'env') {
+      if (!isObject(probe.env) || Object.keys(probe.env).length === 0) errors.push(`${p}.env is required for env strategy`);
+      for (const [key, value] of Object.entries(isObject(probe.env) ? probe.env : {})) {
+        if (!/^[A-Z][A-Z0-9_]{0,79}$/.test(key)) errors.push(`${p}.env contains invalid key: ${key}`);
+        if (typeof value !== 'string' || value.length > 200) errors.push(`${p}.env.${key} must be a string <= 200 chars`);
+      }
+    }
+    if (probe.strategy === 'replace') {
+      if (!safeRelative(probe.target)) errors.push(`${p}.target must be a repo-relative path`);
+      if (typeof probe.find !== 'string' || probe.find.length === 0 || probe.find.length > 4000) errors.push(`${p}.find must be 1..4000 chars`);
+      if (typeof probe.replace !== 'string' || probe.replace.length > 4000) errors.push(`${p}.replace must be <= 4000 chars`);
+    }
+  }
+  if (plan.timeoutMs !== undefined && (!Number.isInteger(plan.timeoutMs) || plan.timeoutMs < 100 || plan.timeoutMs > MAX_TIMEOUT_MS)) {
+    errors.push(`timeoutMs must be an integer between 100 and ${MAX_TIMEOUT_MS}`);
+  }
+  return errors;
+}
+
+function discoverProject(workspace, plan) {
+  const packageFile = path.join(workspace, 'package.json');
+  if (!fs.existsSync(packageFile)) return { ok: false, reason: 'package-json-missing' };
+  let pkg;
+  try { pkg = JSON.parse(fs.readFileSync(packageFile, 'utf8')); }
+  catch (_) { return { ok: false, reason: 'package-json-invalid' }; }
+  if (!isObject(pkg.scripts) || typeof pkg.scripts[plan.script] !== 'string') {
+    return { ok: false, reason: 'npm-script-missing' };
+  }
+  const dependencyCount =
+    Object.keys(isObject(pkg.dependencies) ? pkg.dependencies : {}).length +
+    Object.keys(isObject(pkg.devDependencies) ? pkg.devDependencies : {}).length +
+    Object.keys(isObject(pkg.optionalDependencies) ? pkg.optionalDependencies : {}).length;
+  if (dependencyCount > 0) {
+    return {
+      ok: false,
+      reason: 'external-dependencies-not-supported-v1',
+      detail: 'node-npm-v1 intentionally supports zero-external-dependency projects only; dependency installation is never inferred or networked',
+    };
+  }
+  return {
+    ok: true,
+    packageName: typeof pkg.name === 'string' ? pkg.name : null,
+    script: plan.script,
+    command: `npm run ${plan.script}`,
+    dependencyMode: 'zero-external-dependencies',
+  };
+}
+
+function copyWorkspace(source) {
+  const sourceRoot = path.resolve(source);
+  if (fs.lstatSync(sourceRoot).isSymbolicLink()) {
+    throw new Error('source workspace contains a symbolic link/reparse-point root');
+  }
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-contract-probe-'));
+  const destination = path.join(root, 'workspace');
+  try {
+    fs.cpSync(sourceRoot, destination, {
+      recursive: true,
+      filter: src => {
+        if (fs.lstatSync(src).isSymbolicLink()) {
+          throw new Error('source workspace contains a symbolic link/reparse-point component');
+        }
+        const relative = path.relative(sourceRoot, src).replace(/\\/g, '/');
+        if (!relative) return true;
+        const head = relative.split('/')[0];
+        return !['.git', 'node_modules', '.harness'].includes(head);
+      },
+    });
+  } catch (error) {
+    fs.rmSync(root, { recursive: true, force: true });
+    throw error;
+  }
+  return { root, workspace: destination };
+}
+
+function runScript(workspace, plan, extraEnv = {}) {
+  const timeout = plan.timeoutMs || DEFAULT_TIMEOUT_MS;
+  // On Windows npm is normally a .cmd shim, which child_process cannot
+  // execute directly without a command shell. The script name is restricted
+  // to a safe identifier by validatePlan(), and no user-provided shell text is
+  // interpolated into the command.
+  const result = spawnSync('npm', ['run', plan.script], {
+    cwd: workspace,
+    encoding: 'utf8',
+    timeout,
+    windowsHide: true,
+    shell: process.platform === 'win32',
+    env: { ...process.env, CI: '1', ...extraEnv },
+  });
+  const stdout = String(result.stdout || '');
+  const stderr = String(result.stderr || '');
+  const combined = stdout + '\n' + stderr;
+  if (result.error) {
+    const timedOut = result.error.code === 'ETIMEDOUT';
+    return {
+      kind: timedOut ? 'timeout' : 'spawn-error',
+      exitCode: null,
+      signal: result.signal || null,
+      outputHash: sha256(combined + String(result.error.message || '')),
+      combined,
+    };
+  }
+  return {
+    kind: 'exit',
+    exitCode: Number.isInteger(result.status) ? result.status : null,
+    signal: result.signal || null,
+    outputHash: sha256(combined),
+    combined,
+  };
+}
+
+function isolatedRegularFile(workspace, relativeTarget) {
+  const root = path.resolve(workspace);
+  const target = path.resolve(root, relativeTarget);
+  const lexical = path.relative(root, target);
+  if (lexical === '..' || lexical.startsWith('..' + path.sep) || path.isAbsolute(lexical)) {
+    throw new Error('replace target escaped isolated workspace');
+  }
+
+  let current = root;
+  for (const segment of lexical.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    if (!fs.existsSync(current)) throw new Error('replace target does not exist');
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink()) {
+      throw new Error('replace target contains symbolic link/reparse-point component');
+    }
+  }
+
+  const realRoot = fs.realpathSync(root);
+  const realTarget = fs.realpathSync(target);
+  const resolved = path.relative(realRoot, realTarget);
+  if (resolved === '..' || resolved.startsWith('..' + path.sep) || path.isAbsolute(resolved)) {
+    throw new Error('replace target resolved outside isolated workspace');
+  }
+  if (!fs.lstatSync(realTarget).isFile()) throw new Error('replace target does not exist');
+  return realTarget;
+}
+
+function applyProbe(workspace, probe) {
+  if (probe.strategy === 'env') return { env: { ...probe.env }, mutation: 'environment-only' };
+
+  const target = isolatedRegularFile(workspace, probe.target);
+  const source = fs.readFileSync(target, 'utf8');
+  const first = source.indexOf(probe.find);
+  const last = source.lastIndexOf(probe.find);
+  if (first < 0) throw new Error('replace find text was not present');
+  if (first !== last) throw new Error('replace find text must match exactly once');
+  fs.writeFileSync(target, source.slice(0, first) + probe.replace + source.slice(first + probe.find.length), 'utf8');
+  return { env: {}, mutation: `replace:${probe.target}` };
+}
+
+function evidenceRef(probe, run) {
+  return `probe:${probe.probeId}:output-sha256:${run.outputHash}`;
+}
+
+function notEvaluatedProbe(probe, reason, failureClass = 'infrastructure', workspaceIsolation = 'isolated') {
+  return {
+    probeId: probe.probeId,
+    requirementId: probe.requirementId,
+    status: 'NOT_EVALUATED',
+    sourceSection: probe.sourceSection,
+    evidenceRef: null,
+    workspaceIsolation,
+    failureClass,
+    adapterReason: reason,
+  };
+}
+
+function executePlan(workspace, plan) {
+  const errors = validatePlan(plan);
+  if (errors.length) return { schemaVersion: VERSION, adapter: ADAPTER, result: 'INVALID_PLAN', errors, probes: [] };
+
+  const discovered = discoverProject(workspace, plan);
+  if (!discovered.ok) {
+    return {
+      schemaVersion: VERSION,
+      adapter: ADAPTER,
+      result: 'NOT_EVALUATED',
+      discovery: discovered,
+      baseline: null,
+      probes: plan.probes.map(probe => notEvaluatedProbe(probe, discovered.reason)),
+      errors: [],
+    };
+  }
+
+  let baselineIsolation;
+  try {
+    baselineIsolation = copyWorkspace(workspace);
+    const baselineRun = runScript(baselineIsolation.workspace, plan);
+    const baseline = {
+      status: baselineRun.kind === 'exit' && baselineRun.exitCode === 0 ? 'PASS' : 'FAIL',
+      exitCode: baselineRun.exitCode,
+      failureClass: baselineRun.kind === 'exit' ? (baselineRun.exitCode === 0 ? 'none' : 'baseline-test') : 'infrastructure',
+      evidenceRef: `baseline:output-sha256:${baselineRun.outputHash}`,
+      workspaceIsolation: 'isolated',
+    };
+    if (baseline.status !== 'PASS') {
+      return {
+        schemaVersion: VERSION,
+        adapter: ADAPTER,
+        result: 'NOT_EVALUATED',
+        discovery: discovered,
+        baseline,
+        probes: plan.probes.map(probe => notEvaluatedProbe(probe, 'baseline-not-green')),
+        errors: [],
+      };
+    }
+  } catch (error) {
+    const reason = String(error.message || error);
+    return {
+      schemaVersion: VERSION,
+      adapter: ADAPTER,
+      result: 'NOT_EVALUATED',
+      discovery: discovered,
+      baseline: {
+        status: 'NOT_EVALUATED',
+        evidenceRef: null,
+        workspaceIsolation: 'not-isolated',
+        failureClass: 'infrastructure',
+        adapterReason: reason,
+      },
+      probes: plan.probes.map(probe =>
+        notEvaluatedProbe(probe, reason, 'infrastructure', 'not-isolated')),
+      errors: [],
+    };
+  } finally {
+    if (baselineIsolation?.root) fs.rmSync(baselineIsolation.root, { recursive: true, force: true });
+  }
+
+  const results = [];
+  for (const probe of plan.probes) {
+    let isolated;
+    try {
+      isolated = copyWorkspace(workspace);
+      const applied = applyProbe(isolated.workspace, probe);
+      const run = runScript(isolated.workspace, plan, applied.env);
+      if (run.kind !== 'exit') {
+        results.push(notEvaluatedProbe(probe, run.kind));
+        continue;
+      }
+      if (run.exitCode === 0) {
+        results.push({
+          probeId: probe.probeId,
+          requirementId: probe.requirementId,
+          status: 'SURVIVED',
+          sourceSection: probe.sourceSection,
+          evidenceRef: evidenceRef(probe, run),
+          workspaceIsolation: 'isolated',
+          failureClass: 'none',
+          adapterReason: 'project-test-suite-remained-green',
+        });
+        continue;
+      }
+      if (run.combined.includes(probe.expectedFailureContains)) {
+        results.push({
+          probeId: probe.probeId,
+          requirementId: probe.requirementId,
+          status: 'KILLED',
+          sourceSection: probe.sourceSection,
+          evidenceRef: evidenceRef(probe, run),
+          workspaceIsolation: 'isolated',
+          failureClass: 'contract',
+          adapterReason: 'expected-observable-contract-failure',
+        });
+      } else {
+        results.push({
+          probeId: probe.probeId,
+          requirementId: probe.requirementId,
+          status: 'INVALID',
+          sourceSection: probe.sourceSection,
+          evidenceRef: evidenceRef(probe, run),
+          workspaceIsolation: 'isolated',
+          failureClass: 'unknown',
+          adapterReason: 'test-failed-without-expected-contract-observable',
+        });
+      }
+    } catch (error) {
+      results.push(notEvaluatedProbe(
+        probe,
+        String(error.message || error),
+        'infrastructure',
+        isolated ? 'isolated' : 'not-isolated',
+      ));
+    } finally {
+      if (isolated?.root) fs.rmSync(isolated.root, { recursive: true, force: true });
+    }
+  }
+
+  return {
+    schemaVersion: VERSION,
+    adapter: ADAPTER,
+    result: results.every(probe => probe.status === 'KILLED') ? 'PROTECTED' :
+      results.some(probe => probe.status === 'SURVIVED') ? 'SURVIVED' : 'NOT_EVALUATED',
+    discovery: discovered,
+    baseline: { status: 'PASS', workspaceIsolation: 'isolated' },
+    probes: results,
+    errors: [],
+  };
+}
+
+function parseArgs(argv) {
+  const args = { workspace: null, plan: null, output: null };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--workspace') args.workspace = argv[++i];
+    else if (argv[i] === '--plan') args.plan = argv[++i];
+    else if (argv[i] === '--output') args.output = argv[++i];
+    else throw new Error('unknown argument: ' + argv[i]);
+  }
+  if (!args.workspace || !args.plan) throw new Error('Usage: node node-probe-adapter.js --workspace <project> --plan <probe-plan.json> [--output report.json]');
+  return args;
+}
+
+function main() {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    const workspace = path.resolve(args.workspace);
+    const plan = JSON.parse(fs.readFileSync(path.resolve(args.plan), 'utf8'));
+    const report = executePlan(workspace, plan);
+    const json = JSON.stringify(report, null, 2) + '\n';
+    if (args.output) {
+      fs.mkdirSync(path.dirname(path.resolve(args.output)), { recursive: true });
+      fs.writeFileSync(path.resolve(args.output), json, 'utf8');
+    }
+    process.stdout.write(json);
+    process.exitCode = report.result === 'PROTECTED' ? 0 : report.result === 'SURVIVED' ? 1 : 2;
+  } catch (error) {
+    console.error('[Contract Probe Adapter] ' + error.message);
+    process.exitCode = 2;
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  ADAPTER,
+  VERSION,
+  applyProbe,
+  discoverProject,
+  executePlan,
+  runScript,
+  safeRelative,
+  validatePlan,
+};