scriptonia 0.7.0 → 0.9.0-rc.1

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,28 @@ 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` | Freeze the Git/product-memory snapshot and consume declared CI/JUnit/static evidence. It never executes repository commands. |
 
 ## 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
+capture   run -- <agent-command>      capture exactly the command supplied
+          runs | run show <id>        inspect captured agent sessions
+verify    diff-check [--base <ref>]   sub-second deterministic policy pass
+          verify [--base <ref>]       complete evidence report
+          gate [--base <ref>]         CI-compatible aggregate exit status
+learn     learn <finding-id>          confirmed finding → draft eval
+          eval run [id] | eval doctor run and maintain regression cases
+memory    decide | pulse | why | recall local-first product/codebase memory
 inspect   scriptonia                the loop + what's next
           contexts | query "<topic>" | link "<id>" | sync
 account   status | logout | skill | mcp
@@ -52,10 +61,14 @@ 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. V2 policies, eval definitions, and operational brain data are
+local-first. Deterministic verification does not upload the codebase. When
+semantic evaluation is explicitly enabled, only the bounded evidence bundle is
+sent through the authenticated Scriptonia gateway.
 
 Skip `init` if you have one product — `login → add → plan` uses your default
 brain and scans whatever repo you run `plan` in.
@@ -71,4 +84,5 @@ 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 24 LTS
+is the V2 release baseline; Node 22 remains in the compatibility matrix.

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,7 +31,7 @@ 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, credits, logout, skill: reinstallSkill, mcp,
   flow, guide: flow,
@@ -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,7 +128,7 @@ 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 : ""}`);
@@ -135,10 +136,11 @@ async function flow() {
   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)", `scriptonia add <files>`);
-  row("2", "PLAN", "issue → PLAN.md, sourced & checked", `scriptonia plan "<issue>"`);
+  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)}`);
   if (cr && cr.metered !== false && cr.available <= 0) {
@@ -149,10 +151,10 @@ async function flow() {
 
 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}`;
 }
 
 // ─────────────────────────────────────────────────────────────
@@ -164,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 -",
     );
   }
 
@@ -252,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`);
   }
 }
 
@@ -280,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;
   }
@@ -291,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`);
 }
 
 // ─────────────────────────────────────────────────────────────
@@ -305,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("");
 }
@@ -329,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)',
     );
   }
@@ -346,7 +348,7 @@ async function comment(args) {
     });
     const data = await res.json().catch(() => ({}));
     if (res.status === 402) failCredits(data);
-    if (res.status === 404) fail(`no plan "${slug}" — generate one first: scriptonia plan "<issue>"`);
+    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) {
@@ -370,11 +372,11 @@ async function comment(args) {
   });
   const data = await res.json().catch(() => ({}));
   if (res.status === 402) failCredits(data);
-  if (res.status === 404) fail(`no context "${target}" — see \`scriptonia contexts\``);
+  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`);
 }
 
 // ─────────────────────────────────────────────────────────────
@@ -384,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",
@@ -420,7 +422,7 @@ 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}`);
@@ -446,7 +448,7 @@ async function 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 cost 5 · queries 1 · adding signal is free.${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("");
@@ -505,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.
 ---
@@ -514,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.
@@ -588,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) {
@@ -662,31 +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
-    scriptonia credits            plan, balance, reset date
-
-  ACCOUNT   scriptonia status | logout | skill | mcp
-  Plans & comments cost 5 credits · queries 1 · adding signal is free.
+    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.
 `);
 }
 
@@ -697,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
@@ -736,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();
 
@@ -744,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;
   }
 
@@ -765,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;
   }
@@ -800,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();
@@ -849,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)
@@ -867,6 +877,12 @@ async function plan(args) {
   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";
@@ -882,7 +898,7 @@ 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}`);
+  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));
@@ -973,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(", ")}` : "",
@@ -982,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);
 }
@@ -1009,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, "");
@@ -1058,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>/).",
     "---",
@@ -1098,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.", "");
   }
@@ -1113,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");
 }
 
@@ -1142,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");
 }
 
@@ -1164,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 = "";