@geraldmaron/construct 1.1.0 → 1.2.0

package/lib/diagram-export.mjs

@@ -0,0 +1,192 @@
+/**
+ * lib/diagram-export.mjs — distribution diagram styling for publish exports.
+ *
+ * Publish path renders hand-drawn D2 (--sketch geometry) and Mermaid (handDrawn
+ * look, Caveat handwriting) in a monochrome ink palette — black/grey strokes,
+ * light surfaces, near-black text — for an Excalidraw-adjacent human aesthetic
+ * that stays consistent with the document brand. Color is reserved for explicit
+ * per-node emphasis in the source, not the default theme.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const ICON_DIR = path.join(REPO_ROOT, 'templates', 'distribution', 'icons');
+
+// Monochrome diagram palette, mirroring the ink ramp in construct-brand.typ so
+// embedded diagrams and surrounding body share one design language.
+
+const MONO = {
+  ink: '#0a0c10',
+  inkBody: '#23272e',
+  muted: '#565c66',
+  faint: '#9499a2',
+  hairline: '#e3e4e8',
+  hairlineStrong: '#cdd0d6',
+  surface: '#fafafa',
+  surfaceAlt: '#f3f4f6',
+  paper: '#ffffff',
+};
+
+export const DISTRIBUTION_D2_THEME = '0';
+export const DISTRIBUTION_D2_PAD = '16';
+export const DISTRIBUTION_D2_SCALE = '0.72';
+export const DISTRIBUTION_D2_SKETCH = '1';
+export const DISTRIBUTION_D2_FONT_SIZE = '14';
+export const DISTRIBUTION_MERMAID_MIME = 'image/png';
+export const DISTRIBUTION_MERMAID_WIDTH = '480';
+export const DISTRIBUTION_MERMAID_SCALE = '1';
+export const DISTRIBUTION_FIGURE_MAX_WIDTH = '58%';
+
+// Handwritten font for Mermaid labels so its hand-drawn look matches D2 sketch
+// mode. Caveat ships bundled (templates/distribution/fonts/handwritten) and is
+// installed for the headless Chrome that mmdc drives; the fallbacks stay in the
+// handwriting register so a missing face never drops to a serif.
+
+const MERMAID_FONT = 'Caveat, Comic Sans MS, cursive';
+
+const MERMAID_INIT = `%%{init: {
+  'theme': 'base',
+  'look': 'handDrawn',
+  'fontFamily': '${MERMAID_FONT}',
+  'themeVariables': {
+    'fontFamily': '${MERMAID_FONT}',
+    'fontSize': '19px',
+    'primaryColor': '${MONO.surfaceAlt}',
+    'primaryTextColor': '${MONO.ink}',
+    'primaryBorderColor': '${MONO.ink}',
+    'lineColor': '${MONO.muted}',
+    'secondaryColor': '${MONO.paper}',
+    'secondaryTextColor': '${MONO.ink}',
+    'secondaryBorderColor': '${MONO.ink}',
+    'tertiaryColor': '${MONO.surface}',
+    'tertiaryTextColor': '${MONO.ink}',
+    'tertiaryBorderColor': '${MONO.hairlineStrong}',
+    'clusterBkg': '${MONO.surface}',
+    'clusterBorder': '${MONO.hairlineStrong}',
+    'edgeLabelBackground': '${MONO.paper}',
+    'titleColor': '${MONO.ink}',
+    'noteBkgColor': '${MONO.surface}',
+    'noteTextColor': '${MONO.inkBody}',
+    'noteBorderColor': '${MONO.hairlineStrong}',
+    'actorBkg': '${MONO.surfaceAlt}',
+    'actorBorder': '${MONO.ink}',
+    'actorTextColor': '${MONO.ink}',
+    'actorLineColor': '${MONO.hairlineStrong}',
+    'signalColor': '${MONO.inkBody}',
+    'signalTextColor': '${MONO.inkBody}',
+    'labelBoxBkgColor': '${MONO.surface}',
+    'labelBoxBorderColor': '${MONO.hairlineStrong}',
+    'labelTextColor': '${MONO.ink}',
+    'loopTextColor': '${MONO.inkBody}',
+    'activationBkgColor': '${MONO.hairline}',
+    'activationBorderColor': '${MONO.muted}'
+  }
+}}%%`;
+
+const CHROME_CANDIDATES = [
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/usr/bin/google-chrome',
+  '/usr/bin/chromium',
+  '/usr/bin/chromium-browser',
+];
+
+export function resolvePuppeteerExecutable(env = process.env) {
+  if (env.PUPPETEER_EXECUTABLE_PATH) return env.PUPPETEER_EXECUTABLE_PATH;
+  for (const candidate of CHROME_CANDIDATES) {
+    try {
+      if (fs.existsSync(candidate)) return candidate;
+    } catch {
+      /* skip */
+    }
+  }
+  return null;
+}
+
+export function injectMermaidBrandTheme(code) {
+  const body = String(code || '').trim();
+  if (!body) return body;
+  if (/%%\{init:/.test(body)) return body;
+  return `${MERMAID_INIT}\n${body}\n`;
+}
+
+// `icon: @name` in a d2 block resolves to the bundled monochrome Lucide icon at
+// templates/distribution/icons/name.svg, keeping source markdown portable while
+// d2 (which runs in a temp dir) still receives an absolute path it can read.
+
+export function resolveIconTokens(code) {
+  return String(code || '').replace(
+    /icon:\s*@([a-z0-9-]+)/gi,
+    (match, name) => {
+      const file = path.join(ICON_DIR, `${name}.svg`);
+      return fs.existsSync(file) ? `icon: ${file}` : match;
+    },
+  );
+}
+
+export function injectD2DistributionDefaults(code) {
+  const body = resolveIconTokens(String(code || '').trim());
+  if (!body) return body;
+  if (/CONSTRUCT_D2_DEFAULTS/.test(body)) return body;
+  return `**: {
+  style.font-size: ${DISTRIBUTION_D2_FONT_SIZE}
+  style.font-color: "${MONO.ink}"
+  style.stroke: "${MONO.ink}"
+  style.fill: "${MONO.surfaceAlt}"
+}
+(** -> **)[*]: {
+  style.stroke: "${MONO.muted}"
+  style.font-color: "${MONO.inkBody}"
+}
+
+${body}
+`;
+}
+
+export function preprocessMarkdownDiagrams(content) {
+  let out = String(content);
+  out = out.replace(/```mermaid\n([\s\S]*?)```/g, (_match, inner) => `\`\`\`mermaid\n${injectMermaidBrandTheme(inner)}\`\`\``);
+  out = out.replace(/```d2\n([\s\S]*?)```/g, (_match, inner) => `\`\`\`d2\n${injectD2DistributionDefaults(inner)}\`\`\``);
+  return out;
+}
+
+export function countDiagramFences(content) {
+  const matches = String(content || '').match(/```(?:d2|mermaid)\n/g);
+  return matches ? matches.length : 0;
+}
+
+export function buildDistributionDiagramEnv(baseEnv = process.env) {
+  const env = {
+    ...baseEnv,
+    CONSTRUCT_D2_THEME: DISTRIBUTION_D2_THEME,
+    CONSTRUCT_D2_PAD: DISTRIBUTION_D2_PAD,
+    CONSTRUCT_D2_SCALE: DISTRIBUTION_D2_SCALE,
+    CONSTRUCT_D2_SKETCH: DISTRIBUTION_D2_SKETCH,
+    CONSTRUCT_MERMAID_THEME: 'construct',
+    CONSTRUCT_MERMAID_MIME: DISTRIBUTION_MERMAID_MIME,
+    CONSTRUCT_MERMAID_WIDTH: DISTRIBUTION_MERMAID_WIDTH,
+    CONSTRUCT_MERMAID_SCALE: DISTRIBUTION_MERMAID_SCALE,
+  };
+  const chrome = resolvePuppeteerExecutable(baseEnv);
+  if (chrome) env.PUPPETEER_EXECUTABLE_PATH = chrome;
+  return env;
+}
+
+export function distributionDiagramDefaults() {
+  return {
+    d2Theme: 'neutral',
+    d2ThemeId: DISTRIBUTION_D2_THEME,
+    d2Sketch: true,
+    d2Scale: Number(DISTRIBUTION_D2_SCALE),
+    d2FontSize: Number(DISTRIBUTION_D2_FONT_SIZE),
+    figureMaxWidth: DISTRIBUTION_FIGURE_MAX_WIDTH,
+    mermaidLook: 'handDrawn',
+    mermaidTheme: 'construct',
+    mermaidWidth: Number(DISTRIBUTION_MERMAID_WIDTH),
+    mermaidScale: Number(DISTRIBUTION_MERMAID_SCALE),
+    accent: MONO.ink,
+  };
+}

package/lib/diagram.mjs

@@ -0,0 +1,302 @@
+/**
+ * lib/diagram.mjs — `construct diagram` command, generates code-driven
+ * architecture/flow diagrams from a natural-language description and renders
+ * them to SVG/PNG via an external diagram binary, degrading to source-only
+ * output when no renderer is installed.
+ *
+ * Tool evaluation (2026-06), against: visual distinctiveness, reproducible
+ * from code, headless Node/CI SVG+PNG render, theming, license:
+ *   - D2 (terrastruct, MPL-2.0): single self-contained Go binary, clean neutral
+ *     theme plus `--sketch` hand-drawn mode (publish distribution path), headless
+ *     `d2 in.d2 out.svg|png`, deterministic from a text file. Chosen as PRIMARY.
+ *   - Graphviz `dot` (EPL-1.0): ubiquitous, almost always already present on
+ *     CI images and dev machines, headless `dot -Tsvg|-Tpng`. Chosen as
+ *     FALLBACK for reach when D2 is absent.
+ *   - Mermaid: renders natively in many viewers but headless image export
+ *     needs mermaid-cli, which pulls a headless-Chromium npm tree — disallowed
+ *     by ADR-0001 (zero-npm-core). Used only as the SOURCE we emit when no
+ *     binary is present, reusing lib/wireframe.mjs's Mermaid generators so the
+ *     description still yields a viewable diagram in GitHub/Notion/OpenCode.
+ *
+ * Degradation contract: when neither D2 nor dot is on PATH the command still
+ * succeeds (exit 0) by writing the diagram SOURCE (.d2 by default, or .mmd
+ * Mermaid for diagram kinds wireframe.mjs already models) plus an install
+ * hint. No bundled binaries, no npm dependencies; renderers are detected at
+ * runtime, mirroring lib/runtime/whisper-bootstrap.mjs.
+ *
+ * Output: .cx/diagrams/<slug>-<ts>.<ext>.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join, resolve, dirname } from 'node:path';
+
+import { generateWireframe } from './wireframe.mjs';
+
+const TYPES = ['architecture', 'flow', 'sequence', 'state', 'er', 'class'];
+const FORMATS = ['svg', 'png'];
+
+function slugify(text) {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60) || 'diagram';
+}
+
+function timestamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+}
+
+function which(bin) {
+  const result = spawnSync(process.platform === 'win32' ? 'where' : 'which', [bin], { encoding: 'utf8' });
+  if (result.status !== 0) return null;
+  return result.stdout.trim().split('\n')[0] || null;
+}
+
+// Renderer detection follows the optional-external-tool pattern: probe PATH,
+// return a structured descriptor, never throw. D2 is preferred for its
+// distinctive look; dot is the ubiquitous fallback.
+
+export function locateRenderer() {
+  const d2 = which('d2');
+  if (d2) return { engine: 'd2', binary: d2, sourceExt: 'd2' };
+  const dot = which('dot');
+  if (dot) return { engine: 'dot', binary: dot, sourceExt: 'dot' };
+  return null;
+}
+
+export function installHint() {
+  if (process.platform === 'darwin') return 'brew install d2   (or: brew install graphviz)';
+  if (process.platform === 'linux') return 'curl -fsSL https://d2lang.com/install.sh | sh   (or install graphviz via your distro)';
+  return 'See https://d2lang.com/tour/install or https://graphviz.org/download/';
+}
+
+function inferType(description, explicit) {
+  if (explicit) return explicit;
+  const text = String(description || '').toLowerCase();
+  if (/\b(sequence|handshake|request|response|api call)\b/.test(text)) return 'sequence';
+  if (/\b(state|status|transition|machine|lifecycle)\b/.test(text)) return 'state';
+  if (/\b(entity|schema|database|table|relationship|foreign key)\b/.test(text)) return 'er';
+  if (/\b(class|inheritance|interface)\b/.test(text)) return 'class';
+  if (/\b(flow|funnel|step|decision|process)\b/.test(text)) return 'flow';
+  return 'architecture';
+}
+
+// Parse `a -> b -> c` (or `a → b → c`) chains out of the description so a
+// terse architecture prompt produces a real edge graph rather than a single
+// node. Falls back to treating the whole description as one node.
+
+function parseNodes(description) {
+  const text = String(description || '');
+  const arrowSplit = text.split(/\s*(?:->|→|=>)\s*/).map((s) => s.trim()).filter(Boolean);
+  if (arrowSplit.length >= 2) {
+    const stripped = arrowSplit.map((s) => s.replace(/^[a-z0-9\s]*:\s*/i, '').trim() || s);
+    return stripped.map((label) => label.split(/[,/]/)[0].trim()).filter(Boolean);
+  }
+  return [];
+}
+
+function nodeId(label, index) {
+  const id = String(label).toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+  return id || `n${index}`;
+}
+
+function d2Source(description, nodes) {
+  const header = `# ${description}\n# D2 source — render: d2 this.d2 out.svg  (https://d2lang.com)\n`;
+  if (nodes.length >= 2) {
+    const lines = nodes.map((label, i) => `${nodeId(label, i)}: ${label}`);
+    for (let i = 0; i < nodes.length - 1; i += 1) {
+      lines.push(`${nodeId(nodes[i], i)} -> ${nodeId(nodes[i + 1], i + 1)}`);
+    }
+    return `${header}${lines.join('\n')}\n`;
+  }
+  return `${header}node: ${description || 'Component'}\n`;
+}
+
+function dotSource(description, nodes) {
+  const header = `// ${description}\n// Graphviz DOT source — render: dot -Tsvg this.dot -o out.svg\n`;
+  const body = [];
+  if (nodes.length >= 2) {
+    nodes.forEach((label, i) => body.push(`  ${nodeId(label, i)} [label="${label}"];`));
+    for (let i = 0; i < nodes.length - 1; i += 1) {
+      body.push(`  ${nodeId(nodes[i], i)} -> ${nodeId(nodes[i + 1], i + 1)};`);
+    }
+  } else {
+    body.push(`  node [label="${description || 'Component'}"];`);
+  }
+  return `${header}digraph G {\n  rankdir=LR;\n${body.join('\n')}\n}\n`;
+}
+
+// For diagram kinds wireframe.mjs already models (flow/sequence/state/er) we
+// reuse its Mermaid generators when emitting source-only output, so the
+// description maps to a richer diagram than a bare D2 chain.
+
+const WIREFRAME_KINDS = { flow: 'flow', sequence: 'sequence', state: 'state', er: 'er' };
+
+export function generateDiagram({ description = '', type = null, theme = null } = {}) {
+  const kind = inferType(description, type);
+  const nodes = parseNodes(description);
+
+  let source;
+  let engineHint;
+  if (nodes.length >= 2 || kind === 'architecture' || kind === 'class') {
+    source = d2Source(description, nodes);
+    engineHint = 'd2';
+  } else {
+    const wf = generateWireframe({ description, type: WIREFRAME_KINDS[kind] || 'flow' });
+    source = wf.content;
+    engineHint = 'mermaid';
+  }
+  return { kind, nodes, source, engineHint, theme };
+}
+
+// Render via the detected binary. D2 themes map to numeric ids; an invalid
+// theme name is ignored rather than failing the render. Returns the render
+// result so the caller can fall back to source-only on any non-zero exit.
+
+function renderWithD2(binary, sourcePath, outPath, { format, theme }) {
+  const args = [];
+  const themeName = theme?.toLowerCase();
+  if (themeName === 'sketch') {
+    args.push('--sketch');
+  } else if (themeName) {
+    const themeId = D2_THEMES[themeName];
+    if (themeId != null) args.push('--theme', String(themeId));
+  }
+  args.push(sourcePath, outPath);
+  return spawnSync(binary, args, { encoding: 'utf8', timeout: 60_000 });
+}
+
+const D2_THEMES = {
+  neutral: 0,
+  'neutral-grey': 1,
+  'flagship-terrastruct': 3,
+  'cool-classics': 4,
+  'mixed-berry-blue': 5,
+  'grape-soda': 6,
+  aubergine: 7,
+  'colorblind-clear': 8,
+  'vanilla-nitro-cola': 100,
+  'orange-creamsicle': 101,
+};
+
+function renderWithDot(binary, sourcePath, outPath, { format }) {
+  return spawnSync(binary, [`-T${format}`, sourcePath, '-o', outPath], { encoding: 'utf8', timeout: 60_000 });
+}
+
+export function printHelp() {
+  console.log(`Usage: construct diagram <description> [options]
+
+Generates a code-driven diagram from a description and renders it to SVG/PNG
+via D2 (primary) or Graphviz dot (fallback). When neither renderer is
+installed, writes the diagram SOURCE plus an install hint and exits 0.
+
+Options:
+  --type <t>     architecture (default) | flow | sequence | state | er | class
+  --format <f>   svg (default) | png
+  --theme <name> D2 theme name (default: neutral; sketch enables --sketch hand-drawn)
+  --out <path>   Output path (default: .cx/diagrams/<slug>-<ts>.<ext>)
+  --source-only  Always write the source file; skip rendering
+  -h, --help     Show this message
+
+Renderers (detected at runtime, never bundled):
+  D2     ${process.platform === 'darwin' ? 'brew install d2' : 'https://d2lang.com/tour/install'}
+  dot    ${process.platform === 'darwin' ? 'brew install graphviz' : 'https://graphviz.org/download/'}
+
+Examples:
+  construct diagram "web app: client -> api -> db"
+  construct diagram "auth flow" --type flow
+  construct diagram "client -> api -> db" --format png --theme neutral
+`);
+}
+
+function parseArgs(argv) {
+  const options = { type: null, format: 'svg', theme: null, out: null, sourceOnly: false, description: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') { options.help = true; continue; }
+    if (arg === '--source-only') { options.sourceOnly = true; continue; }
+    if (arg === '--type') { options.type = argv[++i]; continue; }
+    if (arg.startsWith('--type=')) { options.type = arg.slice(7); continue; }
+    if (arg === '--format') { options.format = argv[++i]; continue; }
+    if (arg.startsWith('--format=')) { options.format = arg.slice(9); continue; }
+    if (arg === '--theme') { options.theme = argv[++i]; continue; }
+    if (arg.startsWith('--theme=')) { options.theme = arg.slice(8); continue; }
+    if (arg === '--out') { options.out = argv[++i]; continue; }
+    if (arg.startsWith('--out=')) { options.out = arg.slice(6); continue; }
+    options.description.push(arg);
+  }
+  options.description = options.description.join(' ').trim();
+  return options;
+}
+
+export async function runDiagramCli(argv = [], { cwd = process.cwd() } = {}) {
+  const options = parseArgs(argv);
+  if (options.help || !options.description) {
+    printHelp();
+    if (!options.help && !options.description) process.exit(1);
+    return;
+  }
+  if (options.type && !TYPES.includes(options.type)) {
+    console.error(`Unknown type: ${options.type}. Valid: ${TYPES.join(', ')}`);
+    process.exit(1);
+  }
+  if (!FORMATS.includes(options.format)) {
+    console.error(`Unknown format: ${options.format}. Valid: ${FORMATS.join(', ')}`);
+    process.exit(1);
+  }
+
+  const effectiveTheme = options.theme || 'neutral';
+  const result = generateDiagram({ description: options.description, type: options.type, theme: effectiveTheme });
+  const renderer = options.sourceOnly ? null : locateRenderer();
+
+  const slug = slugify(options.description);
+  const dir = options.out ? dirname(resolve(cwd, options.out)) : join(cwd, '.cx', 'diagrams');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  // Source is always written. When the source is Mermaid (reused wireframe
+  // output) the .d2/.dot renderers can't consume it, so we keep the source
+  // extension honest and skip the binary render in that case.
+
+  const renderableSource = result.engineHint !== 'mermaid';
+  const sourceExt = result.engineHint === 'mermaid' ? 'md' : (renderer ? renderer.sourceExt : 'd2');
+  const baseName = options.out
+    ? resolve(cwd, options.out).replace(/\.[^./]+$/, '')
+    : join(dir, `${slug}-${timestamp()}`);
+  const sourcePath = `${baseName}.${sourceExt}`;
+
+  let source = result.source;
+  if (renderer && renderableSource) {
+    source = renderer.engine === 'dot' ? dotSource(options.description, result.nodes) : d2Source(options.description, result.nodes);
+  }
+  writeFileSync(sourcePath, source, 'utf8');
+
+  if (!renderer || !renderableSource) {
+    console.log(`Diagram source (${result.kind}, ${result.engineHint}) written to:`);
+    console.log(`  ${sourcePath}`);
+    if (!renderer) {
+      console.log(`\nNo diagram renderer found. To render SVG/PNG, install one:`);
+      console.log(`  ${installHint()}`);
+    } else {
+      console.log(`\nThis diagram kind renders as Mermaid; paste into any Mermaid-aware viewer (GitHub, Notion, OpenCode).`);
+    }
+    return;
+  }
+
+  const outPath = `${baseName}.${options.format}`;
+  const render = renderer.engine === 'd2'
+    ? renderWithD2(renderer.binary, sourcePath, outPath, { format: options.format, theme: effectiveTheme })
+    : renderWithDot(renderer.binary, sourcePath, outPath, { format: options.format });
+
+  if (render.status === 0 && existsSync(outPath)) {
+    console.log(`Diagram (${result.kind}) rendered via ${renderer.engine} to:`);
+    console.log(`  ${outPath}`);
+    console.log(`Source: ${sourcePath}`);
+    return;
+  }
+
+  console.log(`Diagram source written to:`);
+  console.log(`  ${sourcePath}`);
+  console.log(`\nRenderer ${renderer.engine} failed (exit ${render.status}); source preserved.`);
+  if (render.stderr) console.log(`  ${render.stderr.trim().split('\n').slice(0, 3).join('\n  ')}`);
+}

package/lib/docs-verify.mjs

@@ -20,6 +20,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { statSync, readFileSync, existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { hasIntakeReference } from "./intake/traceability.mjs";
 import { ensureCxDir } from "./project-init-shared.mjs";
 
@@ -27,6 +28,7 @@ const args = process.argv.slice(2);
 const quickMode = args.includes("--quick");
 const fixMode = args.includes("--fix");
 const stagedMode = args.includes("--staged");
+const strictMode = args.includes("--strict") || process.env.CI === 'true';
 const cwdArg = args.find(arg => arg.startsWith("--cwd="));
 const cwd = cwdArg ? path.resolve(cwdArg.split("=")[1]) : process.cwd();
 
@@ -195,6 +197,17 @@ function checkContextHasProgress(contextPath) {
 // not every artifact necessarily comes from an intake packet — but the absence
 // is a flag for the operator to either stamp the provenance or declare it
 // intake-independent.
+function gitTrackedMdFiles(cwd, dir) {
+  if (!fs.existsSync(dir)) return [];
+  const rel = path.relative(cwd, dir).split(path.sep).join('/');
+  const result = spawnSync('git', ['ls-files', '--', `${rel}/`], { cwd, encoding: 'utf8' });
+  if (result.status !== 0 || !result.stdout) return [];
+  return result.stdout
+    .split('\n')
+    .filter((line) => line.endsWith('.md') && !line.endsWith('/README.md'))
+    .map((line) => path.join(cwd, line));
+}
+
 function checkIntakeTraceability(cwd) {
   const intakeFedDirs = [
     path.join(cwd, 'docs', 'prd'),
@@ -203,13 +216,10 @@ function checkIntakeTraceability(cwd) {
   ];
   let inspected = 0;
   for (const dir of intakeFedDirs) {
-    if (!fs.existsSync(dir)) continue;
-    let entries;
-    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
-    for (const entry of entries) {
-      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
-      if (entry.name.startsWith('_') || entry.name.toLowerCase() === 'readme.md') continue;
-      const filePath = path.join(dir, entry.name);
+    const files = gitTrackedMdFiles(cwd, dir);
+    for (const filePath of files) {
+      const base = path.basename(filePath);
+      if (base.startsWith('_')) continue;
       inspected += 1;
       if (!hasIntakeReference(filePath)) {
         warnings.push(
@@ -438,6 +448,14 @@ function main() {
     console.log("💡 Run `construct init:update` to update project to current standards");
     process.exit(1);
   }
+
+  if (strictMode && warnings.length > 0) {
+    console.log("❌ Strict mode: warnings are blocking:");
+    for (const warning of warnings) {
+      console.log(`  • ${warning}`);
+    }
+    process.exit(1);
+  }
   
   console.log("✅ Documentation validation passed with warnings");
   process.exit(0);

package/lib/doctor/index.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/doctor/index.mjs — `construct-doctor` daemon main loop.
  *
- * Long-running Node process spawned by `construct up`. Holds the L0 watchers
+ * Long-running Node process spawned by `construct dev`. Holds the L0 watchers
  * for resource pressure, service health, disk + log rotation, and cost. Each
  * watcher ticks on its own interval; the loop is bounded so a slow watcher
  * never starves the others. Termination via SIGTERM/SIGINT triggers a clean
@@ -24,9 +24,11 @@ import * as bdWatch from './watchers/bd-watch.mjs';
 import * as handoffs from './watchers/handoffs.mjs';
 import * as consistency from './watchers/consistency.mjs';
 import * as mcpProtocol from './watchers/mcp-protocol.mjs';
+import * as cxBudget from './watchers/cx-budget.mjs';
+import * as graphStaleness from './watchers/graph-staleness.mjs';
 
 const STATE_PATH = join(homedir(), '.construct', 'doctor.json');
-const WATCHERS = [disk, cost, processPressure, serviceHealth, bdWatch, handoffs, consistency, mcpProtocol];
+const WATCHERS = [disk, cost, processPressure, serviceHealth, bdWatch, handoffs, consistency, mcpProtocol, cxBudget, graphStaleness];
 
 let running = false;
 let timers = [];

package/lib/doctor/project-adapters.mjs

@@ -0,0 +1,44 @@
+/**
+ * lib/doctor/project-adapters.mjs — doctor checks for project-scoped host adapters.
+ *
+ * When inside a Construct-managed project, verifies gitignored adapter artifacts
+ * exist for installed hosts (.cursor/mcp.json, .vscode/mcp.json, construct.mdc).
+ */
+
+import { checkProjectParity } from '../parity.mjs';
+import { detectHostCapabilities } from '../host-capabilities.mjs';
+
+const HOST_REQUIRES = {
+  cursor: ['cursor'],
+  vscode: ['vscode'],
+};
+
+export function checkProjectAdaptersForDoctor({ rootDir, projectDir = rootDir }) {
+  const parity = checkProjectParity({ rootDir, projectDir });
+  if (parity.skipped) return { ok: true, label: 'Project adapters (not a Construct project)', warning: false };
+
+  const installed = new Set(
+    detectHostCapabilities()
+      .filter((h) => h.availability === 'installed')
+      .map((h) => h.host.toLowerCase().replace(/\s+/g, '')),
+  );
+  const installedIds = new Set();
+  if (installed.has('claudecode') || installed.has('claude')) installedIds.add('claude');
+  if (installed.has('vscode')) installedIds.add('vscode');
+  if (installed.has('cursor')) installedIds.add('cursor');
+
+  const failures = [];
+  for (const surface of parity.surfaces) {
+    if (surface.status === 'absent' && (surface.surface === 'cursor' || surface.surface === 'vscode')) {
+      if (installedIds.has(surface.surface)) failures.push(surface);
+    }
+    if (surface.status === 'drift') failures.push(surface);
+  }
+
+  const ok = failures.length === 0;
+  const label = ok
+    ? `Project adapters (${parity.summary.filter((s) => s.includes(': ok')).length}/${parity.surfaces.length} ok)`
+    : `Project adapters missing or stale — run \`npm run adapters\` (${failures.map((f) => f.surface).join(', ')})`;
+
+  return { ok, label, warning: !ok, parity };
+}