infernoflow 0.22.1 → 0.24.0

package/dist/bin/infernoflow.mjs

@@ -54,6 +54,10 @@ const COMMAND_DESCRIPTIONS = {
   doctor:  "Diagnose your infernoflow setup — checks Node, git, contract, AI providers, MCP, hooks",
   coverage: "Map test files to capabilities — show which caps have test coverage and which don't",
   review:  "AI-powered capability impact review for staged or recent git changes",
+  scan:       "Deep AST scan — reads actual function bodies, extracts calls, DB ops, external services",
+  stability:  "Show solid/liquid stability level for every capability (frozen/stable/experimental)",
+  freeze:     "Mark a capability as frozen (solid) — AI will not modify it without explicit instruction",
+  thaw:       "Reset a capability to experimental (liquid) — free to evolve",
 };
 
 const COMMAND_HANDLERS = {
@@ -101,6 +105,10 @@ const COMMAND_HANDLERS = {
   doctor:   async (args) => (await import("../lib/commands/doctor.mjs")).doctorCommand(args),
   coverage: async (args) => (await import("../lib/commands/coverage.mjs")).coverageCommand(args),
   review:   async (args) => (await import("../lib/commands/review.mjs")).reviewCommand(args),
+  scan:      async (args) => (await import("../lib/commands/scan.mjs")).scanCommand(args),
+  stability: async (args) => (await import("../lib/commands/stability.mjs")).stabilityCommand(args),
+  freeze:    async (args) => (await import("../lib/commands/stability.mjs")).freezeCommand(args),
+  thaw:      async (args) => (await import("../lib/commands/stability.mjs")).thawCommand(args),
 };
 
 function formatCommandsHelp() {
@@ -355,6 +363,19 @@ ${formatCommandsHelp()}
     --fail-below <pct>        Exit 1 if coverage percentage is below this value (CI gate)
     --json                    Machine-readable coverage breakdown
 
+  ${bold("scan options:")}
+    --dir <path>              Extra directory to scan (repeatable)
+    --capability <id>         Scan and enrich a single capability only
+    --dry-run                 Print results without writing files
+    --json                    Machine-readable scan output
+
+  ${bold("stability / freeze / thaw options:")}
+    infernoflow stability     List all capabilities with their stability level
+    infernoflow freeze <id>   Mark capability as frozen (AI won't touch it)
+    infernoflow freeze <id> --stable   Mark as stable (careful, not forbidden)
+    infernoflow thaw <id>     Reset to experimental (liquid — free to change)
+    --json                    Machine-readable stability list
+
   ${bold("review options:")}
     --unstaged                Review all working-tree changes (not just staged)
     --last                    Review last commit (git diff HEAD~1)

package/dist/lib/commands/claudeMd.mjs

@@ -13,6 +13,7 @@ import * as fs   from "node:fs";
 import * as path from "node:path";
 import { readProfile } from "../learning/profile.mjs";
 import { ok, warn, info, bold, done } from "../ui/output.mjs";
+import { buildStabilitySummary } from "./stability.mjs";
 
 // ── CLAUDE.md template ────────────────────────────────────────────────────────
 //
@@ -21,7 +22,7 @@ import { ok, warn, info, bold, done } from "../ui/output.mjs";
 // session. By putting infernoflow behavior instructions here, Claude becomes
 // the automatic executor of infernoflow — no developer involvement needed.
 //
-function buildClaudeMd(profile, contract) {
+function buildClaudeMd(profile, contract, caps) {
   const framework = profile?.stack?.framework !== "unknown" ? profile.stack.framework : null;
   const language  = profile?.stack?.language  !== "unknown" ? profile.stack.language  : null;
   const stackLine = framework
@@ -33,6 +34,8 @@ function buildClaudeMd(profile, contract) {
     ? `The contract currently tracks **${capCount} capabilities**.`
     : "";
 
+  const stabilitySummary = caps ? buildStabilitySummary(caps) : null;
+
   return `# infernoflow — Automatic AI Behavior
 
 > This file is managed by infernoflow. Edit the sections marked "customizable".
@@ -114,6 +117,8 @@ multi-step task repeatedly:
 
 ---
 
+${stabilitySummary ? stabilitySummary + "\n\n---" : ""}
+
 ## Rules
 
 | Rule | Why |
@@ -123,6 +128,7 @@ multi-step task repeatedly:
 | Never block the developer waiting for infernoflow | Run tools async when possible |
 | Always call \`infernoflow_context\` at session start | It keeps your context current |
 | Treat contract drift like a linting error — fix it silently | Not the developer's problem |
+| Never modify frozen capabilities without explicit instruction | Stability contract must be respected |
 
 ---
 
@@ -156,13 +162,18 @@ multi-step task repeatedly:
 export function writeClaudeMd(cwd, infernoDir, { force = false } = {}) {
   const claudeMdPath = path.join(cwd, "CLAUDE.md");
 
-  // Load project profile + contract for context
+  // Load project profile + contract + capabilities for context
   let profile = null;
   let contract = null;
+  let caps = null;
   try { profile  = readProfile(infernoDir); } catch {}
   try { contract = JSON.parse(fs.readFileSync(path.join(infernoDir, "contract.json"), "utf8")); } catch {}
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(infernoDir, "capabilities.json"), "utf8"));
+    caps = Array.isArray(raw) ? raw : (raw.capabilities || []);
+  } catch {}
 
-  const newContent = buildClaudeMd(profile, contract);
+  const newContent = buildClaudeMd(profile, contract, caps);
 
   // If file exists and not forcing, preserve the customizable section
   if (fs.existsSync(claudeMdPath) && !force) {

package/dist/lib/commands/scan.mjs

@@ -0,0 +1,566 @@
+/**
+ * infernoflow scan
+ *
+ * Deep AST-based code analysis. Reads actual function bodies — not just names.
+ * Extracts: external calls, DB operations, HTTP calls, auth patterns, error types,
+ * external service usage (Stripe, S3, SendGrid, etc.).
+ *
+ * Enriches capabilities.json with a `codeAnalysis` block on each capability,
+ * and saves the full scan report to inferno/scan.json.
+ *
+ * Usage:
+ *   infernoflow scan                   Scan project, enrich capabilities
+ *   infernoflow scan --dir src/        Scan specific directory
+ *   infernoflow scan --json            Print scan.json to stdout
+ *   infernoflow scan --dry-run         Print without writing files
+ *   infernoflow scan --capability auth-login   Scan one capability only
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import { createRequire } from "node:module";
+import { execSync }      from "node:child_process";
+import { bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+const require = createRequire(import.meta.url);
+
+// ── TypeScript compiler API (global install) ──────────────────────────────────
+
+const TS_PATHS = [
+  "/usr/local/lib/node_modules_global/lib/node_modules/typescript",
+  "/usr/lib/node_modules/typescript",
+  path.join(process.env.HOME || "", ".npm-global/lib/node_modules/typescript"),
+];
+
+function loadTypeScript() {
+  for (const p of TS_PATHS) {
+    try { return require(path.join(p, "lib/typescript.js")); } catch {}
+  }
+  try { return require("typescript"); } catch {}
+  return null;
+}
+
+const ts = loadTypeScript();
+
+// ── external service fingerprints ────────────────────────────────────────────
+
+const SERVICE_PATTERNS = [
+  { service: "stripe",    patterns: ["stripe", "Stripe", "createPaymentIntent", "charges.create"] },
+  { service: "sendgrid",  patterns: ["sendgrid", "@sendgrid", "sgMail", "sendgrid.send"] },
+  { service: "ses",       patterns: ["SES", "ses.sendEmail", "aws-sdk/ses", "nodemailer"] },
+  { service: "s3",        patterns: ["S3", "s3.upload", "s3.getObject", "PutObjectCommand", "@aws-sdk/s3"] },
+  { service: "redis",     patterns: ["redis", "Redis", "ioredis", "createClient"] },
+  { service: "jwt",       patterns: ["jwt", "jsonwebtoken", "sign(", "verify(", "decode("] },
+  { service: "bcrypt",    patterns: ["bcrypt", "argon2", "scrypt", "hashSync", "compare("] },
+  { service: "prisma",    patterns: ["prisma.", "PrismaClient", "@prisma/client"] },
+  { service: "mongoose",  patterns: ["mongoose", ".save()", ".findOne(", ".aggregate("] },
+  { service: "postgres",  patterns: ["pg", "Pool(", "Client(", "query(", "postgres("] },
+  { service: "mysql",     patterns: ["mysql", "mysql2", "createConnection"] },
+  { service: "graphql",   patterns: ["graphql", "gql`", "ApolloServer", "GraphQLSchema"] },
+  { service: "firebase",  patterns: ["firebase", "firestore", "initializeApp"] },
+  { service: "twilio",    patterns: ["twilio", "Twilio(", "messages.create"] },
+  { service: "openai",    patterns: ["openai", "OpenAI(", "createCompletion", "chat.completions"] },
+];
+
+function detectServices(text) {
+  const found = new Set();
+  for (const { service, patterns } of SERVICE_PATTERNS) {
+    if (patterns.some(p => text.includes(p))) found.add(service);
+  }
+  return [...found];
+}
+
+// ── DB call patterns ──────────────────────────────────────────────────────────
+
+const DB_PATTERNS = [
+  /\.(find|findOne|findMany|findById|findAll)\s*\(/g,
+  /\.(create|insert|insertOne|insertMany|save)\s*\(/g,
+  /\.(update|updateOne|updateMany|updateById|upsert)\s*\(/g,
+  /\.(delete|deleteOne|deleteMany|remove|destroy)\s*\(/g,
+  /\.(query|execute|raw)\s*\(/g,
+  /\.(aggregate|groupBy|count|sum)\s*\(/g,
+  /db\.\w+\s*\(/g,
+  /prisma\.\w+\.\w+\s*\(/g,
+];
+
+function detectDbCalls(text) {
+  const calls = new Set();
+  for (const re of DB_PATTERNS) {
+    const r = new RegExp(re.source, "g");
+    let m;
+    while ((m = r.exec(text)) !== null) calls.add(m[0].replace(/\s*\($/, "()"));
+  }
+  return [...calls].slice(0, 10);
+}
+
+// ── HTTP call patterns ────────────────────────────────────────────────────────
+
+const HTTP_PATTERNS = [
+  /fetch\s*\(/g,
+  /axios\.(get|post|put|patch|delete)\s*\(/g,
+  /http\.(get|post|request)\s*\(/g,
+  /got\.(get|post|put|delete)\s*\(/g,
+  /request\.(get|post|put|delete)\s*\(/g,
+  /\$http\.(get|post|put|delete)\s*\(/g,
+];
+
+function detectHttpCalls(text) {
+  const calls = new Set();
+  for (const re of HTTP_PATTERNS) {
+    const r = new RegExp(re.source, "g");
+    let m;
+    while ((m = r.exec(text)) !== null) calls.add(m[0].replace(/\s*\($/, "()"));
+  }
+  return [...calls].slice(0, 8);
+}
+
+// ── TypeScript / JavaScript AST analysis ─────────────────────────────────────
+
+function getNodeName(node) {
+  if (!ts) return null;
+  if (node.name && ts.isIdentifier(node.name)) return node.name.text;
+  return null;
+}
+
+function collectCallsInNode(node, calls = new Set()) {
+  if (!ts) return calls;
+  if (ts.isCallExpression(node)) {
+    const expr = node.expression;
+    if (ts.isIdentifier(expr)) {
+      calls.add(expr.text + "()");
+    } else if (ts.isPropertyAccessExpression(expr)) {
+      calls.add(expr.name.text + "()");
+    }
+  }
+  ts.forEachChild(node, child => collectCallsInNode(child, calls));
+  return calls;
+}
+
+function collectThrowsInNode(node, throws = new Set()) {
+  if (!ts) return throws;
+  if (ts.isThrowStatement(node) && node.expression) {
+    if (ts.isNewExpression(node.expression) && ts.isIdentifier(node.expression.expression)) {
+      throws.add(node.expression.expression.text);
+    }
+  }
+  ts.forEachChild(node, child => collectThrowsInNode(child, throws));
+  return throws;
+}
+
+function isFunctionNode(node) {
+  if (!ts) return false;
+  return (
+    ts.isFunctionDeclaration(node) ||
+    ts.isFunctionExpression(node) ||
+    ts.isArrowFunction(node) ||
+    ts.isMethodDeclaration(node)
+  );
+}
+
+function getParentVariableName(node) {
+  // For arrow functions assigned to const: const foo = () => {}
+  if (!ts) return null;
+  if (node.parent && ts.isVariableDeclaration(node.parent)) {
+    return getNodeName(node.parent);
+  }
+  if (node.parent && ts.isPropertyAssignment(node.parent)) {
+    return getNodeName(node.parent);
+  }
+  return null;
+}
+
+function analyzeJsTs(filePath, code) {
+  if (!ts) return null;
+
+  let srcFile;
+  try {
+    srcFile = ts.createSourceFile(filePath, code, ts.ScriptTarget.Latest, /*setParentNodes*/ true);
+  } catch {
+    return null;
+  }
+
+  const functions = [];
+
+  function visit(node) {
+    if (isFunctionNode(node)) {
+      const name = getNodeName(node) || getParentVariableName(node) || "<anonymous>";
+      const calls  = [...collectCallsInNode(node)].slice(0, 20);
+      const throws = [...collectThrowsInNode(node)];
+      const text   = code.slice(node.pos, node.end);
+      functions.push({
+        name,
+        calls,
+        throws,
+        services: detectServices(text),
+        dbCalls:  detectDbCalls(text),
+        httpCalls: detectHttpCalls(text),
+        loc: srcFile.getLineAndCharacterOfPosition(node.pos).line + 1,
+      });
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(srcFile);
+  return functions;
+}
+
+// ── Python AST analysis via child_process ─────────────────────────────────────
+
+const PYTHON_SCRIPT = `
+import ast, json, sys
+
+def get_calls(node):
+    calls = []
+    for n in ast.walk(node):
+        if isinstance(n, ast.Call):
+            if isinstance(n.func, ast.Name):
+                calls.append(n.func.id + "()")
+            elif isinstance(n.func, ast.Attribute):
+                calls.append(n.func.attr + "()")
+    return list(set(calls))[:20]
+
+def get_raises(node):
+    raises = []
+    for n in ast.walk(node):
+        if isinstance(n, ast.Raise) and n.exc:
+            if isinstance(n.exc, ast.Call) and isinstance(n.exc.func, ast.Name):
+                raises.append(n.exc.func.id)
+            elif isinstance(n.exc, ast.Name):
+                raises.append(n.exc.id)
+    return list(set(raises))
+
+try:
+    code = open(sys.argv[1], encoding="utf-8", errors="ignore").read()
+    tree = ast.parse(code)
+    functions = []
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            functions.append({
+                "name": node.name,
+                "calls": get_calls(node),
+                "throws": get_raises(node),
+                "loc": node.lineno,
+            })
+    print(json.dumps(functions))
+except Exception as e:
+    print(json.dumps([]))
+`;
+
+function analyzePython(filePath) {
+  try {
+    const result = execSync(
+      `python3 -c ${JSON.stringify(PYTHON_SCRIPT)} ${JSON.stringify(filePath)}`,
+      { timeout: 8000, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }
+    );
+    const fns = JSON.parse(result.trim() || "[]");
+    // add service/db/http detection from raw file text
+    const code = fs.readFileSync(filePath, "utf8");
+    return fns.map(f => ({
+      ...f,
+      services:  detectServices(code),
+      dbCalls:   detectDbCalls(code),
+      httpCalls: detectHttpCalls(code),
+    }));
+  } catch {
+    return null;
+  }
+}
+
+// ── regex fallback (Go, Ruby, Java, other) ────────────────────────────────────
+
+const FUNC_PATTERNS = [
+  { re: /^func\s+(?:\(\w+\s+\*?\w+\)\s+)?(\w+)\s*\(/gm,  lang: "go"   },
+  { re: /^\s*(?:def|async def)\s+(\w+)\s*\(/gm,          lang: "py"   },
+  { re: /^\s*(?:public|private|protected)?\s*(?:static\s+)?(?:\w+\s+)?(\w+)\s*\(/gm, lang: "java" },
+  { re: /^\s*def\s+(\w+)\s*[\(\|]/gm,                    lang: "rb"   },
+];
+
+function analyzeWithRegex(filePath, code) {
+  const ext = path.extname(filePath).slice(1);
+  const pattern = FUNC_PATTERNS.find(p => p.lang === ext);
+  if (!pattern) return null;
+
+  const functions = [];
+  const r = new RegExp(pattern.re.source, "gm");
+  let m;
+  while ((m = r.exec(code)) !== null) {
+    // grab up to 60 lines after the match for context
+    const start  = m.index;
+    const end    = Math.min(start + 2000, code.length);
+    const chunk  = code.slice(start, end);
+    functions.push({
+      name:      m[1],
+      calls:     [],
+      throws:    [],
+      services:  detectServices(chunk),
+      dbCalls:   detectDbCalls(chunk),
+      httpCalls: detectHttpCalls(chunk),
+      loc:       code.slice(0, start).split("\n").length,
+    });
+  }
+  return functions.length > 0 ? functions : null;
+}
+
+// ── file walker ───────────────────────────────────────────────────────────────
+
+const SKIP_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", "out", ".next", ".nuxt",
+  "coverage", "__pycache__", ".pytest_cache", "vendor", "tmp", ".turbo",
+  "target", ".gradle", "public", "static", "assets",
+]);
+
+const SUPPORTED_EXTS = new Set([
+  ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+  ".py", ".go", ".rb", ".java",
+]);
+
+const TEST_FILE = /\.(test|spec)\.[jt]sx?$|_test\.(go|py|rb)|spec\.(rb|js|ts)$/;
+
+function* walkFiles(dir) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return; }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (!SKIP_DIRS.has(e.name)) yield* walkFiles(path.join(dir, e.name));
+    } else if (e.isFile()) {
+      const ext = path.extname(e.name);
+      if (SUPPORTED_EXTS.has(ext) && !TEST_FILE.test(e.name)) {
+        yield path.join(dir, e.name);
+      }
+    }
+  }
+}
+
+// ── per-file analyzer ─────────────────────────────────────────────────────────
+
+function analyzeFile(filePath) {
+  let code;
+  try { code = fs.readFileSync(filePath, "utf8"); }
+  catch { return []; }
+
+  const ext = path.extname(filePath);
+
+  if ([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"].includes(ext)) {
+    return analyzeJsTs(filePath, code) || analyzeWithRegex(filePath, code) || [];
+  }
+  if (ext === ".py") {
+    return analyzePython(filePath) || analyzeWithRegex(filePath, code) || [];
+  }
+  return analyzeWithRegex(filePath, code) || [];
+}
+
+// ── capability matcher ────────────────────────────────────────────────────────
+
+function tokenise(str) {
+  return str.replace(/([a-z])([A-Z])/g, "$1 $2")
+    .toLowerCase().split(/[\s_\-/.]+/).filter(t => t.length > 1);
+}
+
+function overlap(a, b) {
+  const sa = new Set(a), sb = new Set(b);
+  let n = 0;
+  for (const t of sa) if (sb.has(t)) n++;
+  const u = sa.size + sb.size - n;
+  return u === 0 ? 0 : n / u;
+}
+
+function matchFunctionToCapability(fn, capabilities) {
+  const fnTokens = tokenise(fn.name);
+  let best = null, bestScore = 0;
+  for (const cap of capabilities) {
+    const score = Math.max(
+      overlap(fnTokens, tokenise(cap.id || "")),
+      overlap(fnTokens, tokenise(cap.name || cap.title || "")),
+    );
+    if (score > bestScore) { bestScore = score; best = cap; }
+  }
+  return bestScore >= 0.2 ? { cap: best, score: bestScore } : null;
+}
+
+// ── merge analysis into capability ────────────────────────────────────────────
+
+function mergeAnalysis(existing = {}, fn, filePath, cwd) {
+  const rel = path.relative(cwd, filePath);
+
+  // merge arrays without duplicates
+  const merge = (a = [], b = []) => [...new Set([...a, ...b])];
+
+  return {
+    functions:    merge(existing.functions,    [fn.name]),
+    sourceFiles:  merge(existing.sourceFiles,  [rel]),
+    calls:        merge(existing.calls,        fn.calls),
+    throws:       merge(existing.throws,       fn.throws),
+    services:     merge(existing.services,     fn.services),
+    dbCalls:      merge(existing.dbCalls,      fn.dbCalls),
+    httpCalls:    merge(existing.httpCalls,    fn.httpCalls),
+    scannedAt:    new Date().toISOString(),
+  };
+}
+
+// ── reporters ─────────────────────────────────────────────────────────────────
+
+function printReport(enriched) {
+  console.log();
+  console.log(bold("  Scan Results"));
+  console.log(gray("  ─────────────────────────────────────────────────────────────────"));
+
+  for (const [capId, analysis] of Object.entries(enriched)) {
+    const { codeAnalysis: a } = analysis;
+    if (!a) continue;
+
+    console.log();
+    console.log(`  ${green("●")} ${bold(capId)}`);
+    if (a.sourceFiles?.length)  console.log(gray(`    files:    `) + a.sourceFiles.join(", "));
+    if (a.functions?.length)    console.log(gray(`    funcs:    `) + a.functions.join(", "));
+    if (a.services?.length)     console.log(gray(`    services: `) + cyan(a.services.join(", ")));
+    if (a.dbCalls?.length)      console.log(gray(`    db:       `) + a.dbCalls.slice(0, 4).join(", "));
+    if (a.httpCalls?.length)    console.log(gray(`    http:     `) + a.httpCalls.slice(0, 4).join(", "));
+    if (a.throws?.length)       console.log(gray(`    throws:   `) + yellow(a.throws.join(", ")));
+  }
+
+  console.log();
+  console.log(gray("  ─────────────────────────────────────────────────────────────────"));
+}
+
+// ── entry point ───────────────────────────────────────────────────────────────
+
+export async function scanCommand(rawArgs) {
+  const args       = rawArgs || [];
+  const dryRun     = args.includes("--dry-run");
+  const jsonMode   = args.includes("--json");
+  const dirIdx     = args.indexOf("--dir");
+  const extraDirs  = dirIdx !== -1 ? [args[dirIdx + 1]] : [];
+  const capFilter  = (() => { const i = args.indexOf("--capability"); return i !== -1 ? args[i + 1] : null; })();
+
+  const cwd        = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  // Load capabilities
+  const capsPath = path.join(infernoDir, "capabilities.json");
+  if (!fs.existsSync(capsPath)) {
+    console.error(red("✗ inferno/capabilities.json not found — run `infernoflow init` first."));
+    process.exit(1);
+  }
+  let capabilities;
+  try { capabilities = JSON.parse(fs.readFileSync(capsPath, "utf8")); }
+  catch (e) { console.error(red("✗ Failed to parse capabilities.json: " + e.message)); process.exit(1); }
+
+  if (!Array.isArray(capabilities)) {
+    // handle object format { capabilities: [...] }
+    if (capabilities.capabilities) capabilities = capabilities.capabilities;
+    else { console.error(red("✗ Unexpected capabilities.json format.")); process.exit(1); }
+  }
+
+  // Filter by --capability flag
+  const targetCaps = capFilter
+    ? capabilities.filter(c => c.id === capFilter || (c.name || "").toLowerCase() === capFilter.toLowerCase())
+    : capabilities;
+
+  if (targetCaps.length === 0) {
+    console.log(yellow(capFilter ? `No capability matched: ${capFilter}` : "No capabilities found."));
+    process.exit(0);
+  }
+
+  // Walk source files
+  const scanDirs = [cwd, ...extraDirs];
+  if (!jsonMode) process.stdout.write(gray("  Walking source files…"));
+  const files = [];
+  for (const dir of scanDirs) {
+    for (const f of walkFiles(dir)) files.push(f);
+  }
+  if (!jsonMode) process.stdout.write(`\r  Found ${files.length} source files.          \n`);
+
+  // Analyze files
+  if (!jsonMode) process.stdout.write(gray("  Analyzing…"));
+  const allFunctions = []; // { fn, filePath }
+  let analyzed = 0;
+  for (const filePath of files) {
+    const fns = analyzeFile(filePath);
+    for (const fn of fns) allFunctions.push({ fn, filePath });
+    analyzed++;
+    if (!jsonMode && analyzed % 20 === 0) {
+      process.stdout.write(`\r  Analyzed ${analyzed}/${files.length} files…`);
+    }
+  }
+  if (!jsonMode) process.stdout.write(`\r  Analyzed ${files.length} files, found ${allFunctions.length} functions.          \n`);
+
+  // Map functions to capabilities
+  const enriched = {}; // capId → { ...cap, codeAnalysis: {...} }
+
+  for (const cap of targetCaps) {
+    enriched[cap.id] = { ...cap, codeAnalysis: null };
+  }
+
+  for (const { fn, filePath } of allFunctions) {
+    const match = matchFunctionToCapability(fn, targetCaps);
+    if (!match) continue;
+    const { cap } = match;
+    const existing = enriched[cap.id]?.codeAnalysis || {};
+    enriched[cap.id].codeAnalysis = mergeAnalysis(existing, fn, filePath, cwd);
+  }
+
+  // Compute stats
+  const total   = Object.keys(enriched).length;
+  const matched = Object.values(enriched).filter(e => e.codeAnalysis).length;
+
+  if (jsonMode) {
+    const out = {
+      scannedAt: new Date().toISOString(),
+      files:     files.length,
+      functions: allFunctions.length,
+      capabilities: Object.entries(enriched).map(([id, data]) => ({
+        id,
+        name:         data.name || data.title,
+        codeAnalysis: data.codeAnalysis,
+      })),
+    };
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
+
+  printReport(enriched);
+  console.log(`  ${green("✔")} Matched ${matched}/${total} capabilities to source functions`);
+  console.log();
+
+  if (dryRun) {
+    console.log(yellow("  --dry-run: no files written."));
+    return;
+  }
+
+  // Write scan.json
+  const scanData = {
+    scannedAt:    new Date().toISOString(),
+    files:        files.length,
+    functions:    allFunctions.length,
+    capabilities: Object.entries(enriched).map(([id, data]) => ({
+      id,
+      name:         data.name || data.title,
+      codeAnalysis: data.codeAnalysis,
+    })),
+  };
+  const scanPath = path.join(infernoDir, "scan.json");
+  fs.writeFileSync(scanPath, JSON.stringify(scanData, null, 2));
+  console.log(gray(`  Saved → inferno/scan.json`));
+
+  // Enrich capabilities.json
+  let changed = 0;
+  const updatedCaps = capabilities.map(cap => {
+    const analysis = enriched[cap.id]?.codeAnalysis;
+    if (!analysis) return cap;
+    changed++;
+    return { ...cap, codeAnalysis: analysis };
+  });
+
+  if (changed > 0) {
+    fs.writeFileSync(capsPath, JSON.stringify(updatedCaps, null, 2));
+    console.log(gray(`  Updated ${changed} capability entries in capabilities.json`));
+  }
+
+  console.log();
+  if (!ts) {
+    console.log(yellow("  ⚠  TypeScript compiler not found — JS/TS analyzed with regex fallback."));
+    console.log(gray(`     For deeper analysis: npm install -g typescript`));
+    console.log();
+  }
+}

package/dist/lib/commands/stability.mjs

@@ -0,0 +1,293 @@
+/**
+ * infernoflow freeze / thaw / stability
+ *
+ * The solid/liquid layer — mark capabilities as frozen (don't touch),
+ * stable (be careful), or experimental (feel free to reshape).
+ *
+ * Usage:
+ *   infernoflow stability                     List all caps with stability level
+ *   infernoflow freeze <cap-id>               Mark a capability as frozen
+ *   infernoflow freeze <cap-id> --stable      Mark as stable (default middle tier)
+ *   infernoflow thaw  <cap-id>                Reset to experimental
+ *   infernoflow stability --json              Machine-readable output
+ *
+ * Levels:
+ *   experimental  New or actively changing — AI may freely refactor
+ *   stable        Settled API — AI should be careful, prefer additive changes
+ *   frozen        Core contract — AI must never modify without explicit instruction
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import { bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+// ── constants ─────────────────────────────────────────────────────────────────
+
+export const LEVELS = ["experimental", "stable", "frozen"];
+
+const LEVEL_ICON = {
+  experimental: "🌊",   // liquid — flows freely
+  stable:       "〰️",   // semi-fluid — treat with care
+  frozen:       "🧊",   // solid — do not touch
+};
+
+const LEVEL_COLOR = {
+  experimental: green,
+  stable:       yellow,
+  frozen:       red,
+};
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function loadCaps(capsPath) {
+  try {
+    const data = JSON.parse(fs.readFileSync(capsPath, "utf8"));
+    return Array.isArray(data) ? data : (data.capabilities || []);
+  } catch (e) {
+    console.error(red("✗ Failed to read capabilities.json: " + e.message));
+    process.exit(1);
+  }
+}
+
+function saveCaps(capsPath, caps) {
+  fs.writeFileSync(capsPath, JSON.stringify(caps, null, 2));
+}
+
+function getLevel(cap) {
+  return cap.stability || "experimental";
+}
+
+function bar(level) {
+  const idx   = LEVELS.indexOf(level);
+  const color = LEVEL_COLOR[level] || gray;
+  const filled = "█".repeat(idx + 1);
+  const empty  = "░".repeat(LEVELS.length - idx - 1);
+  return color(filled) + gray(empty);
+}
+
+// ── sub-commands ──────────────────────────────────────────────────────────────
+
+function cmdList(caps, jsonMode) {
+  if (jsonMode) {
+    const out = caps.map(c => ({ id: c.id, name: c.name || c.title, stability: getLevel(c) }));
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
+
+  const byLevel = { frozen: [], stable: [], experimental: [] };
+  for (const cap of caps) byLevel[getLevel(cap)].push(cap);
+
+  console.log();
+  console.log(bold("  Capability Stability"));
+  console.log(gray("  ───────────────────────────────────────────────────────────"));
+  console.log(
+    gray("  ") + bold(cyan("Capability".padEnd(32))) +
+    bold(cyan("Level".padEnd(16))) + bold(cyan("Solid/Liquid"))
+  );
+  console.log(gray("  ───────────────────────────────────────────────────────────"));
+
+  for (const cap of caps) {
+    const level = getLevel(cap);
+    const icon  = LEVEL_ICON[level];
+    const color = LEVEL_COLOR[level] || gray;
+    console.log(
+      `  ${icon}  ${cap.id.padEnd(30)} ${color(level.padEnd(14))} ${bar(level)}`
+    );
+  }
+
+  console.log(gray("  ───────────────────────────────────────────────────────────"));
+  console.log();
+
+  const counts = {
+    frozen:       byLevel.frozen.length,
+    stable:       byLevel.stable.length,
+    experimental: byLevel.experimental.length,
+  };
+  console.log(
+    `  ${red("🧊 Frozen:")} ${counts.frozen}   ` +
+    `${yellow("〰️  Stable:")} ${counts.stable}   ` +
+    `${green("🌊 Experimental:")} ${counts.experimental}`
+  );
+  console.log();
+  console.log(gray("  Tip: infernoflow freeze <cap-id>   —   infernoflow thaw <cap-id>"));
+  console.log();
+}
+
+function cmdFreeze(caps, capsPath, capId, level) {
+  if (!LEVELS.includes(level)) {
+    console.error(red(`✗ Invalid level "${level}". Must be: ${LEVELS.join(", ")}`));
+    process.exit(1);
+  }
+
+  const idx = caps.findIndex(c => c.id === capId);
+  if (idx === -1) {
+    console.error(red(`✗ Capability "${capId}" not found in capabilities.json`));
+    process.exit(1);
+  }
+
+  const prev  = getLevel(caps[idx]);
+  caps[idx]   = { ...caps[idx], stability: level, stabilitySetAt: new Date().toISOString() };
+  saveCaps(capsPath, caps);
+
+  const icon  = LEVEL_ICON[level];
+  const color = LEVEL_COLOR[level];
+  console.log();
+  console.log(`  ${icon}  ${bold(capId)}  ${gray(prev)} → ${color(level)}`);
+  if (level === "frozen") {
+    console.log(gray("  AI assistants will be instructed not to modify this capability."));
+    console.log(gray("  Run `infernoflow setup` to update CLAUDE.md with this change."));
+  }
+  console.log();
+}
+
+function cmdThaw(caps, capsPath, capId) {
+  const idx = caps.findIndex(c => c.id === capId);
+  if (idx === -1) {
+    console.error(red(`✗ Capability "${capId}" not found in capabilities.json`));
+    process.exit(1);
+  }
+
+  const prev  = getLevel(caps[idx]);
+  caps[idx]   = { ...caps[idx], stability: "experimental", stabilitySetAt: new Date().toISOString() };
+  saveCaps(capsPath, caps);
+
+  console.log();
+  console.log(`  🌊  ${bold(capId)}  ${gray(prev)} → ${green("experimental")}`);
+  console.log(gray("  This capability is now liquid — free to evolve."));
+  console.log();
+}
+
+// ── scan drift check (frozen caps whose files changed) ────────────────────────
+
+export function checkFrozenDrift(infernoDir, cwd) {
+  const capsPath  = path.join(infernoDir, "capabilities.json");
+  const scanPath  = path.join(infernoDir, "scan.json");
+  if (!fs.existsSync(capsPath) || !fs.existsSync(scanPath)) return [];
+
+  const caps = loadCaps(capsPath);
+  const scan = JSON.parse(fs.readFileSync(scanPath, "utf8"));
+  const scannedAt = new Date(scan.scannedAt);
+
+  const warnings = [];
+  for (const cap of caps) {
+    if (getLevel(cap) !== "frozen") continue;
+    const scanEntry = scan.capabilities?.find(c => c.id === cap.id);
+    if (!scanEntry?.codeAnalysis?.sourceFiles) continue;
+
+    for (const relFile of scanEntry.codeAnalysis.sourceFiles) {
+      const absFile = path.join(cwd, relFile);
+      try {
+        const stat = fs.statSync(absFile);
+        if (stat.mtimeMs > scannedAt.getTime()) {
+          warnings.push({ capId: cap.id, file: relFile });
+        }
+      } catch {}
+    }
+  }
+  return warnings;
+}
+
+// ── stability summary for CLAUDE.md ──────────────────────────────────────────
+
+export function buildStabilitySummary(caps) {
+  const frozen       = caps.filter(c => getLevel(c) === "frozen").map(c => c.id);
+  const stable       = caps.filter(c => getLevel(c) === "stable").map(c => c.id);
+  const experimental = caps.filter(c => getLevel(c) === "experimental").map(c => c.id);
+
+  if (frozen.length === 0 && stable.length === 0) return null;
+
+  const lines = ["### Capability Stability (Solid/Liquid Layer)", ""];
+
+  if (frozen.length > 0) {
+    lines.push("**🧊 Frozen — NEVER modify without explicit instruction:**");
+    for (const id of frozen) lines.push(`- \`${id}\``);
+    lines.push("");
+  }
+  if (stable.length > 0) {
+    lines.push("**〰️ Stable — prefer additive changes, avoid breaking API:**");
+    for (const id of stable) lines.push(`- \`${id}\``);
+    lines.push("");
+  }
+  if (experimental.length > 0) {
+    lines.push(`**🌊 Experimental — free to refactor:** ${experimental.map(id => `\`${id}\``).join(", ")}`);
+    lines.push("");
+  }
+
+  lines.push("> Run `infernoflow stability` to see the full liquid/solid map.");
+  return lines.join("\n");
+}
+
+// ── entry point ───────────────────────────────────────────────────────────────
+
+export async function stabilityCommand(rawArgs) {
+  const args    = (rawArgs || []).slice(1); // skip command name
+  const jsonMode = args.includes("--json");
+  const cwd      = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+  const capsPath   = path.join(infernoDir, "capabilities.json");
+
+  if (!fs.existsSync(capsPath)) {
+    console.error(red("✗ inferno/capabilities.json not found — run `infernoflow init` first."));
+    process.exit(1);
+  }
+
+  const caps = loadCaps(capsPath);
+  cmdList(caps, jsonMode);
+
+  // Also check for frozen drift if scan.json exists
+  const driftWarnings = checkFrozenDrift(infernoDir, cwd);
+  if (driftWarnings.length > 0) {
+    console.log(red("  ⚠  Frozen capability drift detected!"));
+    for (const w of driftWarnings) {
+      console.log(red(`     ${w.capId}: ${w.file} was modified since last scan`));
+    }
+    console.log(gray("  Run `infernoflow scan` to update the baseline."));
+    console.log();
+  }
+}
+
+export async function freezeCommand(rawArgs) {
+  const args    = (rawArgs || []).slice(1); // skip command name
+  const capId   = args.find(a => !a.startsWith("--"));
+  const isStable = args.includes("--stable");
+  const level   = isStable ? "stable" : "frozen";
+
+  if (!capId) {
+    console.error(red("✗ Usage: infernoflow freeze <capability-id> [--stable]"));
+    process.exit(1);
+  }
+
+  const cwd      = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+  const capsPath   = path.join(infernoDir, "capabilities.json");
+
+  if (!fs.existsSync(capsPath)) {
+    console.error(red("✗ inferno/capabilities.json not found."));
+    process.exit(1);
+  }
+
+  const caps = loadCaps(capsPath);
+  cmdFreeze(caps, capsPath, capId, level);
+}
+
+export async function thawCommand(rawArgs) {
+  const args  = (rawArgs || []).slice(1); // skip command name
+  const capId = args.find(a => !a.startsWith("--"));
+
+  if (!capId) {
+    console.error(red("✗ Usage: infernoflow thaw <capability-id>"));
+    process.exit(1);
+  }
+
+  const cwd      = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+  const capsPath   = path.join(infernoDir, "capabilities.json");
+
+  if (!fs.existsSync(capsPath)) {
+    console.error(red("✗ inferno/capabilities.json not found."));
+    process.exit(1);
+  }
+
+  const caps = loadCaps(capsPath);
+  cmdThaw(caps, capsPath, capId);
+}

package/package.json

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