@geraldmaron/construct 1.0.6 → 1.0.7

package/lib/contracts/validate.mjs

@@ -0,0 +1,323 @@
+/**
+ * lib/contracts/validate.mjs — Validate agents/contracts.json at sync time + at handoff.
+ *
+ * Three validation tiers:
+ *   1. Schema shape: contracts.json conforms to contracts.schema.json (minimal
+ *      validator — top-level required fields, contract entry required fields).
+ *   2. Cross-file refs: every output.schema points to a real file in lib/schemas/,
+ *      every producer/consumer name resolves to an agent or persona in
+ *      agents/registry.json, every well-known event/intake string is reachable.
+ *   3. Runtime handoff: a single artifact validated against the schema referenced
+ *      by a producer→consumer contract, with mustContain post-conditions.
+ *
+ * Surfaces:
+ *   - scripts/sync-agents.mjs invokes validateContractsFile at sync time.
+ *   - bin/construct lint:contracts invokes the same path in CI.
+ *   - workflowContractValidate (runtime) invokes validateHandoff per handoff.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const CONTRACTS_PATH = join(REPO_ROOT, 'agents', 'contracts.json');
+const CONTRACTS_SCHEMA_PATH = join(REPO_ROOT, 'agents', 'contracts.schema.json');
+const REGISTRY_PATH = join(REPO_ROOT, 'agents', 'registry.json');
+
+const WELL_KNOWN_PRODUCERS = new Set(['user', 'oncall', 'incident-system', '*']);
+const WELL_KNOWN_CONSUMERS = new Set(['user', 'construct']);
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+/**
+ * Validate agents/contracts.json shape and cross-file references.
+ * Returns { ok, errors[] } — errors is empty on success.
+ */
+export function validateContractsFile({ contractsPath, registryPath, repoRoot = REPO_ROOT } = {}) {
+  const errors = [];
+
+  // When repoRoot is supplied but explicit paths are not, derive both from it
+  // so test fixtures and the consistency watcher can validate slices in a
+  // tmpdir without pointing at the live repo.
+  const cPath = contractsPath || join(repoRoot, 'agents', 'contracts.json');
+  const rPath = registryPath || join(repoRoot, 'agents', 'registry.json');
+  const schemaPath = join(repoRoot, 'agents', 'contracts.schema.json');
+
+  if (!existsSync(cPath)) {
+    return { ok: false, errors: [`contracts file not found: ${cPath}`] };
+  }
+  if (!existsSync(schemaPath)) {
+    errors.push(`contracts schema missing: ${schemaPath}`);
+  }
+
+  let contracts;
+  try { contracts = readJson(cPath); }
+  catch (err) { return { ok: false, errors: [`contracts.json parse error: ${err.message}`] }; }
+
+  for (const key of ['version', 'terminalStates', 'severities', 'contracts']) {
+    if (!(key in contracts)) errors.push(`contracts.json missing top-level field: ${key}`);
+  }
+
+  const knownNames = collectAgentNames(rPath);
+
+  if (Array.isArray(contracts.contracts)) {
+    const ids = new Set();
+    contracts.contracts.forEach((c, idx) => {
+      const where = `contracts[${idx}]${c.id ? ` (${c.id})` : ''}`;
+      if (!c.id) errors.push(`${where}: missing id`);
+      else if (!/^[a-z0-9][a-z0-9-]*$/.test(c.id)) errors.push(`${where}: id must be kebab-case`);
+      else if (ids.has(c.id)) errors.push(`${where}: duplicate id`);
+      else ids.add(c.id);
+
+      if (!c.producer) errors.push(`${where}: missing producer`);
+      if (!c.consumer) errors.push(`${where}: missing consumer`);
+      if (!c.input) errors.push(`${where}: missing input`);
+
+      if (c.producer && !nameResolves(c.producer, knownNames, 'producer')) {
+        errors.push(`${where}: producer '${c.producer}' is not an agent/persona in registry.json and is not a well-known producer`);
+      }
+      if (c.consumer && !nameResolves(c.consumer, knownNames, 'consumer')) {
+        errors.push(`${where}: consumer '${c.consumer}' is not an agent/persona in registry.json and is not a well-known consumer`);
+      }
+
+      const schemaRef = c.output?.schema;
+      if (schemaRef) {
+        const outputSchemaPath = join(repoRoot, schemaRef);
+        if (!existsSync(outputSchemaPath)) {
+          errors.push(`${where}: output.schema '${schemaRef}' does not exist on disk`);
+        } else {
+          try { readJson(outputSchemaPath); }
+          catch (err) { errors.push(`${where}: output.schema '${schemaRef}' is not valid JSON: ${err.message}`); }
+        }
+      }
+    });
+  } else {
+    errors.push('contracts.json: contracts must be an array');
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+function nameResolves(name, knownNames, role) {
+  if (WELL_KNOWN_PRODUCERS.has(name) && role === 'producer') return true;
+  if (WELL_KNOWN_CONSUMERS.has(name) && role === 'consumer') return true;
+  if (knownNames.has(name)) return true;
+  // Persona registry stores names without the cx- prefix; contracts.json
+  // conventionally uses the cx-prefixed form. Normalize both directions.
+  const stripped = name.startsWith('cx-') ? name.slice(3) : `cx-${name}`;
+  return knownNames.has(stripped);
+}
+
+function collectAgentNames(registryPath) {
+  const names = new Set();
+  if (!existsSync(registryPath)) return names;
+  try {
+    const registry = readJson(registryPath);
+    for (const a of registry.agents || []) {
+      if (a?.name) names.add(a.name);
+      if (a?.displayName) names.add(a.displayName);
+    }
+    for (const p of registry.personas || []) {
+      if (p?.name) names.add(p.name);
+      if (p?.displayName) names.add(p.displayName);
+    }
+  } catch { /* fall through with whatever names we collected */ }
+  return names;
+}
+
+/**
+ * Look up a contract by producer/consumer pair (and optional id).
+ */
+export function findContract({ producer, consumer, id, contractsPath = CONTRACTS_PATH }) {
+  if (!existsSync(contractsPath)) return null;
+  let contracts;
+  try { contracts = readJson(contractsPath); } catch { return null; }
+  const list = contracts.contracts || [];
+  if (id) return list.find((c) => c.id === id) || null;
+  return list.find((c) => c.producer === producer && c.consumer === consumer) || null;
+}
+
+/**
+ * Validate a single artifact against its contract at handoff time.
+ *
+ * Returns one of:
+ *   { ok: true, contract }
+ *   { ok: false, status: 'BLOCKED_CONTRACT', errors[], contract }
+ *
+ * Enforcement defaults to the value of process.env.CONSTRUCT_CONTRACT_ENFORCEMENT
+ * ('warn' or 'block'), and may be overridden by the caller. In warn mode the
+ * result includes errors but ok stays true so a session is not blocked.
+ */
+export function validateHandoff({
+  producer,
+  consumer,
+  id,
+  artifact,
+  contractsPath = CONTRACTS_PATH,
+  repoRoot = REPO_ROOT,
+  enforcement = process.env.CONSTRUCT_CONTRACT_ENFORCEMENT || 'warn',
+}) {
+  const contract = findContract({ producer, consumer, id, contractsPath });
+  if (!contract) {
+    return enforcement === 'block'
+      ? { ok: false, status: 'BLOCKED_CONTRACT', errors: [`no contract found for ${producer}→${consumer}${id ? ` id=${id}` : ''}`], contract: null }
+      : { ok: true, warnings: [`no contract found for ${producer}→${consumer}`], contract: null };
+  }
+
+  const errors = [];
+
+  // A handoff carries a producer's output, which is the consumer's input. The
+  // input contract is what the consumer expects to receive; check mustContain
+  // against that first. Output.schema validation only applies when the artifact
+  // declares the matching `type` (e.g. the consumer is forwarding its own
+  // produced artifact downstream).
+  const inputMustContain = contract.input?.mustContain || [];
+  for (const field of inputMustContain) {
+    if (!hasField(artifact, field)) {
+      errors.push(`artifact missing required field: ${field}`);
+    }
+  }
+
+  const outputType = contract.output?.type;
+  const schemaRef = contract.output?.schema;
+  if (schemaRef && outputType && artifact && artifact.type === outputType) {
+    const schemaPath = join(repoRoot, schemaRef);
+    if (!existsSync(schemaPath)) {
+      errors.push(`contract output.schema '${schemaRef}' does not exist on disk`);
+    } else {
+      const schema = readJson(schemaPath);
+      for (const field of schema.required || []) {
+        if (!hasField(artifact, field)) errors.push(`artifact missing schema-required field: ${field}`);
+      }
+    }
+  }
+
+  // Postcondition checks run against the artifact file on disk when the
+  // handoff envelope declares `artifactPath`. Resolved relative to repoRoot.
+  const declaredArtifactPath = artifact?.artifactPath || artifact?.output?.artifactPath;
+  if (declaredArtifactPath) {
+    const absPath = isAbsolutePath(declaredArtifactPath)
+      ? declaredArtifactPath
+      : join(repoRoot, declaredArtifactPath);
+    const pcErrors = validatePostconditions({ contract, artifactPath: absPath });
+    for (const e of pcErrors) errors.push(e);
+  }
+
+  if (errors.length === 0) return { ok: true, contract };
+  if (enforcement === 'block') return { ok: false, status: 'BLOCKED_CONTRACT', errors, contract };
+  return { ok: true, warnings: errors, contract };
+}
+
+function isAbsolutePath(p) {
+  return p.startsWith('/') || /^[A-Za-z]:[\\/]/.test(p);
+}
+
+function hasField(obj, field) {
+  if (obj == null) return false;
+  if (typeof obj !== 'object') return false;
+  return Object.prototype.hasOwnProperty.call(obj, field) && obj[field] != null && obj[field] !== '';
+}
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+
+function parseArtifactFrontmatter(text) {
+  const m = text.match(FRONTMATTER_RE);
+  if (!m) return { frontmatter: {}, body: text };
+  const fm = {};
+  for (const line of m[1].split('\n')) {
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const rawValue = line.slice(idx + 1).trim();
+    if (key) fm[key] = rawValue.replace(/^["']|["']$/g, '');
+  }
+  return { frontmatter: fm, body: text.slice(m[0].length) };
+}
+
+function hasSection(body, sectionTitle) {
+  const target = sectionTitle.trim().toLowerCase();
+  const headingRe = /^#{1,6}\s+(.+)$/gm;
+  let m;
+  while ((m = headingRe.exec(body))) {
+    if (m[1].trim().toLowerCase() === target) return true;
+  }
+  return false;
+}
+
+function claimsHaveCitations(body) {
+  const lines = body.split('\n');
+  const offenders = [];
+  let inFence = false;
+  let inTable = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^```/.test(line)) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    inTable = /^\s*\|.*\|\s*$/.test(line);
+    if (inTable) continue;
+    if (/\b\d{1,3}\s*%/.test(line) || /\b\d{2,}x\b/i.test(line)) {
+      const window = [lines[i - 1] || '', line, lines[i + 1] || ''].join('\n');
+      if (!/\[source:|\bhttps?:\/\/|\[\^\d+\]/i.test(window)) {
+        offenders.push({ line: i + 1, snippet: line.trim().slice(0, 80) });
+      }
+    }
+  }
+  return offenders;
+}
+
+/**
+ * Run structured postcondition checks against a handoff's output artifact on
+ * disk. Postconditions can be strings (descriptive, ignored here) or objects
+ * with { id, check, field?, section? }. Returns an array of error strings.
+ */
+export function validatePostconditions({ contract, artifactPath }) {
+  if (!contract?.postconditions?.length) return [];
+  if (!artifactPath || !existsSync(artifactPath)) {
+    const structured = contract.postconditions.filter((p) => typeof p === 'object');
+    if (structured.length === 0) return [];
+    return [`postcondition checks declared but artifact not found on disk: ${artifactPath}`];
+  }
+  const text = readFileSync(artifactPath, 'utf8');
+  const { frontmatter, body } = parseArtifactFrontmatter(text);
+  const errors = [];
+  for (const pc of contract.postconditions) {
+    if (typeof pc !== 'object') continue;
+    const tag = pc.id || pc.check;
+    switch (pc.check) {
+      case 'artifact-has-frontmatter-field': {
+        if (!pc.field) {
+          errors.push(`[${tag}] postcondition missing 'field' for artifact-has-frontmatter-field`);
+          break;
+        }
+        if (!frontmatter[pc.field]) {
+          errors.push(`[${tag}] artifact missing frontmatter field: ${pc.field}`);
+        }
+        break;
+      }
+      case 'artifact-has-section': {
+        if (!pc.section) {
+          errors.push(`[${tag}] postcondition missing 'section' for artifact-has-section`);
+          break;
+        }
+        if (!hasSection(body, pc.section)) {
+          errors.push(`[${tag}] artifact missing required section: "${pc.section}"`);
+        }
+        break;
+      }
+      case 'artifact-claims-cited': {
+        const offenders = claimsHaveCitations(body);
+        for (const o of offenders) {
+          errors.push(`[${tag}] uncited numeric claim at line ${o.line}: ${o.snippet}`);
+        }
+        break;
+      }
+      default:
+        errors.push(`[${tag}] unknown postcondition check: ${pc.check}`);
+    }
+  }
+  return errors;
+}

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 = [];