@geraldmaron/construct 1.0.24 → 1.1.1

package/README.md

@@ -149,6 +149,8 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 | `construct ask` | One-shot ask against the active knowledge index |
 | `construct bootstrap` | Import seed observation corpus into local memory store for cold-start acceleration |
 | `construct customer` | Manage customer profiles for product intelligence |
+| `construct demo` | Record reproducible terminal demos via VHS/asciinema (optional system binaries; ADR-0001) |
+| `construct diagram` | Render code-driven diagrams via D2/Graphviz (optional system binaries; ADR-0001) |
 | `construct distill` | Distill documents with query-focused chunking |
 | `construct drop` | Ingest file from Downloads/Desktop |
 | `construct export` | Export markdown to PDF/DOCX/HTML via Pandoc + Typst (optional system binaries; ADR-0024) |

package/bin/construct

@@ -169,6 +169,44 @@ function runNodeScript(scriptPath, args = [], extraEnv = {}, { exitOnError = tru
   return status;
 }
 
+async function cmdRegistryStatus(args = []) {
+  const { readFileSync, existsSync } = await import('node:fs');
+  const { join } = await import('node:path');
+  const matrixPath = join(ROOT_DIR, 'tests', 'registry', 'capability-matrix.json');
+  
+  if (!existsSync(matrixPath)) {
+    errorln('Capability matrix not found. Run "construct sync" or ensure tests/registry/capability-matrix.json exists.');
+    process.exit(1);
+  }
+
+  const { capabilities } = JSON.parse(readFileSync(matrixPath, 'utf8'));
+  const jsonOutput = args.includes('--json');
+
+  if (jsonOutput) {
+    println(JSON.stringify(capabilities, null, 2));
+    return;
+  }
+
+  println(`${COLORS.bold}Workflow & Surface Capability Registry${COLORS.reset}`);
+  println('='.repeat(40));
+  println('');
+
+  for (const cap of capabilities) {
+    const tierColor = cap.criticality === 'P0' ? COLORS.red : cap.criticality === 'P1' ? COLORS.yellow : COLORS.blue;
+    println(`${tierColor}[${cap.criticality}]${COLORS.reset} ${COLORS.bold}${cap.name}${COLORS.reset} (${cap.id})`);
+    println(`  ${COLORS.dim}${cap.description}${COLORS.reset}`);
+    
+    const surfaces = Object.entries(cap.surfaces);
+    for (const [name, status] of surfaces) {
+      const icon = status.quality_score === null ? '⚪' : status.quality_score >= 0.9 ? '🟢' : status.quality_score >= 0.7 ? '🟡' : '🔴';
+      const score = status.quality_score !== null ? `${(status.quality_score * 100).toFixed(0)}%` : 'N/A';
+      const date = status.last_validated ? new Date(status.last_validated).toLocaleDateString() : 'never';
+      println(`    ${icon} ${name.padEnd(10)} | Score: ${score.padEnd(5)} | Validated: ${date}`);
+    }
+    println('');
+  }
+}
+
 async function cmdStatus() {
   const jsonOutput = restArgsCache.includes('--json');
   const status = await buildStatus({ rootDir: ROOT_DIR, cwd: process.cwd(), homeDir: HOME, env: process.env });
@@ -1051,6 +1089,69 @@ async function cmdDoctor() {
     add(`Reconciliation drift check failed: ${err.message}`, false, true);
   }
 
+  // Docling document-extraction runtime (Python venv via uv). Provisioned lazily
+  // on first document ingest, or eagerly via `construct install --with-docling`.
+  // Advisory: absence is fine until a document is ingested.
+  try {
+    const { describeDoclingRuntime } = await import('../lib/runtime/uv-bootstrap.mjs');
+    const docling = describeDoclingRuntime();
+    if (docling.available) {
+      add(`Docling runtime ready (docling ${docling.marker?.doclingVersion ?? '?'})`, true, true);
+    } else {
+      add('Docling runtime not provisioned (`construct install --with-docling`, or auto on first ingest)', false, true);
+    }
+  } catch (err) {
+    add(`Docling runtime check failed: ${err.message}`, false, true);
+  }
+
+  // Capability honesty without re-probing: if the OpenCode default model is one the
+  // probe recorded as COLLAPSED (and its digest still matches), flag it at health
+  // time. Reads the persisted store only — the slow probe stays behind --probe-local.
+  try {
+    const { readOpenCodeConfig } = await import('../lib/opencode-config.mjs');
+    const { isKnownCollapsed } = await import('../lib/ollama/capability-store.mjs');
+    const { modelDigest } = await import('../lib/ollama/provision-context.mjs');
+    const { config } = readOpenCodeConfig();
+    const defaultModel = (config?.model || config?.defaultModel || '').replace(/^ollama\//, '');
+    if (defaultModel && isKnownCollapsed(defaultModel, modelDigest(defaultModel))) {
+      add(`Default local model ${defaultModel} probed COLLAPSED — not agentic-capable (re-verify: construct doctor --probe-local)`, false, true);
+    }
+  } catch { /* advisory */ }
+
+  // Opt-in agentic-coherence probe for local models (`construct doctor --probe-local`).
+  // Loads each registered Ollama model and measures repetition collapse on an agentic
+  // prompt, so it is gated behind the flag. COLLAPSED models produce word salad no
+  // matter how context and tools are tuned (capability is not predictable from size).
+  if (args.includes('--probe-local')) {
+    try {
+      const { ollamaAvailable, listModels, probeAgenticCoherence, probeStreamingToolCallLeak, modelDigest } = await import('../lib/ollama/provision-context.mjs');
+      const { recordProbeResult } = await import('../lib/ollama/capability-store.mjs');
+      // --probe-stream additionally drives a streaming turn and flags a tool-call
+      // leaked into the text channel (`<function=…>`) — the artifact the buffered
+      // probe cannot reproduce. It reloads each model, so it stays opt-in.
+      const probeStream = args.includes('--probe-stream');
+      if (!ollamaAvailable()) {
+        add('Local-model probe: Ollama not available', false, true);
+      } else {
+        const models = listModels().filter((m) => !/embed/i.test(m));
+        for (const m of models) {
+          const r = await probeAgenticCoherence(m);
+          if (r.ok) recordProbeResult(m, r, modelDigest(m));
+          const verdict = r.ok ? (r.coherent ? `COHERENT (repeat ${r.repeatRatio})` : `COLLAPSED (repeat ${r.repeatRatio})`) : `error: ${r.reason}`;
+          add(`Local probe ${m}: ${verdict}`, r.ok && r.coherent, true);
+          if (probeStream && r.ok && r.coherent) {
+            const s = await probeStreamingToolCallLeak(m);
+            if (s.ok) add(`Stream probe ${m}: ${s.leaked ? `TOOL-CALL LEAK (${s.marker})` : 'clean (native tool_calls)'}`, !s.leaked, true);
+          }
+        }
+        add('Quantization: prefer Q4_K_M+ — low quants are a known word-salad source', true, true);
+        add('Verified agentic-capable locals: qwen3-coder:32k, devstral:24b', true, true);
+      }
+    } catch (err) {
+      add(`Local-model probe failed: ${err.message}`, false, true);
+    }
+  }
+
   println('Construct Health Check');
   println('══════════════════════');
   println('');
@@ -1128,7 +1229,7 @@ async function resolveServiceSelection(args, selectable) {
   return null;
 }
 
-async function cmdUp(args = []) {
+async function cmdDev(args = []) {
   const { SELECTABLE_SERVICES } = await import('../lib/service-manager.mjs');
 
   // --only=a,b,c picks services non-interactively; --select opens a checklist.
@@ -1264,7 +1365,7 @@ async function cmdUp(args = []) {
   opLog.close(failed.length ? 'degraded' : 'ok', { failed: failed.map((r) => r.name) });
 }
 
-async function cmdDown() {
+async function cmdStop() {
   const { stopServices } = await import('../lib/service-manager.mjs');
   const result = await stopServices({ homeDir: HOME, rootDir: ROOT_DIR });
   for (const svc of result.results) {
@@ -1283,7 +1384,7 @@ async function cmdDown() {
   } catch { /* best effort */ }
 }
 
-async function cmdServe() {
+async function cmdDashboard() {
   if (restArgsCache.includes('--token')) {
     const { generateToken, setDashboardToken, getDashboardToken } = await import('../lib/server/auth.mjs');
     const existing = getDashboardToken();
@@ -1850,7 +1951,7 @@ async function cmdHosts() {
     printHostCapabilities();
   }
 }
-async function cmdSetup(args) {
+async function cmdInstall(args) {
   const { startOpLog } = await import('../lib/op-log.mjs');
   const opLog = startOpLog('install', { homeDir: HOME });
   opLog.event('args', { args });
@@ -2301,7 +2402,7 @@ async function cmdIntakeProcess(args, cwd) {
       errorln('Choose one:');
       errorln('  construct intake process --wait        Block until the holder finishes (default 30s).');
       errorln('  construct intake process --wait=<sec>  Block for a custom window.');
-      errorln('  construct down                          Stop background services, then retry.');
+      errorln('  construct stop                          Stop background services, then retry.');
       process.exit(2);
     }
     throw err;
@@ -4131,15 +4232,29 @@ async function cmdMemory(args) {
     const { getEngine } = await import('../lib/engine/index.mjs');
     const engine = await getEngine({ rootDir: process.cwd() });
     const summariser = engine.layers.compressor;
+
+    // The judge resolves the value-swap contradictions the heuristic abstains on
+    // when a local model is available; null offline, so consolidation runs the
+    // same with heuristic-only.
+    const { createContradictionJudge } = await import('../lib/engine/contradiction-judge.mjs');
+    const contradictionJudge = createContradictionJudge();
     const thresholdArg = args.find((a) => a.startsWith('--threshold='));
     const archiveDaysArg = args.find((a) => a.startsWith('--archive-days='));
-    const opts = { summariser };
+    const opts = { summariser, contradictionJudge };
     if (thresholdArg) opts.similarityThreshold = Number(thresholdArg.split('=')[1]);
     if (archiveDaysArg) opts.archiveAfterDays = Number(archiveDaysArg.split('=')[1]);
+    if (args.includes('--no-supersede')) opts.supersedeDuplicates = false;
+    if (args.includes('--no-contradictions')) opts.detectContradictions = false;
     const result = await consolidate(process.cwd(), opts);
+    const superseded = result.superseded ?? [];
+    const contradictions = superseded.filter((s) => s.reason === 'contradiction').length;
+    const restatements = superseded.length - contradictions;
+    const agedOut = result.archived.length - superseded.length;
     process.stdout.write(
       `consolidate: ${result.clustersBefore} observations → ${result.clusters} insights, ` +
-      `${result.archived.length} archived, ${result.archivePruned ?? 0} pruned from archive\n`
+      `${restatements} restated, ${contradictions} contradicted, ${agedOut} aged-out, ` +
+      `${result.archivePruned ?? 0} pruned from archive` +
+      `${result.contradictionScanSkipped ? ' (contradiction scan skipped: store too large)' : ''}\n`
     );
     return;
   }
@@ -4454,6 +4569,59 @@ async function cmdLintContracts() {
   process.exit(1);
 }
 
+async function cmdLintPrompts() {
+  const { validatePromptFiles } = await import('../lib/specialists/prompt-schema.mjs');
+  const { errors, warnings, total, converted } = validatePromptFiles({ rootDir: ROOT_DIR });
+  for (const w of warnings) console.warn(`  warn  ${w}`);
+  if (errors.length === 0) {
+    console.log(`specialist prompts: ${total} files (${converted} converted), 0 errors, ${warnings.length} warning(s)`);
+    return;
+  }
+  console.error(`specialist prompts: ${errors.length} error(s) across ${total} files`);
+  for (const err of errors) console.error(`  ${err}`);
+  process.exit(1);
+}
+
+async function cmdSpecialist(args) {
+  const sub = args[0];
+  if (sub === 'lint') return cmdLintPrompts();
+
+  if (sub === 'create') {
+    const role = args[1];
+    if (!role) { errorln('Usage: construct specialist create <role>'); process.exit(1); }
+    const { createSpecialistDraft } = await import('../lib/specialists/scaffold.mjs');
+    try {
+      const { relPath } = createSpecialistDraft({ rootDir: ROOT_DIR, role });
+      println(`Created ${relPath} — fill in the stubbed sections, add it to specialists/registry.json, then run \`construct specialist lint\`.`);
+    } catch (e) { errorln(e.message); process.exit(1); }
+    return;
+  }
+
+  if (sub === 'edit') {
+    const role = args[1];
+    if (!role) { errorln('Usage: construct specialist edit <role> [--set-bias=… --set-tension=… --add-overlay=… --bump-version]'); process.exit(1); }
+    const { editSpecialistFrontmatter } = await import('../lib/specialists/scaffold.mjs');
+    const setPerspective = {};
+    for (const f of ['bias', 'tension', 'openingQuestion', 'failureMode']) {
+      const a = args.find((x) => x.startsWith(`--set-${f}=`));
+      if (a) setPerspective[f] = a.slice(`--set-${f}=`.length);
+    }
+    const overlayArg = args.find((x) => x.startsWith('--add-overlay='));
+    try {
+      const { relPath } = editSpecialistFrontmatter({
+        rootDir: ROOT_DIR, role, setPerspective,
+        addOverlay: overlayArg ? overlayArg.slice('--add-overlay='.length) : undefined,
+        bumpVersion: args.includes('--bump-version'),
+      });
+      println(`Updated ${relPath || `specialists/prompts/cx-${role}.md`} — run \`construct specialist lint\` to confirm.`);
+    } catch (e) { errorln(e.message); process.exit(1); }
+    return;
+  }
+
+  errorln(`Unknown specialist subcommand: ${sub || '(none)'}. Available: create, edit, lint`);
+  process.exit(1);
+}
+
 async function cmdBackup(args) {
   // Postgres-era backups were removed with the SQL backend (lib/storage/backup.mjs).
   // State is now Git-backed (.cx/) plus the local LanceDB index under .cx/lancedb.
@@ -5000,8 +5168,19 @@ async function cmdHook(args) {
     errorln(`Hook not found: ${hookPath}`);
     process.exit(1);
   }
+  const started = Date.now();
   const result = spawnSync(process.execPath, [hookPath, ...args.slice(1)], { stdio: 'inherit' });
-  process.exit(result.status ?? 0);
+  const exitCode = result.status ?? 0;
+
+  // Record fire + outcome so hooks can be judged on whether they ever gate
+  // anything, not just on latency. Dynamic import keeps non-hook commands from
+  // paying the load; a telemetry failure must never change the hook's exit code.
+  try {
+    const { logHookCall } = await import('../lib/telemetry/hook-calls.mjs');
+    logHookCall({ hookId: safe, exitCode, latencyMs: Date.now() - started });
+  } catch { /* telemetry is best-effort */ }
+
+  process.exit(exitCode);
 }
 
 const [command, ...rest] = process.argv.slice(2);
@@ -5030,11 +5209,11 @@ async function readStdin() {
 
 const handlers = new Map([
   // Core
-  ['dev', cmdUp],
-  ['dashboard', cmdServe],
-  ['stop', cmdDown],
+  ['dev', cmdDev],
+  ['dashboard', cmdDashboard],
+  ['stop', cmdStop],
   ['status', cmdStatus],
-  ['install', cmdSetup],
+  ['install', cmdInstall],
   ['config', cmdConfig],
   ['intake', cmdIntake],
   ['recommendations', cmdRecommendations],
@@ -5057,6 +5236,7 @@ const handlers = new Map([
   ['infer', cmdInfer],
   ['search', cmdSearch],
   ['storage', cmdStorage],
+  ['registry:status', cmdRegistryStatus],
   // Pricing / cost readouts are stubbed out: the ledger writes, model-pricing
   // catalog, and per-turn accounting still run, but no CLI surface exposes
   // them to the user. Handlers (cmdPricing, cmdCosts, cmdCost) remain in this
@@ -5240,6 +5420,8 @@ const handlers = new Map([
   ['lint:research', cmdLintResearch],
   ['lint:agents', cmdLintAgents],
   ['lint:contracts', cmdLintContracts],
+  ['lint:prompts', cmdLintPrompts],
+  ['specialist', cmdSpecialist],
   ['decisions', async (args) => {
     const { runDecisionsCli } = await import('../lib/decisions/registry.mjs');
     return runDecisionsCli(args);
@@ -5656,6 +5838,14 @@ const handlers = new Map([
     const { runWireframeCli } = await import('../lib/wireframe.mjs');
     return runWireframeCli(args);
   }],
+  ['diagram', async (args) => {
+    const { runDiagramCli } = await import('../lib/diagram.mjs');
+    return runDiagramCli(args);
+  }],
+  ['demo', async (args) => {
+    const { runDemoCli } = await import('../lib/demo.mjs');
+    return runDemoCli(args);
+  }],
   ['skills', async (args) => {
     const sub = args[0];
     if (sub === 'scope' || !sub) {
@@ -6173,6 +6363,67 @@ if (command === '--version' || command === '-V') {
   process.exit(0);
 }
 
+// Unknown-flag guidance for commands that fully declare their flags (strictFlags
+// in the spec). A stray or typo'd flag on these is a user error, not a no-op:
+// reject it with the nearest declared flag and the command's help, matching how
+// install (lib/setup.mjs KNOWN_FLAGS) already behaves, so no flag is silently
+// swallowed. Opt-in keeps commands that accept undeclared flags unaffected.
+
+function validateKnownFlags(name, argv) {
+  const spec = CLI_COMMANDS.find((c) => c.name === name);
+  if (!spec || !spec.strictFlags) return;
+
+  const exact = new Set(['--help', '-h']);
+  const prefixes = [];
+  for (const opt of spec.options || []) {
+    for (const part of String(opt.flag).split(',')) {
+      const token = part.trim().split('=')[0].split(/\s/)[0];
+      if (!token.startsWith('-')) continue;
+      if (/-<[^>]+>$/.test(token)) prefixes.push(token.replace(/<[^>]+>$/, ''));
+      else exact.add(token);
+    }
+  }
+
+  const declared = [...exact].filter((f) => f.startsWith('--'));
+  const dist = (a, b) => {
+    const row = Array(b.length + 1).fill(0).map((_, i) => i);
+    for (let i = 1; i <= a.length; i += 1) {
+      let prev = i;
+      for (let j = 1; j <= b.length; j += 1) {
+        const cur = a[i - 1] === b[j - 1] ? row[j - 1] : 1 + Math.min(row[j - 1], row[j], prev);
+        row[j - 1] = prev;
+        prev = cur;
+      }
+      row[b.length] = prev;
+    }
+    return row[b.length];
+  };
+
+  const unknown = [];
+  for (const tok of argv) {
+    if (tok === '--') break;
+    if (!/^--?[A-Za-z]/.test(tok)) continue;
+    const bare = tok.split('=')[0];
+    if (exact.has(bare) || prefixes.some((p) => bare.startsWith(p))) continue;
+    unknown.push(bare);
+  }
+  if (unknown.length === 0) return;
+
+  for (const flag of unknown) {
+    errorln(`Unknown flag: ${flag}`);
+    let best = 4;
+    let suggestion = null;
+    for (const cand of declared) {
+      const d = dist(flag, cand);
+      if (d < best) { best = d; suggestion = cand; }
+    }
+    if (suggestion) errorln(`Did you mean: ${suggestion}?`);
+  }
+  println('');
+  println(`${COLORS.dim}Run 'construct ${name} --help' for valid options${COLORS.reset}`);
+  process.exit(1);
+}
+
 const handler = handlers.get(command);
 if (!handler) {
   errorln(`Unknown command: ${command}`);
@@ -6251,7 +6502,9 @@ if (command !== 'hook') {
 
 const probe = await maybeFirstInvocationProbe({ command, homeDir: HOME, env: process.env });
 if (probe?.runSetup) {
-  await cmdSetup([]);
+  await cmdInstall([]);
 }
 
+validateKnownFlags(command, rest);
+
 await handler(rest);

package/lib/agent-instructions/inject.mjs

@@ -22,7 +22,17 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 
-export const CONSTRUCT_INTEGRATION_VERSION = 1;
+export const CONSTRUCT_INTEGRATION_VERSION = 2;
+
+// AGENTS.md is the cross-platform single source (the agents.md standard read by
+// Codex/OpenCode/etc.); CLAUDE.md gets a thin pointer whose `@AGENTS.md` import
+// makes Claude Code load the same content at session start — the pattern the
+// Claude Code memory docs recommend for repos that carry both files. One mapping,
+// shared by init and reconcile, so the two writers cannot disagree.
+
+export function variantForFile(filePath) {
+  return path.basename(filePath) === 'CLAUDE.md' ? 'pointer' : 'full';
+}
 
 const BEGIN_PREFIX = '<!-- BEGIN CONSTRUCT INTEGRATION';
 const END_MARKER = '<!-- END CONSTRUCT INTEGRATION -->';
@@ -37,7 +47,18 @@ function shortHash(body) {
 // with Construct (≤60 lines). When a Beads Integration block is already present
 // the tracker line defers to it rather than duplicating `bd` commands.
 
-export function buildConstructIntegrationBody({ hasBeadsBlock = false } = {}) {
+export function buildConstructIntegrationBody({ hasBeadsBlock = false, variant = 'full' } = {}) {
+  if (variant === 'pointer') {
+    return [
+      '## Construct integration',
+      '',
+      '@AGENTS.md',
+      '',
+      'The Construct integration guidance for this project lives in `AGENTS.md`, imported',
+      'above so Claude Code loads it at session start. Address `@construct` and ask for the',
+      'outcome — Construct routes to the right specialist chain.',
+    ].join('\n');
+  }
   const tracker = hasBeadsBlock
     ? '- **Tracker**: see the Beads Integration block below for `bd` commands.'
     : '- **Tracker**: use Beads (`bd`) for all task tracking — run `bd prime` for the workflow. Do not use ad-hoc TODO lists.';
@@ -78,11 +99,11 @@ export function injectConstructBlock(content, body, version = CONSTRUCT_INTEGRAT
 // (with `header`) when missing; otherwise injects/updates in place, preserving
 // all surrounding content. Writes only when the content changes.
 
-export function injectIntoAgentFile(filePath, { version = CONSTRUCT_INTEGRATION_VERSION, header = '' } = {}) {
+export function injectIntoAgentFile(filePath, { version = CONSTRUCT_INTEGRATION_VERSION, header = '', variant = null } = {}) {
   const existed = fs.existsSync(filePath);
   const current = existed ? fs.readFileSync(filePath, 'utf8') : '';
   const hasBeadsBlock = BEADS_BLOCK_RE.test(current);
-  const body = buildConstructIntegrationBody({ hasBeadsBlock });
+  const body = buildConstructIntegrationBody({ hasBeadsBlock, variant: variant ?? variantForFile(filePath) });
   const base = !existed && header ? (header.endsWith('\n') ? header : `${header}\n`) : current;
   const { content, action } = injectConstructBlock(base, body, version);
   const changed = !existed || action !== 'unchanged';

package/lib/audit-rules.mjs

@@ -0,0 +1,127 @@
+/**
+ * lib/audit-rules.mjs — static reference audit for the rules/ corpus.
+ *
+ * Rules are not retrieved into agent context through any single runtime path the
+ * way skills are (no `logSkillCall` analog fits — they are named by path in prose
+ * the host's Read tool resolves, or read by enforcement tooling), so "which rules
+ * earn their keep" is a STATIC question. A rule is load-bearing two ways:
+ *   1. GLOB-SCOPED — its frontmatter declares `paths:` globs (the Cline/Cursor
+ *      pattern), so it is intended to activate on a matching edit. Whether those
+ *      globs are actually delivered to each host's rule config is a separate
+ *      concern; here they mark the rule as intentionally scoped, not an orphan.
+ *   2. REFERENCED — the canonical `rules/<dir>/<name>` path token (with or without
+ *      the .md) appears somewhere in the active surface (personas, CLAUDE.md,
+ *      skills, all of lib/ except the minified dashboard bundles, registry/
+ *      contracts, other rules, scripts, the CLI).
+ * A rule that is neither glob-activated nor referenced is a true orphan — a
+ * pruning candidate. A rule's own file never counts as referencing itself.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+// Directories and files that make up the "active surface" a rule could be cited
+// from. Code and prose both count — a rule named in a hook or in bin/construct is
+// as load-bearing as one named in a persona.
+
+const SURFACE_DIRS = ['personas', 'skills', 'rules', 'lib', 'specialists', 'scripts'];
+const SURFACE_FILES = ['CLAUDE.md', 'AGENTS.md', 'bin/construct', 'claude/settings.template.json'];
+const TEXT_EXT = new Set(['.md', '.mjs', '.js', '.json', '.txt', '.mdx']);
+
+// The minified Next.js dashboard bundles contain unrelated "rules/" tokens (the
+// markdown lexer's own grammar) that would read as false references.
+const SURFACE_SKIP = ['lib/server/static'];
+
+function isSkipped(full, root) {
+  const rel = path.relative(root, full);
+  return SURFACE_SKIP.some((s) => rel === s || rel.startsWith(`${s}${path.sep}`));
+}
+
+// A rule with `paths:` globs in its frontmatter is glob-activated by the host on a
+// matching edit — load-bearing regardless of whether it is named anywhere.
+function hasPathGlobs(absPath) {
+  try {
+    const head = fs.readFileSync(absPath, 'utf8').slice(0, 1200);
+    const fm = head.match(/^---\n([\s\S]*?)\n---/);
+    return Boolean(fm && /\n?paths:\s*\n\s*-\s+/.test(fm[1]));
+  } catch { return false; }
+}
+
+function collectRuleFiles(rulesDir) {
+  const out = [];
+  const walk = (dir) => {
+    for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) walk(full);
+      else if (ent.name.endsWith('.md')) out.push(path.relative(rulesDir, full).replace(/\.md$/, ''));
+    }
+  };
+  if (fs.existsSync(rulesDir)) walk(rulesDir);
+  return out;
+}
+
+function collectSurfaceText(root, ruleFileAbsSet) {
+  const texts = [];
+  const add = (full) => {
+    if (ruleFileAbsSet.has(full)) return;
+    if (!TEXT_EXT.has(path.extname(full))) return;
+    try { texts.push(fs.readFileSync(full, 'utf8')); } catch { /* unreadable — skip */ }
+  };
+  const walk = (dir) => {
+    let ents;
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const ent of ents) {
+      const full = path.join(dir, ent.name);
+      if (isSkipped(full, root)) continue;
+      if (ent.isDirectory()) walk(full);
+      else add(full);
+    }
+  };
+  for (const d of SURFACE_DIRS) walk(path.join(root, d));
+  for (const f of SURFACE_FILES) add(path.join(root, f));
+  return texts.join('\n');
+}
+
+/**
+ * Audit which rules are referenced in the active surface.
+ * @returns {{ total: number, referenced: Array<{rule:string,refs:number}>, orphans: string[], issues: object[] }}
+ */
+export function auditRules({ rootDir, silent = false } = {}) {
+  const root = rootDir ?? REPO_ROOT;
+  const rulesDir = path.join(root, 'rules');
+  const ruleFiles = collectRuleFiles(rulesDir);
+  const ruleAbsSet = new Set(ruleFiles.map((r) => path.join(rulesDir, `${r}.md`)));
+  const surface = collectSurfaceText(root, ruleAbsSet);
+
+  const referenced = [];
+  const globScoped = [];
+  const orphans = [];
+  for (const rule of ruleFiles) {
+    // Count `rules/<rule>` occurrences (with or without the .md suffix) so a
+    // citation in any surface file marks the rule load-bearing.
+    const token = `rules/${rule}`;
+    const refs = surface.split(token).length - 1;
+    if (refs > 0) referenced.push({ rule, refs });
+    else if (hasPathGlobs(path.join(rulesDir, `${rule}.md`))) globScoped.push(rule);
+    else orphans.push(rule);
+  }
+  referenced.sort((a, b) => b.refs - a.refs);
+
+  const issues = [];
+  if (orphans.length > 0) issues.push({ kind: 'orphan-rules', items: orphans });
+
+  if (!silent) {
+    const line = (s) => process.stdout.write(`${s}\n`);
+    line(`Rule reference audit (${ruleFiles.length} rules: ${referenced.length} referenced, ${globScoped.length} glob-scoped, ${orphans.length} orphan):`);
+    if (orphans.length === 0) {
+      line('  ✓ Every rule is referenced or glob-scoped');
+    } else {
+      line(`  ⚠ Rules neither referenced nor glob-scoped (${orphans.length}) — pruning candidates:`);
+      for (const r of orphans) line(`      - rules/${r}.md`);
+    }
+  }
+
+  return { total: ruleFiles.length, referenced, globScoped, orphans, issues };
+}

package/lib/audit-skills.mjs

@@ -4,6 +4,12 @@
  * Reports: (a) skills with no agent owner, (b) agents with no skill bindings,
  * (c) skill paths declared in registry but missing on disk.
  * Called by 'construct audit skills' and incorporated into 'construct doctor'.
+ *
+ * A `roles/<base>[.<flavor>]` skill is owned when `<base>` is a specialist OR a role
+ * named in any profile (profiles/*.json) — a role skill loads when its specialist or
+ * profile role runs, even without a direct registry `skills:` binding. Counting only
+ * registry bindings over-reported orphans (it missed profile roles like `operator`
+ * from operations.json and conditional specialist flavors); see bead construct-ksfa.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -34,6 +40,34 @@ function collectSkillFiles(skillsDir) {
   return results;
 }
 
+// Collect every role name a profile declares — top-level `roles` and nested
+// `departments[].roles` — so a role skill counts as owned when a profile uses its
+// base even if no specialist declares the skill path directly.
+function collectProfileRoles(root) {
+  const dir = path.join(root, 'profiles');
+  const roles = new Set();
+  const scan = (node) => {
+    if (Array.isArray(node)) { node.forEach(scan); return; }
+    if (node && typeof node === 'object') {
+      if (Array.isArray(node.roles)) for (const r of node.roles) if (typeof r === 'string') roles.add(r);
+      for (const v of Object.values(node)) scan(v);
+    }
+  };
+  try {
+    for (const f of fs.readdirSync(dir)) {
+      if (!f.endsWith('.json')) continue;
+      try { scan(JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'))); } catch { /* skip malformed */ }
+    }
+  } catch { /* no profiles dir */ }
+  return roles;
+}
+
+// The base of a role skill: roles/architect.data → architect; roles/qa → qa.
+function roleBase(skill) {
+  const m = skill.match(/^roles\/([^.]+)(?:\..*)?$/);
+  return m ? m[1] : null;
+}
+
 export function auditSkills({ rootDir, silent = false } = {}) {
   const root = rootDir ?? findConstructRoot();
   const registryPath = path.join(root, 'specialists', 'registry.json');
@@ -59,7 +93,15 @@ export function auditSkills({ rootDir, silent = false } = {}) {
     }
   }
 
-  const orphanSkills = [...allSkillFiles].filter((s) => !declaredSkills.has(s));
+  // Owning role bases = specialist names (registry) ∪ profile role names. A role
+  // skill is owned when its base is in this set, even without a direct binding.
+  const ownerBases = new Set([
+    ...(registry.specialists ?? []).map((a) => a.name.replace(/^cx-/, '')),
+    ...collectProfileRoles(root),
+  ]);
+  const isOwned = (s) => declaredSkills.has(s) || (ownerBases.has(roleBase(s)));
+
+  const orphanSkills = [...allSkillFiles].filter((s) => !isOwned(s));
 
   const issues = [];
   if (agentsWithNoSkills.length > 0) issues.push({ kind: 'agents-no-skills', items: agentsWithNoSkills });