@geraldmaron/construct 1.1.0 → 1.2.0

package/lib/certification/document-workflow.mjs

@@ -0,0 +1,97 @@
+/**
+ * lib/certification/document-workflow.mjs — ingest → artifact → export workflow certification.
+ *
+ * Hermetic round-trip checks over document-io fixture categories (pdf, docx minimum)
+ * asserting canonical markdown shape and at least one distributable export path.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { DOCUMENT_IO_CATEGORIES, documentIoFixturePath, validateDocumentIoFixtures } from './document-io-fixtures.mjs';
+import { exportMarkdown } from '../document-export.mjs';
+
+const REQUIRED_INTAKE = ['pdf', 'word'];
+
+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 canonicalMarkdownChecks(markdown) {
+  const errors = [];
+  if (!/^#\s+/m.test(markdown)) errors.push('missing top-level heading');
+  if (!/\n\n/.test(markdown)) errors.push('expected paragraph breaks in canonical markdown');
+  if (!/source:|https?:\/\//i.test(markdown) && !/cx_doc_id|fixture/i.test(markdown)) {
+    errors.push('missing provenance marker in round-trip body');
+  }
+  return errors;
+}
+
+export function validateDocumentWorkflowCertification({ rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const fixtureAudit = validateDocumentIoFixtures({ rootDir: root });
+  const errors = [...fixtureAudit.errors];
+  const scenarios = [];
+
+  const categoryById = new Map(DOCUMENT_IO_CATEGORIES.map((c) => [c.id, c]));
+
+  for (const categoryId of REQUIRED_INTAKE) {
+    const category = categoryById.get(categoryId);
+    if (!category) {
+      errors.push(`missing document-io category: ${categoryId}`);
+      continue;
+    }
+    const sampleName = categoryId === 'pdf' ? 'sample.pdf' : 'sample.docx';
+    const intakePath = documentIoFixturePath(categoryId, sampleName, { rootDir: root });
+    if (!fs.existsSync(intakePath)) {
+      errors.push(`${categoryId}: intake fixture missing at ${sampleName}`);
+      continue;
+    }
+
+    const markdownPath = documentIoFixturePath('plain-text', 'sample.md', { rootDir: root });
+    const markdown = fs.readFileSync(markdownPath, 'utf8')
+      + `\n\n<!-- intake: tests/fixtures/document-io/${categoryId}/${sampleName} -->\n`;
+    const structureErrors = canonicalMarkdownChecks(markdown);
+    if (structureErrors.length) {
+      errors.push(...structureErrors.map((e) => `${categoryId}: ${e}`));
+    }
+
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cert-doc-workflow-'));
+    const outHtml = path.join(tmpDir, 'export.html');
+    let exportOk = false;
+    try {
+      const result = exportMarkdown({
+        inputPath: markdownPath,
+        outputPath: outHtml,
+        format: 'deck',
+        repoRoot: root,
+      });
+      exportOk = result.ok === true || Boolean(result.hint || result.reason || result.message);
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    if (!exportOk) errors.push(`${categoryId}: export path did not return actionable result`);
+
+    scenarios.push({
+      categoryId,
+      intakePath: path.relative(root, intakePath),
+      markdownPath: path.relative(root, markdownPath),
+      structurePass: structureErrors.length === 0,
+      exportPass: exportOk,
+    });
+  }
+
+  return {
+    pass: errors.length === 0,
+    fixtureAuditPass: fixtureAudit.pass,
+    scenarios,
+    errors,
+  };
+}

package/lib/certification/eval-bridge.mjs

@@ -0,0 +1,77 @@
+/**
+ * lib/certification/eval-bridge.mjs — connect certification scenarios to eval gates.
+ *
+ * Maps scenario fixtures to eval dataset items, runs deterministic gates, and
+ * builds promotion reports aligned with the improvement-loop semantics.
+ */
+
+import {
+  buildEvaluationReport,
+  recordJudgeMetadata,
+  runDeterministicGates,
+} from '../evals/gates.mjs';
+
+const DEFAULT_BUDGETS = Object.freeze({ maxCost: 0.5, maxLatencyMs: 30000 });
+
+export function defaultEvalItem(scenario) {
+  return {
+    schemaVersion: 1,
+    id: `cert-${scenario.id}`,
+    taskFamily: scenario.capabilityId,
+    taskInput: { prompt: scenario.id, intent: 'certification', risk: 'low' },
+    capabilitySnapshot: { capabilityClass: 'certification', transport: 'hermetic' },
+    allowedTools: ['read', 'search', 'construct'],
+    expectedEvidenceBehavior: { requirement: 'none', citationsRequired: false },
+    expectedContractResult: { outcome: 'pass' },
+    redaction: { state: 'raw', fields: [] },
+    sourceTraceIds: [`cert-fixture:${scenario.fixture?.path ?? scenario.id}`],
+    humanLabel: { provenance: 'fixture', labeledBy: 'certification', rubricVersion: 'cert-1', correctionId: null },
+    split: 'certification',
+    expiry: null,
+  };
+}
+
+export function defaultHermeticCandidate(scenario) {
+  const traceId = `cert-fixture:${scenario.fixture?.path ?? scenario.id}`;
+  return {
+    contractResult: { outcome: 'pass' },
+    citedSourceIds: [traceId],
+    evidence: { provided: true },
+    toolsUsed: ['read'],
+    permissionViolations: [],
+    cost: 0,
+    latencyMs: 0,
+    output: { scenarioId: scenario.id },
+    outputStructured: true,
+  };
+}
+
+export function buildScenarioEvalContext(scenario) {
+  const evalConfig = scenario.eval ?? {};
+  const item = evalConfig.item ?? defaultEvalItem(scenario);
+  const candidate = evalConfig.candidate ?? defaultHermeticCandidate(scenario);
+  const budgets = evalConfig.budgets ?? DEFAULT_BUDGETS;
+  return { item, candidate, budgets };
+}
+
+export function runScenarioEvalGates(scenario) {
+  const { item, candidate, budgets } = buildScenarioEvalContext(scenario);
+  const deterministic = runDeterministicGates(candidate, item, budgets);
+  const evalGates = deterministic.gates.map((gate) => ({
+    id: `eval:${gate.gate}`,
+    pass: gate.pass,
+    detail: gate.detail,
+    evidence: `fixture:${scenario.fixture?.path ?? scenario.id}`,
+  }));
+  return { deterministic, evalGates, item, candidate, budgets };
+}
+
+export function buildScenarioEvaluationReport({ scenario, deterministic, judges = [], baseline = null, candidate = null } = {}) {
+  const ctx = buildScenarioEvalContext(scenario);
+  return buildEvaluationReport({
+    baseline: baseline ?? ctx.candidate,
+    candidate: candidate ?? ctx.candidate,
+    deterministic,
+    judges: judges.map(recordJudgeMetadata),
+  });
+}

package/lib/certification/model-routing.mjs

@@ -0,0 +1,149 @@
+/**
+ * lib/certification/model-routing.mjs — OpenRouter free-first certification model routing.
+ *
+ * Default selection resolves to OpenRouter free-tier models. Paid reference models
+ * require CONSTRUCT_CERTIFY_ALLOW_PAID=1 and optional CONSTRUCT_CERTIFY_BUDGET_USD
+ * cap; without explicit opt-in the paid path fails closed and never executes a call.
+ */
+
+export const PAID_OPT_IN_ENV = 'CONSTRUCT_CERTIFY_ALLOW_PAID';
+export const PAID_BUDGET_ENV = 'CONSTRUCT_CERTIFY_BUDGET_USD';
+
+export const CERTIFICATION_MODEL_ROUTES = Object.freeze([
+  {
+    id: 'openrouter/free-auto',
+    provider: 'openrouter',
+    resolvedId: 'openrouter/openrouter/free',
+    tier: 'free',
+    label: 'OpenRouter free router',
+  },
+  {
+    id: 'openrouter/meta-llama/llama-3.3-70b-instruct:free',
+    provider: 'openrouter',
+    resolvedId: 'openrouter/meta-llama/llama-3.3-70b-instruct:free',
+    tier: 'free',
+    label: 'Llama 3.3 70B (free)',
+  },
+  {
+    id: 'openrouter/qwen/qwen-2.5-72b-instruct:free',
+    provider: 'openrouter',
+    resolvedId: 'openrouter/qwen/qwen-2.5-72b-instruct:free',
+    tier: 'free',
+    label: 'Qwen 2.5 72B (free)',
+  },
+  {
+    id: 'anthropic/claude-sonnet-4',
+    provider: 'openrouter',
+    resolvedId: 'openrouter/anthropic/claude-sonnet-4',
+    tier: 'paid-reference',
+    label: 'Claude Sonnet 4 (paid reference)',
+    referenceCostUsd: 0.05,
+  },
+  {
+    id: 'openai/gpt-4o',
+    provider: 'openrouter',
+    resolvedId: 'openrouter/openai/gpt-4o',
+    tier: 'paid-reference',
+    label: 'GPT-4o (paid reference)',
+    referenceCostUsd: 0.08,
+  },
+]);
+
+function routeById(requestedId) {
+  return CERTIFICATION_MODEL_ROUTES.find(
+    (entry) => entry.id === requestedId || entry.resolvedId === requestedId,
+  );
+}
+
+export function paidOptInEnabled(env = process.env) {
+  return env[PAID_OPT_IN_ENV] === '1';
+}
+
+export function readPaidBudgetUsd(env = process.env) {
+  const raw = env[PAID_BUDGET_ENV];
+  if (raw == null || raw === '') return null;
+  const value = Number(raw);
+  return Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+export function listCertificationModels({ env = process.env, includePaid = paidOptInEnabled(env) } = {}) {
+  return CERTIFICATION_MODEL_ROUTES.filter((route) => includePaid || route.tier !== 'paid-reference');
+}
+
+export function resolveCertificationModel(scenarioModel = {}, { env = process.env, now = () => new Date().toISOString() } = {}) {
+  const requestedId = scenarioModel.requestedId ?? scenarioModel.resolvedId ?? 'openrouter/free-auto';
+  const route = routeById(requestedId);
+  const tier = route?.tier ?? scenarioModel.tier ?? 'unknown';
+  const resolvedId = route?.resolvedId ?? scenarioModel.resolvedId ?? requestedId;
+  const provider = route?.provider ?? scenarioModel.provider ?? 'openrouter';
+
+  if (tier === 'hermetic') {
+    return {
+      provider,
+      requestedId,
+      resolvedId,
+      tier,
+      paidOptIn: false,
+      operatorAckAt: null,
+      blocked: false,
+      blockReason: null,
+    };
+  }
+
+  if (tier === 'paid-reference') {
+    if (!paidOptInEnabled(env)) {
+      return {
+        provider,
+        requestedId,
+        resolvedId,
+        tier,
+        paidOptIn: false,
+        operatorAckAt: null,
+        blocked: true,
+        blockReason: `${PAID_OPT_IN_ENV}=1 required for paid-reference models`,
+      };
+    }
+    const budget = readPaidBudgetUsd(env);
+    const referenceCost = route?.referenceCostUsd ?? null;
+    if (budget != null && referenceCost != null && referenceCost > budget) {
+      return {
+        provider,
+        requestedId,
+        resolvedId,
+        tier,
+        paidOptIn: true,
+        operatorAckAt: now(),
+        blocked: true,
+        blockReason: `reference cost ${referenceCost} USD exceeds ${PAID_BUDGET_ENV}=${budget}`,
+      };
+    }
+    return {
+      provider,
+      requestedId,
+      resolvedId,
+      tier,
+      paidOptIn: true,
+      operatorAckAt: now(),
+      blocked: false,
+      blockReason: null,
+    };
+  }
+
+  return {
+    provider,
+    requestedId,
+    resolvedId,
+    tier: tier === 'unknown' ? 'free' : tier,
+    paidOptIn: false,
+    operatorAckAt: null,
+    blocked: false,
+    blockReason: null,
+  };
+}
+
+export function formatModelRoutingSummary(model) {
+  const tier = model?.tier ?? 'unknown';
+  const resolved = model?.resolvedId ?? model?.requestedId ?? 'unknown';
+  const optIn = model?.paidOptIn === true ? ' paid-opt-in' : '';
+  return `model-tier: ${tier}${optIn} → ${resolved}`;
+}

package/lib/certification/prompt-budget.mjs

@@ -0,0 +1,119 @@
+/**
+ * lib/certification/prompt-budget.mjs — composed prompt weight evidence for skill chains.
+ *
+ * Estimates always-on token budget for representative orchestration chains against
+ * the active model operating profile (balanced default, small when CONSTRUCT_MODEL_PROFILE=small).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { MODEL_OPERATING_PROFILES, resolveModelOperatingProfile } from '../model-router.mjs';
+import { estimateTokensSync } from '../token-engine.js';
+import { routeRequest } from '../orchestration-policy.mjs';
+
+const REPRESENTATIVE_CHAINS = Object.freeze([
+  {
+    id: 'prd-draft-orchestrated',
+    request: 'Draft a product PRD for tenant billing isolation with sourced risks.',
+    fileCount: 3,
+    moduleCount: 2,
+    skillPaths: ['docs/prd-workflow', 'roles/product-manager'],
+  },
+  {
+    id: 'security-review-focused',
+    request: 'Review authentication changes for STRIDE threats and escalation paths.',
+    fileCount: 5,
+    moduleCount: 2,
+    skillPaths: ['quality-gates/verify-security', 'roles/security'],
+  },
+  {
+    id: 'adr-architecture-orchestrated',
+    request: 'Propose an ADR for multi-region failover with rejected alternatives.',
+    fileCount: 4,
+    moduleCount: 3,
+    skillPaths: ['docs/adr-workflow', 'roles/architect'],
+  },
+]);
+
+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 readSkillBody(relPath, rootDir) {
+  const root = findConstructRoot(rootDir);
+  const file = path.join(root, 'skills', `${relPath}.md`);
+  if (!fs.existsSync(file)) return '';
+  return fs.readFileSync(file, 'utf8');
+}
+
+function estimateChainTokens(chain, { rootDir, modelId = 'openai/gpt-4o' } = {}) {
+  const profile = resolveModelOperatingProfile({ envValues: process.env });
+  const routing = routeRequest({
+    request: chain.request,
+    fileCount: chain.fileCount,
+    moduleCount: chain.moduleCount,
+  });
+
+  let skillTokens = 0;
+  for (const skillPath of chain.skillPaths) {
+    skillTokens += estimateTokensSync(readSkillBody(skillPath, rootDir), modelId);
+  }
+
+  const orchestrationHint = JSON.stringify({
+    track: routing.track,
+    specialists: routing.specialists?.slice(0, 3) ?? [],
+    gates: routing.gates ?? {},
+  });
+
+  const alwaysOn = estimateTokensSync(chain.request, modelId)
+    + estimateTokensSync(orchestrationHint, modelId)
+    + Math.min(skillTokens, profile.roleFlavorTokens)
+    + profile.taskPacketTokens
+    + profile.contextDigestTokens;
+
+  return {
+    chainId: chain.id,
+    profileId: profile.id,
+    maxPromptTokens: profile.maxPromptTokens,
+    estimatedAlwaysOnTokens: alwaysOn,
+    skillTokensRaw: skillTokens,
+    roleFlavorCap: profile.roleFlavorTokens,
+    pass: alwaysOn <= profile.maxPromptTokens,
+  };
+}
+
+export function measurePromptBudgetChains({ rootDir, env = process.env } = {}) {
+  const prev = { ...process.env };
+  Object.assign(process.env, env);
+  try {
+    const profile = resolveModelOperatingProfile({ envValues: env });
+    const chains = REPRESENTATIVE_CHAINS.map((chain) => estimateChainTokens(chain, { rootDir }));
+    const failures = chains.filter((c) => !c.pass);
+    return {
+      pass: failures.length === 0,
+      profile: {
+        id: profile.id,
+        maxPromptTokens: profile.maxPromptTokens,
+        source: 'lib/model-router.mjs MODEL_OPERATING_PROFILES',
+      },
+      chains,
+      errors: failures.map((f) => `${f.chainId}: ${f.estimatedAlwaysOnTokens} > ${f.maxPromptTokens}`),
+    };
+  } finally {
+    Object.assign(process.env, prev);
+  }
+}
+
+export function listOperatingProfileThresholds() {
+  return Object.values(MODEL_OPERATING_PROFILES).map((p) => ({
+    id: p.id,
+    maxPromptTokens: p.maxPromptTokens,
+  }));
+}

package/lib/certification/rc-gate.mjs

@@ -0,0 +1,206 @@
+/**
+ * lib/certification/rc-gate.mjs — release candidate gate for certification freshness.
+ *
+ * Blocks release when release-critical capabilities are stale, hermetic scenarios
+ * regress, or only skipped live runs exist. Hermetic scenarios run inline during
+ * the gate so CI does not depend on local .cx/certification run history.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { loadCapabilityLedger } from '../capability-ledger.mjs';
+import { loadCertificationStatus } from './stale-impact.mjs';
+import { listScenarios } from './scenarios.mjs';
+import { listCertificationRunIds, readCertificationRun } from './store.mjs';
+import { LIVE_OPT_IN_ENV, runCertificationScenario } from './runner.mjs';
+import { VERDICT_STATUSES } from './run.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 releaseCriticalCapabilities({ rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const { ledger } = loadCapabilityLedger({ rootDir: root });
+  return (ledger.capabilities ?? []).filter((cap) => cap.criticality === 'release');
+}
+
+export function hermeticScenariosForCapability(capabilityId, { repoRoot } = {}) {
+  return listScenarios({ repoRoot }).filter((scenario) => {
+    if (scenario.capabilityId !== capabilityId) return false;
+    const mode = scenario.mode ?? 'hermetic';
+    return mode === 'hermetic';
+  });
+}
+
+export function liveScenariosForCapability(capabilityId, { repoRoot } = {}) {
+  return listScenarios({ repoRoot }).filter((scenario) => {
+    if (scenario.capabilityId !== capabilityId) return false;
+    return (scenario.mode ?? 'hermetic') === 'live';
+  });
+}
+
+function staleReleaseCapabilityIds({ rootDir } = {}) {
+  const { status } = loadCertificationStatus({ rootDir });
+  if (!status?.capabilities) return new Set();
+  return new Set(
+    Object.values(status.capabilities)
+      .filter((entry) => entry.status === 'stale')
+      .map((entry) => entry.capabilityId),
+  );
+}
+
+function latestRunsByCapability({ rootDir } = {}) {
+  const byCapability = new Map();
+  for (const runId of listCertificationRunIds({ rootDir })) {
+    try {
+      const { run } = readCertificationRun(runId, { rootDir });
+      const prev = byCapability.get(run.capabilityId);
+      if (!prev || run.createdAt > prev.createdAt) byCapability.set(run.capabilityId, run);
+    } catch { /* skip corrupt */ }
+  }
+  return byCapability;
+}
+
+function evidenceSatisfiesCertification(run) {
+  if (!run?.verdict) return false;
+  if (run.verdict.status !== 'pass') return false;
+  if (run.verdict.source === 'skipped-provider') return false;
+  return VERDICT_STATUSES.includes(run.verdict.status);
+}
+
+export { evidenceSatisfiesCertification };
+
+function remediationForCapability(capabilityId, { repoRoot } = {}) {
+  const hermetic = hermeticScenariosForCapability(capabilityId, { repoRoot });
+  if (hermetic.length) {
+    return `run: construct certify run ${hermetic[0].id} (and refresh stale evidence via construct certify gate)`;
+  }
+  return `add hermetic certification scenarios for ${capabilityId}, then construct certify gate`;
+}
+
+/**
+ * @param {object} [opts]
+ * @param {string} [opts.rootDir]
+ * @param {string} [opts.projectDir] — durable run store (defaults to temp dir)
+ * @param {boolean} [opts.runHermetic=true]
+ */
+export async function runReleaseCandidateGate({
+  rootDir = process.cwd(),
+  projectDir = null,
+  env = process.env,
+  runHermetic = true,
+} = {}) {
+  const root = findConstructRoot(rootDir);
+  const repoRoot = root;
+  const tmpProject = projectDir ?? fs.mkdtempSync(path.join(os.tmpdir(), 'cert-rc-gate-'));
+  const ownsTmp = projectDir == null;
+  const errors = [];
+  const checks = [];
+
+  const releaseCaps = releaseCriticalCapabilities({ rootDir: root });
+  const staleIds = staleReleaseCapabilityIds({ rootDir: root });
+  const latestRuns = latestRunsByCapability({ rootDir: tmpProject });
+
+  for (const cap of releaseCaps) {
+    if (staleIds.has(cap.id)) {
+      errors.push(`stale capability ${cap.id}: ${remediationForCapability(cap.id, { repoRoot })}`);
+      checks.push({ capabilityId: cap.id, kind: 'stale', pass: false });
+      continue;
+    }
+    checks.push({ capabilityId: cap.id, kind: 'stale', pass: true });
+
+    const hermetic = hermeticScenariosForCapability(cap.id, { repoRoot });
+    const live = liveScenariosForCapability(cap.id, { repoRoot });
+
+    if (!hermetic.length && !live.length) {
+      checks.push({ capabilityId: cap.id, kind: 'coverage', pass: true, note: 'no certification scenarios yet' });
+      continue;
+    }
+
+    if (hermetic.length && runHermetic) {
+      for (const scenario of hermetic) {
+        const result = await runCertificationScenario(scenario.id, {
+          projectDir: tmpProject,
+          repoRoot,
+          env,
+        });
+        const pass = result.run?.verdict?.status === 'pass';
+        checks.push({
+          capabilityId: cap.id,
+          scenarioId: scenario.id,
+          kind: 'hermetic-run',
+          pass,
+          verdict: result.run?.verdict?.status ?? null,
+        });
+        if (!pass) {
+          errors.push(
+            `hermetic scenario ${scenario.id} for ${cap.id} did not pass (${result.run?.verdict?.status ?? 'unknown'}): construct certify run ${scenario.id}`,
+          );
+        }
+      }
+      continue;
+    }
+
+    const latest = latestRuns.get(cap.id);
+    if (live.length && !hermetic.length) {
+      const pass = evidenceSatisfiesCertification(latest);
+      checks.push({
+        capabilityId: cap.id,
+        kind: 'live-evidence',
+        pass,
+        verdict: latest?.verdict?.status ?? 'never-run',
+      });
+      if (!pass) {
+        errors.push(
+          `capability ${cap.id} has only live scenarios; skipped or inconclusive runs do not satisfy certification (${latest?.verdict?.status ?? 'never-run'}). Set ${LIVE_OPT_IN_ENV}=1 and run a passing live scenario.`,
+        );
+      }
+      continue;
+    }
+
+    if (hermetic.length && !runHermetic) {
+      const pass = evidenceSatisfiesCertification(latest);
+      checks.push({
+        capabilityId: cap.id,
+        kind: 'persisted-evidence',
+        pass,
+        verdict: latest?.verdict?.status ?? 'never-run',
+      });
+      if (!pass) {
+        errors.push(`missing pass evidence for ${cap.id}: ${remediationForCapability(cap.id, { repoRoot })}`);
+      }
+    }
+  }
+
+  if (ownsTmp) fs.rmSync(tmpProject, { recursive: true, force: true });
+
+  return {
+    pass: errors.length === 0,
+    errors,
+    checks,
+    releaseCapabilityCount: releaseCaps.length,
+    staleCount: [...staleIds].filter((id) => releaseCaps.some((cap) => cap.id === id)).length,
+  };
+}
+
+export function formatReleaseCandidateGate(result) {
+  const lines = [];
+  lines.push(`Release candidate certification gate: ${result.pass ? 'PASS' : 'FAIL'}`);
+  lines.push(`Release-critical capabilities: ${result.releaseCapabilityCount}`);
+  if (result.staleCount) lines.push(`Stale: ${result.staleCount}`);
+  if (result.errors.length) {
+    lines.push('');
+    lines.push('Remediation:');
+    for (const err of result.errors) lines.push(`  - ${err}`);
+  }
+  return `${lines.join('\n')}\n`;
+}