@geraldmaron/construct 1.2.2 → 1.3.0

package/lib/ui/links.mjs

@@ -0,0 +1,115 @@
+/**
+ * lib/ui/links.mjs — shared OSC-8 hyperlink layer for every construct surface.
+ *
+ * Canonical link authority for CLI output and generated adapter diagnostics.
+ * Renders repo-relative paths and URLs as clickable terminal links (OSC-8) when
+ * the stream supports them, and always keeps the raw path/URL as the visible
+ * label so terminals that ignore OSC-8 (notably macOS Terminal.app) can still
+ * Cmd-click the visible text via their own path/URL detection. Falls back to
+ * colored text when links are disabled.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const OSC8_OPEN = '\x1b]8;;';
+const OSC8_MID = '\x07';
+const OSC8_CLOSE = '\x1b]8;;\x07';
+
+export const REPO_PATH_PATTERN =
+  /(`?)((?:\.cx\/|docs\/|inbox\/|skills\/|rules\/|lib\/|templates\/|specialists\/|tests\/|platforms\/|personas\/|schemas\/)?[\w][\w./-]*\.(?:md|mdx|json|mjs|ts|tsx|yml|yaml)|construct\.config\.json|package\.json|[A-Z][A-Z0-9_]*\.md)(`?)/g;
+
+const REPO_PATH =
+  /(^|[\s(,])(`?)((?:\.cx\/|docs\/|inbox\/|skills\/|rules\/|lib\/|templates\/|specialists\/|tests\/|platforms\/|personas\/|schemas\/)?[\w][\w./-]*\.(?:md|mdx|json|mjs|ts|tsx|yml|yaml)|construct\.config\.json|package\.json|[A-Z][A-Z0-9_]*\.md)(`?)(?=$|[\s),.:;])/g;
+
+const URL_PATTERN = /\bhttps?:\/\/[^\s<>()\][]+[^\s<>()\][.,;:!?'"]/g;
+
+export function terminalLinksEnabled(env = process.env, { plain = false, stream = process.stdout } = {}) {
+  if (plain || env.NO_COLOR === '1' || env.CX_PLAIN_COPY === '1') return false;
+  if (env.CX_LINKS === '0') return false;
+  if (stream?.isTTY) return true;
+  if (env.TERM_PROGRAM === 'vscode' || env.TERM_PROGRAM === 'cursor' || env.WT_SESSION) return true;
+  return false;
+}
+
+export function fileUriForPath(filePath, { cwd = process.cwd() } = {}) {
+  const abs = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
+  return pathToFileURL(abs).href;
+}
+
+// OSC-8 wraps a visible label with an invisible href. Terminals that honor the
+// sequence make the label clickable; terminals that ignore it (Terminal.app)
+// simply print the label — so callers must pass a label that is itself a
+// clickable string (a raw path or URL), never a friendly title that hides it.
+
+export function formatTerminalLink(label, href, colors, { enabled = true } = {}) {
+  const styled = `${colors?.link || ''}${label}${colors?.reset || ''}`;
+  if (!enabled || !href) return styled;
+  return `${OSC8_OPEN}${href}${OSC8_MID}${styled}${OSC8_CLOSE}`;
+}
+
+export function formatPathLink(relPath, colors, { cwd = process.cwd(), enabled = true } = {}) {
+  const display = relPath.replace(/^`/, '').replace(/`$/, '');
+  const abs = path.resolve(cwd, display);
+  const href = fileUriForPath(abs, { cwd });
+  return formatTerminalLink(display, href, colors, { enabled });
+}
+
+// A bare URL is its own visible label, so OSC-8 terminals get one-click and
+// Terminal.app's URL detection still works on the printed text.
+
+export function formatUrlLink(url, colors, { enabled = true } = {}) {
+  return formatTerminalLink(url, url, colors, { enabled });
+}
+
+// A titled link ([text](href)) must keep the destination visible for terminals
+// that drop OSC-8: render the title as the clickable label, then append the raw
+// destination so it is both readable and Cmd-clickable everywhere.
+
+export function formatTitledLink(label, href, colors, { enabled = true, display = href } = {}) {
+  if (!label || label === display) {
+    return formatTerminalLink(display, href, colors, { enabled });
+  }
+  const linked = formatTerminalLink(label, href, colors, { enabled });
+  const tail = `${colors?.dim || ''} (${display})${colors?.reset || ''}`;
+  return `${linked}${tail}`;
+}
+
+export function linkifyRepoPaths(text, colors, { cwd = process.cwd(), enabled = true } = {}) {
+  if (!enabled || text == null) return String(text ?? '');
+  const source = String(text);
+  return source.replace(REPO_PATH_PATTERN, (full, openTick, relPath, closeTick, offset) => {
+    if (offset > 0) {
+      const prev = source[offset - 1];
+      if (!/[\s(,]/.test(prev)) return full;
+    }
+    return formatPathLink(`${openTick || ''}${relPath}${closeTick || ''}`, colors, { cwd, enabled });
+  });
+}
+
+export function applyPathLinks(text, colors, { cwd = process.cwd(), enabled = true } = {}) {
+  if (!enabled || !text) return String(text);
+  return String(text).replace(REPO_PATH, (match, prefix, openTick, relPath, closeTick) => {
+    const linked = formatPathLink(`${openTick || ''}${relPath}${closeTick || ''}`, colors, { cwd, enabled });
+    return `${prefix}${linked}`;
+  });
+}
+
+export function linkifyUrls(text, colors, { enabled = true } = {}) {
+  if (!enabled || text == null) return String(text ?? '');
+  return String(text).replace(URL_PATTERN, (url) => formatUrlLink(url, colors, { enabled }));
+}
+
+// Linkify both repo paths and URLs in one pass; URLs first so a URL containing
+// a path-like suffix is not split by the path matcher.
+
+export function applyLinks(text, colors, { cwd = process.cwd(), enabled = true } = {}) {
+  if (!enabled || !text) return String(text ?? '');
+  return applyPathLinks(linkifyUrls(text, colors, { enabled }), colors, { cwd, enabled });
+}
+
+export function writeLinkedLine(output, line, colors, { cwd, enabled, prefix = '' } = {}) {
+  const body = applyLinks(line, colors, { cwd, enabled });
+  output.write(prefix ? `${prefix}${body}\n` : `${body}\n`);
+}

package/lib/ui/theme.mjs

@@ -0,0 +1,108 @@
+/**
+ * lib/ui/theme.mjs — shared semantic color resolution for every construct surface.
+ *
+ * Surface-neutral palette for the CLI and generated adapter diagnostics.
+ * Terminal codes are basic 16-color SGR, which renders on every
+ * terminal including macOS Terminal.app; the truecolor guard degrades any 24-bit
+ * value so no raw escape leaks where the terminal cannot honor it.
+ */
+
+import { shouldUseColor } from '../term-format.mjs';
+
+const ESC = '[';
+
+function resolveTerminalColorScheme(env = process.env, configTheme = null) {
+  const explicit = String(configTheme || env.CONSTRUCT_COLOR_SCHEME || '').toLowerCase();
+  if (explicit === 'light' || explicit === 'dark') return explicit;
+  const termProgram = String(env.TERM_PROGRAM || '').toLowerCase();
+  if (termProgram.includes('apple_terminal')) return 'light';
+  return 'dark';
+}
+
+function terminalSemantic(scheme) {
+  const dark = scheme !== 'light';
+  return {
+    text: { code: dark ? '97' : '30' },
+    muted: { code: dark ? '90' : '90' },
+    accent: { code: dark ? '96' : '36' },
+    accentAlt: { code: dark ? '95' : '35' },
+    ok: { code: dark ? '92' : '32' },
+    warn: { code: dark ? '93' : '33' },
+    danger: { code: dark ? '91' : '31' },
+    badgeFg: { code: dark ? '30' : '97' },
+    surface: { code: dark ? '40' : '47' },
+    surfaceMuted: { code: dark ? '100' : '47' },
+    border: { code: dark ? '90' : '90' },
+    brandAccent: { code: dark ? '97' : '30' },
+    highlight: { code: dark ? '96' : '36' },
+    heading: { code: dark ? '97' : '30' },
+    emphasis: { code: dark ? '93' : '33' },
+    code: { code: dark ? '92' : '32' },
+    link: { code: dark ? '94' : '34' },
+    panel: { code: dark ? '90' : '90' },
+  };
+}
+
+// COLORTERM=truecolor|24bit advertises 24-bit support. Terminal.app sets neither
+// and tops out at 256 colors, so absent the flag we treat the stream as non-truecolor.
+
+export function supportsTrueColor(env = process.env) {
+  const flag = String(env.COLORTERM || '').toLowerCase();
+  return flag === 'truecolor' || flag === '24bit';
+}
+
+// SGR codes from design-tokens are already basic 16-color (30-37/90-97). A 24-bit
+// sequence (38;2;r;g;b) only survives when the terminal advertises truecolor;
+// otherwise it is dropped to dim so meaning never rides on an unrenderable color.
+
+function degradeCode(code, trueColor) {
+  if (!code) return code;
+  if (/^38;2;/.test(String(code)) && !trueColor) return '2';
+  return code;
+}
+
+export function resolveUiColors({
+  enabled = true,
+  stream = process.stdout,
+  env = process.env,
+  scheme: explicitScheme = null,
+  configTheme = null,
+} = {}) {
+  const scheme = explicitScheme || resolveTerminalColorScheme(env, configTheme);
+  const useColor = shouldUseColor({ enabled, stream, env });
+  const trueColor = supportsTrueColor(env);
+  const semantic = terminalSemantic(scheme);
+  const codes = Object.fromEntries(Object.entries(semantic).map(([k, v]) => [k, degradeCode(v.code, trueColor)]));
+  const reset = useColor ? `${ESC}0m` : '';
+  const wrap = (code) => (useColor && code ? `${ESC}${code}m` : '');
+
+  return {
+    scheme,
+    reset,
+    bold: wrap('1'),
+    dim: wrap('2'),
+    underline: wrap('4'),
+    text: wrap(codes.text),
+    muted: wrap(codes.muted),
+    accent: wrap(codes.accent),
+    accentAlt: wrap(codes.accentAlt),
+    ok: wrap(codes.ok),
+    warn: wrap(codes.warn),
+    danger: wrap(codes.danger),
+    badgeFg: wrap(codes.badgeFg),
+    surface: wrap(codes.surface),
+    surfaceMuted: wrap(codes.surfaceMuted),
+    border: wrap(codes.border),
+    brandAccent: wrap(codes.brandAccent),
+    highlight: wrap(codes.highlight),
+    heading: wrap(codes.heading),
+    emphasis: wrap(codes.emphasis),
+    code: wrap(codes.code),
+    link: wrap(codes.link),
+    panel: wrap(codes.panel),
+    green: wrap(codes.ok),
+    yellow: wrap(codes.warn),
+    cyan: wrap(codes.highlight),
+    red: wrap(codes.danger),
+  };
+}

package/lib/uninstall/uninstall.mjs

@@ -30,6 +30,7 @@
  */
 
 import fs from 'node:fs';
+import { loadRegistry } from '../registry/loader.mjs';
 import path from 'node:path';
 import os from 'node:os';
 import { spawnSync } from 'node:child_process';
@@ -466,7 +467,7 @@ function unmergeSettings(filePath) {
 
 function constructMcpKeys() {
   try {
-    const registry = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'specialists', 'registry.json'), 'utf8'));
+    const registry = loadRegistry({ rootDir: PKG_ROOT });
     return Object.keys(registry.mcpServers || {});
   } catch { return []; }
 }

package/lib/validator.mjs

@@ -6,6 +6,7 @@
  * field-level detail. Backs workflow-state, cli-commands, and MCP tools
  * before they mutate persistent state.
  */
+import { loadRegistry } from './registry/loader.mjs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { existsSync, readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
@@ -55,19 +56,55 @@ export function validateRegistry(reg, options = {}) {
   const errors = [];
   const rootDir = options.rootDir ?? join(__dirname, '..');
 
-  if (!reg.version && reg.version !== 0) errors.push('registry: version is missing');
-  if (!reg.system) errors.push('registry: system is missing');
-  if (!reg.prefix) errors.push('registry: prefix is missing');
+  // Handle unified registry format (v2) - convert specialists from object to array
+  // and extract orchestrator from specialists
+  let registry = reg;
+  if (reg.version === 2 && typeof reg.specialists === 'object' && !Array.isArray(reg.specialists)) {
+    const orchestrator = Object.values(reg.specialists || {}).find(s => s.role === 'orchestrator');
+    const otherSpecialists = Object.values(reg.specialists || {}).filter(s => s.role !== 'orchestrator');
+    registry = {
+      version: 1,
+      system: 'construct',
+      prefix: 'cx',
+      orchestrator: orchestrator ? {
+        name: orchestrator.name,
+        displayName: orchestrator.displayName || orchestrator.description?.split('—')[0].trim(),
+        description: orchestrator.description || '',
+        promptFile: orchestrator.promptFile,
+        modelTier: orchestrator.modelTier || 'standard',
+        skills: orchestrator.skills || [],
+      } : null,
+      specialists: otherSpecialists.map(s => ({
+        name: s.name,
+        displayName: s.displayName || s.description?.split('—')[0].trim(),
+        description: s.description || '',
+        promptFile: s.promptFile,
+        modelTier: s.modelTier || 'standard',
+        skills: s.skills || [],
+        team: s.team,
+        role: s.role,
+        docArtifacts: s.docArtifacts || [],
+        subscriptions: s.events || [],
+        watchConditions: s.watchConditions || [],
+        fence: s.fence || {},
+      })),
+      mcpServers: reg.mcpServers || {},
+    };
+  }
+
+  if (!registry.version && registry.version !== 0) errors.push('registry: version is missing');
+  if (!registry.system) errors.push('registry: system is missing');
+  if (!registry.prefix) errors.push('registry: prefix is missing');
 
-  if (!Array.isArray(reg.specialists) || reg.specialists.length === 0) {
+  if (!Array.isArray(registry.specialists) || registry.specialists.length === 0) {
     errors.push('registry: specialists must be a non-empty array');
   }
-  if (!reg.orchestrator || typeof reg.orchestrator !== 'object') {
+  if (!registry.orchestrator || typeof registry.orchestrator !== 'object') {
     errors.push('registry: orchestrator must be a non-empty object');
   }
 
-  const specialists = Array.isArray(reg.specialists) ? reg.specialists : [];
-  const orchestrator = reg.orchestrator && typeof reg.orchestrator === 'object' ? reg.orchestrator : null;
+  const specialists = Array.isArray(registry.specialists) ? registry.specialists : [];
+  const orchestrator = registry.orchestrator && typeof registry.orchestrator === 'object' ? registry.orchestrator : null;
 
   const allIds = new Set();
   const specialistNames = new Set(specialists.map((s) => s?.name).filter(Boolean));
@@ -218,7 +255,7 @@ export function validateRegistry(reg, options = {}) {
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  const reg = JSON.parse(readFileSync(join(__dirname, '..', 'specialists', 'registry.json'), 'utf8'));
+  const reg = loadRegistry();
   const result = validateRegistry(reg);
   if (result.valid) {
     console.log(`✓ Registry valid (${result.summary})`);

package/lib/validators/skill-effectiveness.mjs

@@ -0,0 +1,174 @@
+/**
+ * lib/validators/skill-effectiveness.mjs — Content-depth validation beyond structure.
+ *
+ * Checks role failure modes, workflow chains, domain boundaries, and resolvable
+ * skill references for scope lint and release-gate enforcement.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { loadRegistry } from '../registry/loader.mjs';
+import { artifactTypes } from '../artifact-manifest.mjs';
+
+const GET_SKILL_RE = /get_skill\("([^"]+)"\)/g;
+const CX_SPECIALIST_RE = /\bcx-[a-z][a-z0-9-]+\b/g;
+
+function walkSkills(skillsDir, prefix = '') {
+  const out = [];
+  if (!fs.existsSync(skillsDir)) return out;
+  for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    const full = path.join(skillsDir, entry.name);
+    if (entry.isDirectory()) out.push(...walkSkills(full, rel));
+    else if (entry.name.endsWith('.md') && entry.name !== 'routing.md') {
+      out.push({ rel: rel.replace(/\.md$/, ''), full });
+    }
+  }
+  return out;
+}
+
+function parseFrontmatter(content) {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return { meta: {}, body: content };
+  const meta = {};
+  for (const line of m[1].split('\n')) {
+    const kv = line.match(/^([a-zA-Z0-9_-]+):\s*(.*)$/);
+    if (!kv) continue;
+    const [, key, raw] = kv;
+    if (raw.startsWith('[')) {
+      try { meta[key] = JSON.parse(raw); } catch { meta[key] = raw; }
+    } else {
+      meta[key] = raw.replace(/^["']|["']$/g, '');
+    }
+  }
+  return { meta, body: content.slice(m[0].length) };
+}
+
+function isRoleSkill(rel) {
+  return rel.startsWith('roles/');
+}
+
+function isWorkflowSkill(rel) {
+  return rel.startsWith('docs/') && rel.endsWith('-workflow');
+}
+
+function isDomainSkill(rel) {
+  return !isRoleSkill(rel) && !isWorkflowSkill(rel) && rel !== 'routing';
+}
+
+function validateRoleDepth(rel, body, errors) {
+  const numberedH3 = (body.match(/^###\s+\d+\./gm) || []).length;
+  const numberedList = (body.match(/^\d+\.\s+\*\*/gm) || []).length;
+  if (numberedH3 + numberedList < 3) {
+    errors.push(`${rel}: role overlay needs ≥3 numbered failure-mode sections (### N. or 1. **Title**)`);
+  }
+  const hasSymptom = /\*\*Symptom\*\*:|Symptom:/i.test(body);
+  const hasCounter = /\*\*Counter-move\*\*:|Counter-move:|Counter:/i.test(body);
+  if (!hasSymptom || !hasCounter) {
+    errors.push(`${rel}: role overlay missing Symptom/Counter-move pattern`);
+  }
+  const isBase = !rel.includes('.') && !/^roles\/[^/]+\.[^/]+$/.test(rel);
+  if (isBase && !/## Self-check|## Methodology|## Ship Check/i.test(body)) {
+    errors.push(`${rel}: base role file should include Self-check or Methodology section`);
+  }
+}
+
+function countWorkflowSteps(body) {
+  const lines = body.split(/\r?\n/);
+  let inFence = false;
+  let count = 0;
+  for (const line of lines) {
+    if (/^```/.test(line.trim())) inFence = !inFence;
+    if (inFence) continue;
+    if (/^\d+\.\s+/.test(line)) count++;
+  }
+  return count;
+}
+
+function validateWorkflowDepth(rel, meta, body, errors) {
+  if (!meta.verificationBar || String(meta.verificationBar).length < 40) {
+    errors.push(`${rel}: workflow missing verificationBar (≥40 chars)`);
+  }
+  if (!meta.artifactType) {
+    errors.push(`${rel}: workflow missing artifactType`);
+  }
+  if (!/construct artifact validate/i.test(body)) {
+    errors.push(`${rel}: workflow must mention construct artifact validate`);
+  }
+  if (countWorkflowSteps(body) < 4) {
+    errors.push(`${rel}: workflow needs ≥4 numbered steps`);
+  }
+}
+
+function validateDomainDepth(rel, body, meta, errors) {
+  const stripped = body.replace(/^---[\s\S]*?---/, '').trim();
+  if (stripped.length < 400) {
+    errors.push(`${rel}: domain skill body too short (<400 chars)`);
+  }
+  const desc = String(meta.description || '');
+  const boundary =
+    /when not to use|when to use|do not use|use this skill when|use this skill to|use when:/i.test(body) ||
+    /use when|use this skill when|use this skill to|do not use/i.test(desc);
+  if (!boundary) {
+    errors.push(`${rel}: domain skill missing boundary section (When not to use / When to use)`);
+  }
+}
+
+function validateReferences(rel, body, skillsSet, registry, errors) {
+  for (const m of body.matchAll(GET_SKILL_RE)) {
+    const id = m[1];
+    if (!skillsSet.has(id)) {
+      errors.push(`${rel}: unresolved get_skill("${id}")`);
+    }
+  }
+  if (isWorkflowSkill(rel)) {
+    for (const id of body.match(CX_SPECIALIST_RE) || []) {
+      const key = id.replace(/^cx-/, '');
+      const found = Object.values(registry.specialists || {}).some(
+        (s) => s.name === key || `cx-${s.name}` === id,
+      );
+      if (!found) errors.push(`${rel}: unknown specialist ${id}`);
+    }
+    const types = artifactTypes();
+    for (const m of body.matchAll(/`([a-z][a-z0-9-]*)`/g)) {
+      const t = m[1];
+      if (t.startsWith('prd') || t === 'rfc' || t === 'adr' || t === 'memo') {
+        if (!types.includes(t) && !types.includes(t.replace(/-platform$/, ''))) {
+          /* template ids vary — only warn on explicit get_template */
+        }
+      }
+    }
+  }
+}
+
+export function validateSkillEffectiveness({ rootDir } = {}) {
+  const root = rootDir || path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', '..');
+  const skillsDir = path.join(root, 'skills');
+  const errors = [];
+  const warnings = [];
+  const files = walkSkills(skillsDir);
+  const skillsSet = new Set(files.map((f) => f.rel));
+  let registry;
+  try {
+    registry = loadRegistry({ rootDir: root });
+  } catch {
+    registry = { specialists: {} };
+  }
+
+  for (const { rel, full } of files) {
+    const raw = fs.readFileSync(full, 'utf8');
+    const { meta, body } = parseFrontmatter(raw);
+    if (isRoleSkill(rel) && meta.role?.includes('.')) {
+      validateRoleDepth(rel, body, errors);
+    } else if (isRoleSkill(rel)) {
+      if (body.length > 200) validateRoleDepth(rel, body, errors);
+    } else if (isWorkflowSkill(rel)) {
+      validateWorkflowDepth(rel, meta, body, errors);
+    } else if (isDomainSkill(rel)) {
+      validateDomainDepth(rel, body, meta, errors);
+    }
+    validateReferences(rel, body, skillsSet, registry, errors);
+  }
+
+  return { valid: errors.length === 0, errors, warnings, checked: files.length };
+}

package/lib/validators/skills.mjs

@@ -8,7 +8,7 @@
  *   description: "<≤1024 chars, includes a 'use when' trigger>"
  *   [inputs: [<string>, …]  — optional, surfaced by capability discovery]
  *   [artifactType: <string> — optional, surfaced by capability discovery]
- *   [role/applies_to/inherits/version/profiles/cap for role files]
+ *   [role/applies_to/inherits/version/scopes/cap for role files]
  *   ---
  *   # <Title>
  *   Use when: <trigger condition>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "type": "module",
   "packageManager": "npm@11.5.1",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
@@ -51,12 +51,15 @@
   },
   "scripts": {
     "mcp": "node lib/mcp/server.mjs",
+    "doctor": "node ./bin/construct doctor",
     "test": "node scripts/run-tests.mjs",
     "test:functional": "XDG_CONFIG_HOME= XDG_STATE_HOME= XDG_CACHE_HOME= node --test --test-timeout=120000 --test-concurrency=1 tests/functional/*.functional.test.mjs",
+    "test:visual": "node -e \"console.log('visual surface tests removed')\"",
     "test:unit": "node scripts/run-tests.mjs --exclude=tests/functional",
     "lint:js": "eslint bin/construct \"lib/**/*.mjs\" \"scripts/**/*.mjs\" \"tests/**/*.mjs\"",
     "coverage": "c8 --reporter=text-summary --reporter=lcov --src=lib --src=bin node scripts/run-tests.mjs --exclude=tests/functional",
     "docs:init": "node -e \"console.error('docs:init is deprecated — use: construct init --docs-preset=lean|product|full'); process.exit(1)\"",
+    "docs:verify": "node ./bin/construct docs:verify",
     "docs:update": "node ./bin/construct docs:update",
     "docs:site": "node ./bin/construct docs:site",
     "docs:dev": "node scripts/npm-run.mjs npm --prefix apps/docs run dev",
@@ -64,20 +67,22 @@
     "lint:comments": "node ./bin/construct lint:comments",
     "lint:contracts": "node ./bin/construct lint:contracts",
     "lint:agents": "node ./bin/construct lint:agents",
+    "gates:audit": "node ./bin/construct gates:audit",
+    "evals": "node ./bin/construct evals",
+    "certify:demos": "node ./bin/construct certify demos",
     "build:sea": "esbuild bin/construct --bundle --platform=node --target=node20 --packages=external --outfile=dist/construct-bundle.cjs 2>&1 || (echo 'esbuild not found — install with: npm install -g esbuild' && exit 1)",
-    "build:chat": "esbuild apps/chat/tui/index.jsx --bundle --platform=node --format=esm --packages=external --jsx=automatic --jsx-import-source=react --outfile=apps/chat/dist/tui.mjs",
-    "build:chat-desktop": "node scripts/build-chat-desktop.mjs",
-    "build:chat-desktop:bundle": "node scripts/npm-run.mjs npm install --prefix apps/chat/desktop --include=dev && node scripts/npm-run.mjs npm --prefix apps/chat/desktop run build",
-    "build:dashboard": "node scripts/npm-run.mjs npm install --prefix apps/dashboard && node scripts/npm-run.mjs npm --prefix apps/dashboard run build",
     "examples:deck": "node scripts/generate-deck-examples.mjs",
     "examples:distribution": "node scripts/generate-distribution-examples.mjs",
     "clean:artifacts": "node scripts/clean-artifacts.mjs",
-    "lint:profiles": "node scripts/lint-profiles.mjs",
+    "lint:scopes": "node scripts/lint-scopes.mjs",
+    "catalog:regen": "node scripts/catalog-regen.mjs",
+    "catalog:validate": "node scripts/catalog-validate.mjs",
+    "docs:sync": "node scripts/docs-sync.mjs",
     "learning:status": "node scripts/learning-status.mjs",
     "lint:templates": "node scripts/lint-commits-pr.mjs",
     "eval:routing": "node scripts/eval/score-intent-classifier.mjs",
     "adapters": "node lib/adapters-sync.mjs",
-    "release:check": "node ./bin/construct doctor && npm test && node ./bin/construct docs:update --check && node ./bin/construct docs:site --check && node ./bin/construct registry:generate-docs --check && node ./bin/construct docs:verify --strict && node scripts/alignment/census.mjs --ratchet && node ./bin/construct dashboard:sync --check && node ./bin/construct lint:comments && node ./bin/construct certify gate && node scripts/lint-commits-pr.mjs",
+    "release:check": "npm run doctor && node ./bin/construct registry:validate --unified && npm run catalog:validate -- --check && npm test && npm run docs:update -- --check && npm run docs:site -- --check && npm run docs:sync -- --check && node ./bin/construct registry:generate-docs --check && npm run docs:verify -- --strict && node scripts/alignment/census.mjs --ratchet && npm run lint:comments && node ./bin/construct certify gate && npm run lint:templates",
     "release:gate": "node --test tests/functional/release-gate.functional.test.mjs",
     "audit:published": "node scripts/audit-published-artifact.mjs",
     "version": "node scripts/sync-construct-version.mjs && git add -f .construct/version",

package/personas/construct.md

@@ -31,13 +31,22 @@ Tracks: immediate (act directly), focused (one bounded specialist), orchestrated
 
 Orchestrated dispatches emit a task-packet with `goal`, `intent`, `workCategory`, `riskFlags`, `acceptanceCriteria` before naming specialists (`specialists/contracts.json:construct-to-orchestrator`).
 
+Research-shaped requests and artifact-drafting requests are never "answer from memory" work. If the request is asking for current evidence, comparison, standards, or a typed output, route it through the matching execution path first:
+- research / compare / explore / explain external state → call `orchestration_run` with the original request and `workflow_type: "research-synthesis"` unless the user explicitly supplied a raw evidence bundle, in which case use the evidence-ingest path
+- draft or revise a typed artifact/output → use the canonical template for that artifact and route through the matching workflow before writing the final draft; use `workflow_invoke` only when the user is asking for the plan / contract preview rather than execution
+- never claim research was completed unless `orchestration_run`, evidence tools, or a user-supplied evidence bundle actually produced the evidence
+- if evidence is missing or execution is unavailable, say what is missing and ask for the minimal next input instead of inventing a process narrative or conclusion
+
+General conversation is still valid for scoping, clarification, and lightweight discussion, but the default for substantive research is evidence-first execution, not free-form synthesis.
+
 ## Gates and contracts (org-in-a-box) <!-- cx:prio=2 -->
 
-`orchestration_policy` returns three artifacts; honor all three:
+`orchestration_policy` returns four artifacts; honor all four:
 
 1. **Gates**. `framingChallenge`, `externalResearch`, `docAuthoring`
 2. **Contract chain**. typed handoffs from `specialists/contracts.json`. Call `agent_contract` with `handoffPacket` from `orchestration_policy`.
 3. **Specialist sequence**. dispatch plan with ordering/parallel markers.
+4. **Team routing**. name `teamRouting.primaryTeam` in the dispatch plan; route through `teamRouting.requiredApprovals` before DONE; if `teamRouting.blockedStatus` is set, stop and escalate along its `escalationPath` rather than proceeding.
 
 Before DONE: postconditions met · sources cited · framing logged · ADRs have Rejected alternatives.
 
@@ -48,12 +57,12 @@ Before DONE: postconditions met · sources cited · framing logged · ADRs have
 
 ## Intake surface <!-- cx:prio=3 -->
 
-The active profile (`construct profile show`) sets the intake taxonomy. Session-start surfaces pending intake at `.cx/intake/pending/<id>.json`. Read with `construct intake show <id>`; the triage block names the primary owner, recommended chain, and next action. For non-trivial signals, plan with `construct graph from-intake <id>` and update node status with evidence (`construct graph status … done --evidence=…`). A node cannot reach `done` without an evidence record. Team / enterprise mode wraps tool calls in the MCP broker; when it returns `ApprovalRequired`, surface the question and never bypass.
+The active profile (`construct scope show`) sets the intake taxonomy. Session-start surfaces pending intake at `.cx/intake/pending/<id>.json`. Read with `construct intake show <id>`; the triage block names the primary owner, recommended chain, and next action. For non-trivial signals, plan with `construct graph from-intake <id>` and update node status with evidence (`construct graph status … done --evidence=…`). A node cannot reach `done` without an evidence record. Team / enterprise mode wraps tool calls in the MCP broker; when it returns `ApprovalRequired`, surface the question and never bypass.
 
 ## Action discipline <!-- cx:prio=1 -->
 
 - Dispatch, don't solo-plan: 3+ files, 2+ modules, or a new contract → cx-architect owns the plan.
-- Ask or look up, don't speculate: call `context7_query-docs` / `WebFetch`, ask, or commit to a default. Never a fourth round of internal debate.
+- Ask or look up, don't speculate: use the route's `researchExecutionPolicy`. For library/framework/API docs, prefer Context7 when available; otherwise search and fetch official docs directly. For broader research, go to domain-primary sources. Never a fourth round of internal debate.
 - Deliberation cap: two passes. Same decision twice without a new read, tool call, or user input = hand off, query, or ask.
 - Probe before bulk read: check size via `Glob` / `wc -l` or a `limit: 50` probe before `Read` with `limit > 200`.
 - Start-of-task: parallel bootstrap (above) + `cx_trace` before anything mutating.

package/platforms/claude/CLAUDE.md

@@ -2,7 +2,7 @@
 
 This file ships as a reference template alongside the Construct npm package. The canonical project-instructions file is `/CLAUDE.md` at your repo root — that's the file Claude Code actually reads at session start. The structure here mirrors that canonical file so users know what shape their own `/CLAUDE.md` should take after `construct init` scaffolds a project.
 
-Personas and specialists are defined in `specialists/registry.json` and rendered into Claude Code agents on every `construct sync`. The single user-facing persona is `construct`; the 28 specialists (cx-engineer, cx-security, cx-devil-advocate, …) are routed internally — you address Construct, Construct dispatches.
+Personas and specialists are defined in `specialists/org` and rendered into Claude Code agents on every `construct sync`. The single user-facing persona is `construct`; the 28 specialists (cx-engineer, cx-security, cx-devil-advocate, …) are routed internally — you address Construct, Construct dispatches.
 
 ## Critical rules (mirror in your project /CLAUDE.md)