@geraldmaron/construct 1.1.0 → 1.2.0

package/lib/artifact-type-from-path.mjs

@@ -0,0 +1,79 @@
+/**
+ * lib/artifact-type-from-path.mjs — Infer manifest doc type from artifact file paths.
+ *
+ * Resolves a manifest doc type when --type is omitted.
+ * Resolution order: YAML frontmatter cx_doc_type → directory heuristics → filename hints.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { artifactTypes } from './artifact-manifest.mjs';
+
+const KNOWN = new Set(artifactTypes());
+
+function readFrontmatterType(filePath) {
+  try {
+    const head = fs.readFileSync(filePath, 'utf8').slice(0, 4096);
+    const match = head.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) return null;
+    for (const line of match[1].split('\n')) {
+      const m = line.match(/^(?:cx_doc_type|artifactType|doc_type)\s*:\s*(.+)$/);
+      if (m) {
+        const value = m[1].trim().replace(/^['"]|['"]$/g, '');
+        return KNOWN.has(value) ? value : null;
+      }
+    }
+  } catch { /* unreadable */ }
+  return null;
+}
+
+function inferPrdSubtype(rel, base) {
+  const blob = `${rel} ${base}`.toLowerCase();
+  if (/meta[\s-]?prd/.test(blob)) return 'meta-prd';
+  if (/platform/.test(blob)) return 'prd-platform';
+  if (/business/.test(blob)) return 'prd-business';
+  return 'prd';
+}
+
+function inferRfcSubtype(rel, base) {
+  const blob = `${rel} ${base}`.toLowerCase();
+  if (/platform/.test(blob)) return 'rfc-platform';
+  return 'rfc';
+}
+
+const PREFIX_RULES = [
+  [/^docs\/prd\//, inferPrdSubtype],
+  [/^docs\/adr\//, () => 'adr'],
+  [/^docs\/rfc\//, inferRfcSubtype],
+  [/^docs\/research\//, () => 'research-brief'],
+  [/^docs\/runbooks?\//, () => 'runbook'],
+  [/^\.cx\/research\//, () => 'research-brief'],
+];
+
+export function isArtifactGatePath(relPath) {
+  const rel = relPath.replace(/\\/g, '/');
+  if (!rel.endsWith('.md')) return false;
+  if (rel.startsWith('templates/docs/')) return false;
+  if (/^docs\//.test(rel) || /^\.cx\/research\//.test(rel)) return true;
+  return false;
+}
+
+export function inferArtifactTypeFromPath(filePath, { rootDir = process.cwd() } = {}) {
+  const rel = path.relative(rootDir, filePath).replace(/\\/g, '/');
+  if (!rel.endsWith('.md')) return null;
+
+  const fromFm = readFrontmatterType(filePath);
+  if (fromFm) return fromFm;
+
+  if (!isArtifactGatePath(rel)) return null;
+
+  const base = path.basename(filePath, path.extname(filePath));
+  for (const [re, resolver] of PREFIX_RULES) {
+    if (re.test(rel)) {
+      const type = typeof resolver === 'function' ? resolver(rel, base) : resolver;
+      return KNOWN.has(type) ? type : null;
+    }
+  }
+
+  return null;
+}

package/lib/audit-skills.mjs

@@ -155,6 +155,10 @@ export function auditSkills({ rootDir, silent = false } = {}) {
 
 export async function runAuditSkillsCli(args = []) {
   const rootDir = args.find((a) => a.startsWith('--root='))?.split('=')[1] ?? undefined;
+  if (args.includes('--inventory')) {
+    const { runSkillInventoryAuditCli } = await import('./certification/skill-inventory.mjs');
+    return runSkillInventoryAuditCli(args.filter((a) => a !== '--inventory'), { rootDir });
+  }
   const result = auditSkills({ rootDir });
   if (!result.pass) process.exit(1);
 }

package/lib/audit-specialists.mjs

@@ -0,0 +1,285 @@
+/**
+ * lib/audit-specialists.mjs — Specialist/skill corpus audit matrix.
+ *
+ * Merges live registry, contracts, skills, prompts, and audit-enrichments into
+ * one machine-readable matrix. Powers `construct audit specialists` and the
+ * human-readable docs/concepts/specialist-skill-audit.md companion.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { auditSkills } from './audit-skills.mjs';
+import { loadArtifactManifest } from './artifact-manifest.mjs';
+import { resolvePerspectiveFromPrompt } from './specialists/prompt-schema.mjs';
+import { validateRoleCards } from './certification/role-cards.mjs';
+import { auditSpecialistContracts } from './certification/specialist-contracts.mjs';
+import { validateAllRoleOverlays } from './certification/role-overlays.mjs';
+import { ROLE_DIRECTIVE_RE } from './role-preload.mjs';
+
+function findConstructRoot(startPath = process.cwd()) {
+  let current = path.resolve(startPath);
+  while (true) {
+    if (fs.existsSync(path.join(current, 'specialists', 'registry.json'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(startPath);
+    current = parent;
+  }
+}
+
+function readJson(p) {
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+function collectSkillFiles(skillsDir) {
+  const results = [];
+  function walk(dir, prefix = '') {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        walk(path.join(dir, entry.name), prefix ? `${prefix}/${entry.name}` : entry.name);
+      } else if (entry.name.endsWith('.md') && entry.name !== 'routing.md') {
+        results.push(prefix ? `${prefix}/${entry.name.replace(/\.md$/, '')}` : entry.name.replace(/\.md$/, ''));
+      }
+    }
+  }
+  try { walk(skillsDir); } catch { /* missing */ }
+  return results.sort();
+}
+
+function parseRoleOverlay(promptPath) {
+  if (!fs.existsSync(promptPath)) return null;
+  const text = fs.readFileSync(promptPath, 'utf8');
+  const m = text.match(ROLE_DIRECTIVE_RE);
+  return m ? `roles/${m[1]}` : null;
+}
+
+function contractsForSpecialist(contracts, name) {
+  const id = name.startsWith('cx-') ? name : `cx-${name}`;
+  const related = [];
+  for (const c of contracts) {
+    if (c.producer === id || c.consumer === id) related.push(c.id);
+  }
+  return related;
+}
+
+function docTypesFromContracts(contracts) {
+  const types = new Set();
+  for (const c of contracts) {
+    const dt = c.trigger?.docAuthoring?.docType;
+    if (Array.isArray(dt)) dt.forEach((t) => types.add(t));
+    else if (typeof dt === 'string') types.add(dt);
+  }
+  return [...types];
+}
+
+function enforcementForAgent(agent, contracts) {
+  const id = `cx-${agent.name}`;
+  const items = ['no-fabrication.md', 'neurodivergent-output.md'];
+  const related = contracts.filter((c) => c.producer === id || c.consumer === id);
+  if (related.some((c) => c.postconditions?.length)) items.push('contracts.json postconditions');
+  if (agent.docArtifacts?.length) items.push('artifact structure lint', 'comment-lint on artifact paths');
+  if (agent.watchConditions?.length) items.push('watchConditions routing');
+  return items;
+}
+
+function crossChecks({ registry, manifest, skillAudit, allSkills, contractDocTypes }) {
+  const issues = [];
+  const manifestTypes = new Set(Object.keys(manifest.artifacts ?? {}));
+
+  for (const agent of registry.specialists ?? []) {
+    for (const skill of agent.skills ?? []) {
+      if (!allSkills.includes(skill)) {
+        issues.push({ kind: 'missing-skill-file', agent: agent.name, skill });
+      }
+    }
+    for (const doc of agent.docArtifacts ?? []) {
+      if (!manifestTypes.has(doc)) {
+        issues.push({ kind: 'doc-artifact-no-manifest', agent: agent.name, docType: doc });
+      }
+    }
+  }
+
+  for (const dt of contractDocTypes) {
+    if (!manifestTypes.has(dt)) {
+      issues.push({ kind: 'contract-doc-no-manifest', docType: dt });
+    }
+  }
+
+  if (skillAudit.missingSkillFiles.length) {
+    for (const { agent, skill } of skillAudit.missingSkillFiles) {
+      issues.push({ kind: 'registry-missing-skill', agent, skill });
+    }
+  }
+
+  return issues;
+}
+
+export function auditSpecialists({ rootDir, silent = false } = {}) {
+  const root = rootDir ?? findConstructRoot();
+  const registry = readJson(path.join(root, 'specialists', 'registry.json'));
+  const contractsDoc = readJson(path.join(root, 'specialists', 'contracts.json'));
+  const enrichments = readJson(path.join(root, 'specialists', 'audit-enrichments.json'));
+  const manifest = loadArtifactManifest({ rootDir: root });
+  const skillAudit = auditSkills({ rootDir: root, silent: true });
+  const allSkills = collectSkillFiles(path.join(root, 'skills'));
+  const contractDocTypes = docTypesFromContracts(contractsDoc.contracts ?? []);
+  const crossCheckIssues = crossChecks({ registry, manifest, skillAudit, allSkills, contractDocTypes });
+
+  const specialists = (registry.specialists ?? []).map((agent) => {
+    const promptPath = agent.promptFile
+      ? path.join(root, agent.promptFile)
+      : null;
+    const meta = enrichments.specialists?.[agent.name] ?? {};
+    const perspective = resolvePerspectiveFromPrompt(agent.name, { rootDir: root, registry });
+    return {
+      name: agent.name,
+      id: `cx-${agent.name}`,
+      humanEquivalent: meta.humanEquivalent ?? 'unknown',
+      primaryOutputs: agent.docArtifacts ?? [],
+      skillsBound: agent.skills ?? [],
+      roleOverlay: promptPath ? parseRoleOverlay(promptPath) : null,
+      researchProfile: meta.researchProfile ?? null,
+      toneProfile: meta.toneProfile ?? 'direct',
+      challengeModel: {
+        tension: perspective?.tension ?? null,
+        failureMode: perspective?.failureMode ?? null,
+        watchConditions: agent.watchConditions ?? [],
+      },
+      enforcementToday: enforcementForAgent(agent, contractsDoc.contracts ?? []),
+      contracts: contractsForSpecialist(contractsDoc.contracts ?? [], agent.name),
+      grade: meta.grade ?? 'adequate',
+      gap: meta.gap ?? 'Not assessed',
+      beadId: meta.beadId ?? 'construct-hcr9',
+      skillCount: (agent.skills ?? []).length,
+    };
+  });
+
+  const roleOverlays = [];
+  const rolesDir = path.join(root, 'skills', 'roles');
+  if (fs.existsSync(rolesDir)) {
+    for (const f of fs.readdirSync(rolesDir).filter((n) => n.endsWith('.md')).sort()) {
+      const key = f.replace(/\.md$/, '');
+      const meta = enrichments.roleOverlays?.[key] ?? {};
+      roleOverlays.push({
+        path: `roles/${key}`,
+        grade: meta.grade ?? 'adequate',
+        gap: meta.gap ?? 'Not assessed',
+      });
+    }
+  }
+
+  const workflowSkills = allSkills
+    .filter((s) => !s.startsWith('roles/'))
+    .map((skillPath) => {
+      const manifestEntry = Object.entries(manifest.artifacts ?? {}).find(([, v]) => v.workflowSkill === skillPath);
+      return {
+        path: skillPath,
+        artifactType: manifestEntry?.[0] ?? null,
+        toneDefault: manifestEntry?.[1]?.toneDefault ?? null,
+      };
+    });
+
+  const roleCards = validateRoleCards({ rootDir: root });
+  const specialistContracts = auditSpecialistContracts({ rootDir: root });
+  const roleOverlayAudit = validateAllRoleOverlays({ rootDir: root });
+  if (!roleCards.pass) {
+    for (const err of roleCards.errors) crossCheckIssues.push({ kind: 'role-card-missing', detail: err });
+  }
+  if (!specialistContracts.pass) {
+    for (const fail of specialistContracts.failures) {
+      crossCheckIssues.push({ kind: 'specialist-contract-fail', specialist: fail.specialistId });
+    }
+  }
+  if (!roleOverlayAudit.pass) {
+    for (const err of roleOverlayAudit.errors.slice(0, 5)) {
+      crossCheckIssues.push({ kind: 'role-overlay-fail', detail: err });
+    }
+  }
+
+  const result = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    specialistCount: specialists.length,
+    roleOverlayCount: roleOverlays.length,
+    workflowSkillCount: workflowSkills.length,
+    specialists,
+    roleOverlays,
+    workflowSkills,
+    crossCheckIssues,
+    roleCards,
+    specialistContracts,
+    roleOverlayAudit,
+    pass: crossCheckIssues.length === 0 && skillAudit.pass,
+  };
+
+  if (!silent) {
+    const line = (msg) => process.stdout.write(`${msg}\n`);
+    line('Construct Specialist Audit');
+    line('═══════════════════════════');
+    line(`  Specialists: ${result.specialistCount}`);
+    line(`  Role overlays: ${result.roleOverlayCount}`);
+    line(`  Workflow skills: ${result.workflowSkillCount}`);
+    line('');
+    if (crossCheckIssues.length === 0) {
+      line('  ✓ Cross-checks passed (skills, docArtifacts, manifest, contracts)');
+    } else {
+      line(`  ✗ Cross-check issues (${crossCheckIssues.length}):`);
+      for (const issue of crossCheckIssues) line(`      - ${JSON.stringify(issue)}`);
+    }
+    line('');
+    line(result.pass ? '  Result: PASS' : '  Result: FAIL');
+  }
+
+  return result;
+}
+
+export function formatAuditMarkdown(result) {
+  const lines = [
+    '# Specialist & skill audit',
+    '',
+    `Generated: ${result.generatedAt}. Re-run \`construct audit specialists --json\` for the live matrix.`,
+    '',
+    '## Specialists',
+    '',
+    '| Specialist | Human equivalent | Outputs | Skills | Role overlay | Research | Tone | Grade | Gap |',
+    '|---|---|---|---|---|---|---|---|---|',
+  ];
+
+  for (const s of result.specialists) {
+    lines.push(
+      `| cx-${s.name} | ${s.humanEquivalent} | ${s.primaryOutputs.join(', ') || '—'} | ${s.skillCount} | ${s.roleOverlay ?? '—'} | ${s.researchProfile ?? '—'} | ${s.toneProfile} | ${s.grade} | ${s.gap} |`,
+    );
+  }
+
+  lines.push('', '## Role overlays', '', '| Overlay | Grade | Gap |', '|---|---|---|');
+  for (const r of result.roleOverlays) {
+    lines.push(`| ${r.path} | ${r.grade} | ${r.gap} |`);
+  }
+
+  lines.push('', '## Cross-check issues', '');
+  if (result.crossCheckIssues.length === 0) {
+    lines.push('None.');
+  } else {
+    for (const issue of result.crossCheckIssues) {
+      lines.push(`- \`${issue.kind}\`: ${JSON.stringify(issue)}`);
+    }
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+export async function runAuditSpecialistsCli(args = []) {
+  const json = args.includes('--json');
+  const markdown = args.includes('--markdown');
+  const rootDir = args.find((a) => a.startsWith('--root='))?.split('=')[1];
+  const result = auditSpecialists({ rootDir, silent: true });
+
+  if (markdown) {
+    process.stdout.write(formatAuditMarkdown(result));
+  } else if (json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    auditSpecialists({ rootDir, silent: false });
+  }
+
+  if (!result.pass) process.exit(1);
+}

package/lib/audit-trail.mjs

@@ -1,22 +1,68 @@
 /**
- * lib/audit-trail.mjs — reads the append-only audit log produced by
- * lib/hooks/audit-trail.mjs and renders it for `construct audit trail`.
+ * lib/audit-trail.mjs — owns the append-only audit log written by
+ * lib/hooks/audit-trail.mjs and rendered for `construct audit trail`.
  *
  * The log is JSONL at ~/.cx/audit-trail.jsonl. Each line carries a
  * prev_line_hash pointing at the SHA-256 of the previous line — tampering
  * (reorder, delete, edit) breaks the chain and is surfaced by --verify.
+ *
+ * A serial hash chain cannot survive concurrent appends: a read-prev-hash +
+ * append done outside a critical section lets two processes (hook, daemon,
+ * parallel tool calls in one session) both chain off the same predecessor, so
+ * the second link points at a stale tail. appendAuditRecord
+ * closes that window by computing prev_line_hash and appending inside a single
+ * cross-process file lock, making every writer effectively serialized.
+ *
+ * Corrupted links cannot be re-derived, so a `chain_reset` boundary line seals
+ * the damaged prefix as immutable legacy and re-bases the live chain;
+ * verifyChain validates only from the last boundary forward. See
+ * docs/concepts/observability.md.
  */
-import { readFileSync, existsSync, statSync } from 'node:fs';
+import { readFileSync, existsSync, statSync, mkdirSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 
+import { appendBounded, readLastLineAcrossSegments } from './logging/rotate.mjs';
+import { withFileLockSync } from './storage/file-lock.mjs';
+
 const AUDIT_FILE = join(homedir(), '.cx', 'audit-trail.jsonl');
 
 function sha256(input) {
   return createHash('sha256').update(input).digest('hex');
 }
 
+// prev_line_hash and the append must be one atomic step or concurrent writers
+// race; the file lock serializes them across processes.
+
+export function appendAuditRecord(partial, { file = AUDIT_FILE } = {}) {
+  return withFileLockSync(file, () => {
+    let prev = null;
+    try {
+      const last = readLastLineAcrossSegments(file);
+      if (last !== null) prev = sha256(last);
+    } catch { /* first record, or unreadable tail */ }
+    const record = { ...partial, prev_line_hash: prev };
+    mkdirSync(dirname(file), { recursive: true });
+    appendBounded('audit-trail', file, JSON.stringify(record) + '\n');
+    return record;
+  });
+}
+
+// A reset boundary seals the records it follows as legacy excluded from
+// verification and re-bases the live chain from this line.
+
+export function writeChainReset({ file = AUDIT_FILE, reason = 'manual reset' } = {}) {
+  return appendAuditRecord({
+    ts: new Date().toISOString(),
+    chain_reset: true,
+    reason,
+    agent: 'construct',
+    tool: null,
+    target: null,
+  }, { file });
+}
+
 export function readAuditTrail({ limit = 50, since = null, agent = null, tool = null } = {}) {
   if (!existsSync(AUDIT_FILE)) return [];
   const lines = readFileSync(AUDIT_FILE, 'utf8').split('\n').filter(Boolean);
@@ -34,19 +80,29 @@ export function readAuditTrail({ limit = 50, since = null, agent = null, tool =
   return filtered.slice(-limit);
 }
 
-export function verifyChain() {
-  if (!existsSync(AUDIT_FILE)) return { ok: true, verified: 0, broken: [] };
-  const lines = readFileSync(AUDIT_FILE, 'utf8').split('\n').filter(Boolean);
+export function verifyChain(file = AUDIT_FILE) {
+  if (!existsSync(file)) return { ok: true, verified: 0, broken: [], legacy: 0 };
+  const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean);
+
+  // Validation starts at the last reset boundary; the prefix it seals is legacy
+  // and exempt, so concurrency damage predating the migration can't fail the chain.
+
+  let start = 0;
+  for (let i = 0; i < lines.length; i += 1) {
+    try { if (JSON.parse(lines[i]).chain_reset) start = i; } catch { /* legacy malformed */ }
+  }
+
   const broken = [];
   let prevHash = null;
-  for (let i = 0; i < lines.length; i += 1) {
+  for (let i = start; i < lines.length; i += 1) {
     const line = lines[i];
     let row;
     try { row = JSON.parse(line); } catch {
       broken.push({ line: i + 1, reason: 'malformed JSON' });
+      prevHash = sha256(line);
       continue;
     }
-    if (i > 0 && row.prev_line_hash !== prevHash) {
+    if (i > start && !row.chain_reset && row.prev_line_hash !== prevHash) {
       broken.push({
         line: i + 1,
         expected: prevHash,
@@ -56,7 +112,7 @@ export function verifyChain() {
     }
     prevHash = sha256(line);
   }
-  return { ok: broken.length === 0, verified: lines.length, broken };
+  return { ok: broken.length === 0, verified: lines.length - start, broken, legacy: start };
 }
 
 function formatRow(row) {
@@ -74,6 +130,9 @@ export async function runAuditTrailCli(args = []) {
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
     if (arg === '--verify') flags.add('verify');
+    else if (arg === '--reset') flags.add('reset');
+    else if (arg.startsWith('--reason=')) options.reason = arg.slice(9);
+    else if (arg === '--reason') options.reason = args[++i];
     else if (arg === '--json') flags.add('json');
     else if (arg === '--all') flags.add('all');
     else if (arg.startsWith('--limit=')) options.limit = Number(arg.slice(8));
@@ -97,6 +156,8 @@ Options:
   --agent <name>    Filter to a specific agent (e.g. cx-engineer)
   --tool <name>     Filter to a specific tool (Edit, Write, MultiEdit, NotebookEdit, Bash)
   --verify          Verify the tamper-evidence chain and exit
+  --reset           Seal the current chain as legacy and re-base a fresh chain
+  --reason <text>   Reason recorded on the --reset boundary
   --json            Emit raw JSONL lines instead of formatted output
   -h, --help        Show this message
 
@@ -105,6 +166,12 @@ Log location: ${AUDIT_FILE}
     return;
   }
 
+  if (flags.has('reset')) {
+    writeChainReset({ reason: options.reason || 'manual reset' });
+    console.log(`Audit chain re-based at ${AUDIT_FILE}. Prior records sealed as legacy; verification resumes from the new boundary.`);
+    return;
+  }
+
   if (flags.has('verify')) {
     const result = verifyChain();
     if (result.ok) {

package/lib/auto-docs.mjs

@@ -90,20 +90,25 @@ function buildCoreDocsContract() {
 }
 
 const DIR_DESCRIPTIONS = {
-  agents: 'Registry and generated platform adapter chains',
-  apps: 'User-facing apps shipped from this repo (e.g. apps/docs/, the Next.js docs site)',
+  apps: 'User-facing apps shipped from this repo (chat, dashboard, docs)',
   bin: 'CLI entrypoint (`construct`)',
-  claude: 'Claude Code integration (agents, settings template)',
   commands: 'Command prompt assets',
-  codex: 'GitHub Copilot / Codex integration',
+  config: 'Repo-wide controlled vocabulary (tag-vocabulary.json)',
+  deploy: 'Terraform and deployment configs',
   docs: 'Architecture notes, runbooks, and documentation contract',
-  telemetry: 'Local trace capture and optional telemetry export',
-  lib: 'Core runtime: CLI, hooks, MCP, status, sync, workflow',
-  opencode: 'OpenCode integration config',
+  examples: 'Example projects and persona fixtures',
+  lib: 'Core runtime: CLI, hooks, MCP, providers, oracle, sync',
+  packages: 'Shared workspace packages (e.g. cx-ui)',
   personas: 'Persona prompt definitions',
+  platforms: 'Host adapter capability configs',
+  profiles: 'Profile catalog',
+  registry: 'Product capability registry',
   rules: 'Coding and quality standards',
-  site: 'Legacy docs-site output',
+  schemas: 'Registry and config JSON Schema',
+  scripts: 'Audit, alignment, release, and sync scripts',
   skills: 'Reusable domain knowledge files',
+  specialists: 'Org registry, contracts, and specialist prompts',
+  templates: 'Doc and workflow templates',
   tests: 'Test suite',
 };
 
@@ -164,16 +169,16 @@ function buildAgentsTable(rootDir) {
   let registry;
   try { registry = JSON.parse(fs.readFileSync(registryPath, 'utf8')); } catch { return ''; }
 
-  const agents = registry.agents ?? registry;
-  if (!Array.isArray(agents)) return '';
+  const agents = [
+    ...(registry.orchestrator ? [{ ...registry.orchestrator, name: registry.orchestrator.name }] : []),
+    ...(registry.specialists ?? []),
+  ];
+  if (!agents.length) return '';
 
   const rows = ['| Specialist | Tier | Purpose |', '|---|---|---|'];
   for (const agent of agents.slice(0, 30)) {
     const name = agent.name ?? agent.id ?? 'n/a';
     const tier = agent.modelTier ?? agent.tier ?? agent.model_tier ?? 'n/a';
-    // Strip em-dashes from descriptions so the prose lint stays clean across
-    // AUTO regen. Em-dashes are allowed in the registry's source descriptions
-    // but never in the rendered markdown.
     const purpose = (agent.description ?? agent.purpose ?? '')
       .split('\n')[0].slice(0, 80)
       .replace(/ — /g, '. ').replace(/—/g, ',');
@@ -474,13 +479,77 @@ export function buildFumadocsReference({ rootDir } = {}) {
     written.push(path.relative(rootDir, hooksPage));
   }
 
-  const agentsContent = renderAgentsPage(rootDir);
-  if (agentsContent) {
-    const agentsPage = path.join(refDir, 'agents.md');
-    if (writeIfChanged(agentsPage, agentsContent)) {
-      written.push(path.relative(rootDir, agentsPage));
+  const specialistsContent = renderAgentsPage(rootDir);
+  if (specialistsContent) {
+    const specialistsPage = path.join(refDir, 'specialists.md');
+    if (writeIfChanged(specialistsPage, specialistsContent)) {
+      written.push(path.relative(rootDir, specialistsPage));
+    }
+    const legacyAgentsPage = path.join(refDir, 'agents.md');
+    if (fs.existsSync(legacyAgentsPage)) {
+      fs.unlinkSync(legacyAgentsPage);
+      written.push(`- ${path.relative(rootDir, legacyAgentsPage)}`);
     }
   }
 
   return { written };
 }
+
+export function checkFumadocsReferenceDrift({ rootDir } = {}) {
+  rootDir = rootDir ?? process.cwd();
+  const refDir = path.join(rootDir, 'docs', 'reference');
+  const cliDir = path.join(refDir, 'cli');
+  const drift = [];
+
+  for (const category of REFERENCE_CATEGORIES) {
+    const commands = CLI_COMMANDS_BY_CATEGORY[category] ?? [];
+    if (!commands.length) continue;
+    const slug = slugify(category);
+    const out = path.join(cliDir, `${slug}.md`);
+    const content = renderCommandPage(category, commands);
+    if (readFile(out) !== content) drift.push(path.relative(rootDir, out));
+  }
+
+  const cliPages = REFERENCE_CATEGORIES
+    .map((cat) => ({ cat, commands: CLI_COMMANDS_BY_CATEGORY[cat] ?? [] }))
+    .filter(({ commands }) => commands.length)
+    .map(({ cat }) => slugify(cat));
+  const cliMetaContent = JSON.stringify({ title: 'CLI', pages: ['index', ...cliPages] }, null, 2) + '\n';
+  const cliMeta = path.join(cliDir, 'meta.json');
+  if (readFile(cliMeta) !== cliMetaContent) drift.push(path.relative(rootDir, cliMeta));
+
+  const cliIndexContent = [
+    '---',
+    'title: CLI',
+    'description: Every construct command, grouped by category. Generated from lib/cli-commands.mjs.',
+    '---',
+    '',
+    '> Generated from `lib/cli-commands.mjs`. Re-run `construct docs:site` to refresh.',
+    '',
+    'Commands are grouped by what they do. Pick a category below.',
+    '',
+    ...REFERENCE_CATEGORIES.map((cat) => {
+      const slug = slugify(cat);
+      const commands = CLI_COMMANDS_BY_CATEGORY[cat] ?? [];
+      if (!commands.length) return null;
+      return `- [${cat}](/reference/cli/${slug}) — ${commands.length} command${commands.length === 1 ? '' : 's'}`;
+    }).filter(Boolean),
+    '',
+  ].join('\n');
+  const cliIndex = path.join(cliDir, 'index.md');
+  if (readFile(cliIndex) !== cliIndexContent) drift.push(path.relative(rootDir, cliIndex));
+
+  const hooksPage = path.join(refDir, 'hooks.md');
+  const hooksContent = renderHooksPage(rootDir);
+  if (hooksContent && readFile(hooksPage) !== hooksContent) drift.push(path.relative(rootDir, hooksPage));
+
+  const specialistsContent = renderAgentsPage(rootDir);
+  const specialistsPage = path.join(refDir, 'specialists.md');
+  if (specialistsContent && readFile(specialistsPage) !== specialistsContent) {
+    drift.push(path.relative(rootDir, specialistsPage));
+  }
+  const legacyAgentsPage = path.join(refDir, 'agents.md');
+  if (fs.existsSync(legacyAgentsPage)) drift.push(path.relative(rootDir, legacyAgentsPage));
+
+  return { drift };
+}