infernoflow 0.10.9 → 0.10.11

package/README.md

@@ -28,6 +28,17 @@ npx infernoflow init
 # 1. Scaffold in your project root:
 npx infernoflow init
 
+# Optional: same as init, plus Cursor hooks that append each Agent reply
+# to inferno/CONTEXT.draft.md (gitignored). Promote with npm run inferno:promote-draft.
+npx infernoflow init --yes --cursor-hooks
+
+# Optional: VS Code + GitHub Copilot agent hooks (Preview) — same draft file + promote flow
+npx infernoflow init --yes --vscode-copilot-hooks
+
+# Or add hooks to an existing infernoflow project:
+npx infernoflow install-cursor-hooks
+npx infernoflow install-vscode-copilot-hooks
+
 # 2. See your contract health:
 infernoflow status
 
@@ -172,11 +183,38 @@ infernoflow doc-gate --json
 | `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 |
+| `infernoflow install-cursor-hooks` | Install `.cursor/hooks` + `scripts/inferno-promote-draft.mjs` (Agent → draft → promote) |
+| `infernoflow install-vscode-copilot-hooks` | Install `.github/hooks` for VS Code + Copilot (Preview) + same promote script |
+
+### Cursor hooks (draft → promote)
+
+[Cursor hooks](https://cursor.com/docs/agent/hooks) can run a small Node script after each assistant message. infernoflow can install:
+
+- **`.cursor/hooks.json`** — `afterAgentResponse` and `stop` events
+- **`.cursor/hooks/inferno-session-draft.mjs`** — appends assistant `text` to **`inferno/CONTEXT.draft.md`** (never overwrites `CONTEXT.md` automatically)
+- **`scripts/inferno-promote-draft.mjs`** + **`npm run inferno:promote-draft`** — preview, `--append-notes` (merge under `## Decisions & notes` in `inferno/CONTEXT.md`), or `--clear`
+- **`.gitignore`** entry for `inferno/CONTEXT.draft.md` when possible
+
+Install with **`infernoflow install-cursor-hooks`** or **`infernoflow init --cursor-hooks`**. Restart Cursor after install. Review the draft before promoting; treat chat as **input**, not product truth.
+
+### VS Code + GitHub Copilot hooks (draft → promote, Preview)
+
+VS Code can run [Agent hooks](https://code.visualstudio.com/docs/copilot/customization/hooks) from **`.github/hooks/*.json`**. infernoflow installs:
+
+- **`.github/hooks/infernoflow-drafts.json`** — wires **`UserPromptSubmit`** (your prompt) and **`Stop`** (end of agent turn)
+- **`scripts/inferno-vscode-copilot-hook.mjs`** — appends the user prompt on submit; on **Stop**, reads **`transcript_path`** from stdin (when present), parses **JSONL** or session **JSON**, and appends the **last assistant text** it can infer (format varies by VS Code / Copilot version — if parsing fails, a short marker is still appended)
+- The same **`inferno:promote-draft`** script and **`.gitignore`** entry for **`inferno/CONTEXT.draft.md`** as the Cursor flow
+
+Install with **`infernoflow install-vscode-copilot-hooks`** or **`infernoflow init --vscode-copilot-hooks`**. Restart VS Code, confirm your org allows hooks, and use the **GitHub Copilot Chat Hooks** output channel for diagnostics.
+
+**Limitations:** Hooks are **Preview**; `transcript_path` / JSONL shape may differ by build; some hook events omit `transcript_path` ([vscode#300583](https://github.com/microsoft/vscode/issues/300583)). You still have the full **`infernoflow`** CLI in the terminal when hooks are not enough.
 
 ### Options
 
 ```bash
 infernoflow init --force       # overwrite existing files
+infernoflow init --cursor-hooks # with init: install Cursor draft hooks (see above)
+infernoflow init --vscode-copilot-hooks # with init: install VS Code + Copilot draft hooks (Preview)
 infernoflow init --yes         # skip prompts, use defaults
 infernoflow init --adopt       # infer baseline from existing project
 infernoflow init --adopt --lang ts --framework react --project-type frontend
@@ -194,6 +232,8 @@ infernoflow pr-impact --json
 infernoflow sync --auto
 infernoflow sync --auto --json
 npm run inferno:hooks      # install local git hooks (after init)
+infernoflow install-cursor-hooks --force  # overwrite hook files if present
+infernoflow install-vscode-copilot-hooks --force
 infernoflow check --json       # machine-readable output for CI
 infernoflow check --skip-doc-gate
 infernoflow status --json      # machine-readable status summary

package/bin/infernoflow.mjs

@@ -9,6 +9,9 @@ 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 (or adopt existing project)",
+  "install-cursor-hooks": "Install Cursor hooks: draft agent replies to inferno/CONTEXT.draft.md",
+  "install-vscode-copilot-hooks":
+    "Install VS Code + Copilot agent hooks (Preview): draft to inferno/CONTEXT.draft.md",
   check: "Validate contract, capabilities, scenarios, changelog",
   status: "Show contract health at a glance",
   "pr-impact": "Summarize PR impact on capabilities and docs",
@@ -22,6 +25,10 @@ const COMMAND_DESCRIPTIONS = {
 
 const COMMAND_HANDLERS = {
   init: async (args) => (await import("../lib/commands/init.mjs")).initCommand(args),
+  "install-cursor-hooks": async (args) =>
+    (await import("../lib/commands/installCursorHooks.mjs")).installCursorHooksCommand(args),
+  "install-vscode-copilot-hooks": async (args) =>
+    (await import("../lib/commands/installVsCodeCopilotHooks.mjs")).installVsCodeCopilotHooksCommand(args),
   check: async (args) => (await import("../lib/commands/check.mjs")).checkCommand(args),
   status: async (args) => (await import("../lib/commands/status.mjs")).statusCommand(args),
   "pr-impact": async (args) => (await import("../lib/commands/prImpact.mjs")).prImpactCommand(args),
@@ -34,8 +41,10 @@ const COMMAND_HANDLERS = {
 };
 
 function formatCommandsHelp() {
+  const names = Object.keys(COMMAND_DESCRIPTIONS);
+  const w = Math.max(...names.map((n) => n.length), 8) + 1;
   return Object.entries(COMMAND_DESCRIPTIONS)
-    .map(([name, desc]) => `    ${name.padEnd(13, " ")}${desc}`)
+    .map(([name, desc]) => `    ${name.padEnd(w, " ")}${desc}`)
     .join("\n");
 }
 
@@ -50,6 +59,8 @@ const HELP = `
 ${formatCommandsHelp()}
 
   ${bold("init options:")}
+    --cursor-hooks           Also install Cursor hooks (draft → inferno/CONTEXT.draft.md)
+    --vscode-copilot-hooks   Also install VS Code + Copilot hooks (.github/hooks — Preview)
     --adopt             Infer capabilities from an existing codebase
     --lang <name>       Override detected language (e.g. ts, js, py)
     --framework <name>  Override detected framework (e.g. react, angular, express)
@@ -60,6 +71,12 @@ ${formatCommandsHelp()}
     --yes, -y           Skip prompts and accept inferred/default values
     --force, -f         Overwrite existing inferno/ files
 
+  ${bold("install-cursor-hooks options:")}
+    --force, -f         Overwrite .cursor/hooks.json and hook scripts if they exist
+
+  ${bold("install-vscode-copilot-hooks options:")}
+    --force, -f         Overwrite .github/hooks/infernoflow-drafts.json and scripts if they exist
+
   ${bold("context options:")}
     --intent  "..."     What you plan to build next
     --working "..."     What you are building right now

package/lib/commands/init.mjs

@@ -11,6 +11,8 @@ import {
   summarizeCapabilities,
   buildSignalsReport,
 } from "./adopt.mjs";
+import { installCursorHooksArtifacts } from "../cursorHooksInstall.mjs";
+import { installVsCodeCopilotHooksArtifacts } from "../vsCodeCopilotHooksInstall.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -153,6 +155,8 @@ export async function initCommand(args) {
   const force = args.includes("--force") || args.includes("-f");
   const yes = args.includes("--yes") || args.includes("-y");
   const adopt = args.includes("--adopt");
+  const cursorHooks = args.includes("--cursor-hooks");
+  const vscodeCopilotHooks = args.includes("--vscode-copilot-hooks");
   const reportJson = args.includes("--report-json");
   const reportJsonOnly = args.includes("--report-json-only");
   const reportHumanOnly = args.includes("--report-human-only");
@@ -317,6 +321,35 @@ export async function initCommand(args) {
 
   upsertScripts(cwd, silent);
 
+  if (cursorHooks) {
+    installCursorHooksArtifacts({
+      cwd,
+      templatesRoot: templates,
+      force,
+      silent,
+      logOk: (msg) => {
+        if (!silent) ok(msg);
+      },
+      logWarn: (msg) => {
+        if (!silent) warn(msg);
+      },
+    });
+  }
+  if (vscodeCopilotHooks) {
+    installVsCodeCopilotHooksArtifacts({
+      cwd,
+      templatesRoot: templates,
+      force,
+      silent,
+      logOk: (msg) => {
+        if (!silent) ok(msg);
+      },
+      logWarn: (msg) => {
+        if (!silent) warn(msg);
+      },
+    });
+  }
+
   if (adopt) {
     const statePath = path.join(infernoDir, "context-state.json");
     let state = {};
@@ -341,7 +374,28 @@ export async function initCommand(args) {
       cyan("infernoflow check") + "   — validate everything",
       (adopt ? "Review inferred baseline in " : "Edit ") + yellow("inferno/capabilities.json") + (adopt ? " and refine IDs/titles" : " to describe each capability in detail"),
       "Add more " + yellow("inferno/scenarios/*.json") + " files for edge cases",
-      "Add " + cyan("inferno:check") + " to your CI pipeline"
+      "Add " + cyan("inferno:check") + " to your CI pipeline",
+      ...(cursorHooks
+        ? [
+            "Restart Cursor — hooks write assistant text to " + yellow("inferno/CONTEXT.draft.md"),
+            "Promote when ready: " + cyan("npm run inferno:promote-draft -- --append-notes"),
+          ]
+        : []),
+      ...(vscodeCopilotHooks
+        ? [
+            "Restart VS Code — Copilot hooks append prompts + assistant (from transcript) to " +
+              yellow("inferno/CONTEXT.draft.md"),
+            "Promote when ready: " + cyan("npm run inferno:promote-draft -- --append-notes"),
+          ]
+        : []),
+      ...(!cursorHooks && !vscodeCopilotHooks
+        ? [
+            "Optional: " +
+              cyan("infernoflow install-cursor-hooks") +
+              " or " +
+              cyan("infernoflow install-vscode-copilot-hooks"),
+          ]
+        : []),
     ]);
   }
 }

package/lib/commands/installCursorHooks.mjs

@@ -0,0 +1,36 @@
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { header, ok, warn, done, nextSteps, cyan, yellow } from "../ui/output.mjs";
+import { installCursorHooksArtifacts } from "../cursorHooksInstall.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function getTemplatesRoot() {
+  return path.resolve(__dirname, "../../templates");
+}
+
+export async function installCursorHooksCommand(args) {
+  const cwd = process.cwd();
+  const force = args.includes("--force") || args.includes("-f");
+
+  header("install-cursor-hooks");
+
+  installCursorHooksArtifacts({
+    cwd,
+    templatesRoot: getTemplatesRoot(),
+    force,
+    silent: false,
+    logOk: (msg) => ok(msg),
+    logWarn: (msg) => warn(msg),
+  });
+
+  done("Cursor draft hooks installed");
+
+  nextSteps([
+    "Restart Cursor (or reload window) so " + yellow(".cursor/hooks.json") + " is picked up",
+    "Use Agent chat — each assistant reply appends to " + yellow("inferno/CONTEXT.draft.md") + " (gitignored)",
+    cyan("npm run inferno:promote-draft") + " — preview draft",
+    cyan("npm run inferno:promote-draft -- --append-notes") + " — merge into inferno/CONTEXT.md under Decisions",
+    cyan("npm run inferno:promote-draft -- --clear") + " — discard draft",
+  ]);
+}

package/lib/commands/installVsCodeCopilotHooks.mjs

@@ -0,0 +1,37 @@
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { header, ok, warn, done, nextSteps, cyan, yellow } from "../ui/output.mjs";
+import { installVsCodeCopilotHooksArtifacts } from "../vsCodeCopilotHooksInstall.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function getTemplatesRoot() {
+  return path.resolve(__dirname, "../../templates");
+}
+
+export async function installVsCodeCopilotHooksCommand(args) {
+  const cwd = process.cwd();
+  const force = args.includes("--force") || args.includes("-f");
+
+  header("install-vscode-copilot-hooks");
+
+  installVsCodeCopilotHooksArtifacts({
+    cwd,
+    templatesRoot: getTemplatesRoot(),
+    force,
+    silent: false,
+    logOk: (msg) => ok(msg),
+    logWarn: (msg) => warn(msg),
+  });
+
+  done("VS Code / Copilot draft hooks installed");
+
+  nextSteps([
+    "Requires VS Code + GitHub Copilot and **Agent hooks (Preview)** — see " +
+      yellow("https://code.visualstudio.com/docs/copilot/customization/hooks"),
+    "Hooks load from " + yellow(".github/hooks/*.json") + " — restart VS Code or reload window after first install",
+    "Check the **GitHub Copilot Chat Hooks** output channel if nothing runs",
+    cyan("npm run inferno:promote-draft") + " — preview draft",
+    cyan("npm run inferno:promote-draft -- --append-notes") + " — merge into inferno/CONTEXT.md",
+  ]);
+}

package/lib/cursorHooksInstall.mjs

@@ -0,0 +1,39 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { installInfernoDraftTooling } from "./draftToolingInstall.mjs";
+
+/**
+ * @param {object} opts
+ * @param {string} opts.cwd
+ * @param {string} opts.templatesRoot
+ * @param {boolean} opts.force
+ * @param {boolean} opts.silent
+ * @param {(msg: string) => void} [opts.logOk]
+ * @param {(msg: string) => void} [opts.logWarn]
+ */
+export function installCursorHooksArtifacts(opts) {
+  const { cwd, templatesRoot, force, silent } = opts;
+  const logOk = opts.logOk || (() => {});
+  const logWarn = opts.logWarn || (() => {});
+
+  function copyFile(src, dst) {
+    if (fs.existsSync(dst) && !force) {
+      if (!silent) logWarn("Skipped (exists): " + path.relative(cwd, dst));
+      return false;
+    }
+    fs.mkdirSync(path.dirname(dst), { recursive: true });
+    fs.copyFileSync(src, dst);
+    if (!silent) logOk("Created: " + path.relative(cwd, dst));
+    return true;
+  }
+
+  installInfernoDraftTooling({ cwd, templatesRoot, force, silent, logOk, logWarn });
+
+  const srcHooksJson = path.join(templatesRoot, "cursor", "hooks.json");
+  const dstHooksJson = path.join(cwd, ".cursor", "hooks.json");
+  const srcHook = path.join(templatesRoot, "cursor", "hooks", "inferno-session-draft.mjs");
+  const dstHook = path.join(cwd, ".cursor", "hooks", "inferno-session-draft.mjs");
+
+  copyFile(srcHooksJson, dstHooksJson);
+  copyFile(srcHook, dstHook);
+}

package/lib/draftToolingInstall.mjs

@@ -0,0 +1,69 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const GITIGNORE_SNIPPET = `
+# infernoflow: agent draft (IDE hooks — review before commit)
+inferno/CONTEXT.draft.md
+`.trimStart();
+
+function upsertPromoteScript(cwd, silent, logOk) {
+  const pkgPath = path.join(cwd, "package.json");
+  if (!fs.existsSync(pkgPath)) {
+    if (!silent) logOk("No package.json — add script manually: inferno:promote-draft");
+    return;
+  }
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  pkg.scripts = pkg.scripts || {};
+  if (!pkg.scripts["inferno:promote-draft"]) {
+    pkg.scripts["inferno:promote-draft"] = "node scripts/inferno-promote-draft.mjs";
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+    if (!silent) logOk("Updated package.json script: inferno:promote-draft");
+  }
+}
+
+/**
+ * inferno/CONTEXT.draft.md gitignore + promote script (shared by Cursor and VS Code installers).
+ * @param {object} opts
+ * @param {string} opts.cwd
+ * @param {string} opts.templatesRoot
+ * @param {boolean} opts.force
+ * @param {boolean} opts.silent
+ * @param {(msg: string) => void} [opts.logOk]
+ * @param {(msg: string) => void} [opts.logWarn]
+ */
+export function installInfernoDraftTooling(opts) {
+  const { cwd, templatesRoot, force, silent } = opts;
+  const logOk = opts.logOk || (() => {});
+  const logWarn = opts.logWarn || (() => {});
+
+  function copyFile(src, dst) {
+    if (fs.existsSync(dst) && !force) {
+      if (!silent) logWarn("Skipped (exists): " + path.relative(cwd, dst));
+      return false;
+    }
+    fs.mkdirSync(path.dirname(dst), { recursive: true });
+    fs.copyFileSync(src, dst);
+    if (!silent) logOk("Created: " + path.relative(cwd, dst));
+    return true;
+  }
+
+  const srcPromote = path.join(templatesRoot, "scripts", "inferno-promote-draft.mjs");
+  const dstPromote = path.join(cwd, "scripts", "inferno-promote-draft.mjs");
+  copyFile(srcPromote, dstPromote);
+
+  upsertPromoteScript(cwd, silent, logOk);
+
+  const gi = path.join(cwd, ".gitignore");
+  if (fs.existsSync(gi)) {
+    const cur = fs.readFileSync(gi, "utf8");
+    if (cur.includes("CONTEXT.draft.md")) {
+      if (!silent) logOk(".gitignore already mentions CONTEXT.draft.md");
+    } else {
+      fs.appendFileSync(gi, `\n${GITIGNORE_SNIPPET}\n`, "utf8");
+      if (!silent) logOk("Updated: " + path.relative(cwd, gi));
+    }
+  } else {
+    fs.writeFileSync(gi, `${GITIGNORE_SNIPPET}\n`, "utf8");
+    if (!silent) logOk("Created: " + path.relative(cwd, gi));
+  }
+}

package/lib/vsCodeCopilotHooksInstall.mjs

@@ -0,0 +1,42 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { installInfernoDraftTooling } from "./draftToolingInstall.mjs";
+
+/**
+ * VS Code + GitHub Copilot agent hooks (Preview). See:
+ * https://code.visualstudio.com/docs/copilot/customization/hooks
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd
+ * @param {string} opts.templatesRoot
+ * @param {boolean} opts.force
+ * @param {boolean} opts.silent
+ * @param {(msg: string) => void} [opts.logOk]
+ * @param {(msg: string) => void} [opts.logWarn]
+ */
+export function installVsCodeCopilotHooksArtifacts(opts) {
+  const { cwd, templatesRoot, force, silent } = opts;
+  const logOk = opts.logOk || (() => {});
+  const logWarn = opts.logWarn || (() => {});
+
+  function copyFile(src, dst) {
+    if (fs.existsSync(dst) && !force) {
+      if (!silent) logWarn("Skipped (exists): " + path.relative(cwd, dst));
+      return false;
+    }
+    fs.mkdirSync(path.dirname(dst), { recursive: true });
+    fs.copyFileSync(src, dst);
+    if (!silent) logOk("Created: " + path.relative(cwd, dst));
+    return true;
+  }
+
+  installInfernoDraftTooling({ cwd, templatesRoot, force, silent, logOk, logWarn });
+
+  const srcHooks = path.join(templatesRoot, "github-hooks", "infernoflow-drafts.json");
+  const dstHooks = path.join(cwd, ".github", "hooks", "infernoflow-drafts.json");
+  const srcHookScript = path.join(templatesRoot, "scripts", "inferno-vscode-copilot-hook.mjs");
+  const dstHookScript = path.join(cwd, "scripts", "inferno-vscode-copilot-hook.mjs");
+
+  copyFile(srcHooks, dstHooks);
+  copyFile(srcHookScript, dstHookScript);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infernoflow",
-  "version": "0.10.9",
+  "version": "0.10.11",
   "description": "The forge for liquid code — keep capabilities, contracts, and docs in sync.",
   "type": "module",
   "bin": {

package/templates/cursor/hooks/inferno-session-draft.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * Cursor hook: append agent output to inferno/CONTEXT.draft.md (gitignored).
+ * - Default stdin: afterAgentResponse → { text }
+ * - --agent-stop stdin: stop → { status, loop_count, ... }
+ * Never fail closed: errors go to stderr; stdout is {} for Cursor.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** Keep in sync with templates/scripts/inferno-promote-draft.mjs (split at first \\n---\\n). */
+const DRAFT_HEADER = `# CONTEXT draft (gitignored)
+
+Auto-captured by Cursor hooks (\`.cursor/hooks/inferno-session-draft.mjs\`). **Not product truth** — review, then run \`npm run inferno:promote-draft\` or \`infernoflow context\`.
+
+---
+`;
+
+const MAX_MESSAGE_CHARS = 120_000;
+const MAX_FILE_BYTES = 280_000;
+
+function projectRoot() {
+  return process.cwd();
+}
+
+function draftPath() {
+  return path.join(projectRoot(), "inferno", "CONTEXT.draft.md");
+}
+
+function ensureDraftFile(file) {
+  if (!fs.existsSync(file)) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, DRAFT_HEADER, "utf8");
+  }
+}
+
+function trimFile(file) {
+  const raw = fs.readFileSync(file, "utf8");
+  if (Buffer.byteLength(raw, "utf8") <= MAX_FILE_BYTES) return;
+  const keep = raw.slice(-Math.floor(MAX_FILE_BYTES * 0.85));
+  const idx = keep.indexOf("\n### ");
+  const body = idx === -1 ? keep : keep.slice(idx);
+  fs.writeFileSync(file, `${DRAFT_HEADER}\n_(older capture trimmed for size)_\n\n${body}`, "utf8");
+}
+
+function appendBlock(file, block) {
+  ensureDraftFile(file);
+  fs.appendFileSync(file, block, "utf8");
+  trimFile(file);
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function main() {
+  const agentStop = process.argv.includes("--agent-stop");
+
+  readStdin()
+    .then((raw) => {
+      let data = {};
+      try {
+        data = raw.trim() ? JSON.parse(raw) : {};
+      } catch (e) {
+        console.error("[inferno-session-draft] stdin JSON parse:", e.message);
+        console.log("{}");
+        process.exit(0);
+        return;
+      }
+
+      const file = draftPath();
+      if (agentStop) {
+        const status = data.status ?? "unknown";
+        const loop = data.loop_count ?? 0;
+        appendBlock(
+          file,
+          `\n### _agent stop_ (${new Date().toISOString()})\n\nstatus: \`${status}\` · loop_count: ${loop}\n\n---\n`
+        );
+        console.log("{}");
+        process.exit(0);
+        return;
+      }
+
+      const text = typeof data.text === "string" ? data.text : "";
+      if (!text.trim()) {
+        console.log("{}");
+        process.exit(0);
+        return;
+      }
+
+      const clipped =
+        text.length > MAX_MESSAGE_CHARS
+          ? `${text.slice(0, MAX_MESSAGE_CHARS)}\n\n_…trimmed (${text.length - MAX_MESSAGE_CHARS} chars omitted)_\n`
+          : text;
+
+      appendBlock(
+        file,
+        `\n### Assistant message (${new Date().toISOString()})\n\n${clipped}\n\n---\n`
+      );
+      console.log("{}");
+      process.exit(0);
+    })
+    .catch((e) => {
+      console.error("[inferno-session-draft]", e);
+      console.log("{}");
+      process.exit(0);
+    });
+}
+
+main();

package/templates/cursor/hooks.json

@@ -0,0 +1,15 @@
+{
+  "version": 1,
+  "hooks": {
+    "afterAgentResponse": [
+      {
+        "command": "node .cursor/hooks/inferno-session-draft.mjs"
+      }
+    ],
+    "stop": [
+      {
+        "command": "node .cursor/hooks/inferno-session-draft.mjs --agent-stop"
+      }
+    ]
+  }
+}

package/templates/github-hooks/infernoflow-drafts.json

@@ -0,0 +1,17 @@
+{
+  "version": 1,
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "type": "command",
+        "command": "node scripts/inferno-vscode-copilot-hook.mjs"
+      }
+    ],
+    "Stop": [
+      {
+        "type": "command",
+        "command": "node scripts/inferno-vscode-copilot-hook.mjs"
+      }
+    ]
+  }
+}

package/templates/scripts/inferno-promote-draft.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * Merge inferno/CONTEXT.draft.md into inferno/CONTEXT.md under ## Decisions & notes,
+ * or clear the draft. Draft is gitignored; CONTEXT.md is the promoted source of truth.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const root = process.cwd();
+const draftFile = path.join(root, "inferno", "CONTEXT.draft.md");
+const contextFile = path.join(root, "inferno", "CONTEXT.md");
+
+/** Keep in sync with .cursor/hooks/inferno-session-draft.mjs (getDraftBody splits at first \\n---\\n). */
+const DRAFT_HEADER = `# CONTEXT draft (gitignored)
+
+Auto-captured by IDE hooks (Cursor and/or VS Code + Copilot). **Not product truth** — review, then run \`npm run inferno:promote-draft\` or \`infernoflow context\`.
+
+---
+`;
+
+const DECISIONS_ANCHOR = "## Decisions & notes";
+const PASTE_FOOTER_ANCHOR = "\n---\n_Paste this block at the start of any new AI session._";
+
+function read(p) {
+  return fs.readFileSync(p, "utf8");
+}
+
+function write(p, s) {
+  fs.writeFileSync(p, s, "utf8");
+}
+
+function getDraftBody() {
+  if (!fs.existsSync(draftFile)) return "";
+  const full = read(draftFile);
+  const sep = full.indexOf("\n---\n");
+  if (sep === -1) return full.trim();
+  const after = full.slice(sep + "\n---\n".length).trim();
+  return after;
+}
+
+function clearDraft() {
+  fs.mkdirSync(path.dirname(draftFile), { recursive: true });
+  write(draftFile, DRAFT_HEADER);
+  console.log("Cleared inferno/CONTEXT.draft.md (header only).");
+}
+
+function appendNotes() {
+  if (!fs.existsSync(contextFile)) {
+    console.error("Missing inferno/CONTEXT.md");
+    process.exit(1);
+  }
+  const body = getDraftBody();
+  if (!body) {
+    console.error("Nothing to promote: inferno/CONTEXT.draft.md is empty after the header.");
+    process.exit(1);
+  }
+
+  const ctx = read(contextFile);
+  const i = ctx.indexOf(DECISIONS_ANCHOR);
+  if (i === -1) {
+    console.error(`Could not find "${DECISIONS_ANCHOR}" in inferno/CONTEXT.md`);
+    process.exit(1);
+  }
+  const j = ctx.indexOf(PASTE_FOOTER_ANCHOR, i);
+  if (j === -1) {
+    console.error("Could not find paste footer block in inferno/CONTEXT.md");
+    process.exit(1);
+  }
+
+  const before = ctx.slice(0, i + DECISIONS_ANCHOR.length);
+  const decisionsAndFooter = ctx.slice(i + DECISIONS_ANCHOR.length, j);
+  const after = ctx.slice(j);
+
+  let middle = decisionsAndFooter;
+  if (middle.includes("_No decisions recorded_")) {
+    middle = middle.replace("_No decisions recorded_", "").replace(/\n\n\n+/g, "\n\n");
+  }
+
+  const stamp = new Date().toISOString().slice(0, 19);
+  const indented = body.split("\n").map((line) => `    ${line}`).join("\n");
+  const block = `\n\n### Captured from agent draft (${stamp})\n\n${indented}\n`;
+
+  write(contextFile, `${before}${middle}${block}${after}`);
+  clearDraft();
+  console.log("Appended draft under ## Decisions & notes in inferno/CONTEXT.md and cleared the draft.");
+  console.log("Next: edit wording if needed, then run infernoflow check when contract/changelog should match.");
+}
+
+const args = process.argv.slice(2);
+if (args.includes("--clear")) {
+  clearDraft();
+  process.exit(0);
+}
+if (args.includes("--append-notes")) {
+  appendNotes();
+  process.exit(0);
+}
+
+const body = getDraftBody();
+if (!body) {
+  console.log("inferno/CONTEXT.draft.md has no captured content yet (after the header).");
+  console.log("Use the Agent chat; each assistant reply appends via the afterAgentResponse hook.");
+  process.exit(0);
+}
+
+console.log("--- inferno/CONTEXT.draft.md (excerpt, first 2000 chars) ---\n");
+console.log(body.slice(0, 2000) + (body.length > 2000 ? "\n…" : ""));
+console.log("\n---");
+console.log("Promote into CONTEXT.md under Decisions:");
+console.log("  npm run inferno:promote-draft -- --append-notes");
+console.log("Or set working/intent via CLI:");
+console.log('  npm exec -- infernoflow context --working "..." --intent "..."');
+console.log("Clear draft without merging:");
+console.log("  npm run inferno:promote-draft -- --clear");

package/templates/scripts/inferno-vscode-copilot-hook.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+/**
+ * GitHub Copilot / VS Code agent hook (Preview): stdin JSON per
+ * https://code.visualstudio.com/docs/copilot/customization/hooks
+ *
+ * - UserPromptSubmit: appends the user's prompt to inferno/CONTEXT.draft.md
+ * - Stop: reads transcript_path (JSONL or session JSON), appends last assistant text if found
+ *
+ * Always prints {"continue":true} so the agent is never blocked. Errors → stderr only.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** Keep in sync with inferno-promote-draft.mjs / inferno-session-draft.mjs */
+const DRAFT_HEADER = `# CONTEXT draft (gitignored)
+
+Auto-captured by VS Code / Copilot hooks. **Not product truth** — review, then run \`npm run inferno:promote-draft\` or \`infernoflow context\`.
+
+---
+`;
+
+const MAX_APPEND = 120_000;
+const MAX_FILE_BYTES = 280_000;
+
+function draftPath(root) {
+  return path.join(root, "inferno", "CONTEXT.draft.md");
+}
+
+function ensureDraft(file) {
+  if (!fs.existsSync(file)) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, DRAFT_HEADER, "utf8");
+  }
+}
+
+function trimFile(file) {
+  const raw = fs.readFileSync(file, "utf8");
+  if (Buffer.byteLength(raw, "utf8") <= MAX_FILE_BYTES) return;
+  const keep = raw.slice(-Math.floor(MAX_FILE_BYTES * 0.85));
+  const idx = keep.indexOf("\n### ");
+  const body = idx === -1 ? keep : keep.slice(idx);
+  fs.writeFileSync(file, `${DRAFT_HEADER}\n_(older capture trimmed for size)_\n\n${body}`, "utf8");
+}
+
+function append(root, block) {
+  const file = draftPath(root);
+  ensureDraft(file);
+  fs.appendFileSync(file, block, "utf8");
+  trimFile(file);
+}
+
+function readStdinSync() {
+  /** Prefer readSync: on some Windows shells, readFileSync(0) returns empty for piped hook stdin. */
+  const buf = Buffer.alloc(16 * 1024 * 1024);
+  let n = 0;
+  try {
+    n = fs.readSync(0, buf, 0, buf.length, null);
+  } catch {
+    return "";
+  }
+  return buf.slice(0, n).toString("utf8");
+}
+
+function flattenResponse(resp) {
+  if (!resp) return "";
+  if (typeof resp === "string") return resp.slice(0, MAX_APPEND);
+  if (typeof resp.markdown === "string") return resp.markdown;
+  if (typeof resp.text === "string") return resp.text;
+  if (Array.isArray(resp.parts)) {
+    const bits = resp.parts
+      .map((p) => (typeof p === "string" ? p : p?.text || p?.content || p?.value || ""))
+      .filter(Boolean);
+    if (bits.length) return bits.join("\n").slice(0, MAX_APPEND);
+  }
+  if (resp.message && typeof resp.message.text === "string") return resp.message.text;
+  return "";
+}
+
+function lastAssistantFromSessionJson(data) {
+  const reqs = data.requests;
+  if (!Array.isArray(reqs)) return "";
+  for (let i = reqs.length - 1; i >= 0; i--) {
+    const t = flattenResponse(reqs[i]?.response);
+    if (t && t.trim()) return t.slice(0, MAX_APPEND);
+  }
+  return "";
+}
+
+function extractFromJsonlLine(obj) {
+  if (!obj || typeof obj !== "object") return "";
+  const a = obj.assistant;
+  if (a && typeof a.message === "string" && a.message.trim()) return a.message.slice(0, MAX_APPEND);
+  if (a && typeof a.text === "string" && a.text.trim()) return a.text.slice(0, MAX_APPEND);
+  if ((obj.role === "assistant" || obj.type === "assistant") && typeof obj.message === "string")
+    return obj.message.slice(0, MAX_APPEND);
+  if ((obj.role === "assistant" || obj.type === "assistant") && typeof obj.content === "string")
+    return obj.content.slice(0, MAX_APPEND);
+  if (obj.assistantMessage && typeof obj.assistantMessage === "string")
+    return obj.assistantMessage.slice(0, MAX_APPEND);
+  return "";
+}
+
+function lastAssistantFromTranscriptFile(transcriptPath) {
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) return "";
+  const raw = fs.readFileSync(transcriptPath, "utf8").trim();
+  if (!raw) return "";
+
+  if (raw.startsWith("{")) {
+    try {
+      const data = JSON.parse(raw);
+      const fromReq = lastAssistantFromSessionJson(data);
+      if (fromReq) return fromReq;
+    } catch {
+      /* fall through */
+    }
+  }
+
+  let last = "";
+  for (const line of raw.split("\n")) {
+    const t = line.trim();
+    if (!t || t[0] !== "{") continue;
+    try {
+      const v = extractFromJsonlLine(JSON.parse(t));
+      if (v) last = v;
+    } catch {
+      /* skip line */
+    }
+  }
+  return last;
+}
+
+function main() {
+  let data = {};
+  try {
+    const s = readStdinSync().trim();
+    if (s) data = JSON.parse(s);
+  } catch (e) {
+    console.error("[inferno-vscode-copilot-hook] stdin JSON:", e.message);
+    console.log(JSON.stringify({ continue: true }));
+    process.exit(0);
+    return;
+  }
+
+  const root = data.cwd || process.cwd();
+  const hook = String(data.hookEventName || data.hook_event_name || "")
+    .replace(/\s+/g, "")
+    .toLowerCase();
+
+  try {
+    if (hook === "userpromptsubmit") {
+      const prompt = data.prompt || data.Prompt || "";
+      if (typeof prompt === "string" && prompt.trim()) {
+        append(
+          root,
+          `\n### User prompt (${new Date().toISOString()})\n\n${prompt.slice(0, MAX_APPEND)}\n\n---\n`
+        );
+      }
+    } else if (hook === "stop") {
+      const tp = data.transcript_path || data.transcriptPath;
+      const assistant = lastAssistantFromTranscriptFile(tp);
+      const stopActive = data.stop_hook_active ?? data.stopHookActive;
+      if (assistant) {
+        append(
+          root,
+          `\n### Assistant (from transcript) (${new Date().toISOString()})\n\n${assistant}\n\n---\n`
+        );
+      } else {
+        append(
+          root,
+          `\n### _Copilot Stop_ (${new Date().toISOString()})\n\nstop_hook_active: ${Boolean(stopActive)}${
+            tp ? ` · transcript: ${tp}` : " · (no transcript_path or empty parse)"
+          }\n\n---\n`
+        );
+      }
+    }
+  } catch (e) {
+    console.error("[inferno-vscode-copilot-hook]", e);
+  }
+
+  console.log(JSON.stringify({ continue: true }));
+  process.exit(0);
+}
+
+main();