@geraldmaron/construct 1.0.23 → 1.1.0

package/README.md

@@ -269,7 +269,6 @@ construct/
 ├── commands         Command prompt assets
 ├── config
 ├── dashboard
-├── db
 ├── deploy
 ├── docs             Architecture notes, runbooks, and documentation contract
 ├── examples
@@ -282,7 +281,6 @@ construct/
 ├── rules            Coding and quality standards
 ├── schemas
 ├── scripts
-├── services
 ├── skills           Reusable domain knowledge files
 ├── specialists
 ├── templates

package/bin/construct

@@ -67,9 +67,7 @@ import { readCostLog, summarizeCostData, formatCostReport, clearCostLog } from '
 import { readEfficiencyLog, summarizeEfficiencyData, formatEfficiencyReport } from '../lib/efficiency.mjs';
 import { resolveColors } from '../lib/term-format.mjs';
 import { buildHybridSearchResultsAsync } from '../lib/storage/hybrid-query.mjs';
-import { createSqlClient, closeSqlClient, readVectorConfig } from '../lib/storage/backend.mjs';
-import { describeVectorStore } from '../lib/storage/vector-store.mjs';
-import { describeSqlStore } from '../lib/storage/sql-store.mjs';
+import { createSqlClient, closeSqlClient } from '../lib/storage/backend.mjs';
 import { syncFileStateToSql } from '../lib/storage/sync.mjs';
 import { deleteIngestedArtifacts, getStorageStatus, inferProjectName, resetStorage } from '../lib/storage/admin.mjs';
 import { runPressureRelease } from '../lib/runtime-pressure.mjs';
@@ -171,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 });
@@ -822,35 +858,10 @@ async function cmdDoctor() {
     const researchLintResults = lintResearchRepo({ rootDir: process.cwd() });
     add('Research artifacts meet minimum evidence structure', researchLintResults.every((entry) => entry.errors.length === 0), true);
 
-    const sqlConfig = describeSqlStore(process.env);
-    const sqlClient = createSqlClient(process.env);
-    // Track SQL reachability so the schema-migration check can cascade correctly
-    // rather than emitting a redundant second warning for the same offline server.
-    let sqlReachable = false;
-    if (sqlConfig.configured && sqlClient) {
-      try {
-        await sqlClient`select 1 as ok`;
-        sqlReachable = true;
-        add('SQL backend reachable', true);
-      } catch {
-        // In solo mode the local vector index is the active storage path, so an
-        // unreachable Postgres is expected unless the user has started it. Emit a
-        // contextual message rather than a bare ⚠ so the fix is obvious.
-        const { getDeploymentMode } = await import('../lib/deployment-mode.mjs');
-        const mode = getDeploymentMode(process.env) ?? 'solo';
-        const hint = mode === 'solo'
-          ? ' (solo mode — run `construct dev` to start Postgres)'
-          : ' — check DATABASE_URL and that the server is running';
-        add(`SQL backend unreachable${hint}`, false, true);
-      } finally {
-        await closeSqlClient(sqlClient);
-      }
-    } else {
-      add('SQL backend configured', sqlConfig.fallbackAvailable, true);
-    }
-
-    const vectorConfig = describeVectorStore(process.env);
-    add('Vector backend configured', Boolean(vectorConfig.endpoint || vectorConfig.indexPath || vectorConfig.mode === 'file'));
+    const { VectorClient } = await import('../lib/storage/vector-client.mjs');
+    const vectorClient = new VectorClient({ env: process.env });
+    const vectorOk = await vectorClient.isHealthy();
+    add('Vector backend (LanceDB) reachable', vectorOk);
 
     const { regenerateDocs } = await import('../lib/auto-docs.mjs');
     const { changed: stale } = await regenerateDocs({ rootDir: ROOT_DIR, check: true });
@@ -979,35 +990,6 @@ async function cmdDoctor() {
       add('Observation size', false, true);
     }
 
-    // Only run the schema migration check when SQL is both configured AND
-    // currently reachable. If the SQL check above already failed (sqlReachable
-    // is false) this check will also fail with the same ECONNREFUSED and would
-    // produce a redundant second warning about the same offline server.
-    if (sqlConfig.configured && sqlReachable) {
-      try {
-        const migClient = createSqlClient(process.env);
-        if (migClient) {
-          const { describeMigrations } = await import('../lib/storage/migrations.mjs');
-          const m = await describeMigrations(migClient);
-          await closeSqlClient(migClient);
-          const ok = !!m.ok && m.drift.length === 0;
-          let label = 'Schema migrations applied + no drift';
-          if (!ok && m.drift && m.drift.length > 0) {
-            const repairable = m.drift.filter((d) => d.idempotent).length;
-            const notRepairable = m.drift.length - repairable;
-            if (notRepairable === 0) {
-              label = `Schema migrations: ${m.drift.length} drifted (all idempotent — run \`construct storage repair-migrations --yes\`)`;
-            } else {
-              label = `Schema migrations: ${m.drift.length} drifted (${notRepairable} non-idempotent — write a new migration file)`;
-            }
-          }
-          add(label, ok, true);
-        }
-      } catch {
-        add('Schema migrations applied + no drift', false, true);
-      }
-    }
-
     try {
       const { detectBeadsDrift } = await import('../lib/beads/drift.mjs');
       const drift = detectBeadsDrift();
@@ -1037,24 +1019,6 @@ async function cmdDoctor() {
       add('cm available', false, true);
     }
 
-    try {
-      const dockerCli = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['docker'], { stdio: 'pipe' });
-      let dockerOk = false;
-      let dockerNote = 'Docker not installed (optional — managed Postgres needs it)';
-      if (dockerCli.status === 0) {
-        const dockerInfo = spawnSync('docker', ['info'], { stdio: 'pipe' });
-        if (dockerInfo.status === 0) {
-          dockerOk = true;
-          dockerNote = 'Docker daemon reachable';
-        } else {
-          dockerNote = 'Docker CLI installed but daemon not reachable — run `construct up` on macOS to auto-start, or start Docker manually';
-        }
-      }
-      add(dockerOk ? 'Docker daemon reachable' : `Docker daemon reachable (${dockerNote})`, dockerOk, true);
-    } catch {
-      add('Docker daemon reachable', false, true);
-    }
-
     try {
       const failuresPath = path.join(HOME, '.cx', 'hook-failures.jsonl');
       if (fs.existsSync(failuresPath)) {
@@ -1125,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('');
@@ -1569,49 +1596,11 @@ async function cmdStorage(args) {
     println(`Reconciled observations: re-embedded ${result.reembedded} of ${result.checked} (model ${result.model}).`);
     return;
   }
-  if (action === 'migrations') {
-    const { describeMigrations } = await import('../lib/storage/migrations.mjs');
-    const sqlClient = createSqlClient(process.env);
-    if (!sqlClient) { errorln('No DATABASE_URL configured.'); process.exit(1); }
-    try {
-      const report = await describeMigrations(sqlClient);
-      println(JSON.stringify(report, null, 2));
-      if (report.drift?.length > 0) process.exit(2);
-    } finally {
-      await closeSqlClient(sqlClient);
-    }
-    return;
-  }
-  if (action === 'repair-migrations') {
-    const confirm = rest.includes('--yes');
-    if (!confirm) {
-      errorln('This re-applies drifted migrations (idempotent only) and updates their recorded SHA.');
-      errorln('Destructive migrations (DROP / TRUNCATE / ALTER…DROP / DELETE) are refused.');
-      errorln('Re-run with --yes to proceed.');
-      process.exit(1);
-    }
-    const { runMigrations } = await import('../lib/storage/migrations.mjs');
-    const sqlClient = createSqlClient(process.env);
-    if (!sqlClient) { errorln('No DATABASE_URL configured.'); process.exit(1); }
-    try {
-      const result = await runMigrations(sqlClient, { repair: true });
-      println(JSON.stringify({
-        applied: result.applied,
-        repaired: result.repaired,
-        skipped: result.skipped,
-        drift: result.drift,
-      }, null, 2));
-      if (result.drift.length > 0) {
-        errorln('');
-        errorln('Refused to repair non-idempotent migrations:');
-        for (const d of result.drift) errorln(`  ${d.filename}`);
-        process.exit(2);
-      }
-      info(`Repaired ${result.repaired.length} migration(s); applied ${result.applied.length} new.`);
-    } finally {
-      await closeSqlClient(sqlClient);
-    }
-    return;
+  if (action === 'migrations' || action === 'repair-migrations') {
+    // Postgres schema migrations were removed with the SQL backend; LanceDB
+    // tables are created on demand and need no migration runner.
+    errorln('construct storage ' + action + ' is no longer supported: Postgres was removed.');
+    process.exit(1);
   }
   if (action === 'sync') {
     const result = await syncFileStateToSql(process.cwd(), { env: process.env, project: inferProjectName(process.cwd()) });
@@ -3543,6 +3532,7 @@ async function cmdOrchestrate(args) {
       host: flag('--host'),
       hostModel: flag('--host-model'),
       hostProvider: flag('--host-provider'),
+      workerBackend: flag('--worker-backend'),
       fileCount: Number(flag('--file-count') || 0),
       moduleCount: Number(flag('--module-count') || 0),
     };
@@ -4242,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;
   }
@@ -4565,100 +4569,64 @@ async function cmdLintContracts() {
   process.exit(1);
 }
 
-async function cmdBackup(args) {
-  const sub = args[0];
-
-  if (!sub || sub === 'create') {
-    const includeSecrets = args.includes('--include-secrets');
-    const noPrune = args.includes('--no-prune');
-    const keepArg = args.find((a) => a.startsWith('--keep='));
-    const keep = keepArg
-      ? Number(keepArg.split('=')[1])
-      : Number(process.env.CONSTRUCT_BACKUP_RETAIN || 10);
-    const { createBackup, pruneBackups } = await import('../lib/storage/backup.mjs');
-    println('Creating backup…');
-    try {
-      const result = await createBackup({ includeSecrets });
-      ok(`Backup created: ${result.path}`);
-      println(`  Contents: ${result.manifest.contents.join(', ') || '(empty)'}`);
-      if (!includeSecrets) println('  Secrets redacted. Use --include-secrets to include them.');
-      if (!noPrune) {
-        const pruned = pruneBackups({ keep });
-        if (pruned.removed.length) {
-          println(`  Auto-pruned ${pruned.removed.length} old backup(s); kept ${pruned.kept}.`);
-        }
-      }
-    } catch (err) {
-      errorln(`Backup failed: ${err.message}`);
-      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);
+}
 
-  if (sub === 'prune') {
-    const keepArg = args.find((a) => a.startsWith('--keep='));
-    const keep = keepArg
-      ? Number(keepArg.split('=')[1])
-      : Number(process.env.CONSTRUCT_BACKUP_RETAIN || 10);
-    const { pruneBackups } = await import('../lib/storage/backup.mjs');
-    const result = pruneBackups({ keep });
-    if (result.removed.length === 0) {
-      println(`Nothing to prune (have ${result.kept}, keeping ${keep}).`);
-    } else {
-      ok(`Pruned ${result.removed.length} backup(s); kept ${result.kept}.`);
-      for (const r of result.removed) println(`  removed ${r}`);
-    }
-    return;
-  }
+async function cmdSpecialist(args) {
+  const sub = args[0];
+  if (sub === 'lint') return cmdLintPrompts();
 
-  if (sub === 'verify') {
-    const archivePath = args[1];
-    if (!archivePath) { errorln('Usage: construct backup verify <archive>'); process.exit(1); }
-    const { verifyBackup } = await import('../lib/storage/backup.mjs');
-    const result = await verifyBackup(archivePath);
-    if (result.ok) {
-      ok('Backup verified — all checksums match.');
-    } else {
-      errorln(`Backup verification failed:\n  ${result.errors.join('\n  ')}`);
-      process.exit(1);
-    }
+  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 === 'restore') {
-    const archivePath = args[1];
-    const yes = args.includes('--yes');
-    if (!archivePath) { errorln('Usage: construct backup restore <archive> [--yes]'); process.exit(1); }
-    if (!yes) {
-      println(`About to restore from: ${archivePath}`);
-      println('This will overwrite observations, sessions, config.env, and registry.json.');
-      println('Press Ctrl+C to cancel, or re-run with --yes to proceed.');
-      await new Promise((r) => setTimeout(r, 3000));
-    }
-    const { restoreBackup } = await import('../lib/storage/backup.mjs');
-    const result = await restoreBackup(archivePath, { yes });
-    if (result.ok) {
-      ok(`Restored: ${result.restored.join(', ')}`);
-    } else {
-      if (result.restored.length) println(`Partially restored: ${result.restored.join(', ')}`);
-      errorln(`Errors:\n  ${result.errors.join('\n  ')}`);
-      process.exit(1);
+  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;
   }
 
-  if (sub === 'list') {
-    const { listBackups } = await import('../lib/storage/backup.mjs');
-    const backups = listBackups();
-    if (!backups.length) { println('No backups found.'); return; }
-    for (const b of backups) {
-      const mb = (b.size / 1024 / 1024).toFixed(1);
-      println(`  ${b.name}  (${mb} MB)  ${b.mtime.toISOString().slice(0, 19)}`);
-    }
-    return;
-  }
+  errorln(`Unknown specialist subcommand: ${sub || '(none)'}. Available: create, edit, lint`);
+  process.exit(1);
+}
 
-  errorln(`Unknown backup subcommand: ${sub}. Available: create, verify, restore, list, prune`);
+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.
+  void args;
+  errorln('construct backup is no longer supported: Postgres was removed. Commit .cx/ for Git-backed state; the LanceDB index lives under .cx/lancedb.');
   process.exit(1);
 }
 
@@ -5200,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);
@@ -5257,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
@@ -5440,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';