@geraldmaron/construct 1.1.1 → 1.2.0

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/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.

package/lib/templates/visual-requirements.mjs

@@ -1,66 +1,47 @@
 /**
- * lib/templates/visual-requirements.mjs — required visuals per document type.
+ * lib/templates/visual-requirements.mjs — required visuals and structure per document type.
  *
- * The machine-readable form of docs/concepts/doc-visual-matrix.md: which doc
- * types must carry which visual (a diagram of a given kind, or a table with given
- * columns), expressed as postcondition checks so the existing validate.mjs engine
- * enforces them. The shipped template for each listed type must satisfy its own
- * requirements — pinned by tests/template-visuals.test.mjs — so the templates can
- * never drift out of step with the matrix (beads wvbf.10 / wvbf.11).
+ * Loads structure and visual requirements from specialists/artifact-manifest.json
+ * (single source of truth) and merges legacy types not yet in the manifest.
+ * Paired with docs/concepts/doc-visual-matrix.md; pinned by template tests.
  */
 
 import { validateArtifactPostconditions } from '../contracts/validate.mjs';
+import {
+  structureRequirementsFromManifest,
+  visualRequirementsFromManifest,
+  getArtifactEntry,
+} from '../artifact-manifest.mjs';
+
+const LEGACY_STRUCTURE = {
+  'persona-artifact': ['Goals', 'Frustrations', 'Decision rights', 'Output contract', 'Failure modes', 'Evidence'],
+  'skill-artifact': ['What this skill produces', 'When to invoke it', 'Competency rubric', 'Failure modes', 'Worked example'],
+  'research-finding': ['SOURCES', 'FINDINGS', 'INFERENCES', 'CONFIDENCE', 'GAPS', 'RECOMMENDATION'],
+};
+
+export const STRUCTURE_REQUIREMENTS = {
+  ...structureRequirementsFromManifest(),
+  ...LEGACY_STRUCTURE,
+};
 
 export const VISUAL_REQUIREMENTS = {
-  runbook: [
-    { id: 'runbook-diagnostic-flowchart', check: 'artifact-has-mermaid', diagram: 'flowchart' },
-  ],
-  'incident-report': [
-    { id: 'incident-timeline-table', check: 'artifact-table-has-columns', columns: ['Time (UTC)', 'Event'] },
-  ],
-  rfc: [
-    { id: 'rfc-sequence-diagram', check: 'artifact-has-mermaid', diagram: 'sequenceDiagram' },
-  ],
+  ...visualRequirementsFromManifest(),
 };
 
 export function visualRequirementTypes() {
   return Object.keys(VISUAL_REQUIREMENTS);
 }
 
-// The structural floor of the quality rubric (ADR-0018): the sections a domain
-// expert expects for each doc type. Each shipped template must satisfy its own
-// entry — pinned by tests/structure-requirements.test.mjs — so a template can
-// never quietly drop a required section. Section requirements compose with the
-// VISUAL_REQUIREMENTS above; lintDocStructure runs both.
-
-export const STRUCTURE_REQUIREMENTS = {
-  adr: ['Problem', 'Decision', 'Rejected alternatives', 'Consequences', 'Reversibility'],
-  rfc: ['Summary', 'Motivation', 'Proposed design', 'Risks', 'Verification'],
-  prd: ['Problem', 'Goals', 'Success metrics', 'Risks and mitigations'],
-  'research-brief': ['Sources', 'Findings', 'Confidence summary', 'Recommendation'],
-  'incident-report': ['Summary', 'Severity rationale', 'Impact', 'Timeline', 'Trigger', 'Root cause', 'Contributing factors', 'Action items'],
-  runbook: ['Alert trigger', 'Symptoms', 'Impact', 'Severity and response', 'Diagnostic steps', 'Remediation', 'Rollback', 'Escalation'],
-  strategy: ['Vision', 'Bets', 'Non-bets', 'North Star Metric', 'Metrics', 'Milestones', 'Risks'],
-  'signal-brief': ['Signal', 'Evidence', 'Counter-signal', 'What would make this actionable'],
-  prfaq: ['Problem statement', 'Press release', 'External FAQ', 'Internal FAQ', 'Evidence appendix'],
-  'customer-profile': ['Snapshot', 'Active pain points', 'Open asks', 'Evidence links'],
-  'one-pager': ['Problem', 'Proposal', 'Why now', 'Success measure', 'Cost', 'Asks'],
-  'product-intelligence-report': ['Executive readout', 'Evidence base', 'Themes', 'Customer asks', 'Product implications', 'Recommended actions', 'Gaps and risks'],
-  'backlog-proposal': ['Source evidence', 'Proposed changes', 'Duplicate and conflict check', 'Approval request'],
-  'persona-artifact': ['Goals', 'Frustrations', 'Decision rights', 'Output contract', 'Failure modes', 'Evidence'],
-  'skill-artifact': ['What this skill produces', 'When to invoke it', 'Competency rubric', 'Failure modes', 'Worked example'],
-  'research-finding': ['SOURCES', 'FINDINGS', 'INFERENCES', 'CONFIDENCE', 'GAPS', 'RECOMMENDATION'],
-};
-
 export function structureRequirementTypes() {
   return [...new Set([...Object.keys(STRUCTURE_REQUIREMENTS), ...Object.keys(VISUAL_REQUIREMENTS)])];
 }
 
-/**
- * Lint one document against both the required sections and required visuals for
- * its type. Returns an array of violation strings (empty when satisfied or when
- * the type declares no requirements).
- */
+export function resolveTemplatePath(type, rootDir) {
+  const entry = getArtifactEntry(type, { rootDir });
+  if (entry?.template) return entry.template;
+  return `templates/docs/${type}.md`;
+}
+
 export function lintDocStructure(filePath, type) {
   const sectionChecks = (STRUCTURE_REQUIREMENTS[type] || []).map((section) => ({
     id: `${type}-section-${section}`,
@@ -72,11 +53,6 @@ export function lintDocStructure(filePath, type) {
   return validateArtifactPostconditions({ contract: { postconditions }, artifactPath: filePath });
 }
 
-/**
- * Lint one document against the visual requirements for its type. Returns an
- * array of violation strings (empty when satisfied, or when the type has no
- * declared visual requirements).
- */
 export function lintDocVisuals(filePath, type) {
   const postconditions = VISUAL_REQUIREMENTS[type];
   if (!postconditions) return [];