infernoflow 0.10.23 → 0.10.26

package/dist/lib/commands/changelog.mjs

@@ -1,21 +1,343 @@
-import*as g from"node:fs";import*as S from"node:path";import{execSync as v}from"node:child_process";import{header as O,ok as R,fail as C,warn as m,info as b,done as G,bold as E,cyan as h,gray as f,green as F,yellow as L}from"../ui/output.mjs";function p(e,n){try{return v(e,{cwd:n,encoding:"utf8",stdio:["ignore","pipe","pipe"]}).trim()}catch{return null}}function y(e){return p("git describe --tags --abbrev=0",e)}function $(e,n){const o=e?`${e}..HEAD`:"",t=p(`git log ${o} --format=%H%x1f%s%x1f%b%x1e`,n);return t?t.split("").map(s=>s.trim()).filter(Boolean).map(s=>{const r=s.split("");return{hash:(r[0]||"").trim().slice(0,8),subject:(r[1]||"").trim(),body:(r[2]||"").trim()}}).filter(s=>s.subject):[]}function M(e,n){return p(`git log -1 --format=%ci "${e}"`,n)?.slice(0,10)||null}const w={feat:"Added",feature:"Added",add:"Added",fix:"Fixed",bugfix:"Fixed",hotfix:"Fixed",perf:"Changed",refactor:"Changed",change:"Changed",chore:"Changed",docs:"Changed",style:"Changed",test:"Changed",ci:"Changed",remove:"Removed",revert:"Removed",deprecate:"Removed"};function x(e){const n=e.match(/^(\w+)(?:\([^)]+\))?[!]?:\s*(.+)/);if(n){const t=n[1].toLowerCase();return{section:w[t]||"Changed",message:n[2].trim(),breaking:e.includes("!")}}const o=e.toLowerCase();for(const[t,s]of Object.entries(w))if(o.startsWith(t+" ")||o.startsWith(t+":"))return{section:s,message:e,breaking:!1};return{section:"Changed",message:e,breaking:!1}}function j(e){const n={Added:[],Fixed:[],Changed:[],Removed:[],Breaking:[]};for(const o of e){const{section:t,message:s,breaking:r}=x(o.subject);r&&n.Breaking.push(s),n[t].push(s)}for(const o of Object.keys(n))n[o]=[...new Set(n[o])];return n}function H(e,n){const o=["## Unreleased",""];n&&o.push(`> Changes since ${n}`,"");const t=["Breaking","Added","Fixed","Changed","Removed"];let s=!1;for(const r of t){const i=e[r];if(!(!i||!i.length)){s=!0,o.push(`### ${r}`);for(const c of i)o.push(`- ${c}`);o.push("")}}return s||o.push("- No significant changes",""),o.join(`
-`)}function k(e){return g.existsSync(e)?g.readFileSync(e,"utf8"):null}function D(e){const n=e.match(/^## Unreleased[\s\S]*?(?=\n## |\n---|\z)/im);return n?n[0].trim():null}function U(e,n){return/^## Unreleased/im.test(e)?e.replace(/^## Unreleased[\s\S]*?(?=\n## |\n---)/im,n+`
-
-`):/^# .+/im.test(e)?e.replace(/^(# .+\n)/im,`$1
-${n}
-
-`):`${n}
-
-${e}`}function J(e,n){const o=n.split(`
-`).filter(t=>t.startsWith("- ")).join(`
-`);return o?/^## Unreleased/im.test(e)?e.replace(/(^## Unreleased[\s\S]*?)(\n## )/im,`$1
-${o}
-$2`):U(e,n):e}function W(e,n){const o=n||y(e),t=$(o,e);if(!t.length){b(`No commits since ${o||"beginning"}`);return}console.log(`
-  ${E("Commits since")} ${h(o||"beginning")}  ${f("("+t.length+")")}
-`);for(const s of t){const{section:r}=x(s.subject),i=r==="Added"?F:r==="Fixed"?L:f;console.log(`  ${f(s.hash)}  ${i(s.subject)}`)}console.log()}function B(e){const n=k(e);if(!n){C("CHANGELOG.md not found");return}const o=D(n);if(!o){m("No ## Unreleased section found in CHANGELOG.md");return}console.log(`
-`+o+`
-`)}async function T(e,n,o){const{ref:t,dryRun:s,append:r,asJson:i}=o,c=t||y(e),a=$(c,e);if(!a.length){if(i){console.log(JSON.stringify({ok:!0,ref:c,commits:0,message:"No new commits"}));return}m(`No commits found since ${c||"beginning of repo"}`),console.log();return}const d=j(a),l=H(d,c);if(i){console.log(JSON.stringify({ok:!0,ref:c,commits:a.length,sections:{breaking:d.Breaking,added:d.Added,fixed:d.Fixed,changed:d.Changed,removed:d.Removed},markdown:l},null,2));return}if(console.log(),console.log(f("  \u2500\u2500\u2500 Drafted entry \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500")),l.split(`
-`).forEach(N=>console.log("  "+N)),console.log(f("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500")),console.log(),b(`${a.length} commit${a.length>1?"s":""} since ${h(c||"beginning")}`),s){m("Dry run \u2014 CHANGELOG.md not modified"),console.log();return}let u=k(n);u||(u=`# Changelog
-
-`);const A=r?J(u,l):U(u,l);g.writeFileSync(n,A),R(`CHANGELOG.md updated  ${f("("+(r?"appended":"replaced")+" ## Unreleased)")}`),console.log(),G("Changelog drafted \u2014 review and edit before your next release"),console.log(`  Run ${h("infernoflow publish")} when ready to cut the release
-`)}async function P(e){const n=e.slice(1),o=n.find(l=>!l.startsWith("-"))||"update",t=n.includes("--dry-run"),s=n.includes("--append"),r=n.includes("--json"),i=n.indexOf("--ref"),c=i!==-1?n[i+1]:null,a=process.cwd(),d=S.join(a,"CHANGELOG.md");if(r||O("changelog "+o),o==="list"){W(a,c);return}if(o==="show"){B(d);return}if(o==="update"){await T(a,d,{ref:c,dryRun:t,append:s,asJson:r});return}C(`Unknown sub-command: ${o}`,"Use: update | show | list"),process.exit(1)}export{P as changelogCommand};
+/**
+ * infernoflow changelog update
+ *
+ * Reads git commits since the last tag, groups them by type (feat/fix/chore/…),
+ * drafts a clean ## Unreleased section, and writes it into CHANGELOG.md.
+ *
+ * Sub-commands:
+ *   infernoflow changelog update      # draft Unreleased from commits
+ *   infernoflow changelog show        # print current Unreleased block
+ *   infernoflow changelog list        # list commits since last tag
+ *
+ * Flags (update):
+ *   --ref <tag|commit>   Compare from a specific ref instead of last tag
+ *   --dry-run            Print what would be written without touching the file
+ *   --append             Append to existing ## Unreleased instead of replacing it
+ *   --json               Machine-readable output
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { execSync } from "node:child_process";
+import { header, ok, fail, warn, info, done, bold, cyan, gray, green, yellow } from "../ui/output.mjs";
+
+// ── git helpers ──────────────────────────────────────────────────────────────
+
+function capture(cmd, cwd) {
+  try {
+    return execSync(cmd, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function lastTag(cwd) {
+  return capture("git describe --tags --abbrev=0", cwd);
+}
+
+function commitsSince(ref, cwd) {
+  // Returns array of { hash, subject, body }
+  // Use NUL-delimited output to avoid shell escaping issues with separators
+  const range = ref ? `${ref}..HEAD` : "";
+  const raw = capture(`git log ${range} --format=%H%x1f%s%x1f%b%x1e`, cwd);
+  if (!raw) return [];
+
+  return raw
+    .split("\x1e")
+    .map(s => s.trim())
+    .filter(Boolean)
+    .map(block => {
+      const parts = block.split("\x1f");
+      return {
+        hash:    (parts[0] || "").trim().slice(0, 8),
+        subject: (parts[1] || "").trim(),
+        body:    (parts[2] || "").trim(),
+      };
+    })
+    .filter(c => c.subject);
+}
+
+function refDate(ref, cwd) {
+  return capture(`git log -1 --format=%ci "${ref}"`, cwd)?.slice(0, 10) || null;
+}
+
+// ── commit classification ────────────────────────────────────────────────────
+
+const TYPE_MAP = {
+  feat:     "Added",
+  feature:  "Added",
+  add:      "Added",
+  fix:      "Fixed",
+  bugfix:   "Fixed",
+  hotfix:   "Fixed",
+  perf:     "Changed",
+  refactor: "Changed",
+  change:   "Changed",
+  chore:    "Changed",
+  docs:     "Changed",
+  style:    "Changed",
+  test:     "Changed",
+  ci:       "Changed",
+  remove:   "Removed",
+  revert:   "Removed",
+  deprecate:"Removed",
+};
+
+function classifyCommit(subject) {
+  // Conventional commits: "feat: ..." or "feat(scope): ..."
+  const match = subject.match(/^(\w+)(?:\([^)]+\))?[!]?:\s*(.+)/);
+  if (match) {
+    const type = match[1].toLowerCase();
+    return {
+      section: TYPE_MAP[type] || "Changed",
+      message: match[2].trim(),
+      breaking: subject.includes("!"),
+    };
+  }
+
+  // Heuristic: starts with a keyword
+  const lower = subject.toLowerCase();
+  for (const [keyword, section] of Object.entries(TYPE_MAP)) {
+    if (lower.startsWith(keyword + " ") || lower.startsWith(keyword + ":")) {
+      return { section, message: subject, breaking: false };
+    }
+  }
+
+  return { section: "Changed", message: subject, breaking: false };
+}
+
+function groupCommits(commits) {
+  const sections = { Added: [], Fixed: [], Changed: [], Removed: [], Breaking: [] };
+
+  for (const c of commits) {
+    const { section, message, breaking } = classifyCommit(c.subject);
+    if (breaking) sections.Breaking.push(message);
+    sections[section].push(message);
+  }
+
+  // Remove duplicates (some commits end up in Breaking AND their category)
+  for (const key of Object.keys(sections)) {
+    sections[key] = [...new Set(sections[key])];
+  }
+
+  return sections;
+}
+
+// ── markdown rendering ───────────────────────────────────────────────────────
+
+function renderUnreleased(sections, ref) {
+  const lines = ["## Unreleased", ""];
+
+  if (ref) {
+    lines.push(`> Changes since ${ref}`, "");
+  }
+
+  const ORDER = ["Breaking", "Added", "Fixed", "Changed", "Removed"];
+  let hasContent = false;
+
+  for (const heading of ORDER) {
+    const items = sections[heading];
+    if (!items || !items.length) continue;
+    hasContent = true;
+    lines.push(`### ${heading}`);
+    for (const item of items) {
+      lines.push(`- ${item}`);
+    }
+    lines.push("");
+  }
+
+  if (!hasContent) {
+    lines.push("- No significant changes", "");
+  }
+
+  return lines.join("\n");
+}
+
+// ── CHANGELOG file operations ────────────────────────────────────────────────
+
+function readChangelog(changelogPath) {
+  if (!fs.existsSync(changelogPath)) return null;
+  return fs.readFileSync(changelogPath, "utf8");
+}
+
+function extractUnreleased(text) {
+  // Returns the content of the ## Unreleased block, or null
+  const match = text.match(/^## Unreleased[\s\S]*?(?=\n## |\n---|\z)/im);
+  return match ? match[0].trim() : null;
+}
+
+function injectUnreleased(text, newBlock) {
+  // Replace existing ## Unreleased block
+  if (/^## Unreleased/im.test(text)) {
+    return text.replace(
+      /^## Unreleased[\s\S]*?(?=\n## |\n---)/im,
+      newBlock + "\n\n"
+    );
+  }
+
+  // No existing Unreleased block — insert after the first # heading
+  if (/^# .+/im.test(text)) {
+    return text.replace(
+      /^(# .+\n)/im,
+      `$1\n${newBlock}\n\n`
+    );
+  }
+
+  // Prepend
+  return `${newBlock}\n\n${text}`;
+}
+
+function appendToUnreleased(text, newBlock) {
+  // Extract just the bullet lines from newBlock and append to existing Unreleased
+  const newLines = newBlock.split("\n").filter(l => l.startsWith("- ")).join("\n");
+  if (!newLines) return text;
+
+  if (/^## Unreleased/im.test(text)) {
+    // Find end of Unreleased and insert before next section
+    return text.replace(
+      /(^## Unreleased[\s\S]*?)(\n## )/im,
+      `$1\n${newLines}\n$2`
+    );
+  }
+
+  return injectUnreleased(text, newBlock);
+}
+
+// ── sub-commands ─────────────────────────────────────────────────────────────
+
+function subcmdList(cwd, ref) {
+  const tag = ref || lastTag(cwd);
+  const commits = commitsSince(tag, cwd);
+
+  if (!commits.length) {
+    info(`No commits since ${tag || "beginning"}`);
+    return;
+  }
+
+  console.log(`\n  ${bold("Commits since")} ${cyan(tag || "beginning")}  ${gray("(" + commits.length + ")")}\n`);
+  for (const c of commits) {
+    const { section } = classifyCommit(c.subject);
+    const color = section === "Added" ? green : section === "Fixed" ? yellow : gray;
+    console.log(`  ${gray(c.hash)}  ${color(c.subject)}`);
+  }
+  console.log();
+}
+
+function subcmdShow(changelogPath) {
+  const text = readChangelog(changelogPath);
+  if (!text) {
+    fail("CHANGELOG.md not found");
+    return;
+  }
+  const block = extractUnreleased(text);
+  if (!block) {
+    warn("No ## Unreleased section found in CHANGELOG.md");
+    return;
+  }
+  console.log("\n" + block + "\n");
+}
+
+async function subcmdUpdate(cwd, changelogPath, opts) {
+  const { ref, dryRun, append, asJson } = opts;
+
+  const tag = ref || lastTag(cwd);
+  const commits = commitsSince(tag, cwd);
+
+  if (!commits.length) {
+    if (asJson) {
+      console.log(JSON.stringify({ ok: true, ref: tag, commits: 0, message: "No new commits" }));
+      return;
+    }
+    warn(`No commits found since ${tag || "beginning of repo"}`);
+    console.log();
+    return;
+  }
+
+  const sections = groupCommits(commits);
+  const newBlock  = renderUnreleased(sections, tag);
+
+  if (asJson) {
+    console.log(JSON.stringify({
+      ok: true,
+      ref: tag,
+      commits: commits.length,
+      sections: {
+        breaking: sections.Breaking,
+        added:    sections.Added,
+        fixed:    sections.Fixed,
+        changed:  sections.Changed,
+        removed:  sections.Removed,
+      },
+      markdown: newBlock,
+    }, null, 2));
+    return;
+  }
+
+  // Print the drafted block
+  console.log();
+  console.log(gray("  ─── Drafted entry ─────────────────────────────────"));
+  newBlock.split("\n").forEach(l => console.log("  " + l));
+  console.log(gray("  ────────────────────────────────────────────────────"));
+  console.log();
+  info(`${commits.length} commit${commits.length > 1 ? "s" : ""} since ${cyan(tag || "beginning")}`);
+
+  if (dryRun) {
+    warn("Dry run — CHANGELOG.md not modified");
+    console.log();
+    return;
+  }
+
+  // Write to CHANGELOG.md
+  let text = readChangelog(changelogPath);
+  if (!text) {
+    // Create a fresh changelog
+    text = `# Changelog\n\n`;
+  }
+
+  const updated = append ? appendToUnreleased(text, newBlock) : injectUnreleased(text, newBlock);
+  fs.writeFileSync(changelogPath, updated);
+
+  ok(`CHANGELOG.md updated  ${gray("(" + (append ? "appended" : "replaced") + " ## Unreleased)")}`);
+  console.log();
+  done("Changelog drafted — review and edit before your next release");
+  console.log(`  Run ${cyan("infernoflow publish")} when ready to cut the release\n`);
+}
+
+// ── main ─────────────────────────────────────────────────────────────────────
+
+export async function changelogCommand(rawArgs) {
+  const args = rawArgs.slice(1); // drop "changelog"
+
+  // Sub-command: first non-flag arg
+  const sub = args.find(a => !a.startsWith("-")) || "update";
+
+  const dryRun = args.includes("--dry-run");
+  const append = args.includes("--append");
+  const asJson = args.includes("--json");
+
+  const refIdx = args.indexOf("--ref");
+  const ref    = refIdx !== -1 ? args[refIdx + 1] : null;
+
+  const cwd           = process.cwd();
+  const changelogPath = path.join(cwd, "CHANGELOG.md");
+
+  if (!asJson) header("changelog " + sub);
+
+  if (sub === "list") {
+    subcmdList(cwd, ref);
+    return;
+  }
+
+  if (sub === "show") {
+    subcmdShow(changelogPath);
+    return;
+  }
+
+  if (sub === "update") {
+    await subcmdUpdate(cwd, changelogPath, { ref, dryRun, append, asJson });
+    return;
+  }
+
+  fail(`Unknown sub-command: ${sub}`, "Use: update | show | list");
+  process.exit(1);
+}

package/dist/lib/commands/check.mjs

@@ -1,3 +1,179 @@
-import*as c from"node:fs";import*as l from"node:path";import{header as v,ok as f,fail as o,warn as E,section as g,done as A,errorAndExit as N,bold as w,red as I,yellow as J}from"../ui/output.mjs";import{docGateCommand as F}from"./docGate.mjs";function O(s,t=!1){try{return JSON.parse(c.readFileSync(s,"utf8"))}catch{if(t)throw new Error(`Cannot parse ${l.basename(s)}`);N(`Cannot parse ${l.basename(s)}`,`Check JSON syntax in: ${s}`)}}function H(s){return c.existsSync(s)?c.readdirSync(s).filter(t=>t.endsWith(".json")).map(t=>l.join(s,t)):[]}function L(s){const t=new Set;for(const a of s)try{(JSON.parse(c.readFileSync(a,"utf8")).capabilitiesCovered||[]).forEach(e=>t.add(e))}catch{}return t}async function B(s){const t=process.cwd(),a=l.join(t,"inferno"),m=s.includes("--skip-doc-gate"),e=s.includes("--json");e||v("check");const i=[],d=[];c.existsSync(a)||(e&&(console.log(JSON.stringify({ok:!1,errors:["inferno/ not found"]})),process.exit(1)),N("inferno/ not found","Run: infernoflow init"));const b=l.join(a,"contract.json"),S=l.join(a,"capabilities.json"),$=l.join(a,"scenarios"),C=l.join(a,"CHANGELOG.md");if(e||g("Contract"),!c.existsSync(b))o("contract.json not found","Run: infernoflow init"),i.push("contract.json missing");else{let r;try{r=O(b,e)}catch(p){i.push(p.message),e||(o(p.message),process.exit(1)),console.log(JSON.stringify({ok:!1,errors:i,warnings:d},null,2)),process.exit(1)}const h=r.capabilities||[];if(r.policyId?e||f(`policyId: ${w(r.policyId)}`):(o("policyId missing"),i.push("policyId missing")),Number.isInteger(r.policyVersion)?e||f(`policyVersion: ${w("v"+r.policyVersion)}`):(o("policyVersion must be an integer"),i.push("policyVersion invalid")),h.length===0?(o("capabilities array is empty"),i.push("no capabilities")):e||f(`${h.length} capabilities declared`),e||g("Capabilities Registry"),!c.existsSync(S))o("capabilities.json not found"),i.push("capabilities.json missing");else{let p;try{p=O(S,e)}catch(n){i.push(n.message),e||(o(n.message),process.exit(1)),console.log(JSON.stringify({ok:!1,errors:i,warnings:d},null,2)),process.exit(1)}const j=new Set((p.capabilities||[]).map(n=>n?.id).filter(Boolean)),x=h.filter(n=>!j.has(n));x.length>0?x.forEach(n=>{e||o(`"${n}" in contract but missing from capabilities.json`,"Add it to inferno/capabilities.json"),i.push(`"${n}" not registered`)}):e||f(`All ${j.size} capabilities registered`),e||g("Scenarios");const y=H($);if(y.length===0)E("No scenarios found"),d.push("no scenarios");else{const n=L(y),k=r?.rules?.requireScenarioForEachCapability!==!1,G=h.filter(u=>!n.has(u));e||f(`${y.length} scenario file(s) found`),G.length>0&&k?G.forEach(u=>{e||o(`"${u}" has no scenario coverage`,"Add to capabilitiesCovered in a scenario file"),i.push(`"${u}" uncovered`)}):e||f("All capabilities covered by scenarios")}}}if(e||g("Changelog"),!c.existsSync(C))o("inferno/CHANGELOG.md not found"),i.push("CHANGELOG missing");else{const r=c.readFileSync(C,"utf8");/##\s+Unreleased/i.test(r)?e||f("CHANGELOG.md has ## Unreleased section"):(o("Missing '## Unreleased' section","Add it to inferno/CHANGELOG.md"),i.push("CHANGELOG missing Unreleased"))}if(m||(e||g("Doc Gate"),await F({silent:e,captureExit:!0}).catch(()=>{i.push("doc-gate failed")})),e){console.log(JSON.stringify({ok:i.length===0,errors:i,warnings:d},null,2)),i.length>0&&process.exit(1);return}console.log(),i.length>0?(console.log("  "+I(`\u2718 check failed \u2014 ${i.length} error(s)
-`)),process.exit(1)):d.length>0?console.log("  "+J(`\u26A0  check passed with ${d.length} warning(s)
-`)):A("check passed \u2014 everything is in sync")}export{B as checkCommand};
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { header, ok, fail, warn, info, section, done, errorAndExit, cyan, bold, red, green, yellow, gray } from "../ui/output.mjs";
+import { docGateCommand } from "./docGate.mjs";
+
+function readJson(filePath, jsonOut = false) {
+  try { return JSON.parse(fs.readFileSync(filePath, "utf8")); }
+  catch (err) {
+    if (jsonOut) {
+      throw new Error(`Cannot parse ${path.basename(filePath)}`);
+    }
+    errorAndExit(
+      `Cannot parse ${path.basename(filePath)}`,
+      `Check JSON syntax in: ${filePath}`
+    );
+  }
+}
+
+function getScenarioFiles(scenariosDir) {
+  if (!fs.existsSync(scenariosDir)) return [];
+  return fs.readdirSync(scenariosDir)
+    .filter(f => f.endsWith(".json"))
+    .map(f => path.join(scenariosDir, f));
+}
+
+function getCovered(scenarioFiles) {
+  const covered = new Set();
+  for (const f of scenarioFiles) {
+    try {
+      const s = JSON.parse(fs.readFileSync(f, "utf8"));
+      (s.capabilitiesCovered || []).forEach(c => covered.add(c));
+    } catch {}
+  }
+  return covered;
+}
+
+export async function checkCommand(args) {
+  const cwd = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+  const skipDocGate = args.includes("--skip-doc-gate");
+  const jsonOut = args.includes("--json");
+
+  if (!jsonOut) header("check");
+
+  const errors = [];
+  const warnings = [];
+
+  // ── inferno/ exists ─────────────────────────────────────────────
+  if (!fs.existsSync(infernoDir)) {
+    if (jsonOut) { console.log(JSON.stringify({ ok: false, errors: ["inferno/ not found"] })); process.exit(1); }
+    errorAndExit("inferno/ not found", `Run: infernoflow init`);
+  }
+
+  // ── contract.json ───────────────────────────────────────────────
+  const contractPath = path.join(infernoDir, "contract.json");
+  const capsPath = path.join(infernoDir, "capabilities.json");
+  const scenariosDir = path.join(infernoDir, "scenarios");
+  const changelogPath = path.join(infernoDir, "CHANGELOG.md");
+
+  if (!jsonOut) section("Contract");
+  if (!fs.existsSync(contractPath)) {
+    fail("contract.json not found", "Run: infernoflow init");
+    errors.push("contract.json missing");
+  } else {
+    let contract;
+    try {
+      contract = readJson(contractPath, jsonOut);
+    } catch (err) {
+      errors.push(err.message);
+      if (!jsonOut) {
+        fail(err.message);
+        process.exit(1);
+      }
+      console.log(JSON.stringify({ ok: false, errors, warnings }, null, 2));
+      process.exit(1);
+    }
+    const caps = contract.capabilities || [];
+
+    if (!contract.policyId) { fail("policyId missing"); errors.push("policyId missing"); }
+    else if (!jsonOut) ok(`policyId: ${bold(contract.policyId)}`);
+
+    if (!Number.isInteger(contract.policyVersion)) { fail("policyVersion must be an integer"); errors.push("policyVersion invalid"); }
+    else if (!jsonOut) ok(`policyVersion: ${bold("v" + contract.policyVersion)}`);
+
+    if (caps.length === 0) { fail("capabilities array is empty"); errors.push("no capabilities"); }
+    else if (!jsonOut) ok(`${caps.length} capabilities declared`);
+
+    // ── capabilities.json ────────────────────────────────────────
+    if (!jsonOut) section("Capabilities Registry");
+    if (!fs.existsSync(capsPath)) {
+      fail("capabilities.json not found"); errors.push("capabilities.json missing");
+    } else {
+      let registry;
+      try {
+        registry = readJson(capsPath, jsonOut);
+      } catch (err) {
+        errors.push(err.message);
+        if (!jsonOut) {
+          fail(err.message);
+          process.exit(1);
+        }
+        console.log(JSON.stringify({ ok: false, errors, warnings }, null, 2));
+        process.exit(1);
+      }
+      const registryIds = new Set((registry.capabilities || []).map(c => c?.id).filter(Boolean));
+
+      const missingInRegistry = caps.filter(c => !registryIds.has(c));
+      if (missingInRegistry.length > 0) {
+        missingInRegistry.forEach(c => {
+          if (!jsonOut) fail(`"${c}" in contract but missing from capabilities.json`, `Add it to inferno/capabilities.json`);
+          errors.push(`"${c}" not registered`);
+        });
+      } else if (!jsonOut) {
+        ok(`All ${registryIds.size} capabilities registered`);
+      }
+
+      // ── scenarios ───────────────────────────────────────────────
+      if (!jsonOut) section("Scenarios");
+      const scenarioFiles = getScenarioFiles(scenariosDir);
+      if (scenarioFiles.length === 0) {
+        warn("No scenarios found"); warnings.push("no scenarios");
+      } else {
+        const covered = getCovered(scenarioFiles);
+        const requireCoverage = contract?.rules?.requireScenarioForEachCapability !== false;
+        const uncovered = caps.filter(c => !covered.has(c));
+
+        if (!jsonOut) ok(`${scenarioFiles.length} scenario file(s) found`);
+
+        if (uncovered.length > 0 && requireCoverage) {
+          uncovered.forEach(c => {
+            if (!jsonOut) fail(`"${c}" has no scenario coverage`, `Add to capabilitiesCovered in a scenario file`);
+            errors.push(`"${c}" uncovered`);
+          });
+        } else if (!jsonOut) {
+          ok(`All capabilities covered by scenarios`);
+        }
+      }
+    }
+  }
+
+  // ── CHANGELOG ────────────────────────────────────────────────────
+  if (!jsonOut) section("Changelog");
+  if (!fs.existsSync(changelogPath)) {
+    fail("inferno/CHANGELOG.md not found"); errors.push("CHANGELOG missing");
+  } else {
+    const txt = fs.readFileSync(changelogPath, "utf8");
+    if (!/##\s+Unreleased/i.test(txt)) {
+      fail("Missing '## Unreleased' section", "Add it to inferno/CHANGELOG.md");
+      errors.push("CHANGELOG missing Unreleased");
+    } else if (!jsonOut) {
+      ok("CHANGELOG.md has ## Unreleased section");
+    }
+  }
+
+  // ── doc-gate ─────────────────────────────────────────────────────
+  if (!skipDocGate) {
+    if (!jsonOut) section("Doc Gate");
+    await docGateCommand({ silent: jsonOut, captureExit: true }).catch(() => {
+      errors.push("doc-gate failed");
+    });
+  }
+
+  // ── Summary ──────────────────────────────────────────────────────
+  if (jsonOut) {
+    console.log(JSON.stringify({ ok: errors.length === 0, errors, warnings }, null, 2));
+    if (errors.length > 0) process.exit(1);
+    return;
+  }
+
+  console.log();
+  if (errors.length > 0) {
+    console.log("  " + red(`✘ check failed — ${errors.length} error(s)\n`));
+    process.exit(1);
+  } else if (warnings.length > 0) {
+    console.log("  " + yellow(`⚠  check passed with ${warnings.length} warning(s)\n`));
+  } else {
+    done("check passed — everything is in sync");
+  }
+}