infernoflow 0.8.0 → 0.10.1

package/README.md

@@ -41,6 +41,65 @@ infernoflow check
 infernoflow doc-gate
 ```
 
+## Recommended Workflow
+
+```bash
+# start a feature
+infernoflow context --intent "add search to tasks" --working "frontend search UX"
+
+# generate implementation prompt(s) for coding agent
+infernoflow implement "add server-side task search endpoint" --mode both
+
+# build code changes
+
+# sync inferno contract with AI assistance
+infernoflow suggest "added task search by title and due date"
+
+# verify no drift
+infernoflow status
+infernoflow check
+```
+
+## Team SOP (Developer Workflow)
+
+Use this checklist for every feature branch:
+
+1) **Set intent**
+```bash
+infernoflow context --intent "what feature is being built" --working "current slice"
+```
+
+2) **Build code**
+- Implement UI/API/tests as usual.
+
+3) **Sync contract with `suggest`**
+```bash
+infernoflow suggest "plain-language description of what changed"
+```
+- Paste generated prompt into your AI.
+- Paste AI JSON back into terminal.
+- Approve with `y` only after preview looks correct.
+
+4) **Validate before commit**
+```bash
+infernoflow status
+infernoflow check
+```
+
+5) **CI-safe checks**
+```bash
+infernoflow status --json
+infernoflow check --json
+infernoflow doc-gate --json
+```
+
+6) **Definition of done**
+- Capability changes are reflected in `inferno/contract.json`.
+- New/changed capabilities exist in `inferno/capabilities.json`.
+- Scenario coverage updated under `inferno/scenarios/`.
+- `inferno/CHANGELOG.md` updated under `## Unreleased`.
+- `infernoflow check` passes.
+
 ## Commands
 
 | Command | Description |
@@ -48,8 +107,10 @@ infernoflow doc-gate
 | `infernoflow init` | Interactive scaffold — creates `inferno/` in your project |
 | `infernoflow status` | At-a-glance health of your contract |
 | `infernoflow suggest` | Generate an AI prompt, apply capability updates |
+| `infernoflow implement` | Generate implementation prompts for coding agents |
 | `infernoflow check` | Full validation: contract, capabilities, scenarios, changelog |
 | `infernoflow doc-gate` | Fails if code changed but docs weren't updated |
+| `infernoflow context` | Build/persist AI session context for this project |
 
 ### Options
 
@@ -57,8 +118,14 @@ infernoflow doc-gate
 infernoflow init --force       # overwrite existing files
 infernoflow init --yes         # skip prompts, use defaults
 infernoflow suggest "..."      # describe what changed
+infernoflow implement "..." --mode both
+infernoflow implement "..." --mode cursor
+infernoflow implement "..." --mode generic
+infernoflow implement "..." --mode both --copy
 infernoflow check --json       # machine-readable output for CI
 infernoflow check --skip-doc-gate
+infernoflow status --json      # machine-readable status summary
+infernoflow doc-gate --json    # machine-readable doc-gate result
 ```
 
 ## `infernoflow suggest` — AI-powered updates
@@ -97,6 +164,41 @@ Proposed Changes
 
 Works with any AI — Claude, ChatGPT, GitHub Copilot, Cursor, or your own setup.
 
+## `infernoflow implement` — code-agent execution prompts
+
+Generate coding prompts from your project context and inferno contract:
+
+```bash
+infernoflow implement "add pagination to tasks" --mode both
+```
+
+Modes:
+- `--mode cursor`: Cursor-specific coding prompt
+- `--mode generic`: generic prompt for any coding agent
+- `--mode both`: print both sections (default)
+- `--copy`: copy selected prompt output to clipboard
+
+Recommended chain:
+1) `infernoflow context --intent "..."`
+2) `infernoflow implement "..."`
+3) run the coding agent and apply code changes
+4) `infernoflow suggest "..."`
+5) `infernoflow check`
+
+## Troubleshooting
+
+- `Unknown command: suggest`:
+  - Run `infernoflow --help` and confirm `suggest` appears.
+  - If using `npx`, force a specific version: `npx infernoflow@latest --help`.
+- `infernoflow: command not found`:
+  - Use `npx infernoflow ...` or install globally: `npm install -g infernoflow`.
+- `npm publish` fails with existing version:
+  - Bump version first (`npm version patch|minor|major`) then publish.
+- `status` or `check` fails due to missing inferno files:
+  - Run `infernoflow init` at project root.
+- Windows/Git Bash path confusion:
+  - Prefer `node bin/infernoflow.mjs --help` from package root for local debugging.
+
 ## Why infernoflow?
 
 **The problem:** AI-assisted development moves fast. Code changes daily. But what does the system *actually do*? What changed? What's covered?
@@ -116,6 +218,17 @@ Works with any AI — Claude, ChatGPT, GitHub Copilot, Cursor, or your own setup
     HEAD_SHA: ${{ github.event.pull_request.head.sha }}
 ```
 
+## Release Checklist
+
+```bash
+npm test
+npm pack --dry-run
+node bin/infernoflow.mjs --help
+node bin/infernoflow.mjs check --help
+```
+
+Then bump version and publish.
+
 ## License
 
 MIT

package/bin/infernoflow.mjs

@@ -1,7 +1,37 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { bold, gray, cyan, red } from "../lib/ui/output.mjs";
 
-const VERSION = "0.5.0";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf8"));
+const VERSION = pkg.version || "0.0.0";
+const COMMAND_DESCRIPTIONS = {
+  init: "Scaffold inferno/ in your project",
+  check: "Validate contract, capabilities, scenarios, changelog",
+  status: "Show contract health at a glance",
+  "doc-gate": "Fail if code changed but docs were not updated",
+  suggest: "Generate AI prompt + apply capability updates",
+  implement: "Generate code-agent implementation prompt(s)",
+  context: "Generate AI-ready context for new sessions",
+};
+
+const COMMAND_HANDLERS = {
+  init: async (args) => (await import("../lib/commands/init.mjs")).initCommand(args),
+  check: async (args) => (await import("../lib/commands/check.mjs")).checkCommand(args),
+  status: async (args) => (await import("../lib/commands/status.mjs")).statusCommand(args),
+  suggest: async (args) => (await import("../lib/commands/suggest.mjs")).suggestCommand(args),
+  implement: async (args) => (await import("../lib/commands/implement.mjs")).implementCommand(args),
+  context: async (args) => (await import("../lib/commands/context.mjs")).contextCommand(args),
+  "doc-gate": async (args) => (await import("../lib/commands/docGate.mjs")).docGateCommand(args),
+};
+
+function formatCommandsHelp() {
+  return Object.entries(COMMAND_DESCRIPTIONS)
+    .map(([name, desc]) => `    ${name.padEnd(13, " ")}${desc}`)
+    .join("\n");
+}
 
 const HELP = `
   ${bold("🔥 infernoflow")} ${gray("v" + VERSION)}
@@ -11,12 +41,7 @@ const HELP = `
     infernoflow <command> [options]
 
   ${bold("Commands:")}
-    init          Scaffold inferno/ in your project
-    check         Validate contract, capabilities, scenarios, changelog
-    status        Show contract health at a glance
-    doc-gate      Fail if code changed but docs were not updated
-    suggest       Generate AI prompt + apply capability updates
-    context       Generate AI-ready context for new sessions
+${formatCommandsHelp()}
 
   ${bold("context options:")}
     --intent  "..."     What you plan to build next
@@ -26,12 +51,21 @@ const HELP = `
     --copy, -c          Copy context to clipboard instantly
     --reset             Clear all stored state
 
+  ${bold("implement options:")}
+    --mode <type>       cursor | generic | both (default: both)
+    --copy, -c          Copy generated prompt(s) to clipboard
+
   ${bold("Typical workflow:")}
     ${gray('1. infernoflow context --intent "what I want to build"')}
     ${gray("2. [paste inferno/CONTEXT.md into Claude / Cursor / Copilot]")}
     ${gray("3. [build the feature]")}
     ${gray('4. infernoflow suggest "what I built"')}
     ${gray("5. infernoflow check")}
+
+  ${bold("Machine output:")}
+    ${gray("status --json")}
+    ${gray("check --json")}
+    ${gray("doc-gate --json")}
 `;
 
 const [, , cmd, ...rest] = process.argv;
@@ -45,7 +79,7 @@ if (cmd === "--version" || cmd === "-v") {
   process.exit(0);
 }
 
-const commands = ["init", "check", "status", "doc-gate", "suggest", "context"];
+const commands = Object.keys(COMMAND_HANDLERS);
 
 if (!commands.includes(cmd)) {
   console.error(red(`\nUnknown command: ${cmd}`));
@@ -54,54 +88,7 @@ if (!commands.includes(cmd)) {
 }
 
 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 "suggest":
-    import("../lib/commands/suggest.mjs")
-      .then((m) => m.suggestCommand(args))
-      .catch((err) => {
-        console.error(red("\nError: ") + err.message);
-        process.exit(1);
-      });
-    break;
-  case "context":
-    import("../lib/commands/context.mjs")
-      .then((m) => m.contextCommand(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;
-}
+COMMAND_HANDLERS[cmd](args).catch((err) => {
+  console.error(red("\nError: ") + err.message);
+  process.exit(1);
+});

package/lib/commands/check.mjs

@@ -3,9 +3,12 @@ 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) {
+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}`
@@ -59,7 +62,18 @@ export async function checkCommand(args) {
     fail("contract.json not found", "Run: infernoflow init");
     errors.push("contract.json missing");
   } else {
-    const contract = readJson(contractPath);
+    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"); }
@@ -76,7 +90,18 @@ export async function checkCommand(args) {
     if (!fs.existsSync(capsPath)) {
       fail("capabilities.json not found"); errors.push("capabilities.json missing");
     } else {
-      const registry = readJson(capsPath);
+      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));

package/lib/commands/context.mjs

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { execSync } from "node:child_process";
 import { bold, gray, cyan, red, green, yellow } from "../ui/output.mjs";
+import { buildCursorImplementPrompt, buildGenericImplementPrompt } from "../ui/prompts.mjs";
 
 function copyToClipboard(text) {
   try {
@@ -77,6 +78,10 @@ export async function contextCommand(args) {
   const version   = String(contract.policyVersion).replace(/^v/i,"");
   const now       = new Date().toLocaleDateString("en-GB",{day:"2-digit",month:"short",year:"numeric"});
   const syncBadge = allInSync?"✓ validated":"⚠ out of sync";
+  const implementTask = state.intent || "describe the exact task to implement";
+  const implementInput = { task: implementTask, contract, caps: capabilities, scenarios: [], state };
+  const cursorPrompt = buildCursorImplementPrompt(implementInput);
+  const genericPrompt = buildGenericImplementPrompt(implementInput);
 
   const capLines  = capList.map(c=>"- **"+c.id+"** — "+c.title).join("\n");
   const chgLines  = recent.length>0 ? recent.map(e=>"### "+e.title+"\n"+e.items.map(i=>"  - "+i).join("\n")).join("\n\n") : "_No recent changes_";
@@ -98,6 +103,24 @@ export async function contextCommand(args) {
     "## What I am working on right now","",workingLine,"","---","",
     "## Intent — what I want to build next","",intentLine,"","---","",
     "## Decisions & notes","",decLines,"","---",
+    "",
+    "## Implementation Prompt Seed","",
+    "Use this to start coding immediately with an agent:","",
+    "```bash",
+    `infernoflow implement "${implementTask}" --mode both`,
+    "```",
+    "",
+    "### Cursor Agent Prompt","",
+    "```text",
+    cursorPrompt,
+    "```",
+    "",
+    "### Generic Agent Prompt","",
+    "```text",
+    genericPrompt,
+    "```",
+    "",
+    "---",
     "_Paste this block at the start of any new AI session._"
   ].join("\n");
 
@@ -125,6 +148,8 @@ export async function contextCommand(args) {
   console.log("  Working on   "+(state.working?cyan(state.working):gray("not set")));
   console.log("  Intent       "+(state.intent ?cyan(state.intent) :gray("not set")));
   console.log("  Decisions    "+(state.decisions?state.decisions.length:0)+" recorded\n");
+  console.log("  "+bold("Implementation Prompt"));
+  console.log("  "+cyan("→")+" Run "+cyan(`infernoflow implement "${implementTask}" --mode both`)+"\n");
 
   if(copyFlag){
     console.log("  "+bold("Ready to use:"));

package/lib/commands/docGate.mjs

@@ -13,8 +13,10 @@ const CODE_PREFIXES = [
 ];
 
 export async function docGateCommand(opts = {}) {
-  const silent = opts?.silent || false;
-  const captureExit = opts?.captureExit || false;
+  const fromArgs = Array.isArray(opts);
+  const silent = fromArgs ? false : (opts?.silent || false);
+  const captureExit = fromArgs ? false : (opts?.captureExit || false);
+  const jsonOut = fromArgs ? opts.includes("--json") : Boolean(opts?.json);
   const base = process.env.BASE_SHA || "HEAD~1";
   const head = process.env.HEAD_SHA || "HEAD";
 
@@ -23,11 +25,19 @@ export async function docGateCommand(opts = {}) {
     const out = sh(`git diff --name-only ${base}..${head}`);
     files = out ? out.split("\n").filter(Boolean) : [];
   } catch {
+    if (jsonOut) {
+      console.log(JSON.stringify({ ok: true, skipped: true, reason: "no_git_available" }, null, 2));
+      return;
+    }
     if (!silent) info(gray("doc-gate skipped (no git available)"));
     return;
   }
 
   if (files.length === 0) {
+    if (jsonOut) {
+      console.log(JSON.stringify({ ok: true, changedFiles: 0, changedCode: false, changedInferno: false }, null, 2));
+      return;
+    }
     if (!silent) ok("doc-gate: no changed files");
     return;
   }
@@ -36,6 +46,21 @@ export async function docGateCommand(opts = {}) {
     CODE_PREFIXES.some(p => f.startsWith(p) || f.includes("/" + p))
   );
   const changedInferno = files.some(f => f.startsWith("inferno/"));
+  const codeFiles = files.filter(f => CODE_PREFIXES.some(p => f.startsWith(p))).slice(0, 5);
+
+  if (jsonOut) {
+    const payload = {
+      ok: !(changedCode && !changedInferno),
+      changedFiles: files.length,
+      changedCode,
+      changedInferno,
+      sampleCodeFiles: codeFiles,
+      hint: changedCode && !changedInferno ? "Update at least one file in inferno/ before committing" : null,
+    };
+    console.log(JSON.stringify(payload, null, 2));
+    if (!payload.ok) process.exit(1);
+    return;
+  }
 
   if (changedCode && !changedInferno) {
     if (!silent) {
@@ -43,7 +68,6 @@ export async function docGateCommand(opts = {}) {
         "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)));

package/lib/commands/implement.mjs

@@ -0,0 +1,103 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import { header, section, info, warn, cyan, gray, errorAndExit } from "../ui/output.mjs";
+import {
+  loadImplementContext,
+  buildCursorImplementPrompt,
+  buildGenericImplementPrompt,
+} from "../ui/prompts.mjs";
+
+function getFlagValue(args, flag) {
+  const idx = args.indexOf(flag);
+  return idx !== -1 && args[idx + 1] ? args[idx + 1] : null;
+}
+
+function extractTask(args) {
+  const skipNextFor = new Set(["--mode"]);
+  const parts = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+    if (token.startsWith("-")) {
+      if (skipNextFor.has(token)) i += 1;
+      continue;
+    }
+    if (i === 0) continue; // command name
+    parts.push(token);
+  }
+  return parts.join(" ").trim();
+}
+
+function copyToClipboard(text) {
+  try {
+    const p = process.platform;
+    if (p === "win32") execSync("clip", { input: text });
+    else if (p === "darwin") execSync("pbcopy", { input: text });
+    else {
+      try { execSync("xclip -selection clipboard", { input: text }); }
+      catch { execSync("xsel --clipboard --input", { input: text }); }
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function implementCommand(args = []) {
+  header("implement");
+
+  const cwd = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+  if (!fs.existsSync(infernoDir)) {
+    errorAndExit("inferno/ not found", "Run: infernoflow init");
+  }
+
+  const mode = (getFlagValue(args, "--mode") || "both").toLowerCase();
+  const copyFlag = args.includes("--copy") || args.includes("-c");
+  if (!["cursor", "generic", "both"].includes(mode)) {
+    errorAndExit("Invalid --mode value", "Use: --mode cursor|generic|both");
+  }
+
+  const rawTask = extractTask(args);
+  if (!rawTask) {
+    errorAndExit("No task provided", 'Usage: infernoflow implement "your task description"');
+  }
+
+  const context = loadImplementContext(cwd);
+  const cursorPrompt = buildCursorImplementPrompt({ task: rawTask, ...context });
+  const genericPrompt = buildGenericImplementPrompt({ task: rawTask, ...context });
+
+  info(`Task: ${cyan(rawTask)}`);
+  info(`Mode: ${cyan(mode)}`);
+  warn("If you hit model high-load/resource-exhausted, retry with Auto/another model.");
+
+  if (mode === "cursor" || mode === "both") {
+    section("Cursor Agent Prompt");
+    console.log();
+    console.log(gray("─".repeat(50)));
+    console.log(cursorPrompt);
+    console.log(gray("─".repeat(50)));
+  }
+
+  if (mode === "generic" || mode === "both") {
+    section("Generic Agent Prompt");
+    console.log();
+    console.log(gray("─".repeat(50)));
+    console.log(genericPrompt);
+    console.log(gray("─".repeat(50)));
+  }
+
+  if (copyFlag) {
+    const textToCopy =
+      mode === "cursor"
+        ? cursorPrompt
+        : mode === "generic"
+          ? genericPrompt
+          : `## Cursor Agent Prompt\n\n${cursorPrompt}\n\n## Generic Agent Prompt\n\n${genericPrompt}`;
+    const ok = copyToClipboard(textToCopy);
+    if (ok) info(`Copied ${mode} prompt${mode === "both" ? "s" : ""} to clipboard.`);
+    else warn("Clipboard copy failed. Copy from terminal output.");
+  }
+
+  console.log();
+}

package/lib/commands/status.mjs

@@ -1,6 +1,6 @@
 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";
+import { header, ok, fail, warn, section, bold, cyan, yellow, gray, green, red, white } from "../ui/output.mjs";
 
 function timeAgo(ms) {
   const s = Math.floor((Date.now() - ms) / 1000);
@@ -23,13 +23,19 @@ function getCoverage(scenariosDir, caps) {
   return { covered: caps.filter(c => covered.has(c)), uncovered: caps.filter(c => !covered.has(c)) };
 }
 
-export async function statusCommand() {
+export async function statusCommand(args = []) {
+  const asJson = args.includes("--json");
   const cwd = process.cwd();
   const infernoDir = path.join(cwd, "inferno");
-
-  header("status");
+  if (!asJson) {
+    header("status");
+  }
 
   if (!fs.existsSync(infernoDir)) {
+    if (asJson) {
+      console.log(JSON.stringify({ ok: false, error: "inferno_not_found", hint: "Run: infernoflow init" }, null, 2));
+      process.exit(1);
+    }
     fail("inferno/ not found", `Run: infernoflow init`);
     console.log();
     process.exit(1);
@@ -37,6 +43,10 @@ export async function statusCommand() {
 
   const contractPath = path.join(infernoDir, "contract.json");
   if (!fs.existsSync(contractPath)) {
+    if (asJson) {
+      console.log(JSON.stringify({ ok: false, error: "contract_not_found" }, null, 2));
+      process.exit(1);
+    }
     fail("contract.json not found");
     console.log();
     process.exit(1);
@@ -48,6 +58,39 @@ export async function statusCommand() {
   const scenariosDir = path.join(infernoDir, "scenarios");
   const changelogPath = path.join(infernoDir, "CHANGELOG.md");
   const capsPath = path.join(infernoDir, "capabilities.json");
+  const { covered, uncovered } = getCoverage(scenariosDir, caps);
+
+  const hasChangelog = fs.existsSync(changelogPath) && /##\s+Unreleased/i.test(fs.readFileSync(changelogPath, "utf8"));
+  const driftReasons = [];
+  if (uncovered.length > 0) driftReasons.push(`${uncovered.length} capabilities without scenario coverage`);
+  if (!hasChangelog) driftReasons.push("CHANGELOG missing ## Unreleased section");
+  const allGood = driftReasons.length === 0;
+
+  if (asJson) {
+    const payload = {
+      ok: allGood,
+      driftReasons,
+      project: {
+        policyId: contract.policyId || null,
+        policyVersion: contract.policyVersion || null,
+        lastChange: timeAgo(stat.mtimeMs),
+      },
+      capabilities: {
+        total: caps.length,
+        uncovered,
+      },
+      changelog: {
+        hasUnreleased: hasChangelog,
+      },
+    };
+    console.log(JSON.stringify(payload, null, 2));
+    process.exit(allGood ? 0 : 1);
+  }
+
+  if (!allGood) {
+    section("Drift");
+    driftReasons.forEach((reason) => console.log(`  ${yellow("⚠")} ${reason}`));
+  }
 
   // ── Project ─────────────────────────────────────────────────────
   section("Project");
@@ -66,8 +109,6 @@ export async function statusCommand() {
     } catch {}
   }
 
-  const { covered, uncovered } = getCoverage(scenariosDir, caps);
-
   caps.forEach(cap => {
     const reg = capsRegistry[cap];
     const hasCoverage = covered.includes(cap);
@@ -122,8 +163,6 @@ export async function statusCommand() {
 
   // ── 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 {

package/lib/commands/suggest.mjs

@@ -87,7 +87,90 @@ Rules:
 - Keep it minimal and accurate`;
 }
 
-function applyChanges({ cwd, contract, capabilities, scenarios, suggestion, version }) {
+function validateSuggestion(suggestion) {
+  const errors = [];
+  if (!suggestion || typeof suggestion !== "object") {
+    return ["AI response must be a JSON object."];
+  }
+  if (suggestion.summary != null && typeof suggestion.summary !== "string") {
+    errors.push(`"summary" must be a string.`);
+  }
+  if (!Array.isArray(suggestion.newCapabilities)) {
+    errors.push(`"newCapabilities" must be an array.`);
+  }
+  if (!Array.isArray(suggestion.removedCapabilities)) {
+    errors.push(`"removedCapabilities" must be an array.`);
+  }
+  if (!Array.isArray(suggestion.updatedScenarios)) {
+    errors.push(`"updatedScenarios" must be an array.`);
+  }
+  if (suggestion.changelogEntry != null && typeof suggestion.changelogEntry !== "string") {
+    errors.push(`"changelogEntry" must be a string.`);
+  }
+
+  for (const c of suggestion.newCapabilities || []) {
+    if (!c || typeof c !== "object") {
+      errors.push(`Each item in "newCapabilities" must be an object.`);
+      continue;
+    }
+    if (typeof c.id !== "string" || !/^[A-Z][A-Za-z0-9]*$/.test(c.id)) {
+      errors.push(`newCapabilities[].id must be PascalCase (example: SendEmail).`);
+    }
+    if (typeof c.title !== "string" || !c.title.trim()) {
+      errors.push(`newCapabilities[].title must be a non-empty string.`);
+    }
+  }
+
+  for (const id of suggestion.removedCapabilities || []) {
+    if (typeof id !== "string" || !id.trim()) {
+      errors.push(`removedCapabilities[] must contain non-empty strings.`);
+    }
+  }
+
+  for (const s of suggestion.updatedScenarios || []) {
+    if (!s || typeof s !== "object") {
+      errors.push(`Each item in "updatedScenarios" must be an object.`);
+      continue;
+    }
+    if (typeof s.file !== "string" || !s.file.endsWith(".json")) {
+      errors.push(`updatedScenarios[].file must be a .json filename.`);
+    }
+    if (typeof s.isNew !== "boolean") {
+      errors.push(`updatedScenarios[].isNew must be boolean.`);
+    }
+    if (!Array.isArray(s.capabilitiesCovered) || !Array.isArray(s.stepsToAdd)) {
+      errors.push(`updatedScenarios[].capabilitiesCovered and stepsToAdd must be arrays.`);
+    }
+  }
+
+  return errors;
+}
+
+function detectSuggestionConflicts(contract, suggestion) {
+  const issues = [];
+  const existing = new Set(contract.capabilities || []);
+  const newIds = new Set((suggestion.newCapabilities || []).map((c) => c.id));
+  const removed = new Set(suggestion.removedCapabilities || []);
+
+  for (const id of newIds) {
+    if (removed.has(id)) {
+      issues.push(`Capability "${id}" appears in both newCapabilities and removedCapabilities.`);
+    }
+    if (existing.has(id)) {
+      issues.push(`Capability "${id}" already exists in contract capabilities.`);
+    }
+  }
+
+  for (const id of removed) {
+    if (!existing.has(id)) {
+      issues.push(`Capability "${id}" cannot be removed because it does not exist in contract.`);
+    }
+  }
+
+  return issues;
+}
+
+function applyChanges({ cwd, contract, capabilities, suggestion, version }) {
   const infernoDir = path.join(cwd, "inferno");
   const contractPath = path.join(infernoDir, "contract.json");
   const capsPath = path.join(infernoDir, "capabilities.json");
@@ -100,6 +183,8 @@ function applyChanges({ cwd, contract, capabilities, scenarios, suggestion, vers
   const changelogEntry = suggestion.changelogEntry || "";
 
   let changed = false;
+  const writes = [];
+  const queueWrite = (filePath, content) => writes.push({ filePath, content });
 
   // ── contract.json ─────────────────────────────────────────────────────────
   if (newCaps.length > 0 || removedCaps.length > 0) {
@@ -107,23 +192,23 @@ function applyChanges({ cwd, contract, capabilities, scenarios, suggestion, vers
       ...contract.capabilities.filter(c => !removedCaps.includes(c)),
       ...newCaps.map(c => c.id)
     ];
-    contract.capabilities = updatedCaps;
-    contract.policyVersion = (contract.policyVersion || 1) + 1;
-    fs.writeFileSync(contractPath, JSON.stringify(contract, null, 2) + "\n");
-    ok(`contract.json updated → policyVersion: v${contract.policyVersion}`);
+    const nextVersion = Number(contract.policyVersion || 1) + 1;
+    const contractUpdated = { ...contract, capabilities: updatedCaps, policyVersion: nextVersion };
+    queueWrite(contractPath, JSON.stringify(contractUpdated, null, 2) + "\n");
+    ok(`contract.json updated → policyVersion: v${nextVersion}`);
     changed = true;
   }
 
   // ── capabilities.json ─────────────────────────────────────────────────────
   if (newCaps.length > 0 || removedCaps.length > 0) {
-    const reg = capabilities || { schemaVersion: 1, capabilities: [] };
-    reg.capabilities = reg.capabilities.filter(c => !removedCaps.includes(c.id));
+    const reg = capabilities ? { ...capabilities } : { schemaVersion: 1, capabilities: [] };
+    reg.capabilities = (reg.capabilities || []).filter(c => !removedCaps.includes(c.id));
     for (const nc of newCaps) {
       if (!reg.capabilities.find(c => c.id === nc.id)) {
         reg.capabilities.push({ id: nc.id, title: nc.title, since: version });
       }
     }
-    fs.writeFileSync(capsPath, JSON.stringify(reg, null, 2) + "\n");
+    queueWrite(capsPath, JSON.stringify(reg, null, 2) + "\n");
     ok(`capabilities.json updated`);
   }
 
@@ -139,7 +224,7 @@ function applyChanges({ cwd, contract, capabilities, scenarios, suggestion, vers
         capabilitiesCovered: us.capabilitiesCovered || [],
         steps: us.stepsToAdd || []
       };
-      fs.writeFileSync(filePath, JSON.stringify(scenario, null, 2) + "\n");
+      queueWrite(filePath, JSON.stringify(scenario, null, 2) + "\n");
       ok(`Created scenario: ${cyan(us.file)}`);
     } else {
       scenario = readJson(filePath);
@@ -147,7 +232,7 @@ function applyChanges({ cwd, contract, capabilities, scenarios, suggestion, vers
       (us.capabilitiesCovered || []).forEach(c => existingCaps.add(c));
       scenario.capabilitiesCovered = [...existingCaps];
       scenario.steps = [...(scenario.steps || []), ...(us.stepsToAdd || [])];
-      fs.writeFileSync(filePath, JSON.stringify(scenario, null, 2) + "\n");
+      queueWrite(filePath, JSON.stringify(scenario, null, 2) + "\n");
       ok(`Updated scenario: ${cyan(us.file)}`);
     }
     changed = true;
@@ -158,12 +243,35 @@ function applyChanges({ cwd, contract, capabilities, scenarios, suggestion, vers
     let txt = fs.readFileSync(changelogPath, "utf8");
     if (/##\s+Unreleased/i.test(txt)) {
       txt = txt.replace(/(##\s+Unreleased[^\n]*\n)/i, `$1\n${changelogEntry}\n`);
-      fs.writeFileSync(changelogPath, txt);
+      queueWrite(changelogPath, txt);
       ok(`CHANGELOG.md updated`);
       changed = true;
     }
   }
 
+  const backups = new Map();
+  try {
+    for (const write of writes) {
+      if (fs.existsSync(write.filePath)) {
+        backups.set(write.filePath, fs.readFileSync(write.filePath, "utf8"));
+      } else {
+        backups.set(write.filePath, null);
+      }
+      const tmpPath = `${write.filePath}.tmp`;
+      fs.writeFileSync(tmpPath, write.content);
+      fs.renameSync(tmpPath, write.filePath);
+    }
+  } catch (err) {
+    for (const [filePath, content] of backups.entries()) {
+      if (content === null) {
+        if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+      } else {
+        fs.writeFileSync(filePath, content);
+      }
+    }
+    throw new Error(`Failed applying changes. Rolled back. Details: ${err.message}`);
+  }
+
   return changed;
 }
 
@@ -276,6 +384,21 @@ export async function suggestCommand(args) {
     );
   }
 
+  const validationErrors = validateSuggestion(suggestion);
+  if (validationErrors.length > 0) {
+    errorAndExit(
+      "AI response schema is invalid",
+      validationErrors[0] + (validationErrors.length > 1 ? ` (+${validationErrors.length - 1} more)` : "")
+    );
+  }
+  const conflictErrors = detectSuggestionConflicts(contract, suggestion);
+  if (conflictErrors.length > 0) {
+    errorAndExit(
+      "AI response contains conflicting capability operations",
+      conflictErrors[0] + (conflictErrors.length > 1 ? ` (+${conflictErrors.length - 1} more)` : "")
+    );
+  }
+
   // ── Preview ───────────────────────────────────────────────────────────────
   section("Proposed Changes");
   console.log();
@@ -337,7 +460,7 @@ export async function suggestCommand(args) {
   section("Applying Changes");
   console.log();
 
-  applyChanges({ cwd, contract, capabilities, scenarios, suggestion, version });
+  applyChanges({ cwd, contract, capabilities, suggestion, version });
 
   done("suggest complete!");
 

package/lib/ui/prompts.mjs

@@ -1,6 +1,8 @@
 // Zero-dependency interactive prompts using readline
 
 import * as readline from "node:readline";
+import * as fs from "node:fs";
+import * as path from "node:path";
 
 function ask(question, defaultVal = "") {
   return new Promise(resolve => {
@@ -18,3 +20,128 @@ export async function promptInit() {
   const caps = await ask("Capabilities (comma-separated)", "CreateTask, ReadTasks, UpdateTask, DeleteTask");
   return { policyId, capabilities: caps.split(",").map(c => c.trim()).filter(Boolean) };
 }
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function loadImplementContext(cwd) {
+  const infernoDir = path.join(cwd, "inferno");
+  const contract = readJson(path.join(infernoDir, "contract.json")) || {};
+  const caps = readJson(path.join(infernoDir, "capabilities.json")) || { capabilities: [] };
+  const state = readJson(path.join(infernoDir, "context-state.json")) || {};
+  const scenariosDir = path.join(infernoDir, "scenarios");
+
+  const scenarios = [];
+  if (fs.existsSync(scenariosDir)) {
+    for (const fileName of fs.readdirSync(scenariosDir).filter((f) => f.endsWith(".json"))) {
+      const scenario = readJson(path.join(scenariosDir, fileName));
+      if (scenario) scenarios.push({ file: fileName, scenario });
+    }
+  }
+
+  return { contract, caps, state, scenarios };
+}
+
+function renderCaps(capsRegistry) {
+  const list = capsRegistry?.capabilities || [];
+  if (list.length === 0) return "- none";
+  return list.map((c) => `- ${c.id}: ${c.title || c.id}`).join("\n");
+}
+
+function renderScenarios(scenarios) {
+  if (!scenarios || scenarios.length === 0) return "- none";
+  return scenarios
+    .map(({ file, scenario }) => {
+      const covered = (scenario.capabilitiesCovered || []).join(", ") || "none";
+      return `- ${file}: covers [${covered}]`;
+    })
+    .join("\n");
+}
+
+function baseContextBlock({ contract, caps, scenarios, state }) {
+  const policy = contract?.policyId || "unknown-policy";
+  const version = contract?.policyVersion ?? "unknown";
+  const declared = (contract?.capabilities || []).join(", ") || "none";
+  const working = state?.working || "not set";
+  const intent = state?.intent || "not set";
+
+  return [
+    `Project policyId: ${policy}`,
+    `Policy version: ${version}`,
+    `Declared capabilities: [${declared}]`,
+    `Working on: ${working}`,
+    `Intent: ${intent}`,
+    "",
+    "Capabilities registry:",
+    renderCaps(caps),
+    "",
+    "Scenarios:",
+    renderScenarios(scenarios),
+  ].join("\n");
+}
+
+export function buildCursorImplementPrompt({ task, contract, caps, scenarios, state }) {
+  return [
+    "You are a Cursor coding agent working inside my repository.",
+    "Implement the task end-to-end with minimal reliable changes.",
+    "",
+    baseContextBlock({ contract, caps, scenarios, state }),
+    "",
+    `Task: ${task}`,
+    "",
+    "Requirements:",
+    "1) Propose smallest safe implementation.",
+    "2) Explain which files you changed and why.",
+    "3) Implement production-ready code.",
+    "4) Preserve backward compatibility unless explicitly requested.",
+    "5) Update tests or add smoke checks.",
+    "6) Provide run/verify commands.",
+    "7) If assumptions are needed, state briefly and proceed with sensible defaults.",
+    "",
+    "Output format:",
+    "- Plan (short)",
+    "- Code changes (by file)",
+    "- Tests updated/added",
+    "- Commands to run",
+    "- Acceptance checklist",
+    "",
+    "Quality bar:",
+    "- No TODO placeholders in final code",
+    "- Handle edge cases and errors",
+    "- Keep naming/style consistent",
+    "- Prefer simple maintainable solutions",
+    "",
+    "If model is overloaded (resource exhausted), retry with Auto/another model and continue deterministically.",
+  ].join("\n");
+}
+
+export function buildGenericImplementPrompt({ task, contract, caps, scenarios, state }) {
+  return [
+    "You are my senior software engineer pair.",
+    "Implement this task end-to-end in my project.",
+    "",
+    baseContextBlock({ contract, caps, scenarios, state }),
+    "",
+    `Goal: ${task}`,
+    "",
+    "Deliverables:",
+    "- Short implementation plan",
+    "- Exact file-level changes",
+    "- Test updates",
+    "- Verification commands",
+    "- Final acceptance checklist",
+    "",
+    "Constraints:",
+    "- Keep backward compatibility by default",
+    "- Make minimal reliable changes",
+    "- Handle edge cases and error states",
+    "- Keep output concise and actionable",
+    "",
+    "If you encounter temporary model high-load errors, retry and preserve the same output structure.",
+  ].join("\n");
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "infernoflow",
-  "version": "0.8.0",
+  "version": "0.10.1",
   "description": "The forge for liquid code — keep capabilities, contracts, and docs in sync.",
   "type": "module",
   "bin": {
-    "infernoflow": "./bin/infernoflow.mjs"
+    "infernoflow": "bin/infernoflow.mjs"
   },
   "engines": {
     "node": ">=18"
@@ -16,7 +16,8 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node bin/infernoflow.mjs --help"
+    "test": "node scripts/smoke.mjs && node scripts/json-smoke.mjs && node scripts/json-negative-smoke.mjs && node scripts/implement-smoke.mjs",
+    "test:help": "node bin/infernoflow.mjs --help"
   },
   "keywords": [
     "cli",
@@ -32,7 +33,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ronmiz/infernoflow.git"
+    "url": "git+https://github.com/ronmiz/infernoflow.git"
   },
   "homepage": "https://github.com/ronmiz/infernoflow#readme",
   "bugs": {