naive-framework 0.0.0-stage → 0.2.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/governance/venture-template/roles/venture-roles.json

@@ -0,0 +1,62 @@
+{
+  "version": "0.1.0",
+  "note": "Roles a person can hold in a venture (EE-082). Agent roles are in agent-roles.json.",
+  "roles": [
+    {
+      "id": "founder",
+      "name": "Founder",
+      "kind": "builder",
+      "description": "Started the venture and owns it; alone, owns every function",
+      "founder": true,
+      "owns_when_solo": true
+    },
+    {
+      "id": "co-founder",
+      "name": "Co-founder",
+      "kind": "builder",
+      "description": "One of two or more founders; owns the functions the team assigns",
+      "founder": true,
+      "owns_when_solo": true
+    },
+    {
+      "id": "general-partner",
+      "name": "General partner",
+      "kind": "investor",
+      "description": "Runs a fund or firm: sets the thesis, raises from limited partners, makes and manages investments",
+      "founder": true,
+      "owns_when_solo": true
+    },
+    {
+      "id": "limited-partner",
+      "name": "Limited partner",
+      "kind": "investor",
+      "description": "Commits capital to a fund and receives reports; does not run it",
+      "founder": false,
+      "owns_when_solo": false
+    },
+    {
+      "id": "operator",
+      "name": "Operator",
+      "kind": "operator",
+      "description": "Runs one or more functions without founding the venture: an early employee or executive",
+      "founder": false,
+      "owns_when_solo": false
+    },
+    {
+      "id": "advisor",
+      "name": "Advisor",
+      "kind": "advisor",
+      "description": "Advises the founders; owns no function",
+      "founder": false,
+      "owns_when_solo": false
+    },
+    {
+      "id": "board-member",
+      "name": "Board member",
+      "kind": "governor",
+      "description": "Sits on the board and governs; owns no function",
+      "founder": false,
+      "owns_when_solo": false
+    }
+  ]
+}

package/interface/acting.mjs

@@ -0,0 +1,83 @@
+// Who is acting (M-18, like cookies in a Server Action) and access on every read (F-5). Every action
+// through the router carries who is acting, a person or an agent, and in which team-plan role. The
+// router checks it before anything else, on every call: the actor is a person or an agent, an agent
+// never acts in a role a person holds, and a venture can refuse role ids its team plan does not list
+// (naive.config.json acting.unknown_roles). Each answer carries `acting` back. When who is acting
+// changes between two calls on one interface, or the role's entry in the team plan changes, the next
+// answer carries `acting_changed` with the routes the new identity may reach: the re-render.
+//
+// Access (P-27) is checked again at the record: a list read returns only the items the role may read,
+// so a role allowed one product never sees the others. Credentials never enter here; connectors keep
+// them, and the platform's stay in platform/ (EE-041).
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash } from "node:crypto";
+import { globsOf, mayReadItem, mayReadSome, roleOf, teamPlan } from "../schema/access.mjs";
+import { configFor } from "../schema/naive-config.mjs";
+
+export { mayReadItem, mayReadSome };
+
+/** Checks who is acting on a venture. Returns { ok, who: { kind, role, known, occupant } } or { ok: false, error }. */
+export function actingOf(dir, kind, roleId) {
+  const who = { kind, role: roleId ?? null };
+  if (kind !== "agent" && kind !== "person") return { ok: false, error: `the actor is a person or an agent, not ${kind}`, who };
+  if (!dir || !roleId) return { ok: true, who };
+  const plan = teamPlan(dir);
+  if (!plan) return { ok: true, who };
+  const role = (plan.roles ?? []).find((r) => r.id === roleId);
+  if (!role) {
+    let mode = "allow";
+    try { mode = configFor(dir).acting?.unknown_roles ?? "allow"; } catch {}
+    if (mode === "refuse") return { ok: false, error: `${roleId} is not a role in the team plan, and naive.config.json refuses unknown roles (acting.unknown_roles)`, who };
+    return { ok: true, who: { ...who, known: false } };
+  }
+  if (kind === "agent" && role.occupant === "person") return { ok: false, error: `${roleId} is a person's role in the team plan: an agent may not act in it`, who };
+  return { ok: true, who: { ...who, known: true, occupant: role.occupant } };
+}
+
+/** A fingerprint of who is acting: kind, role and the role's team-plan entry, so a changed entry counts as a change. */
+export function fingerprint(dir, who) {
+  return createHash("sha256").update(JSON.stringify({ kind: who.kind, role: who.role, entry: dir && who.role ? roleOf(dir, who.role) : null })).digest("hex");
+}
+
+/** The routes an identity may reach: globs to read and write. */
+export function reach(dir, roleId) {
+  const g = dir && roleId ? globsOf(dir, roleId) : null;
+  return g ?? { read: ["**"], write: ["**"] };
+}
+
+/** The id of a collection item from its file, given the collection's file patterns (products/*.json). */
+export function itemId(patterns, path) {
+  for (const g of patterns) {
+    if (!g.includes("*")) continue;
+    const m = path.match(new RegExp("^" + g.split("*").map((s) => s.replace(/[.+^${}()|[\]\\]/g, "\\$&")).join("([^/]*)") + "$"));
+    if (m) return m[1];
+  }
+  return path;
+}
+
+const nested = new AsyncLocalStorage();
+const last = new Map();
+
+/**
+ * Runs one router action with who is acting checked first and carried on the answer. inner is the
+ * router's own call; findDir finds a venture folder. Calls the router makes inside another call
+ * (a view's read, the overview's slots) are checked too, but only the outer call tracks changes.
+ */
+export async function actingCall(a, inner, findDir) {
+  const kind = a.actor ?? "agent", role = a.actor_id ?? process.env.MENTURA_ACTOR_ID;
+  let dir = null;
+  try { dir = a.venture ? findDir(a.venture, a.workspace) : null; } catch {}
+  const check = actingOf(dir, kind, role);
+  const acting = { kind, role: role ?? null };
+  if (!check.ok) return { ok: false, error: check.error, acting };
+  if (nested.getStore()) return { ...(await inner(a)), acting };
+  let changed = null;
+  if (dir) {
+    const key = `${dir}\0${a.via ?? "router"}`, fp = fingerprint(dir, check.who), prev = last.get(key);
+    if (prev && prev.fp !== fp) changed = { from: prev.acting, to: acting, may: reach(dir, role) };
+    last.set(key, { fp, acting });
+  }
+  const r = await nested.run(true, () => inner(a));
+  return { ...r, acting, ...(changed ? { acting_changed: changed } : {}) };
+}

package/interface/adapters/claude-code.json

@@ -0,0 +1,16 @@
+{
+  "name": "claude-code",
+  "title": "Claude Code",
+  "kind": "harness",
+  "integration": "claude-code",
+  "reads": ["CLAUDE.md", ".claude/skills/*/SKILL.md"],
+  "files": [
+    { "path": "CLAUDE.md", "text": "@AGENTS.md\n" }
+  ],
+  "skills": ".claude/skills",
+  "sources": [
+    "https://docs.claude.com/en/docs/claude-code/memory",
+    "https://docs.claude.com/en/docs/claude-code/skills"
+  ],
+  "note": "Claude Code reads CLAUDE.md, which imports the venture's AGENTS.md with @AGENTS.md, and loads project skills from .claude/skills/<name>/SKILL.md. The adapter copies the skill of each package open now, so the agent has the installed version's skill."
+}

package/interface/adapters/codex.json

@@ -0,0 +1,14 @@
+{
+  "name": "codex",
+  "title": "Codex",
+  "kind": "harness",
+  "integration": "codex",
+  "reads": ["AGENTS.md"],
+  "files": [],
+  "skills": null,
+  "sources": [
+    "https://agents.md/",
+    "https://github.com/openai/codex"
+  ],
+  "note": "Codex reads AGENTS.md natively, from the venture root down to the folder it works in, which is the layout chain Naive already writes. Nothing else is needed."
+}

package/interface/adapters/cursor.json

@@ -0,0 +1,16 @@
+{
+  "name": "cursor",
+  "title": "Cursor",
+  "kind": "harness",
+  "integration": "cursor",
+  "reads": ["AGENTS.md", ".cursor/rules/*.mdc"],
+  "files": [
+    { "path": ".cursor/rules/naive.mdc", "text": "---\ndescription: How to work in this Naive venture\nalwaysApply: true\n---\n\nRead AGENTS.md at the venture root, and the AGENTS.md of each folder down to the one you work in, before writing anything. Write records through the router (node interface/cli/mentura.mjs), never by editing files, and never read _private/.\n" }
+  ],
+  "skills": null,
+  "sources": [
+    "https://docs.cursor.com/context/rules",
+    "https://agents.md/"
+  ],
+  "note": "Cursor reads AGENTS.md and project rules in .cursor/rules/. The adapter adds one rule that always applies and points at the AGENTS.md chain."
+}

package/interface/adapters.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+// Adapters (Z-4). Next.js adapters let a platform customize build and deploy, and a verified adapter
+// passes the Next.js test suite. Naive's adapters run the framework on a platform or in an agent
+// harness. Mentura is the first, as Vercel is for Next.js (platform/adapter.json). Claude Code, Codex and
+// Cursor adapt the framework through the venture's AGENTS.md and skills (interface/adapters/*.json):
+// adapt() writes the entry files a harness reads and copies the skills of the packages open now. An
+// adapter is verified when it passes the framework's tests: verify() runs them.
+//
+//   node interface/adapters.mjs [--json]                        the adapters
+//   node interface/adapters.mjs adapt <adapter> <venture dir>   write a harness's files into a venture
+//   node interface/adapters.mjs verify [<adapter>] [--json]     run the framework's tests an adapter must pass
+//
+// adapt() records what it wrote in <venture>/.naive/adapters.json and never overwrites a file it did not
+// write, or one a person changed since: it keeps theirs and says so. An upgrade refreshes the adapters
+// a venture has (schema/upgrades.mjs), so the skill copies follow the installed packages.
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+const repo = new URL("..", import.meta.url).pathname;
+export const STATE = ".naive/adapters.json";
+const load = (p) => JSON.parse(readFileSync(p, "utf8"));
+const sha = (s) => createHash("sha256").update(s).digest("hex");
+
+/** Every adapter: the harness adapters in interface/adapters/, and the platform's if this copy has one. */
+export function adapters() {
+  const d = join(repo, "interface/adapters");
+  const out = existsSync(d) ? readdirSync(d).filter((f) => f.endsWith(".json")).sort().map((f) => ({ ...load(join(d, f)), path: `interface/adapters/${f}` })) : [];
+  if (existsSync(join(repo, "platform/adapter.json"))) out.unshift({ ...load(join(repo, "platform/adapter.json")), path: "platform/adapter.json" });
+  return out;
+}
+const byName = (name) => { const a = adapters().find((x) => x.name === name); if (!a) throw new Error(`no adapter ${name}: ${adapters().map((x) => x.name).join(", ")}`); return a; };
+
+/** The skills of the packages open now in a venture: [{ id, path, package }]. */
+export async function skillsFor(dir) {
+  const { packages } = await import("../schema/packages.mjs");
+  const p = packages(dir);
+  return [...p.core, ...p.handoff].filter((x) => x.in === "now").flatMap((x) => {
+    const f = join(repo, "packages", x.id, "package.json");
+    const s = existsSync(f) ? load(f).skill : null;
+    return s && existsSync(join(repo, s.path)) ? [{ id: s.id, path: s.path, package: x.id }] : [];
+  });
+}
+
+const readState = (dir) => (existsSync(join(dir, STATE)) ? load(join(dir, STATE)) : { adapters: {} });
+
+/**
+ * Writes a harness adapter's files into a venture: its entry files, and a copy of each open package's
+ * skill in its skills folder. Returns what it wrote, what was already current, and what it kept.
+ */
+export async function adapt(dir, name) {
+  if (!existsSync(join(dir, "venture.json"))) throw new Error(`${dir} is not a venture`);
+  const a = byName(name);
+  if (a.kind !== "harness") throw new Error(`${name} is a ${a.kind} adapter: it runs the framework itself and writes nothing into a venture`);
+  const state = readState(dir);
+  const mine = state.adapters[name]?.files ?? {};
+  const want = [...a.files.map((f) => ({ path: f.path, text: f.text }))];
+  if (a.skills) for (const s of await skillsFor(dir)) want.push({ path: `${a.skills}/${s.id}/SKILL.md`, text: readFileSync(join(repo, s.path), "utf8"), skill: s.id, package: s.package });
+  const written = [], current = [], kept = [], files = {};
+  for (const w of want) {
+    const f = join(dir, w.path);
+    const now = existsSync(f) ? readFileSync(f, "utf8") : null;
+    if (now === w.text) { current.push(w.path); files[w.path] = sha(w.text); continue; }
+    // Never overwrite a file a person wrote, or one they changed after the adapter wrote it.
+    if (now !== null && mine[w.path] !== sha(now)) { kept.push({ path: w.path, why: mine[w.path] ? "changed since the adapter wrote it" : "it was there before the adapter" }); if (mine[w.path]) files[w.path] = mine[w.path]; continue; }
+    mkdirSync(dirname(f), { recursive: true });
+    writeFileSync(f, w.text);
+    written.push(w.path);
+    files[w.path] = sha(w.text);
+  }
+  // A skill copy for a package that is no longer open goes, if the adapter wrote it and nobody changed it.
+  const removed = [];
+  for (const [p, h] of Object.entries(mine)) {
+    if (want.some((w) => w.path === p) || !existsSync(join(dir, p))) continue;
+    if (sha(readFileSync(join(dir, p), "utf8")) === h) { rmSync(join(dir, p)); removed.push(p); } else kept.push({ path: p, why: "no longer needed, but changed by a person, so kept" });
+  }
+  state.adapters[name] = { at: new Date().toISOString(), files };
+  mkdirSync(join(dir, ".naive"), { recursive: true });
+  writeFileSync(join(dir, STATE), JSON.stringify(state, null, 2) + "\n");
+  return { adapter: name, written, current, kept, removed, skills: want.filter((w) => w.skill).map((w) => w.skill) };
+}
+
+/** Re-adapts every adapter the venture has, after an upgrade. */
+export async function refresh(dir) {
+  const names = Object.keys(readState(dir).adapters);
+  const out = [];
+  for (const n of names) { try { out.push(await adapt(dir, n)); } catch (e) { out.push({ adapter: n, error: e.message }); } }
+  return out;
+}
+
+// The framework's tests for a harness adapter, run on a new venture in a temporary folder.
+async function harnessSuite(a) {
+  const results = [];
+  const t = (test, passed, detail = "") => results.push({ test, passed: !!passed, detail });
+  const ws = mkdtempSync(join(tmpdir(), `naive-adapter-${a.name}-`));
+  try {
+    const dir = join(ws, "adapted");
+    const init = spawnSync("node", [join(repo, "schema/init-venture.mjs"), dir, "adapted"], { encoding: "utf8" });
+    const up = spawnSync("node", [join(repo, "schema/upgrade-venture.mjs"), dir], { encoding: "utf8" });
+    t("a new venture is created and upgraded to the installed framework", init.status === 0 && up.status === 0, init.stderr + up.stderr);
+    const first = await adapt(dir, a.name);
+    t("every entry file is written with the adapter's text", a.files.every((f) => existsSync(join(dir, f.path)) && readFileSync(join(dir, f.path), "utf8") === f.text), JSON.stringify(first.written));
+    t("the harness reaches the venture's AGENTS.md (it reads it, or an entry file imports or names it)", a.reads.includes("AGENTS.md") || a.files.some((f) => /(^|\s)@AGENTS\.md\b|AGENTS\.md/.test(f.text)));
+    t("no entry file is private or outside the venture", a.files.every((f) => !f.path.startsWith("_private/") && !f.path.includes("..") && !f.path.startsWith("/")));
+    const { call } = await import("./router.mjs");
+    const lay = await call({ venture: "adapted", workspace: ws, route: "foundation/problem", action: "layout" });
+    t("the layout an agent gets starts with the venture's AGENTS.md and its instructions", lay.ok && lay.result.chain[0]?.path === "AGENTS.md" && lay.result.instructions.private === "_private/", lay.error ?? "");
+    if (a.skills) {
+      const want = await skillsFor(dir);
+      t("the venture has packages open now with skills to copy", want.length > 0, "no open package has a skill");
+      t("each open package's skill is copied byte for byte where the harness loads skills", want.every((s) => existsSync(join(dir, a.skills, s.id, "SKILL.md")) && readFileSync(join(dir, a.skills, s.id, "SKILL.md"), "utf8") === readFileSync(join(repo, s.path), "utf8")), JSON.stringify(want.map((s) => s.id)));
+      rmSync(join(dir, a.skills, want[0].id, "SKILL.md"));
+      const back = await refresh(dir);
+      t("a refresh (as after an upgrade) puts a missing skill copy back", back[0]?.written?.includes(`${a.skills}/${want[0].id}/SKILL.md`), JSON.stringify(back));
+    }
+    const again = await adapt(dir, a.name);
+    t("adapting again changes nothing", again.written.length === 0 && again.kept.length === 0, JSON.stringify(again));
+    if (a.files.length) {
+      const f = join(dir, a.files[0].path);
+      writeFileSync(f, readFileSync(f, "utf8") + "\nThe founder's own line.\n");
+      const edited = readFileSync(f, "utf8");
+      const kept = await adapt(dir, a.name);
+      t("a file the founder changed is kept, never overwritten", kept.kept.some((k) => k.path === a.files[0].path) && readFileSync(f, "utf8") === edited, JSON.stringify(kept));
+      const other = join(ws, "own");
+      spawnSync("node", [join(repo, "schema/init-venture.mjs"), other, "own"], { encoding: "utf8" });
+      mkdirSync(dirname(join(other, a.files[0].path)), { recursive: true });
+      writeFileSync(join(other, a.files[0].path), "the founder's own file\n");
+      const theirs = await adapt(other, a.name);
+      t("a file that was there before the adapter is kept", theirs.kept.some((k) => k.path === a.files[0].path) && readFileSync(join(other, a.files[0].path), "utf8") === "the founder's own file\n", JSON.stringify(theirs));
+    }
+  } catch (e) { t("the suite ran to the end", false, String(e.stack ?? e)); }
+  finally { rmSync(ws, { recursive: true, force: true }); }
+  return results;
+}
+
+// A platform adapter runs the framework itself; it is verified by the test programs it names.
+function platformSuite(a) {
+  if (!a.verify?.length) return [{ test: "names the framework tests it must pass", passed: false, detail: "verify is empty" }];
+  return a.verify.map((p) => {
+    if (!existsSync(join(repo, p))) return { test: p, passed: false, detail: "not found" };
+    const r = spawnSync("node", [join(repo, p)], { cwd: repo, encoding: "utf8", timeout: 600000 });
+    const tail = (r.stdout + r.stderr).trim().split("\n").slice(-4).join(" / ");
+    return { test: p, passed: r.status === 0, detail: tail };
+  });
+}
+
+/** Runs the framework's tests for one adapter: { adapter, kind, verified, results }. */
+export async function verify(name) {
+  const a = byName(name);
+  const results = a.kind === "harness" ? await harnessSuite(a) : platformSuite(a);
+  return { adapter: a.name, kind: a.kind, verified: results.every((r) => r.passed), results };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const [cmd, ...rest] = process.argv.slice(2).filter((x) => x !== "--json");
+  const json = process.argv.includes("--json");
+  try {
+    if (!cmd) {
+      const list = adapters().map((a) => ({ name: a.name, title: a.title, kind: a.kind, path: a.path, reads: a.reads }));
+      console.log(json ? JSON.stringify(list, null, 2) : list.map((a) => `${a.name.padEnd(12)} ${a.kind.padEnd(9)} ${a.path}  reads ${a.reads.join(", ")}`).join("\n"));
+    } else if (cmd === "adapt") {
+      const [name, dir] = rest;
+      if (!name || !dir) throw new Error("usage: node interface/adapters.mjs adapt <adapter> <venture dir>");
+      const r = await adapt(dir, name);
+      console.log(json ? JSON.stringify(r, null, 2) : [`adapted for ${r.adapter}: ${r.written.length} written, ${r.current.length} already current, ${r.kept.length} kept${r.skills.length ? `; skills: ${r.skills.join(", ")}` : ""}`,
+        ...r.written.map((p) => `wrote     ${p}`), ...r.kept.map((k) => `kept      ${k.path} (${k.why})`), ...r.removed.map((p) => `removed   ${p}`)].join("\n"));
+    } else if (cmd === "verify") {
+      const names = rest.length ? rest : adapters().map((a) => a.name);
+      const rs = [];
+      for (const n of names) rs.push(await verify(n));
+      if (json) console.log(JSON.stringify(rs, null, 2));
+      else for (const r of rs) {
+        console.log(`${r.verified ? "verified" : "NOT verified"}  ${r.adapter} (${r.kind})`);
+        for (const x of r.results) console.log(`  ${x.passed ? "pass" : "FAIL"}  ${x.test}${x.passed ? "" : `  ${x.detail}`}`);
+      }
+      process.exit(rs.every((r) => r.verified) ? 0 : 1);
+    } else throw new Error("usage: node interface/adapters.mjs [adapt <adapter> <venture dir> | verify [<adapter>]] [--json]");
+  } catch (e) { console.error(e.message); process.exit(1); }
+}

package/interface/api/server.mjs

@@ -0,0 +1,71 @@
+#!/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); a confidence
+//        score computed before the write from x-mentura-confidence
+//   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",
+    // Gate group hook (X-4): x-mentura-confidence carries a score computed before the write, for the gate's confidence rules.
+    provenance: { derived_from: h("x-mentura-derived-from")?.split(",").map((x) => x.trim()).filter(Boolean), decision: h("x-mentura-decision"), confidence: h("x-mentura-confidence"),
+      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}`));
+}