naive-framework 0.1.0 → 0.3.0

package/interface/mcp/server.mjs

@@ -10,6 +10,7 @@
 
 import { createInterface } from "node:readline";
 import { call, routes, routesMd, ventureDir, ventures } from "../router.mjs";
+import { runStreaming } from "../context.mjs";
 import { propose } from "../../schema/decisions.mjs";
 
 const PROTOCOL = "2025-06-18";
@@ -20,17 +21,42 @@ export const TOOLS = [
   { name: "mentura_layout", description: "The context for a route before you act on it: the system, layer and kit purpose, skills and references, the schema and template, the gate, and what need-now says about the record.", inputSchema: { type: "object", properties: { venture, route }, required: ["route"] } },
   { name: "mentura_view", description: "A route as a Markdown page for a person. system/overview shows the venture at a glance.", inputSchema: { type: "object", properties: { venture, route }, required: ["venture", "route"] } },
   { name: "mentura_ventures", description: "The ventures in the workspace, with their phase.", inputSchema: { type: "object", properties: {} } },
-  { name: "mentura_read", description: "Read one record of a venture. Returns null when the venture has no such record yet.", inputSchema: { type: "object", properties: { venture, route }, required: ["venture", "route"] } },
+  { name: "mentura_read", description: "Read one record of a venture, header first: the header (what it is, its state, owner and size in tokens), the budget, the layout (in a session, only the parts you have not seen), the template (need-now and open decisions, fresh), the record as result (null when the venture has no such record yet), and prefetch: short summaries of the routes you are likely to need next. Pass header_only to stop after the header. A list returns only the items your role may read.", inputSchema: { type: "object", properties: { venture, route,
+    session: { type: "string", description: "Your session id: the layout is sent once per session, then only the parts that changed" },
+    task: { type: "string", description: "What you are doing; a route it names is prefetched in full" },
+    prefetch: { description: "false turns prefetch off; a list of routes prefetches those in full", oneOf: [{ type: "boolean" }, { type: "array", items: { type: "string" } }] },
+    header_only: { type: "boolean", description: "Return only the header, to decide whether to read on" },
+    where: { type: "object", description: "For a list: keep only records whose fields match these values" },
+    agent_id: { type: "string", description: "Your role in the team plan, so its read routes apply" } }, required: ["venture", "route"] } },
   { name: "mentura_write", description: "Write one record of a venture. The record must match its schema. A gated record is written as a draft under _drafts/ for a person to accept. Every write is logged in the venture's provenance log: say what the content came from and the decision it acts under.", inputSchema: { type: "object", properties: { venture, route, record: { type: "object", description: "The whole record" },
     derived_from: { type: "array", items: { type: "string" }, description: "What the content came from: venture-relative paths, URLs or decision ids" },
     decision: { type: "string", description: "The decision the write acts under, such as EE-026" },
     model: { type: "string", description: "Your model, for the provenance log" }, note: { type: "string" },
-    agent_id: { type: "string", description: "Your role in the team plan, so its routes and unlocks apply" } }, required: ["venture", "route", "record"] } },
+    agent_id: { type: "string", description: "Your role in the team plan, so its routes and unlocks apply" },
+    // Gate group hook (X-4): a score computed before the write; the gate's confidence rules read it and never compute one.
+    confidence: { type: "number", description: "Your confidence in this record, 0 to 1, if you computed one. Below the venture's threshold, a gate rule may send the write to its function owner" } }, required: ["venture", "route", "record"] } },
   { name: "mentura_decisions", description: "The decisions a venture owes (EE-054): each with its parent, boundary, phase, due time and whether it renders now, is overdue, waits, comes later, is stale or deferred. Work on what renders now or overdue; a decision that waits is held by an open fail-closed decision above it. A route a pending decision unlocks is refused until a person decides it.", inputSchema: { type: "object", properties: { venture,
     render: { type: "array", items: { type: "string" }, description: "Only these states, such as [\"overdue\", \"now\"]" } }, required: ["venture"] } },
   { name: "mentura_propose_decision", description: "Propose a decision, or new wording for an open one. It stays open until a person approves it in the CLI (mentura decide); you can never mark a decision decided. Put it beside what it decides with at (a venture folder such as operations) and name (<record>[.<topic>]).", inputSchema: { type: "object", properties: { venture,
     decision: { type: "object", description: "id, question, and optionally answer (your proposed wording), decides, layer, parent, needed_in, due, outcomes, unlocks, note, plus at and name for where it goes" },
     agent_id: { type: "string", description: "Your role in the team plan" }, model: { type: "string" } }, required: ["venture", "decision"] } },
+  // Setup (EE-083, interface/skills/naive-setup): the questions that establish a new venture, in order, and an artifact of the progress.
+  { name: "mentura_setup", description: "Where a new venture's setup stands: its people and hats, the source of truth for each function, the foundation and first decisions (the docket), the goal for discovery, and which steps are done. artifact is that state as one self-contained HTML page: render it as an artifact where your harness has artifacts, and again after every answer. Ask the founder the next open question, one at a time, in order.", inputSchema: { type: "object", properties: { venture }, required: ["venture"] } },
+  { name: "mentura_setup_answer", description: "Write down the founder's answer to one setup question (a docket id from mentura_setup, or discovery-goal), exactly in their words. It is proposed with their words as its wording and stays open until the founder confirms it at the keyboard (naive setup confirm): you never decide for them.", inputSchema: { type: "object", properties: { venture,
+    id: { type: "string", description: "The question's id from mentura_setup's docket, or discovery-goal" },
+    answer: { type: "string", description: "The founder's answer, verbatim" },
+    agent_id: { type: "string", description: "Your role in the team plan" }, model: { type: "string" } }, required: ["venture", "id", "answer"] } },
+  { name: "mentura_setup_point", description: "Point one function of the venture at the system that holds its truth (from mentura_setup's catalog), as the founder said, such as finance at rho or products at github with address acme/app. Naive keeps a pointer, never a copy; Rho is synced at once.", inputSchema: { type: "object", properties: { venture,
+    function: { type: "string", description: "A function, such as products, finance or legal" },
+    system: { type: "string", description: "A system the catalog offers for that function" },
+    address: { type: "string", description: "Where in that system, such as acme/app" },
+    agent_id: { type: "string", description: "Your role in the team plan" } }, required: ["venture", "function", "system"] } },
+  // The decision library (schema/frames.mjs): a founder's problem matched to a frame, its premises judged, its decisions proposed.
+  { name: "mentura_frame", description: "When the founder states a problem in their own words (\"I need investors to scale but I don't want to give up control\"), match it to a frame in the decision library, judge the premises their sentence assumes against the venture's records, and propose the decisions hidden in it, open, with options. The result says which premises hold, whether the trade is false, real or a sequence, and the better question to ask. Never pick an option for the founder, and never name an instrument as the answer: options for how to do something come from a dated, cited lookup.", inputSchema: { type: "object", properties: { venture,
+    text: { type: "string", description: "The founder's words, verbatim" },
+    frame: { type: "string", description: "A frame id, when you already know it; otherwise the founder's words pick one" },
+    lookup: { type: "object", description: "Options a lookup found: { options: [{ option, source, as_of }] }; only dated, cited options within the frame's freshness are kept" },
+    agent_id: { type: "string", description: "Your role in the team plan" }, model: { type: "string" } } } },
   { name: "mentura_check", description: "Run the checks for one record of a venture.", inputSchema: { type: "object", properties: { venture, route }, required: ["venture", "route"] } },
   { name: "mentura_template", description: "The fill-in template for a record, where its kit has one.", inputSchema: { type: "object", properties: { route }, required: ["route"] } },
   { name: "mentura_run", description: "Run a command route for a venture: system/need-now (what to work on now), system/time-to-ready, purpose/validation/assess (what the problem's evidence is strong enough for), governance/payouts, knowledge/catalog (index every source the venture keeps records in), knowledge/search (find items in any of them). A result with needs_input lists what is missing: ask the person whether to fill it in or run as is, and only then call again with as_is.", inputSchema: { type: "object", properties: { venture, route, value: { type: ["number", "string"], description: "governance/payouts: a sale value; knowledge/search: the query" },
@@ -40,7 +66,8 @@ export const TOOLS = [
 
 let client = null; // the harness, as it named itself at initialize
 
-export async function handle(msg) {
+// notify sends a notification to the client; progress for a call that carries _meta.progressToken (N-5).
+export async function handle(msg, notify = () => {}) {
   const { id, method, params = {} } = msg;
   const reply = (result) => ({ jsonrpc: "2.0", id, result });
   const fail = (code, message) => ({ jsonrpc: "2.0", id, error: { code, message } });
@@ -54,15 +81,26 @@ export async function handle(msg) {
     case "tools/list": return reply({ tools: TOOLS });
     case "tools/call": {
       const a = params.arguments ?? {};
+      const token = params._meta?.progressToken;
+      let step = 0;
+      const progress = token === undefined ? null : ({ progress: p, total, message }) => notify({ jsonrpc: "2.0", method: "notifications/progress", params: { progressToken: token, progress: Math.max(p ?? 0, ++step), ...(total ? { total } : {}), message } });
       let r;
       switch (params.name) {
         case "mentura_routes": r = { ok: true, result: a.group ? routes().filter((x) => x.groups.includes(`(${a.group})`)) : routes() }; break;
         case "mentura_ventures": r = { ok: true, result: ventures().map(({ id, name, phase, path }) => ({ id, name, phase, path })) }; break;
         case "mentura_layout": r = await call({ venture: a.venture, route: a.route, action: "layout" }); break;
         case "mentura_view": r = await call({ venture: a.venture, route: a.route, action: "view" }); break;
-        case "mentura_read": r = await call({ venture: a.venture, route: a.route, action: "read" }); break;
+        // Context hook (interface/context.mjs): a read is a navigation, header first, its parts streamed as progress.
+        // A filtered list (where) is a plain read (interface/writes.mjs); anything else is a navigation.
+        case "mentura_read": r = a.where ? await call({ venture: a.venture, route: a.route, action: "read", actor_id: a.agent_id, via: "mcp", input: { where: a.where } }) : await call({ venture: a.venture, route: a.route, action: "navigate", actor_id: a.agent_id, via: "mcp",
+          input: { session: a.session, task: a.task, prefetch: a.prefetch, header_only: a.header_only, ...(progress ? { onPart: ({ part, data }) => progress({ message: `${part}: ${JSON.stringify(data)}` }) } : {}) } }); break;
         case "mentura_write": r = await call({ venture: a.venture, route: a.route, action: "write", input: a.record, actor: "agent", actor_id: a.agent_id, via: "mcp",
-          provenance: { derived_from: a.derived_from, decision: a.decision, note: a.note, agent: Object.fromEntries(Object.entries({ harness: client, model: a.model }).filter(([, v]) => v)) } }); break;
+          provenance: { derived_from: a.derived_from, decision: a.decision, note: a.note, confidence: a.confidence, agent: Object.fromEntries(Object.entries({ harness: client, model: a.model }).filter(([, v]) => v)) } }); break;
+        // Setup (EE-083): schema/setup.mjs holds the questions; answers are proposals the founder confirms.
+        case "mentura_setup": { const m = await import("../../schema/setup.mjs"); const dir = ventureDir(a.venture); r = { ok: true, result: { state: await m.state(dir), artifact: await m.artifact(dir) } }; break; }
+        case "mentura_setup_answer": r = await (await import("../../schema/setup.mjs")).relay(ventureDir(a.venture), { id: a.id, answer: a.answer, agentId: a.agent_id, harness: client, model: a.model }); break;
+        case "mentura_setup_point": r = await (await import("../../schema/setup.mjs")).point(ventureDir(a.venture), { fn: a.function, system: a.system, address: a.address, via: "mcp", actor: "agent", agentId: a.agent_id }); break;
+        case "mentura_frame": r = await (await import("../../schema/frames.mjs")).run(ventureDir(a.venture), { id: a.frame, text: a.text, lookup: a.lookup, agentId: a.agent_id ?? "frames", harness: client, model: a.model }); break;
         case "mentura_decisions": {
           r = await call({ venture: a.venture, route: "governance/decisions", action: "run", actor_id: a.agent_id });
           if (r.ok && a.render?.length) r.result = { ...r.result, decisions: r.result.decisions.filter((d) => a.render.includes(d.render)) };
@@ -75,7 +113,9 @@ export async function handle(msg) {
         }
         case "mentura_check": r = await call({ venture: a.venture, route: a.route, action: "check" }); break;
         case "mentura_template": r = await call({ route: a.route, action: "template" }); break;
-        case "mentura_run": r = await call({ venture: a.venture, route: a.route, action: "run", actor_id: a.agent_id, input: a.value !== undefined || a.as_is ? { ...(a.value !== undefined ? { value: a.value } : {}), ...(a.as_is ? { as_is: true } : {}) } : undefined }); break;
+        case "mentura_run": r = progress && a.route !== "system/overview" && a.route !== "system/robots"
+          ? await runStreaming({ venture: a.venture, route: a.route, input: { value: a.value, as_is: a.as_is }, actor_id: a.agent_id }, progress)
+          : await call({ venture: a.venture, route: a.route, action: "run", actor_id: a.agent_id, input: a.value !== undefined || a.as_is ? { ...(a.value !== undefined ? { value: a.value } : {}), ...(a.as_is ? { as_is: true } : {}) } : undefined }); break;
         default: return fail(-32602, `unknown tool ${params.name}`);
       }
       if (r.ok && r.needs_input) return reply({ content: [{ type: "text", text: `Ask the person before running. ${r.needs_input.ask}\n${JSON.stringify(r.needs_input, null, 2)}` }], isError: false });
@@ -115,7 +155,7 @@ if (import.meta.url === `file://${process.argv[1]}`) {
       let msg;
       try { msg = JSON.parse(line); } catch { process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } }) + "\n"); return; }
       let res;
-      try { res = await handle(msg); } catch (e) { res = { jsonrpc: "2.0", id: msg.id ?? null, error: { code: -32603, message: String(e.message ?? e) } }; }
+      try { res = await handle(msg, (n) => process.stdout.write(JSON.stringify(n) + "\n")); } catch (e) { res = { jsonrpc: "2.0", id: msg.id ?? null, error: { code: -32603, message: String(e.message ?? e) } }; }
       if (res) process.stdout.write(JSON.stringify(res) + "\n");
     });
   });

package/interface/package-routes.mjs

@@ -0,0 +1,197 @@
+// Package routes, route groups and slot defaults (Next.js translation L-6, P-17, P-36, P-37, and the
+// venture route for P-3). The router reaches these when a route is not in the route table, so the
+// table, generated from the data model, stays as it is.
+//
+//   <package>            a package's own route (validation, foundation, marketing; packages/<name> works
+//                        for every package, even one whose name is also a record route such as product).
+//                        read returns its records and their state: progress, what moves now, what waits,
+//                        and the drafts pending in it (its loading state, P-37). check runs its boundary
+//                        (E-5). view is the same as a page. layout is its group's and its own context.
+//   (<group>)            a route group (P-36): packages that share a layout, so they share context. The
+//                        framework defines (go-to-market) for marketing, relationships and customers; a
+//                        venture adds or changes groups in naive.config.json "groups", and may keep the
+//                        group's own AGENTS.md in a (<group>)/ folder at its root. Only the packages in a
+//                        group get its layout: the layout is opt-in.
+//   venture              the venture's own route: read is the manifest venture.json declares (P-3), check
+//                        runs every boundary (E-5).
+//   @packages            the system/overview slot: each package in use, and for a package with nothing in
+//                        it, its default: what to write first and where to start (P-17).
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { ventureFile } from "../schema/venture-paths.mjs";
+
+const repo = new URL("..", import.meta.url).pathname;
+const load = (f) => JSON.parse(readFileSync(f, "utf8"));
+
+/** The framework's route groups (P-36). A venture's naive.config.json "groups" adds to or replaces these. */
+export const GROUPS = {
+  "go-to-market": { packages: ["marketing", "relationships", "customers"], context: "Who the venture sells to and how it reaches them. Marketing and sales share the ICP, the offer and the accounts, so they share one layout." },
+};
+
+export const packageNames = () => existsSync(join(repo, "packages")) ? readdirSync(join(repo, "packages")).filter((n) => existsSync(join(repo, "packages", n, "package.json"))) : [];
+export const packageDef = (n) => load(join(repo, "packages", n, "package.json"));
+
+/** The venture's route groups: the framework's, then its own from naive.config.json. */
+export function groupsOf(dir) {
+  const f = dir && join(ventureFile(dir, "naive.config.json"));
+  const own = f && existsSync(f) ? load(f).groups ?? {} : {};
+  return { ...GROUPS, ...own };
+}
+
+/** The package a record type lives in: its core home first, else the data or folder package that declares it. */
+export function packageOfRecord(type) {
+  if (!type) return null;
+  const names = packageNames();
+  const core = names.find((n) => { const p = packageDef(n); return p.kind === "core" && [...(p.required ?? []), ...(p.optional ?? [])].includes(type); });
+  if (core) return core;
+  return names.find((n) => { const p = packageDef(n); return p.kind !== "handoff" && (p.records ?? []).includes(type); }) ?? null;
+}
+
+/** The group layout a package gets (P-36), or null when it is in no group. */
+export function groupLayout(pkg, dir) {
+  const gs = groupsOf(dir);
+  const id = Object.keys(gs).find((g) => (gs[g].packages ?? []).includes(pkg));
+  if (!id) return null;
+  const g = gs[id];
+  const agents = dir && existsSync(join(dir, `(${id})`, "AGENTS.md")) ? `(${id})/AGENTS.md` : null;
+  const shares = [...new Set(g.packages.filter((n) => packageNames().includes(n)).flatMap((n) => packageDef(n).refs ?? []))];
+  return { group: `(${id})`, packages: g.packages, context: g.context ?? null, shares, agents };
+}
+
+/** Which special route a name is: a package, a group or the venture. */
+export function special(route) {
+  if (route === "venture") return { kind: "venture" };
+  const g = route.match(/^\(([a-z0-9-]+)\)$/);
+  if (g) return { kind: "group", id: g[1] };
+  const name = route.startsWith("packages/") ? route.slice("packages/".length) : route;
+  return packageNames().includes(name) ? { kind: "package", name } : null;
+}
+
+/** The route of a record type: its item or single route, else its list route. */
+export const routeOfType = async (type) => {
+  const { routes } = await import("./router.mjs");
+  const rs = routes().filter((r) => r.record === type);
+  return (rs.find((r) => r.collection !== "list") ?? rs[0])?.route ?? null;
+};
+
+// The drafts waiting in a package's records (P-37): its pending state.
+async function pendingIn(dir, types, venture) {
+  const { recordOf } = await import("../schema/decisions.mjs");
+  const { entries } = await import("./provenance.mjs");
+  const d = join(ventureFile(dir, "_drafts"));
+  if (!existsSync(d)) return [];
+  const log = entries(dir);
+  const out = [];
+  for (const f of readdirSync(d).filter((x) => x.endsWith(".draft"))) {
+    const file = f.slice(0, -".draft".length).replace(/__/g, "/");
+    const type = recordOf(file);
+    if (!types.includes(type)) continue;
+    const route = await routeOfType(type);
+    const id = route?.endsWith("[id]") ? file.split("/").at(-1).replace(/\.json$/, "") : null;
+    const concrete = id ? route.replace("[id]", id) : route;
+    out.push({ record: type, route: concrete, draft: `_drafts/${f}`, since: log.filter((e) => e.entity === `_drafts/${f}`).at(-1)?.at ?? null, accept: `mentura accept ${concrete} --venture ${venture}` });
+  }
+  return out;
+}
+
+/** A package's own route read (L-6, P-37): its records and their state, what moves now, what waits, what is pending. */
+export async function packageState(dir, name, venture) {
+  const def = packageDef(name);
+  const { packages } = await import("../schema/packages.mjs");
+  const all = packages(dir);
+  const p = [...all.core, ...all.handoff].find((x) => x.id === name);
+  if (p?.kind === "core") {
+    const records = await Promise.all(p.records.map(async (r) => ({ record: r.record, title: r.title, role: r.role, route: await routeOfType(r.record), status: r.status, moves: r.moves, ...(r.waits_on ? { waits_on: r.waits_on } : {}), files: r.files })));
+    const pending = await pendingIn(dir, p.records.filter((r) => r.role !== "reads").map((r) => r.record), venture);
+    return { package: name, kind: "core", title: p.title, purpose: p.purpose, function: def.function ?? def.department ?? null, fit: p.fit, in: p.in, state: p.state, progress: p.progress,
+      records, moves_now: records.filter((r) => r.moves === "now" && r.role !== "reads").map((r) => r.route), waits: records.filter((r) => r.moves === "waits").map((r) => ({ route: r.route, on: r.waits_on })),
+      loading: pending.length ? { drafts: pending, note: `${pending.length} draft${pending.length > 1 ? "s" : ""} waiting for a person to accept` } : null, unlocks: p.unlocks, missing: p.missing, to_review: p.to_review };
+  }
+  if (p?.kind === "handoff") return { package: name, kind: "handoff", title: p.title, for: p.for, from: p.from, fit: p.fit, in: p.in, state: p.state, progress: p.progress, waits_on: p.waits_on, unlocks: p.unlocks, loading: null };
+  // Data, folder and raw packages: never complete; their state is what they hold.
+  const { routes, glob } = await import("./router.mjs");
+  const { files } = await import("./router.mjs");
+  const here = files(dir);
+  const records = await Promise.all((def.records ?? []).map(async (t) => {
+    const r = routes().find((x) => x.record === t);
+    const held = r ? here.filter((f) => r.files.some((g) => glob(g).test(f))) : [];
+    return { record: t, route: await routeOfType(t), items: held.length, files: held };
+  }));
+  const pending = await pendingIn(dir, def.records ?? [], venture);
+  return { package: name, kind: def.kind, title: def.title, purpose: def.purpose, state: records.some((r) => r.items) ? "holding" : "empty", records, gates: def.gates ?? [],
+    loading: pending.length ? { drafts: pending, note: `${pending.length} draft${pending.length > 1 ? "s" : ""} waiting for a person to accept` } : null };
+}
+
+/** The overview's @packages slot (P-17): each package in use, and the default a package with nothing in it shows. */
+export async function packageSlots(dir, venture) {
+  const { manifest } = await import("../schema/structure.mjs");
+  const m = await manifest(dir);
+  const out = [];
+  for (const { name, known } of m.packages.list) {
+    if (!known) { out.push({ package: name, shows: "not a Naive package: check venture.json packages" }); continue; }
+    const s = await packageState(dir, name, venture);
+    const empty = s.kind === "core" ? s.records.filter((r) => r.role !== "reads").every((r) => r.status === "missing") : s.kind === "handoff" ? false : s.state === "empty";
+    if (!empty) { out.push({ package: name, title: s.title, state: s.state, progress: s.progress ?? null, moving: (s.moves_now ?? []).join(", ") || "none" }); continue; }
+    // The default: nothing written yet, and where to start.
+    const first = s.kind === "core" ? s.records.find((r) => r.role === "required" && r.moves === "now") ?? s.records.find((r) => r.role !== "reads") : s.records[0];
+    const route = first?.route ?? null;
+    const concrete = route?.endsWith("[id]") ? route.replace("[id]", "<id>") : route;
+    const { routes } = await import("./router.mjs");
+    const acts = routes().find((x) => x.route === route)?.actions ?? [];
+    const write = acts.includes("write") ? `mentura ${concrete} write --venture ${venture} --input <file>` : null;
+    const start = !concrete ? null : acts.includes("template") ? `mentura ${concrete} template${write ? `, then ${write}` : ""}` : write ?? `mentura ${concrete} layout --venture ${venture}`;
+    out.push({ package: name, title: s.title, default: true, shows: `${s.title}: nothing written yet`, start });
+  }
+  return out;
+}
+
+const pageOf = (s) => {
+  const lines = [`# ${s.title ?? s.package}`, "", s.purpose ?? "", ""];
+  if (s.state) lines.push(`State: ${s.state}${s.progress != null ? ` (${Math.round(s.progress * 100)}%)` : ""}.`, "");
+  if (s.loading) lines.push(`> ${s.loading.note}: ${s.loading.drafts.map((d) => `\`${d.accept}\``).join(", ")}`, "");
+  if (s.records?.length) {
+    const cols = s.kind === "core" ? ["route", "role", "status", "moves"] : ["route", "items"];
+    lines.push(`| ${cols.join(" | ")} |`, `| ${cols.map(() => "---").join(" | ")} |`, ...s.records.map((r) => `| ${cols.map((c) => String(r[c] ?? "")).join(" | ")} |`), "");
+  }
+  return lines.join("\n").replace(/\n{3,}/g, "\n\n").trim() + "\n";
+};
+
+/** Answers a call to a package, group or venture route; null when the route is none of them. */
+export async function specialCall({ venture, route, action, workspace }) {
+  const sp = special(route);
+  if (!sp) return null;
+  const { ventureDir } = await import("./router.mjs");
+  const actions = sp.kind === "group" ? ["read", "view", "layout"] : ["read", "view", "check", "layout"];
+  if (!actions.includes(action)) return { ok: false, error: `${route} has no action ${action} (it has ${actions.join(", ")})` };
+  const dir = venture ? ventureDir(venture, workspace) : null;
+  if (!dir && !(action === "layout" && sp.kind !== "venture")) return { ok: false, error: `no venture ${venture}` };
+  if (sp.kind === "venture") {
+    const { manifest } = await import("../schema/structure.mjs");
+    const { boundaries } = await import("./boundaries.mjs");
+    if (action === "check") { const b = await boundaries(dir); return { ok: b.ok, result: b }; }
+    const m = await manifest(dir);
+    if (action === "view") return { ok: true, result: `# ${m.identity.name}\n\nPhase: ${m.phase}. Packages: ${m.packages.list.map((p) => p.name).join(", ")}.\n\n| Function | Owner | Packages |\n| --- | --- | --- |\n${m.functions.map((f) => `| ${f.function} | ${f.owner ?? "nobody yet"} | ${f.packages.join(", ")} |`).join("\n")}\n` };
+    if (action === "layout") return { ok: true, result: { route: "venture", manifest: m } };
+    return { ok: true, result: m };
+  }
+  if (sp.kind === "group") {
+    const gs = groupsOf(dir);
+    const g = gs[sp.id];
+    if (!g) return { ok: false, error: `no route group (${sp.id}): the groups are ${Object.keys(gs).map((x) => `(${x})`).join(", ")}` };
+    const lay = groupLayout(g.packages[0], dir);
+    if (action === "layout" || !dir) return { ok: true, result: { ...lay, chain: lay.agents && dir ? [{ path: lay.agents, text: readFileSync(ventureFile(dir, lay.agents), "utf8") }] : [] } };
+    const states = [];
+    for (const n of g.packages.filter((x) => packageNames().includes(x))) states.push(await packageState(dir, n, venture));
+    const res = { group: `(${sp.id})`, context: g.context ?? null, packages: states.map((s) => ({ package: s.package, state: s.state, progress: s.progress ?? null, pending: s.loading?.drafts.length ?? 0 })) };
+    return { ok: true, result: action === "view" ? `# (${sp.id})\n\n${res.context ?? ""}\n\n${res.packages.map((p) => `- ${p.package}: ${p.state}${p.progress != null ? ` (${Math.round(p.progress * 100)}%)` : ""}${p.pending ? `, ${p.pending} pending` : ""}`).join("\n")}\n` : res };
+  }
+  const name = sp.name;
+  if (action === "layout") {
+    const def = packageDef(name);
+    return { ok: true, result: { route: name, package: { name, title: def.title, purpose: def.purpose, function: def.function ?? def.department ?? null, skill: def.skill?.path ?? null, gates: def.gates ?? [] }, group: groupLayout(name, dir) } };
+  }
+  if (action === "check") { const { boundaries } = await import("./boundaries.mjs"); const b = await boundaries(dir, { only: [name] }); return { ok: b.packages.every((p) => p.ok), result: b.packages[0] ?? { package: name, ok: true, note: "not in use by this venture" } }; }
+  const s = await packageState(dir, name, venture);
+  return action === "view" ? { ok: true, result: pageOf(s) } : { ok: true, result: s, ...(s.loading ? { pending_drafts: s.loading.drafts } : {}) };
+}

package/interface/provenance.mjs

@@ -5,8 +5,11 @@
 // written outside the router.
 
 import { createHash } from "node:crypto";
-import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { emit } from "./instrumentation.mjs";
+import { ventureFile } from "../schema/venture-paths.mjs";
 
 export const LOG = "provenance.jsonl";
 const sha = (s) => createHash("sha256").update(s).digest("hex");
@@ -15,7 +18,7 @@ export const lineHash = (prev, entry) => { const { hash, ...rest } = entry; retu
 export const contentHash = (file) => sha(readFileSync(file));
 
 export function entries(dir) {
-  const f = join(dir, LOG);
+  const f = ventureFile(dir, LOG);
   return existsSync(f) ? readFileSync(f, "utf8").split("\n").filter((l) => l.trim()).map((l) => JSON.parse(l)) : [];
 }
 
@@ -35,8 +38,29 @@ export function record(dir, { entity, route, activity, agent, derived_from, deci
   const prior = entries(dir);
   const prev = prior.length ? prior.at(-1).hash : "genesis";
   const entry = Object.fromEntries(Object.entries({ at: new Date().toISOString(), entity, route, activity, agent,
-    derived_from: derived_from?.length ? derived_from : undefined, decision, note, source, statement, sha256: sha256 ?? contentHash(join(dir, entity)), prev }).filter(([, v]) => v !== undefined));
+    derived_from: derived_from?.length ? derived_from : undefined, decision, note, source, statement, sha256: sha256 ?? contentHash(ventureFile(dir, entity)), prev }).filter(([, v]) => v !== undefined));
   entry.hash = lineHash(prev, entry);
-  appendFileSync(join(dir, LOG), JSON.stringify(entry) + "\n");
+  appendFileSync(ventureFile(dir, LOG), JSON.stringify(entry) + "\n");
+  // Context hook: every provenance entry (write, draft, accept, confirm, decision) is an instrumentation event (P-4).
+  emit(dir, { kind: "provenance", activity: entry.activity, entity: entry.entity, route: entry.route, decision: entry.decision, by: entry.agent?.kind, via: entry.agent?.via });
+  fireTriggers(dir);
   return entry;
 }
+
+// Triggers hook (M-12, E-7): every entry is an event. A venture whose naive.config.json has triggers or
+// kits runs them (schema/triggers.mjs) in a separate process after the write; the runs themselves do
+// not fire this again. A crash of that process is kept for the next run to raise, never lost.
+function fireTriggers(dir) {
+  if (process.env.NAIVE_TRIGGERS_ACTIVE) return;
+  let cfg;
+  try { cfg = JSON.parse(readFileSync(join(ventureFile(dir, "naive.config.json")), "utf8")); } catch { return; }
+  if (!cfg?.triggers?.length && !cfg?.kits?.length) return;
+  // The write has landed; nothing here may undo it or throw past it.
+  try {
+    const p = spawnSync(process.execPath, [new URL("../schema/triggers.mjs", import.meta.url).pathname, dir, "--fire", "--quiet"], { encoding: "utf8", env: { ...process.env, NAIVE_TRIGGERS_ACTIVE: "hook" } });
+    if (p.status !== 0) {
+      mkdirSync(join(dir, ".naive"), { recursive: true });
+      appendFileSync(join(dir, ".naive/trigger-errors.jsonl"), JSON.stringify({ at: new Date().toISOString(), status: p.status, error: (p.stderr || p.stdout || String(p.error ?? "")).trim().slice(-2000) }) + "\n");
+    }
+  } catch (e) { console.error(`triggers did not run after this write: ${e.message}`); }
+}

package/interface/reads.mjs

@@ -0,0 +1,174 @@
+// What a read answers besides the record (Next.js translation L-9, L-10, O-1, O-2, O-3, P-28). The
+// router's wrapper (interface/writes.mjs) adds these to every read and layout. Code computes all of
+// it from the files and the provenance log; no model writes any of it.
+//
+//   params     L-9   the dynamic segment's value ({ id: "kettle" } for product/kettle), given to the
+//                    read and to every layout below it: the item's own folder AGENTS.md joins the
+//                    chain, and "[id]" in an instruction becomes the id, so a product's layout knows
+//                    which product
+//   where      L-10  route inputs that change what a read returns: input.where { status, phase,
+//                    function, state, or any field by dot path }. A list keeps the items that match;
+//                    a single record that does not match comes back null with filtered_out
+//   metadata   O-1   the static metadata: the venture's identity from venture.json and the record's
+//                    own frontmatter (Markdown) or title
+//              O-2   derived fields, computed by code from the record: counts, the phase, the
+//                    function and its owner, and its state (confirmed, agent, draft, unlogged)
+//              O-3   the fields the framework adds to every record without being asked: id,
+//                    created, updated, and who wrote it last (person or agent), from provenance
+//   hierarchy  P-28  the order the router resolves a read: layout (context), template (fresh
+//                    context), error (failed checks), loading (pending drafts), not-found (missing
+//                    record), then page (the record). resolved_by names the level that answered;
+//                    input.hierarchy returns every level
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { entries } from "./provenance.mjs";
+import { ventureFile } from "../schema/venture-paths.mjs";
+
+const load = (f) => JSON.parse(readFileSync(f, "utf8"));
+const get = (o, p) => p.split(".").reduce((x, k) => (x == null ? undefined : x[k]), o);
+
+/** Simple YAML frontmatter: key: value lines between --- fences. Lists in [a, b] form become arrays. */
+export function frontmatter(text) {
+  const m = typeof text === "string" ? text.match(/^---\n([\s\S]*?)\n---\n?/) : null;
+  if (!m) return null;
+  const out = {};
+  for (const line of m[1].split("\n")) {
+    const kv = line.match(/^([A-Za-z_][\w-]*)\s*:\s*(.*)$/);
+    if (!kv) continue;
+    let v = kv[2].trim().replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1");
+    if (/^\[.*\]$/.test(v)) v = v.slice(1, -1).split(",").map((x) => x.trim()).filter(Boolean);
+    out[kv[1]] = v;
+  }
+  return out;
+}
+
+/** A record's state from the log and the drafts folder (O-2). */
+export async function stateOf(dir, file) {
+  const { confirmedIn } = await import("../schema/foundation.mjs");
+  if (existsSync(join(ventureFile(dir, "_drafts"), `${file.replace(/\//g, "__")}.draft`))) return "draft";
+  const es = entries(dir).filter((e) => e.entity === file);
+  if (!es.length) return "unlogged";
+  return confirmedIn(dir, file, null) ? "confirmed" : "agent";
+}
+
+/** The fields every record gets (O-3): id, created, updated and who wrote it last, from the provenance log, else the file. */
+export function defaults(dir, file, id) {
+  const es = entries(dir).filter((e) => e.entity === file);
+  if (es.length) {
+    const last = es.at(-1);
+    return { id, created: es[0].at, updated: last.at, by: { kind: last.agent?.kind ?? null, ...(last.agent?.id ? { id: last.agent.id } : {}), via: last.agent?.via ?? null }, activity: last.activity, writes: es.length, from: "provenance" };
+  }
+  const st = existsSync(ventureFile(dir, file)) ? statSync(ventureFile(dir, file)) : null;
+  return { id, created: st ? new Date(st.birthtimeMs || st.mtimeMs).toISOString() : null, updated: st ? st.mtime.toISOString() : null, by: null, writes: 0, from: "file", note: "written outside the router: mentura baseline adopts it into the log" };
+}
+
+/** Counts derived from a record (O-2): the length of each top-level list. */
+const countsOf = (v) => v && typeof v === "object" && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).filter(([, x]) => Array.isArray(x)).map(([k, x]) => [k, x.length])) : {};
+
+/** The function owning a record and its owner (O-2), from the package that holds it and venture.json's functions. */
+export async function ownerOf(dir, type) {
+  const { packageOfRecord, packageDef } = await import("./package-routes.mjs");
+  const pkg = packageOfRecord(type);
+  const def = pkg ? packageDef(pkg) : null;
+  const fn = def?.function ?? def?.department ?? null;
+  const v = load(join(dir, "venture.json"));
+  const owner = fn ? v.functions?.[fn]?.owner ?? (!(v.members?.length) ? "the founder" : null) : null;
+  return { package: pkg, function: fn, owner };
+}
+
+/** The metadata a read answers with (O-1, O-2, O-3). items maps each id to its venture-relative file. */
+export async function metadataFor({ dir, r, route, params, result, items }) {
+  const v = load(join(dir, "venture.json"));
+  const fn = await ownerOf(dir, r.record);
+  const one = async (id, file, value) => ({
+    ...defaults(dir, file, id),
+    ...(file.endsWith(".md") || file.endsWith(".mdx") ? { frontmatter: frontmatter(value) } : value && typeof value === "object" && (value.title || value.name) ? { title: value.title ?? value.name } : {}),
+    derived: { state: await stateOf(dir, file), counts: countsOf(value) },
+  });
+  const base = {
+    venture: { id: v.id, name: v.name, phase: v.phase, status: v.status },
+    record: { type: r.record, route, schema: r.schema ?? null, form: r.form },
+    derived: { phase: v.phase, function: fn.function, owner: fn.owner, package: fn.package, by: "code" },
+  };
+  if (r.collection === "list") {
+    const per = {};
+    for (const [id, file] of Object.entries(items)) per[id] = await one(id, file, result?.[id]);
+    return { ...base, derived: { ...base.derived, count: Object.keys(per).length }, items: per };
+  }
+  const [id, file] = Object.entries(items)[0] ?? [];
+  if (!file) return base;
+  const own = await one(params.id ?? r.record, file, result);
+  return { ...base, ...own, derived: { ...base.derived, ...own.derived } };
+}
+
+// One filter test: a field by dot path on the record, else a derived field.
+function matches(value, meta, where) {
+  return Object.entries(where).every(([k, want]) => {
+    let have = get(value ?? {}, k);
+    if (have === undefined) have = { state: meta?.derived?.state, function: meta?.function, owner: meta?.owner, phase: meta?.phase }[k];
+    const wants = Array.isArray(want) ? want.map(String) : [String(want)];
+    return Array.isArray(have) ? have.some((x) => wants.includes(String(typeof x === "object" ? x?.id ?? x?.name : x))) : have !== undefined && have !== null && wants.includes(String(have));
+  });
+}
+
+/** Applies input.where to a read answer (L-10): a list keeps matching items; a record that does not match comes back null. */
+export function filterRead(answer, where, r) {
+  if (!where || typeof where !== "object" || !Object.keys(where).length || answer.result == null) return answer;
+  const md = answer.metadata ?? {};
+  const shared = { function: md.derived?.function, owner: md.derived?.owner, phase: md.venture?.phase };
+  if (r.collection === "list") {
+    const keep = Object.keys(answer.result).filter((id) => matches(answer.result[id], { ...shared, derived: md.items?.[id]?.derived }, where));
+    const pick = (o) => o ? Object.fromEntries(Object.entries(o).filter(([id]) => keep.includes(id))) : o;
+    return { ...answer, result: pick(answer.result), sources: pick(answer.sources), ...(md.items ? { metadata: { ...md, items: pick(md.items), derived: { ...md.derived, count: keep.length } } } : {}), filtered: { where, matched: keep.length, of: Object.keys(answer.result).length } };
+  }
+  if (matches(answer.result, { ...shared, derived: md.derived }, where)) return { ...answer, filtered: { where, matched: 1, of: 1 } };
+  return { ...answer, result: null, filtered_out: { where, note: "the record exists but does not match the filter" } };
+}
+
+const parseInstructions = (chain) => {
+  const out = {};
+  for (const f of chain) for (const line of f.text.split("\n")) { const m = line.match(/^([a-z][a-z0-9_-]*)\s*:\s*(.+)$/); if (m) out[m[1]] = m[2].trim(); }
+  return out;
+};
+
+/**
+ * The layout with params (L-9) and its group (P-36): the group's AGENTS.md after the venture root's,
+ * then the item's own folders' AGENTS.md, nearest last; "[id]" in an instruction becomes the id.
+ */
+export function withParams(layout, { dir, params, file, group }) {
+  const chain = [...(layout.chain ?? [])];
+  const have = new Set(chain.map((c) => c.path));
+  const add = (rel, at = chain.length) => { if (dir && !have.has(rel) && existsSync(ventureFile(dir, rel))) { chain.splice(at, 0, { path: rel, text: readFileSync(ventureFile(dir, rel), "utf8") }); have.add(rel); } };
+  if (group?.agents) add(group.agents, chain.findIndex((c) => c.path === "AGENTS.md") + 1);
+  if (file) {
+    const parts = dirname(file).split("/").filter((p) => p && p !== ".");
+    let acc = "";
+    for (const p of parts) { acc = acc ? `${acc}/${p}` : p; add(`${acc}/AGENTS.md`); }
+  }
+  const instructions = parseInstructions(chain);
+  if (params?.id) for (const k of Object.keys(instructions)) instructions[k] = instructions[k].replace(/\[id\]/g, params.id);
+  return { ...layout, chain, instructions, params: params ?? {}, ...(group ? { group } : {}) };
+}
+
+/** The read's hierarchy (P-28), outermost first, and the level that answered. */
+export function hierarchy({ answer, layout }) {
+  const levels = [
+    { level: "layout", holds: layout ? { chain: layout.chain.map((c) => c.path), stack: layout.stack?.map((s) => s.name) } : null },
+    { level: "template", holds: layout ? { need_now: layout.need_now ?? null, gate: layout.gate ?? null, note: "recomputed on every action" } : null },
+    { level: "error", caught: !answer.ok || !!answer.errors, holds: !answer.ok ? { error: answer.error, fix: answer.fix ?? null } : answer.errors ?? null },
+    { level: "loading", caught: !!(answer.pending_draft || answer.pending_pull_requests), holds: answer.pending_draft ?? answer.pending_pull_requests ?? null },
+    { level: "not-found", caught: answer.ok && answer.result === null && !!answer.not_found, holds: answer.not_found ?? null },
+    { level: "page", caught: answer.ok && answer.result !== null && answer.result !== undefined, holds: answer.ok && answer.result != null ? "the record" : null },
+  ];
+  return { levels, resolved_by: resolvedBy(answer) };
+}
+
+/** The level that answered a read (P-28): error, then loading, then not-found, then page. */
+export function resolvedBy(answer) {
+  if (!answer.ok) return "error";
+  if (answer.pending_draft || answer.pending_pull_requests) return "loading";
+  if (answer.result === null && answer.not_found) return "not-found";
+  if (answer.result === null && answer.filtered_out) return "page";
+  return "page";
+}

package/interface/release-card.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// Draws a release card (P-25, O-7). The card's data is assembled by code from the release's records
+// (schema/releases.mjs cardOf, written to <venture>/.release/card.json); drawing it is the interface's
+// job, so the picture lives here and never in the release. It is a 1200 by 630 SVG, the size link
+// previews use, with the venture's name, phase, headline numbers with their dates, and who confirmed them.
+//
+//   node interface/release-card.mjs <venture dir>     prints the SVG
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ventureFile } from "../schema/venture-paths.mjs";
+
+const esc = (s) => String(s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+const day = (t) => (t ? String(t).slice(0, 10) : "");
+
+/** The card as SVG text. */
+export function svg(card) {
+  const nums = card.headline.filter((h) => h.label !== "Live holes").slice(0, 4);
+  const cell = (h, i) => {
+    const x = 60 + i * 275;
+    return `<text x="${x}" y="330" font-size="64" font-weight="700" fill="#111">${esc(h.value)}${h.unit ? `<tspan font-size="24"> ${esc(h.unit)}</tspan>` : ""}</text>
+  <text x="${x}" y="370" font-size="22" fill="#333">${esc(h.label)}</text>
+  <text x="${x}" y="400" font-size="18" fill="#666">as of ${esc(day(h.as_of))}</text>`;
+  };
+  const by = card.confirmed_by.length ? `Confirmed by ${card.confirmed_by.join(", ")}` : "Nothing confirmed yet";
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630" font-family="system-ui, sans-serif" role="img" aria-label="${esc(card.name)} release card">
+  <rect width="1200" height="630" fill="#fafaf7"/>
+  <rect x="0" y="0" width="1200" height="12" fill="#1f6f5c"/>
+  <text x="60" y="120" font-size="64" font-weight="700" fill="#111">${esc(card.name)}</text>
+  <text x="60" y="175" font-size="28" fill="#333">Phase: ${esc(card.phase)}</text>
+  ${nums.map(cell).join("\n  ")}
+  <text x="60" y="520" font-size="22" fill="#333">${esc(by)}</text>
+  <text x="60" y="560" font-size="18" fill="#666">Release ${esc(card.release)}, built ${esc(day(card.built_at))}</text>
+</svg>
+`;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const dir = process.argv[2];
+  const f = dir && join(ventureFile(dir, ".release/card.json"));
+  if (!f || !existsSync(f)) { console.error("usage: node interface/release-card.mjs <venture dir> (after node schema/build-release.mjs)"); process.exit(2); }
+  process.stdout.write(svg(JSON.parse(readFileSync(f, "utf8"))));
+}