@geraldmaron/construct 1.1.1 → 1.2.1

package/lib/publish.mjs

@@ -0,0 +1,305 @@
+/**
+ * lib/publish.mjs — `construct publish` orchestrator.
+ *
+ * Single compound run: artifact release gate (default), detect tooling, export
+ * markdown (pandoc-ext/diagram + Construct PDF template), optional VHS terminal
+ * demo, optional Playwright dashboard demo. --strict requires toolchain and gate.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { exportMarkdown, parsePublishFrontmatter, EXPORT_FORMATS } from './document-export.mjs';
+import { detectPublishPipeline } from './publish-tooling.mjs';
+import { runDemoRecord } from './demo.mjs';
+import { recordDashboardDemo } from './dashboard-demo.mjs';
+import { loadDemoRecording } from './demo-recording.mjs';
+import { recordPlaywrightDemo } from './playwright-demo.mjs';
+import { validateArtifactRelease } from './artifact-release-gate.mjs';
+import { inferArtifactTypeFromPath } from './artifact-type-from-path.mjs';
+
+export { parsePublishFrontmatter };
+
+export function formatGateFailureMessage(gateResult, { inputPath, cwd = process.cwd() } = {}) {
+  const rel = path.relative(cwd, inputPath);
+  const type = gateResult.type || 'unknown';
+  const lines = [
+    `Publish blocked: artifact release gate failed (${type}: ${rel})`,
+    ...gateResult.errors.map((e) => `  - ${typeof e === 'string' ? e : e.message || String(e)}`),
+  ];
+  if (gateResult.warnings?.length) {
+    lines.push('Warnings:');
+    for (const w of gateResult.warnings) lines.push(`  - ${w}`);
+  }
+  lines.push(
+    '',
+    'Remediation:',
+    `  node bin/construct artifact validate ${rel} --type=${type}`,
+    '  node bin/construct workflow invoke --workflow-type prd-draft --text "…"',
+    '  Run the listed specialists to author the artifact (invoke returns a plan only).',
+    '  See skills/docs/prd-workflow.md — validate must pass before publish.',
+  );
+  return lines.join('\n');
+}
+
+export function runPublish({
+  inputPath,
+  format = 'pdf',
+  outputPath,
+  demos = [],
+  dashboardDemos = [],
+  recordings = [],
+  figures = true,
+  strict = true,
+  sourceOnly = false,
+  gate = true,
+  artifactType = null,
+  cwd = process.cwd(),
+  repoRoot,
+  env = process.env,
+} = {}) {
+  const resolvedIn = path.resolve(cwd, inputPath);
+  if (!fs.existsSync(resolvedIn)) {
+    return { ok: false, message: `Input not found: ${resolvedIn}` };
+  }
+
+  let demoNames = demos;
+  let dashNames = dashboardDemos;
+  let recordingNames = recordings;
+  if (!demoNames.length && !dashNames.length && !recordingNames.length) {
+    const fm = parsePublishFrontmatter(resolvedIn);
+    if (fm?.demo) demoNames = [fm.demo];
+    if (fm?.dashboardDemo) dashNames = [fm.dashboardDemo];
+    if (fm?.recording) recordingNames = [fm.recording];
+  }
+
+  const detection = detectPublishPipeline({
+    format,
+    includeFigures: figures,
+    includeTerminalDemo: demoNames.length > 0 && !sourceOnly,
+    includeDashboardDemo: (dashNames.length > 0 || recordingNames.length > 0) && !sourceOnly,
+    cwd,
+    repoRoot,
+    env,
+  });
+
+  const ledger = { export: null, demos: [], dashboardDemos: [], recordings: [], detection, gate: null };
+  const resolvedType = artifactType || inferArtifactTypeFromPath(resolvedIn, { rootDir: cwd });
+
+  if (gate && !sourceOnly && resolvedType) {
+    ledger.gate = validateArtifactRelease({
+      filePath: resolvedIn,
+      type: resolvedType,
+      cwd,
+      rootDir: repoRoot || cwd,
+    });
+    if (!ledger.gate.ok && strict) {
+      return {
+        ok: false,
+        strict: true,
+        gateBlocked: true,
+        ledger,
+        message: formatGateFailureMessage(ledger.gate, { inputPath: resolvedIn, cwd }),
+      };
+    }
+  }
+
+  if (strict && !sourceOnly && !detection.present) {
+    return { ok: false, strict: true, detection, missing: detection.missing, message: detection.message };
+  }
+
+  if (!sourceOnly) {
+    const publishDir = path.join(cwd, '.cx', 'publish');
+    const defaultOut = path.join(publishDir, `${path.parse(resolvedIn).name}.${format}`);
+    const resolvedOut = outputPath ? path.resolve(cwd, outputPath) : defaultOut;
+
+    ledger.export = exportMarkdown({
+      inputPath: resolvedIn,
+      outputPath: resolvedOut,
+      format,
+      figures: figures && !sourceOnly,
+      artifactType: resolvedType,
+      env,
+      cwd,
+      repoRoot: repoRoot || cwd,
+    });
+
+    if (!ledger.export.ok && strict && !sourceOnly) {
+      return { ok: false, strict: true, ledger, message: ledger.export.message };
+    }
+  } else {
+    ledger.export = { ok: true, skipped: 'source-only' };
+  }
+
+  for (const name of demoNames) {
+    const demoResult = runDemoRecord(name, {
+      cwd,
+      format: 'mp4',
+      sourceOnly: sourceOnly || (!strict && !detection.steps?.terminalDemo?.present),
+      required: strict && !sourceOnly,
+      surface: 'tape',
+    });
+    ledger.demos.push(demoResult);
+    if (strict && !sourceOnly && demoResult.required && !demoResult.ok) {
+      return { ok: false, strict: true, ledger, message: demoResult.message };
+    }
+  }
+
+  for (const name of dashNames) {
+    const dashResult = recordDashboardDemo(name, { cwd, repoRoot, env });
+    ledger.dashboardDemos.push(dashResult);
+    if (strict && !sourceOnly && !dashResult.ok) {
+      return { ok: false, strict: true, ledger, message: dashResult.message };
+    }
+  }
+
+  for (const name of recordingNames) {
+    const recording = loadDemoRecording(name, { cwd, repoRoot: repoRoot || cwd });
+    if (!recording) {
+      const miss = { ok: false, name, message: `Recording not found: ${name}` };
+      ledger.recordings.push(miss);
+      if (strict && !sourceOnly) {
+        return { ok: false, strict: true, ledger, message: miss.message };
+      }
+      continue;
+    }
+    const recResult = recordPlaywrightDemo(recording, { cwd, repoRoot: repoRoot || cwd, env });
+    ledger.recordings.push(recResult);
+    if (strict && !sourceOnly && !recResult.ok) {
+      return { ok: false, strict: true, ledger, message: recResult.message };
+    }
+  }
+
+  return {
+    ok: ledger.export?.ok !== false,
+    ledger,
+    message: ledger.export?.skipped
+      ? 'Publish source-only complete'
+      : ledger.export?.ok
+        ? `Published ${path.relative(cwd, ledger.export.outputPath)}`
+        : ledger.export?.message || detection.message,
+  };
+}
+
+export function printPublishHelp() {
+  console.log(`Usage: construct publish <markdown> [options]
+
+Orchestrates typed artifact distribution: release gate (default), Pandoc export
+with diagram filter and Construct PDF template, optional VHS/Playwright demos.
+
+Options:
+  --to=<format>           ${EXPORT_FORMATS.join(' | ')} (default: pdf)
+  --output=<path>         Output path (default: .cx/publish/<name>.<format>)
+  --type=<doc-type>       Artifact type for release gate (inferred from path when omitted)
+  --demo=<name>           Terminal VHS tape name (repeatable)
+  --dashboard-demo=<name> Playwright demo spec basename (repeatable)
+  --recording=<name>      Playwright recording manifest (repeatable)
+  --no-figures            Skip pandoc-ext/diagram filter
+  --no-gate               Skip artifact release gate (maintainer escape hatch)
+  --source-only           Write sources only; skip rendering
+  --no-strict             Do not exit 2 when toolchain or gate fails
+  --detect                Print tooling JSON and exit
+  -h, --help              Show this message
+
+Frontmatter (optional):
+  publish:
+    demo: resource-guard-rails
+    dashboardDemo: cockpit-tour
+    recording: agentic-platforms-prd
+
+Examples:
+  node bin/construct publish docs/prd-platform/brief.md --strict --figures
+  node bin/construct publish brief.md --type=research-brief --demo=quickstart
+`);
+}
+
+export async function runPublishCli(argv = [], { cwd = process.cwd(), repoRoot } = {}) {
+  const options = {
+    format: 'pdf',
+    output: null,
+    type: null,
+    demos: [],
+    dashboardDemos: [],
+    figures: true,
+    strict: true,
+    gate: true,
+    sourceOnly: false,
+    detect: false,
+    help: false,
+    input: null,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') { options.help = true; continue; }
+    if (arg === '--strict') { options.strict = true; continue; }
+    if (arg === '--no-strict') { options.strict = false; continue; }
+    if (arg === '--source-only') { options.sourceOnly = true; continue; }
+    if (arg === '--no-figures') { options.figures = false; continue; }
+    if (arg === '--no-gate') { options.gate = false; continue; }
+    if (arg === '--detect') { options.detect = true; continue; }
+    if (arg === '--to') { options.format = argv[++i]; continue; }
+    if (arg.startsWith('--to=')) { options.format = arg.slice(5); continue; }
+    if (arg === '--output') { options.output = argv[++i]; continue; }
+    if (arg.startsWith('--output=')) { options.output = arg.slice(9); continue; }
+    if (arg === '--type') { options.type = argv[++i]; continue; }
+    if (arg.startsWith('--type=')) { options.type = arg.slice(7); continue; }
+    if (arg === '--demo') { options.demos.push(argv[++i]); continue; }
+    if (arg.startsWith('--demo=')) { options.demos.push(arg.slice(7)); continue; }
+    if (arg === '--dashboard-demo') { options.dashboardDemos.push(argv[++i]); continue; }
+    if (arg.startsWith('--dashboard-demo=')) { options.dashboardDemos.push(arg.slice(17)); continue; }
+    if (!arg.startsWith('--')) options.input = arg;
+  }
+
+  if (options.help) {
+    printPublishHelp();
+    return { exitCode: 0 };
+  }
+
+  if (options.detect) {
+    const detection = detectPublishPipeline({
+      format: options.format,
+      includeFigures: options.figures,
+      includeTerminalDemo: options.demos.length > 0,
+      includeDashboardDemo: options.dashboardDemos.length > 0,
+      cwd,
+      repoRoot,
+    });
+    console.log(JSON.stringify(detection, null, 2));
+    return { exitCode: detection.present ? 0 : 2 };
+  }
+
+  if (!options.input) {
+    printPublishHelp();
+    return { exitCode: 1 };
+  }
+
+  const result = runPublish({
+    inputPath: options.input,
+    format: options.format,
+    outputPath: options.output,
+    demos: options.demos,
+    dashboardDemos: options.dashboardDemos,
+    figures: options.figures,
+    strict: options.strict,
+    gate: options.gate,
+    artifactType: options.type,
+    sourceOnly: options.sourceOnly,
+    cwd,
+    repoRoot,
+  });
+
+  if (result.ok) {
+    console.log(result.message);
+    if (result.ledger?.demos?.length) {
+      for (const d of result.ledger.demos) {
+        if (d.tapePath) console.log(`  tape: ${d.tapePath}`);
+        if (d.artifactPath) console.log(`  demo: ${d.artifactPath}`);
+      }
+    }
+    return { exitCode: 0, result };
+  }
+
+  console.error(result.message);
+  const exitCode = result.strict && (result.missing?.length || result.gateBlocked) ? 2 : 1;
+  return { exitCode, result };
+}

package/lib/registry/cli.mjs

@@ -0,0 +1,82 @@
+/**
+ * lib/registry/cli.mjs — CLI handlers for registry validate, status, and doc generation.
+ */
+
+import { validateCapabilityRegistry, loadCapabilityRegistry } from './validate.mjs';
+import { generateCapabilitiesDoc, checkCapabilitiesDocDrift } from './generate-docs.mjs';
+import { triageBoundOrphans, formatConsolidationProposalMarkdown } from './consolidation.mjs';
+
+export async function runRegistryStatus(args = [], { rootDir, println = console.log } = {}) {
+  const jsonOutput = args.includes('--json');
+  const { capabilities = [] } = loadCapabilityRegistry({ rootDir });
+
+  if (jsonOutput) {
+    println(JSON.stringify(capabilities, null, 2));
+    return 0;
+  }
+
+  println('Construct Capability Registry');
+  println('='.repeat(40));
+  println('');
+
+  for (const cap of capabilities) {
+    const tier = cap.criticality ?? '—';
+    println(`[${tier}] ${cap.name ?? cap.id} (${cap.id})`);
+    if (cap.description) println(`  ${cap.description}`);
+    const surfaces = Object.entries(cap.surfaces ?? {}).filter(([, v]) => v?.supported);
+    if (surfaces.length) {
+      println(`  surfaces: ${surfaces.map(([n]) => n).join(', ')}`);
+    }
+    const validated = cap.lastValidated ? cap.lastValidated.slice(0, 10) : 'never';
+    println(`  humanGate: ${cap.humanGate ?? '—'}  lastValidated: ${validated}`);
+    println('');
+  }
+  return 0;
+}
+
+export async function runRegistryValidate(args = [], { rootDir, println = console.log, errorln = console.error } = {}) {
+  const jsonOutput = args.includes('--json');
+  const report = validateCapabilityRegistry({ rootDir });
+
+  if (jsonOutput) {
+    println(JSON.stringify(report, null, 2));
+    return report.valid ? 0 : 1;
+  }
+
+  println(`Registry: ${report.registryPath}`);
+  println(`Entries: ${report.count}`);
+  if (report.errors.length) {
+    errorln(`Errors (${report.errors.length}):`);
+    for (const e of report.errors) errorln(`  ✗ ${e}`);
+  }
+  if (report.warnings.length) {
+    println(`Warnings (${report.warnings.length}):`);
+    for (const w of report.warnings) println(`  ⚠ ${w}`);
+  }
+  if (report.valid && !report.warnings.length) println('✓ Registry valid');
+  else if (report.valid) println('✓ Registry valid (with warnings)');
+  else errorln('✗ Registry invalid');
+
+  return report.valid ? 0 : 1;
+}
+
+export async function runRegistryGenerateDocs(args = [], { rootDir, println = console.log, errorln = console.error } = {}) {
+  if (args.includes('--check')) {
+    const { drift } = checkCapabilitiesDocDrift({ rootDir });
+    if (drift) {
+      errorln('capabilities.md drift — run `construct registry:generate-docs`');
+      return 1;
+    }
+    println('capabilities.md is up to date');
+    return 0;
+  }
+  const out = generateCapabilitiesDoc({ rootDir });
+  println(`Generated ${out}`);
+  return 0;
+}
+
+export async function runRegistryConsolidationProposal(args = [], { rootDir, println = console.log } = {}) {
+  const triage = triageBoundOrphans({ rootDir });
+  println(formatConsolidationProposalMarkdown(triage));
+  return 0;
+}

package/lib/registry/consolidation.mjs

@@ -0,0 +1,147 @@
+/**
+ * lib/registry/consolidation.mjs — bound-orphan triage for skill consolidation proposals.
+ *
+ * A bound-orphan is a skill file not declared in any specialist's `skills:` array.
+ * Profile/composer reachability is classified separately — nothing is deleted here.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(MODULE_DIR, '..', '..');
+
+function collectSkillFiles(skillsDir) {
+  const results = [];
+  function walk(dir, prefix = '') {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith('.')) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full, prefix ? `${prefix}/${entry.name}` : entry.name);
+      else if (entry.name.endsWith('.md') && entry.name !== 'routing.md') {
+        results.push(prefix ? `${prefix}/${entry.name.replace(/\.md$/, '')}` : entry.name.replace(/\.md$/, ''));
+      }
+    }
+  }
+  walk(skillsDir);
+  return results;
+}
+
+function roleBase(skill) {
+  const m = skill.match(/^roles\/([^.]+)(?:\..*)?$/);
+  return m ? m[1] : null;
+}
+
+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 */ }
+    }
+  } catch { /* no profiles */ }
+  return roles;
+}
+
+/**
+ * Classify bound-orphans for maintainer approval (bind / merge / composer / review).
+ */
+export function triageBoundOrphans({ rootDir = REPO_ROOT } = {}) {
+  const registry = JSON.parse(fs.readFileSync(path.join(rootDir, 'specialists', 'registry.json'), 'utf8'));
+  const declared = new Set();
+  for (const s of registry.specialists ?? []) for (const sk of s.skills ?? []) declared.add(sk);
+
+  const specialistNames = new Set((registry.specialists ?? []).map((s) => s.name));
+  const profileRoles = collectProfileRoles(rootDir);
+  const all = collectSkillFiles(path.join(rootDir, 'skills'));
+
+  const items = [];
+  for (const skill of all) {
+    if (declared.has(skill)) continue;
+    const base = roleBase(skill);
+    let category = 'D-review';
+    let recommendation = 'Manual review — not declared and no automatic owner signal';
+
+    if (skill.startsWith('docs/') && skill.endsWith('-workflow')) {
+      category = 'A-bind';
+      recommendation = `Bind to owner specialist in registry.json (workflow skill)`;
+    } else if (base && specialistNames.has(base)) {
+      category = 'B-composer';
+      recommendation = `Role flavor for cx-${base} — reachable via prompt-composer; document in registry or bind explicitly`;
+    } else if (base && profileRoles.has(base)) {
+      category = 'B-composer';
+      recommendation = `Profile role "${base}" — may load via profile overlay; verify before merge`;
+    } else if (skill.startsWith('roles/')) {
+      category = 'C-merge';
+      recommendation = 'Consider merging into parent roles/<base>.md or binding to specialist';
+    } else if (skill.startsWith('docs/')) {
+      category = 'A-bind';
+      recommendation = 'Bind to cx-docs-keeper or domain owner specialist';
+    }
+
+    items.push({ skill, category, recommendation });
+  }
+
+  const byCategory = Object.fromEntries(['A-bind', 'B-composer', 'C-merge', 'D-review'].map((c) => [c, []]));
+  for (const item of items) byCategory[item.category].push(item);
+
+  return {
+    declaredCount: declared.size,
+    fileCount: all.length,
+    boundOrphanCount: items.length,
+    composerReachableCount: items.filter((i) => i.category === 'B-composer').length,
+    trueOrphanCount: items.filter((i) => i.category === 'D-review' || i.category === 'C-merge').length,
+    aBindCount: items.filter((i) => i.category === 'A-bind').length,
+    byCategory,
+    items,
+  };
+}
+
+export function formatConsolidationProposalMarkdown(triage, { date = new Date().toISOString().slice(0, 10) } = {}) {
+  const lines = [
+    `# Skill Consolidation Proposal — ${date}`,
+    '',
+    'Gate: **nothing is deleted until the maintainer approves a list.**',
+    '',
+    `Reproduce: \`node -e "import('./lib/registry/consolidation.mjs').then(m => console.log(JSON.stringify(m.triageBoundOrphans(),null,2)))"\``,
+    '',
+    '## Summary',
+    '',
+    `- **${triage.fileCount}** skill files on disk`,
+    `- **${triage.declaredCount}** declared in specialists/registry.json`,
+    `- **${triage.boundOrphanCount}** registry bound-orphans (not declared by any specialist)`,
+    `- **${triage.composerReachableCount}** composer-reachable (B-composer — intentional via prompt composer)`,
+    `- **${triage.trueOrphanCount}** true orphans (C-merge + D-review — need maintainer action)`,
+    '',
+    '## Categories',
+    '',
+    '| Category | Count | Action |',
+    '|---|---:|---|',
+    `| A-bind | ${triage.byCategory['A-bind'].length} | Wire to specialist in registry |`,
+    `| B-composer | ${triage.byCategory['B-composer'].length} | Document composer reachability or bind |`,
+    `| C-merge | ${triage.byCategory['C-merge'].length} | Propose merge into parent role skill |`,
+    `| D-review | ${triage.byCategory['D-review'].length} | Manual review |`,
+    '',
+  ];
+
+  for (const cat of ['A-bind', 'B-composer', 'C-merge', 'D-review']) {
+    const rows = triage.byCategory[cat];
+    if (!rows.length) continue;
+    lines.push(`## ${cat} (${rows.length})`, '');
+    for (const { skill, recommendation } of rows) {
+      lines.push(`- \`skills/${skill}.md\` — ${recommendation}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}

package/lib/registry/generate-docs.mjs

@@ -0,0 +1,75 @@
+/**
+ * lib/registry/generate-docs.mjs — generate reference docs from registry/capabilities.json.
+ *
+ * Writes docs/reference/capabilities.md so the human-readable capability matrix
+ * cannot drift from the machine-readable registry.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { loadCapabilityRegistry } from './validate.mjs';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(MODULE_DIR, '..', '..');
+
+function surfaceSummary(surfaces = {}) {
+  return Object.entries(surfaces)
+    .filter(([, v]) => v?.supported)
+    .map(([name, v]) => {
+      const bits = [name];
+      if (v.primary) bits.push('primary');
+      if (v.tool) bits.push(v.tool);
+      if (v.command) bits.push(v.command);
+      return bits.join(':');
+    })
+    .join(', ') || 'none';
+}
+
+export function generateCapabilitiesDoc({ rootDir = REPO_ROOT, write = true } = {}) {
+  const { capabilities = [] } = loadCapabilityRegistry({ rootDir });
+  const byKind = new Map();
+  for (const cap of capabilities) {
+    const k = cap.kind || 'capability';
+    if (!byKind.has(k)) byKind.set(k, []);
+    byKind.get(k).push(cap);
+  }
+
+  const lines = [
+    '---',
+    'title: Capability Registry',
+    'description: Generated from registry/capabilities.json. Do not edit by hand.',
+    '---',
+    '',
+    '> Generated from `registry/capabilities.json`. Re-run `construct registry:generate-docs` to refresh.',
+    '',
+    `# Capability Registry (${capabilities.length} entries)`,
+    '',
+  ];
+
+  for (const [kind, items] of [...byKind.entries()].sort()) {
+    lines.push(`## ${kind}`, '');
+    lines.push('| ID | Name | Criticality | Surfaces | Human gate | Last validated |');
+    lines.push('|---|---|---|---|---|---|');
+    for (const cap of items.sort((a, b) => a.id.localeCompare(b.id))) {
+      const validated = cap.lastValidated ? cap.lastValidated.slice(0, 10) : 'never';
+      lines.push(
+        `| \`${cap.id}\` | ${cap.name ?? cap.id} | ${cap.criticality ?? '—'} | ${surfaceSummary(cap.surfaces)} | ${cap.humanGate ?? '—'} | ${validated} |`,
+      );
+    }
+    lines.push('');
+  }
+
+  const content = `${lines.join('\n')}\n`;
+  const out = path.join(rootDir, 'docs', 'reference', 'capabilities.md');
+  if (!write) return { out, content, drift: fs.existsSync(out) ? fs.readFileSync(out, 'utf8') !== content : true };
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  fs.writeFileSync(out, content);
+  return out;
+}
+
+export function checkCapabilitiesDocDrift({ rootDir = REPO_ROOT } = {}) {
+  const { content, drift } = generateCapabilitiesDoc({ rootDir, write: false });
+  return { drift, contentLength: content.length };
+}

package/lib/registry/skill-verification.mjs

@@ -0,0 +1,57 @@
+/**
+ * lib/registry/skill-verification.mjs — verification-bar lint for workflow skills.
+ *
+ * docs/*-workflow.md skills must carry inputs, artifactType, and verificationBar
+ * in YAML frontmatter so anti-slop gates apply to the skill layer.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+
+function parseFrontmatter(content) {
+  const match = content.match(FRONTMATTER_RE);
+  if (!match) return null;
+  try {
+    return yaml.load(match[1]) || {};
+  } catch {
+    return null;
+  }
+}
+
+export function lintWorkflowSkillVerification(skillsRoot) {
+  const errors = [];
+  const warnings = [];
+  const docsDir = path.join(skillsRoot, 'docs');
+  if (!fs.existsSync(docsDir)) return { valid: true, errors, warnings, checked: 0 };
+
+  for (const entry of fs.readdirSync(docsDir)) {
+    if (!entry.endsWith('-workflow.md')) continue;
+    const rel = `docs/${entry.replace(/\.md$/, '')}`;
+    const filePath = path.join(docsDir, entry);
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const fm = parseFrontmatter(raw);
+    if (!fm) {
+      errors.push(`${rel}: missing or invalid YAML frontmatter`);
+      continue;
+    }
+    if (!fm.inputs || !Array.isArray(fm.inputs) || fm.inputs.length === 0) {
+      warnings.push(`${rel}: missing frontmatter.inputs`);
+    }
+    if (!fm.artifactType || typeof fm.artifactType !== 'string') {
+      warnings.push(`${rel}: missing frontmatter.artifactType`);
+    }
+    if (!fm.verificationBar || typeof fm.verificationBar !== 'string') {
+      warnings.push(`${rel}: missing frontmatter.verificationBar`);
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    checked: fs.readdirSync(docsDir).filter((f) => f.endsWith('-workflow.md')).length,
+  };
+}