scriptonia 0.6.0 → 0.8.0

package/README.md

@@ -15,8 +15,8 @@ never see one), and your agent's `AGENTS.md` / skill now know about `scriptonia
 plan`. Then, in your project:
 
 ```sh
-scriptonia add feedback.txt call.vtt notes.md   # feed customer signal
-scriptonia plan "let compliance filter the audit log by actor"
+npx scriptonia add feedback.txt call.vtt notes.md   # feed customer signal
+npx scriptonia plan "let compliance filter the audit log by actor"
 # → writes PLAN.md: goal, cited evidence, non-goals, real file paths, acceptance criteria
 claude "execute PLAN.md"                         # your agent ships it → PR
 ```
@@ -24,7 +24,7 @@ claude "execute PLAN.md"                         # your agent ships it → PR
 Left a review note? The plan regenerates:
 
 ```sh
-scriptonia comment plan/<slug> "default to all actors, and gate behind the admin role"
+npx scriptonia comment plan/<slug> "default to all actors, and gate behind the admin role"
 # → PLAN.md v2 with your note folded in
 ```
 
@@ -32,19 +32,21 @@ scriptonia comment plan/<slug> "default to all actors, and gate behind the admin
 
 | step | command | what happens |
 |---|---|---|
-| **SIGNAL** | `scriptonia add <files>` | Ingest text · md · vtt as customer signal (deduped, auto-sourced). |
-| **PLAN** | `scriptonia plan "<issue>"` | Retrieve the relevant signal, check prior decisions, and write **PLAN.md** — every claim cites a signal id; contradictions are gated **UNRESOLVED** until a human approves. |
-| **BUILD** | `claude "execute PLAN.md"` | Your agent runs the plan verbatim. Respects the Non-goals fence; cites sources in the PR. |
-| **REFINE** | `scriptonia comment plan/<slug> "…"` | A note regenerates the plan (v+1). A comment approving an override flips a contradiction to **RESOLVED**. |
+| **SIGNAL** | `npx scriptonia add <files>` | Ingest text · md · vtt as customer signal (deduped, auto-sourced). |
+| **PLAN** | `npx scriptonia plan "<issue>"` | Retrieve the relevant signal, check prior decisions, and write **PLAN.md** — every claim cites a signal id; contradictions are gated **UNRESOLVED** until a human approves. |
+| **BUILD** | `claude "execute PLAN.md"` | Your agent implements against the plan's cited criteria and Non-goals fence. |
+| **REFINE** | `npx scriptonia comment plan/<slug> "…"` | A note regenerates the plan (v+1). A comment approving an override flips a contradiction to **RESOLVED**. |
+| **VERIFY** | `npx scriptonia verify` | Check the git diff, unresolved constraints, repo checks, and test coverage. Writes `.scriptonia/evals/<plan>.yaml`; exits 1 on BLOCK. |
 
 ## Commands
 
 ```
 setup     login                     init [per repo]
-signal    add <files>               (--source, --segment, or  cat x | scriptonia add -)
+signal    add <files>               (--source, --segment, or  cat x | npx scriptonia add -)
 plan      plan "<issue>"            (--out <file>, --refresh <slug>)
           plans                     list plans + their slugs
           comment plan/<slug> "…"   refine → regenerates PLAN.md
+verify    verify [--base <ref>]       PLAN.md + git diff → PASS / WARN / BLOCK
 inspect   scriptonia                the loop + what's next
           contexts | query "<topic>" | link "<id>" | sync
 account   status | logout | skill | mcp
@@ -52,10 +54,13 @@ account   status | logout | skill | mcp
 
 ## One brain per repo (for people juggling projects)
 
-`scriptonia init` in a repo gives it its own brain at
+`npx scriptonia init` in a repo gives it its own brain at
 `~/.scriptonia/projects/<slug>/`, scans the code into a repo map (so plan steps
-name real files), and writes an `AGENTS.md` section. Confidential signal stays
-in your home dir — only `PLAN.md` and the `AGENTS.md` note land in the repo.
+name real files), and writes an `AGENTS.md` section. Customer signal you submit
+is stored and embedded on Scriptonia's servers; it is not written into the
+repository. The local brain is a human-readable working surface. Initialization
+does not upload the full codebase. When you explicitly run `verify`, the selected
+PLAN.md and git diff are sent for analysis; the YAML regression case stays local.
 
 Skip `init` if you have one product — `login → add → plan` uses your default
 brain and scans whatever repo you run `plan` in.
@@ -71,4 +76,4 @@ Exposes `get_context`, `link_back`, `flag_contradiction` from your stored login.
 ## Self-hosting
 
 Defaults to `https://scriptonia.dev`. Point elsewhere with
-`SCRIPTONIA_URL=https://your.host scriptonia login` (or `--url`). Node 18+.
+`SCRIPTONIA_URL=https://your.host npx scriptonia login` (or `--url`). Node 18+.

package/bin/scriptonia.mjs

@@ -2,12 +2,12 @@
 /**
  * scriptonia — issue → executable plan for your coding agent.
  *
- *   scriptonia login                 browser sign-in; wires your agent
- *   scriptonia add <files>           feed customer signal (text · md · vtt)
- *   scriptonia plan "<issue>"        → PLAN.md: sourced, contradiction-checked
- *   scriptonia comment plan/<slug>   refine → regenerates PLAN.md
- *   scriptonia init                  [per repo] give a repo its own brain
- *   scriptonia mcp                   MCP over stdio (for MCP-native agents)
+ *   npx scriptonia login                 browser sign-in; wires your agent
+ *   npx scriptonia add <files>           feed customer signal (text · md · vtt)
+ *   npx scriptonia plan "<issue>"        → PLAN.md: sourced, contradiction-checked
+ *   npx scriptonia comment plan/<slug>   refine → regenerates PLAN.md
+ *   npx scriptonia init                  [per repo] give a repo its own brain
+ *   npx scriptonia mcp                   MCP over stdio (for MCP-native agents)
  *
  * After `login`, everything lives in ~/.scriptonia/. No env vars, no key
  * pasting. Pure ESM, zero build step — runs on Node 18+.
@@ -19,6 +19,7 @@ import path from "node:path";
 import readline from "node:readline";
 import { spawn, execSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
+import { runVerification } from "./verify.mjs";
 
 const DEFAULT_URL = process.env.SCRIPTONIA_URL || "https://scriptonia.dev";
 const CONFIG_DIR = path.join(os.homedir(), ".scriptonia");
@@ -30,9 +31,9 @@ const [, , cmd, ...rest] = process.argv;
 const commands = {
   login, init, sync,
   add, ingest: add, push: add,
-  plan, plans, comment,
+  plan, plans, comment, verify,
   query, contexts, link,
-  status, logout, skill: reinstallSkill, mcp,
+  status, credits, logout, skill: reinstallSkill, mcp,
   flow, guide: flow,
   help: async () => usage(),
 };
@@ -63,7 +64,7 @@ async function login(args) {
       const project = u.searchParams.get("project") ?? "";
       if (!token || returnedState !== state) {
         res.writeHead(400, { "content-type": "text/html" });
-        res.end(pageHtml("Login failed", "State mismatch — run <code>scriptonia login</code> again."));
+        res.end(pageHtml("Login failed", "State mismatch — run <code>npx scriptonia login</code> again."));
         return;
       }
       res.writeHead(200, { "content-type": "text/html" });
@@ -90,13 +91,13 @@ 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 \`scriptonia plan\``);
+  console.log(`  ${C.g}✓${C.r} Agent wired — skill + AGENTS.md know about \`npx scriptonia plan\``);
   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}scriptonia add${C.r} feedback.txt call.vtt      ${C.dim}feed customer signal${C.r}`);
-  console.log(`    ${C.g}scriptonia plan${C.r} "the thing to build"      ${C.dim}→ PLAN.md (sourced, checked)${C.r}`);
+  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}`);
   console.log(`    ${C.g}claude${C.r} "execute PLAN.md"                 ${C.dim}your agent ships it${C.r}`);
-  console.log(`\n  ${C.dim}Try it on the sample data now:${C.r} ${C.g}scriptonia plan "filter audit log by actor"${C.r}`);
-  console.log(`  ${C.dim}Working across repos? Run${C.r} ${C.g}scriptonia init${C.r} ${C.dim}in each for its own brain.${C.r}\n`);
+  console.log(`\n  ${C.dim}Try it on the sample data now:${C.r} ${C.g}npx scriptonia plan "filter audit log by actor"${C.r}`);
+  console.log(`  ${C.dim}Working across repos? Run${C.r} ${C.g}npx scriptonia init${C.r} ${C.dim}in each for its own brain.${C.r}\n`);
 }
 
 // ─────────────────────────────────────────────────────────────
@@ -108,7 +109,7 @@ async function flow() {
   if (!cfg) {
     console.log(`\n  ${C.b}SCRIPTONIA${C.r} · turn customer signal into plans your agent can execute\n`);
     console.log(`  One command sets everything up:\n`);
-    console.log(`    ${C.g}scriptonia login${C.r}\n`);
+    console.log(`    ${C.g}npx scriptonia login${C.r}\n`);
     return;
   }
 
@@ -127,26 +128,33 @@ async function flow() {
   const recentPlan = o?.plans?.[0]?.slug ?? null;
 
   console.log(`\n  ${C.b}SCRIPTONIA${C.r}  ·  issue → executable plan for your agent`);
-  console.log(`  ${C.dim}${cfg.email} · project ${o?.project ?? projName}${repo ? "" : C.dim + "  (global — run `scriptonia init` in a repo for its own brain)"}${C.r}\n`);
+  console.log(`  ${C.dim}${cfg.email} · project ${o?.project ?? projName}${repo ? "" : C.dim + "  (global — run `npx scriptonia init` in a repo for its own brain)"}${C.r}\n`);
 
   const row = (n, name, desc, cmd) =>
     console.log(`  ${C.v}${n}${C.r}  ${C.b}${name.padEnd(7)}${C.r} ${C.dim}${desc.padEnd(34)}${C.r} ${cmd ? C.g + cmd + C.r : ""}`);
 
-  console.log(`  ${C.dim}THE LOOP${C.r}   ${C.dim}${s.total} signals · ${plansN} plans${C.r}`);
-  row("1", "SIGNAL", "feed customer reality (text·md·vtt)", `scriptonia add <files>`);
-  row("2", "PLAN", "issue → PLAN.md, sourced & checked", `scriptonia plan "<issue>"`);
+  const cr = o?.credits;
+  const creditStr = cr && cr.metered !== false ? ` · ${cr.plan} ${cr.used}/${cr.cap} credits` : "";
+  console.log(`  ${C.dim}THE LOOP${C.r}   ${C.dim}${s.total} signals · ${plansN} plans${creditStr}${C.r}`);
+  row("1", "SIGNAL", "feed customer reality (text·md·vtt)", `npx scriptonia add <files>`);
+  row("2", "PLAN", "issue → PLAN.md, sourced & checked", `npx scriptonia plan "<issue>"`);
   row("3", "BUILD", "your agent executes PLAN.md → PR", `claude "execute PLAN.md"`);
-  row("4", "REFINE", "a note regenerates the plan", `scriptonia comment plan/<slug> "…"`);
+  row("4", "REFINE", "a note regenerates the plan", `npx scriptonia comment plan/<slug> "…"`);
+  row("5", "VERIFY", "PR diff → PASS / WARN / BLOCK", `npx scriptonia verify`);
 
-  console.log(`\n  ${C.b}NEXT${C.r}  ${nextStep(s, plansN, recentPlan, repo, C)}\n`);
+  console.log(`\n  ${C.b}NEXT${C.r}  ${nextStep(s, plansN, recentPlan, repo, C)}`);
+  if (cr && cr.metered !== false && cr.available <= 0) {
+    console.log(`  ${C.w}Out of credits${C.r} ${C.dim}— ${cr.topup}${C.r}`);
+  }
+  console.log("");
 }
 
 function nextStep(s, plansN, recentPlan, repo, C) {
   if (s.total === 0)
-    return `${C.g}scriptonia add feedback.txt call.vtt${C.r}  ${C.dim}— feed the brain customer signal${C.r}`;
+    return `${C.g}npx scriptonia add feedback.txt call.vtt${C.r}  ${C.dim}— feed the brain customer signal${C.r}`;
   if (plansN === 0)
-    return `${C.g}scriptonia plan "the thing you're about to build"${C.r}  ${C.dim}— writes PLAN.md${C.r}`;
-  return `${C.g}claude "execute PLAN.md"${C.r}  ${C.dim}— ship it · or refine: ${C.r}${C.g}scriptonia comment plan/${recentPlan} "…"${C.r}`;
+    return `${C.g}npx scriptonia plan "the thing you're about to build"${C.r}  ${C.dim}— writes PLAN.md${C.r}`;
+  return `${C.g}claude "execute PLAN.md"${C.r}  ${C.dim}— then gate the diff: ${C.r}${C.g}npx scriptonia verify${C.r}`;
 }
 
 // ─────────────────────────────────────────────────────────────
@@ -158,11 +166,11 @@ async function add(args) {
   const items = args.filter((a) => !a.startsWith("--"));
   if (items.length === 0) {
     fail(
-      'usage: scriptonia add <file...>            e.g. scriptonia add slack.txt notes.md call.vtt\n' +
-      '       scriptonia add "Issue #42: …"       inline signal — also analyzed against the brain → context.md\n' +
+      'usage: npx scriptonia add <file...>            e.g. npx scriptonia add slack.txt notes.md call.vtt\n' +
+      '       npx scriptonia add "Issue #42: …"       inline signal — also analyzed against the brain → context.md\n' +
       "       flags: --source slack|ticket|sales_call|voice_note|founder_note|email|notion|github\n" +
       "              --segment enterprise|mid_market|smb|free\n" +
-      "       pipe:  cat thread.txt | scriptonia add -",
+      "       pipe:  cat thread.txt | npx scriptonia add -",
     );
   }
 
@@ -246,12 +254,12 @@ async function add(args) {
         if (cfg.inited) appendLog(cfg.dir, "add", `context.md synthesized (${(q.sources ?? []).length} cited, ${unresolved} contradictions)`);
       }
     } catch { /* analysis is best-effort; the signal is already ingested */ }
-    console.log(`\n  ${C.b}Next:${C.r} ${C.g}scriptonia plan "${items[0].slice(0, 48)}${items[0].length > 48 ? "…" : ""}"${C.r}\n`);
+    console.log(`\n  ${C.b}Next:${C.r} ${C.g}npx scriptonia plan "${items[0].slice(0, 48)}${items[0].length > 48 ? "…" : ""}"${C.r}\n`);
     return;
   }
 
   if (created > 0) {
-    console.log(`  ${C.dim}The brain is enriching them now. Then:${C.r} ${C.g}scriptonia plan "<issue>"${C.r}\n`);
+    console.log(`  ${C.dim}The brain is enriching them now. Then:${C.r} ${C.g}npx scriptonia plan "<issue>"${C.r}\n`);
   }
 }
 
@@ -274,7 +282,7 @@ async function contexts() {
 
   if (o.contexts_count === 0) {
     console.log(`\n  ${C.dim}No contexts yet.${C.r}`);
-    if ((o.signals?.total ?? 0) === 0) console.log(`  Add signal first: ${C.g}scriptonia add <files>${C.r}\n`);
+    if ((o.signals?.total ?? 0) === 0) console.log(`  Add signal first: ${C.g}npx scriptonia add <files>${C.r}\n`);
     else console.log(`  The brain is still indexing ${o.signals.total} signals — check back in a minute.\n`);
     return;
   }
@@ -285,7 +293,7 @@ async function contexts() {
     console.log(`  ${C.g}${String(c.strength).padStart(4)}${C.r}  ${C.b}${c.title}${C.r}  ${C.dim}${c.type} · v${c.version} · ${c.segment}${C.r}${warn}`);
     console.log(`        ${C.v}${cfg.url}/contexts/${c.slug}${C.r}`);
   }
-  console.log(`\n  ${C.dim}Turn any of these into a plan:${C.r} ${C.g}scriptonia plan "<the issue>"${C.r}\n`);
+  console.log(`\n  ${C.dim}Turn any of these into a plan:${C.r} ${C.g}npx scriptonia plan "<the issue>"${C.r}\n`);
 }
 
 // ─────────────────────────────────────────────────────────────
@@ -299,14 +307,14 @@ async function plans() {
   const o = await res.json();
   const list = o.plans ?? [];
   if (list.length === 0) {
-    console.log(`\n  ${C.dim}No plans yet.${C.r}  Generate one: ${C.g}scriptonia plan "<issue>"${C.r}\n`);
+    console.log(`\n  ${C.dim}No plans yet.${C.r}  Generate one: ${C.g}npx scriptonia plan "<issue>"${C.r}\n`);
     return;
   }
   console.log(`\n  ${C.b}${list.length} plan${list.length > 1 ? "s" : ""}${C.r} ${C.dim}· ${o.project}${C.r}\n`);
   for (const p of list) {
     console.log(`  ${C.b}${p.slug}${C.r} ${C.dim}v${p.version}${C.r}`);
     console.log(`     ${C.dim}${p.issue}${C.r}`);
-    console.log(`     ${C.g}scriptonia plan --refresh ${p.slug}${C.r} ${C.dim}·${C.r} ${C.g}scriptonia comment plan/${p.slug} "…"${C.r}`);
+    console.log(`     ${C.g}npx scriptonia plan --refresh ${p.slug}${C.r} ${C.dim}·${C.r} ${C.g}npx scriptonia comment plan/${p.slug} "…"${C.r}`);
   }
   console.log("");
 }
@@ -323,8 +331,8 @@ async function comment(args) {
   const text = positional.slice(1).join(" ").trim();
   if (!target || !text) {
     fail(
-      'usage: scriptonia comment <slug> "<your note>"          comment on a context\n' +
-      '       scriptonia comment plan/<slug> "<your note>"     comment on a plan → regenerates PLAN.md\n' +
+      'usage: npx scriptonia comment <slug> "<your note>"          comment on a context\n' +
+      '       npx scriptonia comment plan/<slug> "<your note>"     comment on a plan → regenerates PLAN.md\n' +
       '       --as "Name"   attribute the comment (defaults to you)',
     );
   }
@@ -339,7 +347,8 @@ async function comment(args) {
       body: JSON.stringify({ slug, body: text, author: flags.as ?? cfg.email }),
     });
     const data = await res.json().catch(() => ({}));
-    if (res.status === 404) fail(`no plan "${slug}" — generate one first: scriptonia plan "<issue>"`);
+    if (res.status === 402) failCredits(data);
+    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)}`);
     // Approval-chain receipt: which human note produced which plan version.
     if (cfg.inited) {
@@ -362,11 +371,12 @@ async function comment(args) {
     body: JSON.stringify({ slug: target, body: text, author: flags.as ?? cfg.email }),
   });
   const data = await res.json().catch(() => ({}));
-  if (res.status === 404) fail(`no context "${target}" — see \`scriptonia contexts\``);
+  if (res.status === 402) failCredits(data);
+  if (res.status === 404) fail(`no context "${target}" — see \`npx scriptonia contexts\``);
   if (!res.ok) fail(`comment failed (${res.status}): ${JSON.stringify(data)}`);
 
   console.log(`\n  ${C.g}✓${C.r} comment posted on ${C.b}${target}${C.r} ${C.dim}(v${data.from_version})${C.r}`);
-  console.log(`  ${C.dim}the brain is absorbing it — it'll bump the version. check:${C.r} ${C.g}scriptonia contexts${C.r}\n`);
+  console.log(`  ${C.dim}the brain is absorbing it — it'll bump the version. check:${C.r} ${C.g}npx scriptonia contexts${C.r}\n`);
 }
 
 // ─────────────────────────────────────────────────────────────
@@ -376,7 +386,7 @@ async function query(args) {
   const cfg = activeCreds();
   const flags = parseFlags(args);
   const q = args.filter((a) => !a.startsWith("--")).join(" ").trim();
-  if (!q) fail('usage: scriptonia query "<topic>" [--window 30d] [--segment enterprise] [--json]');
+  if (!q) fail('usage: npx scriptonia query "<topic>" [--window 30d] [--segment enterprise] [--json]');
 
   const res = await fetch(`${cfg.url}/api/query`, {
     method: "POST",
@@ -384,6 +394,7 @@ async function query(args) {
     body: JSON.stringify({ query: q, window: flags.window, segment: flags.segment }),
   });
   const data = await res.json();
+  if (res.status === 402) failCredits(data);
   if (!res.ok) fail(`query failed (${res.status}): ${JSON.stringify(data)}`);
 
   const wantJson = flags.json !== undefined || !process.stdout.isTTY;
@@ -411,13 +422,66 @@ async function link(args) {
 // ─────────────────────────────────────────────────────────────
 async function status() {
   const cfg = loadConfig();
-  if (!cfg) { console.log("not logged in — run `scriptonia login`"); return; }
+  if (!cfg) { console.log("not logged in — run `npx scriptonia login`"); return; }
+  const active = activeCreds();
+  const C = colors();
   console.log(`signed in as ${cfg.email}`);
-  console.log(`project      ${cfg.project}`);
+  console.log(`project      ${active.project}`);
+  const c = await fetchCredits(active);
+  if (c && c.metered !== false) {
+    const bar = creditBar(c.used, c.cap, C);
+    console.log(`plan         ${C.b}${c.plan}${C.r}`);
+    console.log(`credits      ${bar} ${c.used}/${c.cap} used · resets ${c.resets_at}`);
+    if (c.available <= 0) console.log(`             ${C.w}out of credits${C.r} — ${c.topup}`);
+    else if (c.available <= Math.max(2, Math.round(c.cap * 0.2))) console.log(`             ${C.dim}running low — ${c.topup}${C.r}`);
+  }
   console.log(`endpoint     ${cfg.url}`);
   console.log(`config       ${CONFIG_PATH}`);
 }
 
+// ── credits ───────────────────────────────────────────────────
+async function credits() {
+  const cfg = activeCreds();
+  const C = colors();
+  const c = await fetchCredits(cfg);
+  if (!c) fail("could not load credits");
+  if (c.metered === false) { console.log(`\n  ${C.dim}This project isn't metered.${C.r}\n`); return; }
+  console.log(`\n  ${C.b}${c.plan.toUpperCase()}${C.r} · ${cfg.project}`);
+  console.log(`  ${creditBar(c.used, c.cap, C)}  ${C.b}${c.available}${C.r} of ${c.cap} credits left ${C.dim}(resets ${c.resets_at})${C.r}`);
+  console.log(`\n  ${C.dim}Plans, comments & verification cost 5 · queries 1 · adding signal is free.${C.r}`);
+  if (c.available <= 0) console.log(`  ${C.w}Out of credits.${C.r} ${c.topup}`);
+  else console.log(`  ${C.dim}Need more? ${c.topup}${C.r}`);
+  console.log("");
+}
+
+async function fetchCredits(cfg) {
+  try {
+    const res = await fetch(`${cfg.url}/api/credits`, { headers: { authorization: `Bearer ${cfg.token}` } });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch { return null; }
+}
+
+function creditBar(used, cap, C) {
+  const width = 16;
+  const frac = cap > 0 ? Math.min(1, used / cap) : 0;
+  const filled = Math.round(frac * width);
+  const color = frac >= 1 ? C.w : frac >= 0.8 ? C.w : C.g;
+  return `${color}${"█".repeat(filled)}${C.dim}${"░".repeat(width - filled)}${C.r}`;
+}
+
+/** Render an HTTP 402 credits_exhausted body and exit. Shared by plan/query/comment. */
+function failCredits(data) {
+  const C = colors();
+  const resets = data.resets_at ? ` (resets ${data.resets_at})` : "";
+  console.error(`\n  ${C.w}✕ Out of credits${C.r} — ${data.plan}: ${data.used}/${data.cap} used this month${resets}.\n`);
+  console.error(`    Your signal is safe and still being collected. Plans & queries resume`);
+  console.error(`    when credits do.\n`);
+  console.error(`    ${C.b}Top up:${C.r} ${data.topup}`);
+  console.error(`    ${C.dim}(adding signal, sync, contexts, plans list — all still free)${C.r}\n`);
+  process.exit(1);
+}
+
 async function logout() {
   if (fs.existsSync(CONFIG_PATH)) fs.rmSync(CONFIG_PATH);
   console.log("logged out.");
@@ -443,7 +507,7 @@ function skillMarkdown() {
 name: scriptonia
 description: >
   BEFORE building any user-facing change — a feature, a bug fix, a refactor with
-  UX impact — run \`scriptonia plan "<the issue>"\`. It writes PLAN.md here: a
+  UX impact — run \`npx scriptonia plan "<the issue>"\`. It writes PLAN.md here: a
   hyper-focused, sourced, executable plan grounded in this project's real
   customer signal, prior decisions, and human comments. Execute PLAN.md exactly.
 ---
@@ -452,18 +516,20 @@ description: >
 
 When asked to build/fix anything user-facing:
 
-1. Run \`scriptonia plan "<the issue>"\` — it writes **PLAN.md** in the repo.
+1. Run \`npx scriptonia plan "<the issue>"\` — it writes **PLAN.md** in the repo.
 2. Execute PLAN.md **exactly**. Respect its **Non-goals** — do not add anything
    outside the acceptance criteria.
 3. If a constraint is marked **UNRESOLVED**, STOP and surface it to the human.
-4. Your PR description must cite the \`sources\` signal ids from PLAN.md.
+4. Run \`npx scriptonia verify\` after implementation. Fix every BLOCK before
+   merge and preserve the generated regression case.
+5. Your PR description must cite the \`sources\` signal ids from PLAN.md.
 
 If a plan step conflicts with what you find in the code, run
-\`scriptonia comment plan/<slug> "<what you found>"\` and re-read the regenerated PLAN.md.
+\`npx scriptonia comment plan/<slug> "<what you found>"\` and re-read the regenerated PLAN.md.
 
-To just look something up without a full plan: \`scriptonia query "<topic>"\`
+To just look something up without a full plan: \`npx scriptonia query "<topic>"\`
 (JSON: requirements with source_ids, contradictions, edge_cases). Quote a
-customer verbatim with \`scriptonia link "<signal_id>"\`.
+customer verbatim with \`npx scriptonia link "<signal_id>"\`.
 
 Rule: never invent demand. If nothing in the plan/query supports a step, it
 doesn't belong in the PR.
@@ -526,7 +592,7 @@ function loadConfig() {
 }
 function requireConfig() {
   const cfg = loadConfig();
-  if (!cfg) fail("not logged in — run `scriptonia login`");
+  if (!cfg) fail("not logged in — run `npx scriptonia login`");
   return cfg;
 }
 function saveConfig(cfg) {
@@ -600,29 +666,37 @@ function usage() {
   console.log(`scriptonia — issue → executable plan for your coding agent
 
   THE LOOP
-    1 SIGNAL   scriptonia add <files>              feed customer reality (text · md · vtt)
-    2 PLAN     scriptonia plan "<issue>"           → PLAN.md: sourced, contradiction-checked
+    1 SIGNAL   npx scriptonia add <files>              feed customer reality (text · md · vtt)
+    2 PLAN     npx scriptonia plan "<issue>"           → PLAN.md: sourced, contradiction-checked
     3 BUILD    claude "execute PLAN.md"            your agent ships it → PR
-    4 REFINE   scriptonia comment plan/<slug> "…"  a note regenerates the plan
+    4 REFINE   npx scriptonia comment plan/<slug> "…"  a note regenerates the plan
 
   SETUP
-    scriptonia login              sign in (browser) — wires your agent, no keys
-    scriptonia init               [per repo] give this repo its own brain + AGENTS.md
+    npx scriptonia login              sign in (browser) — wires your agent, no keys
+    npx scriptonia init               [per repo] give this repo its own brain + AGENTS.md
 
   SIGNAL & PLANS
-    scriptonia add <file...>      ingest files  (--source, --segment; or  cat x | scriptonia add -)
-    scriptonia plan "<issue>"     generate PLAN.md  (--out <file>, --refresh <slug>)
-    scriptonia plans              list your plans (and their slugs)
-    scriptonia comment plan/<slug> "…"   refine a plan → regenerates PLAN.md
+    npx scriptonia add <file...>      ingest files  (--source, --segment; or  cat x | npx scriptonia add -)
+    npx scriptonia plan "<issue>"     generate PLAN.md  (--out <file>, --refresh <slug>)
+    npx scriptonia plans              list your plans (and their slugs)
+    npx scriptonia comment plan/<slug> "…"   refine a plan → regenerates PLAN.md
+    npx scriptonia verify             check the git diff against PLAN.md
 
   INSPECT
-    scriptonia                    the loop + what's next
-    scriptonia contexts           what the brain learned from your signal
-    scriptonia query "<topic>"    quick lookup, no full plan  (--json)
-    scriptonia link "<id>"        a signal's full text
-    scriptonia sync               write the brain to local files
-
-  ACCOUNT   scriptonia status | logout | skill | mcp
+    npx scriptonia                the loop + what's next
+    npx scriptonia contexts           what the brain learned from your signal
+    npx scriptonia query "<topic>"    quick lookup, no full plan  (--json)
+    npx scriptonia link "<id>"    a signal's full text
+    npx scriptonia sync               write the brain to local files
+    npx scriptonia credits            plan, balance, reset date
+
+  VERIFY
+    npx scriptonia verify [--plan PLAN.md] [--base origin/main] [--diff patch.txt]
+                      [--skip-checks] [--out .scriptonia/evals/<case>.yaml]
+    Exit 0: PASS/WARN · Exit 1: BLOCK or operational failure
+
+  ACCOUNT   npx scriptonia status | npx scriptonia logout | npx scriptonia skill | npx scriptonia mcp
+  Plans, comments & verification cost 5 credits · queries 1 · adding signal is free.
 `);
 }
 
@@ -633,7 +707,7 @@ function usage() {
 /** Repo-local project when pwd is inside an initialized repo, else the global login. */
 function activeCreds() {
   const g = loadConfig();
-  if (!g) fail("run `scriptonia login` first");
+  if (!g) fail("run `npx scriptonia login` first");
   const proj = findProjectForCwd();
   if (proj) {
     // v0.6 brains are flat (REPO.md etc. at the project dir root); older ones
@@ -672,7 +746,7 @@ function findProjectForCwd() {
 async function init(args) {
   const flags = parseFlags(args);
   const g = loadConfig();
-  if (!g) fail("run `scriptonia login` first, then `scriptonia init` in your repo");
+  if (!g) fail("run `npx scriptonia login` first, then `npx scriptonia init` in your repo");
   const C = colors();
   const cwd = process.cwd();
 
@@ -680,8 +754,8 @@ async function init(args) {
   if (existing && !flags.force) {
     writeRepoMd(existing.dir, scanRepo(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}scriptonia init --force${C.r}`);
-    console.log(`  ${C.dim}next:${C.r} ${C.g}scriptonia add <files>${C.r}\n`);
+    console.log(`  ${C.dim}re-scan from scratch:${C.r} ${C.g}npx scriptonia init --force${C.r}`);
+    console.log(`  ${C.dim}next:${C.r} ${C.g}npx scriptonia add <files>${C.r}\n`);
     return;
   }
 
@@ -701,7 +775,7 @@ async function init(args) {
       headers: { authorization: `Bearer ${g.token}`, "content-type": "application/json" },
       body: JSON.stringify({ name }),
     });
-    if (!res.ok) fail(`could not create project (${res.status}) — is your login valid? try \`scriptonia login\``);
+    if (!res.ok) fail(`could not create project (${res.status}) — is your login valid? try \`npx scriptonia login\``);
     const data = await res.json();
     projectId = data.projectId; token = data.token;
   }
@@ -736,15 +810,15 @@ async function init(args) {
   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}`);
   console.log(`\n  ${C.b}Feed it customer signal, then turn an issue into a plan:${C.r}\n`);
-  console.log(`    ${C.g}scriptonia add${C.r} feedback.txt call.vtt   ${C.dim}(or:  scriptonia add "Issue #42: …")${C.r}`);
-  console.log(`    ${C.g}scriptonia plan${C.r} "the issue you want to build"\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`);
 }
 
 // ── sync ──────────────────────────────────────────────────────
 async function sync() {
   const cfg = activeCreds();
   const C = colors();
-  if (!cfg.inited) fail("run `scriptonia init` in this repo first");
+  if (!cfg.inited) fail("run `npx scriptonia init` in this repo first");
   const res = await fetch(`${cfg.url}/api/brain`, { headers: { authorization: `Bearer ${cfg.token}` } });
   if (!res.ok) fail(`sync failed (${res.status})`);
   const brain = await res.json();
@@ -785,7 +859,7 @@ async function plan(args) {
   }
 
   const issue = args.filter((a) => !a.startsWith("--")).join(" ").trim();
-  if (!issue) fail('usage: scriptonia plan "<the issue>"   [--out PLAN.md] [--refresh <slug>]');
+  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)
@@ -798,10 +872,17 @@ async function plan(args) {
     body: JSON.stringify({ issue, repo_summary: repoSummary }),
   });
   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);
 }
 
+// ── verify — PLAN.md + git diff → separate CI gates ──────────────────
+async function verify(args) {
+  const result = await runVerification(args, { cfg: activeCreds(), cwd: process.cwd() });
+  process.exitCode = result.exitCode;
+}
+
 function writePlan(cfg, data, flags) {
   const C = colors();
   const out = flags.out ?? "PLAN.md";
@@ -817,7 +898,13 @@ function writePlan(cfg, data, flags) {
   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}`);
   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}scriptonia comment plan/${data.slug} "…"${C.r} ${C.dim}(rewrites PLAN.md)${C.r}\n`);
+  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) {
+    const cr = data.credits;
+    const low = cr.cap > 0 && cr.cap - cr.used <= Math.max(2, Math.round(cr.cap * 0.2));
+    console.log(`  ${low ? C.w : C.dim}${cr.used}/${cr.cap} credits used this month${low ? " — top up: sathwik07@scriptonia.dev" : ""}${C.r}`);
+  }
+  console.log("");
 }
 
 // ── repo scan ─────────────────────────────────────────────────
@@ -902,7 +989,7 @@ function writeProjectMd(dir, scan, pitch) {
     "",
     `# ${scan.name}`,
     "",
-    pitch ? `> ${pitch}` : (scan.pkgDescription ? `> ${scan.pkgDescription}` : "> (describe this product with `scriptonia init --force`)"),
+    pitch ? `> ${pitch}` : (scan.pkgDescription ? `> ${scan.pkgDescription}` : "> (describe this product with `npx scriptonia init --force`)"),
     "",
     `**Stack:** ${scan.stack}`,
     scan.deps.length ? `**Key deps:** ${scan.deps.join(", ")}` : "",
@@ -911,7 +998,7 @@ function writeProjectMd(dir, scan, pitch) {
     scan.readmeHead ? "## From the README\n\n" + scan.readmeHead : "",
     "",
     "---",
-    "*The product brain. Signal receipts in `signals/`, constraints in `rules/`, enriched contexts in `contexts/`, live synthesis in `context.md`, live plan in `plan.md`. Generated by `scriptonia init`.*",
+    "*The product brain. Signal receipts in `signals/`, constraints in `rules/`, enriched contexts in `contexts/`, live synthesis in `context.md`, live plan in `plan.md`. Generated by `npx scriptonia init`.*",
   ].filter((l) => l !== "" && l !== null).join("\n");
   fs.writeFileSync(path.join(dir, "PROJECT.md"), md);
 }
@@ -938,25 +1025,27 @@ function writeAgentsBrainMd(dir, meta, decisions) {
     "",
     "## 1. Identity",
     "",
-    meta.pitch ? `${meta.pitch}` : "(run `scriptonia init --force` to describe this product)",
+    meta.pitch ? `${meta.pitch}` : "(run `npx scriptonia init --force` to describe this product)",
     meta.stack ? `\nStack: ${meta.stack}` : "",
     "",
     "## 2. Workflow — non-negotiable",
     "",
-    '1. Before building any user-facing change, run `scriptonia plan "<the issue>"`.',
+    '1. 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",
     "   build past it.",
     "3. Any constraint marked **⚠ UNRESOLVED** is an approval gate: STOP and get a",
-    '   human comment (`scriptonia comment plan/<slug> "…"`) before writing code.',
+    '   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",
+    "   before merge and preserve the generated `.scriptonia/evals/*.yaml` case.",
     "",
     "## 3. Non-negotiable constraints (from the decisions corpus)",
     "",
   ];
   if (decisions.length === 0) {
-    L.push("_None synced yet — run `scriptonia sync` after decisions exist. The server_", "_still enforces them during `plan` regardless._");
+    L.push("_None synced yet — run `npx scriptonia sync` after decisions exist. The server_", "_still enforces them during `plan` regardless._");
   } else {
     for (const d of decisions) {
       L.push(`### ${d.title}${d.ref ? ` (${d.ref})` : ""}`, "", d.body, "");
@@ -987,7 +1076,7 @@ function renderRule(d) {
     "check: |",
     ...String(d.body).split("\n").map((l) => `  ${l}`),
     "enforcement: |",
-    "  Server-side during `scriptonia plan`: any issue conflicting with this rule",
+    "  Server-side during `npx scriptonia plan`: any issue conflicting with this rule",
     "  is marked ⚠ UNRESOLVED in PLAN.md until a human comment approves the",
     "  override (recorded in comments/plan/<slug>/).",
     "---",
@@ -1027,7 +1116,7 @@ function renderContextLive(issue, q, project, signalId) {
   if (cons.length) {
     L.push("## ⚠ CONTRADICTION GATE — UNRESOLVED");
     for (const c of cons) L.push(`- ${c.detail} (${c.decision_ref})`);
-    L.push("", "**STATUS: ⚠ UNRESOLVED.** A human must approve the override before any plan", "built on this context is executed. `scriptonia plan` will carry this gate.", "");
+    L.push("", "**STATUS: ⚠ UNRESOLVED.** A human must approve the override before any plan", "built on this context is executed. `npx scriptonia plan` will carry this gate.", "");
   } else {
     L.push("## Contradiction gate", "", "✓ No conflicts with prior decisions on record.", "");
   }
@@ -1042,7 +1131,7 @@ function renderContextLive(issue, q, project, signalId) {
   for (const s of q.sources ?? []) {
     L.push(`- \`sig_${s.signal_id.slice(0, 8)}\` ${s.source}${s.ref ? ` — ${s.ref}` : ""} _(similarity ${s.similarity})_`);
   }
-  L.push("", "---", `*Next: \`scriptonia plan "${issue.slice(0, 60)}${issue.length > 60 ? "…" : ""}"\` → PLAN.md.*`);
+  L.push("", "---", `*Next: \`npx scriptonia plan "${issue.slice(0, 60)}${issue.length > 60 ? "…" : ""}"\` → PLAN.md.*`);
   return L.join("\n");
 }
 
@@ -1071,7 +1160,7 @@ function buildRepoMd(scan) {
     scan.tree,
     "```",
     "",
-    "*When you name files in a plan, use paths from this tree. Refresh with `scriptonia init --force`.*",
+    "*When you name files in a plan, use paths from this tree. Refresh with `npx scriptonia init --force`.*",
   ].filter(Boolean).join("\n");
 }
 
@@ -1093,13 +1182,15 @@ function injectAgentsMd(cwd) {
 This repo has a product brain (customer signal + prior decisions). Before building
 any user-facing change:
 
-- \`scriptonia plan "<the issue>"\` → writes **PLAN.md** here. Execute PLAN.md
+- \`npx scriptonia plan "<the issue>"\` → writes **PLAN.md** here. Execute PLAN.md
   exactly; respect its **Non-goals**; cite its \`sources\` ids in your PR.
-- \`scriptonia query "<topic>"\` → JSON: what customers asked for, contradictions,
+- \`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
-  conflicts with the code, \`scriptonia comment plan/<slug> "<what you found>"\`
+  conflicts with the code, \`npx scriptonia comment plan/<slug> "<what you found>"\`
   and re-read PLAN.md.
+- After implementation, run \`npx scriptonia verify\`. Fix every BLOCK before
+  merge; keep the generated \`.scriptonia/evals/*.yaml\` regression case.
 ${END}`;
 
   let existing = "";

package/bin/verify.mjs

@@ -0,0 +1,266 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+
+const RANK = { PASS: 0, WARN: 1, BLOCK: 2 };
+const CHECK_SCRIPTS = ["test", "build", "lint", "typecheck", "type-check"];
+
+export async function runVerification(args, { cfg, cwd = process.cwd(), fetchImpl = fetch } = {}) {
+  if (!cfg?.url || !cfg?.token) throw new Error("run `npx scriptonia login` first");
+  const flags = parseFlags(args);
+  const planPath = path.resolve(cwd, flags.plan ?? "PLAN.md");
+  if (!fs.existsSync(planPath)) throw new Error(`PLAN.md not found at ${planPath} (use --plan <file>)`);
+
+  const plan = fs.readFileSync(planPath, "utf8");
+  const meta = parsePlanMetadata(plan, planPath);
+  const { diff, files, source } = collectDiff(cwd, flags);
+  if (!diff.trim()) throw new Error("no git diff to verify (use --base <ref> or --diff <file>)");
+
+  const diffForJudge = diff.length > 290_000
+    ? `${diff.slice(0, 290_000)}\n\n[diff truncated by CLI; verdicts requiring omitted evidence must WARN]`
+    : diff;
+  const semanticPromise = fetchImpl(`${cfg.url}/api/verify`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${cfg.token}`, "content-type": "application/json" },
+    body: JSON.stringify({ plan, diff: diffForJudge }),
+  });
+  const repositoryChecks = flags["skip-checks"] ? skippedRepositoryGate() : runRepositoryChecks(cwd, files);
+  const unresolvedConstraints = buildUnresolvedGate(plan);
+  const testCoverage = buildTestCoverageGate(files);
+
+  const response = await semanticPromise;
+  const semantic = await response.json().catch(() => ({}));
+  if (!response.ok) throw new Error(`verification service failed (${response.status}): ${JSON.stringify(semantic).slice(0, 240)}`);
+  for (const name of ["acceptance_criteria", "non_goals", "product_decisions"]) {
+    const result = semantic[name];
+    if (!result || !(result.verdict in RANK) || !Array.isArray(result.checks)) {
+      throw new Error(`verification service returned an invalid ${name} gate`);
+    }
+  }
+
+  const gates = {
+    acceptance_criteria: semantic.acceptance_criteria,
+    non_goals: semantic.non_goals,
+    product_decisions: semantic.product_decisions,
+    unresolved_constraints: unresolvedConstraints,
+    repository_checks: repositoryChecks,
+    test_coverage: testCoverage,
+  };
+  const verdict = worstVerdict(Object.values(gates).map((gate) => gate.verdict));
+  const evalPath = path.resolve(cwd, flags.out ?? path.join(".scriptonia", "evals", `${meta.slug}.yaml`));
+  fs.mkdirSync(path.dirname(evalPath), { recursive: true });
+  fs.writeFileSync(evalPath, renderEvalYaml({
+    id: meta.slug,
+    plan: path.relative(cwd, planPath) || path.basename(planPath),
+    planVersion: meta.version,
+    diffSource: source,
+    diffSha256: createHash("sha256").update(diff).digest("hex"),
+    verdict,
+    gates,
+  }));
+
+  printResult({ verdict, gates, evalPath, cwd });
+  return { verdict, exitCode: verdict === "BLOCK" ? 1 : 0, evalPath, gates };
+}
+
+export function parsePlanMetadata(plan, planPath = "PLAN.md") {
+  const frontmatter = plan.match(/^---\s*\n([\s\S]*?)\n---/m)?.[1] ?? "";
+  const value = (key) => frontmatter.match(new RegExp(`^${key}:\\s*(.+)$`, "m"))?.[1]?.trim().replace(/^['"]|['"]$/g, "");
+  const slug = value("plan") || slugify(plan.match(/^#\s+(.+)$/m)?.[1] || path.basename(planPath, path.extname(planPath)));
+  return { slug: slugify(slug), version: Number(value("version") || 1) };
+}
+
+export function buildUnresolvedGate(plan) {
+  const matches = plan.split("\n").filter((line) => /(?:⚠\s*)?UNRESOLVED/i.test(line));
+  const blocked = matches.length > 0;
+  return gate(blocked ? "BLOCK" : "PASS", {
+    evidence: blocked ? matches.slice(0, 6) : ["No UNRESOLVED marker appears in PLAN.md."],
+    plan_criterion: "Every unresolved constraint requires human approval before implementation.",
+    citation: decisionCitation(matches.join(" ")),
+    reason: blocked ? "PLAN.md still contains an unresolved approval gate." : "No unresolved approval gate remains in the approved plan.",
+  });
+}
+
+export function buildTestCoverageGate(files) {
+  const tests = files.filter(isTestFile);
+  const behavior = files.filter((file) => isSourceFile(file) && !isTestFile(file));
+  if (tests.length) return gate("PASS", {
+    evidence: tests,
+    plan_criterion: "Add or update tests for changed product behavior.",
+    citation: "PLAN.md test plan",
+    reason: "The diff includes test changes that a reviewer can inspect.",
+  });
+  if (behavior.length) return gate("BLOCK", {
+    evidence: behavior.slice(0, 8),
+    plan_criterion: "Add or update tests for changed product behavior.",
+    citation: "PLAN.md test plan",
+    reason: "Product code changed without any test file added or updated.",
+  });
+  return gate("PASS", {
+    evidence: files.length ? files.slice(0, 8) : ["No changed source files."],
+    plan_criterion: "Add or update tests for changed product behavior.",
+    citation: "PLAN.md test plan",
+    reason: "The diff contains no product-code change requiring test coverage.",
+  });
+}
+
+function runRepositoryChecks(cwd, files) {
+  const checks = [];
+  for (const root of relevantPackageRoots(cwd, files)) {
+    let pkg;
+    try { pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")); } catch { continue; }
+    const manager = packageManager(root);
+    const seen = new Set();
+    for (const name of CHECK_SCRIPTS) {
+      if (!pkg.scripts?.[name] || seen.has(pkg.scripts[name])) continue;
+      seen.add(pkg.scripts[name]);
+      const command = manager === "yarn" ? ["yarn", name] : manager === "pnpm" ? ["pnpm", "run", name] : manager === "bun" ? ["bun", "run", name] : ["npm", "run", name];
+      const result = spawnSync(command[0], command.slice(1), { cwd: root, encoding: "utf8", timeout: 300_000, maxBuffer: 2_000_000, env: { ...process.env, CI: "1" } });
+      const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`.trim();
+      checks.push({ name, command: command.join(" "), root: path.relative(cwd, root) || ".", ok: result.status === 0, output: output.slice(-1200) || `(exit ${result.status ?? "unknown"})` });
+    }
+  }
+  if (!checks.length) return gate("WARN", {
+    evidence: ["No test, build, lint, or type-check script was found for the changed packages."],
+    plan_criterion: "Run the repository's existing quality checks.",
+    citation: "repository package scripts",
+    reason: "There were no recognized repository checks to run automatically.",
+  });
+  const failed = checks.filter((check) => !check.ok);
+  return {
+    verdict: failed.length ? "BLOCK" : "PASS",
+    checks: checks.map((check) => ({
+      verdict: check.ok ? "PASS" : "BLOCK",
+      evidence: [`${check.root}: ${check.command}`, check.output],
+      plan_criterion: "Run the repository's existing quality checks.",
+      citation: "repository package scripts",
+      reason: check.ok ? `${check.name} completed successfully.` : `${check.name} failed and must be fixed before merge.`,
+    })),
+  };
+}
+
+function skippedRepositoryGate() {
+  return gate("WARN", {
+    evidence: ["Repository checks skipped with --skip-checks."],
+    plan_criterion: "Run the repository's existing quality checks.",
+    citation: "CLI flag",
+    reason: "CI should run the repository checks separately before merge.",
+  });
+}
+
+function relevantPackageRoots(cwd, files) {
+  const candidates = [];
+  if (fs.existsSync(path.join(cwd, "package.json"))) candidates.push(cwd);
+  for (const entry of fs.readdirSync(cwd, { withFileTypes: true })) {
+    if (entry.isDirectory() && !entry.name.startsWith(".") && fs.existsSync(path.join(cwd, entry.name, "package.json"))) candidates.push(path.join(cwd, entry.name));
+  }
+  const relevant = candidates.filter((root) => {
+    const prefix = path.relative(cwd, root);
+    return !prefix || files.some((file) => file === prefix || file.startsWith(prefix + "/"));
+  });
+  return relevant.length ? relevant : candidates.length === 1 ? candidates : [];
+}
+
+function packageManager(root) {
+  if (fs.existsSync(path.join(root, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs.existsSync(path.join(root, "yarn.lock"))) return "yarn";
+  if (fs.existsSync(path.join(root, "bun.lockb")) || fs.existsSync(path.join(root, "bun.lock"))) return "bun";
+  return "npm";
+}
+
+function collectDiff(cwd, flags) {
+  if (flags.diff) {
+    const file = path.resolve(cwd, flags.diff);
+    const diff = fs.readFileSync(file, "utf8");
+    return { diff, files: diffFiles(diff), source: `file:${path.relative(cwd, file)}` };
+  }
+  const base = flags.base || (process.env.GITHUB_BASE_REF ? `origin/${process.env.GITHUB_BASE_REF}` : null);
+  const range = base ? `${base}...HEAD` : "HEAD";
+  const result = spawnSync("git", ["diff", range, "--no-ext-diff", "--unified=40"], { cwd, encoding: "utf8", maxBuffer: 20_000_000 });
+  if (result.status !== 0) throw new Error(`could not read git diff for ${range}: ${(result.stderr || "").trim()}`);
+  let diff = result.stdout || "";
+  if (!base) diff += untrackedDiff(cwd);
+  return { diff, files: diffFiles(diff), source: `git:${range}` };
+}
+
+function untrackedDiff(cwd) {
+  const status = spawnSync("git", ["status", "--porcelain", "--untracked-files=all"], { cwd, encoding: "utf8" });
+  if (status.status !== 0) return "";
+  const files = status.stdout.split("\n").filter((line) => line.startsWith("?? ")).map((line) => line.slice(3));
+  const chunks = [];
+  for (const file of files) {
+    const full = path.join(cwd, file);
+    try {
+      const stat = fs.statSync(full);
+      if (!stat.isFile() || stat.size > 500_000) continue;
+      const body = fs.readFileSync(full, "utf8");
+      chunks.push(`\ndiff --git a/${file} b/${file}\nnew file mode 100644\n--- /dev/null\n+++ b/${file}\n@@ -0,0 +1,${body.split("\n").length} @@\n${body.split("\n").map((line) => `+${line}`).join("\n")}\n`);
+    } catch { /* ignore unreadable/binary untracked files */ }
+  }
+  return chunks.join("");
+}
+
+function diffFiles(diff) {
+  return [...new Set([...diff.matchAll(/^diff --git a\/(.+?) b\/(.+)$/gm)].map((match) => match[2]))];
+}
+
+function isTestFile(file) {
+  return /(^|\/)(?:__tests__|tests?|spec)(?:\/|$)|\.(?:test|spec)\.[^.]+$/i.test(file);
+}
+
+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 gate(verdict, check) {
+  return { verdict, checks: [{ verdict, ...check }] };
+}
+
+function worstVerdict(verdicts) {
+  return verdicts.reduce((worst, verdict) => (RANK[verdict] > RANK[worst] ? verdict : worst), "PASS");
+}
+
+function decisionCitation(text) {
+  return text.match(/(?:decision|dec)[-_:/ ]?[a-z0-9_-]+/i)?.[0] || "PLAN.md constraint";
+}
+
+function renderEvalYaml(data) {
+  const q = (value) => JSON.stringify(String(value ?? ""));
+  const lines = ["version: 1", `id: ${q(data.id)}`, `plan: ${q(data.plan)}`, `plan_version: ${data.planVersion}`, `diff_source: ${q(data.diffSource)}`, `diff_sha256: ${q(data.diffSha256)}`, `generated_at: ${q(new Date().toISOString())}`, `verdict: ${data.verdict}`, "gates:"];
+  for (const [name, gateResult] of Object.entries(data.gates)) {
+    lines.push(`  ${name}:`, `    verdict: ${gateResult.verdict}`, "    checks:");
+    for (const check of gateResult.checks ?? []) {
+      lines.push(`      - verdict: ${check.verdict}`, `        plan_criterion: ${q(check.plan_criterion)}`, `        citation: ${q(check.citation)}`, `        reason: ${q(check.reason)}`, "        evidence:");
+      for (const evidence of check.evidence ?? []) lines.push(`          - ${q(String(evidence).slice(0, 1600))}`);
+    }
+  }
+  return lines.join("\n") + "\n";
+}
+
+function printResult({ verdict, gates, evalPath, cwd }) {
+  const icon = verdict === "PASS" ? "✓" : verdict === "WARN" ? "!" : "✕";
+  console.log(`\n  ${icon} SCRIPTONIA VERIFY · ${verdict}\n`);
+  for (const [name, result] of Object.entries(gates)) {
+    console.log(`  ${result.verdict.padEnd(5)}  ${name.replaceAll("_", " ")}`);
+    for (const check of (result.checks ?? []).filter((item) => item.verdict !== "PASS").slice(0, 3)) console.log(`         ${check.reason}`);
+  }
+  console.log(`\n  case   ${path.relative(cwd, evalPath)}`);
+  console.log(`  exit   ${verdict === "BLOCK" ? 1 : 0}\n`);
+}
+
+function parseFlags(args) {
+  const out = {};
+  for (let i = 0; i < args.length; i++) {
+    if (!args[i].startsWith("--")) continue;
+    const [name, inline] = args[i].slice(2).split(/=(.*)/s);
+    if (inline !== undefined) out[name] = inline;
+    else if (args[i + 1] && !args[i + 1].startsWith("--")) out[name] = args[++i];
+    else out[name] = true;
+  }
+  return out;
+}
+
+function slugify(value) {
+  return String(value).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "").slice(0, 80) || "plan";
+}

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "scriptonia",
-  "version": "0.6.0",
-  "description": "Turn customer signal into executable plans your coding agent runs. Issue in, PLAN.md out.",
+  "version": "0.8.0",
+  "description": "Turn customer signal into plans and merge-blocking verification for AI-written PRs.",
   "type": "module",
   "bin": {
     "scriptonia": "bin/scriptonia.mjs"
   },
+  "scripts": {
+    "test": "node --test"
+  },
   "files": [
     "bin",
     "README.md"