@geraldmaron/construct 1.0.24 → 1.1.0

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('');
@@ -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);
@@ -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);

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 });

package/lib/beads-client.mjs

@@ -252,6 +252,15 @@ export async function runBd(args, options = {}) {
  * Used as fallback when optimistic locking fails.
  */
 async function runWithLegacyLock(args, opts, cwd, commandDesc) {
+  // Telemetry: every legacy-fallback firing is recorded so the lock+queue removal
+  // decision rests on observed data — if this never fires over a representative
+  // window, the whole exclusive-lock path is removable; if it fires, the entries
+  // name the bd errors that actually need handling (bead construct-nhn5).
+  try {
+    const { logBeadsFallback } = await import('./telemetry/beads-fallback.mjs');
+    logBeadsFallback({ command: commandDesc || args[0] || 'unknown' });
+  } catch { /* telemetry is best-effort */ }
+
   // Clean up any stale locks before trying
   cleanupStaleLock({ cwd });
   cleanupStaleQueue({ cwd });

package/lib/beads-optimistic.mjs

@@ -1,14 +1,14 @@
 /**
- * lib/beads-optimistic.mjs — Optimistic locking and concurrent read support for beads.
+ * lib/beads-optimistic.mjs — concurrent reads + retry-on-conflict writes for beads.
  *
- * Addresses the beads lock contention issue by:
- * 1. Allowing concurrent reads (no lock required)
- * 2. Using optimistic locking for writes (version-based conflict detection)
- * 3. Automatic retry with exponential backoff on conflict
- * 4. Read-replicas for team mode (when available)
- *
- * Replaces the exclusive lock model with a more scalable approach
- * while maintaining consistency guarantees.
+ * Dolt commits are atomic, so it is the serializer: a write is executed and, on a
+ * transient conflict, retried with exponential backoff. There is no separate
+ * read-then-compare version check — that spanned two `bd` processes (a `bd show`
+ * to read the commit hash, then a `bd update`) and guarded nothing, since `bd
+ * update` accepts no expected version, so the window between the read and the
+ * write left the "optimistic lock" unable to actually detect a conflicting commit
+ * (bead construct-iufy). Reads run lock-free; `getBeadVersion` remains as an
+ * advisory reader, not a write-path primitive.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -34,8 +34,9 @@ const DEFAULT_RETRY_OPTIONS = {
 // ---------------------------------------------------------------------------
 
 /**
- * Read the current version of a bead from the database.
- * In Dolt, this uses the commit hash as a logical version.
+ * Read the current version of a bead from the database (the Dolt commit hash).
+ * Advisory only — exposed for callers that want to observe a bead's version; the
+ * write path does not gate on it (see file header).
  */
 export async function getBeadVersion(beadId, cwd = process.cwd()) {
   try {
@@ -56,75 +57,37 @@ export async function getBeadVersion(beadId, cwd = process.cwd()) {
 }
 
 /**
- * Execute a write operation with optimistic locking.
- * 
+ * Execute a bead write, retrying on a transient conflict. Dolt's atomic commit is
+ * the serializer; this does not pre-read or compare a version (see file header).
+ *
  * @param {Object} options
- * @param {string} options.beadId - The bead being modified
  * @param {Function} options.execute - Async function that performs the write
- * @param {string} options.expectedVersion - Version we expect the bead to have
  * @param {Object} options.retry - Retry configuration
  * @returns {Promise<{success: boolean, result: any, attempts: number}>}
  */
 export async function optimisticWrite({
-  beadId,
   execute,
-  expectedVersion,
   retry = DEFAULT_RETRY_OPTIONS,
-  cwd = process.cwd(),
 } = {}) {
   let attempts = 0;
   let delay = retry.baseDelayMs;
-  
+
   while (attempts < retry.maxRetries) {
     attempts++;
-    
-    // Verify version hasn't changed (optimistic check)
-    const currentVersion = await getBeadVersion(beadId, cwd);
-    
-    if (expectedVersion && currentVersion !== expectedVersion) {
-      // Conflict detected - another writer modified the bead
-      if (attempts >= retry.maxRetries) {
-        return {
-          success: false,
-          error: `Optimistic lock conflict after ${attempts} attempts. Bead ${beadId} was modified by another process.`,
-          attempts,
-          currentVersion,
-          expectedVersion,
-        };
-      }
-      
-      // Wait with exponential backoff and jitter
-      const jitter = Math.random() * 50;
-      await new Promise(r => setTimeout(r, delay + jitter));
-      delay = Math.min(delay * retry.backoffMultiplier, retry.maxDelayMs);
-      continue;
-    }
-    
     try {
-      // Execute the write operation
       const result = await execute();
       return { success: true, result, attempts };
     } catch (error) {
       if (attempts >= retry.maxRetries) {
-        return {
-          success: false,
-          error: error.message,
-          attempts,
-        };
+        return { success: false, error: error.message, attempts };
       }
-      
-      // Retry on transient errors
       const jitter = Math.random() * 50;
-      await new Promise(r => setTimeout(r, delay + jitter));
+      await new Promise((r) => setTimeout(r, delay + jitter));
       delay = Math.min(delay * retry.backoffMultiplier, retry.maxDelayMs);
     }
   }
-  
-  return {
-    success: false,
-    error: `Max retries (${retry.maxRetries}) exceeded`,
-    attempts,
-  };
+
+  return { success: false, error: `Max retries (${retry.maxRetries}) exceeded`, attempts };
 }
 
 // ---------------------------------------------------------------------------
@@ -187,21 +150,10 @@ export async function updateBeadOptimistic(
   options = {}
 ) {
   const { actor = 'construct', cwd = process.cwd(), notes } = options;
-  
-  // Get current version before attempting update
-  const currentVersion = await getBeadVersion(beadId, cwd);
-  
-  if (!currentVersion) {
-    return {
-      success: false,
-      error: `Bead ${beadId} not found`,
-    };
-  }
-  
+
+  // A `bd update` on a missing bead exits non-zero and surfaces as a failed
+  // result, so no separate existence pre-check is needed.
   return optimisticWrite({
-    beadId,
-    expectedVersion: currentVersion,
-    cwd,
     execute: async () => {
       const args = ['update', beadId];