@geraldmaron/construct 1.1.1 → 1.2.1

package/lib/bridges/copilot-proxy.mjs

@@ -6,32 +6,19 @@
  * using the user's active `gh` CLI session.
  */
 import http from 'node:http';
-import { execSync } from 'node:child_process';
+import { getCopilotToken as resolveCopilotSessionToken } from '../providers/copilot-auth.mjs';
 
 const PORT = parseInt(process.argv.find(a => a.startsWith('--port='))?.split('=')[1] || '5174', 10);
 
-let cachedSession = null;
+// Token minting, caching, and refresh live in copilot-auth (the OAuth device
+// flow). The bridge only proxies, so a missing or failed session token surfaces
+// to the client as a 401 with the remediation coming from `construct creds login copilot`.
 
 async function getCopilotToken() {
-  if (cachedSession && cachedSession.expires_at > (Date.now() / 1000) + 60) {
-    return cachedSession.token;
-  }
-
   try {
-    const ghToken = execSync('gh auth token', { encoding: 'utf8' }).trim();
-    const res = await fetch('https://api.github.com/copilot_internal/v2/token', {
-      headers: {
-        'Authorization': `Bearer ${ghToken}`,
-        'Accept': 'application/json',
-      }
-    });
-
-    if (!res.ok) throw new Error(`Failed to get session token: ${res.statusText}`);
-    
-    cachedSession = await res.json();
-    return cachedSession.token;
+    return await resolveCopilotSessionToken();
   } catch (err) {
-    console.error('Error fetching Copilot token:', err.message);
+    console.error('Error obtaining Copilot token:', err.message);
     return null;
   }
 }
@@ -61,12 +48,11 @@ const server = http.createServer(async (req, res) => {
     req.on('end', async () => {
       try {
         const payload = JSON.parse(body);
-        
-        // Map common model names to Copilot equivalents if needed
-        // For now, we pass them through or default to gpt-4o
-        const model = payload.model?.includes('gpt-4o') ? 'gpt-4o' : 
-                      payload.model?.includes('claude-3.5-sonnet') ? 'claude-3.5-sonnet' : 
-                      'gpt-4o';
+
+        // Pass the requested model through unchanged so the caller's selection is
+        // honored; Copilot validates it against the account's available models and
+        // returns a clear error for an unsupported id rather than silently swapping.
+        const model = payload.model || 'gpt-4o';
 
         const copilotRes = await fetch('https://api.githubcopilot.com/chat/completions', {
           method: 'POST',
@@ -75,7 +61,8 @@ const server = http.createServer(async (req, res) => {
             'Content-Type': 'application/json',
             'Accept': 'application/json',
             'X-Github-Api-Version': '2023-07-07',
-            'Editor-Version': 'vscode/1.90.0', // Spoof VS Code for compatibility
+            'Copilot-Integration-Id': 'vscode-chat',
+            'Editor-Version': 'vscode/1.90.0',
           },
           body: JSON.stringify({
             ...payload,

package/lib/capability-ledger.mjs

@@ -0,0 +1,156 @@
+/**
+ * lib/capability-ledger.mjs — behavior-to-test traceability for release-critical surfaces.
+ *
+ * The ledger describes observable product capabilities, not implementation units. A
+ * capability entry identifies the outcome, failure modes, affected paths, fixtures,
+ * and test files that verify it. Validation is deliberately bidirectional: every
+ * listed test must declare the capability id in its source, preventing an unmaintained JSON
+ * entry from claiming coverage when its test source lacks the marker.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const TEST_LAYERS = Object.freeze([
+  'unit',
+  'integration',
+  'functional',
+  'host-emulation',
+  'live-provider',
+  'visual',
+]);
+
+export const CRITICALITIES = Object.freeze(['release', 'important', 'standard']);
+
+function findConstructRoot(startPath = process.cwd()) {
+  let current = path.resolve(startPath);
+  while (true) {
+    if (fs.existsSync(path.join(current, 'package.json')) && fs.existsSync(path.join(current, 'tests'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(startPath);
+    current = parent;
+  }
+}
+
+export function defaultLedgerPath(rootDir = process.cwd()) {
+  return path.join(findConstructRoot(rootDir), 'tests', 'capabilities', 'ledger.json');
+}
+
+export function loadCapabilityLedger({ rootDir } = {}) {
+  const filePath = defaultLedgerPath(rootDir);
+  return { filePath, ledger: JSON.parse(fs.readFileSync(filePath, 'utf8')) };
+}
+
+function hasText(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function hasStringArray(value) {
+  return Array.isArray(value) && value.length > 0 && value.every(hasText);
+}
+
+function testDeclaresCapability(testPath, id) {
+  try {
+    return fs.readFileSync(testPath, 'utf8').includes(`@capability ${id}`);
+  } catch {
+    return false;
+  }
+}
+
+export function validateCapabilityLedger({ rootDir, ledger: suppliedLedger } = {}) {
+  const root = findConstructRoot(rootDir);
+  const loaded = suppliedLedger ? { filePath: null, ledger: suppliedLedger } : loadCapabilityLedger({ rootDir: root });
+  const ledger = loaded.ledger;
+  const errors = [];
+  const warnings = [];
+  const ids = new Set();
+  let mappedTestCount = 0;
+
+  if (ledger?.version !== 1) errors.push('ledger.version must equal 1');
+  if (!Array.isArray(ledger?.capabilities) || ledger.capabilities.length === 0) {
+    errors.push('ledger.capabilities must contain at least one capability');
+  }
+
+  for (const capability of ledger?.capabilities ?? []) {
+    const id = capability?.id;
+    if (!hasText(id) || !/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/.test(id)) {
+      errors.push(`capability has invalid id: ${String(id)}`);
+      continue;
+    }
+    if (ids.has(id)) errors.push(`${id}: duplicate capability id`);
+    ids.add(id);
+
+    if (!hasText(capability.outcome)) errors.push(`${id}: outcome must describe an observable user or system result`);
+    if (!hasStringArray(capability.failureModes)) errors.push(`${id}: failureModes must name at least one failure mode`);
+    if (!hasStringArray(capability.changePaths)) errors.push(`${id}: changePaths must identify affected implementation paths`);
+    if (!CRITICALITIES.includes(capability.criticality)) errors.push(`${id}: criticality must be one of ${CRITICALITIES.join(', ')}`);
+    if (!hasStringArray(capability.assertions)) errors.push(`${id}: assertions must describe observable checks`);
+    if (!Array.isArray(capability.tests) || capability.tests.length === 0) {
+      errors.push(`${id}: tests must contain at least one test reference`);
+      continue;
+    }
+
+    const layers = new Set();
+    for (const test of capability.tests) {
+      const relPath = test?.path;
+      if (!hasText(relPath)) {
+        errors.push(`${id}: test path is required`);
+        continue;
+      }
+      const absolutePath = path.join(root, relPath);
+      if (!fs.existsSync(absolutePath)) errors.push(`${id}: test file does not exist: ${relPath}`);
+      if (!TEST_LAYERS.includes(test?.layer)) errors.push(`${id}: ${relPath} has invalid layer ${String(test?.layer)}`);
+      if (!testDeclaresCapability(absolutePath, id)) errors.push(`${id}: ${relPath} must declare @capability ${id}`);
+      layers.add(test?.layer);
+      mappedTestCount += 1;
+    }
+
+    if (capability.criticality === 'release' && !['functional', 'host-emulation', 'integration', 'visual'].some((layer) => layers.has(layer))) {
+      errors.push(`${id}: release-critical capability needs integration, functional, host-emulation, or visual coverage`);
+    }
+
+    for (const fixture of capability.fixtures ?? []) {
+      if (!hasText(fixture) || !fs.existsSync(path.join(root, fixture))) errors.push(`${id}: fixture does not exist: ${String(fixture)}`);
+    }
+    if (!Array.isArray(capability.fixtures) || capability.fixtures.length === 0) warnings.push(`${id}: no committed fixture declared`);
+  }
+
+  return {
+    filePath: loaded.filePath,
+    capabilityCount: ledger?.capabilities?.length ?? 0,
+    mappedTestCount,
+    errors,
+    warnings,
+    pass: errors.length === 0,
+  };
+}
+
+export function formatCapabilityLedgerAudit(result) {
+  const lines = [
+    'Construct capability ledger audit',
+    '════════════════════════════════',
+    `  Capabilities: ${result.capabilityCount}`,
+    `  Test references: ${result.mappedTestCount}`,
+    '',
+  ];
+  if (result.errors.length) {
+    lines.push(`  ✗ Errors (${result.errors.length}):`);
+    result.errors.forEach((error) => lines.push(`      - ${error}`));
+  } else {
+    lines.push('  ✓ Every mapped test declares its observable capability');
+  }
+  if (result.warnings.length) {
+    lines.push('', `  ⚠ Warnings (${result.warnings.length}):`);
+    result.warnings.forEach((warning) => lines.push(`      - ${warning}`));
+  }
+  lines.push('', result.pass ? '  Result: PASS' : '  Result: FAIL');
+  return `${lines.join('\n')}\n`;
+}
+
+export function runCapabilityLedgerAuditCli(args = [], { rootDir } = {}) {
+  const result = validateCapabilityLedger({ rootDir });
+  if (args.includes('--json')) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else process.stdout.write(formatCapabilityLedgerAudit(result));
+  if (!result.pass) process.exitCode = 1;
+  return result;
+}

package/lib/certification/artifact-fixtures.mjs

@@ -0,0 +1,132 @@
+/**
+ * lib/certification/artifact-fixtures.mjs — golden artifact fixtures per manifest type.
+ *
+ * Builds minimal valid markdown derived from specialists/artifact-manifest.json
+ * structure and visual requirements so release-gate tests can reference stable
+ * fixtures under tests/fixtures/artifacts/<type>/.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { artifactTypes, getArtifactEntry } from '../artifact-manifest.mjs';
+import { validateArtifactRelease } from '../artifact-release-gate.mjs';
+
+function findConstructRoot(startPath = process.cwd()) {
+  let current = path.resolve(startPath);
+  while (true) {
+    if (fs.existsSync(path.join(current, 'package.json')) && fs.existsSync(path.join(current, 'tests'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(startPath);
+    current = parent;
+  }
+}
+
+function proseBlock(label, sentences = 3) {
+  const parts = [];
+  for (let i = 0; i < sentences; i += 1) {
+    parts.push(`This paragraph supports the ${label} section with observable evidence. Source: https://example.com/fixture (accessed 2026-06-22).`);
+  }
+  return parts.join(' ');
+}
+
+function mermaidForDiagram(diagram) {
+  if (diagram === 'sequenceDiagram') {
+    return '```mermaid\nsequenceDiagram\n  Client->>Service: request\n  Service-->>Client: response\n```';
+  }
+  return '```mermaid\nflowchart LR\n  A[Start] --> B[End]\n```';
+}
+
+function tableForColumns(columns) {
+  const header = `| ${columns.join(' | ')} |`;
+  const sep = `| ${columns.map(() => '---').join(' | ')} |`;
+  const row = `| ${columns.map((c) => `${c} value`).join(' | ')} |`;
+  return [header, sep, row].join('\n');
+}
+
+export function goldenFixtureRelPath(type) {
+  return path.join('tests', 'fixtures', 'artifacts', type, 'golden.md');
+}
+
+export function goldenFixturePath(type, { rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  return path.join(root, goldenFixtureRelPath(type));
+}
+
+export function buildGoldenFixtureMarkdown(type, { rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const entry = getArtifactEntry(type, { rootDir: root });
+  if (!entry) throw new Error(`unknown artifact type: ${type}`);
+
+  const lines = [
+    '---',
+    `description: Golden ${type} fixture for artifact release-gate certification tests.`,
+    `cx_fixture_type: ${type}`,
+    `cx_fixture_source: ${entry.template}`,
+    '---',
+    '',
+    `# Golden fixture: ${type}`,
+    '',
+  ];
+
+  const proseMinimum = entry.releaseGate?.proseMinimum ?? 0;
+  let proseAdded = 0;
+
+  for (const section of entry.structureRequirements ?? []) {
+    lines.push(`## ${section}`, '');
+    if (proseAdded < proseMinimum) {
+      lines.push(proseBlock(section));
+      proseAdded += 1;
+    } else {
+      lines.push(`Fixture content for ${section}.`);
+    }
+    lines.push('');
+  }
+
+  for (const visual of entry.visualRequirements ?? []) {
+    if (visual.check === 'artifact-has-mermaid') {
+      lines.push(mermaidForDiagram(visual.diagram ?? 'flowchart'), '');
+    }
+    if (visual.check === 'artifact-table-has-columns' && Array.isArray(visual.columns)) {
+      lines.push(tableForColumns(visual.columns), '');
+    }
+  }
+
+  while (proseAdded < proseMinimum) {
+    lines.push(proseBlock('supplemental'), '');
+    proseAdded += 1;
+  }
+
+  if (entry.releaseGate?.citationLint) {
+    lines.push('## References', '', '- https://example.com/fixture-source (accessed 2026-06-22)', '');
+  }
+
+  return `${lines.join('\n').trim()}\n`;
+}
+
+export function writeGoldenFixtures({ rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const written = [];
+  const failures = [];
+
+  for (const type of artifactTypes({ rootDir: root })) {
+    const rel = goldenFixtureRelPath(type);
+    const abs = path.join(root, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    const markdown = buildGoldenFixtureMarkdown(type, { rootDir: root });
+    fs.writeFileSync(abs, markdown);
+    const validation = validateArtifactRelease({ filePath: abs, type, rootDir: root });
+    if (!validation.ok) failures.push({ type, errors: validation.errors });
+    written.push({ type, path: rel, ok: validation.ok });
+  }
+
+  return { written, failures };
+}
+
+export function listGoldenFixturePaths({ rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  return artifactTypes({ rootDir: root }).map((type) => ({
+    type,
+    path: goldenFixtureRelPath(type),
+    exists: fs.existsSync(goldenFixturePath(type, { rootDir: root })),
+  }));
+}

package/lib/certification/artifact-gates.mjs

@@ -0,0 +1,63 @@
+/**
+ * lib/certification/artifact-gates.mjs — per-type structural and visual certification matrix.
+ *
+ * Validates golden artifact fixtures under tests/fixtures/artifacts/<type>/ against
+ * artifact-manifest release gates (layout, accessibility hints, visual requirements).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { artifactTypes, getArtifactEntry } from '../artifact-manifest.mjs';
+import { validateArtifactRelease } from '../artifact-release-gate.mjs';
+import { goldenFixturePath } from './artifact-fixtures.mjs';
+
+function findConstructRoot(startPath = process.cwd()) {
+  let current = path.resolve(startPath);
+  while (true) {
+    if (fs.existsSync(path.join(current, 'package.json')) && fs.existsSync(path.join(current, 'tests'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(startPath);
+    current = parent;
+  }
+}
+
+export function artifactGateMatrix({ rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  return artifactTypes({ rootDir: root }).map((type) => {
+    const entry = getArtifactEntry(type, { rootDir: root });
+    return {
+      type,
+      structureRequirements: entry?.structureRequirements ?? [],
+      visualRequirements: (entry?.visualRequirements ?? []).map((v) => v.check),
+      releaseGate: entry?.releaseGate ?? {},
+    };
+  });
+}
+
+export function validateAllGoldenArtifactGates({ rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const results = [];
+  const errors = [];
+  for (const type of artifactTypes({ rootDir: root })) {
+    const filePath = goldenFixturePath(type, { rootDir: root });
+    if (!fs.existsSync(filePath)) {
+      errors.push(`missing golden fixture: ${type}`);
+      results.push({ type, pass: false, detail: 'missing fixture' });
+      continue;
+    }
+    const validation = validateArtifactRelease({ filePath, type, rootDir: root });
+    results.push({ type, pass: validation.ok === true, errors: validation.errors ?? [] });
+    if (!validation.ok) errors.push(`${type}: ${validation.errors?.[0] ?? 'gate failed'}`);
+  }
+  return { pass: errors.length === 0, results, errors, matrix: artifactGateMatrix({ rootDir: root }) };
+}
+
+export function writeArtifactGateMatrixDoc({ rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const out = path.join(root, 'tests', 'certification', 'artifacts', 'gate-matrix.json');
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  const payload = { generatedAt: new Date().toISOString(), matrix: artifactGateMatrix({ rootDir: root }) };
+  fs.writeFileSync(out, `${JSON.stringify(payload, null, 2)}\n`);
+  return out;
+}

package/lib/certification/artifact-provenance.mjs

@@ -0,0 +1,97 @@
+/**
+ * lib/certification/artifact-provenance.mjs — provenance and accessibility certification.
+ *
+ * Validates golden artifact fixtures for cx_doc_id / fixture provenance stamps and
+ * WCAG-oriented structure (heading order, alt-text placeholders on visual types).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { artifactTypes } from '../artifact-manifest.mjs';
+import { goldenFixturePath } from './artifact-fixtures.mjs';
+import { splitFrontmatter } from '../specialists/prompt-schema.mjs';
+
+const RELEASE_CRITICAL_TYPES = new Set(['prd', 'adr', 'rfc', 'threat-model', 'security-review']);
+
+function findConstructRoot(startPath = process.cwd()) {
+  let current = path.resolve(startPath);
+  while (true) {
+    if (fs.existsSync(path.join(current, 'package.json'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(startPath);
+    current = parent;
+  }
+}
+
+function hasProvenanceStamp(frontmatter, body) {
+  if (frontmatter?.cx_doc_id) return true;
+  if (frontmatter?.cx_fixture_type) return true;
+  if (frontmatter?.cx_fixture_source) return true;
+  if (/\bcx_doc_id:/i.test(body.slice(0, 500))) return true;
+  return false;
+}
+
+function headingLevel(line) {
+  const m = /^(#{1,6})\s/.exec(line.trim());
+  return m ? m[1].length : null;
+}
+
+function validateHeadingStructure(body) {
+  const errors = [];
+  const levels = body.split('\n').map(headingLevel).filter((l) => l != null);
+  if (!levels.includes(1)) errors.push('missing h1 (# heading)');
+  let prev = 0;
+  for (const level of levels) {
+    if (prev > 0 && level > prev + 1) {
+      errors.push(`heading skip: h${prev} → h${level}`);
+      break;
+    }
+    prev = level;
+  }
+  return errors;
+}
+
+function validateAltPlaceholders(body, type) {
+  if (!['prd', 'architecture-overview', 'system-design'].includes(type)) return [];
+  const hasImage = /!\[[^\]]*\]\([^)]+\)/.test(body);
+  const hasPlaceholder = /alt\s*text|describe the (image|diagram)|\[alt:/i.test(body);
+  if (hasImage && !hasPlaceholder) {
+    return ['image without alt-text placeholder guidance'];
+  }
+  return [];
+}
+
+export function validateArtifactProvenance(type, { rootDir, strict = true } = {}) {
+  const root = findConstructRoot(rootDir);
+  const filePath = goldenFixturePath(type, { rootDir: root });
+  const errors = [];
+
+  if (!fs.existsSync(filePath)) {
+    return { type, pass: false, errors: [`missing golden fixture: ${type}`] };
+  }
+
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const { frontmatter, body } = splitFrontmatter(raw);
+
+  if (!hasProvenanceStamp(frontmatter, body)) {
+    errors.push(`${type}: missing provenance stamp (cx_doc_id or cx_fixture_*)`);
+  }
+
+  errors.push(...validateHeadingStructure(body).map((e) => `${type}: ${e}`));
+  errors.push(...validateAltPlaceholders(body, type).map((e) => `${type}: ${e}`));
+
+  const blocking = strict && RELEASE_CRITICAL_TYPES.has(type) && errors.length > 0;
+  return { type, pass: errors.length === 0, blocking, errors };
+}
+
+export function validateAllArtifactProvenance({ rootDir, strict = true } = {}) {
+  const results = [];
+  const errors = [];
+  for (const type of artifactTypes({ rootDir: findConstructRoot(rootDir) })) {
+    const result = validateArtifactProvenance(type, { rootDir, strict });
+    results.push(result);
+    if (!result.pass) errors.push(...result.errors);
+  }
+  return { pass: errors.length === 0, strict, results, errors };
+}

package/lib/certification/canonical-scenarios.mjs

@@ -0,0 +1,78 @@
+/**
+ * lib/certification/canonical-scenarios.mjs — versioned canonical demo scenario catalog.
+ *
+ * Loads tests/certification/demos/canonical-scenarios.json and validates that
+ * cited tape and theme paths exist under templates/demos/.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+function findConstructRoot(startPath = process.cwd()) {
+  let current = path.resolve(startPath);
+  while (true) {
+    if (fs.existsSync(path.join(current, 'package.json')) && fs.existsSync(path.join(current, 'tests'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(startPath);
+    current = parent;
+  }
+}
+
+export const CANONICAL_DEMO_SCHEMA = 'construct/certification/canonical-demos/1';
+
+export function defaultCanonicalScenariosPath(rootDir = process.cwd()) {
+  return path.join(findConstructRoot(rootDir), 'tests', 'certification', 'demos', 'canonical-scenarios.json');
+}
+
+export function loadCanonicalScenarios({ rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const filePath = defaultCanonicalScenariosPath(root);
+  const catalog = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  return { root, filePath, catalog };
+}
+
+export function validateCanonicalScenarios({ rootDir, catalog: supplied } = {}) {
+  const root = findConstructRoot(rootDir);
+  const catalog = supplied ?? JSON.parse(fs.readFileSync(defaultCanonicalScenariosPath(root), 'utf8'));
+  const errors = [];
+
+  if (catalog.version !== 1) errors.push('canonical-scenarios.version must equal 1');
+  if (catalog.schema !== CANONICAL_DEMO_SCHEMA) errors.push(`canonical-scenarios.schema must equal ${CANONICAL_DEMO_SCHEMA}`);
+  if (!Array.isArray(catalog.demos) || catalog.demos.length < 2) errors.push('canonical-scenarios.demos must contain at least two entries');
+
+  const ids = new Set();
+  for (const demo of catalog.demos ?? []) {
+    if (!demo.id || typeof demo.id !== 'string') {
+      errors.push('demo entry missing id');
+      continue;
+    }
+    if (ids.has(demo.id)) errors.push(`${demo.id}: duplicate demo id`);
+    ids.add(demo.id);
+
+    const tape = demo.tape ?? demo.tapePath;
+    if (!tape) errors.push(`${demo.id}: tape path is required`);
+    else if (!fs.existsSync(path.join(root, tape))) errors.push(`${demo.id}: tape does not exist: ${tape}`);
+
+    for (const ref of demo.references ?? []) {
+      if (!fs.existsSync(path.join(root, ref))) errors.push(`${demo.id}: reference does not exist: ${ref}`);
+    }
+    if (demo.vhsTheme && !fs.existsSync(path.join(root, demo.vhsTheme))) {
+      errors.push(`${demo.id}: vhsTheme does not exist: ${demo.vhsTheme}`);
+    }
+    if (demo.script && !fs.existsSync(path.join(root, demo.script))) {
+      errors.push(`${demo.id}: script does not exist: ${demo.script}`);
+    }
+  }
+
+  const required = ['agentic-platforms-prd', 'construct-cockpit'];
+  for (const id of required) {
+    if (!ids.has(id)) errors.push(`required demo missing: ${id}`);
+  }
+
+  return {
+    filePath: defaultCanonicalScenariosPath(root),
+    demoCount: catalog.demos?.length ?? 0,
+    errors,
+    pass: errors.length === 0,
+  };
+}