@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/render-visual-check.mjs

@@ -0,0 +1,240 @@
+/**
+ * lib/render-visual-check.mjs — rendered-artifact visual gate for the test:visual script.
+ *
+ * Exports a fixture through the real document-export engines (Pandoc/Typst for PDF, pptxgenjs for
+ * PPTX, Pandoc for DOCX) and asserts what a source-level check cannot: (1) for pdf/pptx — the same
+ * RENDER_REQUIRED_FORMATS output-quality.mjs already treats as render-required — every rasterized
+ * page carries real ink, not a blank/near-blank canvas from a broken template or missing font,
+ * decoded straight from the produced PNG's own IDAT stream with zlib inflate plus PNG filter
+ * reconstruction (no image-decoding dependency needed); (2) runOutputQuality's text-extraction-
+ * parity and on-disk reference-integrity checks pass against the produced file for every format,
+ * reusing the same gate publish.mjs enforces; (3) a renderer required for the requested format that
+ * is absent is reported as a typed, CI-visible failure reason, never a silent skip, because a
+ * visual claim that rests on a tool that was never invoked is not a visual claim. docx has no
+ * raster path in render-pipeline.mjs (only pdf/html/pptx/mermaid/d2), so it is validated via export
+ * plus text/reference checks only, matching the existing render-required contract.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import zlib from 'node:zlib';
+
+import { exportMarkdown, whichBin } from './document-export.mjs';
+import { runOutputQuality } from './output-quality.mjs';
+
+// Below this ink ratio a rasterized page is treated as blank: a faithful export of a
+// multi-paragraph fixture always covers more of the canvas than antialiasing noise or a stray
+// hairline would produce.
+
+const MIN_INK_RATIO = 0.01;
+
+// Formats output-quality.mjs already treats as render-required (RENDER_REQUIRED_FORMATS); only
+// these get rasterized and blank-page checked. docx has no renderer in render-pipeline.mjs.
+
+const RASTER_FORMATS = new Set(['pdf', 'pptx']);
+
+function readPngChunks(pngPath) {
+  const buf = fs.readFileSync(pngPath);
+  const sig = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+  if (!buf.subarray(0, 8).equals(sig)) throw new Error(`${pngPath}: not a PNG (bad signature)`);
+
+  let offset = 8;
+  let header = null;
+  const idatParts = [];
+  while (offset < buf.length) {
+    const len = buf.readUInt32BE(offset);
+    const type = buf.toString('ascii', offset + 4, offset + 8);
+    const data = buf.subarray(offset + 8, offset + 8 + len);
+    if (type === 'IHDR') {
+      header = {
+        width: data.readUInt32BE(0),
+        height: data.readUInt32BE(4),
+        bitDepth: data.readUInt8(8),
+        colorType: data.readUInt8(9),
+      };
+    }
+    if (type === 'IDAT') idatParts.push(data);
+    offset += 8 + len + 4;
+    if (type === 'IEND') break;
+  }
+  if (!header) throw new Error(`${pngPath}: missing IHDR chunk`);
+  if (header.bitDepth !== 8) throw new Error(`${pngPath}: unsupported bit depth ${header.bitDepth} (need 8)`);
+  const channels = { 0: 1, 2: 3, 4: 2, 6: 4 }[header.colorType];
+  if (!channels) throw new Error(`${pngPath}: unsupported color type ${header.colorType}`);
+  return { ...header, channels, raw: zlib.inflateSync(Buffer.concat(idatParts)) };
+}
+
+function paeth(a, b, c) {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  if (pb <= pc) return b;
+  return c;
+}
+
+// Reverses the per-scanline PNG filter (none/sub/up/average/paeth) so pixel values are real
+// sample bytes rather than filter-encoded deltas.
+
+function unfilterPng({ width, height, channels, raw }) {
+  const stride = width * channels;
+  const bpp = channels;
+  const out = Buffer.alloc(height * stride);
+  let pos = 0;
+  for (let y = 0; y < height; y++) {
+    const filter = raw[pos];
+    pos += 1;
+    const rowStart = y * stride;
+    for (let x = 0; x < stride; x++) {
+      const val = raw[pos + x];
+      const a = x >= bpp ? out[rowStart + x - bpp] : 0;
+      const b = y > 0 ? out[rowStart - stride + x] : 0;
+      const c = x >= bpp && y > 0 ? out[rowStart - stride + x - bpp] : 0;
+      let recon;
+      if (filter === 0) recon = val;
+      else if (filter === 1) recon = val + a;
+      else if (filter === 2) recon = val + b;
+      else if (filter === 3) recon = val + Math.floor((a + b) / 2);
+      else if (filter === 4) recon = val + paeth(a, b, c);
+      else throw new Error(`unsupported PNG filter type ${filter} at row ${y}`);
+      out[rowStart + x] = recon & 0xff;
+    }
+    pos += stride;
+  }
+  return out;
+}
+
+// Fraction of pixels that are not near-white (allows antialiasing/JPEG-adjacent noise near 255).
+
+export function inkRatio(pngPath) {
+  const decoded = readPngChunks(pngPath);
+  const pixels = unfilterPng(decoded);
+  const { channels } = decoded;
+  let inked = 0;
+  let total = 0;
+  for (let i = 0; i < pixels.length; i += channels) {
+    total += 1;
+    const r = pixels[i];
+    const g = channels >= 2 ? pixels[i + 1] : r;
+    const b = channels >= 3 ? pixels[i + 2] : r;
+    if (r < 245 || g < 245 || b < 245) inked += 1;
+  }
+  return total === 0 ? 0 : inked / total;
+}
+
+function rasterizePdf(pdfPath, outDir) {
+  const result = spawnSync('pdftoppm', ['-png', '-r', '72', pdfPath, path.join(outDir, 'page')], { encoding: 'utf8' });
+  if (result.status !== 0) throw new Error(`pdftoppm failed: ${(result.stderr || '').trim()}`);
+  return fs.readdirSync(outDir)
+    .filter((f) => f.startsWith('page') && f.endsWith('.png'))
+    .sort()
+    .map((f) => path.join(outDir, f));
+}
+
+// pptx has no direct rasterizer; render-pipeline.mjs's own pptx path goes soffice -> pdf ->
+// pdftoppm, so this mirrors that exact chain rather than inventing a second one.
+
+function rasterizePptx(pptxPath, outDir, env) {
+  const soffice = whichBin('soffice', env) || whichBin('libreoffice', env);
+  if (!soffice) return { ok: false, reason: 'missing-dependency', message: 'soffice/libreoffice not on PATH' };
+  const conv = spawnSync(soffice, ['--headless', '--convert-to', 'pdf', '--outdir', outDir, pptxPath], { encoding: 'utf8' });
+  if (conv.status !== 0) return { ok: false, reason: 'unavailable-renderer', message: (conv.stderr || '').trim() || 'soffice convert failed' };
+  const pdf = path.join(outDir, `${path.parse(pptxPath).name}.pdf`);
+  if (!fs.existsSync(pdf)) return { ok: false, reason: 'unavailable-renderer', message: 'soffice produced no pdf' };
+  return { ok: true, images: rasterizePdf(pdf, outDir) };
+}
+
+const REQUIRED_ENGINES = {
+  pdf: ['pandoc', 'typst', 'pdftoppm'],
+  pptx: ['pandoc', 'soffice', 'pdftoppm'],
+  docx: ['pandoc'],
+};
+
+export function requiredEngineStatus(format, env = process.env) {
+  const names = REQUIRED_ENGINES[format] || [];
+  const missing = names.filter((name) => {
+    if (name === 'soffice') return !whichBin('soffice', env) && !whichBin('libreoffice', env);
+    return !whichBin(name, env);
+  });
+  return { format, required: names, missing, present: missing.length === 0 };
+}
+
+// Runs the full rendered-artifact gate for one format: export via the real engine, rasterize when
+// the format is render-required, assert non-blank pages, and run the shared output-quality checks
+// (text parity + references) against the produced file. Returns a typed failure (never throws)
+// when a required engine is absent, so the caller can fail the process loudly instead of skipping.
+
+export function checkRenderedArtifact({ fixturePath, format, workDir, env = process.env } = {}) {
+  const engineStatus = requiredEngineStatus(format, env);
+  if (!engineStatus.present) {
+    const message = `test:visual requires real engines for ${format} but ${engineStatus.missing.join(', ')} ${engineStatus.missing.length > 1 ? 'are' : 'is'} not on PATH. Install: ${engineStatus.missing.join(', ')}. This is a hard failure: a rendered-artifact claim cannot rest on a tool that never ran.`;
+    return { ok: false, format, skipped: false, reason: 'missing-dependency', message, failures: [message] };
+  }
+
+  const dir = workDir || fs.mkdtempSync(path.join(os.tmpdir(), `cx-visual-${format}-`));
+  const outputPath = path.join(dir, `artifact.${format}`);
+  const sourceMarkdown = fs.readFileSync(fixturePath, 'utf8');
+
+  const exported = exportMarkdown({ inputPath: fixturePath, outputPath, format, env });
+  if (!exported.ok) {
+    const message = `export failed for ${format}: ${exported.message}`;
+    return { ok: false, format, skipped: false, reason: 'export-failed', message, failures: [message] };
+  }
+
+  let images = [];
+  if (RASTER_FORMATS.has(format)) {
+    if (format === 'pdf') {
+      images = rasterizePdf(outputPath, dir);
+    } else {
+      const raster = rasterizePptx(outputPath, dir, env);
+      if (!raster.ok) {
+        const message = `rasterize failed for ${format}: ${raster.message}`;
+        return { ok: false, format, skipped: false, reason: raster.reason, message, failures: [message] };
+      }
+      images = raster.images;
+    }
+    if (images.length === 0) {
+      const message = `${format} export produced zero rasterizable pages`;
+      return { ok: false, format, skipped: false, reason: 'no-pages', message, failures: [message] };
+    }
+  }
+
+  const blankPages = [];
+  const ratios = [];
+  for (const image of images) {
+    const ratio = inkRatio(image);
+    ratios.push(ratio);
+    if (ratio < MIN_INK_RATIO) blankPages.push({ image, ratio });
+  }
+
+  const quality = runOutputQuality({
+    exportPath: outputPath,
+    format,
+    sourceMarkdown,
+    baseDir: path.dirname(fixturePath),
+    gateLevel: 'render-smoke',
+    env,
+  });
+
+  const failures = [];
+  if (blankPages.length > 0) {
+    failures.push(`${blankPages.length}/${images.length} rendered page(s) are blank (ink ratio < ${MIN_INK_RATIO}): ${blankPages.map((p) => `${path.basename(p.image)}=${p.ratio.toFixed(4)}`).join(', ')}`);
+  }
+  for (const f of quality.failures) failures.push(f);
+
+  return {
+    ok: failures.length === 0,
+    format,
+    skipped: false,
+    pageCount: images.length,
+    inkRatios: ratios,
+    quality,
+    failures,
+    message: failures.length === 0
+      ? `${format}: ${images.length ? `${images.length} page(s) rendered, all non-blank; ` : ''}text parity and references verified`
+      : failures.join('; '),
+  };
+}

package/lib/resources/budget.mjs

@@ -1,11 +1,12 @@
 /**
- * lib/resources/budget.mjs — disk-budget enforcement for .cx/ assets.
+ * lib/resources/budget.mjs — disk-budget enforcement for Construct's
+ * generated project state.
  *
  * Construct generates data continuously: traces, intake archives, task
  * graphs, worker logs, session records, backups. None of it has a
- * natural ceiling, so left unchecked the .cx/ tree grows until it
- * threatens the operator's disk. The budget primitive caps each
- * category against a config-defined ceiling.
+ * natural ceiling, so left unchecked the tree grows until it threatens
+ * the operator's disk. The budget primitive caps each category against
+ * a config-defined ceiling.
  *
  * Two enforcement modes:
  *   - **Hard-reject** (traces, worker logs): observability is
@@ -17,6 +18,13 @@
  *     load-bearing — never reject; emit a warning the operator can
  *     see in the doctor surface, and pruning gets aggressive.
  *
+ * Category locations (ADR-0066): traces and worker-logs are the two
+ * hard-reject, highest-volume categories, so they resolve through the
+ * machine-scoped state root (`resolveStateDir`) rather than the
+ * project's own `.cx/`. The remaining soft-warn categories are smaller
+ * and still project-local. "Total .cx/ cap" therefore really means
+ * "total generated-state cap" and sums bytes across both locations.
+ *
  * Defaults live in DEFAULT_PROJECT_CONFIG.resources. The operator
  * raises them in construct.config.json or via the dashboard. Doctor
  * surfaces usage vs cap at 80% (warn) and 100% (fail).
@@ -24,13 +32,17 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { loadProjectConfig } from '../config/project-config.mjs';
+import { resolveStateDir } from '../state-root.mjs';
 
 export const HARD_REJECT_CATEGORIES = new Set(['traces', 'worker-logs']);
 export const SOFT_WARN_CATEGORIES = new Set(['intake-archive', 'task-graphs', 'sessions', 'backups', 'handoffs']);
 
-const CATEGORY_PATHS = {
-  traces: '.cx/traces',
-  'worker-logs': '.cx/runtime/worker',
+const STATE_ROOT_CATEGORY_SEGMENTS = {
+  traces: ['traces'],
+  'worker-logs': ['runtime', 'worker'],
+};
+
+const PROJECT_LOCAL_CATEGORY_PATHS = {
   'intake-archive': '.cx/intake/processed',
   'intake-skipped': '.cx/intake/skipped',
   'task-graphs': '.cx/task-graphs',
@@ -39,6 +51,19 @@ const CATEGORY_PATHS = {
   handoffs: '.cx/handoffs',
 };
 
+const CATEGORY_NAMES = [...Object.keys(STATE_ROOT_CATEGORY_SEGMENTS), ...Object.keys(PROJECT_LOCAL_CATEGORY_PATHS)];
+
+// ensureDir:false — this module only measures/prunes usage, it never itself
+// writes a trace or worker-log file, so a measurement call must not conjure
+// the directory it is merely checking.
+
+function categoryDir(projectRoot, name) {
+  const stateSegments = STATE_ROOT_CATEGORY_SEGMENTS[name];
+  if (stateSegments) return resolveStateDir(projectRoot, ...stateSegments, { ensureDir: false });
+  const rel = PROJECT_LOCAL_CATEGORY_PATHS[name];
+  return rel ? path.join(projectRoot, rel) : null;
+}
+
 function loadResourceBudgets(projectRoot, env) {
   const { config } = loadProjectConfig(projectRoot, env);
   return config?.resources ?? {};
@@ -67,13 +92,13 @@ function walkDirSize(dir) {
 export function measureUsage(projectRoot, env = process.env) {
   const budgets = loadResourceBudgets(projectRoot, env);
   const result = { categories: {}, totalCxBytes: 0, totalCxCap: (budgets?.disk?.totalCxMaxMb ?? 2000) * 1024 * 1024 };
-  for (const [name, rel] of Object.entries(CATEGORY_PATHS)) {
-    const full = path.join(projectRoot, rel);
+  for (const name of CATEGORY_NAMES) {
+    const full = categoryDir(projectRoot, name);
     const { bytes, files } = walkDirSize(full);
     result.categories[name] = {
       bytes,
       files,
-      path: rel,
+      path: full,
       enforcement: HARD_REJECT_CATEGORIES.has(name) ? 'hard-reject' : 'soft-warn',
     };
     result.totalCxBytes += bytes;
@@ -93,7 +118,7 @@ export function warnBudgetOnce(message, env = process.env) {
 }
 
 export function reserveOrReject(projectRoot, category, sizeBytes, env = process.env) {
-  if (!CATEGORY_PATHS[category]) {
+  if (!CATEGORY_NAMES.includes(category)) {
     return { ok: true, source: 'unknown-category' };
   }
   const usage = measureUsage(projectRoot, env);
@@ -123,10 +148,8 @@ export function reserveOrReject(projectRoot, category, sizeBytes, env = process.
 function listHardRejectFiles(projectRoot) {
   const files = [];
   for (const cat of HARD_REJECT_CATEGORIES) {
-    const rel = CATEGORY_PATHS[cat];
-    if (!rel) continue;
-    const dir = path.join(projectRoot, rel);
-    if (!fs.existsSync(dir)) continue;
+    const dir = categoryDir(projectRoot, cat);
+    if (!dir || !fs.existsSync(dir)) continue;
     const walk = (current) => {
       for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
         const full = path.join(current, entry.name);
@@ -199,7 +222,7 @@ export function planPrune(projectRoot, env = process.env, opts = {}) {
   const actions = [];
 
   const tracesMaxDays = disk.tracesMaxDays ?? 30;
-  const tracesDir = path.join(projectRoot, '.cx/traces');
+  const tracesDir = categoryDir(projectRoot, 'traces');
   if (fs.existsSync(tracesDir)) {
     const cutoff = now - tracesMaxDays * 24 * 60 * 60 * 1000;
     for (const f of fs.readdirSync(tracesDir)) {
@@ -258,7 +281,7 @@ export function planPrune(projectRoot, env = process.env, opts = {}) {
     }
   }
 
-  const workerDir = path.join(projectRoot, '.cx/runtime/worker');
+  const workerDir = categoryDir(projectRoot, 'worker-logs');
   const workerMaxMb = disk.workerLogsMaxMb ?? 100;
   const workerMaxDays = disk.workerLogsMaxDays ?? 14;
   if (fs.existsSync(workerDir)) {

package/lib/roles/flavor-bindings.mjs

@@ -7,33 +7,39 @@
  *
  * baseOnly: classifier value "core" loads the base role file (no .flavor suffix).
  * See ADR-0047 for when to split specialists vs add flavors.
+ *
+ * construct-rf26.11 folded 15 of the 29 legacy specialists into 11 surviving
+ * worker anchors as skill bundles rather than separate personas. rolePrefix
+ * and classifierKey are unchanged (the skills/roles/*.md overlay files and
+ * the classifier heuristics that detect them are untouched); only
+ * specialistId is repointed to the anchor that now loads that overlay.
  */
 
 export const SPECIALIST_FLAVOR_BINDINGS = {
   engineer: { classifierKey: 'engineer', rolePrefix: 'engineer', specialistId: 'cx-engineer' },
-  'ai-engineer': { classifierKey: 'aiEngineer', rolePrefix: 'ai-engineer', specialistId: 'cx-ai-engineer', baseOnly: true },
-  'platform-engineer': { classifierKey: 'platformEngineer', rolePrefix: 'platform-engineer', specialistId: 'cx-platform-engineer', baseOnly: true },
-  'data-engineer': { classifierKey: 'dataEngineer', rolePrefix: 'data-engineer', specialistId: 'cx-data-engineer' },
+  'ai-engineer': { classifierKey: 'aiEngineer', rolePrefix: 'ai-engineer', specialistId: 'cx-engineer', baseOnly: true },
+  'platform-engineer': { classifierKey: 'platformEngineer', rolePrefix: 'platform-engineer', specialistId: 'cx-engineer', baseOnly: true },
+  'data-engineer': { classifierKey: 'dataEngineer', rolePrefix: 'data-engineer', specialistId: 'cx-engineer' },
   architect: { classifierKey: 'architect', rolePrefix: 'architect', specialistId: 'cx-architect' },
   'product-manager': { classifierKey: 'productManager', rolePrefix: 'product-manager', specialistId: 'cx-product-manager' },
-  'business-strategist': { classifierKey: 'businessStrategist', rolePrefix: 'business-strategist', specialistId: 'cx-business-strategist', baseOnly: true },
+  'business-strategist': { classifierKey: 'businessStrategist', rolePrefix: 'business-strategist', specialistId: 'cx-product-manager', baseOnly: true },
   qa: { classifierKey: 'qa', rolePrefix: 'qa', specialistId: 'cx-qa' },
-  'test-automation': { classifierKey: 'testAutomation', rolePrefix: 'test-automation', specialistId: 'cx-test-automation', baseOnly: true },
+  'test-automation': { classifierKey: 'testAutomation', rolePrefix: 'test-automation', specialistId: 'cx-qa', baseOnly: true },
   security: { classifierKey: 'security', rolePrefix: 'security', specialistId: 'cx-security' },
   'data-analyst': { classifierKey: 'dataAnalyst', rolePrefix: 'data-analyst', specialistId: 'cx-data-analyst' },
-  sre: { classifierKey: 'sre', rolePrefix: 'sre', specialistId: 'cx-sre', baseOnly: true },
+  sre: { classifierKey: 'sre', rolePrefix: 'sre', specialistId: 'cx-operations', baseOnly: true },
   operations: { classifierKey: 'operations', rolePrefix: 'operations', specialistId: 'cx-operations', baseOnly: true },
-  'release-manager': { classifierKey: 'releaseManager', rolePrefix: 'release-manager', specialistId: 'cx-release-manager', baseOnly: true },
-  'docs-keeper': { classifierKey: 'docsKeeper', rolePrefix: 'docs-keeper', specialistId: 'cx-docs-keeper', baseOnly: true },
+  'release-manager': { classifierKey: 'releaseManager', rolePrefix: 'release-manager', specialistId: 'cx-operations', baseOnly: true },
+  'docs-keeper': { classifierKey: 'docsKeeper', rolePrefix: 'docs-keeper', specialistId: 'cx-operations', baseOnly: true },
   reviewer: { classifierKey: 'reviewer', rolePrefix: 'reviewer', specialistId: 'cx-reviewer' },
-  'devil-advocate': { classifierKey: 'devilAdvocate', rolePrefix: 'devil-advocate', specialistId: 'cx-devil-advocate', baseOnly: true },
-  evaluator: { classifierKey: 'evaluator', rolePrefix: 'evaluator', specialistId: 'cx-evaluator', baseOnly: true },
-  'trace-reviewer': { classifierKey: 'traceReviewer', rolePrefix: 'trace-reviewer', specialistId: 'cx-trace-reviewer', baseOnly: true },
+  'devil-advocate': { classifierKey: 'devilAdvocate', rolePrefix: 'devil-advocate', specialistId: 'cx-reviewer', baseOnly: true },
+  evaluator: { classifierKey: 'evaluator', rolePrefix: 'evaluator', specialistId: 'cx-reviewer', baseOnly: true },
+  'trace-reviewer': { classifierKey: 'traceReviewer', rolePrefix: 'trace-reviewer', specialistId: 'cx-reviewer', baseOnly: true },
   researcher: { classifierKey: 'researcher', rolePrefix: 'researcher', specialistId: 'cx-researcher' },
-  'ux-researcher': { classifierKey: 'uxResearcher', rolePrefix: 'ux-researcher', specialistId: 'cx-ux-researcher', baseOnly: true },
-  explorer: { classifierKey: 'explorer', rolePrefix: 'explorer', specialistId: 'cx-explorer', baseOnly: true },
+  'ux-researcher': { classifierKey: 'uxResearcher', rolePrefix: 'ux-researcher', specialistId: 'cx-researcher', baseOnly: true },
+  explorer: { classifierKey: 'explorer', rolePrefix: 'explorer', specialistId: 'cx-researcher', baseOnly: true },
   designer: { classifierKey: 'designer', rolePrefix: 'designer', specialistId: 'cx-designer' },
-  accessibility: { classifierKey: 'accessibility', rolePrefix: 'designer.accessibility', specialistId: 'cx-accessibility', baseOnly: true },
+  accessibility: { classifierKey: 'accessibility', rolePrefix: 'designer.accessibility', specialistId: 'cx-designer', baseOnly: true },
   debugger: { classifierKey: 'debugger', rolePrefix: 'debugger', specialistId: 'cx-debugger', baseOnly: true },
 };
 
@@ -45,10 +51,26 @@ const BY_SPECIALIST = Object.fromEntries(
   Object.entries(SPECIALIST_FLAVOR_BINDINGS).map(([name, b]) => [name, b]),
 );
 
+// Reverse index: since construct-rf26.11, several short-name keys above share
+// a single specialistId (e.g. engineer/ai-engineer/platform-engineer/
+// data-engineer all point at cx-engineer). bindingForSpecialist(shortName)
+// only ever returns the entry whose OWN key matches the short name, so a
+// caller resolving a flavor by specialistId (rather than by the historical
+// short name) needs every candidate binding for that id, not just one.
+const BY_SPECIALIST_ID = new Map();
+for (const binding of Object.values(SPECIALIST_FLAVOR_BINDINGS)) {
+  if (!BY_SPECIALIST_ID.has(binding.specialistId)) BY_SPECIALIST_ID.set(binding.specialistId, []);
+  BY_SPECIALIST_ID.get(binding.specialistId).push(binding);
+}
+
 export function bindingForSpecialist(shortName) {
   return BY_SPECIALIST[shortName] ?? null;
 }
 
+export function bindingsForSpecialistId(specialistId) {
+  return BY_SPECIALIST_ID.get(specialistId) ?? [];
+}
+
 export function bindingForClassifier(classifierKey) {
   return BY_CLASSIFIER[classifierKey] ?? null;
 }

package/lib/roles/gateway.mjs

@@ -196,7 +196,14 @@ export function shouldEscalate(event, manifest, now = Date.now()) {
   return { escalate: false, reason: 'below-threshold', count: hits };
 }
 
-async function createBdIncident(event, routeResult) {
+// The bd client is injectable so tests can intercept the escalation path
+// without reaching the real, shared bd/dolt database (construct-y4iv) --
+// CONSTRUCT_ROLES_ROOT isolates the dedup-fingerprint state but is also set
+// legitimately in production (lib/oracle/execute.mjs), so it can't double as
+// a "we're in a test" signal. Callers that don't inject a client get the real
+// one, so production behavior (and every other existing caller) is unchanged.
+
+async function createBdIncident(event, routeResult, { runBd: runBdImpl = runBd } = {}) {
    // Dedup: check if this fingerprint has already been raised as a bead
    if (fingerprintAlreadyRaised(event.fingerprint)) {
      return { success: true, skipped: true, reason: 'fingerprint-already-raised', fingerprint: event.fingerprint };
@@ -221,7 +228,7 @@ async function createBdIncident(event, routeResult) {
      null,
      2
    );
-   const result = await runBd(
+   const result = await runBdImpl(
      ['create', title, '-t', 'bug', '-l', labels, '-d', body],
      { actor: `roles:${routeResult.personaId}`, silent: true, timeoutSeconds: 10, commandTimeoutSeconds: 30 }
    );
@@ -246,7 +253,7 @@ async function emitToastBestEffort(payload) {
   } catch { /* dashboard not loaded; toast is best-effort */ }
 }
 
-export async function tryEscalate(event) {
+export async function tryEscalate(event, deps = {}) {
   const r = routeEvent(event);
   if (!r) return { escalated: false, event, reason: 'no-owner' };
 
@@ -267,7 +274,7 @@ export async function tryEscalate(event) {
     }
   } catch { /* cost ledger optional — never block on missing module */ }
 
-  const bd = await createBdIncident(event, r);
+  const bd = await createBdIncident(event, r, deps);
   if (!bd.success) {
     return { escalated: false, event, reason: 'bd-create-failed', error: bd.error };
   }
@@ -299,12 +306,12 @@ export async function tryEscalate(event) {
   return { escalated: true, event, personaId: r.personaId, bdIssueId: bd.issueId, decision };
 }
 
-export async function recordAndMaybeInvoke(eventType, payload = {}) {
+export async function recordAndMaybeInvoke(eventType, payload = {}, deps = {}) {
   if (process.env.CONSTRUCT_ROLES === 'off') {
     return { recorded: false, escalated: false, reason: 'global-off' };
   }
   const event = emit(eventType, payload);
-  const r = await tryEscalate(event);
+  const r = await tryEscalate(event, deps);
   return { recorded: true, ...r };
 }
 
@@ -366,7 +373,7 @@ export function prunePending({ now = Date.now() } = {}) {
 // events.jsonl, runs each unescalated one through tryEscalate. Bounded by
 // `sinceMs` and `maxProcess` so a long-quiet machine can't trigger a flood.
 
-export async function processBacklog({ sinceMs = 60 * 60 * 1000, maxProcess = 10 } = {}) {
+export async function processBacklog({ sinceMs = 60 * 60 * 1000, maxProcess = 10, deps = {} } = {}) {
   if (process.env.CONSTRUCT_ROLES === 'off') return { processed: 0, escalated: 0, reason: 'global-off' };
 
   const ep = _paths.eventsPath();
@@ -390,7 +397,7 @@ export async function processBacklog({ sinceMs = 60 * 60 * 1000, maxProcess = 10
   for (const e of candidates.reverse()) {
     if (processed >= maxProcess) break;
     processed++;
-    const r = await tryEscalate(e);
+    const r = await tryEscalate(e, deps);
     if (r.escalated) escalated++;
   }
   return { processed, escalated };

package/lib/roots.mjs

@@ -0,0 +1,107 @@
+/**
+ * lib/roots.mjs — canonical resolution of the three directory concepts in Construct.
+ *
+ * packageRoot  — where the construct npm package is installed. Resolved from
+ *                import.meta.url, stable across global install, npx, and local
+ *                dev symlinks. Points to the directory that contains
+ *                construct's own package.json. Locate bundled assets here:
+ *                personas, skills, templates, schemas, hooks.
+ *
+ * projectRoot  — the user's repo being operated on. Discovered at runtime by
+ *                inspecting --project <dir> in argv, then walking up from cwd
+ *                looking for .cx/ or package.json. Falls back to cwd when no
+ *                marker is found. Services (oracle, embed, telemetry) that
+ *                read or write to the user's repo must use this, not
+ *                packageRoot.
+ *
+ * cwd          — process.cwd(). Useful for relative-path resolution before
+ *                projectRoot is determined. Callers should prefer
+ *                projectRoot once it is resolved.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Under `bun build --compile`, every module's import.meta.url/dirname resolves
+// inside the bundle's virtual filesystem (`/$bunfs/root/...`) rather than a
+// real on-disk path, so any install-root resolution derived from it collapses
+// to a directory that does not exist and every sibling-data-dir read (skills/,
+// specialists/, templates/, config/, registry/) throws ENOENT. process.execPath
+// still reports the compiled binary's real on-disk location, so callers whose
+// naive resolution lands inside /$bunfs fall back to the binary's own
+// directory. This assumes the data directories ship next to the binary
+// (true for the CI/dev smoke path — dist/<binary> sits one level below the
+// checkout root, the same depth bin/construct and lib/roots.mjs assume); a
+// fully standalone end-user install still needs its own asset story
+// (embedded assets or a co-installed data tree), tracked separately.
+
+const BUN_VIRTUAL_FS_PREFIX = '/$bunfs';
+
+export function isBunCompiledVirtualPath(candidatePath) {
+  return typeof process.versions?.bun === 'string' && candidatePath.startsWith(BUN_VIRTUAL_FS_PREFIX);
+}
+
+export function resolveInstallRoot(naiveRoot, { execPath = process.execPath, upFromBinary = 1 } = {}) {
+  if (!isBunCompiledVirtualPath(naiveRoot)) return naiveRoot;
+  return path.resolve(path.dirname(execPath), ...Array(upFromBinary).fill('..'));
+}
+
+// Two dozen lib/*.mjs files use the standard Node "was I run directly"
+// idiom (`import.meta.url === file://${process.argv[1]}`) so they double as
+// standalone scripts. Under a Bun-compiled binary, every bundled module's
+// import.meta.url collapses to the same virtual bunfs path as process.argv[1]
+// (both point at the single compiled executable), so that comparison is true
+// for every one of those files simultaneously — each runs its own top-level
+// CLI logic as an unwanted side effect of merely being imported, and the
+// first one whose logic throws (e.g. lib/headhunt.mjs's bare invocation
+// requiring --for) takes the whole binary down before bin/construct's real
+// dispatch ever executes. There is exactly one legitimate entry point inside
+// a compiled binary (bin/construct itself), so this always resolves false
+// under Bun-compile regardless of the module asking.
+
+export function isMainModule(moduleUrl) {
+  if (typeof process.versions?.bun === 'string' && isBunCompiledVirtualPath(process.argv[1] || '')) {
+    return false;
+  }
+  return moduleUrl === `file://${process.argv[1]}`;
+}
+
+// lib/roots.mjs lives one level below the package root (<package>/lib/roots.mjs).
+
+export const packageRoot = resolveInstallRoot(path.resolve(fileURLToPath(import.meta.url), '..', '..'));
+
+// Walk upward from `start`, looking for .cx/ first (Construct project marker),
+// then package.json (generic JS project root). Stops at filesystem root.
+
+function walkUp(start) {
+  let dir = path.resolve(start);
+  while (true) {
+    if (fs.existsSync(path.join(dir, '.cx'))) return dir;
+    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Resolve the project root for the user's repo.
+ *
+ * Resolution order:
+ *   1. --project <dir> in process.argv (explicit override)
+ *   2. Walk upward from cwd looking for .cx/ or package.json
+ *   3. cwd itself as a last resort
+ *
+ * Pass a cwd argument when the caller controls the starting directory (tests,
+ * sub-process workers). Omit it in top-level CLI code to use process.cwd().
+ */
+export function resolveProjectRoot(cwd = process.cwd()) {
+  const argv = process.argv;
+  const flagIndex = argv.indexOf('--project');
+  if (flagIndex !== -1 && argv[flagIndex + 1]) {
+    return path.resolve(argv[flagIndex + 1]);
+  }
+
+  return walkUp(cwd) ?? path.resolve(cwd);
+}