@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/agent-contracts-enforce.mjs

@@ -0,0 +1,158 @@
+/**
+ * lib/agent-contracts-enforce.mjs — runtime contract enforcement.
+ *
+ * Wraps `validatePacket` from `lib/agent-contracts.mjs` with three production
+ * concerns:
+ *
+ *   1. Block on violation. `enforcePacket` throws a `ContractViolationError`
+ *      when the packet doesn't satisfy the contract direction. Callers can
+ *      catch and degrade if they want advisory mode, but the default is hard
+ *      enforcement so contract bugs surface loudly.
+ *
+ *   2. Tamper-evident violation log. Every violation appends a JSONL record
+ *      to `~/.cx/contract-violations.jsonl` with a sha256 chain-hash over
+ *      the prior line. Same pattern as the mutation audit trail. Operators
+ *      can replay the chain to detect after-the-fact tampering.
+ *
+ *   3. Visibility into `construct doctor`. `recentViolations(windowMs)`
+ *      returns the last N violations so doctor can surface
+ *      "3 contract violations in the last 24h — see ~/.cx/contract-violations.jsonl".
+ *
+ * The enforcement is identity-aware. Each violation logs the active agent
+ * (via `~/.cx/last-agent.json` like audit-trail does) so operators can
+ * identify which producer or consumer is at fault.
+ */
+
+import { existsSync, mkdirSync, statSync, readFileSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { getContractById, validatePacket } from './agent-contracts.mjs';
+import { validatePostconditions } from './agents/postconditions.mjs';
+
+const CX_DIR = join(homedir(), '.cx');
+const LOG_FILE = join(CX_DIR, 'contract-violations.jsonl');
+const LAST_AGENT = join(CX_DIR, 'last-agent.json');
+
+export class ContractViolationError extends Error {
+  constructor({ contractId, direction, missing, verdict = 'CONTRACT_VIOLATION', postconditionFailures = [] }) {
+    const detail = postconditionFailures.length > 0
+      ? `postcondition(s) failed: ${postconditionFailures.map((f) => f.id).join(', ')}`
+      : `missing field(s): ${(missing || []).join(', ')}`;
+    super(`contract '${contractId}' (${direction}) violated — ${detail}`);
+    this.name = 'ContractViolationError';
+    this.contractId = contractId;
+    this.direction = direction;
+    this.missing = missing || [];
+    this.verdict = verdict;
+    this.postconditionFailures = postconditionFailures;
+  }
+}
+
+function sha256(input) { return createHash('sha256').update(input).digest('hex'); }
+
+function readLastAgent() {
+  try { return JSON.parse(readFileSync(LAST_AGENT, 'utf8'))?.agent || 'construct'; }
+  catch { return 'construct'; }
+}
+
+function readPrevLineHash() {
+  try {
+    if (!existsSync(LOG_FILE)) return null;
+    const size = statSync(LOG_FILE).size;
+    if (size === 0) return null;
+    const tail = readFileSync(LOG_FILE, 'utf8').slice(Math.max(0, size - 2048));
+    const lines = tail.split('\n').filter(Boolean);
+    return lines.length === 0 ? null : sha256(lines[lines.length - 1]);
+  } catch { return null; }
+}
+
+function logViolation(contractId, direction, missing, packet, extra = {}) {
+  try {
+    mkdirSync(CX_DIR, { recursive: true });
+    const record = {
+      ts: new Date().toISOString(),
+      agent: readLastAgent(),
+      contractId,
+      direction,
+      missing,
+      packet_keys: packet && typeof packet === 'object' ? Object.keys(packet) : null,
+      prev_line_hash: readPrevLineHash(),
+      ...extra,
+    };
+    appendFileSync(LOG_FILE, JSON.stringify(record) + '\n', 'utf8');
+  } catch { /* logging is best-effort */ }
+}
+
+/**
+ * Validate `packet` against `contractId` in the given `direction`. Throws
+ * a `ContractViolationError` on failure (and logs the violation). Returns
+ * the validation result on success so callers can inspect the resolved
+ * contract metadata.
+ *
+ * For `direction === 'output'`, also evaluates the producer's binary
+ * postconditions from `lib/agents/postconditions.mjs`. A failed postcondition
+ * raises with `verdict: 'BLOCKED_CONTRACT'` so the dispatcher can branch on
+ * the typed verdict rather than parsing the error message.
+ *
+ * @param {string} contractId
+ * @param {object} packet
+ * @param {'input'|'output'} [direction]
+ * @returns {{ ok: true, contract, direction }}
+ */
+export function enforcePacket(contractId, packet, direction = 'input') {
+  const result = validatePacket(contractId, packet, direction);
+  if (!result.ok) {
+    if (result.reason === 'contract-not-found') {
+      throw new ContractViolationError({
+        contractId,
+        direction,
+        missing: ['(contract not found)'],
+      });
+    }
+    logViolation(contractId, direction, result.missing || [], packet);
+    throw new ContractViolationError({
+      contractId,
+      direction,
+      missing: result.missing || [],
+    });
+  }
+
+  if (direction === 'output') {
+    const contract = result.contract || getContractById(contractId);
+    const producer = contract?.producer;
+    if (producer) {
+      const postcondition = validatePostconditions(producer, packet);
+      if (!postcondition.ok) {
+        logViolation(contractId, direction, [], packet, {
+          verdict: 'BLOCKED_CONTRACT',
+          postconditionFailures: postcondition.failures,
+        });
+        throw new ContractViolationError({
+          contractId,
+          direction,
+          verdict: 'BLOCKED_CONTRACT',
+          postconditionFailures: postcondition.failures,
+        });
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Read recent violations from the chain log. Returns oldest-first.
+ */
+export function recentViolations({ windowMs = 24 * 60 * 60 * 1000 } = {}) {
+  if (!existsSync(LOG_FILE)) return [];
+  try {
+    const cutoff = Date.now() - windowMs;
+    return readFileSync(LOG_FILE, 'utf8')
+      .trim()
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => { try { return JSON.parse(line); } catch { return null; } })
+      .filter((r) => r && new Date(r.ts).getTime() >= cutoff);
+  } catch { return []; }
+}

package/lib/agent-contracts.mjs

@@ -0,0 +1,231 @@
+/**
+ * lib/agent-contracts.mjs — loader + query layer for agents/contracts.json.
+ *
+ * Agent contracts are explicit service contracts between Construct roles —
+ * "when cx-product-manager hands off to cx-architect, the packet MUST contain
+ * X and the response MUST be shape Y." Single machine-readable source of
+ * truth for handoff schemas, doc ownership, specialist mappings, and the
+ * framing/research gates.
+ *
+ * Consumed by:
+ *   - lib/orchestration-policy.mjs → routeRequest returns the contract chain
+ *     for a request, not just a list of specialists.
+ *   - lib/mcp/server.mjs → exposes agent_contract MCP tool for specialists
+ *     to introspect their inputs and expected outputs at handoff time.
+ *   - future: handoff validators that check packet shape before dispatch.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(MODULE_DIR, '..');
+const CONTRACTS_PATH = join(REPO_ROOT, 'agents', 'contracts.json');
+
+let _cache = null;
+
+function loadRaw() {
+  if (_cache) return _cache;
+  if (!existsSync(CONTRACTS_PATH)) {
+    _cache = { version: 0, contracts: [] };
+    return _cache;
+  }
+  try {
+    _cache = JSON.parse(readFileSync(CONTRACTS_PATH, 'utf8'));
+  } catch (err) {
+    _cache = { version: 0, contracts: [], parseError: err?.message || String(err) };
+  }
+  return _cache;
+}
+
+export function getAllContracts() {
+  return loadRaw().contracts || [];
+}
+
+export function getContractById(id) {
+  return getAllContracts().find((c) => c.id === id) || null;
+}
+
+/**
+ * Returns the contract for a specific producer→consumer pair. If multiple
+ * contracts match (e.g. wildcard producer "*"), returns the most specific one.
+ */
+export function getContract(producer, consumer) {
+  const all = getAllContracts();
+  const exact = all.find((c) => c.producer === producer && c.consumer === consumer);
+  if (exact) return exact;
+  return all.find((c) => (c.producer === '*' && c.consumer === consumer)) || null;
+}
+
+/**
+ * Returns all contracts where the given agent is the consumer — the set of
+ * inbound packets the agent is expected to receive from upstream producers.
+ */
+export function getIncomingContracts(consumer) {
+  return getAllContracts().filter((c) => c.consumer === consumer);
+}
+
+/**
+ * Returns all contracts where the given agent is the producer — the set of
+ * outbound packets the agent is expected to send to downstream consumers.
+ */
+export function getOutgoingContracts(producer) {
+  return getAllContracts().filter((c) => c.producer === producer || c.producer === '*');
+}
+
+/**
+ * Matches contracts whose `trigger` is satisfied by the given routing
+ * context. Surfaces which contracts apply to a dispatch plan so routeRequest
+ * can attach them to the response.
+ *
+ * Trigger language:
+ *   { always: true }                              → always fires
+ *   { intent: "fix" | ["fix","investigation"] }    → intent match
+ *   { workCategory: "deep" }                       → work category match
+ *   { track: "orchestrated" }                      → execution track match
+ *   { riskFlags: ["security"] }                    → any-of risk flags set
+ *   { "framingChallenge.required": true }          → gate required
+ *   { "externalResearch.required": true }          → gate required
+ *   { "docAuthoring.docType": ["prd","adr"] }      → authoring intent match
+ *   { postConsumer: true, changedCoreDocs: true }  → fires after consumer ran and core docs changed
+ */
+export function triggerMatches(contract, ctx = {}) {
+  const t = contract.trigger || {};
+  if (t.always === true) return true;
+
+  // intent: string | string[]
+  if (t.intent) {
+    const intents = Array.isArray(t.intent) ? t.intent : [t.intent];
+    if (!intents.includes(ctx.intent)) return false;
+  }
+  if (t.workCategory) {
+    const cats = Array.isArray(t.workCategory) ? t.workCategory : [t.workCategory];
+    if (!cats.includes(ctx.workCategory)) return false;
+  }
+  if (t.track) {
+    const tracks = Array.isArray(t.track) ? t.track : [t.track];
+    if (!tracks.includes(ctx.track)) return false;
+  }
+  if (Array.isArray(t.riskFlags)) {
+    const anyMatch = t.riskFlags.some((flag) => ctx.riskFlags?.[flag]);
+    if (!anyMatch) return false;
+  }
+  if (t['framingChallenge.required'] === true) {
+    if (!ctx.framingChallenge?.required) return false;
+  }
+  if (t['externalResearch.required'] === true) {
+    if (!ctx.externalResearch?.required) return false;
+  }
+  if (t['docAuthoring.docType']) {
+    const docTypes = Array.isArray(t['docAuthoring.docType'])
+      ? t['docAuthoring.docType']
+      : [t['docAuthoring.docType']];
+    if (!ctx.docAuthoring?.docType || !docTypes.includes(ctx.docAuthoring.docType)) return false;
+  }
+  // Post-consumer contracts (e.g. docs-keeper) fire as side effects, not
+  // from the initial routing decision. They're returned by
+  // resolveContractChain but marked so callers can defer them.
+  return true;
+}
+
+function contractParticipantsApply(contract, ctx = {}) {
+  const specialists = Array.isArray(ctx.specialists) ? ctx.specialists : null;
+  if (!specialists) return true;
+
+  const participants = new Set(['user', 'construct', ...specialists]);
+  const producerApplies = contract.producer === '*' || participants.has(contract.producer);
+  const consumerApplies = participants.has(contract.consumer);
+  return producerApplies && consumerApplies;
+}
+
+/**
+ * Returns the ordered contract chain that applies to a routing context.
+ * Each element is `{ contract, stage }` where stage is "precheck" (runs
+ * before work begins), "handoff" (runs between specialists), or "followup"
+ * (runs after DONE, e.g. docs-keeper).
+ */
+export function resolveContractChain(ctx = {}) {
+  const chain = [];
+  for (const contract of getAllContracts()) {
+    if (!triggerMatches(contract, ctx)) continue;
+    if (!contractParticipantsApply(contract, ctx)) continue;
+    const stage = contract.trigger?.postConsumer ? 'followup'
+      : contract.producer === 'user' ? 'precheck'
+      : 'handoff';
+    chain.push({ contract, stage });
+  }
+  return chain;
+}
+
+function fieldPresent(packet, key) {
+  const value = packet?.[key];
+  if (value === undefined || value === null) return false;
+  if (typeof value === 'string' && value.trim() === '') return false;
+  return true;
+}
+
+/**
+ * Lightweight shape validation for handoff packets. Checks three shapes:
+ *   mustContain     — every key must be present (non-null, non-empty-string).
+ *   mustContainOneOf — array of OR groups; at least one field in each group
+ *                      must be present. Missing entries report joined keys:
+ *                      ["findings", "noIssuesFoundAt"] → "findings|noIssuesFoundAt".
+ *   mustMatchEnum   — map of key → allowed values. Mismatch reports
+ *                      "<key>!=<allowed>" so callers can branch on it.
+ *
+ * Empty arrays and empty objects count as present — they signal "declared
+ * but empty," a legitimate state. Use `mustHaveNonEmpty` in a future spec
+ * if you need a stricter check.
+ */
+export function validatePacket(contractId, packet, direction = 'input') {
+  const contract = getContractById(contractId);
+  if (!contract) return { ok: false, reason: 'contract-not-found', contractId };
+  const spec = direction === 'input' ? contract.input : contract.output;
+  if (!spec) return { ok: true, contract, direction };
+
+  const missing = [];
+
+  if (Array.isArray(spec.mustContain)) {
+    for (const key of spec.mustContain) {
+      if (!fieldPresent(packet, key)) missing.push(key);
+    }
+  }
+
+  if (Array.isArray(spec.mustContainOneOf)) {
+    for (const group of spec.mustContainOneOf) {
+      if (!Array.isArray(group) || group.length === 0) continue;
+      const anyPresent = group.some((key) => fieldPresent(packet, key));
+      if (!anyPresent) missing.push(group.join('|'));
+    }
+  }
+
+  if (spec.mustMatchEnum && typeof spec.mustMatchEnum === 'object') {
+    for (const [key, allowed] of Object.entries(spec.mustMatchEnum)) {
+      if (!Array.isArray(allowed) || allowed.length === 0) continue;
+      if (!fieldPresent(packet, key)) continue;
+      if (!allowed.includes(packet[key])) missing.push(`${key}!=${allowed.join('|')}`);
+    }
+  }
+
+  return { ok: missing.length === 0, missing, contract, direction };
+}
+
+/**
+ * Summary statistics for `construct status` / `construct doctor` surfaces.
+ */
+export function summarize() {
+  const all = getAllContracts();
+  const byProducer = {};
+  const byConsumer = {};
+  for (const c of all) {
+    byProducer[c.producer] = (byProducer[c.producer] || 0) + 1;
+    byConsumer[c.consumer] = (byConsumer[c.consumer] || 0) + 1;
+  }
+  return {
+    total: all.length,
+    producers: Object.keys(byProducer).length,
+    consumers: Object.keys(byConsumer).length,
+    byProducer,
+    byConsumer,
+  };
+}

package/lib/agents/postconditions.mjs

@@ -0,0 +1,126 @@
+/**
+ * lib/agents/postconditions.mjs — hard binary postconditions per producer persona.
+ *
+ * `agents/contracts.json` carries free-text postconditions for documentation
+ * purposes. This module adds binary, programmatically-validated assertions
+ * that the persona's output packet must satisfy before a handoff is allowed
+ * to proceed. Failure throws `ContractViolationError` with reason
+ * `BLOCKED_CONTRACT` so the dispatcher refuses to forward a packet that
+ * silently rubber-stamps, fixes symptoms without root cause, ships stale
+ * docs, or skips accessibility review.
+ *
+ * Each rule is identified by a stable id so violations are greppable in
+ * `~/.cx/contract-violations.jsonl`. Rules are pure functions of the
+ * output packet — no IO, no LLM calls — so they're deterministic and
+ * cheap to evaluate.
+ *
+ * Producers covered (CF3 round 1 from the 2026-05-13 UX audit):
+ *   - cx-reviewer       prevents silent rubber-stamp reviews
+ *   - cx-security       prevents post-hoc threat models
+ *   - cx-debugger       prevents symptom-only fixes
+ *   - cx-docs-keeper    prevents stale-doc PRs
+ *   - cx-designer       prevents post-hoc accessibility
+ */
+
+const ROOT_CAUSE_SOURCES = new Set(['reproduction', 'trace', 'test']);
+
+function isNonEmptyArray(value) {
+  return Array.isArray(value) && value.length > 0;
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function isLaterOrEqual(a, b) {
+  const ta = a instanceof Date ? a.getTime() : Date.parse(a);
+  const tb = b instanceof Date ? b.getTime() : Date.parse(b);
+  if (!Number.isFinite(ta) || !Number.isFinite(tb)) return false;
+  return ta >= tb;
+}
+
+/**
+ * Rule table. Keyed by producer name (matching agents/registry.json).
+ * Each rule:
+ *   id          — stable identifier for violation logs
+ *   description — single-line documentation
+ *   check       — (packet) => boolean — true when satisfied
+ *   reason      — explanation surfaced when violated
+ */
+export const POSTCONDITIONS = {
+  'cx-reviewer': [
+    {
+      id: 'reviewer.findings-or-explicit-clear',
+      description: 'Reviewer must either return at least one finding or explicitly state "no issues found at: <paths>".',
+      check: (p) => isNonEmptyArray(p?.findings) || isNonEmptyArray(p?.noIssuesFoundAt) || isNonEmptyString(p?.noIssuesFoundStatement),
+      reason: 'Reviewer output rubber-stamped: empty findings and no explicit "no issues found at: <paths>" statement.',
+    },
+  ],
+  'cx-security': [
+    {
+      id: 'security.threat-model-not-post-hoc',
+      description: 'Threat model must be updated at or after the contract start (not retrofitted).',
+      check: (p) => {
+        if (!p?.threatModelUpdatedAt || !p?.contractStart) return false;
+        return isLaterOrEqual(p.threatModelUpdatedAt, p.contractStart);
+      },
+      reason: 'Threat model missing or older than the contract start — likely retrofitted after implementation.',
+    },
+  ],
+  'cx-debugger': [
+    {
+      id: 'debugger.root-cause-confirmed-via',
+      description: 'Root cause must be confirmed via reproduction, trace, or test (not inferred).',
+      check: (p) => typeof p?.rootCauseConfirmedVia === 'string' && ROOT_CAUSE_SOURCES.has(p.rootCauseConfirmedVia),
+      reason: `rootCauseConfirmedVia must be one of: ${[...ROOT_CAUSE_SOURCES].join(', ')}.`,
+    },
+  ],
+  'cx-docs-keeper': [
+    {
+      id: 'docs-keeper.cross-doc-coherence-check-ran',
+      description: 'Docs-keeper must run the cross-doc coherence check and attach a named diff.',
+      check: (p) => p?.crossDocCoherenceCheckRan === true && isNonEmptyString(p?.coherenceDiff),
+      reason: 'crossDocCoherenceCheckRan must be true AND coherenceDiff must be a non-empty named diff.',
+    },
+  ],
+  'cx-designer': [
+    {
+      id: 'designer.accessibility-check-ran',
+      description: 'Designer must run the accessibility check before handoff (no post-hoc a11y).',
+      check: (p) => p?.accessibilityCheckRan === true,
+      reason: 'accessibilityCheckRan must be true — accessibility review is a precondition for any visual deliverable.',
+    },
+  ],
+};
+
+/**
+ * Evaluate the binary postcondition rules for a producer's output packet.
+ *
+ * @param {string} producer — persona name (e.g. `cx-reviewer`)
+ * @param {object} packet   — the output packet about to hand off
+ * @returns {{ ok: boolean, producer: string, failures: Array<{id, reason}> }}
+ */
+export function validatePostconditions(producer, packet) {
+  const rules = POSTCONDITIONS[producer] || [];
+  if (rules.length === 0) return { ok: true, producer, failures: [] };
+  const failures = [];
+  for (const rule of rules) {
+    let satisfied;
+    try {
+      satisfied = rule.check(packet);
+    } catch {
+      satisfied = false;
+    }
+    if (!satisfied) failures.push({ id: rule.id, reason: rule.reason });
+  }
+  return { ok: failures.length === 0, producer, failures };
+}
+
+/**
+ * List the rule ids registered for a producer — useful for tests and
+ * for the `agent_contract` MCP tool when surfacing what a persona must
+ * produce.
+ */
+export function describePostconditions(producer) {
+  return (POSTCONDITIONS[producer] || []).map((r) => ({ id: r.id, description: r.description }));
+}

package/lib/agents/schema.mjs

@@ -0,0 +1,124 @@
+/**
+ * lib/agents/schema.mjs — validation contract for agents/registry.json entries.
+ *
+ * Catches drift before it ships: missing description, unknown tool names,
+ * promptFile pointing at a path that does not resolve, unrecognized
+ * modelTier values. Run via `construct lint:agents` and in CI so a typo
+ * in the registry can't silently disable an agent.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const REQUIRED_FIELDS = ['name', 'description', 'promptFile'];
+
+// Tool names that can appear in claudeTools. Anything outside this allowlist
+// surfaces as an error; the host platform will silently drop unknown tool
+// references and the agent will appear to "work" without the tool, which is
+// the failure mode this lint catches.
+
+export const ALLOWED_TOOLS = new Set([
+  // Anthropic Claude Code built-ins
+  'Read', 'Write', 'Edit', 'Glob', 'Grep', 'LS', 'Bash', 'BashOutput',
+  'WebSearch', 'WebFetch', 'TodoWrite', 'NotebookEdit', 'Task',
+  // Construct MCP tools (from construct-mcp server)
+  'list_skills', 'get_skill', 'search_skills',
+  'list_teams', 'get_team',
+  'list_templates', 'get_template',
+  'agent_contract', 'orchestration_policy',
+  'cx_trace', 'cx_score',
+  // Memory MCP server
+  'memory_search', 'memory_add_observations', 'memory_open_nodes',
+  'memory_create_entities', 'memory_create_relations',
+  // Other MCP servers Construct ships with
+  'context7_resolve', 'context7_docs',
+  'sequential_thinking',
+  'playwright_navigate', 'playwright_screenshot',
+  'github_search', 'github_get_pull_request',
+]);
+
+/**
+ * Validate one agent record. Returns an array of error strings; empty means
+ * the record passes.
+ */
+export function validateAgentRecord(record, { rootDir, registryKey } = {}) {
+  const errors = [];
+  const id = record?.name || `#${registryKey ?? '?'}`;
+
+  if (!record || typeof record !== 'object') {
+    return [`${id}: agent record must be an object`];
+  }
+
+  for (const field of REQUIRED_FIELDS) {
+    if (!record[field]) errors.push(`${id}: missing required field "${field}"`);
+  }
+
+  if (record.description) {
+    const desc = String(record.description).trim();
+    if (desc.length < 20) errors.push(`${id}: description is too short (<20 chars) — the description is load-bearing for routing`);
+    if (desc.length > 500) errors.push(`${id}: description is too long (>500 chars) — keep it scannable`);
+  }
+
+  if (record.when_to_use !== undefined && record.when_to_use !== null) {
+    const wtu = String(record.when_to_use).trim();
+    if (wtu.length < 20) errors.push(`${id}: when_to_use is too short (<20 chars) — should describe the trigger conditions`);
+    if (wtu.length > 500) errors.push(`${id}: when_to_use is too long (>500 chars) — keep it scannable for routing`);
+  }
+
+  if (record.promptFile && rootDir) {
+    const promptPath = path.join(rootDir, record.promptFile);
+    if (!fs.existsSync(promptPath)) errors.push(`${id}: promptFile "${record.promptFile}" does not exist`);
+  }
+
+  if (record.claudeTools) {
+    const tools = String(record.claudeTools).split(',').map((t) => t.trim()).filter(Boolean);
+    for (const tool of tools) {
+      if (!ALLOWED_TOOLS.has(tool)) {
+        errors.push(`${id}: unknown tool "${tool}" in claudeTools — host platforms silently drop unknown tool names, causing this agent to appear to work without it`);
+      }
+    }
+  }
+
+  if (record.modelTier && !['fast', 'standard', 'reasoning'].includes(record.modelTier)) {
+    errors.push(`${id}: modelTier must be one of fast | standard | reasoning (got "${record.modelTier}")`);
+  }
+
+  return errors;
+}
+
+/**
+ * Validate every agent in a registry. Returns { errors: string[], agentCount }.
+ */
+export function validateRegistry(registry, { rootDir } = {}) {
+  if (!registry || !Array.isArray(registry.agents)) {
+    return { errors: ['registry.agents is missing or not an array'], agentCount: 0 };
+  }
+  const errors = [];
+  const seenNames = new Set();
+  for (let i = 0; i < registry.agents.length; i += 1) {
+    const record = registry.agents[i];
+    const recordErrors = validateAgentRecord(record, { rootDir, registryKey: i });
+    errors.push(...recordErrors);
+    if (record?.name) {
+      if (seenNames.has(record.name)) errors.push(`${record.name}: duplicate agent name at registry index ${i}`);
+      seenNames.add(record.name);
+    }
+  }
+  return { errors, agentCount: registry.agents.length };
+}
+
+/**
+ * Convenience: load registry.json from disk and validate it.
+ */
+export function validateRegistryFile({ registryPath, rootDir } = {}) {
+  if (!fs.existsSync(registryPath)) {
+    return { errors: [`registry not found at ${registryPath}`], agentCount: 0 };
+  }
+  let registry;
+  try {
+    registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+  } catch (err) {
+    return { errors: [`registry parse error: ${err.message}`], agentCount: 0 };
+  }
+  return validateRegistry(registry, { rootDir });
+}