@geraldmaron/construct 1.2.3 → 1.3.0

package/lib/audit-rules.mjs

@@ -11,7 +11,7 @@
  *      concern; here they mark the rule as intentionally scoped, not an orphan.
  *   2. REFERENCED — the canonical `rules/<dir>/<name>` path token (with or without
  *      the .md) appears somewhere in the active surface (personas, CLAUDE.md,
- *      skills, all of lib/ except the minified dashboard bundles, registry/
+ *      skills, all of lib/, registry/
  *      contracts, other rules, scripts, the CLI).
  * A rule that is neither glob-activated nor referenced is a true orphan — a
  * pruning candidate. A rule's own file never counts as referencing itself.
@@ -30,9 +30,7 @@ const SURFACE_DIRS = ['personas', 'skills', 'rules', 'lib', 'specialists', 'scri
 const SURFACE_FILES = ['CLAUDE.md', 'AGENTS.md', 'bin/construct', 'claude/settings.template.json'];
 const TEXT_EXT = new Set(['.md', '.mjs', '.js', '.json', '.txt', '.mdx']);
 
-// The minified Next.js dashboard bundles contain unrelated "rules/" tokens (the
-// markdown lexer's own grammar) that would read as false references.
-const SURFACE_SKIP = ['lib/server/static'];
+const SURFACE_SKIP = [];
 
 function isSkipped(full, root) {
   const rel = path.relative(root, full);

package/lib/audit-skills.mjs

@@ -6,18 +6,19 @@
  * Called by 'construct audit skills' and incorporated into 'construct doctor'.
  *
  * A `roles/<base>[.<flavor>]` skill is owned when `<base>` is a specialist OR a role
- * named in any profile (profiles/*.json) — a role skill loads when its specialist or
+ * named in any curated scope (specialists/org/scopes) — a role skill loads when its specialist or
  * profile role runs, even without a direct registry `skills:` binding. Counting only
  * registry bindings over-reported orphans (it missed profile roles like `operator`
  * from operations.json and conditional specialist flavors); see bead construct-ksfa.
  */
 import fs from 'node:fs';
+import { loadRegistry } from './registry/loader.mjs';
 import path from 'node:path';
 
 function findConstructRoot(startPath = process.cwd()) {
   let current = path.resolve(startPath);
   while (true) {
-    if (fs.existsSync(path.join(current, 'specialists', 'registry.json'))) return current;
+    if (fs.existsSync(path.join(current, 'specialists', 'org'))) return current;
     const parent = path.dirname(current);
     if (parent === current) return path.resolve(startPath);
     current = parent;
@@ -40,23 +41,18 @@ function collectSkillFiles(skillsDir) {
   return results;
 }
 
-// Collect every role name a profile declares — top-level `roles` and nested
-// `departments[].roles` — so a role skill counts as owned when a profile uses its
-// base even if no specialist declares the skill path directly.
+import { collectScopeRoleIds } from './scopes/enrich.mjs';
+
 function collectProfileRoles(root) {
-  const dir = path.join(root, 'profiles');
+  const dir = path.join(root, 'specialists', 'org', 'scopes');
   const roles = new Set();
-  const scan = (node) => {
-    if (Array.isArray(node)) { node.forEach(scan); return; }
-    if (node && typeof node === 'object') {
-      if (Array.isArray(node.roles)) for (const r of node.roles) if (typeof r === 'string') roles.add(r);
-      for (const v of Object.values(node)) scan(v);
-    }
-  };
   try {
     for (const f of fs.readdirSync(dir)) {
       if (!f.endsWith('.json')) continue;
-      try { scan(JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'))); } catch { /* skip malformed */ }
+      try {
+        const raw = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'));
+        for (const r of collectScopeRoleIds(raw, { rootDir: root })) roles.add(r);
+      } catch { /* skip malformed */ }
     }
   } catch { /* no profiles dir */ }
   return roles;
@@ -70,17 +66,16 @@ function roleBase(skill) {
 
 export function auditSkills({ rootDir, silent = false } = {}) {
   const root = rootDir ?? findConstructRoot();
-  const registryPath = path.join(root, 'specialists', 'registry.json');
   const skillsDir = path.join(root, 'skills');
 
-  const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+  const registry = loadRegistry({ rootDir: root });
   const allSkillFiles = collectSkillFiles(skillsDir);
 
   const declaredSkills = new Set();
   const agentsWithNoSkills = [];
   const missingSkillFiles = [];
 
-  for (const agent of registry.specialists ?? []) {
+  for (const agent of Object.values(registry.specialists ?? {})) {
     const skills = agent.skills ?? [];
     if (skills.length === 0) {
       agentsWithNoSkills.push(agent.name);
@@ -93,12 +88,17 @@ export function auditSkills({ rootDir, silent = false } = {}) {
     }
   }
 
-  // Owning role bases = specialist names (registry) ∪ profile role names. A role
-  // skill is owned when its base is in this set, even without a direct binding.
+  // Owning role bases = specialist names, scope/org roles, and role-skill bases declared on specialists.
   const ownerBases = new Set([
-    ...(registry.specialists ?? []).map((a) => a.name.replace(/^cx-/, '')),
+    ...Object.values(registry.specialists ?? {}).map((a) => a.name.replace(/^cx-/, '')),
     ...collectProfileRoles(root),
   ]);
+  for (const agent of Object.values(registry.specialists ?? {})) {
+    for (const skill of agent.skills ?? []) {
+      const base = roleBase(skill);
+      if (base) ownerBases.add(base);
+    }
+  }
   const isOwned = (s) => declaredSkills.has(s) || (ownerBases.has(roleBase(s)));
 
   const orphanSkills = [...allSkillFiles].filter((s) => !isOwned(s));
@@ -159,6 +159,18 @@ export async function runAuditSkillsCli(args = []) {
     const { runSkillInventoryAuditCli } = await import('./certification/skill-inventory.mjs');
     return runSkillInventoryAuditCli(args.filter((a) => a !== '--inventory'), { rootDir });
   }
+  if (args.includes('--composition')) {
+    const { auditSkillComposition } = await import('./skills/composition-graph.mjs');
+    const result = auditSkillComposition({ rootDir });
+    if (args.includes('--json')) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    else {
+      process.stdout.write(`Skill composition: ${result.stats.onDisk} on disk, ${result.blocking.length} blocking\n`);
+      for (const b of result.blocking) process.stderr.write(`  ✗ ${b}\n`);
+      process.stdout.write(result.pass ? '  Result: PASS\n' : '  Result: FAIL\n');
+    }
+    if (!result.pass) process.exit(1);
+    return result;
+  }
   const result = auditSkills({ rootDir });
   if (!result.pass) process.exit(1);
 }

package/lib/audit-specialists.mjs

@@ -7,6 +7,7 @@
  */
 
 import fs from 'node:fs';
+import { loadRegistry } from './registry/loader.mjs';
 import path from 'node:path';
 import { auditSkills } from './audit-skills.mjs';
 import { loadArtifactManifest } from './artifact-manifest.mjs';
@@ -17,14 +18,14 @@ import { validateAllRoleOverlays } from './certification/role-overlays.mjs';
 import { ROLE_DIRECTIVE_RE } from './role-preload.mjs';
 
 function findConstructRoot(startPath = process.cwd()) {
-  let current = path.resolve(startPath);
-  while (true) {
-    if (fs.existsSync(path.join(current, 'specialists', 'registry.json'))) return current;
-    const parent = path.dirname(current);
-    if (parent === current) return path.resolve(startPath);
-    current = parent;
-  }
-}
+   let current = path.resolve(startPath);
+   while (true) {
+     if (fs.existsSync(path.join(current, 'specialists', 'org'))) return current;
+     const parent = path.dirname(current);
+     if (parent === current) return path.resolve(startPath);
+     current = parent;
+   }
+ }
 
 function readJson(p) {
   return JSON.parse(fs.readFileSync(p, 'utf8'));
@@ -85,7 +86,7 @@ function crossChecks({ registry, manifest, skillAudit, allSkills, contractDocTyp
   const issues = [];
   const manifestTypes = new Set(Object.keys(manifest.artifacts ?? {}));
 
-  for (const agent of registry.specialists ?? []) {
+  for (const agent of Object.values(registry.specialists ?? {})) {
     for (const skill of agent.skills ?? []) {
       if (!allSkills.includes(skill)) {
         issues.push({ kind: 'missing-skill-file', agent: agent.name, skill });
@@ -114,24 +115,41 @@ function crossChecks({ registry, manifest, skillAudit, allSkills, contractDocTyp
 }
 
 export function auditSpecialists({ rootDir, silent = false } = {}) {
-  const root = rootDir ?? findConstructRoot();
-  const registry = readJson(path.join(root, 'specialists', 'registry.json'));
-  const contractsDoc = readJson(path.join(root, 'specialists', 'contracts.json'));
-  const enrichments = readJson(path.join(root, 'specialists', 'audit-enrichments.json'));
-  const manifest = loadArtifactManifest({ rootDir: root });
-  const skillAudit = auditSkills({ rootDir: root, silent: true });
-  const allSkills = collectSkillFiles(path.join(root, 'skills'));
-  const contractDocTypes = docTypesFromContracts(contractsDoc.contracts ?? []);
-  const crossCheckIssues = crossChecks({ registry, manifest, skillAudit, allSkills, contractDocTypes });
+   const root = rootDir ?? findConstructRoot();
+
+   const unifiedRegistry = loadRegistry({ rootDir: root });
+   
+   // Convert unified registry to legacy registry shape for compatibility
+   const registry = {
+     specialists: Object.entries(unifiedRegistry.specialists || {}).map(([id, spec]) => ({
+       name: spec.name,
+       displayName: spec.displayName,
+       description: spec.description,
+       team: spec.team,
+       role: spec.role,
+       skills: spec.skills,
+       promptFile: spec.promptFile,
+       docArtifacts: spec.docArtifacts,
+       ...spec
+     }))
+   };
+   
+   const contractsDoc = { contracts: Object.values(unifiedRegistry.contracts || {}) };
+   const enrichments = readJson(path.join(root, 'specialists', 'audit-enrichments.json'));
+   const manifest = loadArtifactManifest({ rootDir: root });
+   const skillAudit = auditSkills({ rootDir: root, silent: true });
+   const allSkills = collectSkillFiles(path.join(root, 'skills'));
+   const contractDocTypes = docTypesFromContracts(contractsDoc.contracts ?? []);
+   const crossCheckIssues = crossChecks({ registry, manifest, skillAudit, allSkills, contractDocTypes });
 
-  const specialists = (registry.specialists ?? []).map((agent) => {
-    const promptPath = agent.promptFile
-      ? path.join(root, agent.promptFile)
-      : null;
-    const meta = enrichments.specialists?.[agent.name] ?? {};
-    const perspective = resolvePerspectiveFromPrompt(agent.name, { rootDir: root, registry });
-    return {
-      name: agent.name,
+   const specialists = Object.values(registry.specialists ?? {}).map((agent) => {
+     const promptPath = agent.promptFile
+       ? path.join(root, agent.promptFile)
+       : null;
+     const meta = enrichments.specialists?.[agent.name] ?? {};
+     const perspective = resolvePerspectiveFromPrompt(agent.name, { rootDir: root, registry });
+     return {
+       name: agent.name,
       id: `cx-${agent.name}`,
       humanEquivalent: meta.humanEquivalent ?? 'unknown',
       primaryOutputs: agent.docArtifacts ?? [],

package/lib/auto-docs.mjs

@@ -15,6 +15,7 @@
  */
 
 import fs from 'node:fs';
+import { loadRegistry } from './registry/loader.mjs';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
 
@@ -90,7 +91,7 @@ function buildCoreDocsContract() {
 }
 
 const DIR_DESCRIPTIONS = {
-  apps: 'User-facing apps shipped from this repo (chat, dashboard, docs)',
+  apps: 'User-facing apps shipped from this repo (dashboard, docs)',
   bin: 'CLI entrypoint (`construct`)',
   commands: 'Command prompt assets',
   config: 'Repo-wide controlled vocabulary (tag-vocabulary.json)',
@@ -165,13 +166,13 @@ function buildHooksTable(rootDir) {
 }
 
 function buildAgentsTable(rootDir) {
-  const registryPath = path.join(rootDir, 'specialists', 'registry.json');
+  const registryPath = path.join(rootDir, 'specialists', 'org');
   let registry;
   try { registry = JSON.parse(fs.readFileSync(registryPath, 'utf8')); } catch { return ''; }
 
   const agents = [
     ...(registry.orchestrator ? [{ ...registry.orchestrator, name: registry.orchestrator.name }] : []),
-    ...(registry.specialists ?? []),
+    ...Object.values(registry.specialists ?? {}),
   ];
   if (!agents.length) return '';
 
@@ -410,10 +411,10 @@ function renderAgentsPage(rootDir) {
   return [
     '---',
     'title: Specialists',
-    'description: The 28 specialists behind the construct persona. Generated from specialists/registry.json.',
+    'description: The 28 specialists behind the construct persona. Generated from specialists/org.',
     '---',
     '',
-    '> Generated from `specialists/registry.json`. Re-run `construct docs:site` to refresh.',
+    '> Generated from `specialists/org`. Re-run `construct docs:site` to refresh.',
     '',
     'Construct ships one persona (`construct`) and 28 specialists behind it. You address `@construct` for all everyday work; it routes to specialists internally. Each specialist has a role, model tier, and prompt file that defines its decision authority.',
     '',

package/lib/brand-prose.mjs

@@ -15,10 +15,10 @@ export const RETIRED_FONT_RE =
   /Plus\s+Jakarta|PlusJakarta|Geist(?:Mono)?|IBM\s+Plex|Libertinus|font-family:\s*["']?Inter["']?/i;
 
 const CLI_SUBCOMMANDS =
-  'doctor|init|sync|dev|stop|status|intake|chat|install|drop|search|prune|upgrade|config|list|graph|beads|export|publish|artifact|demo|oracle|ci|acp|profile|models|uninstall|reconcile|embed|ingest|classify|workflow|capability';
+  'doctor|init|sync|dev|stop|status|intake|install|drop|search|prune|upgrade|config|list|graph|beads|export|publish|artifact|demo|oracle|ci|acp|profile|models|uninstall|reconcile|embed|ingest|classify|workflow|capability';
 
 const PRODUCT_NOUN_PHRASES =
-  /\bConstruct (?:install|MCP server|MCP tools?|workflow|chat|package|repo|surfaces?|integration|orchestrator|daemon|specialists?|persona|brand|tooling|standards|config|adapters?|platform|version|release|hooks?|memory|loop|Dashboard|Chat|capability)\b/i;
+  /\bConstruct (?:install|MCP server|MCP tools?|workflow|package|repo|surfaces?|integration|orchestrator|daemon|specialists?|persona|brand|tooling|standards|config|adapters?|platform|version|release|hooks?|memory|loop|Dashboard|capability)\b/i;
 
 const UNBACKTICKED_CLI_RE = new RegExp(
   `(?<![\`~/])construct\\s+(${CLI_SUBCOMMANDS})(?:\\s+[\\w:-]+)*\\b`,
@@ -40,7 +40,7 @@ const DOC_EXEMPT =
   /(?:^|\/)(docs\/STYLE\.md|docs\/guides\/reference\/branding\.md|templates\/distribution\/fonts\/README\.md)$/;
 
 const HOOK_SCOPED =
-  /^(docs\/|skills\/|specialists\/|personas\/|templates\/|rules\/|apps\/(dashboard|docs|chat)\/)/;
+  /^(docs\/|skills\/|specialists\/|personas\/|templates\/|rules\/|apps\/(dashboard|docs)\/)/;
 
 export function isBrandHookPath(relPath) {
   if (!relPath || EXCLUDE_PATH.test(relPath) || DOC_EXEMPT.test(relPath)) return false;

package/lib/brand-tokens.mjs

@@ -2,8 +2,8 @@
  * lib/brand-tokens.mjs — Construct distribution brand primitives.
  *
  * Monochrome ink ramp from templates/distribution/construct-brand.typ plus Space
- * Grotesk / JetBrains Mono typography. INK/FONTS/STATUS feed chat surfaces;
- * BRAND_TOKENS feed publish exports, deck HTML, and PPTX.
+ * Grotesk / JetBrains Mono typography. BRAND_TOKENS feed publish exports,
+ * deck HTML, and PPTX.
  */
 
 export const INK = Object.freeze({

package/lib/certification/artifact-fixtures.mjs

@@ -73,7 +73,10 @@ export function buildGoldenFixtureMarkdown(type, { rootDir } = {}) {
 
   for (const section of entry.structureRequirements ?? []) {
     lines.push(`## ${section}`, '');
-    if (proseAdded < proseMinimum) {
+    if (section === 'Phases' && type === 'prd') {
+      lines.push('### Phase 1: Fixture delivery', '', '- **Goal**: Ship an isolated billing ledger per tenant.', '- **Status**: not started', '', '**Functional**', '', '- **FR-1.1**: Each tenant invoice derives only from that tenant ledger events.', '  - *Acceptance*: Reconciliation test passes without cross-tenant reads.', '');
+      proseAdded += 1;
+    } else if (proseAdded < proseMinimum) {
       lines.push(proseBlock(section));
       proseAdded += 1;
     } else {

package/lib/certification/demo-parity.mjs

@@ -1,9 +1,9 @@
 /**
- * lib/certification/demo-parity.mjs — cross-surface demo parity report generator.
+ * lib/certification/demo-parity.mjs — demo terminal-harness report generator.
  *
- * Compares Tauri, web cockpit, and VHS terminal harness markers for each canonical
- * demo. Mismatches are recorded for follow-up beads; acceptable divergences cite
- * platform constraints with evidence paths.
+ * Verifies each canonical demo ships a VHS terminal tape. Terminal is the sole
+ * guided demo surface after web-deprecation retired the desktop window and web cockpit;
+ * acceptable divergences cite platform constraints with evidence paths.
  */
 
 import fs from 'node:fs';
@@ -12,26 +12,6 @@ import path from 'node:path';
 import { loadCanonicalScenarios } from './canonical-scenarios.mjs';
 
 const SURFACE_MARKERS = Object.freeze({
-  tauri: {
-    label: 'Tauri desktop',
-    probe: (root, demo) => {
-      const launcher = path.join(root, 'tests/functional/chat-desktop-launcher.functional.test.mjs');
-      if (!fs.existsSync(launcher)) return { ok: false, detail: 'missing desktop launcher test' };
-      const src = fs.readFileSync(launcher, 'utf8');
-      return { ok: /surface=desktop/.test(src), detail: launcher };
-    },
-  },
-  web: {
-    label: 'Web cockpit',
-    probe: (root, demo) => {
-      const routeStrip = path.join(root, 'apps/chat/web/components/route-strip.tsx');
-      const tokens = path.join(root, 'apps/chat/web/theme/tokens.css');
-      if (!fs.existsSync(routeStrip) || !fs.existsSync(tokens)) {
-        return { ok: false, detail: 'missing web cockpit markers' };
-      }
-      return { ok: true, detail: routeStrip };
-    },
-  },
   terminal: {
     label: 'VHS terminal',
     probe: (root, demo) => {
@@ -45,15 +25,9 @@ const SURFACE_MARKERS = Object.freeze({
 
 const ACCEPTABLE_DIVERGENCES = Object.freeze([
   {
-    id: 'tauri-native-chrome',
-    surface: 'tauri',
-    reason: 'Desktop shell uses native window chrome; web uses browser viewport.',
-    evidence: 'apps/chat/desktop/',
-  },
-  {
-    id: 'vhs-terminal-only',
+    id: 'vhs-tape-direct',
     surface: 'terminal',
-    reason: 'VHS tapes assert terminal UX; Tauri/web use GUI interaction models.',
+    reason: 'VHS tapes assert the scripted terminal recording directly.',
     evidence: 'templates/demos/tapes/',
   },
 ]);

package/lib/certification/real-llm-scenarios.mjs

@@ -34,9 +34,10 @@ export function realLlmOptInEnabled(env = process.env) {
 }
 
 export function realLlmCredentialsPresent(env = process.env) {
-  return hasSecret('OPENROUTER_API_KEY', { env })
-    || hasSecret('ANTHROPIC_API_KEY', { env })
-    || hasSecret('OPENAI_API_KEY', { env })
+  const allowAmbient = env === process.env;
+  return hasSecret('OPENROUTER_API_KEY', { env, allowAmbient })
+    || hasSecret('ANTHROPIC_API_KEY', { env, allowAmbient })
+    || hasSecret('OPENAI_API_KEY', { env, allowAmbient })
     || hasStoredCredential();
 }
 
@@ -51,25 +52,26 @@ export function realLlmSkipReason(env = process.env) {
 }
 
 export function resolveRealLlmProvider(env = process.env) {
+  const allowAmbient = env === process.env;
   const requested = (env[REAL_LLM_PROVIDER_ENV] || DEFAULT_REAL_LLM_PROVIDER).trim().toLowerCase();
   const modelOverride = env[REAL_LLM_MODEL_ENV]?.trim() || null;
 
   if (requested === 'openrouter') {
-    if (!hasSecret('OPENROUTER_API_KEY', { env })) {
+    if (!hasSecret('OPENROUTER_API_KEY', { env, allowAmbient })) {
       return { skip: 'OPENROUTER_API_KEY required for OpenRouter real-LLM scenarios' };
     }
     return { provider: 'openrouter', model: modelOverride || DEFAULT_REAL_LLM_MODEL };
   }
 
   if (requested === 'anthropic') {
-    if (!hasSecret('ANTHROPIC_API_KEY', { env })) {
+    if (!hasSecret('ANTHROPIC_API_KEY', { env, allowAmbient })) {
       return { skip: 'ANTHROPIC_API_KEY required for Anthropic real-LLM scenarios' };
     }
     return { provider: 'anthropic', model: modelOverride || 'claude-sonnet-4-20250514' };
   }
 
   if (requested === 'openai') {
-    if (!hasSecret('OPENAI_API_KEY', { env })) {
+    if (!hasSecret('OPENAI_API_KEY', { env, allowAmbient })) {
       return { skip: 'OPENAI_API_KEY required for OpenAI real-LLM scenarios' };
     }
     return { provider: 'openai', model: modelOverride || 'gpt-4o-mini' };
@@ -125,7 +127,9 @@ export function buildPrdPolishMessages({ requestSummary = S3_REQUEST, specialist
   const system = [
     'You are cx-product-manager synthesizing a multi-specialist orchestration run into one release-quality PRD markdown file.',
     'Output markdown only — no preamble.',
-    'Required ## sections (exact headings): Problem, Goals, Success metrics, Risks and mitigations.',
+    'Required ## sections (exact headings): Problem, Goals, Success metrics, Phases, Risks and mitigations.',
+    'Under Phases include at least one phase with **FR-<phase>.<n>:** functional requirements and *Acceptance:* criteria per requirement.',
+    'You may instead use ## Requirements (or Functional requirements) and ## Acceptance criteria when requirements are not phased inline.',
     'Under Problem and Goals write multi-sentence paragraphs (not bullet-only outlines).',
     'Include a ```mermaid flowchart``` diagram for the user flow.',
     'Include a markdown table with columns: Metric | Baseline | Target (header row required).',
@@ -140,6 +144,50 @@ function resolvePolishModel(env = process.env) {
   return env[REAL_LLM_POLISH_MODEL_ENV]?.trim() || DEFAULT_REAL_LLM_POLISH_MODEL;
 }
 
+export const S3_QUALITY_THRESHOLDS = Object.freeze({ minProse: 2, minCitations: 1 });
+
+export function formatArtifactQualityVerdictDetail(
+  verdict,
+  { minProse = S3_QUALITY_THRESHOLDS.minProse, minCitations = S3_QUALITY_THRESHOLDS.minCitations } = {},
+) {
+  if (!verdict || typeof verdict !== 'object') {
+    return 'quality gate not met after polish';
+  }
+  const structurePart = verdict.structure?.ok
+    ? 'structure: ok'
+    : `structure: fail (${(verdict.structure?.errors ?? []).join('; ') || 'unknown'})`;
+  const prosePart = `prose: ${verdict.prose?.paragraphs ?? 0}/${minProse} (${verdict.prose?.ok ? 'ok' : 'fail'})`;
+  const researchPart = `research: citations=${verdict.research?.citations ?? 0}/${minCitations} unverified=${Boolean(verdict.research?.unverifiedDiscipline)} (${verdict.research?.ok ? 'ok' : 'fail'})`;
+  return `quality gate not met after polish; ${structurePart}; ${prosePart}; ${researchPart}`;
+}
+
+export function buildS3QualityGateFailure({
+  verdict,
+  polishModel = null,
+  rawOutputLength = null,
+  thresholds = S3_QUALITY_THRESHOLDS,
+} = {}) {
+  return {
+    scenarioId: 'real-llm.s3',
+    status: 'inconclusive',
+    detail: formatArtifactQualityVerdictDetail(verdict, thresholds),
+    verdict,
+    qualityThresholds: thresholds,
+    polishModel,
+    rawOutputLength,
+  };
+}
+
+export function redactRealLlmGateEvidence(result) {
+  if (!result?.verdict) return null;
+  return JSON.stringify({
+    artifactQuality: result.verdict,
+    qualityThresholds: result.qualityThresholds ?? S3_QUALITY_THRESHOLDS,
+    polishModel: result.polishModel ?? null,
+    rawOutputLength: result.rawOutputLength ?? null,
+  });
+}
+
 async function polishSpecialistOutputsToPrd({ specialistOutputs, requestSummary, env, fetchImpl = globalThis.fetch }) {
   if (!hasSecret('OPENROUTER_API_KEY', { env })) {
     return { skip: 'OPENROUTER_API_KEY required for PRD polish synthesis' };
@@ -230,16 +278,13 @@ export async function runRealLlmS3({ env = process.env, cleanup = true } = {}) {
 
     const prdPath = join(cwd, 'prd-output.md');
     writeFileSync(prdPath, polished.text);
-    const verdict = assessArtifactQuality(prdPath, 'prd', { minProse: 2, minCitations: 1 });
+    const verdict = assessArtifactQuality(prdPath, 'prd', S3_QUALITY_THRESHOLDS);
     if (!verdict.ok) {
-      return {
-        scenarioId: 'real-llm.s3',
-        status: 'inconclusive',
-        detail: 'quality gate not met after polish',
+      return buildS3QualityGateFailure({
         verdict,
         polishModel: polished.polishModel,
         rawOutputLength: rawLongest.length,
-      };
+      });
     }
     return {
       scenarioId: 'real-llm.s3',

package/lib/certification/role-cards.mjs

@@ -7,6 +7,7 @@
  */
 
 import fs from 'node:fs';
+import { loadRegistry } from '../registry/loader.mjs';
 import path from 'node:path';
 
 import { splitFrontmatter } from '../specialists/prompt-schema.mjs';
@@ -14,7 +15,7 @@ import { splitFrontmatter } from '../specialists/prompt-schema.mjs';
 function findConstructRoot(startPath = process.cwd()) {
   let current = path.resolve(startPath);
   while (true) {
-    if (fs.existsSync(path.join(current, 'specialists', 'registry.json'))) return current;
+    if (fs.existsSync(path.join(current, 'specialists', 'org'))) return current;
     const parent = path.dirname(current);
     if (parent === current) return path.resolve(startPath);
     current = parent;
@@ -60,7 +61,7 @@ export function buildRoleCard(agent, { rootDir } = {}) {
     refusalBoundaries,
     modelTier: agent.modelTier ?? null,
     sources: {
-      registry: 'specialists/registry.json',
+      registry: 'specialists/org',
       promptFile: agent.promptFile ?? null,
     },
   };
@@ -68,11 +69,11 @@ export function buildRoleCard(agent, { rootDir } = {}) {
 
 export function writeRoleCards({ rootDir } = {}) {
   const root = findConstructRoot(rootDir);
-  const registry = JSON.parse(fs.readFileSync(path.join(root, 'specialists', 'registry.json'), 'utf8'));
+  const registry = loadRegistry({ rootDir: root });
   const dir = roleCardsDir(root);
   fs.mkdirSync(dir, { recursive: true });
   const written = [];
-  for (const agent of registry.specialists ?? []) {
+  for (const agent of Object.values(registry.specialists ?? {})) {
     const card = buildRoleCard(agent, { rootDir: root });
     const file = path.join(dir, `${card.specialistId}.role-card.json`);
     fs.writeFileSync(file, `${JSON.stringify(card, null, 2)}\n`);
@@ -83,10 +84,10 @@ export function writeRoleCards({ rootDir } = {}) {
 
 export function validateRoleCards({ rootDir } = {}) {
   const root = findConstructRoot(rootDir);
-  const registry = JSON.parse(fs.readFileSync(path.join(root, 'specialists', 'registry.json'), 'utf8'));
+  const registry = loadRegistry({ rootDir: root });
   const errors = [];
   const cards = [];
-  for (const agent of registry.specialists ?? []) {
+  for (const agent of Object.values(registry.specialists ?? {})) {
     const specialistId = `cx-${agent.name}`;
     const file = path.join(roleCardsDir(root), `${specialistId}.role-card.json`);
     if (!fs.existsSync(file)) {

package/lib/certification/role-overlays.mjs

@@ -6,6 +6,7 @@
  */
 
 import fs from 'node:fs';
+import { loadRegistry } from '../registry/loader.mjs';
 import path from 'node:path';
 
 import { splitFrontmatter } from '../specialists/prompt-schema.mjs';
@@ -21,7 +22,7 @@ const OVERLAY_CLASSES = Object.freeze({
 function findConstructRoot(startPath = process.cwd()) {
   let current = path.resolve(startPath);
   while (true) {
-    if (fs.existsSync(path.join(current, 'specialists', 'registry.json'))) return current;
+    if (fs.existsSync(path.join(current, 'specialists', 'org'))) return current;
     const parent = path.dirname(current);
     if (parent === current) return path.resolve(startPath);
     current = parent;
@@ -29,12 +30,11 @@ function findConstructRoot(startPath = process.cwd()) {
 }
 
 function readRegistry(rootDir) {
-  const file = path.join(findConstructRoot(rootDir), 'specialists', 'registry.json');
-  return JSON.parse(fs.readFileSync(file, 'utf8'));
+  return loadRegistry({ rootDir: findConstructRoot(rootDir) });
 }
 
 function specialistIds(registry) {
-  return new Set((registry.specialists ?? []).map((s) => `cx-${s.name}`));
+  return new Set(Object.values(registry.specialists ?? {}).map((s) => `cx-${s.name}`));
 }
 
 function countAntiPatterns(body) {

package/lib/certification/runner.mjs

@@ -22,7 +22,7 @@ import { measurePromptBudgetChains } from './prompt-budget.mjs';
 import { validateAllArtifactProvenance } from './artifact-provenance.mjs';
 import { validateDocumentWorkflowCertification } from './document-workflow.mjs';
 import { buildDemoParityReport } from './demo-parity.mjs';
-import { runRealLlmS3, runRealLlmS8 } from './real-llm-scenarios.mjs';
+import { redactRealLlmGateEvidence, runRealLlmS3, runRealLlmS8 } from './real-llm-scenarios.mjs';
 import { decidePromotion } from '../evals/gates.mjs';
 import { buildScenarioEvaluationReport, runScenarioEvalGates } from './eval-bridge.mjs';
 import {
@@ -106,7 +106,14 @@ async function runGate(gate, { root, scenario }) {
     const runner = gate.scenario === 's8' ? runRealLlmS8 : runRealLlmS3;
     const result = await runner({ env: process.env });
     if (result.status === 'inconclusive') {
-      return { id: gate.id, pass: false, detail: result.skip ?? result.detail ?? 'inconclusive', inconclusive: true };
+      const evidence = redactRealLlmGateEvidence(result);
+      return {
+        id: gate.id,
+        pass: false,
+        detail: result.skip ?? result.detail ?? 'inconclusive',
+        ...(evidence ? { evidence } : {}),
+        inconclusive: true,
+      };
     }
     return { id: gate.id, pass: result.status === 'pass', detail: result.detail ?? result.status };
   }