@geraldmaron/construct 1.1.0 → 1.2.0

package/lib/orchestration-policy.mjs

@@ -18,6 +18,7 @@
 import { resolveContractChain } from './specialist-contracts.mjs';
 import { verifyRoute } from './intent-classifier.mjs';
 import { ownerForEvent, ownerForDoc, evaluateWatchConditions, knownDocTypes } from './orchestration/routing-tables.mjs';
+import { getArtifactEntry } from './artifact-manifest.mjs';
 
 export const EXECUTION_TRACKS = {
   immediate: 'immediate',
@@ -653,6 +654,19 @@ export function formatOverlayTrace(roleFlavors = {}, request = '') {
   return `Overlays: ${parts.join(', ')}`;
 }
 
+function resolveArtifactReviewRequirements(docAuthoring) {
+  if (!docAuthoring?.docType) {
+    return { requiredReviewers: [], optionalReviewers: [], releaseGate: null };
+  }
+  const entry = getArtifactEntry(docAuthoring.docType);
+  const gate = entry?.releaseGate ?? {};
+  return {
+    requiredReviewers: gate.requiredReviewers ?? [],
+    optionalReviewers: gate.optionalReviewers ?? [],
+    releaseGate: gate,
+  };
+}
+
 export function routeRequest(options = {}) {
   const intent = classifyIntent(options.request);
   const riskFlags = detectRiskFlags(options.request);
@@ -679,6 +693,11 @@ export function routeRequest(options = {}) {
   if (framingChallenge.required && !specialists.includes('cx-devil-advocate')) {
     specialists = ['cx-devil-advocate', ...specialists];
   }
+
+  const artifactReview = resolveArtifactReviewRequirements(docAuthoring);
+  for (const reviewer of artifactReview.requiredReviewers) {
+    if (!specialists.includes(reviewer)) specialists = [...specialists, reviewer];
+  }
   // Pre-dispatch specialists that surface concerns before architecture locks in.
   // Order matters: business framing → R&D validation → legal/compliance review,
   // each prepended so it runs earliest in the chain.
@@ -715,6 +734,7 @@ export function routeRequest(options = {}) {
     framingChallenge,
     externalResearch,
     docAuthoring,
+    artifactReview,
   });
 
   const route = {
@@ -731,6 +751,7 @@ export function routeRequest(options = {}) {
     docAuthoring,
     externalResearch,
     framingChallenge,
+    artifactReview,
     contractChain,
     dispatchPlan: buildDispatchPlan({ track, intent, specialists }),
     dispatchSummary: buildDispatchSummary({ specialists, reasons }),
@@ -754,3 +775,32 @@ export function routeRequestVerified(options = {}) {
   const route = routeRequest(options);
   return verifyRoute(route, { request: options.request, modelCaller: options.modelCaller });
 }
+
+/**
+ * Build the construct→orchestrator contract packet (specialists/contracts.json).
+ * Callers must pass this object to agent_contract — not a bare goal string.
+ */
+export function buildConstructToOrchestratorPacket(options = {}) {
+  const request = String(options.request || '');
+  const route = options.route || routeRequest({
+    request,
+    fileCount: options.fileCount ?? 0,
+    moduleCount: options.moduleCount ?? 0,
+    introducesContract: options.introducesContract ?? false,
+    explicitDrive: options.explicitDrive ?? false,
+  });
+  if (route.track === EXECUTION_TRACKS.immediate) return null;
+
+  const goal = String(options.goal || request || '').trim() || 'User-requested work';
+  const acceptanceCriteria = Array.isArray(options.acceptanceCriteria) && options.acceptanceCriteria.length
+    ? options.acceptanceCriteria
+    : ['Dispatch plan emitted with specialists in sequence', 'Acceptance criteria verified before close'];
+
+  return {
+    goal,
+    intent: route.intent,
+    workCategory: route.workCategory,
+    riskFlags: route.riskFlags || {},
+    acceptanceCriteria,
+  };
+}

package/lib/parity.mjs

@@ -104,6 +104,16 @@ function diffSets(expected, actual) {
   return { missing, extra };
 }
 
+// Construct ensures its own MCP servers are present; it does not own the user's
+// full editor MCP list. A non-registry server the user added (e.g. playwright) is
+// not drift — only a MISSING registry server is, which is a real sync regression.
+// A rename still surfaces, since the new name registers as missing. Agent surfaces
+// keep extra-detection (legacy cx-* cleanup), so this applies to MCP kinds only.
+
+function mcpStatus(missing) {
+  return missing.length === 0 ? 'ok' : 'drift';
+}
+
 function checkFileSurface({ surface, kind, dir, extension, expected }) {
   if (!fs.existsSync(dir)) return { surface, kind, status: 'absent', dir };
   const actual = fs.readdirSync(dir)
@@ -245,7 +255,7 @@ function checkVSCode(registry, { homeDir = os.homedir() } = {}) {
   return {
     surface: 'vscode',
     kind: 'mcps',
-    status: missing.length === 0 && extra.length === 0 ? 'ok' : 'drift',
+    status: mcpStatus(missing),
     paths,
     expectedCount: expected.length,
     actualCount: actual.length,
@@ -269,7 +279,7 @@ function checkCursor(registry, { homeDir = os.homedir() } = {}) {
   return {
     surface: 'cursor',
     kind: 'mcps',
-    status: missing.length === 0 && extra.length === 0 ? 'ok' : 'drift',
+    status: mcpStatus(missing),
     file,
     expectedCount: expected.length,
     actualCount: actual.length,
@@ -278,6 +288,90 @@ function checkCursor(registry, { homeDir = os.homedir() } = {}) {
   };
 }
 
+function checkProjectMcp(registry, { projectDir, surface, relPath, configKey }) {
+  const file = path.join(projectDir, relPath);
+  if (!fs.existsSync(file)) {
+    return { surface, scope: 'project', kind: 'mcps', status: 'absent', file };
+  }
+  let config;
+  try {
+    config = readJsoncFile(file);
+  } catch (err) {
+    return { surface, scope: 'project', kind: 'mcps', status: 'unreadable', file, error: err.message };
+  }
+  const servers = config[configKey] ?? {};
+  const expected = Object.keys(registry.mcpServers ?? {}).filter((id) => id !== 'memory');
+  const actual = Object.keys(servers).filter((id) => id !== 'memory');
+  const { missing, extra } = diffSets(expected, actual);
+  return {
+    surface,
+    scope: 'project',
+    kind: 'mcps',
+    status: mcpStatus(missing),
+    file,
+    expectedCount: expected.length,
+    actualCount: actual.length,
+    missing,
+    extra,
+  };
+}
+
+function checkProjectCursorRules({ projectDir }) {
+  const pointer = path.join(projectDir, '.cursor', 'rules', 'construct.mdc');
+  if (!fs.existsSync(pointer)) {
+    return { surface: 'cursor', scope: 'project', kind: 'rules', status: 'absent', file: pointer };
+  }
+  const text = fs.readFileSync(pointer, 'utf8');
+  const stale = !text.includes('Generated by construct sync');
+  return {
+    surface: 'cursor',
+    scope: 'project',
+    kind: 'rules',
+    status: stale ? 'drift' : 'ok',
+    file: pointer,
+    stale,
+  };
+}
+
+function checkProjectClaudeAgent({ projectDir, registry }) {
+  const expected = registry.orchestrator?.name || 'construct';
+  const file = path.join(projectDir, '.claude', 'agents', `${expected}.md`);
+  if (!fs.existsSync(file)) {
+    return { surface: 'claude', scope: 'project', kind: 'agents', status: 'absent', file, expected: [expected] };
+  }
+  return { surface: 'claude', scope: 'project', kind: 'agents', status: 'ok', file, expected: [expected], actual: [expected] };
+}
+
+/**
+ * Project-scoped adapter parity for Construct-managed repos (.cx/ or .construct/).
+ * Checks `.cursor/mcp.json`, `.vscode/mcp.json`, front-door rule, and construct agent.
+ */
+export function checkProjectParity({ rootDir = ROOT_DIR, projectDir = rootDir } = {}) {
+  const cxPresent = fs.existsSync(path.join(projectDir, '.cx')) || fs.existsSync(path.join(projectDir, '.construct'));
+  if (!cxPresent) {
+    return { ok: true, skipped: true, surfaces: [], summary: ['project: not a Construct project'] };
+  }
+  const registry = loadRegistry(rootDir);
+  const surfaces = [
+    checkProjectClaudeAgent({ projectDir, registry }),
+    checkProjectMcp(registry, { projectDir, surface: 'cursor', relPath: '.cursor/mcp.json', configKey: 'mcpServers' }),
+    checkProjectMcp(registry, { projectDir, surface: 'vscode', relPath: '.vscode/mcp.json', configKey: 'servers' }),
+    checkProjectCursorRules({ projectDir }),
+  ];
+  const ok = surfaces.every((s) => s.status === 'ok' || s.status === 'absent');
+  const summary = surfaces.map((s) => {
+    if (s.status === 'absent') return `${s.surface} (project): missing ${s.kind}`;
+    if (s.status === 'unreadable') return `${s.surface} (project): unreadable (${s.error})`;
+    if (s.status === 'ok') return `${s.surface} (project): ok`;
+    if (s.stale) return `${s.surface} (project): stale construct.mdc — run \`npm run adapters\``;
+    const parts = [];
+    if (s.missing?.length) parts.push(`missing: ${s.missing.join(', ')}`);
+    if (s.extra?.length) parts.push(`extra: ${s.extra.join(', ')}`);
+    return `${s.surface} (project): drift — ${parts.join(' · ')}`;
+  });
+  return { ok, skipped: false, surfaces, summary };
+}
+
 // Names a v1.0.10 install would have populated at user scope (claude, codex,
 // copilot) before the two-tier sync contract moved specialists to project
 // scope. Pulled from the live registry so the roster auto-updates as new

package/lib/persona-sections.mjs

@@ -0,0 +1,66 @@
+/**
+ * lib/persona-sections.mjs — Capability-tiered persona section rendering.
+ *
+ * A persona is authored once. Each `## ` section carries an inline `<!-- cx:prio=N -->`
+ * marker on its heading; the preamble before the first heading is always prio 1
+ * (identity + anti-fabrication). Small local models follow large multi-instruction
+ * prompts poorly — instruction-following degrades well before the context window fills —
+ * so a weak model receives only the sections it can actually comply with. Tiers:
+ * floor (prio 1, must-keep), mid (prio <= 2), full (all). The marker is stripped from the
+ * emitted text. Untagged `## ` sections default to prio 2 so authoring omissions degrade
+ * gracefully rather than vanishing or forcing a floor model to read everything.
+ */
+
+const TIER_MAX_PRIO = Object.freeze({ floor: 1, mid: 2, full: 3 });
+const PRIO_MARKER = /<!--\s*cx:prio=(\d+)\s*-->/;
+const PRIO_MARKER_GLOBAL = /[ \t]*<!--\s*cx:prio=\d+\s*-->/g;
+
+// The markers are authoring metadata; no emitted prompt (full or tiered) may carry them.
+// Tiered render strips them via section parsing; full render (composePrompt) calls this.
+
+export function stripSectionMarkers(text) {
+  return String(text || "").replace(PRIO_MARKER_GLOBAL, "");
+}
+
+// `## ` (exactly two hashes) is the only section boundary; `### ` subheadings stay with
+// their parent section. The preamble (before the first `## `) is implicit prio 1.
+
+export function parsePersonaSections(body) {
+  const lines = String(body || "").split("\n");
+  const sections = [];
+  let current = { heading: null, prio: 1, lines: [] };
+
+  const flush = () => {
+    const content = current.lines.join("\n").trim();
+    if (content || current.heading) {
+      sections.push({ heading: current.heading, prio: current.prio, content });
+    }
+  };
+
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      flush();
+      const marker = line.match(PRIO_MARKER);
+      const prio = marker ? Number(marker[1]) : 2;
+      const heading = line.replace(PRIO_MARKER, "").trimEnd();
+      current = { heading, prio, lines: [heading] };
+    } else {
+      current.lines.push(line);
+    }
+  }
+  flush();
+  return sections;
+}
+
+export function renderPersonaForTier(body, tier = "full") {
+  const maxPrio = TIER_MAX_PRIO[tier] ?? TIER_MAX_PRIO.full;
+  return parsePersonaSections(body)
+    .filter((section) => section.prio <= maxPrio)
+    .map((section) => stripSectionMarkers(section.content))
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+export function personaTierMaxPrio(tier) {
+  return TIER_MAX_PRIO[tier] ?? TIER_MAX_PRIO.full;
+}

package/lib/playwright-demo.mjs

@@ -0,0 +1,252 @@
+/**
+ * lib/playwright-demo.mjs — workspace-agnostic Playwright demo recording.
+ *
+ * Spawns `npx playwright test --config <config> <spec>` with env passthrough for
+ * artifact reveal, collects video output, and transcodes webm→mp4 when ffmpeg exists.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { sanitizeNpmSpawnEnv } from './npm-spawn-env.mjs';
+
+export function resolvePlaywrightPackage(workspace, repoRoot) {
+  const candidates = [
+    path.join(workspace, 'node_modules', '@playwright', 'test'),
+    path.join(repoRoot, 'node_modules', '@playwright', 'test'),
+  ];
+  return candidates.find((p) => fs.existsSync(p)) || null;
+}
+
+export function resolvePlaywrightConfig(workspace) {
+  const candidates = ['playwright.config.mjs', 'playwright.config.ts'].map((f) => path.join(workspace, f));
+  return candidates.find((p) => fs.existsSync(p)) || null;
+}
+
+export function detectPlaywrightDemo({ workspace, cwd = process.cwd(), repoRoot = cwd } = {}) {
+  const root = repoRoot || cwd;
+  const resolvedWorkspace = path.resolve(root, workspace || '.');
+  const missing = [];
+  if (!fs.existsSync(path.join(resolvedWorkspace, 'package.json'))) {
+    missing.push(`package.json in ${workspace || '.'}`);
+  }
+  const config = resolvePlaywrightConfig(resolvedWorkspace);
+  if (!config) missing.push(`playwright.config.mjs in ${workspace || '.'}`);
+  if (!resolvePlaywrightPackage(resolvedWorkspace, root)) {
+    missing.push('@playwright/test (npm install in workspace)');
+  }
+  return {
+    ok: true,
+    present: missing.length === 0,
+    workspace: resolvedWorkspace,
+    config,
+    missing,
+    message: missing.length === 0
+      ? 'Playwright demo tooling ready'
+      : `Install Playwright demo deps: ${missing.join('; ')}`,
+  };
+}
+
+export function locateFfmpeg() {
+  const result = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['ffmpeg'], { encoding: 'utf8' });
+  if (result.status !== 0) return null;
+  return result.stdout.trim().split('\n')[0] || null;
+}
+
+export function collectVideoFiles(dirs) {
+  const collected = [];
+  function walk(dir) {
+    if (!dir || !fs.existsSync(dir)) return;
+    for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+      const p = path.join(dir, ent.name);
+      if (ent.isDirectory()) walk(p);
+      else if (/\.(webm|mp4)$/.test(ent.name)) collected.push(p);
+    }
+  }
+  for (const dir of dirs) walk(dir);
+  return collected;
+}
+
+export function newestVideo(paths) {
+  if (!paths.length) return null;
+  return paths
+    .map((p) => ({ p, mtime: fs.statSync(p).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime)[0].p;
+}
+
+export function transcodeWebmToMp4(src, dest) {
+  const ffmpeg = locateFfmpeg();
+  if (!ffmpeg) return { ok: false, message: 'ffmpeg not on PATH' };
+  const result = spawnSync(ffmpeg, [
+    '-y', '-i', src,
+    '-c:v', 'libx264',
+    '-pix_fmt', 'yuv420p',
+    '-movflags', '+faststart',
+    dest,
+  ], { encoding: 'utf8', timeout: 180_000 });
+  if (result.status !== 0) {
+    return {
+      ok: false,
+      message: `ffmpeg failed (exit ${result.status}): ${(result.stderr || '').trim().slice(0, 300)}`,
+    };
+  }
+  return { ok: true, outputPath: dest };
+}
+
+export function finalizeDemoVideo({ sourcePath, outputPath, format = 'mp4' }) {
+  if (!sourcePath || !fs.existsSync(sourcePath)) {
+    return { ok: false, message: 'No video artifact produced' };
+  }
+  const target = outputPath || sourcePath;
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+
+  if (format === 'mp4' && sourcePath.endsWith('.webm')) {
+    const transcode = transcodeWebmToMp4(sourcePath, target);
+    if (!transcode.ok) return transcode;
+    return { ok: true, outputPath: target, format: 'mp4', engine: 'playwright+ffmpeg' };
+  }
+
+  if (path.resolve(sourcePath) !== path.resolve(target)) {
+    fs.copyFileSync(sourcePath, target);
+  }
+  return {
+    ok: true,
+    outputPath: target,
+    format: path.extname(target).slice(1) || format,
+    engine: 'playwright',
+  };
+}
+
+export function buildArtifactRevealEnv(recording, {
+  repoRoot,
+  cwd = repoRoot,
+  artifactDir = null,
+  artifactFile = null,
+  env = process.env,
+} = {}) {
+  const reveal = recording?.artifactReveal;
+  const out = { ...env };
+  if (!reveal && !artifactDir && !artifactFile) return out;
+
+  const file = artifactFile || reveal?.file || reveal?.path || '';
+  const staticDir = artifactDir
+    || (reveal?.staticDir ? path.resolve(repoRoot || cwd, reveal.staticDir) : '');
+
+  if (staticDir) out.CONSTRUCT_DEMO_ARTIFACT_DIR = staticDir;
+  if (file) out.DEMO_ARTIFACT_FILE = file;
+  if (reveal?.mode) out.DEMO_ARTIFACT_REVEAL_MODE = reveal.mode;
+  if (recording?.baseUrl) out.BASE_URL = recording.baseUrl;
+  if (recording?.webServer && !recording.skipWebServer) {
+    out.DEMO_WEB_SERVER_COMMAND = recording.webServer.command;
+    out.DEMO_WEB_SERVER_URL = recording.webServer.url;
+    out.DEMO_WEB_SERVER_CWD = path.resolve(repoRoot || cwd, recording.webServer.cwd || recording.workspace || '.');
+    out.DEMO_WEB_SERVER_TIMEOUT = String(recording.webServer.timeout || 120_000);
+  }
+  if (recording?.skipWebServer) out.SKIP_WEBSERVER = '1';
+  return out;
+}
+
+export function resolveRecordingPaths(recording, { repoRoot, cwd = repoRoot } = {}) {
+  const root = repoRoot || cwd;
+  const workspace = path.resolve(root, recording.workspace || '.');
+  const spec = path.isAbsolute(recording.spec)
+    ? recording.spec
+    : path.resolve(root, recording.spec);
+  const config = recording.playwrightConfig
+    ? (path.isAbsolute(recording.playwrightConfig)
+      ? recording.playwrightConfig
+      : path.resolve(root, recording.playwrightConfig))
+    : resolvePlaywrightConfig(workspace);
+  const outputDir = recording.output?.path
+    ? path.dirname(path.resolve(root, recording.output.path))
+    : path.join(cwd, '.cx', 'demos');
+  return { workspace, spec, config, outputDir };
+}
+
+export function recordPlaywrightDemo(recording, {
+  cwd = process.cwd(),
+  repoRoot,
+  outputDir = null,
+  outputPath = null,
+  format = null,
+  artifactDir = null,
+  artifactFile = null,
+  env = process.env,
+  timeout = null,
+} = {}) {
+  const root = repoRoot || cwd;
+  const name = recording.name || path.basename(recording.spec || '', '.spec.ts');
+  const { workspace, spec, config, outputDir: defaultOutDir } = resolveRecordingPaths(recording, { repoRoot: root, cwd });
+  const detection = detectPlaywrightDemo({ workspace, repoRoot: root, cwd });
+  if (!detection.present) {
+    return { ok: false, name, missing: detection.missing, message: detection.message };
+  }
+  if (!config || !fs.existsSync(config)) {
+    return { ok: false, name, message: `Playwright config not found for workspace ${recording.workspace || '.'}` };
+  }
+  if (!fs.existsSync(spec)) {
+    return { ok: false, name, message: `Demo spec not found: ${spec}` };
+  }
+
+  const outDir = outputDir || defaultOutDir;
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const outFormat = format || recording.output?.format || 'mp4';
+  const destPath = outputPath
+    || (recording.output?.path ? path.resolve(root, recording.output.path) : path.join(outDir, `${name}.${outFormat}`));
+
+  const spawnEnv = buildArtifactRevealEnv(recording, {
+    repoRoot: root,
+    cwd,
+    artifactDir,
+    artifactFile,
+    env: {
+      ...env,
+      DEMO_OUTPUT_DIR: outDir,
+      CONSTRUCT_DEMO: name,
+      CI: env.CI || '',
+    },
+  });
+
+  const args = ['playwright', 'test', '--config', config, spec];
+  if (recording.project) args.push(`--project=${recording.project}`);
+
+  const spawnTimeout = timeout || recording.timeout || 600_000;
+  const result = spawnSync('npx', args, {
+    cwd: workspace,
+    encoding: 'utf8',
+    env: sanitizeNpmSpawnEnv(spawnEnv),
+    timeout: spawnTimeout,
+  });
+
+  if (result.status !== 0) {
+    const detail = (result.stderr || result.stdout || result.error?.message || '').trim().slice(0, 500);
+    const exitLabel = result.signal ? `signal ${result.signal}` : `exit ${result.status}`;
+    return {
+      ok: false,
+      name,
+      message: `Playwright demo failed (${exitLabel})${detail ? `: ${detail}` : ''}`,
+    };
+  }
+
+  const videos = collectVideoFiles([
+    path.join(workspace, 'test-results'),
+    outDir,
+  ]);
+  const newest = newestVideo(videos);
+  const finalized = finalizeDemoVideo({ sourcePath: newest, outputPath: destPath, format: outFormat });
+  if (!finalized.ok) {
+    return { ok: false, name, message: finalized.message };
+  }
+
+  return {
+    ok: true,
+    name,
+    outputDir: outDir,
+    outputPath: finalized.outputPath,
+    format: finalized.format,
+    engine: finalized.engine,
+    videos: videos.map((p) => path.basename(p)),
+    message: `Recorded Playwright demo to ${finalized.outputPath}`,
+  };
+}

package/lib/project-init-shared.mjs

@@ -87,7 +87,10 @@ instead of letting it turn into a historical log. Durable task status belongs in
 
 > Required project state. Keep this file current enough that a new session can resume work quickly.
 
-## Active Work
+## What was in progress
+
+## Open issues
+None
 
 ## Recent Decisions
 

package/lib/prompt-composer.js

@@ -24,12 +24,16 @@ import { buildContextDigest, readContextState } from './context-state.mjs';
 import {
   MODEL_OPERATING_PROFILES,
   resolveExecutionContractModelMetadata,
-  resolveModelOperatingProfile,
   selectModelTierForWorkCategory,
 } from './model-router.mjs';
+import {
+  resolveExecutionCapabilityProfile,
+  operatingProfileIdFromProfile,
+} from './models/execution-capability-profile.mjs';
 import { listObservations } from './observation-store.mjs';
 import { routeRequest } from './orchestration-policy.mjs';
 import { resolvePromptEntry, resolvePromptMetadata } from './prompt-metadata.mjs';
+import { stripSectionMarkers } from './persona-sections.mjs';
 import { readRoleFile } from './role-preload.mjs';
 import { estimateTokens, estimatePromptTokens, estimateTokensSync } from './token-engine.js';
 import { cxDir } from './paths.mjs';
@@ -207,12 +211,13 @@ export function composePrompt(agentName, {
 
   const metadata = resolvePromptMetadata(agentName, { rootDir, registry });
   const fragments = [];
-  const selectedProfile = resolveModelOperatingProfile({
+  const executionProfile = resolveExecutionCapabilityProfile({
+    model: executionContractModel?.selectedModel ?? modelId,
     envValues: executionContractModel?.profile ? { CONSTRUCT_MODEL_PROFILE: executionContractModel.profile.id } : {},
-    selectedModel: executionContractModel?.selectedModel ?? modelId,
   });
+  const selectedProfile = MODEL_OPERATING_PROFILES[operatingProfileIdFromProfile(executionProfile)];
 
-  fragments.push({ type: 'core', priority: PRIORITY['core'], label: entry.name, content: readPromptBody(entry.promptFile, rootDir), tokenBudget: null });
+  fragments.push({ type: 'core', priority: PRIORITY['core'], label: entry.name, content: stripSectionMarkers(readPromptBody(entry.promptFile, rootDir)), tokenBudget: null });
 
   const shortName = String(agentName).replace(/^cx-/, '');
   const flavorMapping = AGENT_FLAVOR_MAP[shortName];

package/lib/prompt-validation-contract.mjs

@@ -0,0 +1,24 @@
+/**
+ * lib/prompt-validation-contract.mjs — Inline shared validation contract at sync time.
+ *
+ * Prepends specialists/prompts/_shared/validation-contract.md to every cx-* prompt
+ * so assume-nothing discipline is present at runtime without 29 copy-paste edits.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MARKER = '<!-- cx:validation-contract -->';
+
+export function readValidationContract(root) {
+  const p = path.join(root, 'specialists', 'prompts', '_shared', 'validation-contract.md');
+  if (!fs.existsSync(p)) return null;
+  return fs.readFileSync(p, 'utf8').trim();
+}
+
+export function inlineValidationContract(prompt, root, agentName = '(unknown)') {
+  if (!prompt || prompt.includes(MARKER)) return prompt;
+  const block = readValidationContract(root);
+  if (!block) return prompt;
+  return `${MARKER}\n\n${block}\n\n${prompt}`;
+}

package/lib/provider-capabilities.js

@@ -41,6 +41,62 @@ function resolveAdapterKey(modelId) {
   return 'generic';
 }
 
+// Declared adapter defaults for sync hot paths when the 24h probe cache is cold.
+// Matches the static `capabilities()` exports in provider-capabilities-*.js.
+
+const SYNC_ADAPTER_CAPS = {
+  anthropic: {
+    cacheControl: true,
+    cacheMechanism: 'annotation',
+    cacheTTL: { '5m': 300_000, '1h': 1_200_000 },
+    structuredOutput: true,
+    maxContextWindow: 200_000,
+    tokenRatio: 3.5,
+    annotationFormat: 'anthropic',
+    annotationHeaders: { 'anthropic-version': '2024-10-22' },
+  },
+  google: {
+    cacheControl: true,
+    cacheMechanism: 'resource',
+    cacheTTL: { '5m': null, '1h': 1_200_000 },
+    structuredOutput: true,
+    maxContextWindow: 1_000_000,
+    tokenRatio: 4,
+    annotationFormat: 'google',
+    annotationHeaders: null,
+  },
+  openai: {
+    cacheControl: false,
+    cacheMechanism: 'automatic',
+    cacheTTL: null,
+    structuredOutput: true,
+    maxContextWindow: 128_000,
+    tokenRatio: 4,
+    annotationFormat: 'openai',
+    annotationHeaders: null,
+  },
+  deepseek: {
+    cacheControl: false,
+    cacheMechanism: 'none',
+    cacheTTL: null,
+    structuredOutput: true,
+    maxContextWindow: 128_000,
+    tokenRatio: 4,
+    annotationFormat: 'none',
+    annotationHeaders: null,
+  },
+  generic: {
+    cacheControl: false,
+    cacheMechanism: 'none',
+    cacheTTL: null,
+    structuredOutput: false,
+    maxContextWindow: 200_000,
+    tokenRatio: 4,
+    annotationFormat: 'none',
+    annotationHeaders: null,
+  },
+};
+
 function readCapabilityCache() {
   try {
     if (!existsSync(CAPABILITY_CACHE_PATH)) return {};
@@ -103,17 +159,7 @@ export function resolveProviderCapabilitiesSync(modelId) {
   // Check cache first (keyed by adapter type, not full model ID)
   if (cache[adapterKey]) return cache[adapterKey];
 
-  // Return generic synchronously (can't load adapter in sync context)
-  return {
-    cacheControl: false,
-    cacheMechanism: 'none',
-    cacheTTL: null,
-    structuredOutput: false,
-    maxContextWindow: 200000,
-    tokenRatio: 4,
-    annotationFormat: 'none',
-    annotationHeaders: null,
-  };
+  return SYNC_ADAPTER_CAPS[adapterKey] || SYNC_ADAPTER_CAPS.generic;
 }
 
 /**