naive-framework 0.0.0-stage → 0.2.0

package/interface/cli/mentura.mjs

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+// The command line over the router (EE-030). Same routes and gates as the MCP server and the API.
+//
+//   mentura routes [--group <phase>] [--json]       the route table, or one route group
+//   mentura groups [--json]                         route groups: the routes each phase needs
+//   mentura ventures [--json]                       ventures in the workspace
+//   mentura init <dir> --id <id> [--phase <phase>] [--layers purpose,governance]
+//                                                   start a venture; --layers turns on only those
+//   mentura add <function> --venture <id> [--group]
+//                                                   import a function (department is the alias for one release): list it and create its folders
+//   mentura upgrade --venture <id>                  alias of naive upgrade: move the venture onto the package folder layout (EE-070, EE-076)
+//   mentura migrate --from <project> --venture <id|dir> [--apply]
+//                                                   alias of naive migrate: an agent rewrites a project as Naive records (EE-076)
+//   mentura typegen                                 alias of naive typegen (EE-073)
+//   mentura steps <payload|run|check|waterfall|provenance|confirm> --venture <id> [--answers <file>] [--speculate] [--stream]
+//                                                   model steps (use model, EE-073): schema/model-steps.mjs
+//   mentura accept <route> --venture <id> [--confirm <route>]
+//                                                   a person accepts an agent's draft of a gated record;
+//                                                   one holding a foundation statement asks you to type the route;
+//                                                   [--pick <letter>] [--by <name>] accepts one of drafts kept side by side
+//   mentura decide <decision> --venture <id> --by <name> [--answer <text>] [--confirm <decision>]
+//                                                   a person makes a decision: approves its wording or gives their own (EE-058)
+//   mentura propose --venture <id> --input <file.json> [--as <role>]
+//                                                   an agent proposes a decision; it stays open until a person decides
+//   mentura understand --venture <id> [--confirm ideas] [--note <corrections made>]
+//                                                   a person confirms Mentura read their ideas right (the map
+//                                                   and graph, after any corrections), before routing (EE-069)
+//   mentura confirm <statement> --venture <id> [--confirm <statement>]
+//                                                   a person confirms one foundation statement as theirs (EE-051)
+//   mentura <route> <action> --venture <id|path> [--input <file>|-] [--as person] [--value <n>] [--json]
+//          actions: read, write, check, template, layout, view (a page), run (commands)
+//          a collection item is <route>/<id> (purpose/product/kettle); a nested venture is its
+//          folder path (--venture studio/print); system/overview view shows the venture at a glance
+//          [--derived-from a,b] [--decision <id>] [--note <text>]   provenance for a write (EE-031)
+//          [--confidence <n>]   a score computed before the write, read by the gate's confidence rules
+//          knowledge/catalog run builds the catalog over the venture's sources; knowledge/search run
+//          --value <query> finds items in any of them (EE-037)
+//          purpose/validation/assess run lists what is missing and asks to fill it in or run as is;
+//          --as-is runs it anyway (EE-050)
+//          [--where status=active|trial,phase=build] filters a read; --hierarchy shows how it resolved
+//          a package's own route (validation, packages/product) reads its state; (go-to-market) is a
+//          route group; venture read is the manifest, venture check runs every boundary
+//   mentura baseline --venture <id>                 adopt existing records into the provenance log
+//   mentura revalidate <tag:route|path:folder|package:name|route> --venture <id> [--pivot] [--reason <text>]
+//                                                   mark records stale on demand; a plain folder is refused for exact tags (Revalidating)
+//   mentura verify <route|folder> --venture <id>    checked and still right, unchanged: its age starts again
+//   mentura phase <phase> --venture <id> --as person   change phase; per-phase records go stale
+//   mentura freshness --venture <id> [--freeze <out dir>]   what is fresh, stale, expired or a live hole
+//   mentura <route> navigate|head --venture <id> [--session <s>] [--task <text>] [--prefetch a,b | --no-prefetch] [--stream]
+//                                                   read a route header first, with layout once per session, template and prefetch
+//   mentura batch --venture <id> --input <calls.json> [--stream]
+//                                                   run a list of {route, action, input} calls, reporting each as it finishes
+//
+// The workspace is MENTURA_WORKSPACE, else --workspace <dir>, else this repository's instance/.
+// Writes default to an agent actor; --as person is for a person at the keyboard, and a gated
+// record written by an agent lands in <venture>/_drafts/ for a person to accept.
+
+import "./guard.mjs"; // wf/writes hook: a broken framework file answers with recovery steps (E-8)
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { call, draftOf, files, glob, groups, repo, routes, routesMd, ventureDir, ventures } from "../router.mjs";
+import { agentFromEnv, entries, record } from "../provenance.mjs";
+import { FRAME, filesOf } from "../../schema/foundation.mjs";
+import { approve, decisions, propose } from "../../schema/decisions.mjs";
+// Gate group hook (X-2): held drafts kept side by side.
+import { pick as pickDraft, settle as settleDraft } from "../../schema/gate-drafts.mjs";
+import { asRouted, findVenture } from "./find-venture.mjs";
+
+// The danger zone (EE-051): a foundation statement is accepted or confirmed only when the person types
+// its name, at the prompt or with --confirm <name>.
+async function typed(name, what, why = "This is a foundation statement: changing it changes the venture.") {
+  if (opt("confirm") !== undefined) return opt("confirm") === name;
+  console.log(`${what}\n${why} Type ${name} to confirm.`);
+  if (!process.stdin.isTTY) { console.log(`(not at a terminal: pass --confirm ${name})`); return false; }
+  const { createInterface } = await import("node:readline/promises");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const a = (await rl.question("> ")).trim();
+  rl.close();
+  return a === name;
+}
+const foundationOf = (recordType) => FRAME.questions.flatMap((q) => q.statements).filter((s) => s.record === recordType);
+
+const argv = process.argv.slice(2);
+// Inside a venture, --venture and the workspace default to it (I-2): `cd my-venture && mentura system/overview view`.
+const here = !argv.includes("--venture") && !argv.includes("--workspace") ? findVenture() : null;
+if (here) { argv.push("--venture", asRouted(here).venture, "--workspace", asRouted(here).workspace); process.env.MENTURA_WORKSPACE = asRouted(here).workspace; }
+const opt = (name) => { const i = argv.indexOf(`--${name}`); return i >= 0 ? argv[i + 1] : undefined; };
+const flag = (name) => argv.includes(`--${name}`);
+const positional = argv.filter((a, i) => !a.startsWith("--") && !(i > 0 && argv[i - 1].startsWith("--") && !["json", "hierarchy"].includes(argv[i - 1].slice(2))));
+const workspace = opt("workspace") ? resolve(opt("workspace")) : undefined;
+const out = (x) => console.log(typeof x === "string" ? x : JSON.stringify(x, null, 2));
+
+function usage(code = 2) {
+  console.error(readFileSync(new URL(import.meta.url), "utf8").split("\n").filter((l) => l.startsWith("//   ")).map((l) => l.slice(5)).join("\n"));
+  process.exit(code);
+}
+
+const [cmd, action] = positional;
+if (!cmd || cmd === "help" || flag("help")) usage(cmd ? 0 : 2);
+
+if (cmd === "routes") {
+  const g = opt("group")?.replace(/^\(|\)$/g, "");
+  const rs = g ? routes().filter((r) => r.groups.includes(`(${g})`)) : routes();
+  out(flag("json") || g ? (flag("json") ? rs : rs.map((r) => `${r.route.padEnd(44)} ${r.actions.join(", ")}`).join("\n")) : routesMd());
+  process.exit(0);
+}
+
+if (cmd === "groups") { out(flag("json") ? groups() : groups().map((g) => `${g.group.padEnd(14)} ${g.routes.length} routes  ${g.question}`).join("\n")); process.exit(0); }
+
+if (cmd === "ventures") {
+  const vs = ventures(workspace);
+  out(flag("json") ? vs : vs.map((v) => `${v.id.padEnd(24)} ${String(v.phase).padEnd(12)} ${v.path}`).join("\n") || "no ventures");
+  process.exit(0);
+}
+
+// Brand hook: mentura brand ... and mentura assets ... (Y-2..Y-4, J-2..J-4, T-1, T-2, P-24, P-26) live in interface/brand.mjs.
+if (cmd === "brand" || cmd === "assets") process.exit(await (await import("../brand.mjs")).main(argv, { workspace }));
+
+if (cmd === "add") {
+  // Imports one function into a venture (EE-047, EE-048, EE-071). department is the alias for function for one release.
+  const v = opt("venture");
+  if (!action || !v) usage();
+  const p = spawnSync("node", [join(repo, "schema/add-department.mjs"), ventureDir(v, workspace), action, ...(flag("group") ? ["--group"] : [])], { stdio: "inherit" });
+  process.exit(p.status ?? 1);
+}
+
+if (cmd === "typegen") {
+  const p = spawnSync("node", [join(repo, "interface/cli/naive.mjs"), "typegen"], { stdio: "inherit" });
+  process.exit(p.status ?? 1);
+}
+
+// Upgrades hook (M-12, E-7, V-9, Z-4): these commands live in their own modules; this only dispatches.
+//   mentura triggers --venture <id> [--fire] [--json]
+//                                                   the venture's triggers, their runs and open failures; --fire runs what new events start
+//   mentura stale --venture <id> [--json]           summaries whose system of record changed since they were written
+//   mentura notify --venture <id> --source <id> --path <p> [--version <v>]
+//                                                   a system of record says <p> changed: mark what reads it stale (a webhook does this on Mentura)
+//   mentura adapt <adapter> --venture <id>          write a harness's entry files into the venture (claude-code, codex, cursor)
+//   mentura adapters [verify [<adapter>]] [--json]  the adapters, or run the framework's tests an adapter must pass
+if (["triggers", "stale", "notify", "adapt", "adapters"].includes(cmd)) {
+  const d = ["triggers", "stale", "notify", "adapt"].includes(cmd) ? (opt("venture") ? ventureDir(opt("venture"), workspace) : null) : null;
+  if (cmd !== "adapters" && !d) { console.error(opt("venture") ? `no venture ${opt("venture")}` : `mentura ${cmd} needs --venture <id>`); process.exit(2); }
+  const pass = (...names) => names.flatMap((n) => argv.flatMap((a, i) => (a === `--${n}` ? [a, ...(argv[i + 1] && !argv[i + 1].startsWith("--") ? [argv[i + 1]] : [])] : [])));
+  const args = cmd === "triggers" ? ["schema/triggers.mjs", d, ...pass("fire", "json")]
+    : cmd === "stale" ? ["schema/stale.mjs", d, ...pass("json")]
+    : cmd === "notify" ? ["schema/stale.mjs", d, "--notify", ...pass("source", "path", "version", "json")]
+    : cmd === "adapt" ? ["interface/adapters.mjs", "adapt", action ?? "", d, ...pass("json")]
+    : ["interface/adapters.mjs", ...positional.slice(1), ...pass("json")];
+  const p = spawnSync("node", [join(repo, args[0]), ...args.slice(1)], { stdio: "inherit" });
+  process.exit(p.status ?? 1);
+}
+
+if (cmd === "migrate" && (opt("from") || flag("apply"))) {
+  // migrate means rewriting an outside project into a new venture (EE-076): the same as naive migrate.
+  const v = opt("venture");
+  const d = v && (existsSync(join(resolve(v), "venture.json")) ? resolve(v) : ventureDir(v, workspace));
+  if (!d) usage();
+  const p = spawnSync("node", [join(repo, "schema/migrate-venture.mjs"), "--venture", d, ...(opt("from") ? ["--from", opt("from")] : ["--apply"])], { stdio: "inherit" });
+  process.exit(p.status ?? 1);
+}
+
+if (cmd === "upgrade" || cmd === "migrate") {
+  // migrate without --from is the old name of upgrade: for one release it still runs upgrade, with a notice.
+  if (cmd === "migrate") console.error("mentura migrate --venture <id> is now naive upgrade (EE-076); migrate --from <project> rewrites an outside project into Naive");
+  const v = opt("venture");
+  const d = v && ventureDir(v, workspace);
+  if (!d) usage();
+  const p = spawnSync("node", [join(repo, "schema/upgrade-venture.mjs"), d], { stdio: "inherit" });
+  process.exit(p.status ?? 1);
+}
+
+// Model steps hook (use model, EE-073): mentura steps <payload|run|check|waterfall|provenance|confirm> --venture <id> [...].
+// The logic is schema/model-steps.mjs; this passes the venture folder and the other arguments through.
+if (cmd === "steps") {
+  const v = opt("venture"), d = v && ventureDir(v, workspace);
+  if (!d || !action) usage();
+  const pass = argv.slice(argv.indexOf("steps") + 1).filter((a, i, all) => !["--venture", "--workspace"].includes(a) && !["--venture", "--workspace"].includes(all[i - 1]));
+  const p = spawnSync("node", [join(repo, "schema/model-steps.mjs"), d, ...pass], { stdio: "inherit" });
+  process.exit(p.status ?? 1);
+}
+
+if (cmd === "init") {
+  // The venture scaffold lives in schema/init-venture.mjs; this passes the options through.
+  const id = opt("id");
+  if (!action || !id) usage();
+  const pass = ["phase", "parent", "legal-form", "layers"].flatMap((k) => opt(k) !== undefined ? [`--${k}`, opt(k)] : []);
+  const p = spawnSync("node", [join(repo, "schema/init-venture.mjs"), resolve(action), id, ...pass], { stdio: "inherit" });
+  process.exit(p.status ?? 1);
+}
+
+if (cmd === "accept") {
+  // The person at the keyboard accepts a draft: it is checked again and moved into place. The CLI
+  // cannot tell a person from an agent running it, so the repository's review (a pull request a
+  // person merges) remains the gate that holds; this makes the person's step explicit.
+  const venture = opt("venture"), rt = action;
+  if (!venture || !rt) usage();
+  const d = draftOf(rt, venture, workspace);
+  // Any held draft can be accepted: one gated by its decision class, held by an open decision, or held by
+  // the venture's naive.config.json gate.
+  if (!d) { console.error(`${rt} is not a record route, or no venture ${venture}`); process.exit(1); }
+  const draft = join(d.dir, d.draft);
+  if (!existsSync(draft)) { console.error(`no draft of ${d.route} in ${venture}`); process.exit(1); }
+  // Gate group hook (X-2): drafts kept side by side are accepted one at a time with --pick <letter>.
+  let chosen;
+  try { chosen = pickDraft(d.dir, d.draft, opt("pick")); } catch (e) { console.error(e.message); process.exit(1); }
+  const chosenFile = join(d.dir, chosen);
+  const recType = routes().find((x) => x.route === d.route || x.route === d.route.replace(/[^/]+$/, "[id]"))?.record;
+  const touched = foundationOf(recType);
+  if (touched.length) {
+    const get = (o, p) => p.split(".").reduce((x, k) => (x == null ? undefined : x[k]), o);
+    const now = existsSync(join(d.dir, d.file)) ? JSON.parse(readFileSync(join(d.dir, d.file), "utf8")) : {};
+    const next = JSON.parse(readFileSync(chosenFile, "utf8"));
+    const diff = touched.map((s) => `  ${s.id}:\n    now:   ${JSON.stringify(get(now, s.attribute) ?? null)}\n    draft: ${JSON.stringify(get(next, s.attribute) ?? null)}`).join("\n");
+    const names = new Set([d.route, rt]);
+    const confirmed = opt("confirm") !== undefined ? names.has(opt("confirm")) : await typed(d.route, `Accepting ${d.route} changes these foundation statements:\n${diff}`);
+    if (!confirmed) { console.error("not accepted: the confirmation did not match"); process.exit(1); }
+  }
+  const w = await call({ venture, route: d.route, action: "write", input: JSON.parse(readFileSync(chosenFile, "utf8")), actor: "person", workspace, via: "cli",
+    provenance: { activity: "accept", derived_from: [chosen], note: opt("note") } });
+  if (!w.ok) { console.error(w.error); process.exit(1); }
+  // Gate group hook (X-2): removes the draft, its variants and sidecar, and decides the variants decision.
+  const settled = settleDraft(d.dir, d.draft, { picked: opt("pick") ?? "a", by: opt("by") });
+  out(`accepted: ${w.result.written}${settled.decision ? ` (draft ${settled.picked}; decision ${settled.decision} ${settled.decided ? "decided" : `not decided: ${settled.error}`})` : ""}`);
+  process.exit(0);
+}
+
+if (cmd === "decide") {
+  // A person makes a decision (EE-058): approves the drafted wording, or gives their own with
+  // --answer. Typing the decision's id confirms it. Provenance records who, when and in which phase.
+  const venture = opt("venture"), id = action;
+  const dir = venture && ventureDir(venture, workspace);
+  if (!dir || !id) usage();
+  const d = decisions(dir).decisions.find((x) => x.id === id);
+  if (!d || d.source !== "file") { console.error(`no decision record ${id} in ${venture}`); process.exit(1); }
+  if (!(await typed(id, `Deciding ${id}: ${d.question}\n  ${opt("answer") ? "your answer" : "drafted wording"}: ${opt("answer") ?? d.answer ?? "(none)"}`, "This is a decision: it unlocks what waits on it."))) { console.error("not decided: the confirmation did not match"); process.exit(1); }
+  const r = approve(dir, id, { by: opt("by") ?? process.env.MENTURA_PERSON, answer: opt("answer"), note: opt("note") });
+  if (!r.ok) { console.error(r.error); process.exit(1); }
+  out(r.result);
+  process.exit(0);
+}
+
+if (cmd === "propose") {
+  // An agent proposes a decision from a JSON file; it stays open until a person decides it.
+  const venture = opt("venture"), dir = venture && ventureDir(venture, workspace);
+  if (!dir || !opt("input")) usage();
+  const r = propose(dir, JSON.parse(readFileSync(resolve(opt("input")), "utf8")), { agentId: opt("as") ?? process.env.MENTURA_ACTOR_ID, via: "cli" });
+  if (!r.ok) { console.error(r.error); process.exit(1); }
+  out(r.result);
+  process.exit(0);
+}
+
+if (cmd === "understand") {
+  // The Understand gate (EE-069): the founder has looked over the map and the graph, corrected what
+  // Mentura got wrong, and confirms the understanding before the ideas are routed.
+  const venture = opt("venture"), dir = venture && ventureDir(venture, workspace);
+  if (!dir) usage();
+  const hits = ["purpose/ideas/map.mdx", "purpose/ideas/graph.json"].filter((f) => existsSync(join(dir, f)));
+  if (!hits.length) { console.error(`${venture} has no idea map yet: map the idea dump first (purpose/ideas)`); process.exit(1); }
+  if (!(await typed("ideas", `Confirming Mentura's understanding of your ideas: ${hits.join(", ")}`, "Your ideas are routed to their records from this understanding."))) { console.error("not confirmed: the confirmation did not match"); process.exit(1); }
+  for (const f of hits) record(dir, { entity: f, route: f.endsWith(".mdx") ? "purpose/ideas" : "purpose/ideas/graph", activity: "confirm", statement: "ideas", agent: agentFromEnv("person", "cli"), note: opt("note") });
+  out("confirmed: ideas");
+  process.exit(0);
+}
+
+if (cmd === "confirm") {
+  // A person confirms a foundation statement an agent wrote as their own; the content is unchanged.
+  const venture = opt("venture"), id = action;
+  const dir = venture && ventureDir(venture, workspace);
+  if (!dir || !id) usage();
+  const s = FRAME.questions.flatMap((q) => q.statements).find((x) => x.id === id);
+  if (!s?.record) { console.error(`${id} is not a foundation statement with a record (see mentura purpose/foundation run)`); process.exit(1); }
+  const rt = routes().find((x) => x.record === s.record && x.collection !== "list")?.route ?? s.record;
+  const hits = filesOf(dir, s.record).filter((f) => existsSync(join(dir, f)));
+  if (!hits.length) { console.error(`${venture} has no ${s.record} record to confirm`); process.exit(1); }
+  const get = (o, p) => p.split(".").reduce((x, k) => (x == null ? undefined : x[k]), o);
+  const shown = hits.map((f) => `  ${f}: ${JSON.stringify(get(JSON.parse(readFileSync(join(dir, f), "utf8")), s.attribute) ?? null)}`).join("\n");
+  if (!(await typed(id, `Confirming ${id} as yours:\n${shown}`))) { console.error("not confirmed: the confirmation did not match"); process.exit(1); }
+  for (const f of hits) record(dir, { entity: f, route: rt, activity: "confirm", statement: id, agent: agentFromEnv("person", "cli"), note: opt("note") });
+  out(`confirmed: ${id}`);
+  process.exit(0);
+}
+
+if (cmd === "baseline") {
+  // A venture that existed before the log: record each record file as it is now, once, so later
+  // writes have a starting point. Files already in the log are left alone.
+  const venture = opt("venture");
+  const dir = venture && ventureDir(venture, workspace);
+  if (!dir) usage();
+  const logged = new Set(entries(dir).map((e) => e.entity));
+  const globs = routes().filter((r) => r.kind === "record" && r.form === "json" && r.collection !== "list").flatMap((r) => r.files.map((g) => [r.route, g]));
+  const routeOf = (rt, g, f) => rt.endsWith("/[id]") ? rt.replace("[id]", f.match(new RegExp("^" + g.split("*").map((x) => x.replace(/[.+^${}()|[\]\\]/g, "\\$&")).join("([^/]*)") + "$"))[1]) : rt;
+  let n = 0;
+  for (const f of files(dir).filter((f) => !f.startsWith("_drafts/"))) {
+    const hit = globs.find(([, g]) => glob(g).test(f));
+    if (!hit || logged.has(f)) continue;
+    record(dir, { entity: f, route: routeOf(hit[0], hit[1], f), activity: "baseline", agent: agentFromEnv(opt("as") === "person" ? "person" : "agent", "cli"), note: "existed before the provenance log; its history before this is in git" });
+    n++;
+  }
+  out(`baseline: ${n} records added to ${venture}'s provenance log`);
+  process.exit(0);
+}
+
+// Freshness (Revalidating, V-1 to V-8): revalidate, verify, phase and freshness live in ./freshness.mjs.
+if (["revalidate", "verify", "phase", "freshness"].includes(cmd)) process.exit(await (await import("./freshness.mjs")).main(cmd, argv, workspace));
+
+// Context hook (interface/context.mjs): navigate and head read a route header first, with its layout once per
+// session (--session), its template and prefetched refs (--task, --prefetch, --no-prefetch, --stream); batch runs
+// a list of calls with progress.
+if (["navigate", "head"].includes(action) || cmd === "batch") { const { cli } = await import("../context.mjs"); process.exit(await cli(argv, { workspace })); }
+if (!action) usage();
+const venture = opt("venture");
+if (!venture && !["template", "layout"].includes(action)) usage();
+let input;
+const src = opt("input");
+if (src) input = JSON.parse(src === "-" ? readFileSync(0, "utf8") : readFileSync(src, "utf8"));
+if (opt("value")) input = { ...(input ?? {}), value: Number.isNaN(Number(opt("value"))) ? opt("value") : Number(opt("value")) };
+if (flag("as-is")) input = { ...(input ?? {}), as_is: true };
+// wf/writes hook: --where k=v[,k=v] filters a read (L-10); --hierarchy returns its resolution levels (P-28).
+if (["read", "view"].includes(action) && opt("where")) input = { ...(input ?? {}), where: Object.fromEntries(opt("where").split(",").map((kv) => kv.split("=")).map(([k, ...v]) => [k, v.join("=").includes("|") ? v.join("=").split("|") : v.join("=")])) };
+if (["read", "view"].includes(action) && flag("hierarchy")) input = { ...(input ?? {}), hierarchy: true };
+const provenance = { derived_from: opt("derived-from")?.split(",").filter(Boolean), decision: opt("decision"), note: opt("note") };
+// Gate group hook (X-4): a confidence score computed before the write, for the gate's confidence rules.
+if (opt("confidence") !== undefined) provenance.confidence = Number(opt("confidence"));
+let r = await call({ venture, route: cmd, action, input, actor: opt("as") === "person" ? "person" : "agent", workspace, via: "cli", provenance });
+// Asks before running (EE-050): at a terminal, the person chooses; otherwise it prints both choices.
+if (r.ok && r.needs_input && !flag("json")) {
+  const n = r.needs_input;
+  console.log(`${n.ask}\n${n.missing.map((m) => `  - ${m.field}${m.items ? ` (${m.items.join(", ")})` : ""}: ${m.why}. As is: ${m.as_is}`).join("\n")}`);
+  if (!process.stdin.isTTY) { console.log(`Fill in: ${n.options[0].how}\nRun as is: ${n.options[1].how}`); process.exit(0); }
+  const { createInterface } = await import("node:readline/promises");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const a = (await rl.question("Fill in (f) or run as is (r)? ")).trim().toLowerCase();
+  rl.close();
+  if (!a.startsWith("r")) { console.log(`Fill in: ${n.options[0].how}`); process.exit(0); }
+  r = await call({ venture, route: cmd, action, input: { ...(input ?? {}), as_is: true }, actor: opt("as") === "person" ? "person" : "agent", workspace, via: "cli", provenance });
+}
+if (!r.ok) { console.error(r.error ?? JSON.stringify(r.result, null, 2)); process.exit(1); }
+if (r.deprecated) console.error(`note: ${r.deprecated}`);
+const extra = ["not_found", "pending_draft", "fix", "needs_input", "errors", "filtered_out", "hierarchy", "stale"].some((k) => r[k]); // stale: V-9 (schema/stale.mjs)
+out(flag("json") || extra ? r : r.result);

package/interface/cli/naive.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+// The framework CLI (EE-072), the way `next` is Next.js's: run it inside a venture and it finds the
+// venture.json in the current directory or its parents. mentura stays for platform commands and as an
+// alias, so `mentura typegen` and `mentura upgrade` run these same commands.
+//
+//   naive dev [--port 4331]                         the setup page at /setup and the board, live: edit a record and it updates; each saved
+//                                                   record is checked against its schema as you go (I-17, I-24)
+//   naive build                                     check every package and write a release (I-17)
+//   naive start                                     serve the latest release read-only (I-17)
+//   naive check                                     run every check that applies to the venture (I-9)
+//   naive info                                      versions, the venture, and which agents are connected (I-6)
+//   naive mcp                                       serve the venture to an agent over MCP (stdio)
+//   naive setup [state|artifact|answer|point|confirm]  set the venture up: the state, an artifact of it, and
+//                                                   confirming the answers the model relayed (EE-083)
+//   naive frame "<the founder's words>"             match the words to a frame in the decision library, judge its
+//                                                   premises against the venture and propose its decisions, open
+//   naive typegen                                   write .naive/types/ from the route table and the MCP tools
+//   naive upgrade [<venture dir>] [--framework]     move a venture onto the next Naive layout; --framework first
+//                                                   updates the installed framework with the venture's package manager (I-29)
+//   naive port --from <project> --venture <dir>     plan bringing a project in with its files as they are
+//   naive port --venture <dir> --apply --confirm port
+//                                                   carry out that plan (EE-076)
+//   naive migrate --from <project> --venture <dir>  an agent rewrites the project as Naive records, as a plan and decisions
+//   naive migrate --venture <dir> --apply           write what a person decided (EE-076)
+//
+// --venture <dir> names the venture when you are not inside it.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, watch, writeFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { basename, join, relative, resolve } from "node:path";
+import { asRouted, findVenture } from "./find-venture.mjs";
+
+const repo = new URL("../..", import.meta.url).pathname;
+const [cmd, ...rest] = process.argv.slice(2);
+const opt = (n) => { const i = rest.indexOf(`--${n}`); return i >= 0 ? rest[i + 1] : undefined; };
+const run = (script, args, opts = {}) => spawnSync("node", [join(repo, script), ...args], { stdio: "inherit", ...opts }).status ?? 1;
+const version = () => JSON.parse(readFileSync(join(repo, "package.json"), "utf8")).version;
+
+// The venture: --venture <dir>, else the one this command runs inside.
+function here() {
+  const named = opt("venture");
+  const dir = named ? (existsSync(join(resolve(named), "venture.json")) ? resolve(named) : null) : findVenture();
+  if (!dir) {
+    console.error(named ? `${named} has no venture.json` : `no venture here: run naive ${cmd} inside a venture (a directory with venture.json), or pass --venture <dir>`);
+    process.exit(1);
+  }
+  return dir;
+}
+
+// A port that is free, starting at the one asked for, the way next dev moves on from 3000.
+const free = (p) => new Promise((ok) => { const s = createServer().once("error", () => ok(free(p + 1))).once("listening", () => s.close(() => ok(p))).listen(p, "127.0.0.1"); });
+
+// The schema a venture file is checked against, from the route table (records only).
+async function schemaFor(file) {
+  const { glob, routes } = await import("../router.mjs");
+  return routes().find((r) => r.kind === "record" && r.schema && (r.files ?? []).some((g) => glob(g).test(file)))?.schema ?? null;
+}
+
+async function dev(dir) {
+  // The root layout is required (I-21): a venture without AGENTS.md gets a stub, as next dev writes a root layout.
+  if (!existsSync(join(dir, "AGENTS.md"))) {
+    writeFileSync(join(dir, "AGENTS.md"), `# AGENTS.md: ${basename(dir)}\n\nThe map of this venture for agents. Read it, then a route's layout, before writing anything here.\n\n## Instructions\n\nphase: ${JSON.parse(readFileSync(join(dir, "venture.json"), "utf8")).phase}\nprivate: _private/\n`);
+    console.log("   wrote AGENTS.md, the venture's root layout, because it was missing");
+  }
+  const { workspace, venture } = asRouted(dir);
+  process.env.MENTURA_WORKSPACE = workspace;
+  const port = await free(Number(opt("port") ?? 4331));
+  // One origin: /setup is the setup page (interface/dev/setup.mjs); everything else is the board, served
+  // on a port of its own and passed through.
+  const { serve } = await import("../demo/board.mjs");
+  const { handle } = await import("../dev/setup.mjs");
+  const boardPort = await free(port + 1000);
+  serve(boardPort, venture);
+  const { createServer: http, request } = await import("node:http");
+  http(async (req, res) => {
+    if (await handle(req, res, dir)) return;
+    const up = request({ host: "127.0.0.1", port: boardPort, path: req.url, method: req.method, headers: req.headers }, (r) => { res.writeHead(r.statusCode, r.headers); r.pipe(res); });
+    up.on("error", (e) => { res.writeHead(502); res.end(String(e.message)); });
+    req.pipe(up);
+  }).listen(port, "127.0.0.1");
+  const name = JSON.parse(readFileSync(join(dir, "venture.json"), "utf8")).name ?? venture;
+  console.log(`\n  ▲ Naive ${version()}\n  - Venture:  ${name} (${relative(process.cwd(), dir) || "."})\n  - Setup:    http://127.0.0.1:${port}/setup\n  - Board:    http://127.0.0.1:${port}/\n  - Map:      http://127.0.0.1:${port}/map\n\n  Watching for changes. Each saved record is checked against its schema. Ctrl-C to stop.\n`);
+  // Live feedback on save (I-24): a record that no longer matches its schema says so at once.
+  const pending = new Map();
+  watch(dir, { recursive: true }, (_, f) => {
+    if (!f || !f.endsWith(".json") || f.startsWith("node_modules") || f.startsWith(".naive") || f.startsWith("_private")) return;
+    clearTimeout(pending.get(f));
+    pending.set(f, setTimeout(async () => {
+      pending.delete(f);
+      if (!existsSync(join(dir, f))) return;
+      const schema = await schemaFor(f);
+      if (!schema) return;
+      const v = spawnSync("python3", [join(repo, "schema/validate.py"), "--schema", schema.replace(/^schema\//, ""), "--file", join(dir, f)], { encoding: "utf8" });
+      const out = (v.stdout + v.stderr).trim();
+      if (v.status === 0) console.log(`  ✓ ${f}`);
+      else if (/needs jsonschema/.test(out)) console.log(`  - ${f} changed (install python3's jsonschema package to check it as you save)`);
+      else console.log(`  ✗ ${f} does not match ${schema}\n${out.split("\n").map((l) => `      ${l}`).join("\n")}`);
+    }, 150));
+  });
+}
+
+// The checks that read a workspace, run on this venture: it and the ventures nested in it, not its neighbours.
+const CHECKS = ["check-ventures", "check-people", "check-provenance", "check-sources", "check-data-packages", "check-governance", "check-telos", "check-publication", "check-private", "check-where-used"];
+function check(dir) {
+  let failed = 0;
+  for (const c of CHECKS) {
+    const r = spawnSync("node", [join(repo, `schema/${c}.mjs`), dir], { encoding: "utf8" });
+    const last = (r.stdout + r.stderr).trim().split("\n").filter(Boolean).at(-1) ?? "";
+    if (r.status !== 0) failed++;
+    console.log(`${r.status === 0 ? "pass" : "FAIL"}  ${c.replace("check-", "")}: ${last}`);
+    if (r.status !== 0) console.log((r.stdout + r.stderr).trim().split("\n").slice(0, 12).map((l) => `      ${l}`).join("\n"));
+  }
+  console.log(failed ? `\n${failed} failing` : "\nall passing");
+  return failed ? 1 : 0;
+}
+
+function info(dir) {
+  const v = dir && JSON.parse(readFileSync(join(dir, "venture.json"), "utf8"));
+  // Supported agents (I-6): the MCP clients Naive is tested with, and whether this venture is connected to each.
+  const agents = [
+    ["Claude Code", ".mcp.json", (j) => j?.mcpServers?.naive || j?.mcpServers?.mentura],
+    ["Cursor", ".cursor/mcp.json", (j) => j?.mcpServers?.naive || j?.mcpServers?.mentura],
+  ];
+  const read = (f) => { try { return JSON.parse(readFileSync(f, "utf8")); } catch { return null; } };
+  const lines = [
+    `Naive        ${version()} (${repo.replace(/\/$/, "")})`,
+    `Node         ${process.version}`,
+    `Platform     ${process.platform} ${process.arch}`,
+    `python3      ${spawnSync("python3", ["-c", "import jsonschema; print('jsonschema ' + __import__('importlib.metadata').metadata.version('jsonschema'))"], { encoding: "utf8" }).stdout.trim() || "jsonschema missing (needed by schema checks)"}`,
+    `Venture      ${v ? `${v.name ?? v.id} (${v.phase}) at ${dir}` : "none here"}`,
+    "Agents       " + agents.map(([name, f, ok]) => `${name}: ${dir && ok(read(join(dir, f))) ? "connected" : "not connected"}`).join(", "),
+  ];
+  console.log(lines.join("\n"));
+}
+
+function upgradeFramework(dir) {
+  const pkg = join(dir, "package.json");
+  const deps = existsSync(pkg) ? { ...JSON.parse(readFileSync(pkg, "utf8")).devDependencies, ...JSON.parse(readFileSync(pkg, "utf8")).dependencies } : {};
+  const name = Object.keys(deps).find((d) => d === "naive-framework");
+  if (!name) { console.error("this venture does not install the framework from its package.json, so there is nothing to update; upgrading its layout only"); return 0; }
+  const pm = existsSync(join(dir, "pnpm-lock.yaml")) ? "pnpm" : existsSync(join(dir, "yarn.lock")) ? "yarn" : existsSync(join(dir, "bun.lockb")) || existsSync(join(dir, "bun.lock")) ? "bun" : "npm";
+  const spec = deps[name].startsWith("file:") || deps[name].startsWith("github:") ? deps[name] : `${name}@latest`;
+  const args = pm === "npm" ? ["install", "--save-dev", spec] : pm === "yarn" ? ["add", "--dev", spec] : ["add", "-D", spec];
+  console.log(`updating the framework: ${pm} ${args.join(" ")}`);
+  return spawnSync(pm, args, { cwd: dir, stdio: "inherit" }).status ?? 1;
+}
+
+if (cmd === "dev") await dev(here());
+else if (cmd === "check") process.exit(check(here()));
+else if (cmd === "mcp") {
+  // The MCP server, on the venture this runs in: `claude mcp add naive -- npx naive mcp`.
+  const env = { ...process.env };
+  if (!env.MENTURA_WORKSPACE) env.MENTURA_WORKSPACE = asRouted(here()).workspace;
+  process.exit(spawnSync("node", [join(repo, "interface/mcp/server.mjs")], { stdio: "inherit", env }).status ?? 1);
+}
+else if (cmd === "info") info(findVenture() ?? (opt("venture") && existsSync(join(resolve(opt("venture")), "venture.json")) ? resolve(opt("venture")) : null));
+else if (cmd === "build" || cmd === "start") {
+  // The release itself is written and served by schema/build-release.mjs and schema/start-release.mjs.
+  const script = `schema/${cmd}-release.mjs`;
+  if (!existsSync(join(repo, script))) { console.error(`naive ${cmd} runs ${script}, which this version of Naive does not have yet`); process.exit(1); }
+  process.exit(run(script, [here(), ...rest.filter((a, i) => a !== "--venture" && rest[i - 1] !== "--venture")]));
+} else if (cmd === "upgrade") {
+  // Outside a venture with none named, upgrade-venture.mjs prints its usage.
+  const dir = rest[0] && !rest[0].startsWith("--") ? resolve(rest[0]) : (opt("venture") ? here() : findVenture());
+  if (dir && rest.includes("--framework") && upgradeFramework(dir) !== 0) process.exit(1);
+  // Flags (--check, --guide, --adopt, --canary, --agent, --accept, --confirm) pass through to upgrade-venture.mjs; --framework and --venture are handled here.
+  const flags = rest.filter((a, i) => !(i === 0 && !a.startsWith("--")) && a !== "--framework" && a !== "--venture" && rest[i - 1] !== "--venture");
+  process.exit(run("schema/upgrade-venture.mjs", dir ? [dir, ...flags] : flags));
+} else if (cmd === "frame") {
+  // The decision library (schema/frames.mjs): naive frame "<the founder's words>" runs the frame those words fit.
+  const sub = rest[0];
+  if (["list", "match", "check", "eval"].includes(sub)) process.exit(run("schema/frames.mjs", rest));
+  const words = rest.filter((a, i) => a !== "--venture" && rest[i - 1] !== "--venture" && a !== "--frame" && rest[i - 1] !== "--frame" && a !== "--lookup" && rest[i - 1] !== "--lookup").join(" ");
+  process.exit(run("schema/frames.mjs", ["run", here(), ...(opt("frame") ? [opt("frame")] : []), ...(words ? ["--text", words] : []), ...(opt("lookup") ? ["--lookup", opt("lookup")] : [])]));
+} else if (cmd === "setup") {
+  // Setup in the model's harness (EE-083): the state, the artifact, and the founder confirming relayed answers.
+  process.exit(run("schema/setup.mjs", [here(), ...(rest.length ? rest.filter((a, i) => a !== "--venture" && rest[i - 1] !== "--venture") : ["state"])]));
+} else if (cmd === "port" || cmd === "migrate") {
+  // Inside a venture, --venture defaults to it.
+  const args = rest.includes("--venture") ? rest : [...rest, "--venture", here()];
+  process.exit(run(`schema/${cmd}-venture.mjs`, args));
+} else if (cmd === "typegen") {
+  const { TOOLS } = await import("../mcp/server.mjs");
+  const { routes } = await import("../router.mjs");
+  const out = join(repo, ".naive/types");
+  mkdirSync(out, { recursive: true });
+  writeFileSync(join(out, "tools.json"), JSON.stringify(TOOLS, null, 2) + "\n");
+  writeFileSync(join(out, "routes.json"), JSON.stringify(routes().map((r) => ({ route: r.route, actions: r.actions, kind: r.kind })), null, 2) + "\n");
+  console.log(`wrote ${out}`);
+} else {
+  console.error(readFileSync(new URL(import.meta.url), "utf8").split("\n").filter((l) => l.startsWith("//   ")).map((l) => l.slice(5)).join("\n"));
+  process.exit(cmd ? 1 : 2);
+}