session-orchestrator 3.16.0

package/scripts/lib/hardening.mjs

@@ -0,0 +1,43 @@
+/**
+ * hardening.mjs — re-export barrel for the hardening primitives.
+ *
+ * The original 691-line module bundled THREE structurally-independent concerns.
+ * They now live in dedicated modules (Epic A4 split); this file is a pure
+ * re-export barrel that preserves the original import surface (all 11 symbols)
+ * so existing importers keep working UNCHANGED:
+ *   - hooks/enforce-commands.mjs, hooks/enforce-scope.mjs,
+ *     hooks/post-edit-validate.mjs, hooks/pre-bash-destructive-guard.mjs,
+ *     hooks/pre-bash-memory-propose-audit.mjs, hooks/wave-scope-commit-guard.mjs
+ *   - scripts/lib/io.mjs, scripts/lib/pre-dispatch-check.mjs,
+ *     scripts/lib/worktree-freshness.mjs
+ *
+ * Concern split:
+ *   A) Env / runtime checks                → ./env-check.mjs
+ *   B) Scope / pattern primitives          → ./scope-gate.mjs
+ *   C) Command-blocking tokenizer + matcher → ./command-blocker.mjs
+ *
+ * The new modules MUST NOT import from this barrel (would cycle).
+ *
+ * Layering: hook-safe — pure functions only; no I/O at import time;
+ * ESM-pure for fast hook hot-paths. Hooks (under `hooks/`) import from
+ * this lib; this lib MUST NOT reverse-import from `hooks/`. Cross-cutting
+ * invariant for all exports below — see #554 A2.
+ *
+ * Part of v3.0.0 migration (Epic #124, issue #135).
+ */
+
+// A) Env / runtime checks
+export { assertNodeVersion, assertDepInstalled, checkEnvironment } from './env-check.mjs';
+
+// B) Scope / pattern primitives
+export {
+  findScopeFile,
+  getEnforcementLevel,
+  gateEnabled,
+  pathMatchesPattern,
+  extractBashWriteTargets,
+  suggestForScopeViolation,
+} from './scope-gate.mjs';
+
+// C) Command-blocking tokenizer + matcher
+export { tokenizeCommand, commandMatchesBlocked, suggestForCommandBlock } from './command-blocker.mjs';

package/scripts/lib/hardware-pattern-detector.mjs

@@ -0,0 +1,238 @@
+/**
+ * hardware-pattern-detector.mjs — v3.1.0 hardware-pattern detection.
+ *
+ * Part of Sub-Epic #160 / Epic #157. Issue #171 (C2).
+ *
+ * Extracts `hardware-pattern` learning candidates from session + event history.
+ * Detection signals (all key on host_class rather than project):
+ *
+ *   1. oom-kill      — stop events with exitCode 137 or "Out of memory" marker
+ *   2. heartbeat-gap — registry sweep.log entries for the same host
+ *                      (session disappeared without a clean stop — freeze proxy)
+ *   3. concurrent-session-pressure — session events where peer_count crossed
+ *                      the configured concurrent-sessions-warn threshold
+ *   4. disk-full     — events with ENOSPC / "no space left" markers
+ *   5. thermal-throttle — sustained high CPU load + unexpected slow-wave marker
+ *
+ * The detector is additive and idempotent. It produces CANDIDATES; the /evolve
+ * analyze flow still runs them through the standard dedupe + user-confirmation
+ * pipeline before they reach learnings.jsonl. Candidates are emitted with
+ * scope='private' by default (in-repo safe); export (C3) elevates them to
+ * scope='public' only after an anonymization pass.
+ */
+
+// ---------------------------------------------------------------------------
+// Thresholds (defaults; caller can override via opts.thresholds)
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_THRESHOLDS = Object.freeze({
+  /** Minimum recurrence for a candidate to be emitted (same host_class). */
+  minOccurrences: 2,
+  /** Minimum peer_count to count as concurrent-session pressure. */
+  concurrentSessionsWarn: 5,
+  /** CPU load percentage that marks a thermal-throttle signal. */
+  thermalCpuLoadPct: 85,
+  /** Heartbeat gap threshold in minutes above which a session is "frozen". */
+  heartbeatGapMinutes: 30,
+});
+
+/** Signal classifiers — narrow enum for candidate subjects. */
+export const HW_SIGNALS = Object.freeze([
+  'oom-kill',
+  'heartbeat-gap',
+  'concurrent-session-pressure',
+  'disk-full',
+  'thermal-throttle',
+]);
+
+// ---------------------------------------------------------------------------
+// Per-signal detectors — stateless, pure functions over arrays
+// ---------------------------------------------------------------------------
+
+function detectOomKill(events) {
+  const hits = events.filter((e) => {
+    if (e.event !== 'orchestrator.session.stopped') return false;
+    if (e.exit_code === 137) return true;
+    if (typeof e.error === 'string' && /out of memory|killed/i.test(e.error)) return true;
+    return false;
+  });
+  return hits.map((e) => ({
+    signal: 'oom-kill',
+    host_class: e.host_class ?? null,
+    timestamp: e.timestamp,
+    raw: { exit_code: e.exit_code, session: e.session ?? null },
+  }));
+}
+
+function detectHeartbeatGap(sweepLogEntries, thresholdMin) {
+  // sweepLogEntries expected shape: {host_class, session_id, gap_minutes, swept_at}
+  return sweepLogEntries
+    .filter((e) => typeof e.gap_minutes === 'number' && e.gap_minutes >= thresholdMin)
+    .map((e) => ({
+      signal: 'heartbeat-gap',
+      host_class: e.host_class ?? null,
+      timestamp: e.swept_at,
+      raw: { gap_minutes: e.gap_minutes, session_id: e.session_id },
+    }));
+}
+
+function detectConcurrentSessionPressure(events, threshold) {
+  return events
+    .filter((e) => e.event === 'orchestrator.session.started' && typeof e.peer_count === 'number' && e.peer_count >= threshold)
+    .map((e) => ({
+      signal: 'concurrent-session-pressure',
+      host_class: e.host_class ?? null,
+      timestamp: e.timestamp,
+      raw: { peer_count: e.peer_count },
+    }));
+}
+
+function detectDiskFull(events) {
+  const hits = events.filter((e) => {
+    if (typeof e.error !== 'string') return false;
+    return /ENOSPC|no space left|disk full/i.test(e.error);
+  });
+  return hits.map((e) => ({
+    signal: 'disk-full',
+    host_class: e.host_class ?? null,
+    timestamp: e.timestamp,
+    raw: { error: e.error },
+  }));
+}
+
+function detectThermalThrottle(events, thresholdPct) {
+  // Thermal signal: session events carrying cpu_load_pct above threshold
+  // sustained (our events include a live snapshot under .resource_snapshot).
+  return events
+    .filter((e) => {
+      const snap = e.resource_snapshot;
+      return snap && typeof snap.cpu_load_pct === 'number' && snap.cpu_load_pct >= thresholdPct;
+    })
+    .map((e) => ({
+      signal: 'thermal-throttle',
+      host_class: e.host_class ?? null,
+      timestamp: e.timestamp,
+      raw: { cpu_load_pct: e.resource_snapshot.cpu_load_pct },
+    }));
+}
+
+// ---------------------------------------------------------------------------
+// Aggregation — group individual hits into candidate learnings
+// ---------------------------------------------------------------------------
+
+/**
+ * Group hits by (signal, host_class), count occurrences, and emit candidates
+ * whose count meets the minOccurrences threshold. Hits missing host_class
+ * are dropped (a hardware-pattern with no host anchor is meaningless).
+ *
+ * @param {object[]} hits — per-signal hit objects from detectors
+ * @param {number} minOccurrences
+ * @returns {object[]} candidate learning records (pre-validation)
+ */
+export function aggregateCandidates(hits, minOccurrences) {
+  const buckets = new Map();
+  for (const h of hits) {
+    if (!h.host_class) continue;
+    const key = `${h.signal}::${h.host_class}`;
+    let bucket = buckets.get(key);
+    if (!bucket) {
+      bucket = {
+        signal: h.signal,
+        host_class: h.host_class,
+        occurrences: 0,
+        first_seen: h.timestamp,
+        last_seen: h.timestamp,
+        samples: [],
+      };
+      buckets.set(key, bucket);
+    }
+    bucket.occurrences += 1;
+    if (h.timestamp < bucket.first_seen) bucket.first_seen = h.timestamp;
+    if (h.timestamp > bucket.last_seen) bucket.last_seen = h.timestamp;
+    // Keep at most 3 sample payloads to bound candidate size
+    if (bucket.samples.length < 3) bucket.samples.push(h.raw);
+  }
+
+  const out = [];
+  for (const b of buckets.values()) {
+    if (b.occurrences < minOccurrences) continue;
+    out.push({
+      type: 'hardware-pattern',
+      subject: `${b.signal}::${b.host_class}`,
+      signal: b.signal,
+      host_class: b.host_class,
+      occurrences: b.occurrences,
+      first_seen: b.first_seen,
+      last_seen: b.last_seen,
+      samples: b.samples,
+    });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Public entrypoint
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect hardware-pattern candidates from structured session/event history.
+ *
+ * @param {object}   input
+ * @param {object[]} [input.events=[]]          — parsed events.jsonl entries
+ * @param {object[]} [input.sweepLogEntries=[]] — parsed registry sweep.log entries
+ * @param {object}   [input.thresholds]         — override DEFAULT_THRESHOLDS
+ * @returns {object[]} hardware-pattern candidates (type+subject+signal+host_class+occurrences+samples)
+ */
+export function detectHardwarePatterns({
+  events = [],
+  sweepLogEntries = [],
+  thresholds = {},
+} = {}) {
+  const t = { ...DEFAULT_THRESHOLDS, ...thresholds };
+
+  const hits = [
+    ...detectOomKill(events),
+    ...detectHeartbeatGap(sweepLogEntries, t.heartbeatGapMinutes),
+    ...detectConcurrentSessionPressure(events, t.concurrentSessionsWarn),
+    ...detectDiskFull(events),
+    ...detectThermalThrottle(events, t.thermalCpuLoadPct),
+  ];
+
+  return aggregateCandidates(hits, t.minOccurrences);
+}
+
+// ---------------------------------------------------------------------------
+// Candidate → learning shape (feeds /evolve analyze confirmation pipeline)
+// ---------------------------------------------------------------------------
+
+/**
+ * Shape a candidate into the learnings.jsonl schema (see scripts/lib/learnings.mjs).
+ * Intentionally uses scope='private' — hardware patterns never land as 'public'
+ * without a separate anonymization pass (C3).
+ *
+ * @param {object} candidate — output of detectHardwarePatterns()
+ * @param {object} opts
+ * @param {string} opts.sessionId          — current session identifier (source_session)
+ * @param {string} opts.createdAt          — ISO 8601 string (override for tests)
+ * @param {string} opts.expiresAt          — ISO 8601 string (override for tests)
+ * @returns {object} learning entry (pre-validation)
+ */
+export function candidateToLearning(candidate, opts) {
+  const insight = `Host class ${candidate.host_class} shows ${candidate.signal} pattern (${candidate.occurrences} occurrences between ${candidate.first_seen} and ${candidate.last_seen}).`;
+  const evidence = `signal=${candidate.signal}, host_class=${candidate.host_class}, occurrences=${candidate.occurrences}, samples=${JSON.stringify(candidate.samples)}`;
+
+  return {
+    id: opts.id,
+    type: 'hardware-pattern',
+    subject: candidate.subject,
+    insight,
+    evidence,
+    confidence: 0.5,
+    source_session: opts.sessionId,
+    created_at: opts.createdAt,
+    expires_at: opts.expiresAt,
+    scope: 'private',
+    host_class: candidate.host_class,
+    anonymized: false,
+  };
+}

package/scripts/lib/harness-audit/categories/category1.mjs

@@ -0,0 +1,123 @@
+/**
+ * category1.mjs — Category 1: Session Discipline (weight: 10)
+ *
+ * Checks: state-md-present, sessions-jsonl-growth, learnings-jsonl-nonempty,
+ *         orchestrator-layout
+ *
+ * Stdlib only: node:fs, node:path.
+ */
+
+import { existsSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+import { parseFrontmatter, safeRead, parseJsonl, pass, fail } from './helpers.mjs';
+
+export function runCategory1(root) {
+  const checks = [];
+
+  // c1.1 state-md-present
+  {
+    const candidates = [
+      join(root, '.claude/STATE.md'),
+      join(root, '.codex/STATE.md'),
+      join(root, '.cursor/STATE.md'),
+      join(root, '.pi/STATE.md'),
+    ];
+    const found = candidates.find((p) => existsSync(p));
+    if (!found) {
+      checks.push(fail('state-md-present', 3, '.claude/STATE.md',
+        { path: null, hasYaml: false, schemaVersion: null, sessionType: null },
+        'STATE.md not found in .claude/, .codex/, .cursor/, or .pi/'));
+    } else {
+      const text = safeRead(found);
+      const size = text ? text.length : 0;
+      const fm = text ? parseFrontmatter(text) : null;
+      const hasYaml = fm !== null;
+      const sv = fm ? fm['schema-version'] : null;
+      const st = fm ? fm['status'] : null;
+      const stype = fm ? fm['session-type'] : null;
+      const hasSchemaV1 = sv === '1';
+      const relPath = relative(root, found).split(sep).join('/');
+      if (size > 0 && hasYaml && hasSchemaV1 && st && stype) {
+        checks.push(pass('state-md-present', 3, 3, relPath,
+          { path: relPath, hasYaml: true, schemaVersion: sv, sessionType: stype },
+          `STATE.md present, schema-version=${sv}, session-type=${stype}`));
+      } else {
+        checks.push(fail('state-md-present', 3, relPath,
+          { path: relPath, hasYaml, schemaVersion: sv, sessionType: stype },
+          `STATE.md found but missing required frontmatter fields (size=${size}, yaml=${hasYaml}, schema-version=${sv})`));
+      }
+    }
+  }
+
+  // c1.2 sessions-jsonl-growth
+  {
+    const p = join(root, '.orchestrator/metrics/sessions.jsonl');
+    const text = safeRead(p);
+    const relPath = '.orchestrator/metrics/sessions.jsonl';
+    if (!text) {
+      checks.push(fail('sessions-jsonl-growth', 3, relPath,
+        { lineCount: 0, validLines: 0 }, 'sessions.jsonl missing'));
+    } else {
+      const { lines, validLines } = parseJsonl(text);
+      const requiredKeys = ['session_id', 'session_type', 'started_at'];
+      const wellFormed = validLines.filter((l) => requiredKeys.every((k) => k in l));
+      if (lines >= 2 && wellFormed.length === lines) {
+        checks.push(pass('sessions-jsonl-growth', 3, 3, relPath,
+          { lineCount: lines, validLines: wellFormed.length },
+          `sessions.jsonl has ${lines} valid lines`));
+      } else {
+        checks.push(fail('sessions-jsonl-growth', 3, relPath,
+          { lineCount: lines, validLines: wellFormed.length },
+          `sessions.jsonl: lines=${lines} (need ≥2), wellFormed=${wellFormed.length}/${lines}`));
+      }
+    }
+  }
+
+  // c1.3 learnings-jsonl-nonempty
+  {
+    const p = join(root, '.orchestrator/metrics/learnings.jsonl');
+    const text = safeRead(p);
+    const relPath = '.orchestrator/metrics/learnings.jsonl';
+    if (!text) {
+      checks.push(fail('learnings-jsonl-nonempty', 2, relPath,
+        { lineCount: 0, validLines: 0 }, 'learnings.jsonl missing'));
+    } else {
+      const { lines, validLines } = parseJsonl(text);
+      const requiredKeys = ['type', 'subject', 'confidence'];
+      const wellFormed = validLines.filter((l) => requiredKeys.every((k) => k in l));
+      if (lines >= 1 && wellFormed.length === lines) {
+        checks.push(pass('learnings-jsonl-nonempty', 2, 2, relPath,
+          { lineCount: lines, validLines: wellFormed.length },
+          `learnings.jsonl has ${lines} valid lines`));
+      } else {
+        checks.push(fail('learnings-jsonl-nonempty', 2, relPath,
+          { lineCount: lines, validLines: wellFormed.length },
+          `learnings.jsonl: lines=${lines} (need ≥1), wellFormed=${wellFormed.length}/${lines}`));
+      }
+    }
+  }
+
+  // c1.4 orchestrator-layout
+  {
+    const requiredPaths = [
+      '.orchestrator',
+      '.orchestrator/bootstrap.lock',
+      '.orchestrator/policy',
+      '.orchestrator/metrics',
+    ];
+    const presentPaths = requiredPaths.filter((rp) => existsSync(join(root, rp)));
+    if (presentPaths.length === requiredPaths.length) {
+      checks.push(pass('orchestrator-layout', 2, 2, '.orchestrator/',
+        { presentPaths },
+        'All required .orchestrator/ paths present'));
+    } else {
+      const missing = requiredPaths.filter((rp) => !existsSync(join(root, rp)));
+      checks.push(fail('orchestrator-layout', 2, '.orchestrator/',
+        { presentPaths, missingPaths: missing },
+        `Missing: ${missing.join(', ')}`));
+    }
+  }
+
+  return checks;
+}

package/scripts/lib/harness-audit/categories/category2.mjs

@@ -0,0 +1,145 @@
+/**
+ * category2.mjs — Category 2: Quality Gate Coverage (weight: 10)
+ *
+ * Checks: package-json-scripts, bootstrap-lock-schema, quality-gates-policy,
+ *         schema-drift-ci
+ *
+ * Stdlib only: node:fs, node:path.
+ */
+
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { safeRead, safeJson, pass, fail } from './helpers.mjs';
+
+export function runCategory2(root) {
+  const checks = [];
+
+  // c2.1 package-json-scripts
+  {
+    const p = join(root, 'package.json');
+    const text = safeRead(p);
+    const pkg = safeJson(text);
+    const relPath = 'package.json';
+    if (!pkg) {
+      checks.push(fail('package-json-scripts', 3, relPath,
+        { test: null, typecheck: null, lint: null },
+        'package.json missing or invalid JSON'));
+    } else {
+      const scripts = pkg.scripts || {};
+      const testVal = typeof scripts.test === 'string' ? scripts.test : null;
+      const typecheckVal = typeof scripts.typecheck === 'string' ? scripts.typecheck : null;
+      const lintVal = typeof scripts.lint === 'string' ? scripts.lint : null;
+      if (testVal && typecheckVal && lintVal) {
+        checks.push(pass('package-json-scripts', 3, 3, relPath,
+          { test: testVal, typecheck: typecheckVal, lint: lintVal },
+          'package.json has test, typecheck, and lint scripts'));
+      } else {
+        checks.push(fail('package-json-scripts', 3, relPath,
+          { test: testVal, typecheck: typecheckVal, lint: lintVal },
+          `Missing scripts: ${[!testVal && 'test', !typecheckVal && 'typecheck', !lintVal && 'lint'].filter(Boolean).join(', ')}`));
+      }
+    }
+  }
+
+  // c2.2 bootstrap-lock-schema
+  {
+    const p = join(root, '.orchestrator/bootstrap.lock');
+    const text = safeRead(p);
+    const relPath = '.orchestrator/bootstrap.lock';
+    if (!text) {
+      checks.push(fail('bootstrap-lock-schema', 3, relPath,
+        { version: null, tier: null, archetype: null },
+        'bootstrap.lock missing'));
+    } else {
+      // Hand-rolled YAML key extraction
+      const versionMatch = /^version:\s*(.+)$/m.exec(text);
+      const tierMatch = /^tier:\s*(.+)$/m.exec(text);
+      const archetypeMatch = /^archetype:\s*(.+)$/m.exec(text);
+      const version = versionMatch ? versionMatch[1].trim() : null;
+      const tier = tierMatch ? tierMatch[1].trim() : null;
+      const archetype = archetypeMatch ? archetypeMatch[1].trim() : null;
+      const validTiers = ['fast', 'standard', 'deep'];
+      if (version && tier && validTiers.includes(tier) && archetype) {
+        checks.push(pass('bootstrap-lock-schema', 3, 3, relPath,
+          { version, tier, archetype },
+          `bootstrap.lock valid: version=${version}, tier=${tier}, archetype=${archetype}`));
+      } else {
+        checks.push(fail('bootstrap-lock-schema', 3, relPath,
+          { version, tier, archetype },
+          `bootstrap.lock invalid: version=${version}, tier=${tier} (valid: fast|standard|deep), archetype=${archetype}`));
+      }
+    }
+  }
+
+  // c2.3 quality-gates-policy
+  {
+    const p = join(root, '.orchestrator/policy/quality-gates.json');
+    const relPath = '.orchestrator/policy/quality-gates.json';
+    if (!existsSync(p)) {
+      // Optional — skip with pass
+      checks.push(pass('quality-gates-policy', 2, 2, relPath,
+        { present: false, valid: null },
+        'quality-gates.json absent (optional per #183 fallback chain) — skip'));
+    } else {
+      const text = safeRead(p);
+      const json = safeJson(text);
+      if (!json) {
+        checks.push(fail('quality-gates-policy', 2, relPath,
+          { present: true, valid: false },
+          'quality-gates.json exists but is not valid JSON'));
+      } else {
+        const cmds = json.commands || {};
+        const hasTest = cmds.test && typeof cmds.test.command === 'string';
+        const hasTypecheck = cmds.typecheck && typeof cmds.typecheck.command === 'string';
+        const hasLint = cmds.lint && typeof cmds.lint.command === 'string';
+        if (hasTest && hasTypecheck && hasLint) {
+          checks.push(pass('quality-gates-policy', 2, 2, relPath,
+            { present: true, valid: true },
+            'quality-gates.json valid with commands.test|typecheck|lint'));
+        } else {
+          checks.push(fail('quality-gates-policy', 2, relPath,
+            { present: true, valid: false },
+            `quality-gates.json missing commands: ${[!hasTest && 'test', !hasTypecheck && 'typecheck', !hasLint && 'lint'].filter(Boolean).join(', ')}`));
+        }
+      }
+    }
+  }
+
+  // c2.4 schema-drift-ci
+  {
+    const gitlabCi = join(root, '.gitlab-ci.yml');
+    const ghWorkflowsDir = join(root, '.github/workflows');
+    let matchedFile = null;
+
+    const gitlabText = safeRead(gitlabCi);
+    if (gitlabText && gitlabText.includes('schema-drift-check')) {
+      matchedFile = '.gitlab-ci.yml';
+    }
+
+    if (!matchedFile && existsSync(ghWorkflowsDir)) {
+      try {
+        const files = readdirSync(ghWorkflowsDir).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+        for (const f of files) {
+          const text = safeRead(join(ghWorkflowsDir, f));
+          if (text && text.includes('schema-drift')) {
+            matchedFile = `.github/workflows/${f}`;
+            break;
+          }
+        }
+      } catch { /* ignore */ }
+    }
+
+    if (matchedFile) {
+      checks.push(pass('schema-drift-ci', 2, 2, matchedFile,
+        { matchedFile },
+        `schema-drift check found in ${matchedFile}`));
+    } else {
+      checks.push(fail('schema-drift-ci', 2, '.gitlab-ci.yml or .github/workflows/*.yml',
+        { matchedFile: null },
+        'No schema-drift-check/schema-drift string found in CI config'));
+    }
+  }
+
+  return checks;
+}

package/scripts/lib/harness-audit/categories/category3.mjs

@@ -0,0 +1,143 @@
+/**
+ * category3.mjs — Category 3: Hook Integrity (weight: 10)
+ *
+ * Checks: hooks-json-valid, hook-files-exist, hook-mjs-syntax,
+ *         destructive-guard-loads-policy
+ *
+ * Stdlib only: node:fs, node:path, node:child_process.
+ */
+
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+import { safeRead, safeJson, pass, fail } from './helpers.mjs';
+
+export function runCategory3(root) {
+  const checks = [];
+
+  // c3.1 hooks-json-valid
+  {
+    const p = join(root, 'hooks/hooks.json');
+    const text = safeRead(p);
+    const relPath = 'hooks/hooks.json';
+    const json = safeJson(text);
+    if (!json) {
+      checks.push(fail('hooks-json-valid', 3, relPath,
+        { matcherCount: 0 },
+        'hooks/hooks.json missing or invalid JSON'));
+    } else {
+      // Count matcher blocks: each event key in json.hooks has an array of matchers
+      let matcherCount = 0;
+      const hooks = json.hooks || {};
+      for (const eventKey of Object.keys(hooks)) {
+        const eventHooks = hooks[eventKey];
+        if (Array.isArray(eventHooks)) matcherCount += eventHooks.length;
+      }
+      if (matcherCount >= 1) {
+        checks.push(pass('hooks-json-valid', 3, 3, relPath,
+          { matcherCount },
+          `hooks.json valid with ${matcherCount} matcher block(s)`));
+      } else {
+        checks.push(fail('hooks-json-valid', 3, relPath,
+          { matcherCount },
+          'hooks.json valid JSON but has no matcher blocks'));
+      }
+    }
+  }
+
+  // c3.2 hook-files-exist
+  {
+    const p = join(root, 'hooks/hooks.json');
+    const text = safeRead(p);
+    const relPath = 'hooks/hooks.json';
+    const json = safeJson(text);
+    const referenced = [];
+    const missing = [];
+
+    if (json && json.hooks) {
+      // Walk all command strings looking for $CLAUDE_PLUGIN_ROOT/hooks/*.mjs
+      const commandRe = /\$(?:CLAUDE_PLUGIN_ROOT|CODEX_PLUGIN_ROOT|CURSOR_RULES_DIR)\/hooks\/([^"'\s]+\.mjs)/g;
+      const jsonText = JSON.stringify(json);
+      let m;
+      while ((m = commandRe.exec(jsonText)) !== null) {
+        const rel = `hooks/${m[1]}`;
+        if (!referenced.includes(rel)) referenced.push(rel);
+      }
+      for (const rel of referenced) {
+        if (!existsSync(join(root, rel))) missing.push(rel);
+      }
+    }
+
+    if (missing.length === 0) {
+      checks.push(pass('hook-files-exist', 3, 3, relPath,
+        { referenced, missing },
+        `All ${referenced.length} referenced hook file(s) exist`));
+    } else {
+      checks.push(fail('hook-files-exist', 3, relPath,
+        { referenced, missing },
+        `Missing hook files: ${missing.join(', ')}`));
+    }
+  }
+
+  // c3.3 hook-mjs-syntax
+  {
+    const hooksDir = join(root, 'hooks');
+    const relPath = 'hooks/*.mjs';
+    let filesChecked = [];
+    const syntaxErrors = [];
+
+    try {
+      filesChecked = readdirSync(hooksDir)
+        .filter((f) => f.endsWith('.mjs'))
+        .map((f) => `hooks/${f}`);
+    } catch { /* hooks dir missing */ }
+
+    for (const rel of filesChecked) {
+      const abs = join(root, rel);
+      try {
+        execFileSync('node', ['--check', abs], { timeout: 3000, stdio: 'pipe' });
+      } catch (err) {
+        const msg = err.stderr ? err.stderr.toString().trim() : String(err);
+        syntaxErrors.push({ file: rel, error: msg.split('\n')[0] });
+      }
+    }
+
+    if (syntaxErrors.length === 0) {
+      checks.push(pass('hook-mjs-syntax', 2, 2, relPath,
+        { filesChecked: filesChecked.length, syntaxErrors: [] },
+        `All ${filesChecked.length} hook .mjs file(s) pass syntax check`));
+    } else {
+      checks.push(fail('hook-mjs-syntax', 2, relPath,
+        { filesChecked: filesChecked.length, syntaxErrors },
+        `${syntaxErrors.length} hook file(s) have syntax errors`));
+    }
+  }
+
+  // c3.4 destructive-guard-loads-policy
+  {
+    const p = join(root, 'hooks/pre-bash-destructive-guard.mjs');
+    const relPath = 'hooks/pre-bash-destructive-guard.mjs';
+    const text = safeRead(p);
+    if (!text) {
+      checks.push(fail('destructive-guard-loads-policy', 2, relPath,
+        { loadsPolicy: false },
+        'pre-bash-destructive-guard.mjs missing'));
+    } else {
+      const loadsPolicy = text.includes('blocked-commands.json') ||
+        /import.*\.orchestrator\/policy/.test(text) ||
+        /require.*\.orchestrator\/policy/.test(text);
+      if (loadsPolicy) {
+        checks.push(pass('destructive-guard-loads-policy', 2, 2, relPath,
+          { loadsPolicy: true },
+          'pre-bash-destructive-guard.mjs references policy'));
+      } else {
+        checks.push(fail('destructive-guard-loads-policy', 2, relPath,
+          { loadsPolicy: false },
+          'pre-bash-destructive-guard.mjs does not reference blocked-commands.json or .orchestrator/policy'));
+      }
+    }
+  }
+
+  return checks;
+}