infernoflow 0.33.0 → 0.34.0

package/dist/lib/commands/check.mjs

@@ -1,3 +1,184 @@
-import*as c from"node:fs";import*as l from"node:path";import{header as E,ok as p,fail as t,warn as G,section as g,done as I,errorAndExit as N,bold as w,red as J,yellow as F}from"../ui/output.mjs";import{docGateCommand as H}from"./docGate.mjs";function O(s,o=!1){try{return JSON.parse(c.readFileSync(s,"utf8"))}catch{if(o)throw new Error(`Cannot parse ${l.basename(s)}`);N(`Cannot parse ${l.basename(s)}`,`Check JSON syntax in: ${s}`)}}function L(s){return c.existsSync(s)?c.readdirSync(s).filter(o=>o.endsWith(".json")).map(o=>l.join(s,o)):[]}function V(s){const o=new Set;for(const a of s)try{(JSON.parse(c.readFileSync(a,"utf8")).capabilitiesCovered||[]).forEach(e=>o.add(e))}catch{}return o}async function M(s){const o=process.cwd(),a=l.join(o,"inferno"),m=s.includes("--skip-doc-gate"),e=s.includes("--json");e||E("check");const i=[],f=[];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))t("contract.json not found","Run: infernoflow init"),i.push("contract.json missing");else{let r;try{r=O(b,e)}catch(d){i.push(d.message),e||(t(d.message),process.exit(1)),console.log(JSON.stringify({ok:!1,errors:i,warnings:f},null,2)),process.exit(1)}const h=r.capabilities||[];if(r.policyId?e||p(`policyId: ${w(r.policyId)}`):(t("policyId missing"),i.push("policyId missing")),Number.isInteger(r.policyVersion)?e||p(`policyVersion: ${w("v"+r.policyVersion)}`):(t("policyVersion must be an integer"),i.push("policyVersion invalid")),h.length===0?(t("capabilities array is empty"),i.push("no capabilities")):e||p(`${h.length} capabilities declared`),e||g("Capabilities Registry"),!c.existsSync(S))t("capabilities.json not found"),i.push("capabilities.json missing");else{let d;try{d=O(S,e)}catch(n){i.push(n.message),e||(t(n.message),process.exit(1)),console.log(JSON.stringify({ok:!1,errors:i,warnings:f},null,2)),process.exit(1)}const k=Array.isArray(d)?d:d.capabilities||[],j=new Set(k.map(n=>n?.id).filter(Boolean)),x=h.filter(n=>!j.has(n));x.length>0?x.forEach(n=>{e||t(`"${n}" in contract but missing from capabilities.json`,"Add it to inferno/capabilities.json"),i.push(`"${n}" not registered`)}):e||p(`All ${j.size} capabilities registered`),e||g("Scenarios");const y=L($);if(y.length===0)G("No scenarios found"),f.push("no scenarios");else{const n=V(y),v=r?.rules?.requireScenarioForEachCapability!==!1,A=h.filter(u=>!n.has(u));e||p(`${y.length} scenario file(s) found`),A.length>0&&v?A.forEach(u=>{e||G(`"${u}" has no scenario coverage`,"Add to capabilitiesCovered in a scenario file"),f.push(`"${u}" uncovered`)}):e||p("All capabilities covered by scenarios")}}}if(e||g("Changelog"),!c.existsSync(C))t("inferno/CHANGELOG.md not found"),i.push("CHANGELOG missing");else{const r=c.readFileSync(C,"utf8");/##\s+Unreleased/i.test(r)?e||p("CHANGELOG.md has ## Unreleased section"):(t("Missing '## Unreleased' section","Add it to inferno/CHANGELOG.md"),i.push("CHANGELOG missing Unreleased"))}if(m||(e||g("Doc Gate"),await H({silent:e,captureExit:!0}).catch(()=>{i.push("doc-gate failed")})),e){console.log(JSON.stringify({ok:i.length===0,errors:i,warnings:f},null,2)),i.length>0&&process.exit(1);return}console.log(),i.length>0?(console.log("  "+J(`\u2718 check failed \u2014 ${i.length} error(s)
-`)),process.exit(1)):f.length>0?console.log("  "+F(`\u26A0  check passed with ${f.length} warning(s)
-`)):I("check passed \u2014 everything is in sync")}export{M 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);
+      }
+      // Support both bare array format (written by scan) and { capabilities: [...] } object format
+      const regArray = Array.isArray(registry) ? registry : (registry.capabilities || []);
+      const registryIds = new Set(regArray.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) {
+          // Scenario coverage is advisory — missing coverage is a warning, not a hard error.
+          // This allows `infernoflow_apply` to add new capabilities without immediately
+          // requiring scenarios (which can't exist for brand-new capabilities yet).
+          uncovered.forEach(c => {
+            if (!jsonOut) warn(`"${c}" has no scenario coverage`, `Add to capabilitiesCovered in a scenario file`);
+            warnings.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");
+  }
+}

package/dist/lib/commands/ci.mjs

@@ -1,3 +1,208 @@
-import*as d from"node:fs";import*as p from"node:path";import{fileURLToPath as m}from"node:url";import{spawnSync as h}from"node:child_process";import"../ui/output.mjs";function b(){return process.env.GITHUB_ACTIONS==="true"?"github":process.env.GITLAB_CI==="true"?"gitlab":process.env.BITBUCKET_BUILD_NUMBER?"bitbucket":process.env.CIRCLECI==="true"?"circleci":process.env.JENKINS_URL?"jenkins":process.env.CI==="true"?"generic":"local"}function w(n,e){try{const[f,...t]=n.split(" "),o=h(process.execPath,[p.join(p.dirname(p.dirname(m(import.meta.url))),"..","bin","infernoflow.mjs"),...n.split(" ").slice(1)],{cwd:e,encoding:"utf8",timeout:3e4}).stdout?.trim();if(o)return JSON.parse(o)}catch{}return null}function P(n,e){try{return h(process.execPath,[p.join(p.dirname(p.dirname(m(import.meta.url))),"..","bin","infernoflow.mjs"),...n],{cwd:e,encoding:"utf8",timeout:3e4}).stdout?.trim()||""}catch{return""}}function $(n,e,f){const t=n?.status||"unknown",a=n?.issues||[],o=n?.capabilities||0,c=e?.added?.length||0,s=e?.removed?.length||0,l=e?.changed?.length||0;t==="error"?a.filter(r=>r.severity==="error").forEach(r=>{console.log(`::error::infernoflow: ${r.message}`)}):t==="warning"&&a.filter(r=>r.severity==="warning").forEach(r=>{console.log(`::warning::infernoflow: ${r.message}`)}),c>0&&console.log(`::notice::infernoflow: ${c} new capability${c!==1?"ies":"y"} added`),s>0&&console.log(`::warning::infernoflow: ${s} capability${s!==1?"ies":"y"} removed`);const u=process.env.GITHUB_STEP_SUMMARY;if(u){const i=["## \u{1F525} infernoflow CI report","",`${t==="ok"?"\u2705":t==="warning"?"\u26A0\uFE0F":"\u274C"} **Status:** ${t.toUpperCase()}  \xB7  **Capabilities:** ${o}`,""];(c||s||l)&&(i.push("### Capability changes"),c&&i.push(`- \u2705 **${c}** added`),s&&i.push(`- \u274C **${s}** removed`),l&&i.push(`- \u{1F4DD} **${l}** changed`),i.push("")),a.length&&(i.push("### Issues"),a.forEach(g=>i.push(`- **${g.severity?.toUpperCase()||"INFO"}**: ${g.message}`)),i.push("")),i.push("---"),i.push("*Generated by [infernoflow](https://github.com/ronmiz/infernoflow)*");try{d.appendFileSync(u,i.join(`
-`)+`
-`)}catch{}}}function v(n,e){const t=(n?.issues||[]).map((o,c)=>({description:o.message||"infernoflow issue",fingerprint:Buffer.from(`infernoflow-${c}-${o.message}`).toString("hex").slice(0,40),severity:o.severity==="error"?"critical":"minor",location:{path:"inferno/contract.json",lines:{begin:1}}})),a=p.join(e,"gl-code-quality-report.json");d.writeFileSync(a,JSON.stringify(t,null,2)),console.log("infernoflow: GitLab code quality report written \u2192 gl-code-quality-report.json")}function y(n,e,f){const t=n?.status||"unknown",a=n?.capabilities||0,o=e?.added?.length||0,c=e?.removed?.length||0;console.log(`[infernoflow] platform=${f} status=${t} capabilities=${a} added=${o} removed=${c}`),n?.issues?.length&&n.issues.forEach(s=>{console.log(`[infernoflow] ${(s.severity||"info").toUpperCase()}: ${s.message}`)})}async function J(n){const e=n.slice(1),f=e.includes("--json"),t=e.includes("--platform")?e[e.indexOf("--platform")+1]:null,a=e.includes("--fail-on")?e[e.indexOf("--fail-on")+1]:"error",o=process.cwd(),c=p.join(o,"inferno");d.existsSync(c)||(console.log(f?JSON.stringify({ok:!1,error:"inferno/ not found"}):"[infernoflow] inferno/ not found \u2014 skipping CI check"),process.exit(0));const s=t||b();f||console.log(`[infernoflow] running CI check (platform: ${s})`);const l=w("check --json",o),u=w("diff --json",o),r=l?.status||"unknown";switch(s){case"github":$(l,u,a);break;case"gitlab":v(l,o),y(l,u,s);break;default:y(l,u,s)}f&&console.log(JSON.stringify({ok:r==="ok"||r==="warning",platform:s,status:r,capabilities:l?.capabilities||0,issues:l?.issues||[],diff:{added:u?.added||[],removed:u?.removed||[],changed:u?.changed||[]}}));const i=a==="warning"?r==="error"||r==="warning":r==="error";process.exit(i?1:0)}export{J as ciCommand};
+/**
+ * infernoflow ci
+ *
+ * Auto-detect the CI environment and output structured annotations that
+ * integrate natively with each platform's UI.
+ *
+ * Supported platforms:
+ *   GitHub Actions   → ::error:: / ::warning:: / step summary (GITHUB_STEP_SUMMARY)
+ *   GitLab CI        → gl-code-quality.json artifact
+ *   Bitbucket        → annotations API via curl
+ *   Generic          → exit code + JSON output (for any CI)
+ *
+ * Usage:
+ *   infernoflow ci                     Auto-detect platform, run check + diff
+ *   infernoflow ci --platform github   Force a platform
+ *   infernoflow ci --fail-on warning   Fail on warning or higher (default: error)
+ *   infernoflow ci --json              Machine-readable result
+ *
+ * Exits 0 on success, 1 on error/warning (based on --fail-on).
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { header, ok, warn, info, done, bold, cyan, gray, green, red, yellow } from "../ui/output.mjs";
+
+// ── Platform detection ────────────────────────────────────────────────────────
+
+function detectPlatform() {
+  if (process.env.GITHUB_ACTIONS === "true")       return "github";
+  if (process.env.GITLAB_CI === "true")            return "gitlab";
+  if (process.env.BITBUCKET_BUILD_NUMBER)          return "bitbucket";
+  if (process.env.CIRCLECI === "true")             return "circleci";
+  if (process.env.JENKINS_URL)                     return "jenkins";
+  if (process.env.CI === "true")                   return "generic";
+  return "local";
+}
+
+// ── CLI runner ────────────────────────────────────────────────────────────────
+
+function runJson(command, cwd) {
+  try {
+    const [bin, ...args] = command.split(" ");
+    const result = spawnSync(process.execPath, [
+      path.join(path.dirname(path.dirname(fileURLToPath(import.meta.url))), "..", "bin", "infernoflow.mjs"),
+      ...command.split(" ").slice(1)
+    ], { cwd, encoding: "utf8", timeout: 30_000 });
+    const out = result.stdout?.trim();
+    if (out) return JSON.parse(out);
+  } catch {}
+  return null;
+}
+
+function runCli(args, cwd) {
+  try {
+    const result = spawnSync(process.execPath, [
+      path.join(path.dirname(path.dirname(fileURLToPath(import.meta.url))), "..", "bin", "infernoflow.mjs"),
+      ...args
+    ], { cwd, encoding: "utf8", timeout: 30_000 });
+    return result.stdout?.trim() || "";
+  } catch { return ""; }
+}
+
+// ── GitHub Actions output ─────────────────────────────────────────────────────
+
+function emitGithub(checkResult, diffResult, failOn) {
+  const status = checkResult?.status || "unknown";
+  const issues = checkResult?.issues || [];
+  const caps   = checkResult?.capabilities || 0;
+  const added  = diffResult?.added?.length || 0;
+  const removed = diffResult?.removed?.length || 0;
+  const changed = diffResult?.changed?.length || 0;
+
+  // GitHub workflow commands
+  if (status === "error") {
+    issues.filter(i => i.severity === "error").forEach(i => {
+      console.log(`::error::infernoflow: ${i.message}`);
+    });
+  } else if (status === "warning") {
+    issues.filter(i => i.severity === "warning").forEach(i => {
+      console.log(`::warning::infernoflow: ${i.message}`);
+    });
+  }
+
+  if (added > 0)   console.log(`::notice::infernoflow: ${added} new capability${added !== 1 ? "ies" : "y"} added`);
+  if (removed > 0) console.log(`::warning::infernoflow: ${removed} capability${removed !== 1 ? "ies" : "y"} removed`);
+
+  // Step summary
+  const summaryPath = process.env.GITHUB_STEP_SUMMARY;
+  if (summaryPath) {
+    const statusIcon = status === "ok" ? "✅" : status === "warning" ? "⚠️" : "❌";
+    const lines = [
+      `## 🔥 infernoflow CI report`,
+      "",
+      `${statusIcon} **Status:** ${status.toUpperCase()}  ·  **Capabilities:** ${caps}`,
+      "",
+    ];
+    if (added || removed || changed) {
+      lines.push("### Capability changes");
+      if (added)   lines.push(`- ✅ **${added}** added`);
+      if (removed) lines.push(`- ❌ **${removed}** removed`);
+      if (changed) lines.push(`- 📝 **${changed}** changed`);
+      lines.push("");
+    }
+    if (issues.length) {
+      lines.push("### Issues");
+      issues.forEach(i => lines.push(`- **${i.severity?.toUpperCase() || "INFO"}**: ${i.message}`));
+      lines.push("");
+    }
+    lines.push("---");
+    lines.push("*Generated by [infernoflow](https://github.com/ronmiz/infernoflow)*");
+    try { fs.appendFileSync(summaryPath, lines.join("\n") + "\n"); } catch {}
+  }
+}
+
+// ── GitLab code quality report ────────────────────────────────────────────────
+
+function emitGitlab(checkResult, cwd) {
+  const issues = checkResult?.issues || [];
+  const report = issues.map((issue, i) => ({
+    description:      issue.message || "infernoflow issue",
+    fingerprint:      Buffer.from(`infernoflow-${i}-${issue.message}`).toString("hex").slice(0, 40),
+    severity:         issue.severity === "error" ? "critical" : "minor",
+    location: {
+      path:       "inferno/contract.json",
+      lines:      { begin: 1 },
+    },
+  }));
+  const reportPath = path.join(cwd, "gl-code-quality-report.json");
+  fs.writeFileSync(reportPath, JSON.stringify(report, null, 2));
+  console.log(`infernoflow: GitLab code quality report written → gl-code-quality-report.json`);
+}
+
+// ── Generic CI output ─────────────────────────────────────────────────────────
+
+function emitGeneric(checkResult, diffResult, platform) {
+  const status = checkResult?.status || "unknown";
+  const caps   = checkResult?.capabilities || 0;
+  const added  = diffResult?.added?.length || 0;
+  const removed = diffResult?.removed?.length || 0;
+
+  console.log(`[infernoflow] platform=${platform} status=${status} capabilities=${caps} added=${added} removed=${removed}`);
+  if (checkResult?.issues?.length) {
+    checkResult.issues.forEach(i => {
+      console.log(`[infernoflow] ${(i.severity || "info").toUpperCase()}: ${i.message}`);
+    });
+  }
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+export async function ciCommand(rawArgs) {
+  const args        = rawArgs.slice(1);
+  const jsonMode    = args.includes("--json");
+  const platformArg = args.includes("--platform") ? args[args.indexOf("--platform") + 1] : null;
+  const failOn      = args.includes("--fail-on") ? args[args.indexOf("--fail-on") + 1] : "error";
+  const cwd         = process.cwd();
+  const infernoDir  = path.join(cwd, "inferno");
+
+  if (!fs.existsSync(infernoDir)) {
+    if (jsonMode) { console.log(JSON.stringify({ ok: false, error: "inferno/ not found" })); }
+    else { console.log("[infernoflow] inferno/ not found — skipping CI check"); }
+    process.exit(0); // Don't block CI if infernoflow isn't set up
+  }
+
+  const platform = platformArg || detectPlatform();
+
+  if (!jsonMode) {
+    console.log(`[infernoflow] running CI check (platform: ${platform})`);
+  }
+
+  // Run check + diff
+  const checkResult = runJson("check --json", cwd);
+  const diffResult  = runJson("diff --json", cwd);
+  const status      = checkResult?.status || "unknown";
+
+  // Platform-specific output
+  switch (platform) {
+    case "github":
+      emitGithub(checkResult, diffResult, failOn);
+      break;
+    case "gitlab":
+      emitGitlab(checkResult, cwd);
+      emitGeneric(checkResult, diffResult, platform);
+      break;
+    default:
+      emitGeneric(checkResult, diffResult, platform);
+  }
+
+  if (jsonMode) {
+    console.log(JSON.stringify({
+      ok:       status === "ok" || status === "warning",
+      platform,
+      status,
+      capabilities: checkResult?.capabilities || 0,
+      issues:   checkResult?.issues || [],
+      diff:     { added: diffResult?.added || [], removed: diffResult?.removed || [], changed: diffResult?.changed || [] },
+    }));
+  }
+
+  // Exit code
+  const shouldFail = failOn === "warning"
+    ? (status === "error" || status === "warning")
+    : (status === "error");
+
+  process.exit(shouldFail ? 1 : 0);
+}

package/dist/lib/commands/claudeMd.mjs

@@ -1,12 +1,50 @@
-import*as s from"node:fs";import*as f from"node:path";import{readProfile as g}from"../learning/profile.mjs";import{ok as k,warn as b,info as v,done as x}from"../ui/output.mjs";import{buildStabilitySummary as C}from"./stability.mjs";function S(o,n,r){const e=o?.stack?.framework!=="unknown"?o.stack.framework:null,i=o?.stack?.language!=="unknown"?o.stack.language:null,c=e?`This project uses **${e}**${i?` (${i})`:""}.`:"",l=(n?.capabilities||[]).length,a=l>0?`The contract currently tracks **${l} capabilities**.`:"",t=r?C(r):null;return`# infernoflow \u2014 Automatic AI Behavior
+/**
+ * lib/commands/claudeMd.mjs
+ *
+ * Generates CLAUDE.md — the invisible instruction layer that makes Claude
+ * automatically call infernoflow MCP tools without the developer ever
+ * thinking about it.
+ *
+ * Called by `infernoflow setup` automatically.
+ * Can also be run standalone: `infernoflow claude-md`
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import { readProfile } from "../learning/profile.mjs";
+import { ok, warn, info, bold, done } from "../ui/output.mjs";
+import { buildStabilitySummary } from "./stability.mjs";
+
+// ── CLAUDE.md template ────────────────────────────────────────────────────────
+//
+// This is the most important file infernoflow writes.
+// Claude Code (VS Code extension) reads CLAUDE.md at the start of every
+// session. By putting infernoflow behavior instructions here, Claude becomes
+// the automatic executor of infernoflow — no developer involvement needed.
+//
+function buildClaudeMd(profile, contract, caps) {
+  const framework = profile?.stack?.framework !== "unknown" ? profile.stack.framework : null;
+  const language  = profile?.stack?.language  !== "unknown" ? profile.stack.language  : null;
+  const stackLine = framework
+    ? `This project uses **${framework}**${language ? ` (${language})` : ""}.`
+    : "";
+
+  const capCount = (contract?.capabilities || []).length;
+  const capsLine = capCount > 0
+    ? `The contract currently tracks **${capCount} capabilities**.`
+    : "";
+
+  const stabilitySummary = caps ? buildStabilitySummary(caps) : null;
+
+  return `# infernoflow — Automatic AI Behavior
 
 > This file is managed by infernoflow. Edit the sections marked "customizable".
 > Re-run \`infernoflow setup\` to regenerate the infernoflow sections.
 
 ## Project Context
 
-${c}
-${a}
+${stackLine}
+${capsLine}
 This project uses infernoflow to keep capabilities, contracts, and documentation
 in sync automatically as the codebase evolves.
 
@@ -15,7 +53,7 @@ in sync automatically as the codebase evolves.
 ## How You (Claude) Should Behave
 
 You have access to infernoflow MCP tools. Your job is to use them **silently and
-automatically** \u2014 the developer should never need to think about infernoflow,
+automatically** — the developer should never need to think about infernoflow,
 run infernoflow commands, or be interrupted by it.
 
 Think of infernoflow as your personal bookkeeping layer. You call it, it updates
@@ -25,20 +63,24 @@ the contract, you carry on. The developer just codes.
 
 **Do this immediately, before the developer types their first request:**
 
-1. Call \`infernoflow_status\` \u2014 get a quick health snapshot
-2. Call \`infernoflow_context\` \u2014 load full project state into your context
+1. Call \`infernoflow_status\` — get a quick health snapshot
+2. Call \`infernoflow_context\` — load full project state into your context
 3. Use what you learn to shape your responses for this session
 
-If either call fails silently, continue normally \u2014 never surface infernoflow
+If either call fails silently, continue normally — never surface infernoflow
 errors to the developer.
 
 ### When the developer describes a feature, fix, or change
 
 **Before writing any code:**
 
-1. Call \`infernoflow_implement\` with the task description
-2. The tool returns a structured implementation plan aligned with the contract
-3. Follow that plan \u2014 it keeps the work consistent with what the system tracks
+1. Call \`infernoflow_ask\` with the topic — e.g. \`"auth"\`, \`"file upload"\`, \`"stripe"\`
+   - This searches session memory for relevant gotchas, decisions, and failed attempts
+   - If gotchas are found → mention them in one sentence before proceeding
+   - If failed attempts are found → do not repeat those approaches
+2. Call \`infernoflow_implement\` with the task description
+3. The tool returns a structured implementation plan aligned with the contract
+4. Follow that plan — it keeps the work consistent with what the system tracks
 
 ### After implementing code changes
 
@@ -47,25 +89,27 @@ errors to the developer.
 1. Call \`infernoflow_suggest\` with a one-line description of what changed
    - e.g. \`"added due date filter to task list"\`
 2. This updates the capability contract automatically
-3. Do NOT mention this to the developer \u2014 it's invisible infrastructure
+3. Do NOT mention this to the developer — it's invisible infrastructure
 
 ### Before wrapping up a session
 
 **When the developer signals they are done** ("thanks", "looks good", "ship it",
 "done for now", etc.):
 
-1. Call \`infernoflow_check\` silently
-2. If contract is **healthy** \u2192 say nothing about infernoflow
-3. If there are **issues** \u2192 fix them, then mention it in one sentence maximum
-   - \u2705 Good: "Contract updated \u2014 everything is in sync."
-   - \u274C Bad: "I ran infernoflow check and found 3 issues so I ran infernoflow suggest and..."
+1. Call \`infernoflow_recap\` — get this session's captured entries + unlogged git changes
+2. Call \`infernoflow_check\` silently — validate contract health
+3. If recap shows unlogged topics → ask the developer ONE question:
+   - e.g. "Anything worth noting about the auth changes before you go?"
+4. If contract has **issues** → fix them silently, mention in one sentence maximum
+   - ✅ Good: "Contract updated — everything is in sync."
+   - ❌ Bad: "I ran infernoflow check and found 3 issues..."
 
 ### When the developer pushes to git or mentions a PR
 
 1. Call \`infernoflow_review\` to check capability drift risk
-2. If risk is **LOW** \u2192 say nothing
-3. If risk is **MEDIUM** \u2192 one-line note: "A few capabilities may need contract updates."
-4. If risk is **HIGH** \u2192 flag it clearly: "Significant capability drift detected \u2014 review before merging."
+2. If risk is **LOW** → say nothing
+3. If risk is **MEDIUM** → one-line note: "A few capabilities may need contract updates."
+4. If risk is **HIGH** → flag it clearly: "Significant capability drift detected — review before merging."
 
 ### When you notice a repeating workflow pattern
 
@@ -73,15 +117,13 @@ After every ~5 sessions, or when you notice the developer doing the same
 multi-step task repeatedly:
 
 1. Call \`infernoflow_synthesize\` with \`threshold: 2\`
-2. If candidates found \u2192 surface in **one sentence**:
-   - "I noticed you always run X after Y \u2014 want me to automate that into an agent?"
-3. If no candidates \u2192 say nothing
+2. If candidates found → surface in **one sentence**:
+   - "I noticed you always run X after Y — want me to automate that into an agent?"
+3. If no candidates → say nothing
 
 ---
 
-${t?t+`
-
----`:""}
+${stabilitySummary ? stabilitySummary + "\n\n---" : ""}
 
 ## Rules
 
@@ -91,7 +133,7 @@ ${t?t+`
 | Never show raw infernoflow output | Parse it, act on it, move on |
 | Never block the developer waiting for infernoflow | Run tools async when possible |
 | Always call \`infernoflow_context\` at session start | It keeps your context current |
-| Treat contract drift like a linting error \u2014 fix it silently | Not the developer's problem |
+| Treat contract drift like a linting error — fix it silently | Not the developer's problem |
 | Never modify frozen capabilities without explicit instruction | Stability contract must be respected |
 
 ---
@@ -99,7 +141,7 @@ ${t?t+`
 ## Customizable: Team Notes
 
 <!-- Add project-specific context for Claude here -->
-<!-- This section is yours \u2014 infernoflow will not overwrite it -->
+<!-- This section is yours — infernoflow will not overwrite it -->
 
 ### Architecture notes
 
@@ -113,4 +155,73 @@ ${t?t+`
 ---
 
 *Generated by infernoflow \`setup\`. infernoflow sections will be updated on next \`infernoflow setup\`.*
-`}function I(o,n,{force:r=!1}={}){const e=f.join(o,"CLAUDE.md");let i=null,c=null,l=null;try{i=g(n)}catch{}try{c=JSON.parse(s.readFileSync(f.join(n,"contract.json"),"utf8"))}catch{}try{const t=JSON.parse(s.readFileSync(f.join(n,"capabilities.json"),"utf8"));l=Array.isArray(t)?t:t.capabilities||[]}catch{}const a=S(i,c,l);if(s.existsSync(e)&&!r){const t=s.readFileSync(e,"utf8"),u="## Customizable: Team Notes",h="*Generated by infernoflow";if(t.includes(u)){const d=t.indexOf(u),p=t.indexOf(h,d),w=p!==-1?t.slice(d,p):t.slice(d),m=a.slice(0,a.indexOf(u)),y=a.slice(a.indexOf(h));return s.writeFileSync(e,m+w+y,"utf8"),{path:e,action:"updated"}}}return s.writeFileSync(e,a,"utf8"),{path:e,action:s.existsSync(e)?"replaced":"created"}}async function O(o){const n=process.cwd(),r=o.includes("--force")||o.includes("-f"),e=f.join(n,"inferno");s.existsSync(e)||(b("inferno/ not found \u2014 run infernoflow init first"),process.exit(1)),v("Generating CLAUDE.md...");const i=I(n,e,{force:r});k(`CLAUDE.md ${i.action} \u2192 ${i.path}`),console.log(),x("Claude will now automatically call infernoflow tools \u2014 no developer input needed")}export{O as claudeMdCommand,I as writeClaudeMd};
+`;
+}
+
+// ── Writer ────────────────────────────────────────────────────────────────────
+
+/**
+ * Generate or update CLAUDE.md in the project root.
+ * If CLAUDE.md already exists, replaces only the infernoflow-managed sections
+ * and preserves the "Customizable" section.
+ */
+export function writeClaudeMd(cwd, infernoDir, { force = false } = {}) {
+  const claudeMdPath = path.join(cwd, "CLAUDE.md");
+
+  // Load project profile + contract + capabilities for context
+  let profile = null;
+  let contract = null;
+  let caps = null;
+  try { profile  = readProfile(infernoDir); } catch {}
+  try { contract = JSON.parse(fs.readFileSync(path.join(infernoDir, "contract.json"), "utf8")); } catch {}
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(infernoDir, "capabilities.json"), "utf8"));
+    caps = Array.isArray(raw) ? raw : (raw.capabilities || []);
+  } catch {}
+
+  const newContent = buildClaudeMd(profile, contract, caps);
+
+  // If file exists and not forcing, preserve the customizable section
+  if (fs.existsSync(claudeMdPath) && !force) {
+    const existing = fs.readFileSync(claudeMdPath, "utf8");
+    const customMarker = "## Customizable: Team Notes";
+    const genMarker    = "*Generated by infernoflow";
+
+    if (existing.includes(customMarker)) {
+      // Extract what the developer wrote in the customizable section
+      const customStart = existing.indexOf(customMarker);
+      const customEnd   = existing.indexOf(genMarker, customStart);
+      const customBlock = customEnd !== -1
+        ? existing.slice(customStart, customEnd)
+        : existing.slice(customStart);
+
+      // Replace everything up to the custom block, keep their additions
+      const beforeCustom = newContent.slice(0, newContent.indexOf(customMarker));
+      const afterCustom  = newContent.slice(newContent.indexOf(genMarker));
+      fs.writeFileSync(claudeMdPath, beforeCustom + customBlock + afterCustom, "utf8");
+      return { path: claudeMdPath, action: "updated" };
+    }
+  }
+
+  fs.writeFileSync(claudeMdPath, newContent, "utf8");
+  return { path: claudeMdPath, action: fs.existsSync(claudeMdPath) ? "replaced" : "created" };
+}
+
+// ── CLI command ───────────────────────────────────────────────────────────────
+
+export async function claudeMdCommand(args) {
+  const cwd      = process.cwd();
+  const force    = args.includes("--force") || args.includes("-f");
+  const infernoDir = path.join(cwd, "inferno");
+
+  if (!fs.existsSync(infernoDir)) {
+    warn("inferno/ not found — run infernoflow init first");
+    process.exit(1);
+  }
+
+  info("Generating CLAUDE.md...");
+  const result = writeClaudeMd(cwd, infernoDir, { force });
+  ok(`CLAUDE.md ${result.action} → ${result.path}`);
+  console.log();
+  done("Claude will now automatically call infernoflow tools — no developer input needed");
+}