harness-everything 0.14.0 → 0.15.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "harness-everything",
       "source": "./",
       "description": "Harness OS: an orchestrated agent operating system — tier routing, circuit breaker guardrails, verification gates, WAL session memory, and self-evolving workspace rules.",
-      "version": "0.14.0",
+      "version": "0.15.0",
       "author": {
         "name": "Miya Daniel"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "harness-everything",
   "description": "Harness OS: an orchestrated agent operating system — tier routing, circuit breaker guardrails, verification gates, WAL session memory, and self-evolving workspace rules.",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "author": {
     "name": "Miya Daniel"
   },

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.15.0](https://github.com/dyphn1/Harness-everything/compare/v0.14.0...v0.15.0) (2026-09-20)
+
+### Features
+
+* **contract:** add freshness provenance helpers ([865fc0b](https://github.com/dyphn1/Harness-everything/commit/865fc0bdb111feff865c3a85767fc587aecbd11a))
+* **contract:** emit requirement-scoped repair guidance ([cbd33ce](https://github.com/dyphn1/Harness-everything/commit/cbd33ce18fb8575671056bd4b2701bd0138baa96))
+* **contract:** reject stale completion reports ([79ea49e](https://github.com/dyphn1/Harness-everything/commit/79ea49e40f110fe062ac714519597e8a23a6ab5b))
+* **contract:** sync freshness audit runtime ([c5d0381](https://github.com/dyphn1/Harness-everything/commit/c5d038163b7ff2dc14e11bd4733e140e85e39f55))
+
+### Bug Fixes
+
+* **contract:** harden freshness evidence boundaries ([33ebbda](https://github.com/dyphn1/Harness-everything/commit/33ebbdafb2b63c4ece86ee81c14c4fcc6d33907f))
+* **contract:** launch npm probes cross-platform ([9ca5315](https://github.com/dyphn1/Harness-everything/commit/9ca5315cb30e8f03b08fb1f8789a141ea1179af4))
+* **contract:** launch npm probes cross-platform ([2cad76e](https://github.com/dyphn1/Harness-everything/commit/2cad76e217af136d934946f05c740d816e051acd))
+* **contract:** require complete freshness provenance ([5b6d717](https://github.com/dyphn1/Harness-everything/commit/5b6d717487fce37dcd1d1e8cbe8b037597035103))
+* **contract:** require complete freshness provenance ([d94e256](https://github.com/dyphn1/Harness-everything/commit/d94e2562c54d615d223a8572fd4d468e017a5807))
+
 ## [0.14.0](https://github.com/dyphn1/Harness-everything/compare/v0.13.0...v0.14.0) (2026-09-20)
 
 ### Features

package/ci/contract-integrity.test.js

@@ -265,5 +265,159 @@ for (const relative of [
     'Phase 2 OpenAI package mirror matches canonical: ' + relative);
 }
 
-console.log(`\n${failed === 0 ? 'PASS' : 'FAIL'}: #84 contract integrity phase 1-2 (${failed} failure${failed === 1 ? '' : 's'})`);
+// Phase 4: reports carry actionable requirement-scoped repair guidance and
+// content fingerprints so stale completion evidence cannot be reused.
+check(driftReport.repairGuidance.some(item =>
+  item.requirementId === 'REQ-001' && item.code === 'update-living-spec' &&
+  item.sourceRef === 'docs/specs/api.md#REQ-001'),
+  'stale-spec drift emits requirement-scoped living-spec repair guidance');
+check(paddedReport.repairGuidance.some(item =>
+  item.requirementId === 'REQ-001' && item.code === 'strengthen-weak-oracle' && item.priority === 'BLOCKER'),
+  'surviving required probe emits BLOCKER weak-oracle guidance');
+check(/Repair Guidance/.test(markdown(driftReport)) && /REQ-001/.test(markdown(driftReport)),
+  'Markdown keeps repair guidance concise and tied to requirement identity');
+
+const freshRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-contract-freshness-'));
+try {
+  const workspace = path.join(freshRoot, 'workspace');
+  fs.mkdirSync(workspace, { recursive: true });
+  for (const artifact of baseline.artifacts) {
+    const file = path.join(workspace, artifact.path);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, artifact.id + ': fixture content\n', 'utf8');
+  }
+  const tracePath = path.join(freshRoot, 'trace.json');
+  const tddPath = path.join(freshRoot, 'tdd.json');
+  const reportPath = path.join(freshRoot, 'report.json');
+  fs.writeFileSync(tracePath, JSON.stringify(baseline), 'utf8');
+  fs.writeFileSync(tddPath, JSON.stringify(baselineTdd), 'utf8');
+
+  const unboundReportPath = path.join(freshRoot, 'report-unbound.json');
+  const unboundAudit = spawnSync(process.execPath, [
+    path.join(ROOT, 'contract-integrity/scripts/audit.js'),
+    tracePath,
+    '--tdd-evidence', tddPath,
+    '--output', unboundReportPath,
+  ], { encoding: 'utf8' });
+  check(unboundAudit.status === 0, 'strict audit may emit a PASS report without workspace binding for immediate inspection');
+  const emptyWorkspace = path.join(freshRoot, 'empty-workspace');
+  fs.mkdirSync(emptyWorkspace, { recursive: true });
+  const unboundFreshness = spawnSync(process.execPath, [
+    path.join(ROOT, 'contract-integrity/scripts/audit.js'),
+    tracePath,
+    '--tdd-evidence', tddPath,
+    '--workspace', emptyWorkspace,
+    '--verify-fresh', unboundReportPath,
+  ], { encoding: 'utf8' });
+  check(unboundFreshness.status === 1 &&
+    /report-workspace-unbound/.test(unboundFreshness.stderr) &&
+    /artifact-fingerprint-missing:/.test(unboundFreshness.stderr),
+    'report created without workspace fingerprints cannot later authorize freshness against a supplied workspace');
+
+  const audit = spawnSync(process.execPath, [
+    path.join(ROOT, 'contract-integrity/scripts/audit.js'),
+    tracePath,
+    '--tdd-evidence', tddPath,
+    '--workspace', workspace,
+    '--output', reportPath,
+  ], { encoding: 'utf8' });
+  check(audit.status === 0, 'strict audit with existing workspace artifacts produces fresh PASS report', audit.stderr);
+  const freshReport = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
+  check(freshReport.provenance?.inputs?.trace?.sha256 &&
+    freshReport.provenance?.inputs?.tddEvidence?.sha256 &&
+    freshReport.provenance?.artifacts?.length === baseline.artifacts.length &&
+    freshReport.provenance.artifacts.every(item => item.sha256 && item.missing === false),
+    'report provenance records trace/TDD hashes plus current artifact hashes');
+
+  const verifyFresh = () => spawnSync(process.execPath, [
+    path.join(ROOT, 'contract-integrity/scripts/audit.js'),
+    tracePath,
+    '--tdd-evidence', tddPath,
+    '--workspace', workspace,
+    '--verify-fresh', reportPath,
+  ], { encoding: 'utf8' });
+
+  const current = verifyFresh();
+  check(current.status === 0 && /Freshness: PASS/.test(current.stdout),
+    'unchanged PASS report can authorize completion');
+
+  const failingTracePath = path.join(freshRoot, 'trace-failing.json');
+  const failingReportPath = path.join(freshRoot, 'report-failing.json');
+  const failingTrace = clone(baseline);
+  failingTrace.probes[0].status = 'SURVIVED';
+  failingTrace.probes[0].failureClass = 'none';
+  fs.writeFileSync(failingTracePath, JSON.stringify(failingTrace), 'utf8');
+  const failingAudit = spawnSync(process.execPath, [
+    path.join(ROOT, 'contract-integrity/scripts/audit.js'),
+    failingTracePath,
+    '--tdd-evidence', tddPath,
+    '--workspace', workspace,
+    '--output', failingReportPath,
+  ], { encoding: 'utf8' });
+  check(failingAudit.status === 1, 'surviving required probe produces a reusable FAIL report fixture');
+  const forgedReport = JSON.parse(fs.readFileSync(failingReportPath, 'utf8'));
+  forgedReport.result = 'PASS';
+  forgedReport.completionGate = 'PASS';
+  fs.writeFileSync(failingReportPath, JSON.stringify(forgedReport), 'utf8');
+  const forgedFreshness = spawnSync(process.execPath, [
+    path.join(ROOT, 'contract-integrity/scripts/audit.js'),
+    failingTracePath,
+    '--tdd-evidence', tddPath,
+    '--workspace', workspace,
+    '--verify-fresh', failingReportPath,
+  ], { encoding: 'utf8' });
+  check(forgedFreshness.status === 1 && /current-audit-not-pass/.test(forgedFreshness.stderr),
+    'freshness verification re-derives the current gate instead of trusting forged PASS fields');
+
+  const linkedWorkspace = path.join(freshRoot, 'linked-workspace');
+  fs.mkdirSync(linkedWorkspace, { recursive: true });
+  for (const artifact of baseline.artifacts.filter(item => item.id !== 'IMPL-001')) {
+    const file = path.join(linkedWorkspace, artifact.path);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, artifact.id + ': fixture content\n', 'utf8');
+  }
+  const outsideImpl = path.join(freshRoot, 'outside-implementation');
+  fs.mkdirSync(outsideImpl, { recursive: true });
+  fs.writeFileSync(path.join(outsideImpl, 'api.js'), 'IMPL-001: fixture content\n', 'utf8');
+  fs.symlinkSync(outsideImpl, path.join(linkedWorkspace, 'src'),
+    process.platform === 'win32' ? 'junction' : 'dir');
+  const linkedAudit = spawnSync(process.execPath, [
+    path.join(ROOT, 'contract-integrity/scripts/audit.js'),
+    tracePath,
+    '--tdd-evidence', tddPath,
+    '--workspace', linkedWorkspace,
+  ], { encoding: 'utf8' });
+  check(linkedAudit.status === 2 && /linked-path: IMPL-001/.test(linkedAudit.stderr),
+    'workspace-aware audit rejects artifact paths that resolve through a symlink or junction');
+
+  const testArtifact = path.join(workspace, 'tests/api.test.js');
+  fs.appendFileSync(testArtifact, 'changed after audit\n', 'utf8');
+  const staleTestReport = verifyFresh();
+  check(staleTestReport.status === 1 &&
+    /artifact-changed-since-audit:TEST-001/.test(staleTestReport.stderr),
+    'test artifact change invalidates previously passing report');
+  fs.writeFileSync(testArtifact, 'TEST-001: fixture content\n', 'utf8');
+
+  fs.writeFileSync(tddPath, JSON.stringify({ ...baselineTdd, changedAfterAudit: true }), 'utf8');
+  const staleEvidence = verifyFresh();
+  check(staleEvidence.status === 1 &&
+    /tdd-evidence-changed-since-audit/.test(staleEvidence.stderr),
+    '#58 evidence change invalidates previously passing report');
+
+  fs.writeFileSync(tddPath, JSON.stringify(baselineTdd), 'utf8');
+  fs.rmSync(path.join(workspace, 'src/api.js'));
+  const missingArtifactAudit = spawnSync(process.execPath, [
+    path.join(ROOT, 'contract-integrity/scripts/audit.js'),
+    tracePath,
+    '--tdd-evidence', tddPath,
+    '--workspace', workspace,
+  ], { encoding: 'utf8' });
+  check(missingArtifactAudit.status === 2 &&
+    /provenance artifact missing from workspace: IMPL-001/.test(missingArtifactAudit.stderr),
+    'strict workspace-aware audit fails closed when traced implementation evidence is missing');
+} finally {
+  fs.rmSync(freshRoot, { recursive: true, force: true });
+}
+
+console.log(`\n${failed === 0 ? 'PASS' : 'FAIL'}: #84 contract integrity phase 1-4 mechanism (${failed} failure${failed === 1 ? '' : 's'})`);
 process.exit(failed === 0 ? 0 : 1);

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/opencode-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "harness-enforcement",
   "description": "Repository inventory for the opencode enforcement plugin and its standalone helper",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "runtime": "index.mjs",
   "hooks": {
     "verify": "hooks/verify.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-everything",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Harness OS: An Orchestrated Agent Operating System for AI-driven Development",
   "main": "harness-everything/scripts/bootstrap.js",
   "bin": {

package/plugins/harness-everything/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-everything",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Invariant-first engineering harness for routing, verification, and failure recovery while preserving agent autonomy.",
   "author": {
     "name": "Miya Daniel",

package/plugins/harness-everything/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('../../skills/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/plugins/harness-everything/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "harness-everything",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Invariant-first engineering harness for routing, verification, and failure recovery while preserving agent autonomy.",
   "author": {
     "name": "Miya Daniel",

package/plugins/harness-everything/skills/verification-loop/SKILL.md

@@ -4,7 +4,7 @@ description: "Run objective verification gates (build, types, lint, tests, secur
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.12.0
+  version: 0.15.0
 ---
 
 # Verification Loop
@@ -41,7 +41,7 @@ and rerun from the first affected gate.
 4. Tests and coverage: `npm run test -- --coverage`.
 5. Security scan: secrets and stray logs.
 6. Diff review: `git diff --stat` and unintended-change checks.
-7. Contract reconciliation when the work cites `REQ-*` / ADR/spec/ticket lineage or a contract-integrity trace exists: run the strict `<this-skill-dir>/scripts/contract-integrity-audit.js` gate with current #58 evidence. `AUDIT`, `NOT_EVALUATED`, stale source binding, or drift is **not ready** for delivery.
+7. Contract reconciliation when the work cites `REQ-*` / ADR/spec/ticket lineage or a contract-integrity trace exists: run the strict `<this-skill-dir>/scripts/contract-integrity-audit.js` gate with current #58 evidence and `--workspace <workspace>` so traced source/test/implementation artifacts are fingerprinted. `AUDIT`, `NOT_EVALUATED`, stale source binding, or drift is **not ready** for delivery.
 8. Fill `<this-skill-dir>/templates/verification-report.template.md` with evidence.
 
 Deep dive: `<this-skill-dir>/references/verification-phases.md`

package/plugins/harness-everything/skills/verification-loop/references/verification-phases.md

@@ -110,11 +110,19 @@ This phase is applicable when any of the following is true:
 Use the current trace plus current #58 TDD evidence:
 
 ```bash
-node "<this-skill-dir>/scripts/contract-integrity-audit.js" <trace.json> --tdd-evidence <tdd-evidence.json> --output <report.json> --markdown <report.md>
+node "<this-skill-dir>/scripts/contract-integrity-audit.js" <trace.json> --tdd-evidence <tdd-evidence.json> --workspace <workspace> --output <report.json> --markdown <report.md>
 ```
 
 Delivery requires strict **PASS**. Treat `FAIL`, `AUDIT`, `NOT_EVALUATED`, source conflicts/defects, stale spec/test/implementation lineage, surviving required probes, and audit-only output as **NOT READY**. Do not downgrade the gate merely because build/tests are otherwise green.
 
+If an existing JSON report is being reused rather than regenerated immediately, verify its content fingerprints first:
+
+```bash
+node "<this-skill-dir>/scripts/contract-integrity-audit.js" <trace.json> --tdd-evidence <tdd-evidence.json> --workspace <workspace> --verify-fresh <report.json>
+```
+
+Any trace, #58 evidence, spec, test, ticket, ADR, or implementation artifact change makes the prior report stale and unable to authorize completion.
+
 If this phase is not applicable, record `NOT_APPLICABLE` with a one-line reason. Never use `NOT_APPLICABLE` to hide known requirement lineage.
 
 ## Output Format

package/verification-loop/SKILL.md

@@ -4,7 +4,7 @@ description: "Run objective verification gates (build, types, lint, tests, secur
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.12.0
+  version: 0.15.0
 ---
 
 # Verification Loop
@@ -41,7 +41,7 @@ and rerun from the first affected gate.
 4. Tests and coverage: `npm run test -- --coverage`.
 5. Security scan: secrets and stray logs.
 6. Diff review: `git diff --stat` and unintended-change checks.
-7. Contract reconciliation when the work cites `REQ-*` / ADR/spec/ticket lineage or a contract-integrity trace exists: run the strict `<this-skill-dir>/scripts/contract-integrity-audit.js` gate with current #58 evidence. `AUDIT`, `NOT_EVALUATED`, stale source binding, or drift is **not ready** for delivery.
+7. Contract reconciliation when the work cites `REQ-*` / ADR/spec/ticket lineage or a contract-integrity trace exists: run the strict `<this-skill-dir>/scripts/contract-integrity-audit.js` gate with current #58 evidence and `--workspace <workspace>` so traced source/test/implementation artifacts are fingerprinted. `AUDIT`, `NOT_EVALUATED`, stale source binding, or drift is **not ready** for delivery.
 8. Fill `<this-skill-dir>/templates/verification-report.template.md` with evidence.
 
 Deep dive: `<this-skill-dir>/references/verification-phases.md`

package/verification-loop/references/verification-phases.md

@@ -110,11 +110,19 @@ This phase is applicable when any of the following is true:
 Use the current trace plus current #58 TDD evidence:
 
 ```bash
-node "<this-skill-dir>/scripts/contract-integrity-audit.js" <trace.json> --tdd-evidence <tdd-evidence.json> --output <report.json> --markdown <report.md>
+node "<this-skill-dir>/scripts/contract-integrity-audit.js" <trace.json> --tdd-evidence <tdd-evidence.json> --workspace <workspace> --output <report.json> --markdown <report.md>
 ```
 
 Delivery requires strict **PASS**. Treat `FAIL`, `AUDIT`, `NOT_EVALUATED`, source conflicts/defects, stale spec/test/implementation lineage, surviving required probes, and audit-only output as **NOT READY**. Do not downgrade the gate merely because build/tests are otherwise green.
 
+If an existing JSON report is being reused rather than regenerated immediately, verify its content fingerprints first:
+
+```bash
+node "<this-skill-dir>/scripts/contract-integrity-audit.js" <trace.json> --tdd-evidence <tdd-evidence.json> --workspace <workspace> --verify-fresh <report.json>
+```
+
+Any trace, #58 evidence, spec, test, ticket, ADR, or implementation artifact change makes the prior report stale and unable to authorize completion.
+
 If this phase is not applicable, record `NOT_APPLICABLE` with a one-line reason. Never use `NOT_APPLICABLE` to hide known requirement lineage.
 
 ## Output Format