@geraldmaron/construct 1.1.1 → 1.2.1

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] [--dry-run] [--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)
@@ -56,6 +59,9 @@ Flags:
   --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
@@ -307,14 +313,35 @@ 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 }) {
+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');
   }
@@ -326,6 +353,7 @@ function printInstallPlan({ scope, homeDir, withDocling, noLaunchAgent }) {
   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)');
@@ -341,13 +369,14 @@ 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', '--dry-run', '--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) => {
@@ -369,13 +398,25 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
   }
   const scope = scopeResult.scope;
 
-  if (scope === 'project') {
-    printProjectScopeGuidance();
+  if (dryRun) {
+    if (scope === 'project' && !cleanupLegacyGlobal) {
+      printProjectScopeGuidance();
+      return;
+    }
+    printInstallPlan({ scope, homeDir, withDocling, noLaunchAgent: argSet.has('--no-launch-agent'), cleanupLegacyGlobal });
     return;
   }
 
-  if (dryRun) {
-    printInstallPlan({ scope, homeDir, withDocling, noLaunchAgent: argSet.has('--no-launch-agent') });
+  if (cleanupLegacyGlobal) {
+    runLegacyGlobalCleanup({ homeDir, dryRun: false });
+    if (scope === 'project') {
+      printProjectScopeGuidance();
+      return;
+    }
+  }
+
+  if (scope === 'project') {
+    printProjectScopeGuidance();
     return;
   }
 
@@ -415,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/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 [];