naive-framework 0.0.0-stage → 0.1.0

package/governance/venture-template/roles/talent-acquisition-manager.md

@@ -0,0 +1,50 @@
+---
+type: venture-template-role
+ai-model: claude-opus-5
+role: talent-acquisition-manager
+primary-pillar: business
+secondary-pillars: [product, brand]
+source: hybrid
+created: 2026-08-10
+last-reviewed: 2026-08-10
+authorship: hybrid
+ip-sensitivity: normal
+scope: global
+scope-entity: "[[everything-ecosystem]]"
+tags: [venture-template, role, talent-acquisition, recruiting, business-pillar, stub]
+canonical-for: "talent-acquisition-manager-role-reference"
+related:
+  - "[[governance/venture-template/roles/README]]"
+  - "[[position-schema]]"
+  - "[[role-and-candidate-authoring]]"
+  - "[[hr-manager]]"
+status: STUB
+---
+
+# Talent Acquisition Manager
+
+> **Purpose:** Owns the recruiting pipeline — role intake, sourcing, screening coordination, offer process — for seats the company has decided to fill with humans.
+
+## Primary pillar
+
+- **Business** (people / growth). Partners with hiring managers in Product and Brand.
+
+## Typical responsibilities
+
+- Translate position instances + [[role-and-candidate-authoring]] artifacts into search plans
+- Pipeline health; candidate experience; interview loop logistics
+- Close coordination with HR Manager on offers / onboarding handoff
+- Does **not** invent headcount — consumes approved vacant positions with human staffing posture
+
+## Staffing posture (default for instances)
+
+- `human-required` for the TA manager seat once volume justifies a specialist
+- Pipeline **triage / scheduling / draft outreach** may be `agent-capable` as *duties* under a hybrid seat or supporting agent roles — not a substitute for the TA seat’s judgment on fit
+
+## Position instances
+
+Per [[position-schema]]. Link assignments to open reqs / position vacancies.
+
+## Status
+
+Stub 2026-08-10.

package/interface/api/server.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// The HTTP API over the router (EE-030). Local by default: it binds to 127.0.0.1 and has no
+// authentication, so it is for one builder's machine, not the internet. Every caller is treated as
+// an agent, so gated records are written as drafts for a person to accept.
+//
+//   node interface/api/server.mjs [--port 4330]
+//
+//   GET  /routes, /groups                           the route table; route groups by phase
+//   GET  /ventures                                  ventures in the workspace
+//   GET  /templates/<route>                         a record's template
+//   GET  /ventures/<venture>                        the venture overview (system/overview)
+//   GET  /ventures/<venture>/<route>                read a record (a collection item: <route>/<id>)
+//   GET  /ventures/<venture>/<route>/view           the route as a Markdown page
+//   GET  /ventures/<venture>/<route>/layout         the layout an agent gets before acting
+//   PUT  /ventures/<venture>/<route>                write a record (JSON body); provenance from the
+//        headers x-mentura-derived-from (comma-separated), x-mentura-decision, x-mentura-model;
+//        the role acting from x-mentura-actor (checked against the team plan's routes)
+//   POST /ventures/<venture>/<route>/check          run its checks
+//   POST /ventures/<venture>/<route>/run            run a command route (optional JSON body {value})
+//
+// <venture> is an id or, for a nested venture, its folder path (studio/print).
+
+import { createServer } from "node:http";
+import { call, groups, resolve, routes, ventureDir, ventures } from "../router.mjs";
+
+const status = (r) => r.ok ? 200 : /^no (route|venture)/.test(r.error ?? "") ? 404 : /has no action/.test(r.error ?? "") ? 405 : / may not /.test(r.error ?? "") ? 403 : 422;
+const VERBS = { check: "POST", run: "POST", view: "GET", layout: "GET" };
+
+export async function route(method, url, body, headers = {}) {
+  const path = decodeURIComponent(new URL(url, "http://x").pathname).replace(/\/+$/, "");
+  if (method === "GET" && path === "/routes") return [200, routes()];
+  if (method === "GET" && path === "/ventures") return [200, ventures().map(({ id, name, phase }) => ({ id, name, phase }))];
+  let m = path.match(/^\/templates\/(.+)$/);
+  if (method === "GET" && m) { const r = await call({ route: m[1], action: "template" }); return [status(r), r]; }
+  if (method === "GET" && path === "/groups") return [200, groups()];
+  m = path.match(/^\/ventures\/(.+)$/);
+  if (!m) return [404, { ok: false, error: `no endpoint ${method} ${path}` }];
+  // [...venture]: the longest leading run of segments that names a venture; the rest is the route.
+  const parts = m[1].split("/");
+  let venture, rest;
+  for (let i = parts.length; i >= 1; i--) if (ventureDir(parts.slice(0, i).join("/"))) { venture = parts.slice(0, i).join("/"); rest = parts.slice(i); break; }
+  if (!venture) return [404, { ok: false, error: `no venture in ${path}` }];
+  if (!rest.length) { if (method !== "GET") return [405, { ok: false, error: `${method} is not allowed on ${path}` }]; const r = await call({ venture, route: "system/overview", action: "run", via: "api" }); return [status(r), r]; }
+  let verb = VERBS[rest.at(-1)] && resolve(rest.slice(0, -1).join("/")).r ? rest.pop() : null;
+  const rt = rest.join("/");
+  const action = verb ?? (method === "GET" ? "read" : method === "PUT" ? "write" : null);
+  if (!action || (verb && VERBS[verb] !== method)) return [405, { ok: false, error: `${method} is not allowed on ${path}` }];
+  const h = (k) => headers[k] || undefined;
+  const r = await call({ venture, route: rt, action, input: body, actor: "agent", actor_id: h("x-mentura-actor"), via: "api",
+    provenance: { derived_from: h("x-mentura-derived-from")?.split(",").map((x) => x.trim()).filter(Boolean), decision: h("x-mentura-decision"),
+      agent: Object.fromEntries(Object.entries({ model: h("x-mentura-model"), harness: h("user-agent") }).filter(([, v]) => v)) } });
+  return [status(r), r];
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const i = process.argv.indexOf("--port");
+  const port = i >= 0 ? Number(process.argv[i + 1]) : 4330;
+  createServer((req, res) => {
+    let raw = "";
+    req.on("data", (c) => { raw += c; if (raw.length > 1e6) req.destroy(); });
+    req.on("end", async () => {
+      let body;
+      try { body = raw ? JSON.parse(raw) : undefined; } catch { res.writeHead(400, { "content-type": "application/json" }); res.end(JSON.stringify({ ok: false, error: "body is not JSON" })); return; }
+      const [code, out] = await route(req.method, req.url, body, req.headers);
+      res.writeHead(code, { "content-type": "application/json" });
+      res.end(JSON.stringify(out, null, 2));
+    });
+  }).listen(port, "127.0.0.1", () => console.log(`mentura API on http://127.0.0.1:${port}`));
+}

package/interface/cli/find-venture.mjs

@@ -0,0 +1,15 @@
+// The venture a command runs on when none is named: the nearest venture.json in the current
+// directory or its parents, the way next finds the project it runs in (I-2).
+
+import { existsSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+
+export function findVenture(from = process.cwd()) {
+  for (let d = resolve(from); ; d = dirname(d)) {
+    if (existsSync(join(d, "venture.json"))) return d;
+    if (dirname(d) === d) return null;
+  }
+}
+
+/** The router's view of a venture directory: its workspace is the folder that holds it. */
+export const asRouted = (dir) => ({ workspace: dirname(dir), venture: basename(dir) });

package/interface/cli/mentura.mjs

@@ -0,0 +1,271 @@
+#!/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 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
+//   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)
+//          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)
+//   mentura baseline --venture <id>                 adopt existing records into the provenance log
+//
+// 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 { 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";
+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"].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);
+}
+
+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);
+}
+
+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);
+}
+
+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); }
+  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(draft, "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(draft, "utf8")), actor: "person", workspace, via: "cli",
+    provenance: { activity: "accept", derived_from: [d.draft], note: opt("note") } });
+  if (!w.ok) { console.error(w.error); process.exit(1); }
+  rmSync(draft);
+  out(`accepted: ${w.result.written}`);
+  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);
+}
+
+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 };
+const provenance = { derived_from: opt("derived-from")?.split(",").filter(Boolean), decision: opt("decision"), note: opt("note") };
+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"].some((k) => r[k]);
+out(flag("json") || extra ? r : r.result);

package/interface/cli/naive.mjs

@@ -0,0 +1,169 @@
+#!/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 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 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));
+  const { serve } = await import("../demo/board.mjs");
+  serve(port, venture);
+  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  - 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 the folder that holds this venture.
+const CHECKS = ["check-ventures", "check-provenance", "check-sources", "check-data-packages", "check-governance", "check-telos", "check-publication", "check-private", "check-where-used"];
+function check(dir) {
+  const { workspace } = asRouted(dir);
+  let failed = 0;
+  for (const c of CHECKS) {
+    const r = spawnSync("node", [join(repo, `schema/${c}.mjs`), workspace], { 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);
+  process.exit(run("schema/upgrade-venture.mjs", dir ? [dir] : []));
+} 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);
+}