@geraldmaron/construct 1.0.24 → 1.1.0

package/lib/runtime/uv-bootstrap.mjs

@@ -17,7 +17,7 @@
  * sidecar without relying on PATH state.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import path from 'node:path';
 import os from 'node:os';
 
@@ -37,6 +37,31 @@ function which(bin) {
   return result.stdout.trim().split('\n')[0] || null;
 }
 
+// Provisioning runs on the request path (the first docling ingest), including
+// inside the long-lived MCP server. spawnSync would block the event loop for the
+// whole multi-minute install — freezing every other request and defeating the
+// per-tool dispatch timeout. Run each step via async spawn instead, shaped to
+// mirror spawnSync's result so describeStepFailure reads it unchanged.
+
+function runAsync(cmd, args, { timeoutMs, env } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { env });
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    child.stdout?.setEncoding('utf8');
+    child.stderr?.setEncoding('utf8');
+    child.stdout?.on('data', (d) => { stdout += d; });
+    child.stderr?.on('data', (d) => { stderr += d; });
+    const timer = timeoutMs ? setTimeout(() => { timedOut = true; child.kill('SIGTERM'); }, timeoutMs) : null;
+    child.on('error', (error) => { if (timer) clearTimeout(timer); resolve({ status: null, stdout, stderr, error, signal: null }); });
+    child.on('close', (code, signal) => {
+      if (timer) clearTimeout(timer);
+      resolve({ status: code, stdout, stderr, signal: timedOut ? 'SIGTERM' : signal, error: timedOut ? { code: 'ETIMEDOUT' } : null });
+    });
+  });
+}
+
 // First-run docling provisioning blocks for minutes (uv install, venv, then a
 // large `uv pip install docling` that pulls ML deps). Without a heartbeat it
 // reads as a hang. Progress goes to stderr only, so JSON consumers on stdout are
@@ -56,7 +81,7 @@ function describeStepFailure(label, result, timeoutMs) {
   return `${label} failed (${result.status}): ${result.stderr || result.stdout || result.error?.message || 'unknown error'}`;
 }
 
-function ensureUv(installDir) {
+async function ensureUv(installDir) {
   const fromPath = which('uv');
   if (fromPath) return fromPath;
   const cachedUv = path.join(installDir, 'bin', 'uv');
@@ -64,11 +89,7 @@ function ensureUv(installDir) {
   mkdirSync(installDir, { recursive: true });
   progress('Installing uv (Python toolchain) — first run only…');
   const env = { ...process.env, UV_INSTALL_DIR: path.join(installDir, 'bin'), UV_NO_MODIFY_PATH: '1' };
-  const sh = spawnSync('sh', ['-c', `curl -LsSf ${UV_INSTALL_URL} | sh`], {
-    env,
-    timeout: UV_TIMEOUT_MS,
-    encoding: 'utf8',
-  });
+  const sh = await runAsync('sh', ['-c', `curl -LsSf ${UV_INSTALL_URL} | sh`], { env, timeoutMs: UV_TIMEOUT_MS });
   if (sh.status !== 0) {
     throw new Error(describeStepFailure('uv install', sh, UV_TIMEOUT_MS));
   }
@@ -95,7 +116,7 @@ function writeMarker(markerPath, payload) {
   writeFileSync(markerPath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
 }
 
-export function ensureDoclingVenv({ runtimeDir = defaultRuntimeDir(), force = false } = {}) {
+export async function ensureDoclingVenv({ runtimeDir = defaultRuntimeDir(), force = false } = {}) {
   mkdirSync(runtimeDir, { recursive: true });
   const venvDir = path.join(runtimeDir, '.venv');
   const markerPath = path.join(runtimeDir, '.install-marker.json');
@@ -107,22 +128,16 @@ export function ensureDoclingVenv({ runtimeDir = defaultRuntimeDir(), force = fa
   }
 
   progress('Provisioning the docling document extractor (first run). This downloads a Python runtime and ML dependencies and can take several minutes; later runs are instant.');
-  const uv = ensureUv(runtimeDir);
+  const uv = await ensureUv(runtimeDir);
 
   progress('Creating Python 3.11 virtualenv…');
-  const venvResult = spawnSync(uv, ['venv', venvDir, '--python', '3.11'], {
-    timeout: VENV_TIMEOUT_MS,
-    encoding: 'utf8',
-  });
+  const venvResult = await runAsync(uv, ['venv', venvDir, '--python', '3.11'], { timeoutMs: VENV_TIMEOUT_MS });
   if (venvResult.status !== 0) {
     throw new Error(describeStepFailure('uv venv', venvResult, VENV_TIMEOUT_MS));
   }
 
   progress(`Installing docling ${DOCLING_PIN} and its dependencies — the slow step (large download)…`);
-  const installResult = spawnSync(uv, ['pip', 'install', '--python', pythonBinFor(venvDir), `docling==${DOCLING_PIN}`], {
-    timeout: INSTALL_TIMEOUT_MS,
-    encoding: 'utf8',
-  });
+  const installResult = await runAsync(uv, ['pip', 'install', '--python', pythonBinFor(venvDir), `docling==${DOCLING_PIN}`], { timeoutMs: INSTALL_TIMEOUT_MS });
   if (installResult.status !== 0) {
     throw new Error(describeStepFailure('docling install', installResult, INSTALL_TIMEOUT_MS));
   }

package/lib/service-manager.mjs

@@ -159,10 +159,15 @@ async function isMemoryRunning(port) {
   return probeRuntimePort(port);
 }
 
-async function isOpenCodeRunning(port) {
+async function isBridgeRunning(port) {
   return probeRuntimeHttp(`http://127.0.0.1:${port}/`, { timeoutMs: 1000 });
 }
 
+async function isCopilotBridgeRunning(port) {
+  // Check if the port is reachable.
+  return probeRuntimePort(port);
+}
+
 function spawnDetached(command, args, homeDir, logFile, options = {}) {
   const logPath = path.join(runtimeStateDir(homeDir), logFile);
   fs.mkdirSync(path.dirname(logPath), { recursive: true });
@@ -290,7 +295,7 @@ export async function startDashboard({ rootDir, homeDir = os.homedir(), preferre
 export async function getRuntimePorts(homeDir = os.homedir(), {
   dashboardProbeFn = isDashboardRunning,
   memoryProbeFn = isMemoryRunning,
-  openCodeProbeFn = isOpenCodeRunning,
+  openCodeProbeFn = isBridgeRunning,
   findAvailablePortFn = findAvailablePort,
 } = {}) {
   const dashboard = readDashboardState(homeDir);
@@ -308,6 +313,7 @@ export async function getRuntimePorts(homeDir = os.homedir(), {
     dashboard: dashboard?.port ?? await resolvePort('DASHBOARD_PORT', 4242, dashboardProbeFn),
     memory: await resolvePort('MEMORY_PORT', derivedMemoryPort(), memoryProbeFn),
     bridge: await resolvePort('BRIDGE_PORT', 5173, openCodeProbeFn),
+    copilotBridge: await resolvePort('COPILOT_BRIDGE_PORT', 5174, probeRuntimePort),
   };
 }
 
@@ -324,6 +330,7 @@ export async function describeRuntimeSupport() {
     tmux: commandExists('tmux'),
     cm: commandExists('cm'),
     opencode: commandExists('opencode'),
+    gh: commandExists('gh'),
   };
 }
 
@@ -332,6 +339,7 @@ export const SELECTABLE_SERVICES = Object.freeze([
   { key: 'telemetry', label: 'Telemetry', description: 'Trace export / local JSONL traces.' },
   { key: 'memory', label: 'Memory (cm)', description: 'Persistent memory service (cm).' },
   { key: 'opencode', label: 'OpenCode', description: 'OpenCode bridge server.' },
+  { key: 'copilot-bridge', label: 'Copilot Bridge', description: 'Host-native Copilot bridge proxy (requires gh auth).' },
 ]);
 
 export async function startServices({
@@ -344,7 +352,7 @@ export async function startServices({
   loadConstructEnvFn = loadConstructEnv,
   spawnDetachedFn = spawnDetached,
   memoryProbeFn = isMemoryRunning,
-  openCodeProbeFn = isOpenCodeRunning,
+  openCodeProbeFn = isBridgeRunning,
   runPressureReleaseFn = runPressureRelease,
 } = {}) {
   const support = await describeRuntimeSupportFn();
@@ -357,10 +365,15 @@ export async function startServices({
     DASHBOARD_PORT: String(ports.dashboard),
     MEMORY_PORT: String(ports.memory),
     BRIDGE_PORT: String(ports.bridge),
+    COPILOT_BRIDGE_PORT: String(ports.copilotBridge),
   });
 
   const liveEnv = loadConstructEnvFn({ rootDir, homeDir });
   const results = [];
+  
+  // Set Ollama persistence for local inference performance
+  liveEnv.OLLAMA_KEEP_ALIVE = "-1";
+  
   const pressureReport = runPressureReleaseFn({ env: { ...liveEnv, HOME: homeDir } });
   if (pressureReport?.killed?.length) {
     results.push({
@@ -438,6 +451,27 @@ export async function startServices({
     }
   }
 
+  // Copilot Bridge
+  if (wants('copilot-bridge') && support.gh) {
+    const { detectActiveSessions } = await import('./host-capabilities.mjs');
+    const sessions = detectActiveSessions();
+    if (sessions.includes('github-copilot')) {
+      if (await probeRuntimePort(ports.copilotBridge)) {
+        results.push({ name: 'Copilot Bridge', url: `http://127.0.0.1:${ports.copilotBridge}`, status: 'reused' });
+      } else {
+        const proxyPath = path.join(INSTALL_ROOT, 'lib', 'bridges', 'copilot-proxy.mjs');
+        if (fs.existsSync(proxyPath)) {
+          spawnDetachedFn('node', [proxyPath, '--port', String(ports.copilotBridge)], homeDir, 'copilot-bridge.log');
+          results.push({ name: 'Copilot Bridge', url: `http://127.0.0.1:${ports.copilotBridge}`, status: 'started' });
+        } else {
+          results.push({ name: 'Copilot Bridge', status: 'unavailable', note: 'copilot-proxy binary missing in lib/bridges/' });
+        }
+      }
+    } else {
+      results.push({ name: 'Copilot Bridge', status: 'unavailable', note: 'gh auth status shows no active GitHub session' });
+    }
+  }
+
   const doctor = startDoctor({ rootDir, homeDir });
   if (doctor.started) {
     results.push({ name: 'Doctor', status: 'started', note: `L0 daemon · logs: ${doctor.logPath}` });
@@ -521,6 +555,10 @@ export async function stopServices({
   const openCodeKilled = killPortOwners(bridgePort, spawnSyncFn);
   results.push({ name: 'OpenCode', status: openCodeKilled ? 'stopped' : 'not-running' });
 
+  const copilotBridgePort = Number(envValues.COPILOT_BRIDGE_PORT) || 5174;
+  const copilotBridgeKilled = killPortOwners(copilotBridgePort, spawnSyncFn);
+  results.push({ name: 'Copilot Bridge', status: copilotBridgeKilled ? 'stopped' : 'not-running' });
+
   const stopped = results.filter((r) => r.status === 'stopped' || r.status === 'cleaned').map((r) => r.name);
   return { stopped, results };
 }

package/lib/setup.mjs

@@ -40,7 +40,7 @@ function printHelp() {
   console.log(`Construct install — machine setup (once per machine)
 
 Usage:
-  construct install [--scope=project|user|both] [--yes] [--no-launch-agent] [--reconfigure]
+  construct install [--scope=project|user|both] [--yes] [--no-launch-agent] [--reconfigure] [--with-docling]
 
 Flags:
   --scope=<s>       project | user | both (default: project — see ADR-0029)
@@ -52,6 +52,9 @@ Flags:
   --yes             accept detected defaults without prompting
   --no-launch-agent skip macOS LaunchAgent background service registration
   --reconfigure     re-prompt for service consent, ignoring cached answers
+  --with-docling    eagerly provision the docling document-extraction venv now
+                      (heavy, ~10 min via uv; otherwise provisioned lazily on
+                      first document ingest)
 
 What --scope=user does:
   - creates ~/.construct/config.env
@@ -313,7 +316,8 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
     return;
   }
 
-  const KNOWN_FLAGS = new Set(['--yes', '--no-launch-agent', '--reconfigure', '--help', '-h']);
+  const KNOWN_FLAGS = new Set(['--yes', '--no-launch-agent', '--reconfigure', '--with-docling', '--help', '-h']);
+  const withDocling = argSet.has('--with-docling');
   const unknownFlags = args.filter((a) => {
     if (!a.startsWith('-')) return false;
     if (a.startsWith('--scope=') || a === '--scope') return false;
@@ -392,6 +396,21 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
     console.log(`Embeddings: warmup skipped (${err?.message || 'unknown error'}) — model will load on first use`);
   }
 
+  // Docling (document/PDF extraction) provisions a pinned Python venv via uv,
+  // which is heavy (~10 min) and only needed for document ingest — so it stays
+  // lazy by default and is provisioned eagerly only when the user opts in with
+  // --with-docling. First document ingest still auto-provisions if skipped.
+  if (withDocling) {
+    try {
+      const { ensureDoclingVenv } = await import('./runtime/uv-bootstrap.mjs');
+      console.log('Docling: provisioning Python venv (uv) — this can take several minutes…');
+      const docling = await ensureDoclingVenv();
+      console.log(`Docling: ready (${docling.fresh ? 'provisioned' : 'already present'} at ${docling.venvDir})`);
+    } catch (err) {
+      console.log(`Docling: provisioning skipped (${err?.message || 'unknown error'}) — will provision on first document ingest`);
+    }
+  }
+
   const { isCheapestProviderEnabled, selectCheapestForAllTiers, setCheapestProviderPreference } =
     await import('./model-cheapest-provider.mjs');
   const cheapestAlreadyEnabled = isCheapestProviderEnabled(envPath, { env: process.env });

package/lib/specialists/prompt-schema.mjs

@@ -0,0 +1,162 @@
+/**
+ * lib/specialists/prompt-schema.mjs — validation for hybrid specialist prompt files.
+ *
+ * Specialist prompts are migrating from opaque free-form markdown to a hybrid
+ * shape: YAML frontmatter (structured metadata) + markdown body (the authored
+ * prose), mirroring skills/roles/*.md. This validates the frontmatter and the
+ * canonical-section contract, and gates the highest-value invariant — the
+ * frontmatter `perspective{}` must equal the registry's, since the two
+ * currently duplicate each other and drift silently (ADR-0037).
+ *
+ * A file with no frontmatter is treated as not-yet-converted: reported, never an
+ * error, so the linter can run across a half-migrated corpus. Frontmatter is the
+ * source of truth; section checks are warnings until the body-normalization
+ * phase, so adding frontmatter alone never fails the gate.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+
+export const REQUIRED_FRONTMATTER = ['name', 'role', 'version', 'perspective'];
+export const PERSPECTIVE_FIELDS = ['bias', 'tension', 'openingQuestion', 'failureMode'];
+export const OPTIONAL_FRONTMATTER = ['roleGuidance', 'roleOverlays', 'templates', 'preloadRoleGuidance'];
+export const REQUIRED_SECTIONS = ['Anti-fabrication contract', 'Output format'];
+export const CANONICAL_SECTIONS = [
+  'Orientation', 'Anti-fabrication contract', 'Productive tension',
+  'Opening question', 'Failure mode', 'Domain overlays', 'Output format',
+];
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+
+/**
+ * Split a prompt file into { frontmatter, body }. frontmatter is null when the
+ * file has none (unconverted), or undefined when the YAML failed to parse.
+ */
+export function splitFrontmatter(text) {
+  const raw = String(text ?? '');
+  const m = raw.match(FRONTMATTER_RE);
+  if (!m) return { frontmatter: null, body: raw };
+  try {
+    const fm = yaml.load(m[1]);
+    return { frontmatter: (fm && typeof fm === 'object') ? fm : {}, body: raw.slice(m[0].length) };
+  } catch (err) {
+    return { frontmatter: undefined, body: raw.slice(m[0].length), error: err.message };
+  }
+}
+
+function hasHeading(body, title) {
+  const target = String(title).trim().toLowerCase();
+  const re = /^#{1,6}\s+(.+)$/gm;
+  let m;
+  while ((m = re.exec(body))) {
+    if (m[1].trim().toLowerCase() === target) return true;
+  }
+  return false;
+}
+
+function samePerspective(a, b) {
+  if (!a || !b) return false;
+  return PERSPECTIVE_FIELDS.every((f) => String(a[f] ?? '').trim() === String(b[f] ?? '').trim());
+}
+
+/**
+ * Validate one prompt file's content against the hybrid format.
+ *
+ * @param {object} opts
+ * @param {string} opts.content - raw file content
+ * @param {string} [opts.id] - display id (cx-<role>) for messages
+ * @param {object} [opts.registryEntry] - the matching registry specialist (for drift checks)
+ * @returns {{ converted: boolean, errors: string[], warnings: string[] }}
+ */
+export function validatePromptContent({ content, id = '(prompt)', registryEntry } = {}) {
+  const errors = [];
+  const warnings = [];
+  const { frontmatter, body, error } = splitFrontmatter(content);
+
+  if (frontmatter === null) {
+    return { converted: false, errors, warnings: [`${id}: no frontmatter — not yet converted to the hybrid format`] };
+  }
+  if (frontmatter === undefined) {
+    errors.push(`${id}: frontmatter is not valid YAML — ${error}`);
+    return { converted: true, errors, warnings };
+  }
+
+  for (const field of REQUIRED_FRONTMATTER) {
+    if (frontmatter[field] == null || frontmatter[field] === '') {
+      errors.push(`${id}: missing required frontmatter field "${field}"`);
+    }
+  }
+
+  if (frontmatter.name && registryEntry?.name) {
+    const expected = `cx-${registryEntry.name}`;
+    if (frontmatter.name !== expected) {
+      errors.push(`${id}: frontmatter name "${frontmatter.name}" must equal "${expected}" (registry name)`);
+    }
+  }
+  if (frontmatter.version != null && !Number.isInteger(frontmatter.version)) {
+    errors.push(`${id}: frontmatter version must be an integer (got ${JSON.stringify(frontmatter.version)})`);
+  }
+
+  const persp = frontmatter.perspective;
+  if (persp && typeof persp === 'object') {
+    for (const f of PERSPECTIVE_FIELDS) {
+      if (!persp[f] || !String(persp[f]).trim()) errors.push(`${id}: perspective.${f} is required and must be non-empty`);
+    }
+    if (registryEntry?.perspective && !samePerspective(persp, registryEntry.perspective)) {
+      errors.push(`${id}: perspective{} drifts from registry.json — they must match while both exist (frontmatter is the source of truth; update the registry)`);
+    }
+  } else if (frontmatter.perspective != null) {
+    errors.push(`${id}: perspective must be an object with ${PERSPECTIVE_FIELDS.join(', ')}`);
+  }
+
+  const known = new Set([...REQUIRED_FRONTMATTER, ...OPTIONAL_FRONTMATTER]);
+  for (const key of Object.keys(frontmatter)) {
+    if (!known.has(key)) warnings.push(`${id}: unknown frontmatter key "${key}"`);
+  }
+
+  for (const section of REQUIRED_SECTIONS) {
+    if (!hasHeading(body, section)) warnings.push(`${id}: missing canonical section "## ${section}" (warn-only until body normalization)`);
+  }
+
+  return { converted: true, errors, warnings };
+}
+
+/**
+ * Validate every specialist prompt file referenced by the registry.
+ * @returns {{ errors: string[], warnings: string[], total: number, converted: number }}
+ */
+export function validatePromptFiles({ rootDir = process.cwd(), registry } = {}) {
+  const errors = [];
+  const warnings = [];
+  let total = 0;
+  let converted = 0;
+
+  const reg = registry ?? loadRegistry(rootDir);
+  const specialists = Array.isArray(reg?.specialists) ? reg.specialists : [];
+  const byName = new Map(specialists.map((s) => [s.name, s]));
+
+  const seen = new Set();
+  for (const entry of specialists) {
+    if (!entry?.promptFile || !entry.promptFile.startsWith('specialists/prompts/')) continue;
+    if (seen.has(entry.promptFile)) continue;
+    seen.add(entry.promptFile);
+    const filePath = path.join(rootDir, entry.promptFile);
+    if (!fs.existsSync(filePath)) { errors.push(`${entry.name}: promptFile ${entry.promptFile} does not exist`); continue; }
+    total += 1;
+    const content = fs.readFileSync(filePath, 'utf8');
+    const result = validatePromptContent({ content, id: `cx-${entry.name}`, registryEntry: byName.get(entry.name) });
+    if (result.converted) converted += 1;
+    errors.push(...result.errors);
+    warnings.push(...result.warnings);
+  }
+  return { errors, warnings, total, converted };
+}
+
+function loadRegistry(rootDir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(rootDir, 'specialists', 'registry.json'), 'utf8'));
+  } catch {
+    return { specialists: [] };
+  }
+}

package/lib/specialists/scaffold.mjs

@@ -0,0 +1,109 @@
+/**
+ * lib/specialists/scaffold.mjs — scaffold and field-edit hybrid specialist prompts.
+ *
+ * The CLI harness side of ADR-0037: `construct specialist create` emits a
+ * canonical skeleton (frontmatter + required sections) a human then fills in,
+ * and `construct specialist edit` mutates frontmatter fields only (never the
+ * prose body). Both validate against lib/specialists/prompt-schema.mjs before
+ * declaring success, so a scaffolded file passes `lint:prompts` immediately.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { splitFrontmatter, validatePromptContent, PERSPECTIVE_FIELDS } from './prompt-schema.mjs';
+
+function promptRelPath(role) {
+  return path.join('specialists', 'prompts', `cx-${role}.md`);
+}
+
+/**
+ * Render a canonical skeleton for a new specialist. Body sections are stubbed
+ * with a one-line placeholder so the file is valid-shaped from creation.
+ */
+export function renderSkeleton({ role, perspective = {}, roleGuidance } = {}) {
+  const fm = {
+    name: `cx-${role}`,
+    role,
+    version: 1,
+    perspective: {
+      bias: perspective.bias || 'TODO: what this role is instinctively suspicious of',
+      tension: perspective.tension || 'cx-TODO',
+      openingQuestion: perspective.openingQuestion || 'TODO: the first diagnostic question',
+      failureMode: perspective.failureMode || 'TODO: how this role fails when absent',
+    },
+    ...(roleGuidance ? { roleGuidance } : {}),
+  };
+  const body = [
+    '## Orientation',
+    '',
+    'TODO: the role voice — the hard-won instinct that makes this specialist worth consulting.',
+    '',
+    '## Anti-fabrication contract',
+    '',
+    'Every load-bearing claim cites a source the reader can re-verify. When a fact is not in the source, write `unknown` or `[unverified]`. See `rules/common/no-fabrication.md`.',
+    '',
+    '## Output format',
+    '',
+    'TODO: the artifact this role produces, or the `get_template(...)` it delegates to.',
+    '',
+  ].join('\n');
+  return `---\n${yaml.dump(fm).trimEnd()}\n---\n\n${body}`;
+}
+
+/**
+ * Create a specialist prompt draft on disk. Refuses to overwrite. Validates
+ * the rendered skeleton before writing.
+ * @returns {{ path: string, relPath: string }}
+ */
+export function createSpecialistDraft({ rootDir = process.cwd(), role, perspective, roleGuidance } = {}) {
+  if (!role || !/^[a-z][a-z0-9-]*$/.test(role)) {
+    throw new Error(`invalid role id "${role}" — use lowercase kebab-case (e.g. performance-auditor)`);
+  }
+  const relPath = promptRelPath(role);
+  const filePath = path.join(rootDir, relPath);
+  if (fs.existsSync(filePath)) throw new Error(`${relPath} already exists — refusing to overwrite`);
+
+  const content = renderSkeleton({ role, perspective, roleGuidance });
+  const { errors } = validatePromptContent({ content, id: `cx-${role}` });
+  if (errors.length) throw new Error(`scaffold failed validation:\n  ${errors.join('\n  ')}`);
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content.endsWith('\n') ? content : `${content}\n`);
+  return { path: filePath, relPath };
+}
+
+/**
+ * Edit a specialist's frontmatter only (never the prose body). Supported edits:
+ * set a perspective field, add a role overlay, or bump the version.
+ * @returns {{ path: string, frontmatter: object }}
+ */
+export function editSpecialistFrontmatter({ rootDir = process.cwd(), role, setPerspective = {}, addOverlay, bumpVersion = false } = {}) {
+  const relPath = promptRelPath(role);
+  const filePath = path.join(rootDir, relPath);
+  if (!fs.existsSync(filePath)) throw new Error(`${relPath} does not exist`);
+
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const { frontmatter, body } = splitFrontmatter(raw);
+  if (!frontmatter) throw new Error(`${relPath} has no frontmatter — convert it to the hybrid format first`);
+
+  for (const [field, value] of Object.entries(setPerspective)) {
+    if (!PERSPECTIVE_FIELDS.includes(field)) throw new Error(`unknown perspective field "${field}"`);
+    frontmatter.perspective = { ...(frontmatter.perspective || {}), [field]: value };
+  }
+  if (addOverlay) {
+    const overlays = new Set(Array.isArray(frontmatter.roleOverlays) ? frontmatter.roleOverlays : []);
+    overlays.add(addOverlay);
+    frontmatter.roleOverlays = [...overlays];
+  }
+  if (bumpVersion) {
+    frontmatter.version = (Number.isInteger(frontmatter.version) ? frontmatter.version : 0) + 1;
+  }
+
+  const next = `---\n${yaml.dump(frontmatter).trimEnd()}\n---\n${body.startsWith('\n') ? '' : '\n'}${body}`;
+  const { errors } = validatePromptContent({ content: next, id: `cx-${role}` });
+  if (errors.length) throw new Error(`edit would break validation:\n  ${errors.join('\n  ')}`);
+
+  fs.writeFileSync(filePath, next.endsWith('\n') ? next : `${next}\n`);
+  return { path: filePath, frontmatter };
+}

package/lib/storage/embeddings-engine.mjs

@@ -8,7 +8,10 @@
  *   - local    → ONNX Transformers (Xenova/all-MiniLM-L6-v2, 384d) — DEFAULT
  *   - openai   → OpenAI API (text-embedding-3-small, 1536d)
  *   - ollama   → Ollama server (nomic-embed-text, 768d)
- *   - hashing  → Deterministic bag-of-words (256d) — fallback / test fixture only
+ *   - hashing  → Deterministic bag-of-words (256d) — opt-in via the id only; never
+ *                a silent fallback (256d has no semantics and mismatches the 384d
+ *                vector schema, so an accidental fall-through degrades retrieval
+ *                invisibly). An unknown CONSTRUCT_EMBEDDING_MODEL fails loud.
  *
  * OpenAI policy:
  *   - When CONSTRUCT_EMBEDDING_MODEL=openai and OPENAI_API_KEY is missing,
@@ -28,6 +31,8 @@ const ADAPTERS = {
   hashing: () => import('./embeddings-legacy.mjs'),
 };
 
+const KNOWN_MODELS = new Set(Object.keys(ADAPTERS));
+
 const DEFAULT_MODEL = 'local';
 
 let openaiFallbackWarned = false;
@@ -39,7 +44,16 @@ let openaiFallbackWarned = false;
  */
 function resolveModelId(env) {
   const requested = (env.CONSTRUCT_EMBEDDING_MODEL || DEFAULT_MODEL).toLowerCase();
-  if (requested !== 'openai') return requested;
+  if (requested !== 'openai') {
+    if (!KNOWN_MODELS.has(requested)) {
+      throw new Error(
+        `CONSTRUCT_EMBEDDING_MODEL='${requested}' is not a known embedding model ` +
+        `(${[...KNOWN_MODELS].join('|')}). Fix the value — falling through to the 256d ` +
+        `hashing adapter would silently degrade retrieval and mismatch the vector schema.`
+      );
+    }
+    return requested;
+  }
 
   if (env.OPENAI_API_KEY) return 'openai';
 
@@ -69,7 +83,7 @@ function resolveModelId(env) {
  */
 export async function embedText(text, { env = process.env } = {}) {
   const modelId = resolveModelId(env);
-  const loader = ADAPTERS[modelId] || ADAPTERS.hashing;
+  const loader = ADAPTERS[modelId];
   const { embed } = await loader();
   return embed(text, { env });
 }
@@ -82,7 +96,7 @@ export async function embedText(text, { env = process.env } = {}) {
  */
 export async function embedBatch(texts, { env = process.env } = {}) {
   const modelId = resolveModelId(env);
-  const loader = ADAPTERS[modelId] || ADAPTERS.hashing;
+  const loader = ADAPTERS[modelId];
   const { embedBatch } = await loader();
   return embedBatch(texts, { env });
 }
@@ -94,7 +108,7 @@ export async function embedBatch(texts, { env = process.env } = {}) {
  */
 export async function getEmbeddingModelInfo({ env = process.env } = {}) {
   const modelId = resolveModelId(env);
-  const loader = ADAPTERS[modelId] || ADAPTERS.hashing;
+  const loader = ADAPTERS[modelId];
   const { getModelInfo } = await loader();
   return getModelInfo({ env });
 }

package/lib/telemetry/beads-fallback.mjs

@@ -0,0 +1,40 @@
+/**
+ * lib/telemetry/beads-fallback.mjs — count legacy-lock fallback firings.
+ *
+ * The beads write path is optimistic by default; the exclusive file-lock runs only
+ * as the PATH-3 fallback after optimistic retries exhaust. Whether that fallback
+ * ever fires in practice is the evidence that decides if the lock + wait-queue can
+ * be retired (bead construct-nhn5): one JSON line per firing to
+ * ~/.cx/beads-fallback.jsonl. Zero entries over a representative window = safe to
+ * remove; entries name the bd commands that actually contend.
+ *
+ * Errors here are non-fatal — telemetry must never add a failure mode to the
+ * fallback it observes.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { appendBounded } from '../logging/rotate.mjs';
+import { cxDir } from '../paths.mjs';
+
+export function defaultLogPath() {
+  return path.join(cxDir(), 'beads-fallback.jsonl');
+}
+
+export function logBeadsFallback(event, opts = {}) {
+  const logPath = opts.logPath || defaultLogPath();
+  const entry = {
+    ts: new Date().toISOString(),
+    command: event?.command || 'unknown',
+  };
+  try {
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    appendBounded('beads-fallback', logPath, JSON.stringify(entry) + '\n');
+  } catch { /* best-effort */ }
+}
+
+export function readBeadsFallbacks({ logPath = defaultLogPath() } = {}) {
+  if (!fs.existsSync(logPath)) return [];
+  return fs.readFileSync(logPath, 'utf8').split('\n').filter(Boolean).map((l) => {
+    try { return JSON.parse(l); } catch { return null; }
+  }).filter(Boolean);
+}