@geraldmaron/construct 1.1.0 → 1.2.0

package/lib/setup.mjs

@@ -32,6 +32,9 @@ import { getCanonicalOpenCodeConfigPath, readOpenCodeConfig, writeOpenCodeConfig
 import { getEmbeddingModelInfo, warmupEmbeddingModel } from './storage/embeddings-engine.mjs';
 import { buildPressureGuardValues, installPressureGuardLaunchAgent, loadPressureGuardLaunchAgent } from './runtime-pressure.mjs';
 import { consentToInstall } from './setup-prompts.mjs';
+import { cleanupLegacyGlobalConstruct } from './install/legacy-global-cleanup.mjs';
+import { downloadDesktopBinary } from './install/desktop-binary-download.mjs';
+import { buildDesktopBinary, hasDesktopSource } from './chat/desktop-build.mjs';
 
 const ROOT_DIR = path.resolve(import.meta.dirname, '..');
 const HOME = os.homedir();
@@ -40,7 +43,7 @@ function printHelp() {
   console.log(`Construct install — machine setup (once per machine)
 
 Usage:
-  construct install [--scope=project|user|both] [--yes] [--no-launch-agent] [--reconfigure] [--with-docling]
+  construct install [--scope=project|user|both] [--yes] [--dry-run] [--no-launch-agent] [--reconfigure] [--with-docling] [--cleanup-legacy-global]
 
 Flags:
   --scope=<s>       project | user | both (default: project — see ADR-0029)
@@ -50,11 +53,15 @@ Flags:
                                ~/.claude/* via consent-gated sync).
                       both:    print project guidance, then run user-scope install.
   --yes             accept detected defaults without prompting
+  --dry-run         print the install plan and exit without writing anything
   --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)
+  --cleanup-legacy-global
+                    remove legacy user-global Construct adapters/MCP/history
+                      before setup; does not uninstall a global construct CLI
 
 What --scope=user does:
   - creates ~/.construct/config.env
@@ -306,17 +313,71 @@ function printProjectScopeGuidance() {
   console.log('  construct install --scope=both');
 }
 
+function runLegacyGlobalCleanup({ homeDir, dryRun }) {
+  const result = cleanupLegacyGlobalConstruct({ homeDir, dryRun });
+  const action = dryRun ? 'would remove' : 'removed';
+  console.log(`Legacy global cleanup: ${result.removed.length ? `${action} ${result.removed.length} item(s)` : 'nothing detected'}`);
+  for (const item of result.removed.slice(0, 20)) {
+    console.log(`  - ${item}`);
+  }
+  if (result.removed.length > 20) {
+    console.log(`  - ...and ${result.removed.length - 20} more`);
+  }
+  return result;
+}
+
+// Dry-run renders the user-scope plan as intent only — every line names a write,
+// network call, or service registration that the real run would perform — and
+// returns before touching disk so the preview is provably side-effect-free.
+
+function printInstallPlan({ scope, homeDir, withDocling, noLaunchAgent, cleanupLegacyGlobal }) {
+  console.log('Construct install — dry-run (no changes written)');
+  console.log('────────────────────────────────────────────────');
+  console.log(`Scope: ${scope}`);
+  if (cleanupLegacyGlobal) {
+    console.log('\nLegacy global cleanup:');
+    runLegacyGlobalCleanup({ homeDir, dryRun: true });
+  }
+  if (scope === 'project') {
+    console.log('\nWould not run user-scope setup. Re-run without --dry-run to apply cleanup only.');
+    return;
+  }
+  if (scope === 'both') {
+    console.log('  · would print project-scope guidance, then run the user-scope plan below');
+  }
+  console.log('\nWould write:');
+  console.log(`  · ${getUserEnvPath(homeDir)} (user config, managed defaults)`);
+  console.log(`  · ${getCanonicalOpenCodeConfigPath(homeDir)} (OpenCode config)`);
+  console.log(`  · ${path.join(homeDir, '.construct', 'lib')} → ${path.join(ROOT_DIR, 'lib')} (hook lib symlink)`);
+  console.log(`  · ${path.join(homeDir, '.construct', 'workspace')} (workspace docs scaffold)`);
+  console.log(`  · ${path.dirname(defaultVectorIndexPath(homeDir))} (LanceDB vector store dir)`);
+  console.log('\nWould check / install runtime tooling:');
+  console.log('  · cm (memory CLI) and cass (session search) when available on PATH');
+  console.log('  · construct-chat desktop binary (from GitHub releases → ~/.construct/bin/)');
+  console.log('\nWould reach the network / external services:');
+  console.log('  · embedding model warmup (loads from local cache; offline-safe, no download)');
+  if (withDocling) console.log('  · docling Python venv provisioning via uv (~10 min)');
+  console.log('  · construct sync --quiet, construct sync --global, construct doctor');
+  if (process.platform === 'darwin' && !noLaunchAgent) {
+    console.log('\nWould register macOS LaunchAgent:');
+    console.log(`  · ${path.join(homeDir, 'Library', 'LaunchAgents', 'dev.construct.pressure-release.plist')} (consent-gated)`);
+  }
+  console.log('\nNo files were written. Re-run without --dry-run to apply.');
+}
+
 export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME } = {}) {
   const argSet = new Set(args);
   const isYes = argSet.has('--yes');
   const reconfigure = argSet.has('--reconfigure');
+  const cleanupLegacyGlobal = argSet.has('--cleanup-legacy-global');
 
   if (argSet.has('--help') || argSet.has('-h')) {
     printHelp();
     return;
   }
 
-  const KNOWN_FLAGS = new Set(['--yes', '--no-launch-agent', '--reconfigure', '--with-docling', '--help', '-h']);
+  const KNOWN_FLAGS = new Set(['--yes', '--dry-run', '--no-launch-agent', '--reconfigure', '--with-docling', '--cleanup-legacy-global', '--help', '-h']);
+  const dryRun = argSet.has('--dry-run');
   const withDocling = argSet.has('--with-docling');
   const unknownFlags = args.filter((a) => {
     if (!a.startsWith('-')) return false;
@@ -337,6 +398,23 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
   }
   const scope = scopeResult.scope;
 
+  if (dryRun) {
+    if (scope === 'project' && !cleanupLegacyGlobal) {
+      printProjectScopeGuidance();
+      return;
+    }
+    printInstallPlan({ scope, homeDir, withDocling, noLaunchAgent: argSet.has('--no-launch-agent'), cleanupLegacyGlobal });
+    return;
+  }
+
+  if (cleanupLegacyGlobal) {
+    runLegacyGlobalCleanup({ homeDir, dryRun: false });
+    if (scope === 'project') {
+      printProjectScopeGuidance();
+      return;
+    }
+  }
+
   if (scope === 'project') {
     printProjectScopeGuidance();
     return;
@@ -378,6 +456,28 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
     if (cassInstall.installCommand) console.log(`  Install with: ${cassInstall.installCommand}`);
   }
 
+  try {
+    if (hasDesktopSource(ROOT_DIR)) {
+      const built = buildDesktopBinary({ repoRoot: ROOT_DIR, env: process.env });
+      if (built.ok) {
+        console.log(`Desktop binary: built from source → ${built.binaryPath}`);
+      } else {
+        console.log(`Desktop binary: build skipped (${built.reason}) — runs on first \`construct chat\``);
+      }
+    } else {
+      const desktop = await downloadDesktopBinary({ homeDir, env: process.env });
+      if (desktop.status === 'downloaded') {
+        console.log(`Desktop binary: ${desktop.version} → ${desktop.dest}`);
+      } else if (desktop.status === 'failed') {
+        console.log(`Desktop binary: download failed (${desktop.reason}) — run \`construct install --scope=user\` again to retry`);
+      } else {
+        console.log(`Desktop binary: ${desktop.reason}`);
+      }
+    }
+  } catch (err) {
+    console.log(`Desktop binary: skipped (${err?.message || 'unknown error'})`);
+  }
+
   const telemetryResult = process.env.CONSTRUCT_TELEMETRY_URL
     ? { status: 'configured', note: `remote export configured (${process.env.CONSTRUCT_TELEMETRY_URL})` }
     : { status: 'local', note: 'local JSONL traces in .cx/traces; remote export optional' };

package/lib/specialists/prompt-schema.mjs

@@ -5,8 +5,8 @@
  * 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).
+ * frontmatter `perspective{}` is the sole source of truth (ADR-0037); registry.json
+ * carries routing metadata only.
  *
  * 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
@@ -55,11 +55,6 @@ function hasHeading(body, title) {
   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.
  *
@@ -103,9 +98,6 @@ export function validatePromptContent({ content, id = '(prompt)', registryEntry
     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(', ')}`);
   }
@@ -160,3 +152,20 @@ function loadRegistry(rootDir) {
     return { specialists: [] };
   }
 }
+
+/**
+ * Resolve a specialist's perspective from its prompt frontmatter.
+ * @param {string} agentName - registry name or cx-prefixed id
+ * @returns {object|null}
+ */
+export function resolvePerspectiveFromPrompt(agentName, { rootDir = process.cwd(), registry } = {}) {
+  const reg = registry ?? loadRegistry(rootDir);
+  const normalized = String(agentName ?? '').trim().replace(/^cx-/, '');
+  const entry = (reg.specialists ?? []).find((s) => s.name === normalized);
+  if (!entry?.promptFile) return null;
+  const filePath = path.join(rootDir, entry.promptFile);
+  if (!fs.existsSync(filePath)) return null;
+  const { frontmatter } = splitFrontmatter(fs.readFileSync(filePath, 'utf8'));
+  const persp = frontmatter?.perspective;
+  return persp && typeof persp === 'object' ? persp : null;
+}

package/lib/specialists/roster.mjs

@@ -0,0 +1,43 @@
+/**
+ * lib/specialists/roster.mjs — lazy specialist catalog for runtime resolution
+ * (construct-ymp5).
+ *
+ * The specialist catalog is resolved at runtime through orchestration_policy rather
+ * than inlined into synced orchestrator prompts. Each catalog entry carries id and
+ * whenToUse for routing discovery without an always-on prompt block.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REGISTRY_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'specialists', 'registry.json');
+
+function loadRegistry(rootDir = null) {
+  const path = rootDir
+    ? join(rootDir, 'specialists', 'registry.json')
+    : REGISTRY_PATH;
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+/**
+ * Compact specialist catalog for orchestration_policy responses. Each entry names
+ * the cx-prefixed id and the routing hint (when_to_use when present, else description).
+ */
+export function buildSpecialistCatalog({ rootDir = null, includeInternal = true } = {}) {
+  const registry = loadRegistry(rootDir);
+  const prefix = registry.prefix || 'cx';
+  const specialists = Array.isArray(registry.specialists) ? registry.specialists : [];
+  return specialists
+    .filter((s) => includeInternal || !s.internal)
+    .map((s) => ({
+      id: `${prefix}-${s.name}`,
+      whenToUse: s.when_to_use || s.description || '',
+    }));
+}
+
+/**
+ * Legacy text roster shape retained for tests and migration comparisons.
+ */
+export function formatSpecialistRosterText(catalog) {
+  return catalog.map((row) => `- ${row.id}: ${row.whenToUse}`).join('\n');
+}

package/lib/specialists/scaffold.mjs

@@ -51,6 +51,62 @@ export function renderSkeleton({ role, perspective = {}, roleGuidance } = {}) {
   return `---\n${yaml.dump(fm).trimEnd()}\n---\n\n${body}`;
 }
 
+function buildFrontmatterFromRegistry(role, { perspective, roleGuidance, roleOverlays, docArtifacts } = {}) {
+  if (!perspective || typeof perspective !== 'object') {
+    throw new Error(`perspective is required to wrap legacy prompt cx-${role} (frontmatter is the source of truth)`);
+  }
+  const fm = {
+    name: `cx-${role}`,
+    role,
+    version: 1,
+    perspective,
+  };
+  if (roleGuidance) fm.roleGuidance = roleGuidance;
+  if (Array.isArray(roleOverlays) && roleOverlays.length) fm.roleOverlays = roleOverlays;
+  if (Array.isArray(docArtifacts) && docArtifacts.length) fm.templates = docArtifacts;
+  return fm;
+}
+
+/**
+ * Wrap a legacy prompt body with hybrid frontmatter from the registry entry.
+ * The body bytes are preserved (emit-neutral) aside from a trailing newline.
+ */
+export function wrapLegacyPromptWithFrontmatter({ role, perspective, registryEntry = {}, body }) {
+  const fm = buildFrontmatterFromRegistry(role, {
+    perspective,
+    roleGuidance: registryEntry.roleGuidance,
+    roleOverlays: registryEntry.roleOverlays,
+    docArtifacts: registryEntry.docArtifacts,
+  });
+  const normalizedBody = String(body ?? '').replace(/^\n+/, '');
+  const withNl = normalizedBody.endsWith('\n') ? normalizedBody : `${normalizedBody}\n`;
+  return `---\n${yaml.dump(fm).trimEnd()}\n---\n\n${withNl}`;
+}
+
+/**
+ * Convert one on-disk legacy prompt to hybrid format in place.
+ * @returns {{ path: string, relPath: string, converted: boolean }}
+ */
+export function convertLegacyPromptFile({ rootDir = process.cwd(), role, perspective, registryEntry } = {}) {
+  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) return { path: filePath, relPath, converted: false };
+
+  const persp = perspective ?? registryEntry?.perspective;
+  if (!persp) {
+    throw new Error(`perspective required to convert ${relPath} — pass explicitly or supply registryEntry.perspective`);
+  }
+  const content = wrapLegacyPromptWithFrontmatter({ role, perspective: persp, registryEntry, body });
+  const { errors } = validatePromptContent({ content, id: `cx-${role}`, registryEntry });
+  if (errors.length) throw new Error(`convert ${relPath} failed:\n  ${errors.join('\n  ')}`);
+
+  fs.writeFileSync(filePath, content);
+  return { path: filePath, relPath, converted: true };
+}
+
 /**
  * Create a specialist prompt draft on disk. Refuses to overwrite. Validates
  * the rendered skeleton before writing.

package/lib/storage/backend.mjs

@@ -1,15 +1,15 @@
 /**
  * lib/storage/backend.mjs — shared storage backend helpers.
  *
- * Construct now uses embedded LanceDB and Git-backed state. 
- * createSqlClient and related helpers are retained as stubs to prevent
- * breaking existing imports, but they no longer facilitate local 
- * Postgres orchestration.
+ * Construct uses embedded LanceDB and Git-backed state. createSqlClient and
+ * related helpers are stubs that keep existing imports working without
+ * orchestrating local Postgres.
  */
 
 export function createSqlClient(env = process.env) {
-  // Construct no longer manages local Postgres. External DATABASE_URL is
-  // ignored for local-first operations.
+  // Stub: local-first operations skip Postgres, so external DATABASE_URL has
+  // no effect here.
+
   return null;
 }
 

package/lib/storage/embeddings-local.mjs

@@ -1,9 +1,11 @@
 /**
  * lib/storage/embeddings-local.mjs — Local ONNX embedding via @huggingface/transformers.
  *
- * Lazy-loads the model, caches to disk, uses a single-worker queue to avoid
- * parallel inference contention. Falls back to hashing-bow-v1 if the model
- * fails to load.
+ * Lazy-loads the model from local cache only and runs inference offline. Falls
+ * back to hashing-bow-v1 when the model is absent or fails to load. Remote model
+ * fetching is disabled (allowRemoteModels=false): the runtime path never reaches
+ * the network, so a first run with no cached weights degrades to the hashing
+ * backend rather than downloading from the HuggingFace hub.
  *
  * Model: Xenova/all-MiniLM-L6-v2 (384 dimensions, quantized)
  */
@@ -29,6 +31,7 @@ async function getExtractor(cacheDir) {
   modelPromise = (async () => {
     const { pipeline, env: hfEnv } = await import('@huggingface/transformers');
     hfEnv.allowLocalModels = true;
+    hfEnv.allowRemoteModels = false;
     hfEnv.useBrowserCache = false;
     try {
       const ex = await pipeline('feature-extraction', MODEL_ID, {

package/lib/storage/file-lock.mjs

@@ -50,17 +50,24 @@ function tryAcquire(lockPath) {
     return true;
   } catch (err) {
     if (err.code !== 'EEXIST') throw err;
-    let holder = null;
-    try { holder = Number(readFileSync(lockPath, 'utf8').trim()); } catch { /* unreadable */ }
-    if (!isHolderAlive(holder)) {
-      try { unlinkSync(lockPath); } catch { /* race */ }
-      try {
-        writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
-        heldLocks.add(lockPath);
-        return true;
-      } catch { return false; }
-    }
-    return false;
+
+    // Steal only from a holder we can positively read as dead. An empty or
+    // unreadable pidfile is the mid-create window of a live holder, not a
+    // crash; stealing it would admit two writers and break an append chain.
+    // The acquire timeout still bounds the wait if the holder truly crashed.
+
+    let raw = '';
+    try { raw = readFileSync(lockPath, 'utf8').trim(); } catch { return false; }
+    if (raw === '') return false;
+    const holder = Number(raw);
+    if (!Number.isFinite(holder) || isHolderAlive(holder)) return false;
+
+    try { unlinkSync(lockPath); } catch { /* another stealer won */ }
+    try {
+      writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
+      heldLocks.add(lockPath);
+      return true;
+    } catch { return false; }
   }
 }
 

package/lib/storage/hybrid-query.mjs

@@ -1,21 +1,24 @@
 /**
  * lib/storage/hybrid-query.mjs — unified search across knowledge and facts.
  *
- * This is a stub for the new LanceDB-backed search. 
+ * Stub for the LanceDB-backed search.
  */
 import { VectorClient } from './vector-client.mjs';
 
 export async function buildHybridSearchResultsAsync(rootDir, query, { limit = 10, env = process.env } = {}) {
-  // 1. Embed query
+  // Embed the query
+
   const { embedText } = await import('./embeddings-engine.mjs');
   const { embedding } = await embedText(query, { env });
 
-  // 2. Search LanceDB
+  // Search LanceDB documents and observations
+
   const client = new VectorClient({ env });
   const docs = await client.searchDocuments({ project: 'construct', queryEmbedding: embedding, limit });
   const obs = await client.searchObservations({ project: 'construct', queryEmbedding: embedding, limit });
 
-  // 3. Merge and rank (simple merge for now)
+  // Merge both result sets and rank by similarity
+
   const all = [...docs.map(d => ({ ...d, type: 'document' })), ...obs.map(o => ({ ...o, type: 'observation' }))];
   return all.sort((a, b) => b.similarity - a.similarity).slice(0, limit);
 }

package/lib/storage/state-source.mjs

@@ -4,7 +4,7 @@
  */
 import { existsSync, readdirSync, statSync, readFileSync } from 'node:fs';
 import { basename, extname, join, relative } from 'node:path';
-import { EXTRACTABLE_DOCUMENT_EXTS, extractDocumentText } from '../document-extract.mjs';
+import { EXTRACTABLE_DOCUMENT_EXTS, extractDocumentTextNodeNative } from '../document-extract.mjs';
 
 function readJsonIfExists(filePath) {
   if (!existsSync(filePath)) return null;
@@ -28,7 +28,7 @@ function titleFromPath(filePath) {
   return basename(filePath, extname(filePath)).replace(/[-_]+/g, ' ');
 }
 
-function collectTextFiles(rootDir, dirs, { extensions = EXTRACTABLE_DOCUMENT_EXTS } = {}) {
+async function collectTextFiles(rootDir, dirs, { extensions = EXTRACTABLE_DOCUMENT_EXTS } = {}) {
   const files = [];
   for (const dir of dirs) {
     const abs = join(rootDir, dir);
@@ -47,7 +47,7 @@ function collectTextFiles(rootDir, dirs, { extensions = EXTRACTABLE_DOCUMENT_EXT
         try {
           const stat = statSync(full);
           if (stat.size > 5_000_000) continue;
-          const body = extractDocumentText(full, { maxChars: 200_000 }).text;
+          const body = (await extractDocumentTextNodeNative(full, { maxChars: 200_000 })).text;
           files.push({
             path: relative(rootDir, full),
             title: titleFromPath(full),
@@ -62,12 +62,12 @@ function collectTextFiles(rootDir, dirs, { extensions = EXTRACTABLE_DOCUMENT_EXT
   return files.sort((a, b) => a.path.localeCompare(b.path));
 }
 
-export function loadStateSnapshot(rootDir) {
+export async function loadStateSnapshot(rootDir) {
   const contextJsonPath = join(rootDir, '.cx', 'context.json');
   const planPath = join(rootDir, 'plan.md');
   const architecturePath = join(rootDir, 'docs', 'architecture.md');
   const docsReadmePath = join(rootDir, 'docs', 'README.md');
-  const productIntelDocs = collectTextFiles(rootDir, [
+  const productIntelDocs = await collectTextFiles(rootDir, [
     '.cx/knowledge',
     'docs/prd',
     'docs/meta-prd',

package/lib/storage/sync.mjs

@@ -2,8 +2,7 @@
 /**
  * lib/storage/sync.mjs — sync file-state artifacts into local LanceDB indices.
  *
- * This implementation replaces the Postgres-backed sync with a LanceDB-backed
- * one, matching the new local-first, Git-backed architecture.
+ * Syncs into LanceDB indices, matching the local-first, Git-backed architecture.
  */
 import crypto from 'node:crypto';
 import { loadStateSnapshot } from './state-source.mjs';
@@ -87,7 +86,7 @@ function toDocumentRows(rootDir, snapshot, project = 'construct') {
 }
 
 export async function syncFileStateToSql(rootDir, { env = process.env, project = 'construct' } = {}) {
-  const snapshot = loadStateSnapshot(rootDir);
+  const snapshot = await loadStateSnapshot(rootDir);
   const rows = toDocumentRows(rootDir, snapshot, project);
   
   const modelInfo = await getEmbeddingModelInfo({ env });

package/lib/telemetry/rule-calls.mjs

@@ -0,0 +1,52 @@
+/**
+ * lib/telemetry/rule-calls.mjs — record when a rule path is referenced at runtime.
+ *
+ * Mirrors hook-calls telemetry: append-only JSONL at ~/.cx/rule-calls.jsonl.
+ * Consumed by `construct rules usage` for consolidation decisions.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { appendBounded } from '../logging/rotate.mjs';
+
+export const DEFAULT_LOG_PATH = path.join(os.homedir(), '.cx', 'rule-calls.jsonl');
+
+/**
+ * @param {object} event
+ * @param {string} event.rulePath — e.g. rules/common/no-fabrication.md
+ * @param {string} event.source — mcp | hook | prompt-composer | validation | other
+ * @param {string} [event.callerContext]
+ */
+export function logRuleCall(event, { logPath = DEFAULT_LOG_PATH, env = process.env } = {}) {
+  if (env.CONSTRUCT_RULE_TELEMETRY === 'off') return;
+  const entry = {
+    ts: new Date().toISOString(),
+    rulePath: event.rulePath,
+    source: event.source || 'other',
+    callerContext: event.callerContext || null,
+  };
+  try {
+    appendBounded('rule-calls', logPath, `${JSON.stringify(entry)}\n`);
+  } catch {
+    /* non-fatal */
+  }
+}
+
+export function summarizeRuleCalls({ logPath = DEFAULT_LOG_PATH, since = '30d' } = {}) {
+  if (!fs.existsSync(logPath)) return { rules: {}, total: 0 };
+  const ms = since.endsWith('d') ? parseInt(since, 10) * 86400000 : 30 * 86400000;
+  const cutoff = Date.now() - ms;
+  const rules = {};
+  let total = 0;
+  for (const line of fs.readFileSync(logPath, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const row = JSON.parse(line);
+      if (Date.parse(row.ts) < cutoff) continue;
+      total += 1;
+      rules[row.rulePath] = (rules[row.rulePath] || 0) + 1;
+    } catch { /* skip */ }
+  }
+  return { rules, total, since };
+}

package/lib/template-registry.mjs

@@ -20,7 +20,7 @@ export const SPECIALIST_TEMPLATES = {
   // Tranche 1 — five new templates authored alongside this map.
   'cx-reviewer':        ['code-review-report'],
   'cx-security':        ['security-audit-report'],
-  'cx-qa':              ['qa-report', 'test-plan'],
+  'cx-qa':              ['qa-report', 'test-plan', 'qa-strategy'],
   'cx-debugger':        ['debug-investigation'],
   'cx-devil-advocate':  ['verdict'],
   'cx-evaluator':       ['verdict'],
@@ -31,7 +31,7 @@ export const SPECIALIST_TEMPLATES = {
   // Already-wired specialists pinned here so the gate guards them against drift.
   'cx-architect':       ['adr', 'rfc', 'architecture-review'],
   'cx-researcher':      ['research-brief', 'evidence-brief'],
-  'cx-sre':             ['runbook', 'incident-report'],
+  'cx-sre':             ['runbook', 'incident-report', 'postmortem'],
   'cx-product-manager': ['prd', 'meta-prd'],
 
   // Tranche 2 — three lower-frequency artifacts.