harness-everything 0.9.0 → 0.11.0

package/contract-integrity/scripts/audit.js

@@ -0,0 +1,536 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { evaluateEvidence } = require('../../tdd/scripts/quality-gate');
+
+const VERSION = '1.0.0';
+const MODES = new Set(['audit', 'strict']);
+const ARTIFACT_KINDS = new Set(['ADR', 'SPEC', 'TICKET', 'TEST', 'IMPLEMENTATION']);
+const ARTIFACT_STATUSES = new Set(['ACTIVE', 'SUPERSEDED', 'DEPRECATED']);
+const REQUIREMENT_STATUSES = new Set(['CURRENT', 'SUPERSEDED']);
+const SOURCE_VALIDITY = new Set(['VALID', 'SOURCE_DEFECT', 'SOURCE_CONFLICT']);
+const PROBE_STATUSES = new Set(['KILLED', 'SURVIVED', 'INVALID', 'NOT_EVALUATED']);
+const DRIFT = new Set([
+  'CONSISTENT',
+  'UNTRACED_CHANGE',
+  'STALE_SPEC',
+  'STALE_TEST',
+  'STALE_IMPLEMENTATION',
+  'SOURCE_DEFECT',
+  'SOURCE_CONFLICT',
+  'INTENTIONAL_SUPERSESSION',
+  'NOT_EVALUATED',
+]);
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function text(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function round(value) {
+  return Math.round((value + Number.EPSILON) * 100) / 100;
+}
+function unique(values) {
+  return [...new Set(values)];
+}
+function safeRelativePath(value) {
+  const p = text(value);
+  if (!p || path.isAbsolute(p) || p.includes('\\0')) return false;
+  const normalized = p.replace(/\\/g, '/');
+  return normalized !== '..' && !normalized.startsWith('../') && !normalized.includes('/../');
+}
+function rejectUnknownKeys(value, allowed, errors, location) {
+  if (!isObject(value)) return;
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) errors.push(`${location} contains unknown field: ${key}`);
+  }
+}
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(path.resolve(file), 'utf8'));
+}
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (!isObject(value)) return value;
+  return Object.fromEntries(Object.keys(value).sort().map(key => [key, stable(value[key])]));
+}
+
+function validateTrace(input) {
+  const errors = [];
+  if (!isObject(input)) return ['trace root must be an object'];
+  if (input.schemaVersion !== VERSION) errors.push(`schemaVersion must be ${VERSION}`);
+  if (!MODES.has(input.mode)) errors.push('mode must be audit or strict');
+  if (!Array.isArray(input.artifacts)) errors.push('artifacts must be an array');
+  if (!Array.isArray(input.requirements) || input.requirements.length === 0) errors.push('requirements must be a non-empty array');
+  if (!Array.isArray(input.probes)) errors.push('probes must be an array');
+  if (errors.length) return errors;
+
+  const artifactIds = new Set();
+  for (const [index, artifact] of input.artifacts.entries()) {
+    const p = `artifacts[${index}]`;
+    if (!isObject(artifact)) { errors.push(`${p} must be an object`); continue; }
+    rejectUnknownKeys(artifact, new Set(['id','kind','path','status','revision','requirementId','requirementRevision','changeImpact','supersedes','evidenceRef']), errors, p);
+    if (!text(artifact.id)) errors.push(`${p}.id is required`);
+    else if (artifactIds.has(artifact.id)) errors.push(`duplicate artifact id: ${artifact.id}`);
+    else artifactIds.add(artifact.id);
+    if (!ARTIFACT_KINDS.has(artifact.kind)) errors.push(`${p}.kind is invalid`);
+    if (!safeRelativePath(artifact.path)) errors.push(`${p}.path must be a repo-relative non-traversing path`);
+    if (!ARTIFACT_STATUSES.has(artifact.status)) errors.push(`${p}.status is invalid`);
+    if (!Number.isInteger(artifact.revision) || artifact.revision < 1) errors.push(`${p}.revision must be >= 1`);
+    if (artifact.requirementRevision != null && (!Number.isInteger(artifact.requirementRevision) || artifact.requirementRevision < 1)) {
+      errors.push(`${p}.requirementRevision must be null or >= 1`);
+    }
+    if (artifact.kind === 'TICKET' && !['none','implementation','behavior','architecture'].includes(artifact.changeImpact)) {
+      errors.push(`${p}.changeImpact is required for tickets`);
+    }
+    if (artifact.kind !== 'TICKET' && artifact.changeImpact !== undefined) errors.push(`${p}.changeImpact is ticket-only`);
+    if (artifact.supersedes !== undefined && (!Array.isArray(artifact.supersedes) || new Set(artifact.supersedes).size !== artifact.supersedes.length)) {
+      errors.push(`${p}.supersedes must be a unique array`);
+    }
+  }
+
+  const requirementIds = new Set();
+  for (const [index, requirement] of input.requirements.entries()) {
+    const p = `requirements[${index}]`;
+    if (!isObject(requirement)) { errors.push(`${p} must be an object`); continue; }
+    rejectUnknownKeys(requirement, new Set(['requirementId','revision','status','specId','decisionIds','ticketIds','testIds','implementationIds','requiredProbeIds','sourceValidity','supersededBy']), errors, p);
+    if (!text(requirement.requirementId)) errors.push(`${p}.requirementId is required`);
+    else if (requirementIds.has(requirement.requirementId)) errors.push(`duplicate requirementId: ${requirement.requirementId}`);
+    else requirementIds.add(requirement.requirementId);
+    if (!Number.isInteger(requirement.revision) || requirement.revision < 1) errors.push(`${p}.revision must be >= 1`);
+    if (!REQUIREMENT_STATUSES.has(requirement.status)) errors.push(`${p}.status is invalid`);
+    if (!text(requirement.specId)) errors.push(`${p}.specId is required`);
+    for (const field of ['decisionIds','ticketIds','testIds','implementationIds','requiredProbeIds']) {
+      if (!Array.isArray(requirement[field])) errors.push(`${p}.${field} must be an array`);
+      else if (new Set(requirement[field]).size !== requirement[field].length) errors.push(`${p}.${field} must not contain duplicates`);
+    }
+    if (!SOURCE_VALIDITY.has(requirement.sourceValidity)) errors.push(`${p}.sourceValidity is invalid`);
+    if (requirement.status === 'SUPERSEDED' && !text(requirement.supersededBy)) errors.push(`${p}.supersededBy is required for superseded requirements`);
+    if (requirement.status === 'CURRENT' && requirement.supersededBy != null) errors.push(`${p}.supersededBy must be null/omitted for current requirements`);
+  }
+
+  const probeIds = new Set();
+  for (const [index, probe] of input.probes.entries()) {
+    const p = `probes[${index}]`;
+    if (!isObject(probe)) { errors.push(`${p} must be an object`); continue; }
+    rejectUnknownKeys(probe, new Set(['probeId','requirementId','status','sourceSection','evidenceRef','workspaceIsolation','failureClass']), errors, p);
+    if (!text(probe.probeId)) errors.push(`${p}.probeId is required`);
+    else if (probeIds.has(probe.probeId)) errors.push(`duplicate probeId: ${probe.probeId}`);
+    else probeIds.add(probe.probeId);
+    if (!text(probe.requirementId)) errors.push(`${p}.requirementId is required`);
+    if (!PROBE_STATUSES.has(probe.status)) errors.push(`${p}.status is invalid`);
+    if (!text(probe.sourceSection)) errors.push(`${p}.sourceSection is required`);
+    if (!['isolated','not-isolated','unknown'].includes(probe.workspaceIsolation)) errors.push(`${p}.workspaceIsolation is invalid`);
+    if (!['contract','build','infrastructure','flaky','none','unknown'].includes(probe.failureClass)) errors.push(`${p}.failureClass is invalid`);
+    if (['KILLED','SURVIVED'].includes(probe.status) && !text(probe.evidenceRef)) errors.push(`${p}.evidenceRef is required for evaluated probes`);
+    if (probe.status === 'KILLED' && probe.failureClass !== 'contract') {
+      errors.push(`${p}: KILLED requires failureClass=contract; compile/build/infrastructure failures are invalid protection evidence`);
+    }
+    if (['KILLED','SURVIVED'].includes(probe.status) && probe.workspaceIsolation !== 'isolated') {
+      errors.push(`${p}: evaluated probes require isolated workspace evidence`);
+    }
+  }
+  return errors;
+}
+
+function artifactMap(trace) {
+  return new Map(trace.artifacts.map(artifact => [artifact.id, artifact]));
+}
+
+function expectedKind(map, id, kind, errors, location) {
+  const artifact = map.get(id);
+  if (!artifact) { errors.push(`${location}: missing artifact ${id}`); return null; }
+  if (artifact.kind !== kind) { errors.push(`${location}: ${id} must be ${kind}, got ${artifact.kind}`); return null; }
+  return artifact;
+}
+
+function classifyLineage(requirement, map) {
+  const statuses = [];
+  const reasons = [];
+  const links = [];
+
+  const spec = map.get(requirement.specId);
+  if (!spec || spec.kind !== 'SPEC') {
+    statuses.push('UNTRACED_CHANGE');
+    reasons.push('missing-current-spec-link');
+  } else {
+    links.push({ from: requirement.requirementId, to: spec.id, relation: 'defined-by' });
+    if (spec.status !== 'ACTIVE' || spec.revision !== requirement.revision) {
+      statuses.push('STALE_SPEC');
+      reasons.push(spec.status !== 'ACTIVE' ? 'spec-not-active' : 'spec-revision-mismatch');
+    }
+  }
+
+  if (requirement.sourceValidity === 'SOURCE_DEFECT') {
+    statuses.push('SOURCE_DEFECT');
+    reasons.push('declared-source-defect');
+  }
+  if (requirement.sourceValidity === 'SOURCE_CONFLICT') {
+    statuses.push('SOURCE_CONFLICT');
+    reasons.push('declared-source-conflict');
+  }
+
+  if (requirement.status === 'SUPERSEDED') {
+    statuses.push('INTENTIONAL_SUPERSESSION');
+    reasons.push('requirement-explicitly-superseded');
+    links.push({ from: requirement.requirementId, to: requirement.supersededBy, relation: 'superseded-by' });
+    return { statuses: unique(statuses), reasons: unique(reasons), links };
+  }
+
+  for (const id of requirement.decisionIds || []) {
+    const adr = map.get(id);
+    if (!adr || adr.kind !== 'ADR') {
+      statuses.push('UNTRACED_CHANGE');
+      reasons.push(`missing-decision:${id}`);
+      continue;
+    }
+    links.push({ from: id, to: requirement.requirementId, relation: 'governs' });
+    if (adr.status !== 'ACTIVE') {
+      statuses.push('UNTRACED_CHANGE');
+      reasons.push(`decision-not-active:${id}`);
+    }
+  }
+
+  if (!requirement.ticketIds?.length) {
+    statuses.push('UNTRACED_CHANGE');
+    reasons.push('no-ticket-lineage');
+  }
+  for (const id of requirement.ticketIds || []) {
+    const ticket = map.get(id);
+    if (!ticket || ticket.kind !== 'TICKET') {
+      statuses.push('UNTRACED_CHANGE');
+      reasons.push(`missing-ticket:${id}`);
+      continue;
+    }
+    links.push({ from: requirement.requirementId, to: id, relation: 'implemented-by-change' });
+    const targetRevision = ticket.requirementRevision;
+    if (ticket.requirementId !== requirement.requirementId) {
+      statuses.push('UNTRACED_CHANGE');
+      reasons.push(`ticket-requirement-mismatch:${id}`);
+    }
+    if (Number.isInteger(targetRevision) && targetRevision > requirement.revision && ['behavior','architecture'].includes(ticket.changeImpact)) {
+      statuses.push('STALE_SPEC');
+      statuses.push('UNTRACED_CHANGE');
+      reasons.push(`ticket-ahead-of-contract:${id}`);
+    } else if (Number.isInteger(targetRevision) && targetRevision !== requirement.revision) {
+      statuses.push('UNTRACED_CHANGE');
+      reasons.push(`ticket-revision-mismatch:${id}`);
+    }
+    if (ticket.changeImpact === 'architecture' && !(requirement.decisionIds || []).length) {
+      statuses.push('UNTRACED_CHANGE');
+      reasons.push(`architecture-change-without-decision-lineage:${id}`);
+    }
+  }
+
+  if (!requirement.testIds?.length) {
+    statuses.push('STALE_TEST');
+    reasons.push('no-test-lineage');
+  }
+  for (const id of requirement.testIds || []) {
+    const testArtifact = map.get(id);
+    if (!testArtifact || testArtifact.kind !== 'TEST') {
+      statuses.push('STALE_TEST');
+      reasons.push(`missing-test:${id}`);
+      continue;
+    }
+    links.push({ from: requirement.requirementId, to: id, relation: 'protected-by' });
+    if (testArtifact.requirementId !== requirement.requirementId || testArtifact.requirementRevision !== requirement.revision || testArtifact.status !== 'ACTIVE') {
+      statuses.push('STALE_TEST');
+      reasons.push(`test-lineage-mismatch:${id}`);
+    }
+  }
+
+  if (!requirement.implementationIds?.length) {
+    statuses.push('STALE_IMPLEMENTATION');
+    reasons.push('no-implementation-lineage');
+  }
+  for (const id of requirement.implementationIds || []) {
+    const impl = map.get(id);
+    if (!impl || impl.kind !== 'IMPLEMENTATION') {
+      statuses.push('STALE_IMPLEMENTATION');
+      reasons.push(`missing-implementation:${id}`);
+      continue;
+    }
+    links.push({ from: requirement.requirementId, to: id, relation: 'realized-by' });
+    if (impl.requirementId !== requirement.requirementId || impl.requirementRevision !== requirement.revision || impl.status !== 'ACTIVE') {
+      statuses.push('STALE_IMPLEMENTATION');
+      reasons.push(`implementation-lineage-mismatch:${id}`);
+    }
+  }
+
+  if (statuses.length === 0) statuses.push('CONSISTENT');
+  return { statuses: unique(statuses), reasons: unique(reasons), links };
+}
+
+function protectionForRequirement(requirement, probesById, currentSpec = null) {
+  const expected = requirement.requiredProbeIds || [];
+  if (expected.length === 0) {
+    return {
+      status: 'NOT_EVALUATED',
+      score: 0,
+      required: 0,
+      killed: 0,
+      survived: 0,
+      invalid: 0,
+      missing: [],
+      reasonCodes: ['no-required-probes-declared'],
+    };
+  }
+
+  let killed = 0;
+  let survived = 0;
+  let invalid = 0;
+  const missing = [];
+  const reasonCodes = [];
+
+  for (const id of expected) {
+    const probe = probesById.get(id);
+    if (!probe || probe.requirementId !== requirement.requirementId) {
+      missing.push(id);
+      continue;
+    }
+    const sourceMatchesCurrentSpec = currentSpec && typeof probe.sourceSection === 'string' &&
+      (probe.sourceSection === currentSpec.path || probe.sourceSection.startsWith(`${currentSpec.path}#`));
+    if (!sourceMatchesCurrentSpec) {
+      invalid++;
+      reasonCodes.push('probe-source-not-current-spec');
+      continue;
+    }
+    if (probe.status === 'KILLED' && probe.failureClass === 'contract' && probe.workspaceIsolation === 'isolated' && text(probe.evidenceRef)) killed++;
+    else if (probe.status === 'SURVIVED') survived++;
+    else invalid++;
+  }
+
+  if (missing.length || invalid) {
+    reasonCodes.push(...(missing.length ? ['required-probe-missing'] : []), ...(invalid ? ['invalid-probe-evidence'] : []));
+    return { status: 'NOT_EVALUATED', score: 0, required: expected.length, killed, survived, invalid, missing, reasonCodes };
+  }
+  if (survived > 0) {
+    return {
+      status: 'SURVIVED',
+      score: 0,
+      required: expected.length,
+      killed,
+      survived,
+      invalid,
+      missing,
+      reasonCodes: ['required-contract-probe-survived'],
+    };
+  }
+  if (killed === expected.length) {
+    return {
+      status: 'PROTECTED',
+      score: 100,
+      required: expected.length,
+      killed,
+      survived,
+      invalid,
+      missing,
+      reasonCodes: ['all-predeclared-contract-probes-killed'],
+    };
+  }
+  return { status: 'NOT_EVALUATED', score: 0, required: expected.length, killed, survived, invalid, missing, reasonCodes: ['probe-evidence-incomplete'] };
+}
+
+function completenessByRequirement(tddEvidence) {
+  if (!tddEvidence) return { report: null, byId: new Map(), score: 0, result: 'NOT_EVALUATED' };
+  const report = evaluateEvidence(tddEvidence);
+  const byId = new Map(report.requirements.map(req => [req.requirementId, { score: req.score, result: req.result }]));
+  return { report, byId, score: report.score, result: report.result };
+}
+
+function evaluateTrace(trace, options = {}) {
+  const validationErrors = validateTrace(trace);
+  const map = Array.isArray(trace?.artifacts) ? artifactMap(trace) : new Map();
+  const probesById = new Map((trace?.probes || []).map(probe => [probe.probeId, probe]));
+  const completeness = completenessByRequirement(options.tddEvidence || null);
+  const reportRequirements = [];
+  const links = [];
+  const globalErrors = [...validationErrors];
+
+  if (validationErrors.length === 0) {
+    const reqIds = new Set(trace.requirements.map(req => req.requirementId));
+    for (const artifact of trace.artifacts) {
+      for (const prior of artifact.supersedes || []) {
+        if (!map.has(prior)) globalErrors.push(`artifact ${artifact.id} supersedes missing artifact ${prior}`);
+        else links.push({ from: artifact.id, to: prior, relation: 'supersedes' });
+      }
+    }
+    for (const requirement of trace.requirements) {
+      if (requirement.status === 'SUPERSEDED' && !reqIds.has(requirement.supersededBy)) {
+        globalErrors.push(`${requirement.requirementId}: supersededBy target does not exist: ${requirement.supersededBy}`);
+      }
+    }
+  }
+
+  for (const requirement of trace?.requirements || []) {
+    const lineage = classifyLineage(requirement, map);
+    links.push(...lineage.links);
+    const currentSpec = map.get(requirement.specId) || null;
+    const protection = protectionForRequirement(requirement, probesById, currentSpec);
+    const quality = completeness.byId.get(requirement.requirementId) || { score: 0, result: 'NOT_EVALUATED' };
+    const statuses = [...lineage.statuses];
+    const qualityDetail = completeness.report?.requirements?.find(item => item.requirementId === requirement.requirementId) || null;
+    if (qualityDetail && currentSpec && qualityDetail.source?.status === 'AUTHORITATIVE' &&
+        qualityDetail.source.path !== currentSpec.path) {
+      statuses.push('STALE_TEST');
+      lineage.reasons.push('tdd-source-not-current-spec');
+    }
+    if (requirement.status === 'CURRENT' && protection.status === 'NOT_EVALUATED') statuses.push('NOT_EVALUATED');
+    if (requirement.status === 'CURRENT' && quality.result === 'NOT_EVALUATED') statuses.push('NOT_EVALUATED');
+    const blocking = statuses.filter(status => !['CONSISTENT','INTENTIONAL_SUPERSESSION'].includes(status));
+    reportRequirements.push({
+      requirementId: requirement.requirementId,
+      revision: requirement.revision,
+      lifecycleStatus: requirement.status,
+      drift: unique(statuses),
+      reasonCodes: lineage.reasons,
+      completeness: quality,
+      protection,
+      gateEligible: requirement.status === 'SUPERSEDED' ? true : blocking.length === 0 && quality.result === 'PASS' && protection.status === 'PROTECTED',
+    });
+  }
+
+  const current = reportRequirements.filter(req => req.lifecycleStatus === 'CURRENT');
+  const completenessScore = current.length
+    ? round(current.reduce((sum, req) => sum + req.completeness.score, 0) / current.length)
+    : 0;
+  const protectionScore = current.length
+    ? round(current.reduce((sum, req) => sum + req.protection.score, 0) / current.length)
+    : 0;
+  const contractIntegrityScore = Math.min(completenessScore, protectionScore);
+  const driftCounts = Object.fromEntries([...DRIFT].map(status => [status, 0]));
+  for (const req of reportRequirements) for (const status of req.drift) driftCounts[status] = (driftCounts[status] || 0) + 1;
+
+  const strictPass = globalErrors.length === 0 &&
+    current.length > 0 &&
+    current.every(req => req.gateEligible) &&
+    contractIntegrityScore === 100;
+
+  return {
+    schemaVersion: VERSION,
+    mode: trace?.mode || null,
+    result: globalErrors.length ? 'FAIL' : (strictPass ? 'PASS' : (trace?.mode === 'audit' ? 'AUDIT' : 'FAIL')),
+    completionGate: strictPass ? 'PASS' : (current.some(req => req.drift.includes('NOT_EVALUATED')) ? 'NOT_EVALUATED' : 'FAIL'),
+    gateEligible: strictPass,
+    scores: {
+      completenessScore,
+      protectionScore,
+      contractIntegrityScore,
+      formula: 'min(completenessScore, protectionScore)',
+    },
+    counts: {
+      artifacts: trace?.artifacts?.length || 0,
+      requirements: reportRequirements.length,
+      currentRequirements: current.length,
+      probes: trace?.probes?.length || 0,
+    },
+    driftCounts,
+    requirements: reportRequirements,
+    graph: {
+      nodes: [
+        ...(trace?.artifacts || []).map(artifact => ({ id: artifact.id, kind: artifact.kind, status: artifact.status, path: artifact.path })),
+        ...(trace?.requirements || []).map(req => ({ id: req.requirementId, kind: 'REQUIREMENT', status: req.status, revision: req.revision })),
+      ],
+      links: unique(links.map(link => JSON.stringify(stable(link)))).map(value => JSON.parse(value)),
+    },
+    tddQuality: completeness.report,
+    errors: globalErrors,
+  };
+}
+
+function markdown(report) {
+  const lines = [
+    '# Contract Integrity Report',
+    '',
+    `- Mode: **${report.mode}**`,
+    `- Result: **${report.result}**`,
+    `- Completion gate: **${report.completionGate}**`,
+    `- Completeness score: **${report.scores.completenessScore}**`,
+    `- Protection score: **${report.scores.protectionScore}**`,
+    `- Contract integrity score: **${report.scores.contractIntegrityScore}** = min(completeness, protection)`,
+    '',
+    '| Requirement | Rev | Drift | Completeness | Protection | Gate |',
+    '| --- | ---: | --- | ---: | --- | --- |',
+  ];
+  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.errors.length) {
+    lines.push('', '## Errors', '', ...report.errors.map(error => `- ${error}`));
+  }
+  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.');
+  lines.push('- Build/infrastructure/flaky failures are invalid probe evidence and cannot count as killed contract probes.');
+  lines.push('- Audit mode reports legacy debt without authorizing completion; strict mode fails on any unresolved drift or NOT_EVALUATED protection.');
+  return `${lines.join('\n')}\n`;
+}
+
+function parseArgs(argv) {
+  const args = { input: null, tddEvidence: null, output: null, markdown: 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 throw new Error(`unknown argument: ${token}`);
+  }
+  return args;
+}
+
+function runCli(argv) {
+  let args;
+  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]');
+    return 2;
+  }
+
+  let trace;
+  let tddEvidence = null;
+  try {
+    trace = readJson(args.input);
+    if (args.tddEvidence) tddEvidence = readJson(args.tddEvidence);
+  } catch (error) {
+    console.error(`Contract Integrity: FAIL\n- ${error.message}`);
+    return 2;
+  }
+
+  const report = evaluateTrace(trace, { tddEvidence });
+  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}`);
+  for (const req of report.requirements) console.log(`- ${req.requirementId}: ${req.drift.join(', ')} / protection=${req.protection.status}`);
+  for (const error of report.errors) console.error(`- error: ${error}`);
+
+  if (args.output) {
+    fs.mkdirSync(path.dirname(path.resolve(args.output)), { recursive: true });
+    fs.writeFileSync(path.resolve(args.output), `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+  }
+  if (args.markdown) {
+    fs.mkdirSync(path.dirname(path.resolve(args.markdown)), { recursive: true });
+    fs.writeFileSync(path.resolve(args.markdown), markdown(report), 'utf8');
+  }
+
+  if (report.errors.length) return 2;
+  if (trace.mode === 'audit') return 0;
+  return report.result === 'PASS' ? 0 : 1;
+}
+
+if (require.main === module) process.exit(runCli(process.argv));
+
+module.exports = {
+  DRIFT,
+  VERSION,
+  classifyLineage,
+  evaluateTrace,
+  markdown,
+  protectionForRequirement,
+  runCli,
+  validateTrace,
+};

package/docs/contract-integrity.md

@@ -0,0 +1,109 @@
+# Contract Integrity Audit
+
+The contract-integrity audit reconciles the chain:
+
+```text
+ADR decision -> living spec requirement -> ticket/change
+-> #58 completeness evidence -> predeclared protection probes
+-> implementation evidence
+```
+
+Phase 1 is a **trace/reconciliation engine**. It does not yet generate or execute mutation probes. A green existing suite therefore cannot manufacture a protection PASS.
+
+## Inputs
+
+`contract-integrity/schemas/trace.schema.json` defines version `1.0.0`.
+
+Every current requirement has:
+
+- a stable `requirementId` and revision;
+- one current living spec;
+- zero or more governing ADR decisions;
+- linked tickets, tests, and implementation evidence;
+- **predeclared** `requiredProbeIds`;
+- explicit source validity.
+
+Artifacts use stable IDs and lifecycle state instead of appending ticket history into ADR text.
+
+Protection probe dispositions are:
+
+- `KILLED`: valid only when an isolated source-derived contract probe fails for the expected contract reason;
+- `SURVIVED`: the implementation violated the contract and the tests did not stop it;
+- `INVALID`: build/infrastructure/flaky or otherwise unusable evidence;
+- `NOT_EVALUATED`: not executed.
+
+A compile/build failure is never counted as a killed contract probe.
+
+## Scoring
+
+Completeness is not reimplemented. Pass `--tdd-evidence` and Harness calls the existing #58 evaluator.
+
+Protection is intentionally anti-padding:
+
+1. each requirement declares `requiredProbeIds` before execution;
+2. only those probe IDs affect its score;
+3. a requirement is 100 only when **every required probe is validly KILLED**;
+4. any required `SURVIVED` probe makes that requirement 0;
+5. missing/invalid/not-evaluated required evidence also gives 0 and `NOT_EVALUATED`;
+6. extra killed probes do not change the requirement score.
+
+The project score is:
+
+```text
+contractIntegrityScore = min(completenessScore, protectionScore)
+```
+
+Scores never override a drift or evidence gate.
+
+## Drift vocabulary
+
+The machine report uses:
+
+- `CONSISTENT`
+- `UNTRACED_CHANGE`
+- `STALE_SPEC`
+- `STALE_TEST`
+- `STALE_IMPLEMENTATION`
+- `SOURCE_DEFECT`
+- `SOURCE_CONFLICT`
+- `INTENTIONAL_SUPERSESSION`
+- `NOT_EVALUATED`
+
+A ticket with behavior/architecture impact targeting a newer requirement revision than the living spec is `STALE_SPEC + UNTRACED_CHANGE`. Test/probe evidence must point to the current living spec, not merely have a green score.
+
+## CLI
+
+```bash
+node contract-integrity/scripts/audit.js trace.json \
+  --tdd-evidence tdd-evidence.json \
+  --output contract-report.json \
+  --markdown contract-report.md
+```
+
+Or:
+
+```bash
+npm run contract:integrity -- trace.json --tdd-evidence tdd-evidence.json
+```
+
+### Modes
+
+`strict`
+: unresolved drift, missing completeness evidence, surviving/invalid/missing probes, source defects/conflicts, or a score below 100 fail the completion gate.
+
+`audit`
+: intended for migration of legacy projects. It returns an audit report and exits zero for valid input even when debt exists, but `gateEligible` remains false and it **cannot authorize completion**.
+
+Malformed input/evidence returns exit 2 in either mode.
+
+## Reports
+
+JSON contains raw artifact/requirement/probe counts, both component scores, integrity score, drift counts, per-requirement reason codes, and the compact contract graph.
+
+Markdown stays concise. Detailed lineage belongs in the generated graph/report, not as raw ticket chronology appended to ADRs/specs.
+
+## Phase boundary
+
+Phase 1 consumes declared probe evidence but does not create it. Phase 3 of #84 will define project adapters and execute source-derived probes in isolated/recoverable workspaces. Until then, absent probe evidence is `NOT_EVALUATED`, never PASS.
+
+No new directly routed skill is introduced in Phase 1. Phase 2 must first review routing/description collision before integrating this audit into `grill-with-docs`, `to-spec`, `to-tickets`, or completion workflows.