@lifeaitools/rdc-skills 0.24.5 → 0.24.7

package/git-sha.json

@@ -1,3 +1,3 @@
 {
-  "sha": "c8a28f6d5c90e94b2e2429b40ffb2752eda66887"
+  "sha": "2fc0a320523abba6b5a122094627eb9c4e2e980d"
 }

package/hooks/gate-watchdog-selfcheck.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+/**
+ * gate-watchdog-selfcheck.js — Truth Gate 3.0 Layer 6 (gate watchdog).
+ *
+ * Registered on `SessionStart`. Per the Claude Code hooks reference,
+ * `SessionStart` CANNOT block — so this watchdog is ADVISORY: it prints a loud
+ * STOP-banner (like the existing agent-startup guard) when a Truth-Gate
+ * component is missing or unregistered, but it always exits 0. A disabled or
+ * absent gate is the ultimate bypass (R4); this watchdog surfaces that the
+ * moment a session starts, before any work trusts the gate chain.
+ *
+ * It asserts three things are present + registered:
+ *   1. work-item-exit-gate.js  — exists in the installed rdc-skills hooks AND is
+ *      referenced by a registered hook command (PreToolUse).
+ *   2. truth-gate.mjs          — exists in the repo's .claude/hooks AND is
+ *      registered on Stop and SubagentStop in .claude/settings.json.
+ *   3. the LIVE hookify plugin hooks.json — the plugin's OWN hooks manifest under
+ *      ~/.claude/plugins/cache/.../hookify/<hash>/hooks/hooks.json.
+ *      ⛔ It deliberately does NOT trust the dead ~/.claude/hooks/hookify-*.js
+ *      wrappers — those point at an ORPHANED cache hash and are not the live
+ *      enforcement path. The watchdog resolves the live manifest and (when both
+ *      exist) warns if the dead wrappers point at a cache hash that differs from
+ *      the live one (the exact drift that silently disables hookify).
+ *
+ * Test seam: the pure decision is `evaluateWatchdog(facts)` where `facts` is a
+ * plain object of booleans/paths gathered by the side-effecting probes. The
+ * banner text is produced by `renderBanner(findings)`. Both are exported and
+ * have no filesystem/process dependency, so the missing-gate banner and the
+ * all-present silent path are provable offline.
+ */
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const REPO_ROOT = process.env.RDC_TRUTH_GATE_REPO || 'C:/Dev/regen-root';
+const HOOKS_DIR = __dirname; // installed rdc-skills hooks dir (where this file lives)
+
+function readJsonSafe(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) { return null; }
+}
+
+/** Serialize all hook command strings in a settings.json hooks object. */
+function settingsCommandText(settings) {
+  if (!settings || !settings.hooks || typeof settings.hooks !== 'object') return '';
+  const parts = [];
+  for (const event of Object.keys(settings.hooks)) {
+    const groups = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
+    for (const g of groups) {
+      for (const h of Array.isArray(g.hooks) ? g.hooks : []) {
+        if (h && typeof h.command === 'string') parts.push(`${event}::${h.command}`);
+      }
+    }
+  }
+  return parts.join('\n');
+}
+
+/** Is a hook command referenced for the given event in the serialized text? */
+function registeredForEvent(commandText, event, needle) {
+  return commandText.split('\n').some((line) => line.startsWith(`${event}::`) && line.includes(needle));
+}
+
+/**
+ * Locate the LIVE hookify plugin hooks.json under the plugins cache. Returns the
+ * resolved manifest path (the plugin's OWN hooks/hooks.json), or null. NEVER
+ * returns one of the dead ~/.claude/hooks/hookify-*.js wrappers.
+ */
+function findLiveHookifyManifest(home) {
+  const cacheRoot = path.join(home, '.claude', 'plugins', 'cache');
+  const found = [];
+  const walk = (dir, depth) => {
+    if (depth > 6) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        walk(full, depth + 1);
+      } else if (e.isFile() && e.name === 'hooks.json' && /hookify/i.test(full)) {
+        found.push(full);
+      }
+    }
+  };
+  walk(cacheRoot, 0);
+  return found.length > 0 ? found[0] : null;
+}
+
+/** Read the cache-hash a dead hookify wrapper points at (its PLUGIN_ROOT). null if none. */
+function deadWrapperPluginRoot(home) {
+  const wrapper = path.join(home, '.claude', 'hooks', 'hookify-stop.js');
+  try {
+    const src = fs.readFileSync(wrapper, 'utf8');
+    const m = src.match(/PLUGIN_ROOT\s*=\s*['"]([^'"]+)['"]/);
+    return m ? m[1] : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Gather the watchdog facts via side-effecting probes. Returns a plain facts
+ * object consumed by the pure evaluator. Kept separate from evaluateWatchdog so
+ * the decision logic is unit-testable without a filesystem.
+ */
+function gatherFacts({ home = os.homedir(), repoRoot = REPO_ROOT, hooksDir = HOOKS_DIR } = {}) {
+  const exitGatePath = path.join(hooksDir, 'work-item-exit-gate.js');
+  const truthGatePath = path.join(repoRoot, '.claude', 'hooks', 'truth-gate.mjs');
+  const settingsPath = path.join(repoRoot, '.claude', 'settings.json');
+  const settings = readJsonSafe(settingsPath);
+  const commandText = settingsCommandText(settings);
+
+  const liveHookifyManifest = findLiveHookifyManifest(home);
+  const deadRoot = deadWrapperPluginRoot(home);
+  // The live manifest's plugin-root dir (the parent of /hooks/hooks.json).
+  const liveRoot = liveHookifyManifest
+    ? path.dirname(path.dirname(liveHookifyManifest))
+    : null;
+
+  return {
+    exitGateFileExists: fs.existsSync(exitGatePath),
+    exitGateRegistered: registeredForEvent(commandText, 'PreToolUse', 'work-item-exit-gate.js'),
+    truthGateFileExists: fs.existsSync(truthGatePath),
+    truthGateOnStop: registeredForEvent(commandText, 'Stop', 'truth-gate.mjs'),
+    truthGateOnSubagentStop: registeredForEvent(commandText, 'SubagentStop', 'truth-gate.mjs'),
+    liveHookifyManifestExists: Boolean(liveHookifyManifest),
+    liveHookifyManifestPath: liveHookifyManifest,
+    // Drift: a dead wrapper that points at a different cache hash than the live one.
+    deadWrapperRoot: deadRoot,
+    liveHookifyRoot: liveRoot,
+    deadWrapperPointsAtStaleCache: Boolean(
+      deadRoot && liveRoot &&
+      path.normalize(deadRoot).toLowerCase() !== path.normalize(liveRoot).toLowerCase(),
+    ),
+    // paths for the banner / log
+    exitGatePath,
+    truthGatePath,
+    settingsPath,
+  };
+}
+
+/**
+ * Pure decision over the gathered facts. Returns an array of finding strings
+ * (empty = all gates healthy). The live hookify check is explicitly the PLUGIN
+ * manifest, not the dead wrappers.
+ */
+function evaluateWatchdog(facts = {}) {
+  const findings = [];
+  if (!facts.exitGateFileExists) {
+    findings.push(`work-item-exit-gate.js is MISSING from the installed hooks (${facts.exitGatePath || '?'}).`);
+  }
+  if (!facts.exitGateRegistered) {
+    findings.push('work-item-exit-gate.js is NOT registered on a PreToolUse hook in .claude/settings.json.');
+  }
+  if (!facts.truthGateFileExists) {
+    findings.push(`truth-gate.mjs is MISSING from the repo (${facts.truthGatePath || '?'}).`);
+  }
+  if (!facts.truthGateOnStop) {
+    findings.push('truth-gate.mjs is NOT registered on the Stop event in .claude/settings.json.');
+  }
+  if (!facts.truthGateOnSubagentStop) {
+    findings.push('truth-gate.mjs is NOT registered on the SubagentStop event in .claude/settings.json.');
+  }
+  if (!facts.liveHookifyManifestExists) {
+    findings.push(
+      'The LIVE hookify plugin hooks.json could not be found under ~/.claude/plugins/cache/**/hookify/**/hooks/hooks.json. ' +
+      'Hookify enforcement may be disabled. (The dead ~/.claude/hooks/hookify-*.js wrappers are NOT the live path and are not trusted here.)',
+    );
+  }
+  if (facts.deadWrapperPointsAtStaleCache) {
+    findings.push(
+      `The dead ~/.claude/hooks/hookify-*.js wrappers point at an ORPHANED cache hash (${facts.deadWrapperRoot}) ` +
+      `that differs from the live plugin (${facts.liveHookifyRoot}). The wrappers are stale; the live plugin manifest is authoritative.`,
+    );
+  }
+  return findings;
+}
+
+/** Render the loud STOP-banner from findings. Empty findings → empty string. */
+function renderBanner(findings) {
+  if (!Array.isArray(findings) || findings.length === 0) return '';
+  const lines = findings.map((f) => `  ⛔ ${f}`).join('\n');
+  return (
+    '\n' +
+    '════════════════════════════════════════════════════════════════════════\n' +
+    '⛔⛔  TRUTH GATE WATCHDOG — A GATE IS MISSING OR UNREGISTERED  ⛔⛔\n' +
+    '════════════════════════════════════════════════════════════════════════\n' +
+    'The Truth Gate enforcement chain is INCOMPLETE for this session. A disabled\n' +
+    'or unregistered gate is the ultimate closure bypass. Findings:\n\n' +
+    lines + '\n\n' +
+    'Repair before trusting any work-item closure this session:\n' +
+    '  node C:/Dev/rdc-skills/scripts/install-rdc-skills.js   (reinstall the hooks)\n' +
+    '  then verify .claude/settings.json registers truth-gate.mjs on Stop+SubagentStop\n' +
+    '  and work-item-exit-gate.js on PreToolUse.\n' +
+    '════════════════════════════════════════════════════════════════════════\n'
+  );
+}
+
+function main() {
+  // Drain stdin if present (SessionStart delivers JSON); we don't need its body.
+  try {
+    const chunks = [];
+    process.stdin.on('data', (c) => chunks.push(c));
+    process.stdin.on('end', () => finish());
+    process.stdin.resume();
+    // If no stdin arrives quickly, finish anyway (SessionStart may pass nothing).
+    setTimeout(finish, 1500);
+  } catch (_) {
+    finish();
+  }
+}
+
+let _finished = false;
+function finish() {
+  if (_finished) return;
+  _finished = true;
+  let findings = [];
+  try {
+    findings = evaluateWatchdog(gatherFacts());
+  } catch (e) {
+    // Even the watchdog crashing must not block the session — advisory only.
+    findings = [`gate-watchdog self-check crashed: ${e && e.message ? e.message : String(e)}`];
+  }
+  const banner = renderBanner(findings);
+  if (banner) {
+    // SessionStart context output via systemMessage; also emit to stderr so it
+    // is visible like the agent-startup guard. ADVISORY — always exit 0.
+    process.stdout.write(JSON.stringify({ systemMessage: banner }));
+    process.stderr.write(banner);
+  }
+  process.exit(0); // SessionStart cannot block — never exit non-zero.
+}
+
+if (require.main === module) {
+  main();
+} else {
+  module.exports = {
+    evaluateWatchdog,
+    renderBanner,
+    gatherFacts,
+    findLiveHookifyManifest,
+    settingsCommandText,
+    registeredForEvent,
+  };
+}

package/hooks/post-tool-batch-gate.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/**
+ * post-tool-batch-gate.js — Truth Gate 3.0 Layer 5 (per-wave batch gate).
+ *
+ * Registered on the `PostToolBatch` event — it fires after a full batch of
+ * parallel tool calls resolves, BEFORE the next model call. Per the Claude Code
+ * hooks reference, `PostToolBatch` CAN block (exit code 2 stops the agentic
+ * loop). After a parallel build wave (multiple Agent dispatches into isolated
+ * worktrees), this gate asserts the wave's worktree bases are sane — every agent
+ * worktree must be based on the current `develop` HEAD — so a stale-base wave
+ * cannot feed fabricated/diverged closures into the next model turn.
+ *
+ * ⛔ FLAG-GATED, DEFAULT OFF. Until the flag is flipped at deploy this hook is a
+ * pure no-op (exit 0) so the in-flight build session is NOT disrupted. When the
+ * flag is ON it is FAIL-CLOSED: an inability to confirm worktree-base sanity is
+ * a BLOCK, never a silent pass.
+ *
+ * Flag (default OFF):
+ *   - env RDC_TRUTHGATE_POSTTOOLBATCH in {1,true,on,yes}.
+ *
+ * Worktree-base sanity, per worktree:
+ *   - resolve develop HEAD: `git rev-parse refs/heads/develop` in the main repo.
+ *   - for each linked worktree (`git worktree list --porcelain`), its base must
+ *     equal develop HEAD — i.e. develop is an ancestor of the worktree HEAD
+ *     (`git merge-base --is-ancestor <developHead> <worktreeHead>`), OR the
+ *     worktree HEAD already IS develop HEAD. A worktree whose base predates the
+ *     current develop HEAD is STALE and the wave is flagged.
+ *
+ * Test seam: inject the git surface via the exported pure `evaluateWave({
+ * developHead, worktrees, isAncestor })`, where `worktrees` is
+ * [{ path, head }] and `isAncestor(a,b)` returns whether a is an ancestor of b.
+ * The pure evaluator has no process/network dependency, so the flag-OFF no-op
+ * and the stale-base FLAG branches are provable offline.
+ */
+'use strict';
+
+const { execFileSync } = require('child_process');
+const hookLog = require('./hook-logger');
+
+const FULL_SHA_RE = /^[0-9a-f]{40}$/i;
+const MAIN_REPO = process.env.RDC_TRUTH_GATE_REPO || 'C:/Dev/regen-root';
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let input = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { input += chunk; });
+    process.stdin.on('end', () => resolve(input));
+    process.stdin.resume();
+  });
+}
+
+/** Block the batch with exit code 2 (the blocking semantics for PostToolBatch). */
+function block(reason, details = {}) {
+  hookLog('post-tool-batch-gate', 'PostToolBatch', 'block', { reason, ...details });
+  process.stdout.write(JSON.stringify({
+    decision: 'block',
+    reason: `BUILD WAVE FLAGGED — Truth Gate Layer 5 (PostToolBatch).\n\n${reason}`,
+  }));
+  process.stderr.write(`BUILD WAVE FLAGGED: ${reason}\n`);
+  process.exit(2);
+}
+
+function pass(details = {}) {
+  hookLog('post-tool-batch-gate', 'PostToolBatch', 'pass', details);
+  process.exit(0);
+}
+
+/** Default OFF. Only the env switch enables it (test-stable, deploy-flippable). */
+function flagEnabledEnv() {
+  const v = String(process.env.RDC_TRUTHGATE_POSTTOOLBATCH || '').trim().toLowerCase();
+  return v === '1' || v === 'true' || v === 'on' || v === 'yes';
+}
+
+function git(args, { cwd = MAIN_REPO, allowFail = false } = {}) {
+  try {
+    return execFileSync('git', args, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      maxBuffer: 8 * 1024 * 1024,
+    }).trim();
+  } catch (e) {
+    if (allowFail) return null;
+    throw e;
+  }
+}
+
+/** Resolve develop's HEAD SHA in the main repo, or null. */
+function developHead() {
+  const sha = git(['rev-parse', '--verify', '--quiet', 'refs/heads/develop'], { allowFail: true });
+  return sha && FULL_SHA_RE.test(sha) ? sha.toLowerCase() : null;
+}
+
+/** Parse `git worktree list --porcelain` into [{ path, head }] (linked only). */
+function listWorktrees() {
+  const out = git(['worktree', 'list', '--porcelain'], { allowFail: true });
+  if (out == null) return null;
+  const worktrees = [];
+  let cur = null;
+  for (const line of out.split('\n')) {
+    if (line.startsWith('worktree ')) {
+      if (cur) worktrees.push(cur);
+      cur = { path: line.slice('worktree '.length).trim(), head: null, bare: false };
+    } else if (line.startsWith('HEAD ')) {
+      if (cur) cur.head = line.slice('HEAD '.length).trim().toLowerCase();
+    } else if (line.trim() === 'bare') {
+      if (cur) cur.bare = true;
+    }
+  }
+  if (cur) worktrees.push(cur);
+  // Linked worktrees only: drop the bare entry and the primary checkout (== MAIN_REPO).
+  const norm = (p) => String(p || '').replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+  const mainNorm = norm(MAIN_REPO);
+  return worktrees.filter((w) => !w.bare && w.head && norm(w.path) !== mainNorm);
+}
+
+/** True when `git merge-base --is-ancestor a b` (a is an ancestor of b). */
+function isAncestor(a, b) {
+  if (!a || !b) return false;
+  if (a === b) return true;
+  // exit 0 = ancestor, exit 1 = not. allowFail captures the non-zero exit.
+  try {
+    execFileSync('git', ['merge-base', '--is-ancestor', a, b], {
+      cwd: MAIN_REPO,
+      stdio: ['ignore', 'ignore', 'ignore'],
+    });
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Pure wave evaluator (unit-testable, no process/network). Returns
+ * { stale: [{ path, head }], ok: boolean }. A worktree is STALE when develop
+ * HEAD is NOT an ancestor of its HEAD (its base predates current develop), and
+ * its HEAD is not develop HEAD itself.
+ *
+ * @param {object} surface
+ * @param {string|null}            surface.developHead  develop HEAD SHA (null → cannot evaluate)
+ * @param {Array<{path,head}>}     surface.worktrees    linked worktrees
+ * @param {(a:string,b:string)=>boolean} surface.isAncestor
+ */
+function evaluateWave({ developHead, worktrees, isAncestor: anc }) {
+  if (!developHead) {
+    return { ok: false, cannotEvaluate: true, stale: [] };
+  }
+  const list = Array.isArray(worktrees) ? worktrees : [];
+  const stale = [];
+  for (const w of list) {
+    if (!w || !w.head) continue;
+    const based = w.head === developHead || anc(developHead, w.head);
+    if (!based) stale.push({ path: w.path, head: w.head });
+  }
+  return { ok: stale.length === 0, cannotEvaluate: false, stale };
+}
+
+async function main() {
+  // Drain stdin (PostToolBatch payload) — we don't need its body, but the event
+  // delivers JSON on stdin and the process should consume it cleanly.
+  try { await readStdin(); } catch (_) {}
+
+  // Default-OFF: a no-op until the flag is flipped at deploy.
+  if (!flagEnabledEnv()) return pass({ reason: 'flag-off' });
+
+  // FAIL-CLOSED from here.
+  const head = developHead();
+  const worktrees = listWorktrees();
+  if (head == null || worktrees == null) {
+    block(
+      `Could not read git state in ${MAIN_REPO} (develop HEAD or worktree list unavailable). ` +
+      `Fail-closed: cannot confirm the build wave's worktree bases are current.`,
+    );
+  }
+
+  const verdict = evaluateWave({ developHead: head, worktrees, isAncestor });
+  if (verdict.cannotEvaluate) {
+    block(`develop HEAD could not be resolved; fail-closed — cannot confirm worktree-base sanity for this wave.`);
+  }
+  if (!verdict.ok) {
+    const lines = verdict.stale.map((s) => `  - ${s.path} @ ${s.head.slice(0, 9)} (base predates develop ${head.slice(0, 9)})`).join('\n');
+    block(
+      `One or more build-wave worktrees are NOT based on the current develop HEAD ${head.slice(0, 9)}:\n${lines}\n\n` +
+      `A wave built on a stale base can feed diverged/fabricated closures into the next turn. ` +
+      `Rebase each worktree onto develop (git fetch && git rebase origin/develop), re-run its verification, then continue.`,
+      { developHead: head, stale: verdict.stale },
+    );
+  }
+
+  pass({ developHead: head, worktreeCount: worktrees.length });
+}
+
+if (require.main === module) {
+  main().catch((e) => block(`post-tool-batch-gate crashed: ${e.message}`));
+} else {
+  module.exports = {
+    flagEnabledEnv,
+    evaluateWave,
+    listWorktrees,
+    developHead,
+  };
+}

package/hooks/task-completed-gate.js

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+/**
+ * task-completed-gate.js — Truth Gate 3.0 Layer 5 (harness completion gate).
+ *
+ * Registered on the `TaskCompleted` event. Per the Claude Code hooks reference,
+ * `TaskCompleted` CAN block (exit code 2 / decision "block" prevents the task
+ * from being marked completed). This hook makes a task completion structurally
+ * dependent on a SOUND work-item closure: a task cannot complete unless the
+ * work item it references is `done` AND that `done` was admitted by Layers 2–3
+ * (the FUSED evidence gate + the validator re-run receipt) — i.e. the work item
+ * carries an HMAC-valid, witnessed `implementation_report.codeflow_post` and is
+ * in status `done`. The exit gate (work-item-exit-gate.js) is what proves
+ * Layers 2–3 at `done` time; this gate refuses to let a TASK finish on a work
+ * item that never reached that sound `done` state.
+ *
+ * ⛔ FLAG-GATED, DEFAULT OFF. Until the flag is flipped at deploy this hook is a
+ * pure no-op (exit 0) so the in-flight build session is NOT disrupted — the
+ * blocking Stop/SubagentStop truth-gate is already live and gating capability
+ * claims; this layer is dormant until activation. When the flag is ON it is
+ * FAIL-CLOSED: an inability to verify a sound closure is a BLOCK, never a pass.
+ *
+ * Flag (default OFF), either enables it:
+ *   - env  RDC_TRUTHGATE_TASKCOMPLETED in {1,true,on,yes}, OR
+ *   - DB   public.truthgate_flags(flag='taskcompleted', enabled=true) — but the
+ *          DB check is OPT-IN: it only runs when RDC_TRUTHGATE_TASKCOMPLETED_DB
+ *          is in {1,true,on,yes}. This keeps the default-OFF path ZERO-COST: an
+ *          unset env flag returns false with NO Supabase/clauth round-trip, so a
+ *          dormant gate never makes a network call on every TaskCompleted.
+ *
+ * Offline test seam: when RDC_TASKCOMPLETED_CLOSURE_SINK points at a JSON file,
+ * the hook reads the closure row from that file instead of Supabase. This lets
+ * the gate be proven without a live DB. The sink shape is a single work_items
+ * row: { id, status, item_type, implementation_report }.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+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 WITNESS_ALLOWLIST = new Set(['validator-rerun', 'ci', 'human-review']);
+const DEFAULT_SUPABASE_URL = 'https://uvojezuorjgqzmhhgluu.supabase.co';
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let input = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { input += chunk; });
+    process.stdin.on('end', () => resolve(input));
+    process.stdin.resume();
+  });
+}
+
+/** Block the TaskCompleted with exit code 2 (the blocking semantics for this event). */
+function block(reason, details = {}) {
+  hookLog('task-completed-gate', 'TaskCompleted', 'block', { reason, ...details });
+  process.stdout.write(JSON.stringify({
+    decision: 'block',
+    reason: `TASK COMPLETION BLOCKED — Truth Gate Layer 5 (TaskCompleted).\n\n${reason}`,
+  }));
+  process.stderr.write(`TASK COMPLETION BLOCKED: ${reason}\n`);
+  process.exit(2);
+}
+
+function pass(details = {}) {
+  hookLog('task-completed-gate', 'TaskCompleted', 'pass', details);
+  process.exit(0);
+}
+
+/**
+ * Is the Layer-5 TaskCompleted gate enabled? Default OFF (returns false).
+ * Mirrors work-item-exit-gate.js truthGateFlagEnabled — env is the authoritative,
+ * test-stable switch; a DB toggle is an optional deploy-time enable.
+ */
+function flagEnabledEnv() {
+  const v = String(process.env.RDC_TRUTHGATE_TASKCOMPLETED || '').trim().toLowerCase();
+  return v === '1' || v === 'true' || v === 'on' || v === 'yes';
+}
+
+/**
+ * Is the optional DB flag check opted into? Default OFF (returns false).
+ * The DB check is a Supabase/clauth round-trip; gating it behind this explicit
+ * env opt-in keeps the default-OFF path zero-cost (no network on every
+ * TaskCompleted). Only when this is set do we consult truthgate_flags.
+ */
+function flagDbOptIn() {
+  const v = String(process.env.RDC_TRUTHGATE_TASKCOMPLETED_DB || '').trim().toLowerCase();
+  return v === '1' || v === 'true' || v === 'on' || v === 'yes';
+}
+
+async function getServiceKey() {
+  if (process.env.SUPABASE_SERVICE_ROLE_KEY) return process.env.SUPABASE_SERVICE_ROLE_KEY;
+  if (process.env.SUPABASE_SERVICE_KEY) return process.env.SUPABASE_SERVICE_KEY;
+  for (const endpoint of ['supabase-service', 'supabase-service-role']) {
+    try {
+      const res = await fetch(`http://127.0.0.1:52437/v/${endpoint}`, { signal: AbortSignal.timeout(2000) });
+      if (res.ok) {
+        const text = (await res.text()).trim();
+        if (text && !text.startsWith('{')) return text;
+      }
+    } catch (_) {}
+  }
+  return null;
+}
+
+async function supabaseGet(pathname) {
+  const key = await getServiceKey();
+  if (!key) throw new Error('clauth/env did not provide a Supabase service key');
+  const base = (process.env.SUPABASE_URL || process.env.NEXT_PUBLIC_SUPABASE_URL || DEFAULT_SUPABASE_URL).replace(/\/$/, '');
+  const res = await fetch(`${base}/rest/v1/${pathname}`, {
+    headers: { apikey: key, Authorization: `Bearer ${key}`, Accept: 'application/json' },
+    signal: AbortSignal.timeout(3500),
+  });
+  if (!res.ok) throw new Error(`Supabase HTTP ${res.status}`);
+  return res.json();
+}
+
+/** Best-effort DB flag toggle. Absence/error → false (stays OFF). */
+async function flagEnabledDb() {
+  try {
+    const rows = await supabaseGet('truthgate_flags?flag=eq.taskcompleted&select=enabled&limit=1');
+    return Array.isArray(rows) && rows[0] && rows[0].enabled === true;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Extract the work-item UUID a task is bound to from the TaskCompleted payload.
+ * Looks in the common task fields and falls back to the first UUID anywhere in
+ * the serialized payload (the closure ref the agent recorded against the task).
+ * Returns the lowercased UUID or null.
+ */
+function extractWorkItemId(raw) {
+  const candidates = [
+    raw && raw.work_item_id,
+    raw && raw.task && raw.task.work_item_id,
+    raw && raw.task && raw.task.metadata && raw.task.metadata.work_item_id,
+    raw && raw.metadata && raw.metadata.work_item_id,
+  ];
+  for (const c of candidates) {
+    if (typeof c === 'string' && UUID_RE.test(c)) return c.match(UUID_RE)[0].toLowerCase();
+  }
+  let blob = '';
+  try { blob = JSON.stringify(raw); } catch (_) { blob = String(raw || ''); }
+  const m = blob.match(UUID_RE);
+  return m ? m[0].toLowerCase() : null;
+}
+
+/**
+ * Is the work-item closure SOUND for completion? Pure + unit-testable; returns
+ * { ok:true } or { ok:false, reason } — never throws. A sound closure for an
+ * implementation task requires (mirrors the L2/L3 contract the exit gate proves
+ * at `done` time):
+ *   - the row exists
+ *   - status === 'done'   (the exit gate admitted it; epics are exempt below)
+ *   - implementation_report.codeflow_post exists
+ *   - codeflow_post.witness ∈ allow-list (never 'agent' / self-witness, D5)
+ *   - codeflow_post.commit is present (a captured SHA the exit gate matched)
+ *   - codeflow_post.files_changed is a non-empty array
+ *   - codeflow_post.verification is a non-empty array
+ * Epics are not implementation tasks — an epic row is considered sound on
+ * status alone (the exit gate exempts epics from L2/L3).
+ */
+function closureIsSound(row) {
+  if (!row || typeof row !== 'object') {
+    return { ok: false, reason: 'no work-item closure row found for this task — cannot confirm a sound, Layer 2–3-admitted `done`.' };
+  }
+  if (row.item_type === 'epic') {
+    return row.status === 'done'
+      ? { ok: true }
+      : { ok: false, reason: `linked epic ${row.id} is status "${row.status}", not "done".` };
+  }
+  if (row.status !== 'done') {
+    return { ok: false, reason: `linked work item ${row.id} is status "${row.status}", not "done" — the exit gate has not admitted a Layer 2–3 closure.` };
+  }
+  const report = row.implementation_report;
+  if (!report || typeof report !== 'object') {
+    return { ok: false, reason: `work item ${row.id} has no implementation_report — a sound closure must carry one.` };
+  }
+  const post = report.codeflow_post;
+  if (!post || typeof post !== 'object') {
+    return { ok: false, reason: `work item ${row.id} has no implementation_report.codeflow_post — Layer 2–3 evidence absent.` };
+  }
+  const witness = String(post.witness || '');
+  if (!WITNESS_ALLOWLIST.has(witness)) {
+    return { ok: false, reason: `closure witness "${witness || '<missing>'}" is not in {validator-rerun, ci, human-review} — the doer cannot self-witness (D5).` };
+  }
+  if (typeof post.commit !== 'string' || !post.commit.trim()) {
+    return { ok: false, reason: `closure codeflow_post.commit is missing — no captured commit to bind the closure to.` };
+  }
+  if (!Array.isArray(post.files_changed) || post.files_changed.length === 0) {
+    return { ok: false, reason: `closure codeflow_post.files_changed is empty — a sound closure names the files it changed.` };
+  }
+  if (!Array.isArray(post.verification) || post.verification.length === 0) {
+    return { ok: false, reason: `closure codeflow_post.verification is empty — a sound closure carries a captured verification artifact.` };
+  }
+  return { ok: true };
+}
+
+/** Load the closure row: offline sink first (test seam), else Supabase. */
+async function loadClosureRow(workItemId) {
+  const sink = process.env.RDC_TASKCOMPLETED_CLOSURE_SINK;
+  if (sink) {
+    const txt = fs.readFileSync(sink, 'utf8');
+    const parsed = JSON.parse(txt);
+    return Array.isArray(parsed) ? parsed[0] : parsed;
+  }
+  const rows = await supabaseGet(
+    `work_items?id=eq.${encodeURIComponent(workItemId)}&select=id,status,item_type,implementation_report&limit=1`,
+  );
+  return Array.isArray(rows) ? rows[0] : null;
+}
+
+async function main() {
+  let raw;
+  try { raw = JSON.parse(await readStdin()); } catch { process.exit(0); }
+
+  // Default-OFF: a no-op until the flag is flipped at deploy. The env flag is
+  // checked first and short-circuits — when it is unset, the DB check runs ONLY
+  // if explicitly opted in via RDC_TRUTHGATE_TASKCOMPLETED_DB, so the dormant
+  // path is zero-cost (no Supabase/clauth round-trip on every TaskCompleted).
+  let enabled = flagEnabledEnv();
+  if (!enabled && flagDbOptIn()) {
+    enabled = await flagEnabledDb().catch(() => false);
+  }
+  if (!enabled) return pass({ reason: 'flag-off' });
+
+  // FAIL-CLOSED from here: any inability to confirm a sound closure is a BLOCK.
+  const workItemId = extractWorkItemId(raw);
+  if (!workItemId) {
+    block(
+      'This task completion carries no work-item reference, so its closure cannot be verified against the ' +
+      'Layer 2–3 exit gate. Bind the task to its work item (record the work-item UUID on the task/closure) and retry.',
+    );
+  }
+
+  let row;
+  try {
+    row = await loadClosureRow(workItemId);
+  } catch (e) {
+    block(
+      `Could not load the work-item closure for ${workItemId} (${e && e.message ? e.message : String(e)}). ` +
+      `Fail-closed: not completing the task until the closure can be verified.`,
+      { workItemId },
+    );
+  }
+
+  const verdict = closureIsSound(row);
+  if (!verdict.ok) {
+    block(
+      `${verdict.reason}\n\n` +
+      `A task may only complete once its work item has reached a sound, Layer 2–3-admitted \`done\` ` +
+      `(HMAC-valid, witnessed codeflow_post via the validator path). Move the work item through review → validator ` +
+      `\`done\` first, then complete the task.`,
+      { workItemId },
+    );
+  }
+
+  pass({ workItemId });
+}
+
+if (require.main === module) {
+  main().catch((e) => block(`task-completed-gate crashed: ${e.message}`));
+} else {
+  module.exports = {
+    flagEnabledEnv,
+    flagDbOptIn,
+    extractWorkItemId,
+    closureIsSound,
+    WITNESS_ALLOWLIST,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/rdc-skills",
-  "version": "0.24.5",
+  "version": "0.24.7",
   "description": "RDC typed-agent dispatch skill suite for Claude Code - plan, build, review, overnight builds",
   "keywords": [
     "claude-code",
@@ -34,7 +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/work-item-exit-gate-l3.test.mjs && node tests/require-work-item-on-commit.test.mjs",
+    "test:truth-gate": "node tests/run-evidence-gate.test.mjs && node tests/work-item-exit-gate-l2.test.mjs && node tests/work-item-exit-gate-l3.test.mjs && node tests/require-work-item-on-commit.test.mjs && node tests/harness-gates.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

@@ -715,10 +715,21 @@ function buildHooksConfig(hooksDir, profile = 'core') {
       cmd('check-rdc-environment.js', 'Checking RDC skills runtime...'),
       cmd('check-cwd.js'),
       cmd('check-stale-work-items.js', 'Checking for stale work items...'),
+      // Truth Gate 3.0 Layer 6 — gate watchdog (ADVISORY; SessionStart cannot block).
+      cmd('gate-watchdog-selfcheck.js', 'Truth Gate watchdog: verifying gate registration...'),
     ]}];
     config.PreToolUse[0].hooks.push(
       cmd('work-item-exit-gate.js', 'Checking work item exit gates...'),
     );
+    // Truth Gate 3.0 Layer 5 — harness completion gates. Both blocking hooks are
+    // FLAG-GATED, default OFF (no-op until the env/DB flag is flipped at deploy),
+    // so registering them does NOT disrupt the in-flight build session.
+    config.TaskCompleted = [{ hooks: [
+      cmd('task-completed-gate.js', 'Truth Gate: verifying task closure...'),
+    ]}];
+    config.PostToolBatch = [{ hooks: [
+      cmd('post-tool-batch-gate.js', 'Truth Gate: checking build-wave worktree bases...'),
+    ]}];
     config.PreCompact = [{ hooks: [
       cmd('precompact-log.js'),
     ]}];

package/tests/harness-gates.test.mjs

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+/**
+ * Truth Gate 3.0 — Layers 5+6 harness-gate tests (WP-5).
+ *
+ * Covers the three new hooks, fully offline (no DB, no brain, no clauth):
+ *   task-completed-gate.js   — flag OFF no-op; flag ON + no/unsound closure BLOCK;
+ *                              flag ON + sound closure PASS.
+ *   post-tool-batch-gate.js  — flag OFF no-op; flag ON + stale worktree base FLAG;
+ *                              flag ON + current base PASS.
+ *   gate-watchdog-selfcheck  — STOP-banner when a gate file/registration absent;
+ *                              silent when all present; checks the LIVE hookify
+ *                              hooks.json (plugin manifest), not the dead wrappers.
+ *
+ * Run: node tests/harness-gates.test.mjs
+ */
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, '..');
+const HOOKS = join(REPO_ROOT, 'hooks');
+const require = createRequire(import.meta.url);
+
+const failures = [];
+function assert(name, condition, detail = '') {
+  if (!condition) failures.push(`${name}${detail ? `: ${detail}` : ''}`);
+  else process.stdout.write(`  ok  ${name}\n`);
+}
+
+function runHook(file, payload, extraEnv = {}) {
+  return spawnSync(process.execPath, [join(HOOKS, file)], {
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+    env: { ...process.env, ...extraEnv },
+  });
+}
+
+const WI = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee';
+
+// ===========================================================================
+// 1. task-completed-gate.js
+// ===========================================================================
+{
+  const tcg = require(join(HOOKS, 'task-completed-gate.js'));
+
+  // pure: closureIsSound branches
+  assert('TCG closureIsSound: null row → not ok', tcg.closureIsSound(null).ok === false);
+  assert('TCG closureIsSound: not-done task → not ok',
+    tcg.closureIsSound({ id: WI, item_type: 'task', status: 'review' }).ok === false);
+  assert('TCG closureIsSound: done but witness:agent → not ok',
+    tcg.closureIsSound({ id: WI, item_type: 'task', status: 'done', implementation_report: { codeflow_post: { witness: 'agent', commit: 'x', files_changed: ['f'], verification: [{ exit_code: 0 }] } } }).ok === false);
+  const soundRow = {
+    id: WI, item_type: 'task', status: 'done',
+    implementation_report: { codeflow_post: { witness: 'validator-rerun', commit: 'c3189c9d58a37d648e9de4a6bcd7d46772053eea', files_changed: ['hooks/x.js'], verification: [{ exit_code: 0 }] } },
+  };
+  assert('TCG closureIsSound: full sound closure → ok', tcg.closureIsSound(soundRow).ok === true,
+    tcg.closureIsSound(soundRow).reason || '');
+  assert('TCG closureIsSound: epic done → ok',
+    tcg.closureIsSound({ id: WI, item_type: 'epic', status: 'done' }).ok === true);
+
+  // pure: extractWorkItemId
+  assert('TCG extractWorkItemId: from field', tcg.extractWorkItemId({ work_item_id: WI }) === WI);
+  assert('TCG extractWorkItemId: from blob', tcg.extractWorkItemId({ task: { note: `closes ${WI}` } }) === WI);
+  assert('TCG extractWorkItemId: none → null', tcg.extractWorkItemId({ task: { note: 'no uuid' } }) === null);
+
+  // pure: flagEnabledEnv default OFF
+  {
+    const prev = process.env.RDC_TRUTHGATE_TASKCOMPLETED;
+    delete process.env.RDC_TRUTHGATE_TASKCOMPLETED;
+    assert('TCG flag default OFF', tcg.flagEnabledEnv() === false);
+    process.env.RDC_TRUTHGATE_TASKCOMPLETED = 'true';
+    assert('TCG flag ON via env', tcg.flagEnabledEnv() === true);
+    if (prev === undefined) delete process.env.RDC_TRUTHGATE_TASKCOMPLETED;
+    else process.env.RDC_TRUTHGATE_TASKCOMPLETED = prev;
+  }
+
+  // pure: flagDbOptIn default OFF, ON via env
+  {
+    const prev = process.env.RDC_TRUTHGATE_TASKCOMPLETED_DB;
+    delete process.env.RDC_TRUTHGATE_TASKCOMPLETED_DB;
+    assert('TCG DB-opt-in default OFF', tcg.flagDbOptIn() === false);
+    process.env.RDC_TRUTHGATE_TASKCOMPLETED_DB = 'on';
+    assert('TCG DB-opt-in ON via env', tcg.flagDbOptIn() === true);
+    if (prev === undefined) delete process.env.RDC_TRUTHGATE_TASKCOMPLETED_DB;
+    else process.env.RDC_TRUTHGATE_TASKCOMPLETED_DB = prev;
+  }
+
+  // process: flag OFF → no-op (exit 0, no block)
+  {
+    const r = runHook('task-completed-gate.js', { work_item_id: WI }, { RDC_TRUTHGATE_TASKCOMPLETED: '' });
+    assert('TCG flag OFF → exit 0 no-op', r.status === 0, `status=${r.status} ${r.stderr}`);
+  }
+
+  // process: flag OFF + DB-opt-in unset → ZERO-COST OFF path makes NO DB call.
+  // Point Supabase + the clauth daemon at a non-routable, slow-to-fail address.
+  // If the OFF path consulted the DB, the call would stall near the hook's
+  // Supabase timeout (~3.5s) / clauth timeout (~2s). The run completing far
+  // under that floor proves no round-trip was attempted.
+  {
+    const t0 = Date.now();
+    const r = runHook('task-completed-gate.js', { work_item_id: WI }, {
+      RDC_TRUTHGATE_TASKCOMPLETED: '',
+      RDC_TRUTHGATE_TASKCOMPLETED_DB: '',     // DB check NOT opted into
+      SUPABASE_URL: 'http://10.255.255.1',    // non-routable: any call would hang
+      SUPABASE_SERVICE_ROLE_KEY: 'x',         // a key IS present, so only the opt-in gate keeps us off the network
+    });
+    const elapsed = Date.now() - t0;
+    assert('TCG OFF path → exit 0', r.status === 0, `status=${r.status} ${r.stderr}`);
+    assert('TCG OFF path makes no DB call (returns well under the network-timeout floor)',
+      elapsed < 1500, `elapsed=${elapsed}ms (a DB round-trip would approach the ~3.5s timeout)`);
+  }
+
+  // process: flag ON + no closure ref → BLOCK (exit 2)
+  {
+    const r = runHook('task-completed-gate.js', { task: { note: 'no uuid here' } },
+      { RDC_TRUTHGATE_TASKCOMPLETED: '1' });
+    assert('TCG flag ON + no work-item ref → exit 2 BLOCK', r.status === 2, `status=${r.status}`);
+    assert('TCG block mentions no work-item reference', /no work-item reference/.test(r.stdout + r.stderr), r.stdout);
+  }
+
+  // process: flag ON + unsound closure (status review via sink) → BLOCK
+  {
+    const dir = mkdtempSync(join(tmpdir(), 'tcg-'));
+    const sink = join(dir, 'closure.json');
+    writeFileSync(sink, JSON.stringify({ id: WI, item_type: 'task', status: 'review', implementation_report: null }));
+    const r = runHook('task-completed-gate.js', { work_item_id: WI },
+      { RDC_TRUTHGATE_TASKCOMPLETED: '1', RDC_TASKCOMPLETED_CLOSURE_SINK: sink });
+    assert('TCG flag ON + unsound closure → exit 2 BLOCK', r.status === 2, `status=${r.status} ${r.stdout}`);
+    rmSync(dir, { recursive: true, force: true });
+  }
+
+  // process: flag ON + sound closure (via sink) → PASS (exit 0)
+  {
+    const dir = mkdtempSync(join(tmpdir(), 'tcg-'));
+    const sink = join(dir, 'closure.json');
+    writeFileSync(sink, JSON.stringify(soundRow));
+    const r = runHook('task-completed-gate.js', { work_item_id: WI },
+      { RDC_TRUTHGATE_TASKCOMPLETED: '1', RDC_TASKCOMPLETED_CLOSURE_SINK: sink });
+    assert('TCG flag ON + sound closure → exit 0 PASS', r.status === 0, `status=${r.status} ${r.stdout}${r.stderr}`);
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// ===========================================================================
+// 2. post-tool-batch-gate.js
+// ===========================================================================
+{
+  const ptb = require(join(HOOKS, 'post-tool-batch-gate.js'));
+  const DEV = 'c3189c9d58a37d648e9de4a6bcd7d46772053eea';
+  const STALE = 'deadbeefdeadbeefdeadbeefdeadbeefdeadbeef';
+  const FRESH = '1234567812345678123456781234567812345678';
+
+  // pure: evaluateWave — cannotEvaluate when no develop HEAD
+  {
+    const v = ptb.evaluateWave({ developHead: null, worktrees: [], isAncestor: () => true });
+    assert('PTB evaluateWave: no develop HEAD → cannotEvaluate', v.cannotEvaluate === true && v.ok === false);
+  }
+  // pure: current base (develop is ancestor of worktree HEAD) → ok
+  {
+    const v = ptb.evaluateWave({
+      developHead: DEV,
+      worktrees: [{ path: '/wt/a', head: FRESH }],
+      isAncestor: (a, b) => a === DEV && b === FRESH, // DEV is ancestor of FRESH
+    });
+    assert('PTB evaluateWave: current base → ok, no stale', v.ok === true && v.stale.length === 0);
+  }
+  // pure: worktree HEAD == develop HEAD → ok
+  {
+    const v = ptb.evaluateWave({
+      developHead: DEV,
+      worktrees: [{ path: '/wt/a', head: DEV }],
+      isAncestor: () => false,
+    });
+    assert('PTB evaluateWave: head==develop → ok', v.ok === true && v.stale.length === 0);
+  }
+  // pure: stale base (develop NOT an ancestor) → flagged
+  {
+    const v = ptb.evaluateWave({
+      developHead: DEV,
+      worktrees: [{ path: '/wt/stale', head: STALE }],
+      isAncestor: () => false, // DEV is NOT an ancestor of STALE
+    });
+    assert('PTB evaluateWave: stale base → not ok', v.ok === false, JSON.stringify(v));
+    assert('PTB evaluateWave: stale worktree listed', v.stale.length === 1 && v.stale[0].head === STALE);
+  }
+
+  // process: flag OFF → no-op (exit 0)
+  {
+    const r = runHook('post-tool-batch-gate.js', { hook_event_name: 'PostToolBatch' },
+      { RDC_TRUTHGATE_POSTTOOLBATCH: '' });
+    assert('PTB flag OFF → exit 0 no-op', r.status === 0, `status=${r.status} ${r.stderr}`);
+  }
+}
+
+// ===========================================================================
+// 3. gate-watchdog-selfcheck.js
+// ===========================================================================
+{
+  const wd = require(join(HOOKS, 'gate-watchdog-selfcheck.js'));
+
+  const allPresent = {
+    exitGateFileExists: true, exitGateRegistered: true,
+    truthGateFileExists: true, truthGateOnStop: true, truthGateOnSubagentStop: true,
+    liveHookifyManifestExists: true, deadWrapperPointsAtStaleCache: false,
+  };
+  // all present → no findings, empty banner (silent)
+  {
+    const findings = wd.evaluateWatchdog(allPresent);
+    assert('WD all present → no findings', findings.length === 0, JSON.stringify(findings));
+    assert('WD all present → empty banner (silent)', wd.renderBanner(findings) === '');
+  }
+  // truth-gate missing → finding + STOP banner
+  {
+    const findings = wd.evaluateWatchdog({ ...allPresent, truthGateFileExists: false });
+    assert('WD truth-gate missing → finding', findings.some((f) => /truth-gate\.mjs is MISSING/.test(f)), JSON.stringify(findings));
+    const banner = wd.renderBanner(findings);
+    assert('WD truth-gate missing → STOP banner emitted', /TRUTH GATE WATCHDOG/.test(banner) && banner.length > 0);
+  }
+  // truth-gate unregistered on SubagentStop → finding
+  {
+    const findings = wd.evaluateWatchdog({ ...allPresent, truthGateOnSubagentStop: false });
+    assert('WD truth-gate not on SubagentStop → finding', findings.some((f) => /SubagentStop/.test(f)));
+  }
+  // exit gate missing → finding
+  {
+    const findings = wd.evaluateWatchdog({ ...allPresent, exitGateFileExists: false });
+    assert('WD exit-gate missing → finding', findings.some((f) => /work-item-exit-gate\.js is MISSING/.test(f)));
+  }
+  // LIVE hookify manifest absent → finding mentions plugin manifest, NOT dead wrappers as trusted
+  {
+    const findings = wd.evaluateWatchdog({ ...allPresent, liveHookifyManifestExists: false });
+    const f = findings.find((x) => /hookify/i.test(x));
+    assert('WD live hookify manifest absent → finding', Boolean(f), JSON.stringify(findings));
+    assert('WD finding names the LIVE plugin hooks.json (not dead wrappers as trusted)',
+      f && /plugins\/cache.*hookify.*hooks\.json/i.test(f) && /NOT the live path/i.test(f), f || '');
+  }
+  // dead wrapper points at stale cache → drift finding
+  {
+    const findings = wd.evaluateWatchdog({ ...allPresent, deadWrapperPointsAtStaleCache: true,
+      deadWrapperRoot: '/cache/hookify/OLDHASH', liveHookifyRoot: '/cache/hookify/NEWHASH' });
+    assert('WD stale-cache drift → finding', findings.some((f) => /ORPHANED cache hash/.test(f)));
+  }
+
+  // structural: gatherFacts inspects the LIVE plugins/cache hooks.json path, not the wrappers.
+  {
+    const home = mkdtempSync(join(tmpdir(), 'wd-home-'));
+    const repo = mkdtempSync(join(tmpdir(), 'wd-repo-'));
+    // Build a fake LIVE hookify plugin manifest under plugins/cache/.../hookify/<hash>/hooks/hooks.json
+    const live = join(home, '.claude', 'plugins', 'cache', 'official', 'hookify', 'NEWHASH', 'hooks');
+    mkdirSync(live, { recursive: true });
+    writeFileSync(join(live, 'hooks.json'), JSON.stringify({ hooks: {} }));
+    // Build a dead wrapper that points at a DIFFERENT (orphaned) hash.
+    const deadDir = join(home, '.claude', 'hooks');
+    mkdirSync(deadDir, { recursive: true });
+    writeFileSync(join(deadDir, 'hookify-stop.js'),
+      "const PLUGIN_ROOT = 'C:/cache/official/hookify/OLDHASH';\n");
+    // Minimal settings.json registering both gates so those facts are true.
+    mkdirSync(join(repo, '.claude', 'hooks'), { recursive: true });
+    writeFileSync(join(repo, '.claude', 'hooks', 'truth-gate.mjs'), '// stub');
+    writeFileSync(join(repo, '.claude', 'settings.json'), JSON.stringify({
+      hooks: {
+        PreToolUse: [{ hooks: [{ type: 'command', command: 'node hooks/work-item-exit-gate.js' }] }],
+        Stop: [{ hooks: [{ type: 'command', command: 'node .claude/hooks/truth-gate.mjs' }] }],
+        SubagentStop: [{ hooks: [{ type: 'command', command: 'node .claude/hooks/truth-gate.mjs' }] }],
+      },
+    }));
+
+    const manifest = wd.findLiveHookifyManifest(home);
+    assert('WD findLiveHookifyManifest resolves the plugin hooks.json',
+      typeof manifest === 'string' && /plugins[\\/]cache.*hookify.*hooks\.json$/i.test(manifest.replace(/\\/g, '/')), manifest || 'null');
+
+    const facts = wd.gatherFacts({ home, repoRoot: repo, hooksDir: HOOKS });
+    assert('WD gatherFacts: live hookify manifest detected', facts.liveHookifyManifestExists === true);
+    assert('WD gatherFacts: dead wrapper stale-cache drift detected', facts.deadWrapperPointsAtStaleCache === true,
+      `dead=${facts.deadWrapperRoot} live=${facts.liveHookifyRoot}`);
+    assert('WD gatherFacts: truth-gate registered on Stop+SubagentStop',
+      facts.truthGateOnStop === true && facts.truthGateOnSubagentStop === true);
+    assert('WD gatherFacts: exit gate registered on PreToolUse', facts.exitGateRegistered === true);
+
+    rmSync(home, { recursive: true, force: true });
+    rmSync(repo, { recursive: true, force: true });
+  }
+}
+
+// ===========================================================================
+if (failures.length > 0) {
+  console.error('\nharness-gates tests — FAIL\n');
+  for (const f of failures) console.error(`  - ${f}`);
+  process.exit(1);
+}
+console.log('\nharness-gates tests — PASS');