scriptonia 0.8.0 → 0.9.0-rc.2

package/bin/scriptonia.mjs

@@ -25,6 +25,12 @@ const DEFAULT_URL = process.env.SCRIPTONIA_URL || "https://scriptonia.dev";
 const CONFIG_DIR = path.join(os.homedir(), ".scriptonia");
 const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 const PROJECTS_DIR = path.join(CONFIG_DIR, "projects");
+let brainBridgePromise;
+
+function loadBrainBridge() {
+  brainBridgePromise ??= import(new URL("../dist/legacy-brain-bridge.js", import.meta.url).href);
+  return brainBridgePromise;
+}
 
 const [, , cmd, ...rest] = process.argv;
 
@@ -91,7 +97,7 @@ async function login(args) {
 
   const C = colors();
   console.log(`\n  ${C.g}✓${C.r} Signed in as ${result.email}  ${C.dim}(project "${result.project}", with sample data to try)${C.r}`);
-  console.log(`  ${C.g}✓${C.r} Agent wired — skill + AGENTS.md know about \`npx scriptonia plan\``);
+  console.log(`  ${C.g}✓${C.r} Claude skill installed — run \`npx scriptonia init\` inside each repository to add AGENTS.md`);
   console.log(`\n  ${C.b}The loop — feed signal, turn an issue into a plan your agent runs:${C.r}\n`);
   console.log(`    ${C.g}npx scriptonia add${C.r} feedback.txt call.vtt      ${C.dim}feed customer signal${C.r}`);
   console.log(`    ${C.g}npx scriptonia plan${C.r} "the thing to build"      ${C.dim}→ PLAN.md (sourced, checked)${C.r}`);
@@ -341,15 +347,34 @@ async function comment(args) {
   if (target.startsWith("plan/")) {
     const slug = target.slice(5);
     console.log(`\n  ${C.dim}Folding your note into "${slug}" and regenerating…${C.r}`);
+    // A regeneration receives both a freshly retrieved pack and the complete
+    // snapshot-bound census inventory. Without both, create-file absence
+    // cannot be proved and the server fails closed.
+    let evidence;
+    try {
+      evidence = await freshPackForExistingPlan(cfg, slug);
+    } catch (error) {
+      fail(error instanceof Error ? error.message : String(error));
+    }
+    if (!evidence) {
+      fail("Cannot prove the repository census for this plan. Restore its local PLAN.md issue metadata and rebuild the Deep Brain before regenerating.");
+    }
     const res = await fetch(`${cfg.url}/api/plan/comment`, {
       method: "POST",
       headers: { authorization: `Bearer ${cfg.token}`, "content-type": "application/json" },
-      body: JSON.stringify({ slug, body: text, author: flags.as ?? cfg.email }),
+      body: JSON.stringify({
+        slug,
+        body: text,
+        author: flags.as ?? cfg.email,
+        ...(evidence ? {
+          context_pack: evidence.contextPack,
+          repository_inventory: evidence.repositoryInventory,
+        } : {}),
+      }),
     });
-    const data = await res.json().catch(() => ({}));
-    if (res.status === 402) failCredits(data);
+    const data = await readResponseJson(res);
     if (res.status === 404) fail(`no plan "${slug}" — generate one first: npx scriptonia plan "<issue>"`);
-    if (!res.ok) fail(`comment failed (${res.status}): ${JSON.stringify(data).slice(0, 200)}`);
+    if (!res.ok) failPlanResponse("comment", res, data);
     // Approval-chain receipt: which human note produced which plan version.
     if (cfg.inited) {
       const cdir = path.join(cfg.dir, "comments", "plan", slug);
@@ -360,7 +385,7 @@ async function comment(args) {
       );
       appendLog(cfg.dir, "comment", `plan/${slug} — regenerated to v${data.version}`);
     }
-    writePlan(cfg, data, flags);
+    await writePlan(cfg, data, flags, "commented");
     return;
   }
 
@@ -482,6 +507,71 @@ function failCredits(data) {
   process.exit(1);
 }
 
+async function readResponseJson(response) {
+  const text = await response.text();
+  if (!text) return {};
+  try { return JSON.parse(text); } catch { return { error: "invalid_json_response", message: text.slice(0, 2000) }; }
+}
+
+function issueText(value) {
+  if (typeof value === "string") return value;
+  if (!value || typeof value !== "object") return String(value);
+  const pathText = Array.isArray(value.path) && value.path.length ? `${value.path.join(".")}: ` : "";
+  return `${pathText}${typeof value.message === "string" ? value.message : JSON.stringify(value)}`;
+}
+
+function planWarnings(data) {
+  const values = [
+    ...(Array.isArray(data?.warnings) ? data.warnings : []),
+    ...(Array.isArray(data?.quality?.warnings) ? data.quality.warnings : []),
+  ].map(issueText).filter(Boolean);
+  return [...new Set(values)];
+}
+
+function failPlanResponse(operation, response, data) {
+  if (response.status === 402) failCredits(data);
+  const error = typeof data?.error === "string" ? data.error : `${operation}_failed`;
+  const message = typeof data?.message === "string" ? data.message : "";
+  const issues = Array.isArray(data?.issues) ? data.issues.map(issueText) : [];
+  const warnings = planWarnings(data);
+  const details = [message, ...issues.map((item) => `- ${item}`), ...warnings.map((item) => `- warning: ${item}`)].filter(Boolean);
+  if (response.status === 409) {
+    fail(`\nPlan blocked (409 · ${error}).${details.length ? `\n${details.join("\n")}` : ""}\nRun \`npx scriptonia brain status\`; rebuild if needed, then retry.`);
+  }
+  if (response.status === 422) {
+    fail(`\nPlan quality rejected (422 · ${error}).${details.length ? `\n${details.join("\n")}` : ""}\nNo PLAN.md was overwritten.`);
+  }
+  fail(`${operation} failed (${response.status} · ${error})${details.length ? `:\n${details.join("\n")}` : ""}`);
+}
+
+function issueFromPlanMarkdown(markdown) {
+  const raw = markdown.match(/^issue:\s*(.+)$/m)?.[1]?.trim();
+  if (!raw) return undefined;
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed === "string" && parsed.trim() ? parsed.trim() : undefined;
+  } catch {
+    return raw.replace(/^['"]|['"]$/g, "").trim() || undefined;
+  }
+}
+
+async function freshPackForExistingPlan(cfg, slug) {
+  if (!cfg.inited) return undefined;
+  const candidates = [path.join(cfg.plansDir, `${slug}.md`), path.resolve(process.cwd(), "PLAN.md")];
+  let issue;
+  for (const filename of candidates) {
+    try {
+      const markdown = fs.readFileSync(filename, "utf8");
+      if (filename.endsWith("PLAN.md") && !new RegExp(`^plan:\\s*${slug.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*$`, "m").test(markdown)) continue;
+      issue = issueFromPlanMarkdown(markdown);
+      if (issue) break;
+    } catch { /* server pack remains the safe fallback */ }
+  }
+  if (!issue) return undefined;
+  const { buildFreshPlanEvidence } = await loadBrainBridge();
+  return buildFreshPlanEvidence(cfg.repoPath, issue);
+}
+
 async function logout() {
   if (fs.existsSync(CONFIG_PATH)) fs.rmSync(CONFIG_PATH);
   console.log("logged out.");
@@ -752,9 +842,11 @@ async function init(args) {
 
   const existing = findProjectForCwd();
   if (existing && !flags.force) {
-    writeRepoMd(existing.dir, scanRepo(cwd));
+    injectAgentsMd(cwd);
+    injectBrainGitignore(cwd);
     console.log(`\n  ${C.g}✓${C.r} already initialized as ${C.b}${existing.data.name}${C.r} ${C.dim}(${existing.dir})${C.r}`);
     console.log(`  ${C.dim}re-scan from scratch:${C.r} ${C.g}npx scriptonia init --force${C.r}`);
+    await buildFastBrainForInit(existing.data.repoPath ?? cwd, existing.dir, C);
     console.log(`  ${C.dim}next:${C.r} ${C.g}npx scriptonia add <files>${C.r}\n`);
     return;
   }
@@ -788,9 +880,8 @@ async function init(args) {
   for (const sub of ["signals", "rules", "contexts", "plans", "comments/plan", "logs"]) {
     fs.mkdirSync(path.join(dir, sub), { recursive: true });
   }
-  // Migrate a legacy brain/ subfolder layout if present.
-  const legacyBrain = path.join(dir, "brain");
-  if (fs.existsSync(legacyBrain)) fs.rmSync(legacyBrain, { recursive: true, force: true });
+  // Legacy plain-file brains remain readable. Init never deletes repository
+  // memory or the last READY generation while replacing a project binding.
 
   fs.writeFileSync(
     path.join(dir, "project.json"),
@@ -798,22 +889,68 @@ async function init(args) {
     { mode: 0o600 },
   );
   writeProjectMd(dir, scan, pitch);
-  writeRepoMd(dir, scan);
   writeAgentsBrainMd(dir, { name, pitch, stack: scan.stack }, []);
   fs.writeFileSync(path.join(dir, ".gitignore"), "logs/\nproject.json\n");
   injectAgentsMd(cwd);
+  injectBrainGitignore(cwd);
   installSkill();
   appendLog(dir, "init", `Initialized brain for ${name} (${repoPath}) — stack: ${scan.stack}`);
 
   console.log(`\n  ${C.g}✓${C.r} Brain created for ${C.b}${name}${C.r}  ${C.dim}→ ${dir}${C.r}`);
-  console.log(`      ${C.dim}AGENTS.md · PROJECT.md · REPO.md · signals/ · rules/ · contexts/ · plans/ · comments/ · logs/${C.r}`);
+  console.log(`      ${C.dim}AGENTS.md · PROJECT.md · signals/ · rules/ · contexts/ · plans/ · comments/ · logs/${C.r}`);
   console.log(`  ${C.g}✓${C.r} Scanned repo (${scan.stack})`);
   console.log(`  ${C.g}✓${C.r} Wrote agent instructions  ${C.dim}→ ./AGENTS.md${C.r}`);
+  await buildFastBrainForInit(cwd, dir, C);
   console.log(`\n  ${C.b}Feed it customer signal, then turn an issue into a plan:${C.r}\n`);
   console.log(`    ${C.g}npx scriptonia add${C.r} feedback.txt call.vtt   ${C.dim}(or:  npx scriptonia add "Issue #42: …")${C.r}`);
   console.log(`    ${C.g}npx scriptonia plan${C.r} "the issue you want to build"\n`);
 }
 
+async function buildFastBrainForInit(repoRoot, projectDir, C) {
+  console.log(`  ${C.dim}Building the local fast brain…${C.r}`);
+  try {
+    const { buildFastBrainAfterInit } = await loadBrainBridge();
+    const result = await buildFastBrainAfterInit(repoRoot);
+    const projection = mirrorDeepRepoProjection(repoRoot, projectDir);
+    appendLog(projectDir, "brain", `READY generation ${result.generation} (${result.buildId}) after init`);
+    console.log(`  ${C.g}✓${C.r} Local brain READY  ${C.dim}generation ${result.generation}${C.r}`);
+    console.log(`  ${C.g}✓${C.r} Full repository map  ${C.dim}→ ${projection}${C.r}`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    appendLog(projectDir, "brain", `Fast build failed after binding persisted — ${message}`);
+    console.error(`  ${C.w}⚠${C.r} Fast brain build could not finish: ${message}`);
+    console.error(`    ${C.dim}Your login and project binding are saved; any prior READY generation is unchanged.${C.r}`);
+  }
+  console.log(`  ${C.b}Next:${C.r} ${C.g}npx scriptonia brain build --deep${C.r} ${C.dim}— full repository understanding (5–7 minutes)${C.r}`);
+}
+
+/**
+ * The legacy project binding still exposes REPO.md to agents working outside
+ * the repository. Its contents must be the activated Deep Brain projection,
+ * never a second, shallow filesystem scan with different facts.
+ */
+function mirrorDeepRepoProjection(repoRoot, projectDir) {
+  const source = path.join(realPath(repoRoot), ".scriptonia", "REPO.md");
+  if (!fs.existsSync(source)) throw new Error("READY generation did not produce .scriptonia/REPO.md");
+  const markdown = fs.readFileSync(source, "utf8");
+  if (!markdown.startsWith("# Repository Brain") || markdown.includes("Tree (depth 3)") || /Stack:\s*unknown/i.test(markdown)) {
+    throw new Error("READY generation produced an invalid repository projection");
+  }
+
+  // Pre-v0.6 project bindings used brain/; keep them readable without
+  // manufacturing a different repository map.
+  const targetDir = fs.existsSync(path.join(projectDir, "brain")) && !fs.existsSync(path.join(projectDir, "REPO.md"))
+    ? path.join(projectDir, "brain")
+    : projectDir;
+  fs.mkdirSync(targetDir, { recursive: true });
+  const target = path.join(targetDir, "REPO.md");
+  const temporary = `${target}.tmp-${process.pid}`;
+  fs.writeFileSync(temporary, markdown, { mode: 0o600 });
+  fs.chmodSync(temporary, 0o600);
+  fs.renameSync(temporary, target);
+  return target;
+}
+
 // ── sync ──────────────────────────────────────────────────────
 async function sync() {
   const cfg = activeCreds();
@@ -853,28 +990,36 @@ async function plan(args) {
 
   if (flags.refresh) {
     const res = await fetch(`${cfg.url}/api/plan?slug=${encodeURIComponent(flags.refresh)}`, { headers: { authorization: `Bearer ${cfg.token}` } });
-    const data = await res.json();
-    if (!res.ok) fail(`refresh failed (${res.status}): ${JSON.stringify(data)}`);
-    return writePlan(cfg, data, flags);
+    const data = await readResponseJson(res);
+    if (!res.ok) failPlanResponse("refresh", res, data);
+    return writePlan(cfg, data, flags, "refreshed");
   }
 
   const issue = args.filter((a) => !a.startsWith("--")).join(" ").trim();
   if (!issue) fail('usage: npx scriptonia plan "<the issue>"   [--out PLAN.md] [--refresh <slug>]');
 
-  const repoSummary = cfg.inited && fs.existsSync(path.join(cfg.brainDir, "REPO.md"))
-    ? fs.readFileSync(path.join(cfg.brainDir, "REPO.md"), "utf8").slice(0, 6000)
-    : buildRepoMd(scanRepo(process.cwd())).slice(0, 6000);
+  if (!cfg.inited) fail("run `npx scriptonia init` in this repository first — plans require a fresh local Deep Brain context pack");
+  let evidence;
+  try {
+    const { buildFreshPlanEvidence } = await loadBrainBridge();
+    evidence = buildFreshPlanEvidence(cfg.repoPath, issue);
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
 
-  console.log(`\n  ${C.dim}Planning "${issue}" — retrieving signal, checking decisions, drafting… (Opus, ~15s)${C.r}`);
+  console.log(`\n  ${C.dim}Planning "${issue}" — using fresh local brain evidence, retrieving signal, checking decisions, drafting…${C.r}`);
   const res = await fetch(`${cfg.url}/api/plan`, {
     method: "POST",
     headers: { authorization: `Bearer ${cfg.token}`, "content-type": "application/json" },
-    body: JSON.stringify({ issue, repo_summary: repoSummary }),
+    body: JSON.stringify({
+      issue,
+      context_pack: evidence.contextPack,
+      repository_inventory: evidence.repositoryInventory,
+    }),
   });
-  const data = await res.json();
-  if (res.status === 402) failCredits(data);
-  if (!res.ok) fail(`plan failed (${res.status}): ${JSON.stringify(data).slice(0, 200)}`);
-  writePlan(cfg, data, flags);
+  const data = await readResponseJson(res);
+  if (!res.ok) failPlanResponse("plan", res, data);
+  await writePlan(cfg, data, flags, "fresh");
 }
 
 // ── verify — PLAN.md + git diff → separate CI gates ──────────────────
@@ -883,7 +1028,7 @@ async function verify(args) {
   process.exitCode = result.exitCode;
 }
 
-function writePlan(cfg, data, flags) {
+async function writePlan(cfg, data, flags, flow) {
   const C = colors();
   const out = flags.out ?? "PLAN.md";
   fs.writeFileSync(path.resolve(process.cwd(), out), data.markdown);
@@ -895,8 +1040,25 @@ function writePlan(cfg, data, flags) {
     fs.writeFileSync(path.join(cfg.brainDir, "plan.md"), data.markdown);
     appendLog(cfg.dir, "plan", `${data.slug} v${data.version} — ${(data.sources ?? []).length} sources, ${data.contradictions ?? 0} unresolved`);
   }
+  if (cfg.inited && cfg.repoPath) {
+    try {
+      const { recordPlanQualityEvidence } = await loadBrainBridge();
+      recordPlanQualityEvidence(cfg.repoPath, {
+        flow,
+        slug: data.slug,
+        version: data.version,
+        quality: data.quality,
+        brainGeneration: data.brain_generation,
+        contextPackHash: data.context_pack_hash,
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`  ${C.dim}Plan was written, but build-scoped quality evidence could not be recorded: ${message}${C.r}`);
+    }
+  }
   console.log(`\n  ${C.g}✓${C.r} Plan ${C.b}${data.slug}${C.r} ${C.dim}v${data.version}${C.r} → ${C.v}${out}${C.r}`);
   console.log(`  ${C.dim}${(data.sources ?? []).length} cited signal(s)${data.contradictions ? `, ${data.contradictions} unresolved contradiction(s)` : ""}${C.r}`);
+  for (const warning of planWarnings(data)) console.log(`  ${C.w}⚠ ${warning}${C.r}`);
   console.log(`\n  ${C.b}Hand it to your agent:${C.r}  ${C.g}claude "execute PLAN.md"${C.r}   ${C.dim}(or codex · opencode · hermes)${C.r}`);
   console.log(`  ${C.dim}refine:${C.r} ${C.g}npx scriptonia comment plan/${data.slug} "…"${C.r} ${C.dim}(rewrites PLAN.md)${C.r}`);
   if (data.credits) {
@@ -914,7 +1076,6 @@ function scanRepo(cwd) {
   let pkg = null;
   try { pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8")); } catch {}
   const stack = detectStack(cwd, pkg);
-  const tree = buildTree(cwd, 3);
   const name =
     (pkg && pkg.name && String(pkg.name).replace(/^@[^/]+\//, "")) ||
     gitRemoteName(cwd) ||
@@ -922,11 +1083,16 @@ function scanRepo(cwd) {
   const scripts = pkg && pkg.scripts ? Object.keys(pkg.scripts) : [];
   const deps = pkg ? Object.keys({ ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) }).slice(0, 20) : [];
   const entryPoints = findEntryPoints(cwd);
-  return { name, readmeHead, stack, tree, scripts, deps, entryPoints, pkgDescription: pkg?.description || "" };
+  return { name, readmeHead, stack, scripts, deps, entryPoints, pkgDescription: pkg?.description || "" };
 }
 
 function detectStack(cwd, pkg) {
   const has = (f) => fs.existsSync(path.join(cwd, f));
+  let pubspec = "";
+  if (has("pubspec.yaml")) {
+    try { pubspec = fs.readFileSync(path.join(cwd, "pubspec.yaml"), "utf8"); } catch {}
+    if (/(^|\n)\s*flutter\s*:|sdk\s*:\s*flutter\b|flutter_test\s*:/m.test(pubspec)) return "Flutter/Dart";
+  }
   if (pkg) {
     const d = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
     if (d.next) return "Next.js / TypeScript";
@@ -936,6 +1102,7 @@ function detectStack(cwd, pkg) {
   }
   if (has("go.mod")) return "Go";
   if (has("Cargo.toml")) return "Rust";
+  if (pubspec) return "Dart";
   if (has("requirements.txt") || has("pyproject.toml")) return "Python";
   if (has("Gemfile")) return "Ruby";
   if (has("pom.xml") || has("build.gradle")) return "Java/JVM";
@@ -951,24 +1118,6 @@ function findEntryPoints(cwd) {
   return cands.filter((c) => fs.existsSync(path.join(cwd, c)));
 }
 
-function buildTree(cwd, maxDepth) {
-  const IGNORE = new Set(["node_modules", ".git", ".next", "dist", "build", ".turbo", "coverage", ".vercel", "out", "__pycache__", ".venv", "target", "vendor"]);
-  const lines = [];
-  const walk = (d, depth, prefix) => {
-    if (depth > maxDepth) return;
-    let entries;
-    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
-    entries = entries.filter((e) => !e.name.startsWith(".") || e.name === ".env.example").filter((e) => !IGNORE.has(e.name));
-    entries.sort((a, b) => (a.isDirectory() === b.isDirectory() ? a.name.localeCompare(b.name) : a.isDirectory() ? -1 : 1));
-    for (const e of entries.slice(0, 40)) {
-      lines.push(`${prefix}${e.name}${e.isDirectory() ? "/" : ""}`);
-      if (e.isDirectory()) walk(path.join(d, e.name), depth + 1, prefix + "  ");
-    }
-  };
-  walk(cwd, 1, "");
-  return lines.slice(0, 200).join("\n");
-}
-
 function gitRemoteName(cwd) {
   try {
     const url = execSync("git remote get-url origin", { cwd, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
@@ -1003,15 +1152,6 @@ function writeProjectMd(dir, scan, pitch) {
   fs.writeFileSync(path.join(dir, "PROJECT.md"), md);
 }
 
-function writeRepoMd(dir, scan) {
-  // v0.6 flat layout; keep writing into brain/ for pre-0.6 projects.
-  const target = fs.existsSync(path.join(dir, "brain")) && !fs.existsSync(path.join(dir, "REPO.md"))
-    ? path.join(dir, "brain")
-    : dir;
-  fs.mkdirSync(target, { recursive: true });
-  fs.writeFileSync(path.join(target, "REPO.md"), buildRepoMd(scan));
-}
-
 /**
  * AGENTS.md — the brain's master contract. What an agent must respect when
  * acting on this project: identity, the Scriptonia workflow, and the
@@ -1030,17 +1170,24 @@ function writeAgentsBrainMd(dir, meta, decisions) {
     "",
     "## 2. Workflow — non-negotiable",
     "",
-    '1. Before building any user-facing change, run `npx scriptonia plan "<the issue>"`.',
+    "1. Check repository evidence with `npx scriptonia brain status`. If it is",
+    "   missing or stale, run `npx scriptonia brain build --fast --offline`.",
+    '2. Before building any user-facing change, run `npx scriptonia plan "<the issue>"`.',
     "   It writes PLAN.md, grounded in real customer signal and checked against",
-    "   the rules below.",
-    "2. Execute PLAN.md **exactly**. Its **Non-goals** section is a fence — do not",
+    "   the rules below and the active local Deep Brain generation.",
+    "3. Use `npx scriptonia why <file>` to inspect the exact facts, dependents,",
+    "   and tests behind a planned file before editing it.",
+    "4. Execute PLAN.md **exactly**. Its **Non-goals** section is a fence — do not",
     "   build past it.",
-    "3. Any constraint marked **⚠ UNRESOLVED** is an approval gate: STOP and get a",
+    "5. Any constraint marked **⚠ UNRESOLVED** is an approval gate: STOP and get a",
     '   human comment (`npx scriptonia comment plan/<slug> "…"`) before writing code.',
-    "4. Cite PLAN.md's `sources` signal ids in your PR description.",
-    "5. After implementation, run `npx scriptonia verify`; fix every BLOCK",
+    "6. Cite PLAN.md's `sources` signal ids in your PR description.",
+    "7. After implementation, run `npx scriptonia verify`; fix every BLOCK",
     "   before merge and preserve the generated `.scriptonia/evals/*.yaml` case.",
     "",
+    "After setup, run `npx scriptonia brain build --deep` for the enriched",
+    "repository model (allow 5–7 minutes).",
+    "",
     "## 3. Non-negotiable constraints (from the decisions corpus)",
     "",
   ];
@@ -1148,22 +1295,6 @@ function appendLog(dir, name, msg) {
   } catch { /* audit trail is best-effort */ }
 }
 
-function buildRepoMd(scan) {
-  return [
-    `# Repo map — ${scan.name}`,
-    "",
-    `**Stack:** ${scan.stack}`,
-    scan.entryPoints.length ? `**Entry points:** ${scan.entryPoints.join(", ")}` : "",
-    "",
-    "## Tree (depth 3)",
-    "```",
-    scan.tree,
-    "```",
-    "",
-    "*When you name files in a plan, use paths from this tree. Refresh with `npx scriptonia init --force`.*",
-  ].filter(Boolean).join("\n");
-}
-
 function renderContextFile(c) {
   const L = [`# ${c.title}`, "", `> **${c.type}** · ${c.segment} · strength ${c.strength}/10 · v${c.version}`, "", c.summary, ""];
   if (c.sources?.length) { L.push("## Sources"); for (const s of c.sources) L.push(`- \`${s.id.slice(0, 8)}\` ${s.source}${s.ref ? ` — ${s.ref}` : ""}`); L.push(""); }
@@ -1182,8 +1313,12 @@ function injectAgentsMd(cwd) {
 This repo has a product brain (customer signal + prior decisions). Before building
 any user-facing change:
 
+- \`npx scriptonia brain status\` → confirms the local Deep Brain is READY and fresh.
+  If missing or stale, run \`npx scriptonia brain build --fast --offline\`.
 - \`npx scriptonia plan "<the issue>"\` → writes **PLAN.md** here. Execute PLAN.md
   exactly; respect its **Non-goals**; cite its \`sources\` ids in your PR.
+- \`npx scriptonia why <file>\` → shows the facts, dependents, and related tests
+  behind a planned file before you edit it.
 - \`npx scriptonia query "<topic>"\` → JSON: what customers asked for, contradictions,
   edge cases.
 - If a plan constraint is **UNRESOLVED**, stop and ask the human. If a step
@@ -1191,6 +1326,8 @@ any user-facing change:
   and re-read PLAN.md.
 - After implementation, run \`npx scriptonia verify\`. Fix every BLOCK before
   merge; keep the generated \`.scriptonia/evals/*.yaml\` regression case.
+- After setup, run \`npx scriptonia brain build --deep\` for the enriched repository
+  model (allow 5–7 minutes).
 ${END}`;
 
   let existing = "";
@@ -1205,6 +1342,36 @@ ${END}`;
   }
 }
 
+// The database, object store, and regenerated projections are local artifacts.
+// Keep policies/evals outside these rules so teams can commit their shared
+// product constraints and regression cases.
+function injectBrainGitignore(cwd) {
+  const file = path.join(cwd, ".gitignore");
+  const required = [
+    ".scriptonia/brain.db*",
+    ".scriptonia/artifacts/",
+    ".scriptonia/objects/",
+    ".scriptonia/staging/",
+    ".scriptonia/REPO.md",
+    ".scriptonia/GRAPH.md",
+    ".scriptonia/ARCHITECTURE.md",
+    ".scriptonia/PATTERNS.md",
+    ".scriptonia/DECISION_CANDIDATES.md",
+    ".scriptonia/brain-coverage.json",
+    ".scriptonia/result*.json",
+    ".scriptonia/result*.sarif",
+  ];
+  let existing = "";
+  try { existing = fs.readFileSync(file, "utf8"); } catch {}
+
+  const present = new Set(existing.split(/\r?\n/).map((line) => line.trim()));
+  const missing = required.filter((line) => !present.has(line));
+  if (!missing.length) return;
+
+  const prefix = existing.length && !existing.endsWith("\n") ? `${existing}\n` : existing;
+  fs.writeFileSync(file, `${prefix}${missing.join("\n")}\n`);
+}
+
 // ── misc ──────────────────────────────────────────────────────
 function slugify(s) {
   return String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "").slice(0, 60) || "project";

package/bin/verify.mjs

@@ -27,7 +27,7 @@ export async function runVerification(args, { cfg, cwd = process.cwd(), fetchImp
   });
   const repositoryChecks = flags["skip-checks"] ? skippedRepositoryGate() : runRepositoryChecks(cwd, files);
   const unresolvedConstraints = buildUnresolvedGate(plan);
-  const testCoverage = buildTestCoverageGate(files);
+  const testCoverage = buildTestCoverageGate(files, cwd);
 
   const response = await semanticPromise;
   const semantic = await response.json().catch(() => ({}));
@@ -82,9 +82,9 @@ export function buildUnresolvedGate(plan) {
   });
 }
 
-export function buildTestCoverageGate(files) {
+export function buildTestCoverageGate(files, cwd) {
   const tests = files.filter(isTestFile);
-  const behavior = files.filter((file) => isSourceFile(file) && !isTestFile(file));
+  const behavior = files.filter((file) => isSourceFile(file, cwd));
   if (tests.length) return gate("PASS", {
     evidence: tests,
     plan_criterion: "Add or update tests for changed product behavior.",
@@ -205,12 +205,46 @@ function diffFiles(diff) {
   return [...new Set([...diff.matchAll(/^diff --git a\/(.+?) b\/(.+)$/gm)].map((match) => match[2]))];
 }
 
+const SOURCE_EXTENSIONS = new Set([
+  ".c", ".h", ".cc", ".cp", ".cpp", ".cxx", ".hh", ".hpp", ".hxx", ".inc", ".m", ".mm", ".cs",
+  ".css", ".scss", ".sass", ".less", ".dart", ".ex", ".exs", ".go", ".graphql", ".gql", ".html", ".htm",
+  ".java", ".js", ".jsx", ".mjs", ".cjs", ".json", ".jsonc", ".kt", ".kts", ".lua", ".pl", ".pm", ".php",
+  ".proto", ".py", ".pyi", ".rb", ".rs", ".scala", ".sh", ".bash", ".zsh", ".fish", ".sql", ".bzl",
+  ".bazel", ".star", ".swift", ".toml", ".ts", ".tsx", ".mts", ".cts", ".vue", ".xml", ".plist", ".yaml", ".yml",
+]);
+const STARLARK_BASENAMES = new Set(["BUILD", "BUILD.bazel", "WORKSPACE", "WORKSPACE.bzlmod", "MODULE.bazel"]);
+const CONFIG_BASENAMES = new Set([
+  "package.json", "package-lock.json", "pnpm-lock.yaml", "pnpm-workspace.yaml", "yarn.lock", "pubspec.yaml", "pubspec.lock",
+  "Cargo.toml", "go.mod", "go.sum", "pom.xml", "composer.json", "composer.lock", "pyproject.toml", "requirements.txt",
+  "tsconfig.json", "analysis_options.yaml", "CMakeLists.txt", "Makefile", "Dockerfile", "CODEOWNERS",
+]);
+const TEST_EXTENSION = "(?:c|cc|cp|cpp|cxx|h|hh|hpp|hxx|inc|m|mm|cs|dart|ex|exs|go|java|js|jsx|mjs|cjs|kt|kts|lua|pl|pm|php|proto|py|pyi|rb|rs|scala|sh|bash|zsh|fish|bzl|bazel|star|swift|ts|tsx|mts|cts|vue)";
+const TEST_BASENAME = new RegExp(`(?:^|/)(?:test_[^/]+|[^/]+_(?:test|spec)|[^/]+\\.(?:test|spec))\\.${TEST_EXTENSION}$`, "i");
+
 function isTestFile(file) {
-  return /(^|\/)(?:__tests__|tests?|spec)(?:\/|$)|\.(?:test|spec)\.[^.]+$/i.test(file);
+  const normalized = file.replaceAll("\\", "/");
+  return /(^|\/)(?:__tests__|tests?|spec|integration_test)(?:\/|$)/i.test(normalized) ||
+    TEST_BASENAME.test(normalized) ||
+    /(?:^|\/)[^/]+(?:Test|Tests|Spec)\.(?:cs|java|kt|kts|scala|swift)$/.test(normalized);
 }
 
-function isSourceFile(file) {
-  return /\.(?:[cm]?[jt]sx?|py|go|rs|java|rb|php|swift|kt)$/i.test(file) && !/(?:^|\/)(?:scripts?|migrations?|drizzle)(?:\/|$)/i.test(file);
+function isSourceFile(file, cwd) {
+  const normalized = file.replaceAll("\\", "/");
+  if (isTestFile(normalized) || /(?:^|\/)(?:third_party|vendor|external|docs?|adr|changelogs?)(?:\/|$)/i.test(normalized)) return false;
+  const base = path.posix.basename(normalized);
+  if (/(?:^|\/)generated(?:\/|$)/i.test(normalized) || /\.(?:g|freezed)\.dart$|\.pb\.go$|\.generated\.[^.]+$|\.min\.(?:js|css)$/i.test(base)) return false;
+  if (STARLARK_BASENAMES.has(base)) return true;
+  if (CONFIG_BASENAMES.has(base) || /\.(?:lock|config|conf|ini|properties)$/i.test(base) ||
+      /(?:^|\/)\.github\/workflows\/[^/]+\.ya?ml$/i.test(normalized) ||
+      /^(?:Dockerfile(?:\..+)?|requirements(?:[-_.][^/]*)?\.txt|tsconfig(?:\.[^/]+)?\.json|(?:docker-)?compose(?:\.[^/]+)?\.ya?ml)$/i.test(base)) return false;
+  if (SOURCE_EXTENSIONS.has(path.posix.extname(base).toLowerCase())) return true;
+  if (!cwd) return false;
+  try {
+    const firstLine = fs.readFileSync(path.join(cwd, normalized), "utf8").split(/\r?\n/, 1)[0] ?? "";
+    return /^#!.*\b(?:python3?|bash|sh|zsh|fish|node|ruby)\b/.test(firstLine);
+  } catch {
+    return false;
+  }
 }
 
 function gate(verdict, check) {

package/dist/brain-ast-worker.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import {
+  AST_WORKER_PROTOCOL_VERSION,
+  isAstWorkerRequest,
+  parseSource
+} from "./chunk-6TLQP3LV.js";
+
+// ../packages/brain-ast/src/worker-runtime.ts
+import { isMainThread, parentPort, threadId } from "worker_threads";
+function serializeError(error) {
+  if (!(error instanceof Error)) return { name: "Error", message: String(error) };
+  const code = "code" in error && typeof error.code === "string" ? error.code : void 0;
+  return {
+    name: error.name,
+    message: error.message,
+    ...error.stack ? { stack: error.stack } : {},
+    ...code ? { code } : {}
+  };
+}
+function startAstWorkerThread() {
+  if (isMainThread || !parentPort) {
+    throw new Error("the Deep Brain AST worker entry must run inside a worker thread");
+  }
+  const port = parentPort;
+  port.on("message", async (request) => {
+    if (!isAstWorkerRequest(request)) {
+      const response = {
+        protocolVersion: AST_WORKER_PROTOCOL_VERSION,
+        type: "error",
+        jobId: request && typeof request === "object" && "jobId" in request && typeof request.jobId === "number" ? request.jobId : 0,
+        threadId,
+        error: { name: "AstWorkerProtocolError", message: "received an invalid AST worker request" }
+      };
+      port.postMessage(response);
+      return;
+    }
+    try {
+      const result = await parseSource(request.input);
+      const response = {
+        protocolVersion: AST_WORKER_PROTOCOL_VERSION,
+        type: "result",
+        jobId: request.jobId,
+        threadId,
+        result
+      };
+      port.postMessage(response);
+    } catch (error) {
+      const response = {
+        protocolVersion: AST_WORKER_PROTOCOL_VERSION,
+        type: "error",
+        jobId: request.jobId,
+        threadId,
+        error: serializeError(error)
+      };
+      port.postMessage(response);
+    }
+  });
+}
+
+// src/brain-ast-worker.ts
+startAstWorkerThread();
+//# sourceMappingURL=brain-ast-worker.js.map

package/dist/brain-ast-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../packages/brain-ast/src/worker-runtime.ts","../src/brain-ast-worker.ts"],"sourcesContent":["import { isMainThread, parentPort, threadId } from \"node:worker_threads\";\nimport { parseSource } from \"./parse-source\";\nimport {\n  AST_WORKER_PROTOCOL_VERSION,\n  isAstWorkerRequest,\n  type AstWorkerResponse,\n  type SerializedWorkerError,\n} from \"./worker-protocol\";\n\nfunction serializeError(error: unknown): SerializedWorkerError {\n  if (!(error instanceof Error)) return { name: \"Error\", message: String(error) };\n  const code = \"code\" in error && typeof error.code === \"string\" ? error.code : undefined;\n  return {\n    name: error.name,\n    message: error.message,\n    ...(error.stack ? { stack: error.stack } : {}),\n    ...(code ? { code } : {}),\n  };\n}\n\n/** Starts the dedicated AST worker message loop. This is intentionally not run\n * when the module is imported so the CLI can bundle it as a separate entry. */\nexport function startAstWorkerThread(): void {\n  if (isMainThread || !parentPort) {\n    throw new Error(\"the Deep Brain AST worker entry must run inside a worker thread\");\n  }\n  const port = parentPort;\n  port.on(\"message\", async (request: unknown) => {\n    if (!isAstWorkerRequest(request)) {\n      const response: AstWorkerResponse = {\n        protocolVersion: AST_WORKER_PROTOCOL_VERSION,\n        type: \"error\",\n        jobId: request && typeof request === \"object\" && \"jobId\" in request && typeof request.jobId === \"number\" ? request.jobId : 0,\n        threadId,\n        error: { name: \"AstWorkerProtocolError\", message: \"received an invalid AST worker request\" },\n      };\n      port.postMessage(response);\n      return;\n    }\n    try {\n      const result = await parseSource(request.input);\n      const response: AstWorkerResponse = {\n        protocolVersion: AST_WORKER_PROTOCOL_VERSION,\n        type: \"result\",\n        jobId: request.jobId,\n        threadId,\n        result,\n      };\n      port.postMessage(response);\n    } catch (error) {\n      const response: AstWorkerResponse = {\n        protocolVersion: AST_WORKER_PROTOCOL_VERSION,\n        type: \"error\",\n        jobId: request.jobId,\n        threadId,\n        error: serializeError(error),\n      };\n      port.postMessage(response);\n    }\n  });\n}\n","import { startAstWorkerThread } from \"@scriptonia/brain-ast/worker\";\n\nstartAstWorkerThread();\n"],"mappings":";;;;;;;;AAAA,SAAS,cAAc,YAAY,gBAAgB;AASnD,SAAS,eAAe,OAAuC;AAC7D,MAAI,EAAE,iBAAiB,OAAQ,QAAO,EAAE,MAAM,SAAS,SAAS,OAAO,KAAK,EAAE;AAC9E,QAAM,OAAO,UAAU,SAAS,OAAO,MAAM,SAAS,WAAW,MAAM,OAAO;AAC9E,SAAO;AAAA,IACL,MAAM,MAAM;AAAA,IACZ,SAAS,MAAM;AAAA,IACf,GAAI,MAAM,QAAQ,EAAE,OAAO,MAAM,MAAM,IAAI,CAAC;AAAA,IAC5C,GAAI,OAAO,EAAE,KAAK,IAAI,CAAC;AAAA,EACzB;AACF;AAIO,SAAS,uBAA6B;AAC3C,MAAI,gBAAgB,CAAC,YAAY;AAC/B,UAAM,IAAI,MAAM,iEAAiE;AAAA,EACnF;AACA,QAAM,OAAO;AACb,OAAK,GAAG,WAAW,OAAO,YAAqB;AAC7C,QAAI,CAAC,mBAAmB,OAAO,GAAG;AAChC,YAAM,WAA8B;AAAA,QAClC,iBAAiB;AAAA,QACjB,MAAM;AAAA,QACN,OAAO,WAAW,OAAO,YAAY,YAAY,WAAW,WAAW,OAAO,QAAQ,UAAU,WAAW,QAAQ,QAAQ;AAAA,QAC3H;AAAA,QACA,OAAO,EAAE,MAAM,0BAA0B,SAAS,yCAAyC;AAAA,MAC7F;AACA,WAAK,YAAY,QAAQ;AACzB;AAAA,IACF;AACA,QAAI;AACF,YAAM,SAAS,MAAM,YAAY,QAAQ,KAAK;AAC9C,YAAM,WAA8B;AAAA,QAClC,iBAAiB;AAAA,QACjB,MAAM;AAAA,QACN,OAAO,QAAQ;AAAA,QACf;AAAA,QACA;AAAA,MACF;AACA,WAAK,YAAY,QAAQ;AAAA,IAC3B,SAAS,OAAO;AACd,YAAM,WAA8B;AAAA,QAClC,iBAAiB;AAAA,QACjB,MAAM;AAAA,QACN,OAAO,QAAQ;AAAA,QACf;AAAA,QACA,OAAO,eAAe,KAAK;AAAA,MAC7B;AACA,WAAK,YAAY,QAAQ;AAAA,IAC3B;AAAA,EACF,CAAC;AACH;;;AC1DA,qBAAqB;","names":[]}