@lifeaitools/rdc-skills 0.24.0 → 0.24.2

package/hooks/work-item-exit-gate.js

@@ -11,12 +11,21 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { execFileSync } = require('child_process');
 const hookLog = require('./hook-logger');
 
 const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+const FULL_SHA_RE = /^[0-9a-f]{40}$/i;
 const DEFAULT_SUPABASE_URL = 'https://uvojezuorjgqzmhhgluu.supabase.co';
 const EVENT_LOG = path.join(os.homedir(), '.claude', 'work-item-checklist-events.jsonl');
 
+// Truth Gate 3.0 — Layer 2 (FUSED evidence gate).
+//   Witness allow-list (D5 / SLSA: the doer cannot sign its own provenance).
+const WITNESS_ALLOWLIST = new Set(['validator-rerun', 'ci', 'human-review']);
+//   Repo the gate runs `git` against. The work tree under verification is
+//   regen-root; overridable for tests via RDC_TRUTH_GATE_REPO.
+const TRUTH_GATE_REPO = process.env.RDC_TRUTH_GATE_REPO || 'C:/Dev/regen-root';
+
 function readStdin() {
   return new Promise((resolve) => {
     let input = '';
@@ -208,6 +217,216 @@ function requiredItems(checklist) {
     : [];
 }
 
+// ===========================================================================
+// Truth Gate 3.0 — Layer 2 (FUSED evidence gate / freeze-the-leak)
+//
+// Asserts, server-checkable and FAIL-CLOSED, that a `done` close corresponds to
+// reality. Baru-trap hardening (from the auditors' OWN false positives):
+//   - resolve commits by FULL 40-hex SHA only — never short-prefix compare
+//     (prefix collisions falsely flagged real work as fabricated).
+//   - locate claimed files WHOLE-REPO (`git log --all -- <path>`), never
+//     cited-path-only (wrong-path lookups falsely cried "absent").
+// ===========================================================================
+
+/**
+ * A Layer-2 denial. Thrown by `deny()` so verifyLayer2 short-circuits without
+ * coupling to process.exit — production translates it to block(), tests assert
+ * on `.reason`. This keeps the gate logic pure + unit-testable while staying
+ * FAIL-CLOSED at the process boundary.
+ */
+class GateDenied extends Error {
+  constructor(reason, details) {
+    super(reason);
+    this.name = 'GateDenied';
+    this.reason = reason;
+    this.details = details || {};
+  }
+}
+
+function deny(reason, details) {
+  throw new GateDenied(reason, details);
+}
+
+/** Run a git command in the truth-gate repo; returns trimmed stdout or null. */
+function git(args, { allowFail = false } = {}) {
+  try {
+    return execFileSync('git', args, {
+      cwd: TRUTH_GATE_REPO,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      maxBuffer: 16 * 1024 * 1024,
+    }).trim();
+  } catch (e) {
+    if (allowFail) return null;
+    throw e;
+  }
+}
+
+/**
+ * Resolve a commit ref to its FULL 40-char SHA, or null if it does not exist.
+ * Uses `rev-parse --verify <ref>^{commit}` so only real commit objects resolve.
+ * NEVER does a prefix/substring compare — the returned value is the canonical
+ * full SHA, and all equality downstream is full-SHA equality.
+ */
+function resolveFullSha(ref) {
+  if (typeof ref !== 'string' || !ref.trim()) return null;
+  const full = git(['rev-parse', '--verify', '--quiet', `${ref.trim()}^{commit}`], { allowFail: true });
+  return full && FULL_SHA_RE.test(full) ? full.toLowerCase() : null;
+}
+
+/** Full set of file paths touched by a commit (`git show --stat`→ name-only). */
+function filesInCommit(fullSha) {
+  const out = git(['show', '--no-renames', '--name-only', '--pretty=format:', fullSha], { allowFail: true });
+  if (out == null) return null;
+  return new Set(out.split('\n').map((l) => l.trim()).filter(Boolean).map(normalizeRepoPath));
+}
+
+function normalizeRepoPath(p) {
+  return String(p || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '').trim();
+}
+
+/**
+ * Whole-repo existence check for a claimed file. A file "exists for this repo"
+ * when EITHER it is tracked anywhere in history (`git log --all -- <path>`
+ * returns a commit) OR it is present on disk. This is deliberately broad to
+ * avoid the cited-path-only false "absent" verdict.
+ */
+function fileKnownToRepo(repoPath) {
+  const p = normalizeRepoPath(repoPath);
+  if (!p) return false;
+  // On disk now?
+  try {
+    if (fs.existsSync(path.join(TRUTH_GATE_REPO, p))) return true;
+  } catch (_) { /* fall through to history */ }
+  // Tracked anywhere in history (whole-repo locator, never cited-path-only)?
+  const log = git(['log', '--all', '--oneline', '-1', '--', p], { allowFail: true });
+  return Boolean(log && log.length > 0);
+}
+
+/** Does the file exist on disk in the work tree right now? */
+function fileOnDisk(repoPath) {
+  const p = normalizeRepoPath(repoPath);
+  if (!p) return false;
+  try { return fs.existsSync(path.join(TRUTH_GATE_REPO, p)); } catch { return false; }
+}
+
+let _isMachineArtifact = null;
+/** Lazy-load the fused primitive's artifact discriminator (ESM from CJS).
+ * Uses a file:// URL so the dynamic import works on Windows absolute paths. */
+async function loadIsMachineArtifact() {
+  if (_isMachineArtifact) return _isMachineArtifact;
+  const { pathToFileURL } = require('url');
+  const libPath = path.join(__dirname, 'lib', 'run-evidence-gate.mjs');
+  const mod = await import(pathToFileURL(libPath).href);
+  _isMachineArtifact = mod.isMachineArtifact;
+  return _isMachineArtifact;
+}
+
+/**
+ * Layer-2 verification of a `done` close against the real repo. Throws (caught
+ * by verifyDone → block) on any internal error so the gate is FAIL-CLOSED:
+ * an inability to verify is a DENY, never a silent pass.
+ *
+ * @param statusCall parsed update_work_item_status args (has .id, .actorSessionId)
+ * @param item       the work_items row (has implementation_report)
+ * @param capturedShas Set<string> of FULL L1-captured SHAs for this item/session
+ */
+async function verifyLayer2(statusCall, item, capturedShas) {
+  const post = item.implementation_report && item.implementation_report.codeflow_post;
+  if (!post || typeof post !== 'object') {
+    deny('L2: done rejected — implementation_report.codeflow_post is missing or not an object.', statusCall);
+  }
+
+  // (5) Witness allow-list — the doer cannot self-witness (D5 / SLSA).
+  const witness = String(post.witness || '').trim();
+  if (!WITNESS_ALLOWLIST.has(witness)) {
+    deny(
+      'L2: done rejected — codeflow_post.witness must be one of {validator-rerun, ci, human-review}; got "' +
+      (witness || '<missing>') + '". ' +
+      'The party that did the work cannot sign its own provenance (witness:"agent" is never accepted).',
+      { ...statusCall, witness },
+    );
+  }
+
+  // (1) Commit resolves (FULL SHA) AND was captured by L1 for this item/session.
+  const claimedCommit = post.commit;
+  const fullSha = resolveFullSha(claimedCommit);
+  if (!fullSha) {
+    deny(
+      'L2: done rejected — codeflow_post.commit ("' + (claimedCommit || '<missing>') +
+      '") does not resolve to a real commit (git cat-file/rev-parse). Free-typed or wrong SHAs are rejected.',
+      { ...statusCall, claimedCommit },
+    );
+  }
+  if (!capturedShas.has(fullSha)) {
+    deny(
+      'L2: done rejected — commit ' + fullSha + ' was not captured by Layer 1 for this work item + originating session. ' +
+      'The exit gate only accepts a commit SHA the commit-hook recorded against this item (no agent-asserted SHAs). ' +
+      'Captured SHAs for this item/session: ' + (capturedShas.size ? [...capturedShas].join(', ') : '(none)') + '.',
+      { ...statusCall, fullSha, capturedCount: capturedShas.size },
+    );
+  }
+
+  // (2)/(3) Every files_changed entry is in the commit AND exists on disk.
+  const filesChanged = Array.isArray(post.files_changed) ? post.files_changed : [];
+  if (filesChanged.length === 0) {
+    deny('L2: done rejected — codeflow_post.files_changed is empty; a closure must name the files it changed.', statusCall);
+  }
+  const commitFiles = filesInCommit(fullSha);
+  if (commitFiles == null) {
+    deny('L2: done rejected — could not read the file list of commit ' + fullSha + ' (git show failed).', statusCall);
+  }
+  for (const raw of filesChanged) {
+    const p = normalizeRepoPath(raw);
+    if (!p) {
+      deny('L2: done rejected — a files_changed entry is empty/blank.', { ...statusCall, raw });
+    }
+    // In the commit? (whole-repo lookup is implicit — commitFiles is the full
+    // name-only set of the resolved commit, not a cited-path filter.)
+    if (!commitFiles.has(p)) {
+      deny(
+        'L2: done rejected — file "' + p + '" is NOT among the files changed by commit ' + fullSha +
+        ' (git show --stat). files_changed must match the commit\'s actual contents.',
+        { ...statusCall, file: p, fullSha },
+      );
+    }
+    // On disk now?
+    if (!fileOnDisk(p)) {
+      deny(
+        'L2: done rejected — claimed file "' + p + '" does not exist on disk in the work tree. ' +
+        'A deliverable that is not present is not done.',
+        { ...statusCall, file: p },
+      );
+    }
+    // Whole-repo sanity (defense in depth; should always hold if on disk).
+    if (!fileKnownToRepo(p)) {
+      deny(
+        'L2: done rejected — claimed file "' + p + '" is unknown to the repo (not on disk and not in history).',
+        { ...statusCall, file: p },
+      );
+    }
+  }
+
+  // (4) Every verification entry is a machine-parseable artifact, not prose.
+  const isMachineArtifact = await loadIsMachineArtifact();
+  const verifications = Array.isArray(post.verification) ? post.verification : [];
+  if (verifications.length === 0) {
+    deny('L2: done rejected — codeflow_post.verification is empty; closure needs a captured verification artifact.', statusCall);
+  }
+  for (const v of verifications) {
+    if (!isMachineArtifact(v)) {
+      const shown = typeof v === 'string' ? v.slice(0, 60) : JSON.stringify(v).slice(0, 80);
+      deny(
+        'L2: done rejected — verification entry is prose/proxy, not a captured artifact: "' + shown + '". ' +
+        'Each verification must be a run-evidence-gate result or a machine shape ' +
+        '({exit_code|http_status|rowcount|passed/total}). Strings like "HTTP 200" / "works" are rejected.',
+        { ...statusCall, verification: shown },
+      );
+    }
+  }
+  // No denial thrown => Layer-2 verification PASSED.
+}
+
 async function verifyDone(statusCall, blob) {
   if (!statusCall.id) block('`update_work_item_status(..., done)` must include a work item UUID.', statusCall);
   if (!statusCall.actorSessionId || !statusCall.actorRole) {
@@ -222,9 +441,11 @@ async function verifyDone(statusCall, blob) {
 
   let rows;
   let events;
+  let capturedRows;
   try {
-    rows = await supabaseGet(`work_items?id=eq.${encodeURIComponent(statusCall.id)}&select=id,status,item_type,implementation_report,checklist`);
+    rows = await supabaseGet(`work_items?id=eq.${encodeURIComponent(statusCall.id)}&select=id,status,item_type,session_id,implementation_report,checklist`);
     events = await supabaseGet(`work_item_checklist_events?work_item_id=eq.${encodeURIComponent(statusCall.id)}&select=item_id,checked,actor_session_id,actor_role,created_at&order=created_at.desc&limit=200`);
+    capturedRows = await supabaseGet(`work_item_commits?work_item_id=eq.${encodeURIComponent(statusCall.id)}&select=sha,session_id`);
   } catch (e) {
     block(`Cannot live-verify work item exit gate: ${e.message}. Do not close the item until clauth/Supabase verification is available.`, statusCall);
   }
@@ -256,6 +477,27 @@ async function verifyDone(statusCall, blob) {
       { ...statusCall, supervisorReticks: supervisorReticks.map((e) => e.item_id) },
     );
   }
+
+  // --- Truth Gate 3.0 Layer 2 — FUSED evidence gate (freeze-the-leak) ---------
+  // The L1-captured SHA set is restricted to the item's ORIGINATING session
+  // (the session that ticked the checklist) so a SHA captured by some other
+  // session against this item cannot launder a fabricated close.
+  const originatingSession = item.session_id || null;
+  const capturedShas = new Set(
+    (Array.isArray(capturedRows) ? capturedRows : [])
+      .filter((r) => !originatingSession || r.session_id === originatingSession)
+      .map((r) => String(r.sha || '').toLowerCase())
+      .filter((s) => FULL_SHA_RE.test(s)),
+  );
+  try {
+    await verifyLayer2(statusCall, item, capturedShas);
+  } catch (e) {
+    if (e instanceof GateDenied) {
+      block(e.reason, e.details);     // translate the L2 denial into a hard block
+    }
+    // Any OTHER error during L2 is an inability to verify => FAIL-CLOSED.
+    block('L2: done rejected — Layer-2 verification could not complete (' + (e && e.message ? e.message : String(e)) + '). Fail-closed: not closing.', statusCall);
+  }
 }
 
 function validateTick(tick, rawTool) {
@@ -294,4 +536,20 @@ async function main() {
   pass({ status });
 }
 
-main().catch((e) => block(`Exit gate crashed: ${e.message}`));
+// Run as a hook; export the Layer-2 internals when required by a test.
+if (require.main === module) {
+  main().catch((e) => block(`Exit gate crashed: ${e.message}`));
+} else {
+  module.exports = {
+    GateDenied,
+    deny,
+    verifyLayer2,
+    resolveFullSha,
+    filesInCommit,
+    fileOnDisk,
+    fileKnownToRepo,
+    normalizeRepoPath,
+    loadIsMachineArtifact,
+    WITNESS_ALLOWLIST,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/rdc-skills",
-  "version": "0.24.0",
+  "version": "0.24.2",
   "description": "RDC typed-agent dispatch skill suite for Claude Code - plan, build, review, overnight builds",
   "keywords": [
     "claude-code",
@@ -34,6 +34,7 @@
     "validate": "node tests/validate-skills.js",
     "rdc-design": "node scripts/rdc-design-cli.mjs",
     "test:hooks": "node scripts/test-rdc-hooks.mjs",
+    "test:truth-gate": "node tests/run-evidence-gate.test.mjs && node tests/work-item-exit-gate-l2.test.mjs && node tests/require-work-item-on-commit.test.mjs",
     "test:mcp": "node tests/mcp.test.mjs",
     "test:mcp:remote": "node tests/mcp.test.mjs --remote",
     "mcp": "node bin/rdc-skills-mcp.mjs",

package/scripts/install-rdc-skills.js

@@ -696,9 +696,14 @@ function buildHooksConfig(hooksDir, profile = 'core') {
         cmd('require-work-item-on-commit.js'),
       ]},
     ],
-    PostToolUse: [{ hooks: [
-      cmd('check-services.js'),
-    ]}],
+    PostToolUse: [
+      { hooks: [
+        cmd('check-services.js'),
+      ]},
+      { matcher: 'Bash', hooks: [
+        cmd('require-work-item-on-commit.js', 'Capturing commit SHA for work item...'),
+      ]},
+    ],
     Stop: [{ hooks: [
       cmd('rdc-output-contract-gate.js', 'Checking RDC output contract...'),
       cmd('post-work-check.js',    'Checking for undocumented work...'),

package/skills/build/SKILL.md

@@ -288,6 +288,16 @@ Read the task title and description, then:
    Without `max_turns: 70`, agents hit the default turn cap mid-task and stop.
    `isolation: "worktree"` gives each agent its own git worktree and branch — eliminates push race conditions and index lock contention when multiple agents commit in parallel. The supervisor merges worktree branches after each wave (Step 9).
 
+   ### ✅ PREVENTION FIRST — create worktrees fresh off origin/develop (kills stale-base by construction)
+   The repeated stale-base failures below come from creating worktrees off a
+   local/old ref. Eliminate the failure mode at the source: ALWAYS create agent
+   worktrees with a fresh fetch + `origin/develop` base, e.g.
+   `git fetch origin develop && git worktree add <dir> -b <branch> origin/develop`
+   — or use the canonical launcher `node scripts/wt.mjs add <name>`, which does
+   exactly that. A worktree cut from `origin/develop` HEAD **cannot** be stale.
+   The HARD GATE below remains as the blocking backstop (detection), but
+   construction-from-`origin/develop` is the primary defense.
+
    ### ⛔ HARD GATE — Worktree base MUST equal develop HEAD (blocking, not advisory)
    The worktree-isolation harness has shipped worktrees pinned to a STALE base
    commit (lessons 2026-06-10-build-worktree-stale-base, 2026-06-11-build-worktree-stale-base,

package/tests/require-work-item-on-commit.test.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * Truth Gate L1 — commit-capture hook tests.
+ *
+ * Proves:
+ *   1. parse: the work-item UUID is extracted from a commit message; absent UUID -> null.
+ *   2. capture: on a PostToolUse(git commit), the captured `sha` EQUALS the real
+ *      `git rev-parse HEAD` of the repo (verified against a throwaway git repo,
+ *      via the RDC_COMMIT_CAPTURE_SINK file — no live DB required).
+ *   3. no-item: capture NO-OPs (writes nothing) when the commit message carries
+ *      no work-item UUID. No orphan row.
+ *
+ * Run: node tests/require-work-item-on-commit.test.mjs   (or `node --test tests/`)
+ */
+import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync, execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, '..');
+const HOOK = join(REPO_ROOT, 'hooks', 'require-work-item-on-commit.js');
+
+const require = createRequire(import.meta.url);
+const failures = [];
+function assert(name, condition, detail = '') {
+  if (!condition) failures.push(`${name}${detail ? `: ${detail}` : ''}`);
+}
+
+// ---------------------------------------------------------------------------
+// 1. Pure parse assertions
+// ---------------------------------------------------------------------------
+const hook = require(HOOK);
+const WI = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee';
+
+assert('parse: extracts UUID from message',
+  hook.parseCommitMessageWorkItem(`feat(x): do thing for ${WI}`) === WI);
+assert('parse: null when no UUID',
+  hook.parseCommitMessageWorkItem('feat(x): no work item here') === null);
+assert('isGitCommit: true for real commit',
+  hook.isGitCommit('git commit -m "feat: x"') === true);
+assert('isGitCommit: false for --help',
+  hook.isGitCommit('git commit --help') === false);
+assert('isGitCommit: false for unrelated',
+  hook.isGitCommit('git status') === false);
+assert('commitSucceeded: false on nothing-to-commit',
+  hook.commitSucceeded({ stdout: 'nothing to commit, working tree clean' }) === false);
+assert('commitSucceeded: true on exit 0',
+  hook.commitSucceeded({ exit_code: 0 }) === true);
+
+// ---------------------------------------------------------------------------
+// helper: build a throwaway git repo with one commit
+// ---------------------------------------------------------------------------
+function makeRepo() {
+  const dir = mkdtempSync(join(tmpdir(), 'wic-repo-'));
+  const g = (...args) => execFileSync('git', args, { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  g('init', '-q');
+  g('config', 'user.email', 'test@example.com');
+  g('config', 'user.name', 'Test');
+  writeFileSync(join(dir, 'f.txt'), 'hello\n');
+  g('add', 'f.txt');
+  g('commit', '-q', '-m', `feat: seed for ${WI}`);
+  const head = g('rev-parse', 'HEAD').trim();
+  return { dir, head };
+}
+
+function runHook(payload, extraEnv = {}) {
+  return spawnSync(process.execPath, [HOOK], {
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+    env: { ...process.env, ...extraEnv },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 2. Capture: sha == git rev-parse HEAD
+// ---------------------------------------------------------------------------
+{
+  const { dir, head } = makeRepo();
+  const sink = join(dir, 'sink.jsonl');
+  // Point Supabase at an unreachable host so the test never touches a real DB;
+  // capture still writes the sink, which is what we assert on.
+  const res = runHook({
+    hook_event_name: 'PostToolUse',
+    tool_name: 'Bash',
+    session_id: 'sess-capture-1',
+    cwd: dir,
+    tool_input: { command: `git commit -m "feat: thing for ${WI}"` },
+    tool_response: { exit_code: 0, stdout: '1 file changed' },
+  }, {
+    RDC_COMMIT_CAPTURE_SINK: sink,
+    SUPABASE_URL: 'http://127.0.0.1:9',     // unreachable -> DB insert fails fast, capture still records sink
+    SUPABASE_SERVICE_ROLE_KEY: 'test-key-not-real',
+  });
+  assert('capture: hook exits zero', res.status === 0, res.stderr);
+  assert('capture: sink written', existsSync(sink), 'no sink file');
+  if (existsSync(sink)) {
+    const row = JSON.parse(readFileSync(sink, 'utf8').trim().split('\n')[0]);
+    assert('capture: sha equals real HEAD', row.sha === head, `${row.sha} !== ${head}`);
+    assert('capture: work_item_id parsed', row.work_item_id === WI, row.work_item_id);
+    assert('capture: session_id recorded', row.session_id === 'sess-capture-1', row.session_id);
+  }
+  rmSync(dir, { recursive: true, force: true });
+}
+
+// ---------------------------------------------------------------------------
+// 3. No active work item -> NO-OP (no sink row)
+// ---------------------------------------------------------------------------
+{
+  const { dir } = makeRepo();
+  const sink = join(dir, 'sink.jsonl');
+  const res = runHook({
+    hook_event_name: 'PostToolUse',
+    tool_name: 'Bash',
+    session_id: 'sess-no-item',
+    cwd: dir,
+    tool_input: { command: 'git commit -m "feat: no work item ref"' },
+    tool_response: { exit_code: 0 },
+  }, { RDC_COMMIT_CAPTURE_SINK: sink });
+  assert('no-item: hook exits zero', res.status === 0, res.stderr);
+  assert('no-item: no sink row written', !existsSync(sink), 'orphan capture written for no-item commit');
+  rmSync(dir, { recursive: true, force: true });
+}
+
+// ---------------------------------------------------------------------------
+// 4. PreToolUse legacy behavior preserved (warn-only, never blocks)
+// ---------------------------------------------------------------------------
+{
+  const res = runHook({
+    hook_event_name: 'PreToolUse',
+    tool_name: 'Bash',
+    tool_input: { command: 'git commit -m "no convention and no uuid"' },
+  });
+  assert('pre: warn exits zero (never blocks)', res.status === 0, res.stderr);
+  assert('pre: emits warn systemMessage', /no work item reference/.test(res.stdout), res.stdout);
+
+  const ok = runHook({
+    hook_event_name: 'PreToolUse',
+    tool_name: 'Bash',
+    tool_input: { command: 'git commit -m "feat(x): conventional"' },
+  });
+  assert('pre: conventional passes silently', ok.status === 0 && ok.stdout.trim() === '', ok.stdout);
+}
+
+// ---------------------------------------------------------------------------
+if (failures.length > 0) {
+  console.error('\ncommit-capture hook tests — FAIL\n');
+  for (const f of failures) console.error(`  - ${f}`);
+  process.exit(1);
+}
+console.log('commit-capture hook tests — PASS');

package/tests/run-evidence-gate.test.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * Truth Gate 3.0 — fused run-evidence-gate primitive tests.
+ *
+ * Proves the Nidus property: evidence cannot exist without a run.
+ *   - a verdict is emitted ONLY after the command runs (no run => no pass).
+ *   - the output hash is server-side and derived from the actual run.
+ *   - isMachineArtifact rejects prose and accepts captured machine shapes.
+ *
+ * Run: node tests/run-evidence-gate.test.mjs
+ */
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const LIB = pathToFileURL(join(resolve(__dirname, '..'), 'hooks', 'lib', 'run-evidence-gate.mjs')).href;
+const { runEvidenceGate, isMachineArtifact, hashOutput, EVIDENCE_KIND } = await import(LIB);
+
+const failures = [];
+function assert(name, cond, detail = '') {
+  if (!cond) failures.push(`${name}${detail ? `: ${detail}` : ''}`);
+  else process.stdout.write(`  ok  ${name}\n`);
+}
+
+// --- 1. A passing run produces verdict:'pass' WITH a hash, only after running.
+let ranCount = 0;
+const passArt = runEvidenceGate(
+  { command: 'noop', args: ['x'], label: 'unit-pass' },
+  () => { ranCount += 1; return { status: 0, stdout: 'ok', stderr: '' }; },
+);
+assert('runner invoked exactly once', ranCount === 1, String(ranCount));
+assert('pass: kind stamped', passArt.kind === EVIDENCE_KIND);
+assert('pass: ran=true', passArt.ran === true);
+assert('pass: verdict=pass', passArt.verdict === 'pass', passArt.verdict);
+assert('pass: output_sha256 present', typeof passArt.output_sha256 === 'string' && passArt.output_sha256.length === 64, passArt.output_sha256);
+
+// --- 2. A failing run -> verdict:'fail', never silently pass.
+const failArt = runEvidenceGate(
+  { command: 'noop' },
+  () => ({ status: 7, stdout: '', stderr: 'boom' }),
+);
+assert('fail: verdict=fail', failArt.verdict === 'fail', failArt.verdict);
+assert('fail: exit_code preserved', failArt.exit_code === 7, String(failArt.exit_code));
+
+// --- 3. NO RUN -> NO verdict (fail-closed). Invalid spec.
+const noCmd = runEvidenceGate({});
+assert('no-command: ran=false', noCmd.ran === false);
+assert('no-command: verdict=error (never pass)', noCmd.verdict === 'error', noCmd.verdict);
+
+// --- 4. Runner that yields no exit status -> cannot have run -> error.
+const noStatus = runEvidenceGate({ command: 'noop' }, () => ({ status: null, stdout: '', stderr: '' }));
+assert('no-status: ran=false', noStatus.ran === false);
+assert('no-status: verdict=error', noStatus.verdict === 'error', noStatus.verdict);
+
+// --- 5. Runner throws -> fail-closed error, never pass.
+const threw = runEvidenceGate({ command: 'noop' }, () => { throw new Error('spawn failed'); });
+assert('runner-throws: ran=false', threw.ran === false);
+assert('runner-throws: verdict=error', threw.verdict === 'error', threw.verdict);
+
+// --- 6. Hash is deterministic + derived from the captured combined output.
+assert('hash deterministic', hashOutput('abc') === hashOutput('abc'));
+assert('hash differs by content', hashOutput('abc') !== hashOutput('abd'));
+
+// --- 7. isMachineArtifact discrimination.
+assert('reject bare prose "HTTP 200"', isMachineArtifact('HTTP 200') === false);
+assert('reject bare prose "works"', isMachineArtifact('works') === false);
+assert('reject "107 nodes"', isMachineArtifact('107 nodes') === false);
+assert('accept fused artifact', isMachineArtifact(passArt) === true);
+assert('accept {exit_code}', isMachineArtifact({ exit_code: 0 }) === true);
+assert('accept {http_status}', isMachineArtifact({ http_status: 200 }) === true);
+assert('accept {rowcount}', isMachineArtifact({ rowcount: 12 }) === true);
+assert('accept {passed,total}', isMachineArtifact({ passed: 5, total: 5 }) === true);
+assert('accept JSON string of machine shape', isMachineArtifact('{"exit_code":0}') === true);
+assert('reject plain object', isMachineArtifact({ note: 'done' }) === false);
+assert('reject null', isMachineArtifact(null) === false);
+
+if (failures.length > 0) {
+  console.error('\nrun-evidence-gate tests — FAIL\n');
+  for (const f of failures) console.error(`  - ${f}`);
+  process.exit(1);
+}
+console.log('\nrun-evidence-gate tests — PASS');