naive-framework 0.0.0-stage → 0.2.0

package/interface/mcp/server.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+// The MCP server over the router (EE-030): stdio, newline-delimited JSON-RPC 2.0, no dependencies.
+// Tools are the router's actions; resources are the route table and each venture's records.
+// Every caller here is an agent: write never takes an actor, so a gated record (ownership, board,
+// founder agreement, exit, telos, decision rights, publication policy) is always written as a
+// draft for a person to accept. Nothing an agent sends through this server can approve itself.
+//
+//   claude mcp add mentura -- node <repo>/interface/mcp/server.mjs
+//   MENTURA_WORKSPACE=<dir> sets the workspace; the default is this repository's instance/.
+
+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";
+const venture = { type: "string", description: "The venture's id, or its folder path for a nested venture (see mentura_ventures)" };
+const route = { type: "string", description: "A route from mentura_routes, such as purpose/validation/problem" };
+export const TOOLS = [
+  { name: "mentura_routes", description: "The route table: every record and command a venture has, with its actions, decision classes and groups. A collection item is <route>/<id>, such as purpose/product/kettle.", inputSchema: { type: "object", properties: { group: { type: "string", description: "Only the routes need-now suggests in this phase: discovery, validation, beachhead, scale or platform" } } } },
+  { 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, 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" },
+    // 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" },
+    as_is: { type: "boolean", description: "purpose/validation/assess: run even though the record is incomplete. Set it only after the person chose to run as is" },
+    agent_id: { type: "string", description: "Your role in the team plan" } }, required: ["venture", "route"] } },
+];
+
+let client = null; // the harness, as it named itself at initialize
+
+// 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 } });
+  switch (method) {
+    case "initialize":
+      client = params.clientInfo ? [params.clientInfo.name, params.clientInfo.version].filter(Boolean).join(" ") : null;
+      return reply({ protocolVersion: PROTOCOL, capabilities: { tools: {}, resources: {} }, serverInfo: { name: "mentura", version: "0.1.0" },
+        instructions: "Start with mentura_decisions to see which decisions are due and what is held, then mentura_run on system/need-now to see what a venture needs now, so you build only that. Read before you write. Gated records are drafts until a person accepts them." });
+    case "notifications/initialized": case "notifications/cancelled": return null;
+    case "ping": return reply({});
+    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;
+        // 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, 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)) };
+          break;
+        }
+        case "mentura_propose_decision": {
+          const dir = ventureDir(a.venture);
+          r = dir ? propose(dir, a.decision, { agentId: a.agent_id, via: "mcp", harness: client, model: a.model }) : { ok: false, error: `no venture ${a.venture}` };
+          break;
+        }
+        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 = 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 });
+      const extra = ["not_found", "pending_draft", "fix", "deprecated"].some((k) => r[k]);
+      const text = r.ok ? (typeof r.result === "string" && !extra ? r.result : JSON.stringify(extra ? r : r.result, null, 2)) : JSON.stringify({ error: r.error, ...(r.fix ? { fix: r.fix } : {}), ...(r.result ? { result: r.result } : {}) }, null, 2);
+      return reply({ content: [{ type: "text", text }], isError: !r.ok });
+    }
+    case "resources/list":
+      return reply({ resources: [
+        { uri: "mentura://routes", name: "Route table", mimeType: "text/markdown" },
+        ...ventures().map((v) => ({ uri: `mentura://${v.id}`, name: `${v.id}: overview`, mimeType: "text/markdown" })),
+        ...ventures().flatMap((v) => routes().filter((x) => x.kind === "record" && !x.route.endsWith("[id]")).map((x) => ({ uri: `mentura://${v.id}/${x.route}`, name: `${v.id}: ${x.route}`, mimeType: "application/json" }))),
+      ] });
+    case "resources/read": {
+      const uri = params.uri ?? "";
+      if (uri === "mentura://routes") return reply({ contents: [{ uri, mimeType: "text/markdown", text: routesMd() }] });
+      const o = uri.match(/^mentura:\/\/([^/]+)$/);
+      if (o) { const r = await call({ venture: o[1], route: "system/overview", action: "view" }); return r.ok ? reply({ contents: [{ uri, mimeType: "text/markdown", text: r.result }] }) : fail(-32602, r.error); }
+      const m = uri.match(/^mentura:\/\/([^/]+)\/(.+)$/);
+      if (!m) return fail(-32602, `unknown resource ${uri}`);
+      const r = await call({ venture: m[1], route: m[2], action: "read" });
+      if (!r.ok) return fail(-32602, r.error);
+      return reply({ contents: [{ uri, mimeType: "application/json", text: JSON.stringify(r.result, null, 2) }] });
+    }
+    default:
+      return id === undefined ? null : fail(-32601, `method not found: ${method}`);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const rl = createInterface({ input: process.stdin });
+  // Answers go out in the order requests came in: each line waits for the one before.
+  let queue = Promise.resolve();
+  rl.on("line", (line) => {
+    if (!line.trim()) return;
+    queue = queue.then(async () => {
+      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, (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/operator-console/README.md

@@ -0,0 +1,58 @@
+---
+type: entity-readme
+ai-model: claude
+entity-name: operator-console
+companion-to: "[[project-view-mockup-2026-05-14.html]]"
+source: hybrid
+created: 2026-05-14
+last-reviewed: 2026-05-14
+authorship: hybrid
+authors: [the author, Claude]
+ip-sensitivity: normal
+scope: global
+scope-entity: "[[everything-ecosystem]]"
+tags: [operator-console, methodology-product, orchestration-software, mockup, html-companion, 2026-05-14]
+---
+
+# `operator-console/` — The Operator Console
+
+*Renamed from `harness/` on 2026-10-26 (G-029): "harness" now means only the entity class for a first-party interface over a product.*
+
+> Working folder for the operator console — the operational software layered on top of the SAD methodology. Per §39, the trajectory is HTML now → real software later. The first mockup is **[[project-view-mockup-2026-05-14.html]]**. Open it in a browser.
+
+## What this is
+
+The operator console is the methodology's operational consumer surface. It's the dashboard a solo operator (or eventually a multi-person team) lives in when managing projects under the methodology. Distinct from:
+
+- **The methodology itself** ([[pipeline-canonical-view-2026-05-14]]) — the abstract framework
+- **The methodology website** (separate concern; for publishing + teaching + onboarding to the public)
+- **Per-entity orchestration HTML** ([[per-entity-orchestration-template]]) — the static, vault-embedded version of similar information
+
+The operator console is a polished SaaS-style application that surfaces project state, agent activity, and methodology mechanisms (skills, commands, hooks) for the operator.
+
+## Current state
+
+- **[[project-view-mockup-2026-05-14.html]]** — high-fidelity static mockup of the project-level view (the reference project as the demonstrative project)
+- Topbar with project switcher; left sidebar with project + operations + methodology nav groups; main area showing three-pillar prominence + agent system panel + recent decisions + quick action cards
+
+## Trajectory
+
+Per §39 orchestration trajectory:
+
+- **Now:** static HTML mockup for design iteration
+- **Next:** real web app (Next.js + Postgres likely), bespoke for the owner's solo use initially
+- **Later:** multi-person team support (auth, real-time collaboration, role-based access)
+- **Eventually:** publicly available methodology product (when the methodology generalizes beyond the reference project)
+
+Paused as of 2026-05-14 to return to the reference project work. Will resume after V1.5 articulation has more shape.
+
+## Related
+
+- [[pipeline-canonical-view-2026-05-14]] — the methodology the operator console operationalizes
+- [[per-entity-orchestration-template]] — vault-embedded parallel artifact (less polished, more comprehensive)
+- A project note — the orchestration HTML instance the operator console mockup demonstrates against
+- [[build-roadmap-and-html-orchestration-2026-05-12]] §32 + §39 — methodology amendments establishing the operator console concept
+
+## Status
+
+- **2026-05-14:** Initial mockup authored; paused to return to the reference project V1.5 work.

package/interface/package-routes.mjs

@@ -0,0 +1,196 @@
+// 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";
+
+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(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(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(join(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

@@ -0,0 +1,65 @@
+// The provenance log (EE-031): one append-only JSON line per write, after W3C PROV (entity,
+// activity, agent, derived from). Each line carries the previous line's hash, so an edited or
+// deleted line breaks the chain. Lives at <venture>/provenance.jsonl, in the system layer, so it
+// is on whatever layers a venture uses. Git history stays the implicit provenance for anything
+// written outside the router.
+
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { emit } from "./instrumentation.mjs";
+
+export const LOG = "provenance.jsonl";
+const sha = (s) => createHash("sha256").update(s).digest("hex");
+const sorted = (x) => Array.isArray(x) ? x.map(sorted) : x && typeof x === "object" ? Object.fromEntries(Object.keys(x).sort().map((k) => [k, sorted(x[k])])) : x;
+export const lineHash = (prev, entry) => { const { hash, ...rest } = entry; return sha(prev + JSON.stringify(sorted(rest))); };
+export const contentHash = (file) => sha(readFileSync(file));
+
+export function entries(dir) {
+  const f = join(dir, LOG);
+  return existsSync(f) ? readFileSync(f, "utf8").split("\n").filter((l) => l.trim()).map((l) => JSON.parse(l)) : [];
+}
+
+/** The agent behind this process: MENTURA_ACTOR (person or agent), MENTURA_ACTOR_ID, MENTURA_MODEL, MENTURA_SESSION, MENTURA_HARNESS. */
+export function agentFromEnv(kind, via, extra = {}) {
+  const e = process.env;
+  const a = { kind, via, id: e.MENTURA_ACTOR_ID, model: kind === "agent" ? e.MENTURA_MODEL : undefined, session: e.MENTURA_SESSION, harness: e.MENTURA_HARNESS, ...extra };
+  return Object.fromEntries(Object.entries(a).filter(([, v]) => v));
+}
+
+/**
+ * Appends one entry for a file just written: a path relative to the venture folder, or, for a
+ * record in another source (EE-037), its address (<source>://<path>) with the content's sha256
+ * and the source's version, commit and pull request.
+ */
+export function record(dir, { entity, route, activity, agent, derived_from, decision, note, sha256, source, statement }) {
+  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));
+  entry.hash = lineHash(prev, entry);
+  appendFileSync(join(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(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}`); }
+}