naive-framework 0.1.0 → 0.2.0

package/interface/skills/naive-setup/SKILL.md

@@ -0,0 +1,71 @@
+---
+type: knowledge
+tags: [everything-ecosystem, naive, skills, interface, setup, artifacts, docket]
+ai-model: claude-opus-5.5
+created: 2026-10-29T06:30:00Z
+source: hybrid
+name: naive-setup
+description: >
+  Walk a founder through setting up a new Naive venture inside the model's own
+  harness: their people and hats, where each function keeps its truth, the
+  strategic foundation and first decisions, and a goal for discovery. Show the
+  progress as a Claude artifact where the harness has artifacts (EE-083).
+  MANDATORY TRIGGERS: set up my venture, naive setup, finish setup, walk me
+  through setup, I just ran create-venture, establish my venture, structure my
+  business, what do I do after create-venture.
+---
+
+# Naive setup
+
+Interface layer (EE-083). `create-venture` scaffolds the venture. This skill finishes the job in conversation. You ask the questions, the founder answers in their own words, and Naive writes each answer as a decision or a source-of-truth pointer, with provenance. The progress is a view the harness renders, not a server Naive runs. In Claude, it is an artifact.
+
+The questions and their order come from Naive, not from you. Read them from `mentura_setup` (MCP) or `node schema/setup.mjs <venture dir> state`, and never invent a question.
+
+## 1. Read the state
+
+Call `mentura_setup` with the venture id. The result has:
+
+- `state`: the people, sources of truth, docket and goal, plus `steps` (which of the four are done), `done`, and `counts`.
+- `artifact`: the state, already rendered into `interface/skills/naive-setup/artifact.html`, as one self-contained HTML page.
+
+Without MCP, run `node schema/setup.mjs <venture dir> state` and `node schema/setup.mjs <venture dir> artifact`.
+
+## 2. Show it
+
+- **Claude (claude.ai, the desktop app, or Claude Code with the Artifact tool):** render `artifact` as an HTML artifact. Do not edit its contents; it is generated. Render it again after every answer, so the founder sees the progress bar move.
+- **A harness without artifacts:** show the four steps as a short checklist in Markdown, with the next open question underneath.
+
+## 3. Ask one question at a time, in order
+
+Work through the first step that is not done, and ask only its next open question:
+
+1. **People and hats.** If `state.people` is missing, ask for the founder's name, role, and whether they are solo or a team. A solo founder wears every hat. These come from `create-venture`. If they are missing, tell the founder to run `npx create-venture` again with `--name`, `--role` and `--team`. Do not write `people/` by hand.
+2. **Sources of truth.** For each function, ask where its truth lives, offering the systems in `state.catalog.functions[<function>]`. Write each answer with `mentura_setup_point` (`function`, `system`, and an `address` such as `acme/app`). If the founder has nothing for a function yet, leave it unpointed and move on. For legal, if there are no documents, say so and name the options in the catalog.
+3. **Foundation and first decisions.** These are the `state.docket` items whose status is not `decided`, taken in order. Ask the question as written. If it has options, offer them, but take the founder's own words. Write the answer with `mentura_setup_answer` (`id` and `answer`).
+4. **A goal for discovery.** Ask what must be true for the venture to leave discovery. Write it with `mentura_setup_answer`, using `id: "discovery-goal"`.
+
+## 4. The founder's words, not yours
+
+- Pass the founder's answer exactly as they wrote it. Do not polish it, summarize it, or fill in an answer they did not give.
+- If an answer is unclear, ask a follow-up question. Do not guess.
+- A foundation statement is the founder's to state. If they ask you to draft one, show the draft and ask them to accept it or rewrite it in their own words. Write it only after they reply, and write what they replied.
+
+## 5. When every step is done
+
+`state.done` is true. Render the artifact one last time: it shows "Your venture is structured." Then tell the founder, in a few lines:
+
+- the venture now has its people, its sources of truth, its foundation and first decisions, and a discovery goal;
+- how many decisions wait for later phases (`state.later`); the docket brings each one up when it matters;
+- each next decision should be oriented around the discovery goal;
+- to operate the business day to day, with a team and agents, they use Mentura. Naive is the structure; Mentura is where it runs, the way a Next.js app is deployed on Vercel.
+
+## Without a model
+
+The same steps run from the command line:
+
+```sh
+node schema/setup.mjs ~/ventures/acme state
+node schema/setup.mjs ~/ventures/acme point finance rho
+node schema/setup.mjs ~/ventures/acme answer discovery-goal "Ten clinic owners confirm the scheduling problem by December"
+node schema/setup.mjs ~/ventures/acme artifact > setup.html
+```

package/interface/skills/naive-setup/artifact.html

@@ -0,0 +1,83 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Venture setup</title>
+<style>
+:root { --bg:#f6f7f4; --panel:#fff; --fg:#1d2320; --muted:#5d675f; --line:#d9ded8; --accent:#2f6b4f; --accent-soft:#e3efe8; --warn:#8a5a00; --warn-soft:#f6ecd8;
+  --body: system-ui, -apple-system, "Segoe UI", sans-serif; --mono: ui-monospace, "SF Mono", Menlo, monospace; color-scheme: light; }
+@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --bg:#121614; --panel:#1a201d; --fg:#e4e9e5; --muted:#9aa59d; --line:#2b332e; --accent:#86c4a3; --accent-soft:#1d2b24; --warn:#e3b25c; --warn-soft:#2c2414; color-scheme: dark; } }
+:root[data-theme="dark"] { --bg:#121614; --panel:#1a201d; --fg:#e4e9e5; --muted:#9aa59d; --line:#2b332e; --accent:#86c4a3; --accent-soft:#1d2b24; --warn:#e3b25c; --warn-soft:#2c2414; color-scheme: dark; }
+* { box-sizing: border-box }
+body { margin:0; background:var(--bg); color:var(--fg); font:16px/1.55 var(--body); }
+.wrap { max-width: 820px; margin: 0 auto; padding: 28px 16px 64px; display: grid; gap: 22px; }
+header { display:grid; gap:6px } h1 { margin:0; font-size:1.7rem; letter-spacing:-.01em } h2 { margin:0 0 2px; font-size:1.1rem }
+.muted { color: var(--muted) } .mono { font-family: var(--mono); font-size: .86em; overflow-wrap: anywhere }
+.bar { height: 8px; border-radius: 999px; background: var(--line); overflow: hidden } .bar > div { height: 100%; background: var(--accent) }
+.steps { display:flex; gap:6px; flex-wrap:wrap } .step { font:600 .76rem/1 var(--mono); padding:6px 9px; border-radius:999px; border:1px solid var(--line); color:var(--muted) }
+.step.ok { background: var(--accent-soft); color: var(--accent); border-color: transparent } .step.next { border-color: var(--accent); color: var(--accent) }
+section { background: var(--panel); border:1px solid var(--line); border-radius:10px; padding:18px; display:grid; gap:12px; min-width: 0 }
+.table { overflow-x: auto } table { width:100%; border-collapse: collapse; font-size:.93rem }
+td.mono { white-space: nowrap }
+td, th { text-align:left; padding:7px 6px; border-bottom:1px solid var(--line); vertical-align: top }
+th { font: 600 .72rem/1.2 var(--mono); text-transform: uppercase; letter-spacing:.05em; color: var(--muted) }
+.pill { display:inline-block; font:600 .72rem/1.2 var(--mono); padding:4px 7px; border-radius:999px; background: var(--accent-soft); color: var(--accent); margin: 0 4px 4px 0 }
+.pill.pointed { background: var(--line); color: var(--fg) } .pill.none { background: var(--warn-soft); color: var(--warn) }
+.card { border:1px solid var(--line); border-radius:8px; padding:12px; display:grid; gap:6px } .card.done { opacity:.7 } .card.next { border-color: var(--accent) }
+.q { font-weight:600 } .hint { font-size:.88rem; color: var(--muted) }
+.celebrate { text-align:center; padding: 28px 18px; background: var(--accent-soft); border-color: transparent }
+.celebrate .big { font-size: 1.9rem; font-weight: 700; color: var(--accent) } ol { margin:0; padding-left: 1.2em; display:grid; gap:6px; text-align:left }
+</style>
+</head>
+<body>
+<div class="wrap" id="app"></div>
+<script id="naive-setup-state" type="application/json">__NAIVE_SETUP_STATE__</script>
+<script>
+// A view of the venture's setup state, filled in by `node schema/setup.mjs <venture dir> artifact`.
+// It reads nothing from the network and writes nothing: the founder answers in the chat, the model writes
+// each answer through Naive, and renders this page again.
+const S = JSON.parse(document.getElementById("naive-setup-state").textContent);
+const esc = (s) => String(s ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+const st = S.steps, v = S.venture;
+const order = [["people", "People and hats"], ["truth", "Sources of truth"], ["docket", "Foundation and first decisions"], ["goal", "A goal for discovery"]];
+const next = order.find(([k]) => !st[k])?.[0];
+const doneCount = order.filter(([k]) => st[k]).length;
+const label = ([k, t]) => '<span class="step ' + (st[k] ? "ok" : k === next ? "next" : "") + '">' + (st[k] ? "&#10003; " : "") + t + "</span>";
+
+const people = S.people
+  ? '<div class="table"><table><tr><th>Person</th><th>Role</th><th>Hats</th></tr>' + S.people.people.map((p) => "<tr><td>" + esc(p.name) + '</td><td class="mono">' + esc(p.role) + "</td><td>" + (p.hats.map((h) => '<span class="pill pointed">' + esc(h) + "</span>").join("") || '<span class="muted">none</span>') + "</td></tr>").join("") + "</table></div>"
+  : '<p class="muted">Nobody is listed yet. Tell me your name, your role, and whether you are solo or a team.</p>';
+
+const fns = [...new Set([...Object.keys(S.catalog.functions).filter((f) => f === "legal" || (S.people?.people ?? []).some((p) => p.hats.includes(f))), ...Object.keys(S.functions)])];
+const systemsOf = (f) => { const x = S.functions[f]; return x?.systems?.length ? x.systems.map((s) => '<span class="pill ' + (s.status === "connected" ? "" : "pointed") + '">' + esc(S.catalog.systems[s.system]?.label ?? s.system) + (s.address ? " &middot; " + esc(s.address) : "") + " &middot; " + esc(s.status) + (s.fixture ? " (fixture)" : "") + "</span>").join("") : '<span class="pill none">not pointed yet</span>'; };
+const offered = (f) => (S.catalog.functions[f] ?? []).map((s) => esc(S.catalog.systems[s]?.label ?? s)).join(", ");
+const truth = '<div class="table"><table><tr><th>Function</th><th>Source of truth</th><th>You can point it at</th></tr>' + fns.map((f) => "<tr><td>" + esc(f) + "</td><td>" + systemsOf(f) + '</td><td class="hint">' + offered(f) + "</td></tr>").join("") + "</table></div>";
+
+const open = S.docket.filter((d) => d.status !== "decided");
+const cards = S.docket.map((d) => '<div class="card ' + (d.status === "decided" ? "done" : d === open[0] ? "next" : "") + '"><div class="q">' + esc(d.question) + "</div>"
+  + (d.status === "decided" ? "<div>&#10003; " + esc(d.answer) + "</div>"
+    : d.relayed ? "<div>" + esc(d.answer) + '</div><div class="hint">Your answer, waiting for you to confirm it.</div>'
+
+    : (d.options.length ? '<div class="hint">Options: ' + d.options.map(esc).join(" / ") + "</div>" : "") + '<div class="hint">Answer in the chat, in your own words.</div>')
+  + "</div>").join("");
+
+const goal = S.goal?.status === "decided" ? "<p>&#10003; " + esc(S.goal.answer) + "</p>" : S.goal?.relayed ? "<p>" + esc(S.goal.answer) + '</p><p class="hint">Your answer, waiting for you to confirm it.</p>' : '<p class="muted">What must be true for ' + esc(v.name) + " to leave discovery? For example: ten clinic owners confirm the scheduling problem in interviews by December.</p>";
+
+const done = S.done
+  ? '<section class="celebrate"><div class="big">Your venture is structured.</div><p>' + esc(v.name) + " has its people and their hats, a source of truth for each function, a settled foundation and first decisions, and a goal for discovery. Every decision from here routes through the docket.</p><ol>"
+    + "<li>Orient each next decision around the discovery goal.</li><li>" + (S.later ? S.later + " more decisions wait for later phases; the docket brings each one up when it matters." : "The docket brings up each new decision when it matters.") + "</li><li>To operate the business day to day, with your team and your agents, use Mentura.</li></ol></section>"
+  : "";
+
+document.getElementById("app").innerHTML =
+  '<header><span class="muted mono">' + esc(v.type?.label ?? "venture") + " &middot; " + esc(v.phase) + "</span><h1>Set up " + esc(v.name) + '</h1><p class="muted">The structure of your venture, step by step. Answer in the chat; each answer is saved as a decision, and this page updates.</p>'
+  + '<div class="bar" role="progressbar" aria-valuemin="0" aria-valuemax="4" aria-valuenow="' + doneCount + '"><div style="width:' + doneCount * 25 + '%"></div></div><div class="steps">' + order.map(label).join("") + "</div></header>"
+  + (S.waiting.length ? '<section><h2>' + S.waiting.length + (S.waiting.length === 1 ? " answer waits" : " answers wait") + ' for you</h2><p class="muted">The model wrote these down from your words. They become your decisions when you confirm them yourself: run <span class="mono">npx naive setup confirm</span> in the venture.</p></section>' : "")
+  + done
+  + "<section><h2>1. People and hats</h2>" + people + "</section>"
+  + '<section><h2>2. Sources of truth</h2><p class="muted">Where each function keeps its truth. Naive keeps pointers, never copies.</p>' + truth + "</section>"
+  + '<section><h2>3. Foundation and first decisions</h2><p class="muted">The decision docket: ' + S.counts.settled + " of " + S.counts.of + " settled.</p>" + cards + "</section>"
+  + "<section><h2>4. A goal for discovery</h2>" + goal + "</section>";
+</script>
+</body>
+</html>

package/interface/vitals.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// Agent vitals (N-6): Naive's Core Web Vitals. Where Next.js measures time to first byte and time to
+// interactive, Naive measures what it costs an agent to get work done through the router:
+//
+//   calls_per_task      router calls an agent makes in one session (a task)
+//   tokens_per_call     tokens of context each call sends back
+//   time_to_useful_ms   time from a session's first call to its first useful answer
+//   decision_hours      time from a decision opening to a person deciding it (open ones count their age)
+//
+// Like Web Vitals, each is assessed at the 75th percentile and checked against a threshold (C-15),
+// so vitals are checked, not only measured. Calls and judgments come from the events log that
+// instrumentation writes (interface/instrumentation.mjs); decisions come from provenance.jsonl, so
+// decision latency is measured even with instrumentation off. Thresholds are the defaults below,
+// overridden by "vitals" in the venture's naive.config.json.
+//
+//   node interface/vitals.mjs <venture dir> [--json] [--check]     --check exits 1 when a vital fails
+//   node interface/vitals.mjs <venture dir> --trace [--session <id>] the events as a trace, for
+//                                                                   platform/integrations/langsmith.mjs
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { events } from "./instrumentation.mjs";
+import { entries } from "./provenance.mjs";
+
+export const THRESHOLDS = { calls_per_task: 25, tokens_per_call: 6000, time_to_useful_ms: 10000, decision_hours: 72 };
+const DECISION = /(^|\/)decisions\/[^/]+\.decision\.json$/;
+
+/** The 75th percentile, nearest rank. */
+export const p75 = (xs) => { if (!xs.length) return null; const s = [...xs].sort((a, b) => a - b); return s[Math.ceil(0.75 * s.length) - 1]; };
+const startOf = (e) => Date.parse(e.at) - (e.ms ?? 0);
+const config = (dir) => { const f = join(dir, "naive.config.json"); try { return existsSync(f) ? JSON.parse(readFileSync(f, "utf8")) : {}; } catch { return {}; } };
+
+/** Top-level calls grouped by session: one task per session. */
+export function tasks(dir) {
+  const calls = events(dir).filter((e) => e.kind === "call" && !e.parent);
+  const judgments = events(dir).filter((e) => e.kind === "judgment");
+  const by = new Map();
+  for (const e of calls) { const k = e.session ?? "(no session)"; if (!by.has(k)) by.set(k, []); by.get(k).push(e); }
+  return [...by.entries()].map(([session, es]) => {
+    const t0 = Math.min(...es.map(startOf));
+    const useful = es.filter((e) => e.useful).sort((a, b) => Date.parse(a.at) - Date.parse(b.at))[0];
+    return { session, calls: es.length, tokens_per_call: Math.round(es.reduce((n, e) => n + (e.tokens ?? 0), 0) / es.length), max_tokens: Math.max(...es.map((e) => e.tokens ?? 0)),
+      time_to_useful_ms: useful ? Date.parse(useful.at) - t0 : null, judgments: judgments.filter((j) => (j.session ?? "(no session)") === session).length };
+  });
+}
+
+/** Each decision the provenance log saw open: when it opened, when a person decided it, and the hours between. */
+export function decisionLatency(dir, now = Date.now()) {
+  const by = new Map();
+  for (const e of entries(dir).filter((x) => DECISION.test(x.entity ?? ""))) {
+    const d = by.get(e.entity) ?? { file: e.entity, opened: null, decided: null };
+    if (!d.opened) d.opened = e.at;
+    if (e.activity === "accept" && !d.decided) d.decided = e.at;
+    by.set(e.entity, d);
+  }
+  return [...by.values()].map((d) => {
+    let id = d.file.split("/").at(-1).replace(/\.decision\.json$/, "");
+    try { id = JSON.parse(readFileSync(join(dir, d.file), "utf8")).id ?? id; } catch {}
+    const end = d.decided ? Date.parse(d.decided) : now;
+    return { id, ...d, open: !d.decided, hours: Math.round(((end - Date.parse(d.opened)) / 36e5) * 100) / 100 };
+  });
+}
+
+/** The venture's vitals, each at p75 against its threshold. */
+export function vitals(dir, now = Date.now()) {
+  const limits = { ...THRESHOLDS, ...(config(dir).vitals ?? {}) };
+  const ts = tasks(dir), ds = decisionLatency(dir, now);
+  const measure = (name, xs, never = 0) => {
+    const v = p75(xs);
+    const n = xs.length + never;
+    const passed = n === 0 ? null : never > 0 && never / n > 0.25 ? false : v === null ? false : v <= limits[name];
+    return { p75: v, threshold: limits[name], n, passed, status: passed === null ? "no data" : passed ? "good" : "needs work", ...(never ? { never_useful: never } : {}) };
+  };
+  const out = {
+    calls_per_task: measure("calls_per_task", ts.map((t) => t.calls)),
+    tokens_per_call: measure("tokens_per_call", ts.map((t) => t.tokens_per_call)),
+    time_to_useful_ms: measure("time_to_useful_ms", ts.filter((t) => t.time_to_useful_ms !== null).map((t) => t.time_to_useful_ms), ts.filter((t) => t.time_to_useful_ms === null).length),
+    decision_hours: measure("decision_hours", ds.map((d) => d.hours)),
+  };
+  const failing = Object.entries(out).filter(([, v]) => v.passed === false).map(([k]) => k);
+  return { events: events(dir).length, tasks: ts, decisions: ds, vitals: out, passed: failing.length === 0, failing,
+    note: events(dir).length ? "p75 of each vital against its threshold (naive.config.json vitals overrides the defaults)" : "no events yet: turn instrumentation on in naive.config.json ({\"instrumentation\": {\"events\": true}}) to measure calls, tokens and time to a useful answer" };
+}
+
+/** The events as one trace (root run per session, a child per call, nested calls under their parent), with the vitals as feedback. */
+export function trace(dir, session) {
+  const es = events(dir).filter((e) => !session || (e.session ?? "(no session)") === session);
+  const calls = es.filter((e) => e.kind === "call");
+  const node = (e) => ({ name: `${e.action} ${e.route}`, run_type: e.action === "run" ? "tool" : "retriever", start: new Date(startOf(e)).toISOString(), end: e.at,
+    inputs: { venture: e.venture, route: e.route, action: e.action }, outputs: { ok: e.ok, useful: e.useful, tokens: e.tokens, ms: e.ms }, ...(e.ok ? {} : { error: "call failed" }),
+    metadata: { via: e.via, actor: e.actor }, children: calls.filter((c) => c.parent === e.id).map(node) });
+  const judged = es.filter((e) => e.kind === "judgment").map((e) => ({ name: `judgment ${e.question ?? e.route ?? ""}`.trim(), run_type: "llm", start: new Date(Date.parse(e.at) - (e.ms ?? 0)).toISOString(), end: e.at,
+    inputs: { question: e.question, route: e.route }, outputs: { score: e.score, threshold: e.threshold, outcome: e.outcome }, metadata: { model: e.model, owner: e.owner } }));
+  const v = vitals(dir);
+  const start = es.length ? new Date(Math.min(...es.map((e) => Date.parse(e.at) - (e.ms ?? 0)))).toISOString() : new Date().toISOString();
+  const end = es.length ? es.at(-1).at : start;
+  return { name: `naive ${JSON.parse(readFileSync(join(dir, "venture.json"), "utf8")).id}${session ? ` ${session}` : ""}`, run_type: "chain", start, end,
+    inputs: { session: session ?? null }, outputs: { calls: calls.filter((c) => !c.parent).length, judgments: judged.length },
+    children: [...calls.filter((c) => !c.parent).map(node), ...judged].sort((a, b) => a.start.localeCompare(b.start)),
+    feedback: Object.entries(v.vitals).filter(([, x]) => x.passed !== null).map(([key, x]) => ({ key, score: x.passed ? 1 : 0, comment: `p75 ${x.p75} against ${x.threshold}` })) };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const dir = process.argv[2];
+  if (!dir || !existsSync(join(dir, "venture.json"))) { console.error("usage: node interface/vitals.mjs <venture dir> [--json] [--check] [--trace [--session <id>]]"); process.exit(2); }
+  const arg = (n) => { const i = process.argv.indexOf(`--${n}`); return i >= 0 ? process.argv[i + 1] : undefined; };
+  if (process.argv.includes("--trace")) { console.log(JSON.stringify(trace(dir, arg("session")), null, 2)); process.exit(0); }
+  const r = vitals(dir);
+  if (process.argv.includes("--json")) console.log(JSON.stringify(r, null, 2));
+  else {
+    console.log(`${r.events} events, ${r.tasks.length} tasks, ${r.decisions.length} decisions. ${r.note}`);
+    for (const [k, x] of Object.entries(r.vitals)) console.log(`  ${k.padEnd(18)} ${x.status.padEnd(10)} p75 ${x.p75 ?? "-"} (threshold ${x.threshold}, n ${x.n})`);
+  }
+  if (process.argv.includes("--check") && !r.passed) { console.error(`vitals failing: ${r.failing.join(", ")}`); process.exit(1); }
+}

package/interface/writes.mjs

@@ -0,0 +1,190 @@
+// What a write answers, what a layout offers, and the wrapper the router puts around every call
+// (Next.js translation M-3, M-9, M-17; it also wires in interface/reads.mjs, interface/boundaries.mjs
+// and interface/package-routes.mjs).
+//
+//   changed   M-3   one round trip: a write answers with the new state and what it changed: the
+//                   record's state before and after, each package whose progress or state moved,
+//                   the records that move now because of it, what it unlocked (a package that
+//                   completed and what that opens, a decision that no longer waits) and the
+//                   need-now rows it settled
+//   next      M-17  a write answers with the next route to act on: accept the draft it made, else
+//                   the next record in the same package that moves now, else what it unlocked,
+//                   else what need-now suggests, else the decision that matters most
+//   actions   M-9   a layout lists the actions available in its folder to the actor asking: each
+//                   route's actions, which of them this actor may take now, and whether a write
+//                   lands as the record, as a draft, or is locked or refused, with why
+//
+// around() runs before and after the router's own call: the framework and venture global errors
+// first (E-8), then package, group and venture routes (L-6, P-36, P-3), then the call, then what
+// reads and layouts add (L-9, L-10, O-1 to O-3, P-28) and what writes answer (M-3, M-17). It never
+// calls a model.
+
+import { allowed, draftOf, gateOf, resolve, routes, ventureDir } from "./router.mjs";
+import { frameworkHealth, globalError, ventureHealth } from "./boundaries.mjs";
+import { groupLayout, packageOfRecord, routeOfType, specialCall } from "./package-routes.mjs";
+import { filterRead, hierarchy, metadataFor, resolvedBy, withParams } from "./reads.mjs";
+
+/** The state a write can change, taken before and after it. */
+export async function snapshot(dir) {
+  const safe = async (f) => { try { return await f(); } catch { return null; } };
+  const { packages } = await import("../schema/packages.mjs");
+  const { needNow } = await import("../schema/need-now.mjs");
+  const { decisions } = await import("../schema/decisions.mjs");
+  return { packages: await safe(() => packages(dir)), need: await safe(() => needNow(dir)), decisions: await safe(() => decisions(dir)) };
+}
+
+const pkgMap = (s) => new Map([...(s?.packages?.core ?? []), ...(s?.packages?.handoff ?? [])].map((p) => [p.id, p]));
+const rowOf = (s, type) => (s?.packages?.core ?? []).flatMap((p) => p.records).find((x) => x.record === type && x.role !== "reads") ?? null;
+
+/** What a write changed (M-3), from the state before and after it. */
+export async function changed(before, after, { record }) {
+  const b = pkgMap(before), a = pkgMap(after);
+  const packages = [...a.values()].filter((p) => { const o = b.get(p.id); return !o || o.progress !== p.progress || o.state !== p.state; })
+    .map((p) => ({ package: p.id, title: p.title, progress: { from: b.get(p.id)?.progress ?? null, to: p.progress }, state: { from: b.get(p.id)?.state ?? null, to: p.state } }));
+  const was = new Map((before?.packages?.core ?? []).flatMap((p) => p.records.map((x) => [`${p.id}:${x.record}`, x])));
+  const moves = [];
+  for (const p of after?.packages?.core ?? []) for (const x of p.records) {
+    const o = was.get(`${p.id}:${x.record}`);
+    if (x.role !== "reads" && x.moves === "now" && o?.moves === "waits" && !moves.some((m) => m.record === x.record)) moves.push({ record: x.record, package: p.id, route: await routeOfType(x.record) });
+  }
+  const unlocked = [...a.values()].filter((p) => p.state === "complete" && b.get(p.id)?.state !== "complete").map((p) => ({ package: p.id, unlocks: p.unlocks ?? [] }));
+  const dBefore = new Map((before?.decisions?.decisions ?? []).map((d) => [d.id, d.render]));
+  const freed = (after?.decisions?.decisions ?? []).filter((d) => ["waiting", "later"].includes(dBefore.get(d.id)) && ["now", "overdue"].includes(d.render)).map((d) => ({ decision: d.id, question: d.question ?? null }));
+  const nBefore = new Map((before?.need?.rows ?? []).map((x) => [x.type, x.status]));
+  const need = (after?.need?.rows ?? []).filter((x) => nBefore.has(x.type) && nBefore.get(x.type) !== x.status).map((x) => ({ record: x.type, from: nBefore.get(x.type), to: x.status }));
+  return {
+    record: { type: record, from: rowOf(before, record)?.status ?? null, to: rowOf(after, record)?.status ?? null, package: packageOfRecord(record) },
+    packages, moves_now: moves, unlocked: [...unlocked, ...freed], need_now: need,
+  };
+}
+
+const commandFor = (route, venture) => route?.endsWith("[id]") ? `mentura ${route.replace("[id]", "<id>")} write --venture ${venture} --input <file>` : `mentura ${route} write --venture ${venture} --input <file>`;
+
+/** The next route to act on after a write (M-17). */
+export async function next(after, { record, route, draft, venture, change }) {
+  if (draft) return { route, action: "accept", who: "a person", command: `mentura accept ${route} --venture ${venture}`, why: "the write is held as a draft until a person accepts it" };
+  const home = packageOfRecord(record);
+  const p = (after?.packages?.core ?? []).find((x) => x.id === home);
+  const missing = (p?.records ?? []).filter((x) => x.role !== "reads" && x.record !== record && x.moves === "now" && x.status === "missing");
+  const required = missing.find((x) => x.role === "required");
+  if (required) { const rt = await routeOfType(required.record); return { route: rt, action: "write", command: commandFor(rt, venture), why: `the next required record in ${p.title} that moves now` }; }
+  // An agent's write waits for a person before what reads it can move.
+  const review = (p?.records ?? []).filter((x) => x.role !== "reads" && x.status === "agent");
+  if (review.length) { const rt = await routeOfType(review[0].record); return { route: rt, action: "review", who: "a person", command: `mentura ${rt} read --venture ${venture}`, why: `${review[0].title} was written by an agent: a person confirms it by writing it with --as person, and what reads it moves then` }; }
+  const freed = change?.moves_now?.[0];
+  if (freed) return { route: freed.route, action: "write", command: commandFor(freed.route, venture), why: `this write let ${freed.record} move` };
+  if (missing.length) { const rt = await routeOfType(missing[0].record); return { route: rt, action: "write", command: commandFor(rt, venture), why: `the next ${missing[0].role} record in ${p.title} that moves now` }; }
+  const suggest = (after?.need?.rows ?? []).filter((x) => x.status === "suggest now" && x.type !== record).sort((a, b) => b.now - a.now)[0];
+  if (suggest) { const rt = await routeOfType(suggest.type); if (rt) return { route: rt, action: "write", command: commandFor(rt, venture), why: `need-now suggests it now: ${suggest.why}` }; }
+  const { rank } = await import("../schema/decisions.mjs");
+  const ds = after?.decisions ? rank(after.decisions.decisions, after.decisions.phase).filter((d) => d.rank != null && d.source === "file") : [];
+  if (ds.length) return { route: "governance/decisions", action: "decide", who: "a person", command: `mentura decide ${ds[0].id} --venture ${venture} --by <your name>`, why: ds[0].question };
+  return { route: null, action: null, why: "nothing waits on this write" };
+}
+
+/** The actions available in a route's folder to one actor (M-9). */
+export async function actionsIn({ dir, r, route, actor = "agent", actor_id, venture }) {
+  const { holding, locked } = await import("../schema/decisions.mjs");
+  const { configOf, hold } = await import("../schema/gate.mjs");
+  const folder = r.collection === "item" ? r.route.slice(0, -"/[id]".length) : route.includes("/") ? route.slice(0, route.lastIndexOf("/")) : route;
+  const rs = routes().filter((x) => x.route === folder || x.route.startsWith(`${folder}/`));
+  const list = [];
+  for (const x of rs) {
+    const concrete = x.route === r.route ? route : x.route;
+    const entry = { route: concrete, kind: x.kind, actions: x.actions };
+    if (!dir) { list.push(entry); continue; }
+    const reads = allowed(dir, actor_id, "read", concrete);
+    const avail = x.actions.filter((a) => !["write", "run"].includes(a) && (reads || a === "template" || a === "layout"));
+    if (x.actions.includes("run")) {
+      const lock = actor !== "person" ? locked(dir, concrete, actor_id) : null;
+      if (reads && !lock) avail.push("run");
+      entry.run = lock ? { runs: false, why: `locked until decision ${lock.id} is made` } : reads ? { runs: true } : { runs: false, why: "the team plan does not let this role reach it" };
+    }
+    if (x.actions.includes("write")) {
+      let w;
+      if (!allowed(dir, actor_id, "write", concrete)) w = { lands: null, why: `${actor_id} may not write it (team plan routes)` };
+      else {
+        const lock = actor !== "person" ? locked(dir, concrete, actor_id) : null;
+        if (lock) w = { lands: null, why: `locked until decision ${lock.id} is made: ${lock.question}` };
+        else if (actor === "person") w = { lands: "record", why: "a person's write goes straight to the record" };
+        else {
+          const gate = gateOf(x, dir);
+          const d = !concrete.includes("[id]") ? draftOf(concrete, venture, undefined) : null;
+          const held = d ? holding(dir, d.file) : null;
+          const cfg = hold(configOf(dir), x.route, actor);
+          w = gate?.drafts ? { lands: "draft", why: `${x.record} is a ${gate.class} decision (${gate.level})` } : held ? { lands: "draft", why: `decision ${held.id} ${held.why}` } : cfg ? { lands: "draft", why: `${cfg.rule} fails closed in naive.config.json` } : { lands: "record", why: "no gate holds it" };
+        }
+      }
+      if (w.lands) avail.push("write");
+      entry.write = w;
+    }
+    entry.available = avail;
+    list.push(entry);
+  }
+  return { folder, actor: { kind: actor, ...(actor_id ? { id: actor_id } : {}) }, routes: list };
+}
+
+// The venture-relative file behind a read's source address (venture://path), for local sources only.
+const fileOfAddress = (a) => a?.startsWith("venture://") ? a.slice("venture://".length) : null;
+
+/**
+ * The wrapper around the router's call (see the top of this file). inner is the router's own call;
+ * args are what call takes. Returns what call returns, with the additions above.
+ */
+export async function around(inner, args) {
+  const { venture, route, action, input, actor = "agent", workspace } = args;
+  const actor_id = args.actor_id ?? process.env.MENTURA_ACTOR_ID;
+  // E-8: a broken framework file stops every route, with its recovery steps.
+  const fw = frameworkHealth();
+  if (fw) return globalError(fw);
+  let res;
+  try { res = resolve(route); } catch (e) { return globalError({ scope: "framework", file: "schema/data-model.json", problem: `the route table cannot be built: ${String(e.message ?? e).split("\n")[0]}`, recovery: ["Check the data model and the manifests: node schema/check-data-model.mjs", "Restore the file it names from git"] }); }
+  const dir = venture ? ventureDir(venture, workspace) : null;
+  // E-8: a broken venture.json answers with recovery steps, before anything reads it.
+  if (dir) { const h = ventureHealth(dir); if (h) return globalError(h, venture); }
+  // L-6, P-36, P-3: package, group and venture routes are answered here, outside the route table.
+  if (!res.r) return (await specialCall(args)) ?? inner(args);
+  const r = res.r, params = res.params;
+  const concrete = r.collection === "item" ? r.route.replace("[id]", params.id) : r.route;
+  const before = action === "write" && dir && r.kind === "record" ? await snapshot(dir) : null;
+  let out;
+  try { out = await inner(args); }
+  catch (e) {
+    // E-6: a record that cannot be read is that record's error, not a crash.
+    if (action !== "read") throw e;
+    return { ok: false, outcome: "error", error: `${concrete}: the record does not parse: ${String(e.message ?? e).split("\n")[0]}`, fix: { schema: r.schema ?? null, template: r.template ?? null }, resolved_by: "error" };
+  }
+
+  if (action === "read" && dir && r.kind === "record") {
+    if (out.ok) {
+      const items = r.collection === "list" ? Object.fromEntries(Object.entries(out.sources ?? {}).map(([id, s]) => [id, fileOfAddress(s.address)]).filter(([, f]) => f))
+        : out.source && fileOfAddress(out.source.address) ? { [params.id ?? r.record]: fileOfAddress(out.source.address) } : {};
+      out = { ...out, params, metadata: await metadataFor({ dir, r, route: concrete, params, result: out.result, items }) };
+      out = filterRead(out, input?.where, r);
+    }
+    out.resolved_by = resolvedBy(out);
+    if (input?.hierarchy) {
+      const { layout } = await import("./router.mjs");
+      const pkg = packageOfRecord(r.record);
+      const lay = withParams(layout(r, dir), { dir, params, file: draftOf(concrete, venture, workspace)?.file, group: pkg ? groupLayout(pkg, dir) : null });
+      out.hierarchy = hierarchy({ answer: out, layout: lay }).levels;
+    }
+    return out;
+  }
+
+  if (action === "layout" && out.ok) {
+    const pkg = r.kind === "record" ? packageOfRecord(r.record) : null;
+    const file = dir && r.kind === "record" && r.collection !== "list" && !concrete.includes("[id]") ? draftOf(concrete, venture, workspace)?.file : null;
+    const result = withParams(out.result, { dir, params, file, group: pkg ? groupLayout(pkg, dir) : null });
+    result.actions = await actionsIn({ dir, r, route: concrete, actor, actor_id, venture: venture ?? null });
+    return { ...out, result };
+  }
+
+  if (action === "write" && before && out.ok && out.result?.written) {
+    const after = await snapshot(dir);
+    const change = await changed(before, after, { record: r.record });
+    out.result.changed = change;
+    out.result.next = await next(after, { record: r.record, route: concrete, draft: out.result.draft, venture, change });
+  }
+  return out;
+}

package/knowledge/freshness.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "../schema/freshness-profiles.schema.json",
+  "note": "Default freshness profiles (Revalidating, V-1 to V-3): how long a record stays fresh, by record type, after Next.js cacheLife profiles. A venture overrides any of them under freshness in its naive.config.json, as a Next.js app defines cacheLife profiles in next.config.js. stale: how long an agent may reuse what it read without reading it again. revalidate: after this the record is stale, still readable with a stale flag, and should be checked or redone. expire: after this it is expired and not frozen into a release. per_phase: the record is stale once the venture changes phase after it was last checked. live: a fast-changing record, never frozen into a release; it stays a live hole. Durations are seconds, or a number with s, m, h, d or w. Version 0.x: ours and unevaluated.",
+  "version": "0.1.0",
+  "default": "max",
+  "profiles": {
+    "live": {
+      "live": true,
+      "stale": "0s",
+      "revalidate": "7d",
+      "note": "Pipeline, money and streams: read from their system of record every time, synced at least weekly, never frozen"
+    },
+    "feedback": {
+      "stale": "1d",
+      "revalidate": "30d",
+      "expire": "90d",
+      "note": "What customers said: stale after 30 days, too old to rely on after 90"
+    },
+    "research": {
+      "stale": "1d",
+      "revalidate": "90d",
+      "expire": "365d",
+      "note": "Market research, product cards and site measurements: stale after 90 days"
+    },
+    "assumption": {
+      "per_phase": true,
+      "stale": "1d",
+      "revalidate": "90d",
+      "expire": "365d",
+      "note": "What the venture believes about its problem, solution, price and market: tested again each phase, and stale after 90 days"
+    },
+    "foundation": {
+      "per_phase": true,
+      "stale": "1d",
+      "revalidate": "365d",
+      "note": "The strategic foundation: tested again each phase; in Discovery even confirmed statements are"
+    },
+    "max": {
+      "stale": "1d",
+      "revalidate": "365d",
+      "note": "Governance and other slow records: looked at again once a year"
+    },
+    "none": {
+      "note": "Generated or configuration records: never stale by time, only when what they depend on changes"
+    }
+  },
+  "records": {
+    "customer": "live",
+    "investor": "live",
+    "money-account": "live",
+    "data-stream": "live",
+    "raw-source": "feedback",
+    "raw-text": "feedback",
+    "evidence": "feedback",
+    "product": "research",
+    "account": "research",
+    "site-presence": "research",
+    "anatomy-input": "research",
+    "anatomy-answers": "research",
+    "validation-problem": "assumption",
+    "validation-solution": "assumption",
+    "validation-product-market-fit": "assumption",
+    "validation-pricing": "assumption",
+    "validation-go-to-market": "assumption",
+    "validation-team": "assumption",
+    "validation-operations-readiness": "assumption",
+    "telos": "foundation",
+    "icp": "foundation",
+    "alignment": "foundation",
+    "idea-dump": "none",
+    "idea-map": "none",
+    "idea-graph": "none",
+    "venture-profile": "max",
+    "provenance": "none",
+    "freshness-log": "none",
+    "venture-package": "none",
+    "knowledge-sources": "none",
+    "where-used": "none",
+    "decision-record": "none",
+    "decision-rights": "none",
+    "team-plan": "max",
+    "marketing-sitemap": "none",
+    "marketing-content": "none"
+  }
+}

package/knowledge/layer.json

@@ -19,11 +19,18 @@
     "design-document",
     "nextjs-status",
     "knowledge-sources",
-    "where-used"
+    "where-used",
+    "freshness-profiles",
+    "freshness-log",
+    "judgment",
+    "systems-catalog",
+    "glossary"
   ],
   "reads": [
     "venture",
-    "product"
+    "product",
+    "provenance",
+    "decision-record"
   ],
   "writes": [
     "reference"
@@ -36,7 +43,8 @@
     "No check on the venture profile or design documents of its own; design-coverage (evidence) is the only one",
     "Two connectors so far (filesystem and GitHub); a database, Notion, Slack or Salesforce each need their own module meeting the same contract",
     "Checks and command routes (need-now, time-to-ready, validation score) still read the venture folder, so they do not yet see a record kept in another source",
-    "A merged pull request is not logged as an accept in provenance; the read after the merge is the only sign"
+    "A merged pull request is not logged as an accept in provenance; the read after the merge is the only sign",
+    "Freshness (schema/freshness.mjs) checks children in the venture folder only; a child in another source is listed as needing the platform, and a webhook from a system of record that marks summaries stale (V-9) is the platform's"
   ],
   "name": "knowledge"
 }

package/knowledge/templates/glossary.md

@@ -0,0 +1,23 @@
+---
+type: template
+tags: [everything-ecosystem, knowledge, glossary, template]
+ai-model: claude-opus-5.5
+created: 2026-10-29T06:04:07Z
+source: hybrid
+---
+
+# Template: package glossary
+
+Fills `<venture>/glossary/<package>.json` (`schema/glossary.schema.json`). A package's terms stay local to it: an agent working in another package sees only the terms marked `export`. See what a package sees with `mentura glossary/terms run --value <package>`.
+
+```json
+{
+  "package": "finance",
+  "terms": [
+    { "term": "burn multiple", "meaning": "net burn divided by net new ARR" },
+    { "term": "runway", "meaning": "months of cash at the current burn", "export": true }
+  ]
+}
+```
+
+Two packages may not export one term with different meanings. A package's own term wins over another's exported one.