harness-everything 0.14.0 → 0.16.0

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.16.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