infernoflow 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# 🔥 infernoflow
+
+> The forge for liquid code — keep capabilities, contracts, and docs in sync with your codebase.
+
+## What it does
+
+infernoflow ensures that when your code changes, your **capability contracts** and **documentation** stay in sync. It prevents "semantic drift" — where code evolves but no one knows what the system can actually do.
+
+```
+inferno/
+├── contract.json       ← what your system promises to do
+├── capabilities.json   ← registry of each capability
+├── scenarios/          ← test scenarios covering each capability
+└── CHANGELOG.md        ← history of capability changes
+```
+
+## Install
+
+```bash
+npm install -g infernoflow
+# or use without installing:
+npx infernoflow init
+```
+
+## Quick Start
+
+```bash
+# In your project root:
+npx infernoflow init
+
+# See your contract health:
+infernoflow status
+
+# Validate everything:
+infernoflow check
+
+# In CI / pre-push hook:
+infernoflow doc-gate
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `infernoflow init` | Interactive scaffold — creates `inferno/` in your project |
+| `infernoflow status` | At-a-glance health of your contract |
+| `infernoflow check` | Full validation: contract, capabilities, scenarios, changelog |
+| `infernoflow doc-gate` | Fails if code changed but docs weren't updated |
+
+### Options
+
+```bash
+infernoflow init --force    # overwrite existing files
+infernoflow init --yes      # skip prompts, use defaults
+infernoflow check --json    # machine-readable output for CI
+infernoflow check --skip-doc-gate
+```
+
+## Example: Todo App
+
+After `infernoflow init` in a React Todo project:
+
+```
+inferno/
+├── contract.json
+│   {
+│     "policyId": "todo-app",
+│     "policyVersion": 1,
+│     "capabilities": ["CreateTask", "ReadTasks", "UpdateTask", "ToggleComplete", "DeleteTask"]
+│   }
+├── capabilities.json
+│   { capabilities: [{ id: "CreateTask", title: "Create a task", since: "0.1.0" }, ...] }
+├── scenarios/
+│   └── happy_path.json   ← covers all 5 capabilities
+└── CHANGELOG.md
+```
+
+Then in CI:
+
+```yaml
+- run: npm run inferno:check
+```
+
+## Why infernoflow?
+
+**The problem:** AI-assisted development moves fast. Code changes daily. But what does the system *actually do*? What changed? What's covered?
+
+**The metaphor:** A forge (כיבשן). Metal becomes liquid — flexible, shapeable. The forge is the controlled environment where that change happens safely, with molds (contracts) and tempering (tests).
+
+**The principle:** Liquid where you want flexibility. Solid where you need safety.
+
+## CI Integration
+
+```yaml
+# .github/workflows/ci.yml
+- name: infernoflow check
+  run: npx infernoflow check --json
+  env:
+    BASE_SHA: ${{ github.event.pull_request.base.sha }}
+    HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+```
+
+## License
+
+MIT

package/bin/infernoflow.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+import { parseArgs } from "node:util";
+import { bold, gray, cyan, red, orange } from "../lib/ui/output.mjs";
+
+const VERSION = "0.1.0";
+
+const HELP = `
+  ${bold("🔥 infernoflow")} ${gray("v" + VERSION)}
+  ${gray("The forge for liquid code")}
+
+  ${bold("Usage:")}
+    infernoflow <command> [options]
+
+  ${bold("Commands:")}
+    init          Scaffold inferno/ in your project (interactive)
+    check         Validate contract, capabilities, scenarios, changelog
+    status        Show contract health at a glance
+    doc-gate      Fail if code changed but docs were not updated
+
+  ${bold("Options:")}
+    init:
+      --force, -f     Overwrite existing files
+      --yes, -y       Skip prompts, use defaults
+
+    check:
+      --skip-doc-gate   Skip the git doc-gate check
+      --json            Machine-readable JSON output (for CI)
+
+  ${bold("Examples:")}
+    ${cyan("npx infernoflow init")}
+    ${cyan("infernoflow status")}
+    ${cyan("infernoflow check")}
+    ${cyan("infernoflow check --json")}
+    ${cyan("infernoflow doc-gate")}
+
+  ${bold("CI example:")}
+    ${gray("# In GitHub Actions:")}
+    ${gray("- run: npx infernoflow check --json")}
+    ${gray("  env:")}
+    ${gray("    BASE_SHA: ${{ github.event.pull_request.base.sha }}")}
+    ${gray("    HEAD_SHA: ${{ github.event.pull_request.head.sha }}")}
+`;
+
+const [,, cmd, ...rest] = process.argv;
+
+if (!cmd || cmd === "--help" || cmd === "-h") {
+  console.log(HELP);
+  process.exit(0);
+}
+
+if (cmd === "--version" || cmd === "-v") {
+  console.log(VERSION);
+  process.exit(0);
+}
+
+const commands = ["init", "check", "status", "doc-gate"];
+
+if (!commands.includes(cmd)) {
+  console.error(red(`\nUnknown command: ${cmd}`));
+  console.error(gray("Run: infernoflow --help\n"));
+  process.exit(1);
+}
+
+const args = [cmd, ...rest];
+
+switch (cmd) {
+  case "init":
+    import("../lib/commands/init.mjs")
+      .then(m => m.initCommand(args))
+      .catch(err => { console.error(red("\nError: ") + err.message); process.exit(1); });
+    break;
+  case "check":
+    import("../lib/commands/check.mjs")
+      .then(m => m.checkCommand(args))
+      .catch(err => { console.error(red("\nError: ") + err.message); process.exit(1); });
+    break;
+  case "status":
+    import("../lib/commands/status.mjs")
+      .then(m => m.statusCommand(args))
+      .catch(err => { console.error(red("\nError: ") + err.message); process.exit(1); });
+    break;
+  case "doc-gate":
+    import("../lib/commands/docGate.mjs")
+      .then(m => m.docGateCommand())
+      .catch(err => { console.error(red("\nError: ") + err.message); process.exit(1); });
+    break;
+}

package/lib/commands/check.mjs

@@ -0,0 +1,154 @@
+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) {
+  try { return JSON.parse(fs.readFileSync(filePath, "utf8")); }
+  catch (err) {
+    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 {
+    const contract = readJson(contractPath);
+    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 {
+      const registry = readJson(capsPath);
+      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");
+  }
+}

package/lib/commands/docGate.mjs

@@ -0,0 +1,57 @@
+import { execSync } from "node:child_process";
+import { ok, fail, warn, info, gray } from "../ui/output.mjs";
+
+function sh(cmd) {
+  return execSync(cmd, { stdio: ["ignore", "pipe", "pipe"] }).toString("utf8").trim();
+}
+
+const CODE_PREFIXES = [
+  "src/", "frontend/", "backend/",
+  "app/", "pages/", "components/",
+  "Controllers/", "Services/", "Endpoints/",
+  "lib/", "api/", "server/"
+];
+
+export async function docGateCommand(opts = {}) {
+  const silent = opts?.silent || false;
+  const captureExit = opts?.captureExit || false;
+  const base = process.env.BASE_SHA || "HEAD~1";
+  const head = process.env.HEAD_SHA || "HEAD";
+
+  let files = [];
+  try {
+    const out = sh(`git diff --name-only ${base}..${head}`);
+    files = out ? out.split("\n").filter(Boolean) : [];
+  } catch {
+    if (!silent) info(gray("doc-gate skipped (no git available)"));
+    return;
+  }
+
+  if (files.length === 0) {
+    if (!silent) ok("doc-gate: no changed files");
+    return;
+  }
+
+  const changedCode = files.some(f =>
+    CODE_PREFIXES.some(p => f.startsWith(p) || f.includes("/" + p))
+  );
+  const changedInferno = files.some(f => f.startsWith("inferno/"));
+
+  if (changedCode && !changedInferno) {
+    if (!silent) {
+      fail(
+        "Code changed but inferno/ was NOT updated",
+        "Update at least one file in inferno/ before committing"
+      );
+      const codeFiles = files.filter(f => CODE_PREFIXES.some(p => f.startsWith(p))).slice(0, 5);
+      if (codeFiles.length) {
+        console.log();
+        codeFiles.forEach(f => console.log("      " + gray("• " + f)));
+      }
+    }
+    if (captureExit) throw new Error("doc-gate failed");
+    process.exit(1);
+  }
+
+  if (!silent) ok("doc-gate: docs are up to date");
+}

package/lib/commands/init.mjs

@@ -0,0 +1,193 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as readline from "node:readline";
+import { fileURLToPath } from "node:url";
+import { header, ok, warn, done, nextSteps, cyan, yellow, gray } from "../ui/output.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function getTemplatesRoot() {
+  return path.resolve(__dirname, "../../templates");
+}
+
+function ask(rl, question, defaultVal = "") {
+  return new Promise(resolve => {
+    const hint = defaultVal ? gray(` (${defaultVal})`) : "";
+    rl.question(`  ${question}${hint}: `, answer => {
+      resolve(answer.trim() || defaultVal);
+    });
+  });
+}
+
+function copyFile(src, dst, force) {
+  if (fs.existsSync(dst) && !force) {
+    warn("Skipped (exists): " + path.relative(process.cwd(), dst));
+    return false;
+  }
+  fs.mkdirSync(path.dirname(dst), { recursive: true });
+  fs.copyFileSync(src, dst);
+  ok("Created: " + cyan(path.relative(process.cwd(), dst)));
+  return true;
+}
+
+function copyDirDeep(srcDir, dstDir, force) {
+  fs.mkdirSync(dstDir, { recursive: true });
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const src = path.join(srcDir, entry.name);
+    const dst = path.join(dstDir, entry.name);
+    if (entry.isDirectory()) copyDirDeep(src, dst, force);
+    else copyFile(src, dst, force);
+  }
+}
+
+function upsertScripts(cwd) {
+  const pkgPath = path.join(cwd, "package.json");
+  if (!fs.existsSync(pkgPath)) return;
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  pkg.scripts = pkg.scripts || {};
+  let changed = false;
+  const toAdd = {
+    "inferno:check":  "infernoflow check",
+    "inferno:status": "infernoflow status",
+    "inferno:gate":   "infernoflow doc-gate"
+  };
+  for (const [k, v] of Object.entries(toAdd)) {
+    if (!pkg.scripts[k]) { pkg.scripts[k] = v; changed = true; }
+  }
+  if (changed) {
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+    ok("Updated " + cyan("package.json") + " scripts");
+  }
+}
+
+function detectProjectName(cwd) {
+  const pkgPath = path.join(cwd, "package.json");
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+      if (pkg.name) return pkg.name.replace(/[^a-z0-9_-]/gi, "_");
+    } catch {}
+  }
+  return path.basename(cwd);
+}
+
+function writeContract(contractPath, policyId, capabilities) {
+  const contract = {
+    policyId,
+    policyVersion: 1,
+    capabilities,
+    rules: {
+      docsRequiredOnCapabilityChange: true,
+      requireScenarioForEachCapability: true,
+      requireChangelogOnCapabilityChange: true
+    }
+  };
+  fs.writeFileSync(contractPath, JSON.stringify(contract, null, 2) + "\n");
+}
+
+function writeCapabilities(capsPath, capabilities) {
+  const registry = {
+    schemaVersion: 1,
+    capabilities: capabilities.map(id => ({
+      id,
+      title: id.replace(/([A-Z])/g, " $1").trim(),
+      since: "0.1.0"
+    }))
+  };
+  fs.writeFileSync(capsPath, JSON.stringify(registry, null, 2) + "\n");
+}
+
+function writeScenario(scenariosDir, capabilities) {
+  fs.mkdirSync(scenariosDir, { recursive: true });
+  const scenario = {
+    scenarioId: "happy_path",
+    description: "Basic happy-path flow covering all capabilities",
+    capabilitiesCovered: capabilities,
+    steps: capabilities.map(c => ({
+      action: c,
+      expect: `${c} works as expected`
+    }))
+  };
+  fs.writeFileSync(
+    path.join(scenariosDir, "happy_path.json"),
+    JSON.stringify(scenario, null, 2) + "\n"
+  );
+}
+
+function writeChangelog(changelogPath, policyId) {
+  const content = `# Changelog — ${policyId}
+
+## Unreleased
+
+- Initial capabilities defined
+
+## 0.1.0 — Initial release
+
+- Project initialized with infernoflow
+`;
+  fs.writeFileSync(changelogPath, content);
+}
+
+export async function initCommand(args) {
+  const cwd = process.cwd();
+  const force = args.includes("--force") || args.includes("-f");
+  const yes = args.includes("--yes") || args.includes("-y");
+
+  header("init");
+
+  const infernoDir = path.join(cwd, "inferno");
+  if (fs.existsSync(infernoDir) && !force) {
+    warn("inferno/ already exists. Use --force to overwrite.");
+    console.log();
+    process.exit(0);
+  }
+
+  const detectedName = detectProjectName(cwd);
+  const defaultCaps = "CreateTask, ReadTasks, UpdateTask, ToggleComplete, DeleteTask";
+
+  let policyId = detectedName;
+  let capabilities = defaultCaps.split(",").map(c => c.trim());
+
+  if (!yes) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    console.log(gray("  Press Enter to accept defaults\n"));
+    policyId = await ask(rl, "Project / policy name", detectedName);
+    const capsRaw = await ask(rl, "Capabilities (comma-separated)", defaultCaps);
+    capabilities = capsRaw.split(",").map(c => c.trim()).filter(Boolean);
+    rl.close();
+    console.log();
+  }
+
+  // Write files
+  fs.mkdirSync(infernoDir, { recursive: true });
+
+  writeContract(path.join(infernoDir, "contract.json"), policyId, capabilities);
+  ok("Created: " + cyan("inferno/contract.json"));
+
+  writeCapabilities(path.join(infernoDir, "capabilities.json"), capabilities);
+  ok("Created: " + cyan("inferno/capabilities.json"));
+
+  writeScenario(path.join(infernoDir, "scenarios"), capabilities);
+  ok("Created: " + cyan("inferno/scenarios/happy_path.json"));
+
+  writeChangelog(path.join(infernoDir, "CHANGELOG.md"), policyId);
+  ok("Created: " + cyan("inferno/CHANGELOG.md"));
+
+  // Copy doc-gate script
+  const templates = getTemplatesRoot();
+  const srcScript = path.join(templates, "scripts", "inferno-doc-gate.mjs");
+  const dstScript = path.join(cwd, "scripts", "inferno-doc-gate.mjs");
+  copyFile(srcScript, dstScript, force);
+
+  upsertScripts(cwd);
+
+  done("infernoflow initialized!");
+
+  nextSteps([
+    cyan("infernoflow status") + "  — see your contract at a glance",
+    cyan("infernoflow check") + "   — validate everything",
+    "Edit " + yellow("inferno/capabilities.json") + " to describe each capability in detail",
+    "Add more " + yellow("inferno/scenarios/*.json") + " files for edge cases",
+    "Add " + cyan("inferno:check") + " to your CI pipeline"
+  ]);
+}

package/lib/commands/status.mjs

@@ -0,0 +1,133 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { header, ok, fail, warn, info, section, bold, cyan, yellow, gray, green, red, white } from "../ui/output.mjs";
+
+function timeAgo(ms) {
+  const s = Math.floor((Date.now() - ms) / 1000);
+  if (s < 60) return "just now";
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+  return `${Math.floor(s / 86400)}d ago`;
+}
+
+function getCoverage(scenariosDir, caps) {
+  const covered = new Set();
+  if (fs.existsSync(scenariosDir)) {
+    for (const f of fs.readdirSync(scenariosDir).filter(f => f.endsWith(".json"))) {
+      try {
+        const s = JSON.parse(fs.readFileSync(path.join(scenariosDir, f), "utf8"));
+        (s.capabilitiesCovered || []).forEach(c => covered.add(c));
+      } catch {}
+    }
+  }
+  return { covered: caps.filter(c => covered.has(c)), uncovered: caps.filter(c => !covered.has(c)) };
+}
+
+export async function statusCommand() {
+  const cwd = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  header("status");
+
+  if (!fs.existsSync(infernoDir)) {
+    fail("inferno/ not found", `Run: infernoflow init`);
+    console.log();
+    process.exit(1);
+  }
+
+  const contractPath = path.join(infernoDir, "contract.json");
+  if (!fs.existsSync(contractPath)) {
+    fail("contract.json not found");
+    console.log();
+    process.exit(1);
+  }
+
+  const contract = JSON.parse(fs.readFileSync(contractPath, "utf8"));
+  const caps = contract.capabilities || [];
+  const stat = fs.statSync(contractPath);
+  const scenariosDir = path.join(infernoDir, "scenarios");
+  const changelogPath = path.join(infernoDir, "CHANGELOG.md");
+  const capsPath = path.join(infernoDir, "capabilities.json");
+
+  // ── Project ─────────────────────────────────────────────────────
+  section("Project");
+  console.log(`  ${gray("policy")}       ${bold(contract.policyId || "—")}`);
+  console.log(`  ${gray("version")}      ${bold("v" + (contract.policyVersion || "?"))}`);
+  console.log(`  ${gray("last change")}  ${gray(timeAgo(stat.mtimeMs))}`);
+
+  // ── Capabilities ─────────────────────────────────────────────────
+  section(`Capabilities  ${gray("(" + caps.length + ")")}`);
+
+  let capsRegistry = {};
+  if (fs.existsSync(capsPath)) {
+    try {
+      const reg = JSON.parse(fs.readFileSync(capsPath, "utf8"));
+      (reg.capabilities || []).forEach(c => { capsRegistry[c.id] = c; });
+    } catch {}
+  }
+
+  const { covered, uncovered } = getCoverage(scenariosDir, caps);
+
+  caps.forEach(cap => {
+    const reg = capsRegistry[cap];
+    const hasCoverage = covered.includes(cap);
+    const icon = hasCoverage ? green("✔") : red("✘");
+    const title = reg?.title ? gray(` — ${reg.title}`) : "";
+    const since = reg?.since ? gray(` [${reg.since}]`) : "";
+    console.log(`  ${icon} ${white(cap)}${title}${since}`);
+  });
+
+  if (uncovered.length > 0) {
+    console.log(`\n  ${yellow("⚠")}  ${uncovered.length} capability(ies) lack scenario coverage`);
+  } else {
+    console.log(`\n  ${green("✔")}  All capabilities have scenario coverage`);
+  }
+
+  // ── Scenarios ─────────────────────────────────────────────────────
+  section("Scenarios");
+  if (fs.existsSync(scenariosDir)) {
+    const files = fs.readdirSync(scenariosDir).filter(f => f.endsWith(".json"));
+    if (files.length === 0) {
+      warn("No scenario files — add .json files to inferno/scenarios/");
+    } else {
+      files.forEach(f => {
+        try {
+          const s = JSON.parse(fs.readFileSync(path.join(scenariosDir, f), "utf8"));
+          const steps = s.steps?.length || 0;
+          const capCount = (s.capabilitiesCovered || []).length;
+          console.log(`  ${green("✔")} ${cyan(f)} ${gray(`— ${steps} steps, ${capCount} caps covered`)}`);
+        } catch {
+          console.log(`  ${red("✘")} ${cyan(f)} ${gray("— invalid JSON")}`);
+        }
+      });
+    }
+  } else {
+    warn("scenarios/ directory not found");
+  }
+
+  // ── Changelog ─────────────────────────────────────────────────────
+  section("Changelog");
+  if (fs.existsSync(changelogPath)) {
+    const txt = fs.readFileSync(changelogPath, "utf8");
+    if (/##\s+Unreleased/i.test(txt)) {
+      ok("Has ## Unreleased section");
+    } else {
+      fail("Missing ## Unreleased section");
+    }
+    const sections = txt.split("\n").filter(l => /^##\s/.test(l)).slice(0, 3);
+    sections.forEach(l => console.log(`  ${gray(l)}`));
+  } else {
+    fail("inferno/CHANGELOG.md not found");
+  }
+
+  // ── Health ────────────────────────────────────────────────────────
+  console.log();
+  const hasChangelog = fs.existsSync(changelogPath) && /##\s+Unreleased/i.test(fs.readFileSync(changelogPath, "utf8"));
+  const allGood = uncovered.length === 0 && hasChangelog;
+  if (allGood) {
+    console.log(`  ${green("●")} ${bold(green("ready"))} ${gray("— run infernoflow check for full validation")}`);
+  } else {
+    console.log(`  ${yellow("●")} ${bold(yellow("needs attention"))} ${gray("— run infernoflow check for details")}`);
+  }
+  console.log();
+}

package/lib/ui/output.mjs

@@ -0,0 +1,72 @@
+// Zero-dependency color/output utilities using ANSI codes
+
+const c = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  cyan: "\x1b[36m",
+  white: "\x1b[37m",
+  gray: "\x1b[90m",
+  orange: "\x1b[38;5;208m",
+};
+
+const noColor = !process.stdout.isTTY || process.env.NO_COLOR;
+
+function paint(code, text) {
+  if (noColor) return text;
+  return `${code}${text}${c.reset}`;
+}
+
+export const bold    = t => paint(c.bold, t);
+export const red     = t => paint(c.red, t);
+export const green   = t => paint(c.green, t);
+export const yellow  = t => paint(c.yellow, t);
+export const cyan    = t => paint(c.cyan, t);
+export const gray    = t => paint(c.gray, t);
+export const white   = t => paint(c.white, t);
+export const orange  = t => paint(c.orange, t);
+export const boldRed    = t => paint(c.bold + c.red, t);
+export const boldGreen  = t => paint(c.bold + c.green, t);
+export const boldYellow = t => paint(c.bold + c.yellow, t);
+export const boldOrange = t => paint(c.bold + c.orange, t);
+
+function strip(str) {
+  return str.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+export function header(text) {
+  const title = boldOrange("🔥 infernoflow") + gray(" — " + text);
+  console.log("\n" + title);
+  console.log(gray("─".repeat(50)));
+}
+
+export function ok(msg)          { console.log("  " + green("✔") + " " + msg); }
+export function fail(msg, hint)  {
+  console.log("  " + red("✘") + " " + red(msg));
+  if (hint) console.log("      " + gray("→ " + hint));
+}
+export function warn(msg)        { console.log("  " + yellow("⚠") + " " + yellow(msg)); }
+export function info(msg)        { console.log("  " + cyan("ℹ") + " " + msg); }
+export function section(title)   { console.log("\n" + bold(white(title))); }
+
+export function done(msg) {
+  console.log("\n" + boldGreen("✨ " + msg) + "\n");
+}
+
+export function nextSteps(steps) {
+  console.log(bold("Next steps:"));
+  steps.forEach((s, i) => {
+    console.log("  " + gray((i + 1) + ".") + " " + s);
+  });
+  console.log();
+}
+
+export function errorAndExit(msg, hint) {
+  console.error("\n" + boldRed("Error: ") + red(msg));
+  if (hint) console.error(gray("  → " + hint));
+  console.error();
+  process.exit(1);
+}

package/lib/ui/prompts.mjs

@@ -0,0 +1,20 @@
+// Zero-dependency interactive prompts using readline
+
+import * as readline from "node:readline";
+
+function ask(question, defaultVal = "") {
+  return new Promise(resolve => {
+    const hint = defaultVal ? ` (${defaultVal})` : "";
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(`  ${question}${hint}: `, answer => {
+      rl.close();
+      resolve(answer.trim() || defaultVal);
+    });
+  });
+}
+
+export async function promptInit() {
+  const policyId = await ask("Project / policy name", process.env._INFERNO_DEFAULT_POLICY || "my-project");
+  const caps = await ask("Capabilities (comma-separated)", "CreateTask, ReadTasks, UpdateTask, DeleteTask");
+  return { policyId, capabilities: caps.split(",").map(c => c.trim()).filter(Boolean) };
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "infernoflow",
+  "version": "0.1.0",
+  "description": "The forge for liquid code — keep capabilities, contracts, and docs in sync.",
+  "type": "module",
+  "bin": {
+    "infernoflow": "./bin/infernoflow.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node bin/infernoflow.mjs --help"
+  },
+  "keywords": ["cli", "capabilities", "contract", "documentation", "ai", "liquid-code"],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {}
+}

package/templates/inferno/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## Unreleased
+
+- Initial capabilities: CreateItem, ReadItems, UpdateItem, DeleteItem
+
+## 0.1.0 — Initial release
+
+- Project initialized with infernoflow

package/templates/inferno/capabilities.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "capabilities": [
+    { "id": "CreateItem", "title": "Create item", "since": "0.1.0" },
+    { "id": "ReadItems", "title": "List items", "since": "0.1.0" },
+    { "id": "UpdateItem", "title": "Edit item", "since": "0.1.0" },
+    { "id": "DeleteItem", "title": "Delete item", "since": "0.1.0" }
+  ]
+}

package/templates/inferno/contract.json

@@ -0,0 +1,15 @@
+{
+  "policyId": "my_project",
+  "policyVersion": 1,
+  "capabilities": [
+    "CreateItem",
+    "ReadItems",
+    "UpdateItem",
+    "DeleteItem"
+  ],
+  "rules": {
+    "docsRequiredOnCapabilityChange": true,
+    "requireScenarioForEachCapability": true,
+    "requireChangelogOnCapabilityChange": true
+  }
+}

package/templates/inferno/scenarios/happy_path.json

@@ -0,0 +1,16 @@
+{
+  "scenarioId": "happy_path",
+  "description": "Basic CRUD flow",
+  "capabilitiesCovered": [
+    "CreateItem",
+    "ReadItems",
+    "UpdateItem",
+    "DeleteItem"
+  ],
+  "steps": [
+    { "action": "CreateItem", "expect": "A new item appears in the list" },
+    { "action": "ReadItems",  "expect": "All items are visible" },
+    { "action": "UpdateItem", "expect": "Item content is updated" },
+    { "action": "DeleteItem", "expect": "Item is removed from the list" }
+  ]
+}

package/templates/scripts/inferno-doc-gate.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// inferno-doc-gate.mjs
+// Run as a git pre-push or CI step:
+//   node scripts/inferno-doc-gate.mjs
+import { execSync } from "node:child_process";
+
+const CODE_PREFIXES = ["src/", "frontend/", "backend/", "app/", "pages/", "components/", "lib/", "api/"];
+const INFERNO_PATTERNS = [f => f.startsWith("inferno/")];
+
+function sh(cmd) {
+  return execSync(cmd, { stdio: ["ignore", "pipe", "pipe"] }).toString("utf8").trim();
+}
+
+const base = process.env.BASE_SHA || "HEAD~1";
+const head = process.env.HEAD_SHA || "HEAD";
+
+let files = [];
+try {
+  const out = sh(`git diff --name-only ${base}..${head}`);
+  files = out ? out.split("\n").filter(Boolean) : [];
+} catch {
+  console.log("[inferno doc-gate] skipped (git unavailable)");
+  process.exit(0);
+}
+
+const changedCode = files.some(f => CODE_PREFIXES.some(p => f.startsWith(p)));
+const changedInferno = files.some(f => INFERNO_PATTERNS.some(fn => fn(f)));
+
+if (changedCode && !changedInferno) {
+  console.error("\n[inferno doc-gate] ✘ Code changed but inferno/ was NOT updated.");
+  console.error("Update at least one file in inferno/ before pushing.\n");
+  process.exit(1);
+}
+console.log("[inferno doc-gate] ✔ OK");