@geraldmaron/construct 1.0.5 → 1.0.7

package/lib/daemons/contract.mjs

@@ -0,0 +1,210 @@
+/**
+ * lib/daemons/contract.mjs — Shared safeguard contract for every long-running
+ * Construct process. No ambient process in Construct survives without these
+ * rails.
+ *
+ * Safeguards enforced for every daemon that uses DaemonRunner:
+ *   - Bounded lifetime: max wall-clock runtime (default 24h) before self-restart
+ *     with state checkpoint.
+ *   - Idle shutdown: if no work for N consecutive ticks, stop and log;
+ *     resume on next external trigger.
+ *   - Heartbeat: every tick writes lastTickAt to a known path.
+ *   - Single-writer lock: prevents duplicate daemon instances; auto-expires.
+ *   - Killswitch: env var disables the daemon without code changes.
+ *   - Resource caps: CPU/memory limits via process.resourceUsage thresholds.
+ *
+ * Per-item safeguards (TTL, retry budget, dead-letter) are owned by the work
+ * queue, not the runner; this module exposes a small queue helper for that.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+
+export const DEFAULT_MAX_RUNTIME_MS = 24 * 60 * 60 * 1000;
+export const DEFAULT_IDLE_TICKS = 6;
+export const DEFAULT_MEMORY_CAP_MB = 256;
+
+/**
+ * Build a DaemonRunner. Spec fields:
+ *   name              — identifier; used in heartbeat path
+ *   tick(ctx)         — async; returns { didWork: boolean } each cycle
+ *   intervalMs        — sleep between ticks
+ *   killswitchEnv     — process.env key; when '=off' the daemon refuses to start
+ *   heartbeatPath     — file written each tick with { ts, name, ticks }
+ *   lockPath          — single-writer lockfile (defaults to heartbeatPath + .lock)
+ *   maxRuntimeMs      — bounded lifetime; default 24h
+ *   maxIdleTicks      — consecutive zero-work ticks before idle shutdown
+ *   memoryCapMb       — RSS cap; exceeding triggers self-stop + escalation
+ *   onIdleShutdown    — optional callback when the runner stops due to idle
+ *   onMemoryExceeded  — optional callback when the runner stops due to memory
+ */
+export function createDaemon(spec) {
+  if (!spec?.name) throw new Error('daemon spec missing name');
+  if (typeof spec.tick !== 'function') throw new Error('daemon spec missing tick(ctx)');
+
+  const cfg = {
+    intervalMs: spec.intervalMs ?? 60_000,
+    killswitchEnv: spec.killswitchEnv,
+    heartbeatPath: spec.heartbeatPath,
+    lockPath: spec.lockPath || (spec.heartbeatPath ? `${spec.heartbeatPath}.lock` : null),
+    maxRuntimeMs: spec.maxRuntimeMs ?? DEFAULT_MAX_RUNTIME_MS,
+    maxIdleTicks: spec.maxIdleTicks ?? DEFAULT_IDLE_TICKS,
+    memoryCapMb: spec.memoryCapMb ?? DEFAULT_MEMORY_CAP_MB,
+    onIdleShutdown: spec.onIdleShutdown,
+    onMemoryExceeded: spec.onMemoryExceeded,
+  };
+
+  let running = false;
+  let stopRequested = false;
+  let startedAt = 0;
+  let ticks = 0;
+  let idleTicks = 0;
+
+  function killswitchEngaged() {
+    if (!cfg.killswitchEnv) return false;
+    return process.env[cfg.killswitchEnv] === 'off' || process.env[cfg.killswitchEnv] === '0';
+  }
+
+  function acquireLock() {
+    if (!cfg.lockPath) return true;
+    try { mkdirSync(dirname(cfg.lockPath), { recursive: true }); } catch { /* ignore */ }
+    try {
+      writeFileSync(cfg.lockPath, JSON.stringify({ pid: process.pid, startedAt: Date.now() }), { flag: 'wx' });
+      return true;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      const holder = readLockHolder();
+      if (holder && processAlive(holder.pid)) return false;
+      // Stale lock — steal it
+      writeFileSync(cfg.lockPath, JSON.stringify({ pid: process.pid, startedAt: Date.now() }), { flag: 'w' });
+      return true;
+    }
+  }
+
+  function releaseLock() {
+    if (!cfg.lockPath) return;
+    try { unlinkSync(cfg.lockPath); } catch { /* ignore */ }
+  }
+
+  function readLockHolder() {
+    if (!cfg.lockPath || !existsSync(cfg.lockPath)) return null;
+    try { return JSON.parse(readFileSync(cfg.lockPath, 'utf8')); } catch { return null; }
+  }
+
+  function processAlive(pid) {
+    if (!pid) return false;
+    try { process.kill(pid, 0); return true; } catch { return false; }
+  }
+
+  function heartbeat() {
+    if (!cfg.heartbeatPath) return;
+    try { mkdirSync(dirname(cfg.heartbeatPath), { recursive: true }); } catch { /* ignore */ }
+    try {
+      writeFileSync(cfg.heartbeatPath, JSON.stringify({
+        name: spec.name, pid: process.pid, ts: Date.now(), ticks, idleTicks,
+      }));
+    } catch { /* heartbeat is best effort */ }
+  }
+
+  function memoryExceeded() {
+    const rssMb = process.memoryUsage().rss / (1024 * 1024);
+    return rssMb > cfg.memoryCapMb;
+  }
+
+  async function run() {
+    if (killswitchEngaged()) {
+      return { stopped: true, reason: 'killswitch' };
+    }
+    if (!acquireLock()) {
+      return { stopped: true, reason: 'lock-held' };
+    }
+
+    running = true;
+    stopRequested = false;
+    startedAt = Date.now();
+    ticks = 0;
+    idleTicks = 0;
+
+    try {
+      while (running && !stopRequested) {
+        if (Date.now() - startedAt >= cfg.maxRuntimeMs) {
+          return { stopped: true, reason: 'max-runtime', ticks };
+        }
+        if (memoryExceeded()) {
+          if (cfg.onMemoryExceeded) try { await cfg.onMemoryExceeded(); } catch { /* ignore */ }
+          return { stopped: true, reason: 'memory-cap', ticks };
+        }
+        if (killswitchEngaged()) {
+          return { stopped: true, reason: 'killswitch-mid-run', ticks };
+        }
+
+        ticks++;
+        let result;
+        try { result = await spec.tick({ ticks, idleTicks }); }
+        catch (err) { result = { didWork: false, error: err.message }; }
+
+        heartbeat();
+
+        if (result?.didWork) idleTicks = 0;
+        else idleTicks++;
+
+        if (idleTicks >= cfg.maxIdleTicks) {
+          if (cfg.onIdleShutdown) try { await cfg.onIdleShutdown(); } catch { /* ignore */ }
+          return { stopped: true, reason: 'idle', ticks };
+        }
+
+        await sleep(cfg.intervalMs);
+      }
+      return { stopped: true, reason: 'requested', ticks };
+    } finally {
+      running = false;
+      releaseLock();
+    }
+  }
+
+  function stop() { stopRequested = true; }
+
+  function status() {
+    return {
+      name: spec.name,
+      running,
+      ticks,
+      idleTicks,
+      uptimeMs: running ? Date.now() - startedAt : 0,
+      heartbeatPath: cfg.heartbeatPath,
+      lockPath: cfg.lockPath,
+    };
+  }
+
+  return { run, stop, status };
+}
+
+/**
+ * Inspect a heartbeat file written by a DaemonRunner. Returns the heartbeat
+ * if fresh (within staleMs), null if stale or missing.
+ */
+export function readHeartbeat(heartbeatPath, { staleMs = 5 * 60 * 1000 } = {}) {
+  if (!heartbeatPath || !existsSync(heartbeatPath)) return null;
+  try {
+    const data = JSON.parse(readFileSync(heartbeatPath, 'utf8'));
+    const age = Date.now() - (data.ts || 0);
+    if (age > staleMs) return null;
+    return { ...data, ageMs: age };
+  } catch { return null; }
+}
+
+/**
+ * Helper for per-item TTL + retry + dead-letter routing inside a tick. Given
+ * a packet with `firstSeenAt` and optional `attempts`, returns a routing
+ * decision: 'process' (within budget), 'dead-letter' (TTL or retry budget
+ * exhausted), or 'escalate' (past TTL but not yet retried max).
+ */
+export function classifyPacket(packet, { maxAgeMs = 14 * 24 * 60 * 60 * 1000, maxAttempts = 3 } = {}) {
+  const firstSeenAt = packet?.firstSeenAt || packet?.createdAt || Date.now();
+  const attempts = packet?.attempts || 0;
+  const age = Date.now() - new Date(firstSeenAt).getTime();
+  if (age > maxAgeMs) return { route: 'dead-letter', reason: 'ttl-exceeded' };
+  if (attempts >= maxAttempts) return { route: 'dead-letter', reason: 'retry-budget-exhausted' };
+  return { route: 'process', attempts };
+}

package/lib/docs-verify.mjs

@@ -4,9 +4,11 @@
  *
  * Checks:
  * 1. README.md exists and has basic sections
- * 2. AGENTS.md exists and has required sections  
+ * 2. AGENTS.md exists and has required sections
  * 3. plan.md exists and is current (< 7 days)
- * 4. .cx/context.md exists and is current (< 7 days)
+ * 4. .cx/context.md is current (< 7 days, critical when .cx/ exists). Verifier
+ *    reconstitutes the file from the init template when .cx/ exists but the
+ *    file does not — invariant enforcement is centralized here.
  * 5. docs/README.md exists (if docs system initialized)
  * 6. Required documentation lanes exist (if specified in init)
  *
@@ -18,6 +20,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { statSync, readFileSync, existsSync } from "node:fs";
+import { hasIntakeReference } from "./intake/traceability.mjs";
+import { ensureCxDir } from "./project-init-shared.mjs";
 
 const args = process.argv.slice(2);
 const quickMode = args.includes("--quick");
@@ -196,6 +200,37 @@ function checkContextHasProgress(contextPath) {
   }
 }
 
+// Surfaces drift: artifacts under intake-fed locations that lack an
+// intake_id / intake: none frontmatter reference. Advisory (warning) because
+// not every artifact necessarily comes from an intake packet — but the absence
+// is a flag for the operator to either stamp the provenance or declare it
+// intake-independent.
+function checkIntakeTraceability(cwd) {
+  const intakeFedDirs = [
+    path.join(cwd, 'docs', 'prd'),
+    path.join(cwd, 'docs', 'research'),
+    path.join(cwd, '.cx', 'knowledge', 'internal'),
+  ];
+  let inspected = 0;
+  for (const dir of intakeFedDirs) {
+    if (!fs.existsSync(dir)) continue;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+      if (entry.name.startsWith('_') || entry.name.toLowerCase() === 'readme.md') continue;
+      const filePath = path.join(dir, entry.name);
+      inspected += 1;
+      if (!hasIntakeReference(filePath)) {
+        warnings.push(
+          `Intake traceability: ${path.relative(cwd, filePath)} lacks intake_id or "intake: none" in frontmatter — stamp via \`construct intake done <id> --output\` or declare intake-independent.`,
+        );
+      }
+    }
+  }
+  return inspected;
+}
+
 function checkDocsSystem(docsPath) {
   if (!fs.existsSync(docsPath)) {
     // docs/ directory doesn't exist, which is fine if project doesn't use docs system
@@ -331,7 +366,25 @@ function main() {
   // Critical checks (fail CI)
   checkExists(path.join(cwd, "README.md"), "README.md", true);
   checkExists(path.join(cwd, "AGENTS.md"), "AGENTS.md", true);
-  checkExists(path.join(cwd, ".cx", "context.md"), ".cx/context.md", true);
+
+  // .cx/context.md invariant. The verifier is the canonical enforcer: if .cx/
+  // exists but context.md does not, the file is reconstituted from the init
+  // template here. This is consistent with construct init (which creates both
+  // together) and absorbs the case where a subsystem creates a .cx/ subdirectory
+  // for operational reasons without going through ensureCxDir. CI starts with
+  // no .cx/ at all (gitignored) so the block is skipped entirely. Staleness
+  // remains critical — a context.md older than 7 days indicates sessions that
+  // are running without keeping the handoff state current, which is the real
+  // bug the gate exists to catch.
+  const cxDir = path.join(cwd, ".cx");
+  const contextMdPath = path.join(cxDir, "context.md");
+  const cxExists = fs.existsSync(cxDir);
+  if (cxExists) {
+    if (!fs.existsSync(contextMdPath)) {
+      ensureCxDir(cwd);
+    }
+    checkFileAge(contextMdPath, 7, ".cx/context.md", true);
+  }
 
   // plan.md is a local working document — gitignored, not committed.
   // Verify it's healthy when present, but don't fail when it's absent.
@@ -339,16 +392,16 @@ function main() {
 
   // Age checks (fail CI if stale)
   if (planExists) checkFileAge(path.join(cwd, "plan.md"), 7, "plan.md", true);
-  checkFileAge(path.join(cwd, ".cx", "context.md"), 7, ".cx/context.md", true);
 
   if (!quickMode) {
     // Detailed checks (warnings only)
     checkReadmeBasicSections(path.join(cwd, "README.md"));
     checkAgentsRequiredSections(path.join(cwd, "AGENTS.md"));
     if (planExists) checkPlanLinkedToIssues(path.join(cwd, "plan.md"));
-    checkContextHasProgress(path.join(cwd, ".cx", "context.md"));
+    if (cxExists && fs.existsSync(contextMdPath)) checkContextHasProgress(contextMdPath);
     checkDocsSystem(path.join(cwd, "docs"));
-    
+    checkIntakeTraceability(cwd);
+
     // Age warning for README.md (30 days)
     checkFileAge(path.join(cwd, "README.md"), 30, "README.md", false);
   }

package/lib/doctor/cli.mjs

@@ -85,6 +85,7 @@ export async function runCli(args) {
       import('./watchers/process-pressure.mjs'),
       import('./watchers/service-health.mjs'),
       import('./watchers/bd-watch.mjs'),
+      import('./watchers/consistency.mjs'),
     ]);
     for (const w of watchers) {
       const r = await w.tick();
@@ -93,7 +94,21 @@ export async function runCli(args) {
     return 0;
   }
 
+  if (sub === 'consistency') {
+    const { runAllChecks } = await import('./watchers/consistency.mjs');
+    const result = await runAllChecks();
+    const blocking = result.findings.filter((f) => f.severity === 'blocking');
+    const warnings = result.findings.filter((f) => f.severity === 'warning');
+
+    for (const p of result.passed) console.log(`  ✓  ${p.category.padEnd(18)} ${p.summary}`);
+    for (const w of warnings) console.log(`  ⚠  ${w.category.padEnd(18)} ${w.summary}`);
+    for (const b of blocking) console.log(`  ✗  ${b.category.padEnd(18)} ${b.summary}`);
+
+    console.log(`\n${result.passed.length} category(s) clean, ${warnings.length} warning(s), ${blocking.length} blocking finding(s)`);
+    return blocking.length > 0 ? 1 : 0;
+  }
+
   console.error(`Unknown doctor subcommand: ${sub}`);
-  console.error('Usage: construct doctor [status|watch|stop|logs|tick]');
+  console.error('Usage: construct doctor [status|watch|stop|logs|tick|consistency]');
   return 2;
 }

package/lib/doctor/index.mjs

@@ -22,9 +22,11 @@ import * as processPressure from './watchers/process-pressure.mjs';
 import * as serviceHealth from './watchers/service-health.mjs';
 import * as bdWatch from './watchers/bd-watch.mjs';
 import * as handoffs from './watchers/handoffs.mjs';
+import * as consistency from './watchers/consistency.mjs';
+import * as mcpProtocol from './watchers/mcp-protocol.mjs';
 
 const STATE_PATH = join(homedir(), '.construct', 'doctor.json');
-const WATCHERS = [disk, cost, processPressure, serviceHealth, bdWatch, handoffs];
+const WATCHERS = [disk, cost, processPressure, serviceHealth, bdWatch, handoffs, consistency, mcpProtocol];
 
 let running = false;
 let timers = [];

package/lib/doctor/watchers/consistency.mjs

@@ -0,0 +1,310 @@
+/**
+ * lib/doctor/watchers/consistency.mjs — cross-surface drift watcher.
+ *
+ * Five drift checks bundled at one cadence:
+ *   1. Hook manifest ↔ files: every entry in platforms/claude/settings.template.json
+ *      points to a real .mjs file in lib/hooks/ that parses.
+ *   2. MCP registration ↔ impl: every `name === '<tool>'` branch in the MCP
+ *      dispatch resolves to an imported function, and every exported tool
+ *      function in lib/mcp/tools/*.mjs is wired into the dispatch.
+ *   3. Roles ↔ registry: every persona key in agents/role-manifests.json
+ *      resolves to a persona or agent name in agents/registry.json.
+ *   4. Persona promptFiles: every registry.personas[].promptFile and
+ *      registry.agents[].promptFile exists on disk.
+ *   5. Contracts ↔ schemas: agents/contracts.json passes validateContractsFile
+ *      (cross-file refs, producer/consumer names, schema paths).
+ *
+ * Each violation produces an audit record. Blocking severity escalates to a
+ * role intake; advisory severity records only. Tick is cheap — reads JSON +
+ * directory listings, no network.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { record } from '../audit.mjs';
+import { escalate } from '../escalate.mjs';
+
+export const name = 'consistency';
+export const intervalMs = 15 * 60 * 1000;
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+
+export async function tick() {
+  const results = await runAllChecks({ repoRoot: REPO_ROOT });
+  const actions = [];
+  const escalations = [];
+
+  for (const finding of results.findings) {
+    record({
+      kind: finding.severity === 'blocking' ? 'escalation' : 'action',
+      watcher: name,
+      action: finding.category,
+      summary: finding.summary,
+      context: { details: finding.details },
+    });
+    actions.push({ type: finding.category, target: finding.target || null });
+    if (finding.severity === 'blocking') {
+      escalate({
+        watcher: name,
+        event: `consistency.${finding.category}`,
+        severity: 'high',
+        summary: finding.summary,
+        context: { details: finding.details },
+      });
+      escalations.push({ event: `consistency.${finding.category}`, severity: 'high' });
+    }
+  }
+
+  return { actions, escalations };
+}
+
+/**
+ * Run all five consistency checks. Returns { findings: [], passed: [] }.
+ * Pure function — no audit/escalate side effects. Surfaced separately so the
+ * `construct doctor consistency` CLI and the release-gate functional test can
+ * call it without spinning up the daemon.
+ */
+export async function runAllChecks({ repoRoot = REPO_ROOT } = {}) {
+  const findings = [];
+  const passed = [];
+
+  const hooks = checkHooksDrift({ repoRoot });
+  collect(hooks, findings, passed, 'hooks-drift');
+
+  const mcp = checkMcpDrift({ repoRoot });
+  collect(mcp, findings, passed, 'mcp-drift');
+
+  const roles = checkRolesDrift({ repoRoot });
+  collect(roles, findings, passed, 'roles-drift');
+
+  const prompts = checkPersonaPrompts({ repoRoot });
+  collect(prompts, findings, passed, 'prompt-files');
+
+  const contracts = await checkContractsDrift({ repoRoot });
+  collect(contracts, findings, passed, 'contracts-drift');
+
+  return { findings, passed };
+}
+
+function collect(result, findings, passed, defaultCategory) {
+  if (result.violations.length === 0) {
+    passed.push({ category: defaultCategory, summary: result.summary });
+    return;
+  }
+  for (const v of result.violations) {
+    findings.push({
+      category: v.category || defaultCategory,
+      severity: v.severity || 'warning',
+      summary: v.summary,
+      target: v.target || null,
+      details: v.details || null,
+    });
+  }
+}
+
+// ── Check 1: hook manifest ↔ files ─────────────────────────────────────────
+
+function checkHooksDrift({ repoRoot }) {
+  const violations = [];
+  const settingsPath = join(repoRoot, 'platforms', 'claude', 'settings.template.json');
+  const hooksDir = join(repoRoot, 'lib', 'hooks');
+
+  if (!existsSync(settingsPath)) {
+    return {
+      summary: 'settings template missing',
+      violations: [{ severity: 'blocking', summary: `settings template missing: ${settingsPath}` }],
+    };
+  }
+
+  let settings;
+  try { settings = JSON.parse(readFileSync(settingsPath, 'utf8')); }
+  catch (err) {
+    return {
+      summary: 'settings template parse error',
+      violations: [{ severity: 'blocking', summary: `settings template parse error: ${err.message}` }],
+    };
+  }
+
+  const referenced = new Set();
+  collectHookCommands(settings.hooks, referenced);
+
+  for (const hookPath of referenced) {
+    const resolvedPath = resolveHookPath(hookPath, hooksDir, repoRoot);
+    if (!resolvedPath || !existsSync(resolvedPath)) {
+      violations.push({
+        category: 'hooks-drift',
+        severity: 'blocking',
+        target: hookPath,
+        summary: `hook referenced by settings template does not exist on disk: ${hookPath}`,
+      });
+    }
+  }
+
+  return { summary: `hooks: ${referenced.size} referenced, ${violations.length} missing`, violations };
+}
+
+function collectHookCommands(node, out) {
+  if (!node) return;
+  if (Array.isArray(node)) { node.forEach((n) => collectHookCommands(n, out)); return; }
+  if (typeof node !== 'object') return;
+  if (typeof node.command === 'string' && /\.mjs/.test(node.command)) {
+    const match = node.command.match(/([\w./-]+\.mjs)/);
+    if (match) out.add(match[1]);
+  }
+  for (const v of Object.values(node)) collectHookCommands(v, out);
+}
+
+function resolveHookPath(reference, hooksDir, repoRoot) {
+  if (reference.startsWith('/')) return reference;
+  if (reference.startsWith('lib/hooks/')) return join(repoRoot, reference);
+  const bare = reference.split('/').pop();
+  return join(hooksDir, bare);
+}
+
+// ── Check 2: MCP registration ↔ impl ───────────────────────────────────────
+
+function checkMcpDrift({ repoRoot }) {
+  const violations = [];
+  const serverPath = join(repoRoot, 'lib', 'mcp', 'server.mjs');
+  const toolsDir = join(repoRoot, 'lib', 'mcp', 'tools');
+
+  if (!existsSync(serverPath) || !existsSync(toolsDir)) {
+    return { summary: 'mcp surface missing', violations: [] };
+  }
+
+  const serverSource = readFileSync(serverPath, 'utf8');
+  const dispatchedTools = new Set();
+  for (const m of serverSource.matchAll(/name === ['"]([a-z][a-z0-9_]*)['"]/g)) {
+    dispatchedTools.add(m[1]);
+  }
+
+  const exportedTools = new Set();
+  const entries = readdirSync(toolsDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.mjs')) continue;
+    const src = readFileSync(join(toolsDir, entry.name), 'utf8');
+    for (const m of src.matchAll(/export (?:async )?function (\w+)/g)) {
+      exportedTools.add(camelToSnake(m[1]));
+    }
+  }
+
+  for (const tool of exportedTools) {
+    if (KNOWN_NON_DISPATCH_TOOLS.has(tool)) continue;
+    if (!dispatchedTools.has(tool)) {
+      violations.push({
+        category: 'mcp-drift',
+        severity: 'warning',
+        target: tool,
+        summary: `MCP tool exported but not dispatched: ${tool}`,
+      });
+    }
+  }
+
+  return { summary: `mcp: ${dispatchedTools.size} dispatched, ${exportedTools.size} exported, ${violations.length} drift`, violations };
+}
+
+const KNOWN_NON_DISPATCH_TOOLS = new Set([
+  // Internal helpers exported for tests but never wired through MCP.
+  'workflow_status_bound',
+  'create_needs_main_input_packet',
+]);
+
+function camelToSnake(s) {
+  return s.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+}
+
+// ── Check 3: roles ↔ registry ──────────────────────────────────────────────
+
+function checkRolesDrift({ repoRoot }) {
+  const violations = [];
+  const manifestsPath = join(repoRoot, 'agents', 'role-manifests.json');
+  const registryPath = join(repoRoot, 'agents', 'registry.json');
+
+  if (!existsSync(manifestsPath) || !existsSync(registryPath)) {
+    return { summary: 'role manifests or registry missing', violations: [] };
+  }
+
+  const manifests = JSON.parse(readFileSync(manifestsPath, 'utf8'));
+  const registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+
+  const known = new Set();
+  for (const a of registry.agents || []) {
+    if (a?.name) { known.add(a.name); known.add(`cx-${a.name}`); }
+  }
+  for (const p of registry.personas || []) {
+    if (p?.name) { known.add(p.name); known.add(`cx-${p.name}`); }
+  }
+
+  const personaKeys = Object.keys(manifests.personas || manifests || {});
+  for (const key of personaKeys) {
+    if (key === 'version' || key === 'description' || key === 'schemaVersion') continue;
+    if (!known.has(key) && !known.has(`cx-${key}`)) {
+      violations.push({
+        category: 'roles-drift',
+        severity: 'warning',
+        target: key,
+        summary: `role-manifests persona '${key}' does not resolve to a registry persona/agent`,
+      });
+    }
+  }
+
+  return { summary: `roles: ${personaKeys.length} manifest keys, ${violations.length} drift`, violations };
+}
+
+// ── Check 4: persona promptFile existence ──────────────────────────────────
+
+function checkPersonaPrompts({ repoRoot }) {
+  const violations = [];
+  const registryPath = join(repoRoot, 'agents', 'registry.json');
+  if (!existsSync(registryPath)) return { summary: 'registry missing', violations: [] };
+
+  const registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+  let checked = 0;
+
+  for (const list of [registry.personas || [], registry.agents || []]) {
+    for (const entry of list) {
+      const ref = entry?.promptFile;
+      if (!ref) continue;
+      checked++;
+      const promptPath = ref.startsWith('/') ? ref : join(repoRoot, ref);
+      if (!existsSync(promptPath)) {
+        violations.push({
+          category: 'prompt-files',
+          severity: 'blocking',
+          target: ref,
+          summary: `registry entry '${entry.name}' references missing promptFile: ${ref}`,
+        });
+      }
+    }
+  }
+
+  return { summary: `prompt-files: ${checked} referenced, ${violations.length} missing`, violations };
+}
+
+// ── Check 5: contracts ↔ schemas ───────────────────────────────────────────
+
+async function checkContractsDrift({ repoRoot }) {
+  const violations = [];
+  try {
+    const { validateContractsFile } = await import('../../contracts/validate.mjs');
+    const result = validateContractsFile({ repoRoot });
+    if (!result.ok) {
+      for (const err of result.errors) {
+        violations.push({
+          category: 'contracts-drift',
+          severity: 'warning',
+          summary: err,
+        });
+      }
+    }
+  } catch (err) {
+    violations.push({
+      category: 'contracts-drift',
+      severity: 'warning',
+      summary: `contract validator unavailable: ${err.message}`,
+    });
+  }
+  return { summary: `contracts: ${violations.length} drift`, violations };
+}