@geraldmaron/construct 1.1.0 → 1.2.0

package/lib/certification/runner.mjs

@@ -0,0 +1,323 @@
+/**
+ * lib/certification/runner.mjs — execute certification scenarios and persist run records.
+ *
+ * Hermetic scenarios run deterministic gates only. Live scenarios require
+ * CONSTRUCT_CERTIFY_LIVE=1; without opt-in the runner records inconclusive and
+ * never promotes a skipped provider call to pass. Paid reference models require
+ * CONSTRUCT_CERTIFY_ALLOW_PAID=1 with operator ack recorded on the run artifact.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import { validateCapabilityLedger } from '../capability-ledger.mjs';
+import { validateCorpusInventory } from '../test-corpus-inventory.mjs';
+import { validateArtifactRelease } from '../artifact-release-gate.mjs';
+import { validateRoleCards } from './role-cards.mjs';
+import { auditSpecialistContracts } from './specialist-contracts.mjs';
+import { validateAllGoldenArtifactGates } from './artifact-gates.mjs';
+import { validateSkillScenarioFixture } from './skill-scenarios.mjs';
+import { validateSpecialistScenarioFixture } from './specialist-scenarios.mjs';
+import { validateAllRoleOverlays } from './role-overlays.mjs';
+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 { decidePromotion } from '../evals/gates.mjs';
+import { buildScenarioEvaluationReport, runScenarioEvalGates } from './eval-bridge.mjs';
+import {
+  formatModelRoutingSummary,
+  listCertificationModels,
+  resolveCertificationModel,
+} from './model-routing.mjs';
+import { deriveVerdictFromExecution } from './run.mjs';
+import { fixtureDigest, getScenario, newRunId } from './scenarios.mjs';
+import { writeCertificationRun } from './store.mjs';
+
+export const LIVE_OPT_IN_ENV = 'CONSTRUCT_CERTIFY_LIVE';
+
+function liveOptInEnabled(env = process.env) {
+  return env[LIVE_OPT_IN_ENV] === '1';
+}
+
+async function runGate(gate, { root, scenario }) {
+  if (gate.type === 'capability-ledger-audit') {
+    const result = validateCapabilityLedger({ rootDir: root });
+    return { id: gate.id, pass: result.pass, detail: result.errors[0] ?? null };
+  }
+  if (gate.type === 'corpus-inventory-audit') {
+    const result = validateCorpusInventory({ rootDir: root });
+    return { id: gate.id, pass: result.pass, detail: result.errors[0] ?? null };
+  }
+  if (gate.type === 'artifact-release-gate') {
+    const rel = scenario.fixture.path;
+    const result = validateArtifactRelease({
+      filePath: path.join(root, rel),
+      type: gate.artifactType ?? 'prd',
+      rootDir: root,
+    });
+    return { id: gate.id, pass: result.ok === true, detail: result.errors?.[0] ?? null };
+  }
+  if (gate.type === 'role-cards-audit') {
+    const result = validateRoleCards({ rootDir: root });
+    return { id: gate.id, pass: result.pass, detail: result.errors[0] ?? null };
+  }
+  if (gate.type === 'specialist-contracts-audit') {
+    const result = auditSpecialistContracts({ rootDir: root });
+    return { id: gate.id, pass: result.pass, detail: result.failures[0]?.specialistId ?? null };
+  }
+  if (gate.type === 'skill-scenario-audit') {
+    const rel = scenario.fixture.path;
+    const fixture = JSON.parse(fs.readFileSync(path.join(root, rel), 'utf8'));
+    const result = validateSkillScenarioFixture(fixture, { rootDir: root });
+    return { id: gate.id, pass: result.pass, detail: result.errors[0] ?? null };
+  }
+  if (gate.type === 'artifact-golden-audit') {
+    const result = validateAllGoldenArtifactGates({ rootDir: root });
+    return { id: gate.id, pass: result.pass, detail: result.errors[0] ?? null };
+  }
+  if (gate.type === 'specialist-scenario-audit') {
+    const rel = scenario.fixture.path;
+    const fixture = JSON.parse(fs.readFileSync(path.join(root, rel), 'utf8'));
+    const result = validateSpecialistScenarioFixture(fixture, { rootDir: root });
+    return { id: gate.id, pass: result.pass, detail: result.errors[0] ?? null };
+  }
+  if (gate.type === 'role-overlays-audit') {
+    const result = validateAllRoleOverlays({ rootDir: root });
+    return { id: gate.id, pass: result.pass, detail: result.errors[0] ?? null };
+  }
+  if (gate.type === 'prompt-budget-audit') {
+    const result = measurePromptBudgetChains({ rootDir: root });
+    return { id: gate.id, pass: result.pass, detail: result.errors[0] ?? null };
+  }
+  if (gate.type === 'artifact-provenance-audit') {
+    const result = validateAllArtifactProvenance({ rootDir: root, strict: gate.strict !== false });
+    return { id: gate.id, pass: result.pass, detail: result.errors[0] ?? null };
+  }
+  if (gate.type === 'document-workflow-audit') {
+    const result = validateDocumentWorkflowCertification({ rootDir: root });
+    return { id: gate.id, pass: result.pass, detail: result.errors[0] ?? null };
+  }
+  if (gate.type === 'demo-parity-audit') {
+    const result = buildDemoParityReport({ rootDir: root });
+    return { id: gate.id, pass: result.pass, detail: result.mismatches[0]?.detail ?? null };
+  }
+  if (gate.type === 'real-llm-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 };
+    }
+    return { id: gate.id, pass: result.status === 'pass', detail: result.detail ?? result.status };
+  }
+  if (gate.type === 'live-provider-smoke') {
+    return { id: gate.id, pass: false, detail: 'live provider gate not executed in hermetic mode' };
+  }
+  return { id: gate.id, pass: false, detail: `unknown gate type: ${gate.type}` };
+}
+
+function deriveVerdictWithEval({ scenarioGates = [], evalReport = null, providerSkipped = false, qualitative = null, error = null } = {}) {
+  if (providerSkipped || error) {
+    return deriveVerdictFromExecution({ providerSkipped, error });
+  }
+
+  const scenarioFailed = scenarioGates.some((gate) => gate?.pass === false && !gate?.inconclusive);
+  const inconclusiveGate = scenarioGates.find((gate) => gate?.inconclusive);
+  if (inconclusiveGate) {
+    return deriveVerdictFromExecution({ providerSkipped: true, error: inconclusiveGate.detail });
+  }
+  if (scenarioFailed) {
+    return deriveVerdictFromExecution({ gates: scenarioGates });
+  }
+
+  const promotion = evalReport?.decision ?? decidePromotion({
+    deterministic: evalReport?.blocked != null
+      ? { blocked: evalReport.blocked, regressions: (evalReport.gates ?? []).filter((g) => !g.pass).map((g) => g.gate), gates: evalReport.gates ?? [] }
+      : null,
+    judges: evalReport?.evaluators ?? [],
+  });
+
+  if (!promotion.promotable) {
+    const source = evalReport?.blocked ? 'deterministic' : (evalReport?.evaluators?.some((j) => j.verdict === 'fail') ? 'qualitative' : 'deterministic');
+    return {
+      status: 'fail',
+      source,
+      reason: promotion.reason,
+    };
+  }
+
+  if (qualitative?.abstained) {
+    return deriveVerdictFromExecution({ gates: scenarioGates, qualitative });
+  }
+  if (typeof qualitative?.score === 'number' && qualitative.score < 0.5) {
+    return deriveVerdictFromExecution({ gates: scenarioGates, qualitative });
+  }
+
+  return deriveVerdictFromExecution({ gates: scenarioGates, qualitative });
+}
+
+export function previewCertificationRun(scenarioId, { repoRoot = process.cwd(), env = process.env, now = () => new Date().toISOString() } = {}) {
+  const { scenario } = getScenario(scenarioId, { repoRoot });
+  const model = resolveCertificationModel(scenario.model ?? {}, { env, now });
+  const mode = scenario.mode ?? 'hermetic';
+  const requiresLive = mode === 'live' || scenario.requiresEnv === LIVE_OPT_IN_ENV;
+  return {
+    scenarioId,
+    mode,
+    model,
+    modelSummary: formatModelRoutingSummary(model),
+    requiresLive,
+    liveOptIn: liveOptInEnabled(env),
+    modelsAvailable: listCertificationModels({ env }),
+  };
+}
+
+export async function runCertificationScenario(scenarioId, {
+  projectDir = process.cwd(),
+  repoRoot = projectDir,
+  env = process.env,
+  now = () => new Date().toISOString(),
+  dryRun = false,
+  judges = [],
+} = {}) {
+  const startedAt = now();
+  const startMs = Date.now();
+  const { root, scenario } = getScenario(scenarioId, { repoRoot });
+  const fixturePath = scenario.fixture.path;
+  const sha256 = fixtureDigest(root, fixturePath);
+  const mode = scenario.mode ?? 'hermetic';
+  const requiresLive = mode === 'live' || scenario.requiresEnv === LIVE_OPT_IN_ENV;
+  const resolvedModel = resolveCertificationModel(scenario.model ?? {}, { env, now });
+
+  if (resolvedModel.blocked) {
+    const verdict = deriveVerdictFromExecution({
+      providerSkipped: true,
+      error: resolvedModel.blockReason,
+    });
+    const run = {
+      schemaVersion: 1,
+      id: newRunId(scenarioId),
+      scenarioId,
+      capabilityId: scenario.capabilityId,
+      model: {
+        provider: resolvedModel.provider,
+        requestedId: resolvedModel.requestedId,
+        resolvedId: resolvedModel.resolvedId,
+        tier: resolvedModel.tier,
+        paidOptIn: resolvedModel.paidOptIn,
+        operatorAckAt: resolvedModel.operatorAckAt,
+      },
+      fixture: { path: fixturePath, sha256 },
+      verdict: { ...verdict, reason: resolvedModel.blockReason },
+      gates: [],
+      evaluation: null,
+      qualitative: null,
+      timing: { latencyMs: Date.now() - startMs, startedAt, finishedAt: now() },
+      cost: null,
+      artifacts: null,
+      evidenceVersion: 'corpus-inventory:1',
+      createdAt: startedAt,
+    };
+    if (dryRun) return { dryRun: true, run, exitCode: 2, modelSummary: formatModelRoutingSummary(resolvedModel) };
+    writeCertificationRun(run, { rootDir: projectDir });
+    return { run, exitCode: 2, modelSummary: formatModelRoutingSummary(resolvedModel) };
+  }
+
+  if (requiresLive && !liveOptInEnabled(env)) {
+    const verdict = deriveVerdictFromExecution({
+      providerSkipped: true,
+      gates: [],
+    });
+    const run = {
+      schemaVersion: 1,
+      id: newRunId(scenarioId),
+      scenarioId,
+      capabilityId: scenario.capabilityId,
+      model: {
+        provider: resolvedModel.provider,
+        requestedId: resolvedModel.requestedId,
+        resolvedId: resolvedModel.resolvedId,
+        tier: resolvedModel.tier,
+        paidOptIn: resolvedModel.paidOptIn,
+        operatorAckAt: resolvedModel.operatorAckAt,
+      },
+      fixture: { path: fixturePath, sha256 },
+      verdict: { ...verdict, reason: `${LIVE_OPT_IN_ENV}=1 required for live scenarios` },
+      gates: [],
+      evaluation: null,
+      qualitative: null,
+      timing: { latencyMs: Date.now() - startMs, startedAt, finishedAt: now() },
+      cost: null,
+      artifacts: null,
+      evidenceVersion: 'corpus-inventory:1',
+      createdAt: startedAt,
+    };
+    if (dryRun) return { dryRun: true, run, exitCode: 2, modelSummary: formatModelRoutingSummary(resolvedModel) };
+    writeCertificationRun(run, { rootDir: projectDir });
+    return { run, exitCode: 2, modelSummary: formatModelRoutingSummary(resolvedModel) };
+  }
+
+  const scenarioGates = [];
+  for (const gate of scenario.gates ?? []) {
+    scenarioGates.push(await runGate(gate, { root, scenario }));
+  }
+
+  const { deterministic, evalGates } = runScenarioEvalGates(scenario);
+  const evaluation = buildScenarioEvaluationReport({
+    scenario,
+    deterministic,
+    judges,
+  });
+  const gates = [...scenarioGates, ...evalGates];
+
+  const qualitative = judges.length > 0
+    ? {
+      judgeModel: judges[0]?.model ?? null,
+      score: judges.every((j) => j.verdict !== 'fail') ? 1 : 0,
+      abstained: judges.every((j) => j.verdict === 'abstain'),
+    }
+    : null;
+
+  const verdict = deriveVerdictWithEval({
+    scenarioGates,
+    evalReport: evaluation,
+    qualitative,
+  });
+
+  const run = {
+    schemaVersion: 1,
+    id: newRunId(scenarioId),
+    scenarioId,
+    capabilityId: scenario.capabilityId,
+    model: {
+      provider: resolvedModel.provider,
+      requestedId: resolvedModel.requestedId,
+      resolvedId: resolvedModel.resolvedId,
+      tier: resolvedModel.tier,
+      paidOptIn: resolvedModel.paidOptIn,
+      operatorAckAt: resolvedModel.operatorAckAt,
+    },
+    fixture: { path: fixturePath, sha256 },
+    verdict,
+    gates,
+    evaluation,
+    qualitative,
+    timing: { latencyMs: Date.now() - startMs, startedAt, finishedAt: now() },
+    cost: null,
+    artifacts: null,
+    evidenceVersion: 'corpus-inventory:1',
+    createdAt: startedAt,
+  };
+
+  if (dryRun) {
+    return {
+      dryRun: true,
+      run,
+      exitCode: verdict.status === 'pass' ? 0 : verdict.status === 'fail' ? 1 : 2,
+      modelSummary: formatModelRoutingSummary(resolvedModel),
+    };
+  }
+  const persisted = writeCertificationRun(run, { rootDir: projectDir });
+  const exitCode = verdict.status === 'pass' ? 0 : verdict.status === 'fail' ? 1 : 2;
+  return { ...persisted, exitCode, modelSummary: formatModelRoutingSummary(resolvedModel) };
+}

package/lib/certification/scenarios.mjs

@@ -0,0 +1,51 @@
+/**
+ * lib/certification/scenarios.mjs — load certification scenario catalog and fixtures.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+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 defaultScenarioCatalogPath(rootDir = process.cwd()) {
+  return path.join(findConstructRoot(rootDir), 'tests', 'certification', 'scenarios', 'catalog.json');
+}
+
+export function loadScenarioCatalog({ repoRoot } = {}) {
+  const root = findConstructRoot(repoRoot);
+  const filePath = defaultScenarioCatalogPath(root);
+  const catalog = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  return { root, filePath, catalog };
+}
+
+export function listScenarios({ repoRoot } = {}) {
+  const { catalog } = loadScenarioCatalog({ repoRoot });
+  return catalog.scenarios ?? [];
+}
+
+export function getScenario(scenarioId, { repoRoot } = {}) {
+  const { root, catalog } = loadScenarioCatalog({ repoRoot });
+  const scenario = (catalog.scenarios ?? []).find((entry) => entry.id === scenarioId);
+  if (!scenario) throw new Error(`unknown certification scenario: ${scenarioId}`);
+  return { root, scenario };
+}
+
+export function fixtureDigest(root, relPath) {
+  const absolute = path.join(root, relPath);
+  if (!fs.existsSync(absolute)) throw new Error(`fixture does not exist: ${relPath}`);
+  return createHash('sha256').update(fs.readFileSync(absolute)).digest('hex');
+}
+
+export function newRunId(scenarioId) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return `cert-${scenarioId.replace(/[^a-z0-9.-]+/gi, '-')}-${stamp}`;
+}

package/lib/certification/skill-inventory.mjs

@@ -0,0 +1,289 @@
+/**
+ * lib/certification/skill-inventory.mjs — machine-readable skill corpus inventory.
+ *
+ * Walks skills/**, extracts id, owner specialist, activation triggers, inputs,
+ * outputs, and verification hooks. Flags orphan skills and conflicting output
+ * contracts for manifest workflow types. Output feeds tests/certification/skills/inventory.json.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { artifactTypes, loadArtifactManifest } from '../artifact-manifest.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;
+  }
+}
+
+function collectSkillFiles(skillsDir) {
+  const results = [];
+  const walk = (dir, prefix = '') => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        walk(path.join(dir, entry.name), prefix ? `${prefix}/${entry.name}` : entry.name);
+      } else if (entry.name.endsWith('.md') && entry.name !== 'routing.md') {
+        const rel = prefix ? `${prefix}/${entry.name.replace(/\.md$/, '')}` : entry.name.replace(/\.md$/, '');
+        results.push(rel);
+      }
+    }
+  };
+  try { walk(skillsDir); } catch { /* skills dir missing */ }
+  return results.sort();
+}
+
+function collectProfileRoles(root) {
+  const dir = path.join(root, 'profiles');
+  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 */ }
+    }
+  } catch { /* no profiles dir */ }
+  return roles;
+}
+
+function roleBase(skillId) {
+  const m = skillId.match(/^roles\/([^.]+)(?:\..*)?$/);
+  return m ? m[1] : null;
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return { meta: {}, body: content };
+  const meta = {};
+  for (const line of match[1].split('\n')) {
+    const kv = line.match(/^([a-zA-Z0-9_-]+):\s*(.*)$/);
+    if (!kv) continue;
+    const [, key, raw] = kv;
+    if (raw.startsWith('[')) {
+      try { meta[key] = JSON.parse(raw); } catch { meta[key] = raw; }
+    } else {
+      meta[key] = raw.replace(/^["']|["']$/g, '');
+    }
+  }
+  return { meta, body: content.slice(match[0].length) };
+}
+
+function activationTriggers(meta, body) {
+  const triggers = [];
+  if (meta.description) triggers.push(meta.description);
+  const useWhen = body.match(/^Use when:\s*(.+)$/m)?.[1];
+  if (useWhen) triggers.push(useWhen.trim());
+  return [...new Set(triggers.filter(Boolean))];
+}
+
+function verificationHooks(meta, body) {
+  const hooks = [];
+  if (meta.verificationBar) hooks.push({ kind: 'verificationBar', value: meta.verificationBar });
+  if (/construct artifact validate/i.test(body)) hooks.push({ kind: 'cli', value: 'construct artifact validate' });
+  if (/construct certify/i.test(body)) hooks.push({ kind: 'cli', value: 'construct certify' });
+  if (/get_template\(/i.test(body)) hooks.push({ kind: 'mcp', value: 'get_template' });
+  return hooks;
+}
+
+function resolveOwners(skillId, { registry, declaredSkills, ownerBases }) {
+  const owners = new Set();
+  for (const agent of registry.specialists ?? []) {
+    if ((agent.skills ?? []).includes(skillId)) owners.add(`cx-${agent.name}`);
+  }
+  const base = roleBase(skillId);
+  if (base && ownerBases.has(base)) {
+    for (const agent of registry.specialists ?? []) {
+      if (agent.name === base || agent.name.replace(/^cx-/, '') === base) owners.add(`cx-${agent.name}`);
+    }
+    if (!owners.size) owners.add(`profile-role:${base}`);
+  }
+  if (declaredSkills.has(skillId) && owners.size === 0) {
+    for (const agent of registry.specialists ?? []) {
+      if ((agent.skills ?? []).includes(skillId)) owners.add(`cx-${agent.name}`);
+    }
+  }
+  return [...owners].sort();
+}
+
+function workflowSkillIds(manifest) {
+  const ids = new Set();
+  for (const entry of Object.values(manifest.artifacts ?? {})) {
+    if (entry.workflowSkill) ids.add(entry.workflowSkill);
+  }
+  return ids;
+}
+
+function detectConflictingOutputs(skills) {
+  const manifestTypes = new Set(artifactTypes());
+  const byType = new Map();
+  for (const skill of skills) {
+    const type = skill.outputs?.artifactType;
+    if (!type || !manifestTypes.has(type)) continue;
+    if (!skill.id.startsWith('docs/') && !skill.id.includes('-workflow')) continue;
+    const list = byType.get(type) ?? [];
+    list.push(skill);
+    byType.set(type, list);
+  }
+  const conflicts = [];
+  for (const [artifactType, entries] of byType) {
+    if (entries.length < 2) continue;
+    const bars = new Set(entries.map((e) => e.verificationHooks.find((h) => h.kind === 'verificationBar')?.value ?? ''));
+    conflicts.push({
+      artifactType,
+      skillIds: entries.map((e) => e.id),
+      reason: bars.size > 1 ? 'divergent verificationBar across workflow skills' : 'multiple workflow skills claim the same manifest artifact type',
+    });
+  }
+  return conflicts;
+}
+
+export function defaultSkillInventoryPath(rootDir = process.cwd()) {
+  return path.join(findConstructRoot(rootDir), 'tests', 'certification', 'skills', 'inventory.json');
+}
+
+export function buildSkillInventory({ rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const skillsDir = path.join(root, 'skills');
+  const registry = JSON.parse(fs.readFileSync(path.join(root, 'specialists', 'registry.json'), 'utf8'));
+  const manifest = loadArtifactManifest({ rootDir: root });
+  const declaredSkills = new Set();
+  for (const agent of registry.specialists ?? []) {
+    for (const skill of agent.skills ?? []) declaredSkills.add(skill);
+  }
+  const ownerBases = new Set([
+    ...(registry.specialists ?? []).map((a) => a.name.replace(/^cx-/, '')),
+    ...collectProfileRoles(root),
+  ]);
+  const workflowIds = workflowSkillIds(manifest);
+
+  const skills = collectSkillFiles(skillsDir).map((id) => {
+    const filePath = path.join(skillsDir, `${id}.md`);
+    const content = fs.readFileSync(filePath, 'utf8');
+    const { meta, body } = parseFrontmatter(content);
+    const owners = resolveOwners(id, { registry, declaredSkills, ownerBases });
+    const hooks = verificationHooks(meta, body);
+    return {
+      id,
+      owners,
+      activationTriggers: activationTriggers(meta, body),
+      inputs: Array.isArray(meta.inputs) ? meta.inputs : (meta.inputs ? [meta.inputs] : []),
+      outputs: {
+        artifactType: meta.artifactType ?? null,
+        name: meta.name ?? null,
+      },
+      verificationHooks: hooks,
+      workflowSkill: workflowIds.has(id),
+    };
+  });
+
+  const blockingFindings = [];
+  for (const skill of skills) {
+    if (skill.owners.length === 0) {
+      blockingFindings.push({ kind: 'no-owner', skillId: skill.id, severity: 'blocking' });
+    }
+  }
+  for (const conflict of detectConflictingOutputs(skills)) {
+    blockingFindings.push({
+      kind: 'conflicting-output-contract',
+      severity: 'blocking',
+      artifactType: conflict.artifactType,
+      skillIds: conflict.skillIds,
+      reason: conflict.reason,
+    });
+  }
+
+  const payload = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    generator: 'lib/certification/skill-inventory.mjs',
+    skillCount: skills.length,
+    skills,
+    blockingFindings,
+    digest: null,
+  };
+  const canonical = { ...payload, digest: undefined };
+  payload.digest = createHash('sha256').update(JSON.stringify(canonical)).digest('hex');
+  return payload;
+}
+
+export function validateSkillInventory({ rootDir, inventory: supplied, checkFreshness = true } = {}) {
+  const root = findConstructRoot(rootDir);
+  const inventoryPath = defaultSkillInventoryPath(root);
+  const inventory = supplied ?? JSON.parse(fs.readFileSync(inventoryPath, 'utf8'));
+  const errors = [];
+  const warnings = [];
+
+  if (inventory.version !== 1) errors.push('inventory.version must equal 1');
+  if (!Array.isArray(inventory.skills) || inventory.skills.length === 0) errors.push('inventory.skills must be non-empty');
+
+  const onDisk = new Set(collectSkillFiles(path.join(root, 'skills')));
+  const indexed = new Set((inventory.skills ?? []).map((s) => s.id));
+  for (const id of onDisk) {
+    if (!indexed.has(id)) errors.push(`missing inventory entry: ${id}`);
+  }
+  for (const skill of inventory.skills ?? []) {
+    if (!onDisk.has(skill.id)) errors.push(`stale inventory entry: ${skill.id}`);
+    if (!Array.isArray(skill.owners)) errors.push(`${skill.id}: owners must be an array`);
+    if (!Array.isArray(skill.activationTriggers)) errors.push(`${skill.id}: activationTriggers must be an array`);
+  }
+
+  for (const finding of inventory.blockingFindings ?? []) {
+    if (finding.severity === 'blocking') warnings.push(`blocking finding recorded: ${finding.kind} ${finding.skillId ?? finding.artifactType ?? ''}`.trim());
+  }
+
+  if (checkFreshness) {
+    const fresh = buildSkillInventory({ rootDir: root });
+    const freshCanonical = { ...fresh, digest: undefined, generatedAt: undefined };
+    const committedCanonical = { ...inventory, digest: undefined, generatedAt: undefined };
+    if (JSON.stringify(freshCanonical) !== JSON.stringify(committedCanonical)) {
+      errors.push('inventory is stale — regenerate with node scripts/generate-skill-inventory.mjs');
+    }
+  }
+
+  return {
+    filePath: inventoryPath,
+    skillCount: inventory.skills?.length ?? 0,
+    blockingCount: (inventory.blockingFindings ?? []).filter((f) => f.severity === 'blocking').length,
+    errors,
+    warnings,
+    pass: errors.length === 0,
+  };
+}
+
+export function writeSkillInventory({ rootDir } = {}) {
+  const root = findConstructRoot(rootDir);
+  const inventory = buildSkillInventory({ rootDir: root });
+  const inventoryPath = defaultSkillInventoryPath(root);
+  fs.mkdirSync(path.dirname(inventoryPath), { recursive: true });
+  fs.writeFileSync(inventoryPath, `${JSON.stringify(inventory, null, 2)}\n`);
+  return { inventoryPath, inventory };
+}
+
+export function runSkillInventoryAuditCli(args = [], { rootDir } = {}) {
+  if (args.includes('--write')) {
+    const { inventoryPath, inventory } = writeSkillInventory({ rootDir });
+    process.stdout.write(`Wrote ${inventoryPath} (${inventory.skillCount} skills, ${inventory.blockingFindings.length} blocking findings)\n`);
+    return validateSkillInventory({ rootDir, inventory, checkFreshness: false });
+  }
+  const checkFreshness = !args.includes('--no-freshness');
+  const result = validateSkillInventory({ rootDir, checkFreshness });
+  if (args.includes('--json')) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else {
+    process.stdout.write(`Skill inventory: ${result.skillCount} skills (${result.blockingCount} blocking findings recorded)\n`);
+    if (result.errors.length) result.errors.forEach((error) => process.stderr.write(`  ✗ ${error}\n`));
+    if (result.warnings.length) result.warnings.forEach((warning) => process.stderr.write(`  ⚠ ${warning}\n`));
+    process.stdout.write(result.pass ? '  Result: PASS\n' : '  Result: FAIL\n');
+  }
+  if (!result.pass) process.exitCode = 1;
+  return result;
+}