harness-everything 0.14.0 → 0.16.0

package/contract-integrity/scripts/audit.js

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

package/docs/platform-capabilities.md

@@ -64,6 +64,22 @@ Codex has two paths that must not be collapsed:
 
 The package is tested at the mechanism layer and remains subject to the host’s hook review/trust flow. A fresh host session is still required before claiming that a particular ChatGPT/Codex installation loaded and fired the hooks or that the model followed read-before-skip.
 
+### Explicit Codex user-hook compatibility fallback
+
+Current Codex documentation supports plugin-bundled hooks, so native plugin mounting remains the preferred path. Some host/source combinations have nevertheless failed to expose enabled plugin hooks for review/entry attribution (#122 and upstream Codex reports). Harness therefore provides an **explicit compatibility fallback**, not an automatic replacement for native plugin hooks:
+
+```bash
+harness codex-hooks install
+harness codex-hooks status
+harness codex-hooks uninstall
+```
+
+The fallback copies the current packaged runtime into `$CODEX_HOME/harness-everything/compat-hooks/` and merges absolute-path entries into `$CODEX_HOME/hooks.json`. It does **not** modify `config.toml`, trust hashes, approval policy, or hook enablement. Codex must still show/review/trust the resulting non-managed hooks through its normal `/hooks` flow.
+
+Ownership is deliberately strict: update/uninstall removes only exact entries recorded in the Harness compatibility manifest. If an installed Harness entry was edited after installation, the operation fails closed rather than overwriting or deleting that user-modified entry. Unrelated pre-existing and later-added user hooks are preserved.
+
+This fallback solves only plugin-source discovery/mounting. It does not claim to repair a Codex carrier that fails to dispatch `PreToolUse` at all; those host-level execution-path limitations remain a live compatibility boundary.
+
 The public OpenAI Skills-only plugin is narrower again. Its ZIP contains the packaged `skills/` tree and referenced files, but not the local `.codex-plugin` lifecycle hooks. Public submission readiness is therefore a package/form contract, not evidence of public-directory approval or live hook execution.
 
 ## Install/uninstall ownership boundary

package/docs/platform-compatibility.json

@@ -1,6 +1,6 @@
 {
   "format": "harness-platform-compatibility-v1",
-  "last_reviewed": "2026-09-14",
+  "last_reviewed": "2026-09-19",
   "status_vocabulary": {
     "Supported": "An official or native mechanism exists and the Harness behavior is verified.",
     "Mechanism verified": "Harness package, adapter, or installer checks pass, but a real host run is not confirmed.",
@@ -109,13 +109,13 @@
         "standaloneSkills": {"status": "Supported", "paths": {"project": [".agents/skills"], "global": ["~/.agents/skills"]}},
         "pluginSupport": {"status": "Mechanism verified", "paths": {"manifest": ["plugin.json", ".codex-plugin/plugin.json"]}},
         "bundledSkills": {"status": "Mechanism verified", "notes": "The local package contains a root skills/ tree."},
-        "hooksLifecycle": {"status": "Mechanism verified", "notes": "Codex-supported SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, SubagentStart, SubagentStop, and Stop are covered by package checks; the plugin intentionally does not declare unsupported PostToolUseFailure. Non-managed hooks still require trust."},
+        "hooksLifecycle": {"status": "Mechanism verified", "notes": "Codex officially supports plugin-bundled hooks and the local package is mechanism-tested. The plugin intentionally does not declare unsupported PostToolUseFailure; Codex uses documented PostToolUse semantics instead. Harness also provides an explicit user-config compatibility fallback that copies the packaged runtime and merges exact-owned entries into $CODEX_HOME/hooks.json without changing trust/config.toml. Neither path is promoted to live verified until a real host exposes and executes the hooks."},
         "projectScope": {"status": "Mechanism verified", "paths": {"skills": [".agents/skills"], "instructions": ["AGENTS.md"]}},
         "globalScope": {"status": "Mechanism verified", "paths": {"skills": ["~/.agents/skills"]}},
-        "installUninstallSymmetry": {"status": "Mechanism verified", "notes": "Harness installer round-trip checks cover owned files and user-owned collisions."},
+        "installUninstallSymmetry": {"status": "Mechanism verified", "notes": "General Harness installer ownership is mechanism-tested. The optional codex-hooks compatibility fallback separately has exact-entry update/uninstall ownership tests and preserves unrelated user hooks; live Codex trust/dispatch still requires host evidence."},
         "assetsReferences": {"status": "Mechanism verified", "notes": "Packaged skill references are checked and remain inside the package."},
         "updateSync": {"status": "Unknown", "notes": "A real marketplace refresh has not been run in a Codex host."},
-        "liveHostVerification": {"status": "Unknown", "notes": "No preserved Codex plugin/session artifact is committed."}
+        "liveHostVerification": {"status": "Unknown", "notes": "No preserved Codex plugin/session artifact proves current bundled-hook entry. Native plugin mounting is preferred; the explicit user-hook fallback is mechanism-verified only and does not solve host carriers that bypass hook dispatch."}
       }
     },
     {

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.16.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.16.0",
   "description": "Harness OS: An Orchestrated Agent Operating System for AI-driven Development",
   "main": "harness-everything/scripts/bootstrap.js",
   "bin": {
@@ -54,7 +54,9 @@
     "test:contract-integrity": "node ci/contract-integrity.test.js",
     "contract:integrity": "node contract-integrity/scripts/audit.js",
     "waza:check": "node scripts/waza-harness-check.js",
-    "test:waza:compat": "node ci/mechanism-2aj-waza-reference-adapter.test.js"
+    "test:waza:compat": "node ci/mechanism-2aj-waza-reference-adapter.test.js",
+    "codex:hooks": "node scripts/codex-hooks-compat.js",
+    "test:codex:hooks-compat": "node ci/mechanism-2al-codex-hooks-compat.test.js"
   },
   "engines": {
     "node": ">=22"

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

@@ -1,6 +1,6 @@
 {
   "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",