naive-framework 0.1.0 → 0.3.0

package/schema/data-model.json

@@ -48,7 +48,13 @@
         "exit",
         "telos",
         "provenance",
-        "knowledge-sources"
+        "knowledge-sources",
+        "people",
+        "founder",
+        "fund-thesis",
+        "fund-terms",
+        "deal",
+        "money-summary"
       ],
       "refs": [
         {
@@ -495,6 +501,43 @@
       ],
       "note": "For each fact kept once in its system of record, every place that repeats it; live children must show the parent's value (EE-042)"
     },
+    {
+      "id": "freshness-profiles",
+      "layer": "knowledge",
+      "level": "method",
+      "schema": "schema/freshness-profiles.schema.json",
+      "form": "json",
+      "paths": [
+        "knowledge/freshness.json"
+      ],
+      "refs": [
+        {
+          "field": "records",
+          "to": "(record types)",
+          "checked_by": "schema/freshness-test.mjs"
+        }
+      ],
+      "note": "Default freshness profiles by record type (Revalidating V-2): stale, revalidate and expire after Next.js cacheLife, plus per_phase and live; a venture overrides them under freshness in naive.config.json"
+    },
+    {
+      "id": "freshness-log",
+      "layer": "knowledge",
+      "level": "venture",
+      "schema": "schema/freshness-log.schema.json",
+      "form": "json-lines",
+      "paths": [
+        "instance/**/knowledge/freshness.jsonl",
+        "schema/examples/**/knowledge/freshness.jsonl"
+      ],
+      "refs": [
+        {
+          "field": "target.value",
+          "to": "(venture file)",
+          "checked_by": "schema/freshness.mjs"
+        }
+      ],
+      "note": "On-demand revalidations (a tag, a path or a package marked stale), checks that a record is still right, and phase changes: one append-only line each (Revalidating V-1, V-5, V-7)"
+    },
     {
       "id": "department-catalog",
       "layer": "operations",
@@ -979,6 +1022,24 @@
       ],
       "note": "Venture packages (EE-067, EE-069): the assumed governance model; core packages by department (each record's one home, what it reads, priors per phase with conditions, what completion unlocks); handoff packages by receiver; record-level dependencies; the question matrix"
     },
+    {
+      "id": "frame",
+      "layer": "system",
+      "level": "method",
+      "schema": "schema/frame.schema.json",
+      "form": "json",
+      "paths": [
+        "packages/*/frames/*.frame.json"
+      ],
+      "refs": [
+        {
+          "field": "emits.*.id",
+          "to": "decision",
+          "checked_by": "schema/frames-test.mjs"
+        }
+      ],
+      "note": "The decision library: one recurring venture problem as a shape (goal, hidden decisions, premises and the attacks on them, a freshness spec, reasoning), never an answer. schema/frames.mjs matches it to the founder's words, judges its premises against the venture and proposes its decisions, open"
+    },
     {
       "id": "venture-package",
       "layer": "system",
@@ -992,6 +1053,18 @@
       ],
       "note": "The venture package view (EE-067, EE-069): the open core packages and handoffs, each record confirmed, to review or to write, what moves now and what waits, with its versions; the records themselves stay in place"
     },
+    {
+      "id": "release",
+      "layer": "system",
+      "level": "venture",
+      "schema": null,
+      "form": "json",
+      "paths": [
+        "instance/**/.release/release.json",
+        "instance/**/.release/card.json"
+      ],
+      "note": "A release (C-11, I-17): the venture's static shell, written by node schema/build-release.mjs. release.json is the manifest (confirmed records frozen in with their sha256, date and who confirmed them; named live holes; the route table as the release holds it; frozen command answers); card.json is the release card's data (P-25, O-7). The frozen copies under .release/records/ keep their own record types. Read without the router by node schema/start-release.mjs"
+    },
     {
       "id": "team-plan",
       "layer": "operations",
@@ -1063,6 +1136,35 @@
       ],
       "note": "Who or what wrote each record, how, from what and under which decision: one append-only line per write, hash-chained, after W3C PROV (EE-031)"
     },
+    {
+      "id": "naive-config",
+      "layer": "system",
+      "level": "venture",
+      "schema": "schema/naive-config.schema.json",
+      "paths": [
+        "instance/**/naive.config.json",
+        "schema/examples/**/naive.config.json"
+      ],
+      "decision_class": "security-loosening",
+      "refs": [
+        {
+          "field": "gate.rules.routes",
+          "to": "(routes)",
+          "checked_by": "schema/check-config.mjs"
+        },
+        {
+          "field": "owners",
+          "to": "team-plan",
+          "checked_by": "schema/check-config.mjs"
+        },
+        {
+          "field": "packages",
+          "to": "venture-packages",
+          "checked_by": "schema/check-config.mjs"
+        }
+      ],
+      "note": "The venture's overrides to Naive's defaults (P-2, like next.config.js): the gate's static rules, function owners, check settings, thresholds, which System 1 questions run, pinned package versions and how strictly the acting role is checked. An agent's write of it is a draft, since it can loosen the gate"
+    },
     {
       "id": "route-aliases",
       "layer": "interface",
@@ -1073,6 +1175,51 @@
       ],
       "note": "Old routes kept as aliases of their new ones, so a rename does not break agents (EE-032)"
     },
+    {
+      "id": "adapter",
+      "layer": "interface",
+      "level": "method",
+      "schema": "schema/adapter.schema.json",
+      "paths": [
+        "interface/adapters/*.json",
+        "platform/adapter.json"
+      ],
+      "note": "What runs Naive on a platform or in an agent harness (Z-4): the entry files a harness adapter writes into a venture and where it loads skills, or the tests a platform adapter runs. Verified when it passes the framework's tests (interface/adapters.mjs verify)"
+    },
+    {
+      "id": "upgrade-registry",
+      "layer": "system",
+      "level": "method",
+      "schema": "schema/upgrade-registry.schema.json",
+      "paths": [
+        "schema/upgrades.json"
+      ],
+      "refs": [
+        {
+          "field": "versions[].guide",
+          "to": "(repository file)",
+          "checked_by": "schema/upgrades-test.mjs"
+        }
+      ],
+      "note": "Naive's versions with their guides, the migrations between them, and each package's version and channel (U-1 to U-6, EE-076). naive upgrade reads it from the installed copy"
+    },
+    {
+      "id": "kit",
+      "layer": "system",
+      "level": "method",
+      "schema": "schema/kit.schema.json",
+      "paths": [
+        "platform/kits/*/kit.json"
+      ],
+      "refs": [
+        {
+          "field": "extends.package",
+          "to": "venture-packages",
+          "checked_by": null
+        }
+      ],
+      "note": "A Mentura kit (EE-071): an enhanced package or command, with its automations (triggers that need a complete package, M-12) or its agent workflow (the agent-run upgrade, U-3). The framework reads it as data and never imports its code (schema/kits.mjs)"
+    },
     {
       "id": "icp",
       "layer": "purpose",
@@ -1158,6 +1305,17 @@
       ],
       "note": "A money master record. Activity is an append-only stream. The package is never complete (EE-070)."
     },
+    {
+      "id": "money-summary",
+      "layer": "purpose",
+      "level": "venture",
+      "schema": "schema/money-summary.schema.json",
+      "paths": [
+        "instance/**/money/_summary.json",
+        "schema/examples/**/money/_summary.json"
+      ],
+      "note": "Cash, monthly flows and runway from the money source's last sync; versioned, and the only money record a model sees (EE-070)"
+    },
     {
       "id": "data-stream",
       "layer": "purpose",
@@ -1195,17 +1353,177 @@
         "schema/examples/**/raw/sources/*/text.md"
       ],
       "note": "The text of a raw source. original.* stays out of git (EE-070)."
-    }
-  ],
-  "ignore": [
+    },
     {
-      "path": "package.json",
-      "reason": "The framework's npm manifest: the naive and mentura commands (I-1, I-17); not a record"
+      "id": "judgment",
+      "layer": "knowledge",
+      "level": "venture",
+      "schema": "schema/judgment.schema.json",
+      "paths": [
+        "instance/**/knowledge/judgments/*.json",
+        "schema/examples/**/knowledge/judgments/*.json"
+      ],
+      "refs": [
+        {
+          "field": "package",
+          "to": "(packages and kits)",
+          "checked_by": "schema/model-steps.mjs"
+        },
+        {
+          "field": "decision",
+          "to": "decision-record",
+          "checked_by": "schema/model-steps.mjs"
+        }
+      ],
+      "note": "The typed output of one model step (use model, EE-073): what it read, its answer and confidence, and whether code accepted, overruled or routed it to a person as uncertain. The agent's until a person confirms it (schema/model-steps.mjs)"
     },
     {
-      "path": "interface/create-venture/package.json",
-      "reason": "The create-venture generator's npm manifest (I-1); not a record"
+      "id": "venture-types",
+      "layer": "system",
+      "level": "method",
+      "schema": "schema/venture-types.schema.json",
+      "paths": [
+        "schema/venture-types.json"
+      ],
+      "note": "The venture types create-venture scaffolds, and what each starts with (EE-082)"
+    },
+    {
+      "id": "venture-role",
+      "layer": "governance",
+      "level": "method",
+      "schema": "schema/venture-role.schema.json",
+      "paths": [
+        "governance/venture-template/roles/venture-roles.json"
+      ],
+      "note": "Roles a person can hold in a venture, beside the agent roles (EE-082)"
+    },
+    {
+      "id": "people",
+      "layer": "operations",
+      "level": "venture",
+      "schema": "schema/people.schema.json",
+      "paths": [
+        "instance/**/people/people.json",
+        "schema/examples/**/people/people.json"
+      ],
+      "note": "The venture's people: role and hats per person; venture.json for human capital (EE-082)"
     },
+    {
+      "id": "founder",
+      "layer": "operations",
+      "level": "venture",
+      "schema": "schema/founder.schema.json",
+      "paths": [
+        "instance/**/people/founders/*.json",
+        "schema/examples/**/people/founders/*.json"
+      ],
+      "note": "One file per founder, linked to the founder agreement (EE-082)"
+    },
+    {
+      "id": "fund-thesis",
+      "layer": "purpose",
+      "level": "venture",
+      "schema": "schema/fund-thesis.schema.json",
+      "paths": [
+        "instance/**/fund/thesis.json",
+        "schema/examples/**/fund/thesis.json"
+      ],
+      "note": "A fund's thesis (EE-082)"
+    },
+    {
+      "id": "fund-terms",
+      "layer": "purpose",
+      "level": "venture",
+      "schema": "schema/fund-terms.schema.json",
+      "paths": [
+        "instance/**/fund/terms.json",
+        "schema/examples/**/fund/terms.json"
+      ],
+      "note": "A fund's terms and closes (EE-082)"
+    },
+    {
+      "id": "deal",
+      "layer": "purpose",
+      "level": "venture",
+      "schema": "schema/deal.schema.json",
+      "paths": [
+        "instance/**/deals/*.json",
+        "schema/examples/**/deals/*.json"
+      ],
+      "note": "A company in a fund's pipeline (EE-082)"
+    },
+    {
+      "id": "systems-catalog",
+      "layer": "knowledge",
+      "level": "method",
+      "schema": "schema/systems-catalog.schema.json",
+      "paths": [
+        "schema/systems-catalog.json"
+      ],
+      "note": "The systems of record create-venture offers per function (EE-083)"
+    },
+    {
+      "id": "glossary",
+      "layer": "knowledge",
+      "level": "venture",
+      "schema": "schema/glossary.schema.json",
+      "paths": [
+        "instance/**/glossary/*.json",
+        "schema/examples/**/glossary/*.json"
+      ],
+      "refs": [
+        {
+          "field": "terms[].export",
+          "to": "glossary",
+          "checked_by": "schema/check-brand.mjs"
+        }
+      ],
+      "note": "A package's own terms, at glossary/<package>.json (Y-2): local to the package unless exported, so an agent in another package sees only exported terms; glossary/terms shows what one package sees"
+    },
+    {
+      "id": "marketing-brand",
+      "layer": "operations",
+      "level": "venture",
+      "schema": "schema/marketing-brand.schema.json",
+      "paths": [
+        "instance/**/marketing/brand.json",
+        "schema/examples/**/marketing/brand.json"
+      ],
+      "refs": [
+        {
+          "field": "marks[].asset",
+          "to": "public-assets",
+          "checked_by": "schema/check-brand.mjs"
+        },
+        {
+          "field": "typefaces[].files",
+          "to": "public-assets",
+          "checked_by": "schema/check-brand.mjs"
+        }
+      ],
+      "decision_class": "experience-design",
+      "note": "Brand tokens in the marketing package (Y-3): colors, licensed self-hosted typefaces (T-1), the font each role uses with scopes where nearer context wins (Y-5, T-2), voice rules (the global stylesheet for words), the logo and marks (P-24) and outside design systems by reference (Y-4). Read by every agent's layout; marketing/brand/tokens renders it for interfaces"
+    },
+    {
+      "id": "public-assets",
+      "layer": "operations",
+      "level": "venture",
+      "schema": "schema/public-assets.schema.json",
+      "paths": [
+        "instance/**/public/assets.json",
+        "schema/examples/**/public/assets.json"
+      ],
+      "refs": [
+        {
+          "field": "remote[].id",
+          "to": "raw-source",
+          "checked_by": "schema/check-assets.mjs"
+        }
+      ],
+      "note": "The register of what the venture ships as it is, in public/ (I-23, J-2, J-3, J-4): each file's source, license and credit, facts code reads from its bytes, alt text and who wrote it; remote images as links with a note in raw/; the hosts an agent may fetch from"
+    }
+  ],
+  "ignore": [
     {
       "path": "site/package.json",
       "reason": "The developer-docs site's npm manifest (EE-034); not a record"
@@ -1253,6 +1571,14 @@
     {
       "path": "site/content/marketing/meta.json",
       "reason": "Fumadocs sidebar order for marketing pages (EE-080); not a record"
+    },
+    {
+      "path": "package.json",
+      "reason": "The framework's npm manifest: the naive and mentura commands (I-1, I-17); not a record"
+    },
+    {
+      "path": "interface/create-venture/package.json",
+      "reason": "The create-venture generator's npm manifest (I-1); not a record"
     }
   ]
 }

package/schema/deal.schema.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "deal.schema.json",
+  "title": "Deal",
+  "description": "One company in the fund's pipeline (deals/<id>.json), from sourced to invested or passed. An investment it makes becomes a nested venture under portfolio/.",
+  "type": "object",
+  "required": [
+    "id",
+    "company",
+    "round",
+    "status"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$"
+    },
+    "company": {
+      "type": "string"
+    },
+    "round": {
+      "enum": [
+        "pre-seed",
+        "seed",
+        "series-a",
+        "series-b",
+        "growth",
+        "late"
+      ],
+      "description": "The financing round the company is raising"
+    },
+    "status": {
+      "enum": [
+        "sourced",
+        "screening",
+        "diligence",
+        "term-sheet",
+        "invested",
+        "passed"
+      ]
+    },
+    "sector": {
+      "type": "string"
+    },
+    "source": {
+      "type": "string"
+    },
+    "check": {
+      "type": "object",
+      "required": [
+        "amount",
+        "currency"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "amount": {
+          "type": "number",
+          "minimum": 0
+        },
+        "currency": {
+          "type": "string",
+          "pattern": "^[A-Z]{3}$"
+        }
+      }
+    },
+    "thesis_fit": {
+      "type": "string",
+      "description": "How the company fits fund/thesis.json, in a sentence"
+    },
+    "portfolio": {
+      "type": "string",
+      "pattern": "^portfolio/[a-z0-9-]+$",
+      "description": "The nested venture, once invested"
+    },
+    "note": {
+      "type": "string"
+    }
+  }
+}

package/schema/decision-analytics.mjs

@@ -19,6 +19,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { decisions } from "./decisions.mjs";
 import { HOME, PACKAGES, TITLES } from "./packages.mjs";
+import { ventureFile } from "./venture-paths.mjs";
 
 const load = (f) => JSON.parse(readFileSync(f, "utf8"));
 const titleOf = (t) => ({ icp: "ICP", "venture-core": "Core product" })[t] ?? TITLES[t] ?? t.replace(/^validation-/, "").replace(/-/g, " ").replace(/^./, (c) => c.toUpperCase());
@@ -30,7 +31,7 @@ const OPEN = new Set(["now", "overdue", "waiting", "stale", "later"]);
 export function analytics(dir, now) {
   const r = decisions(dir, now);
   const rows = r.decisions.filter((d) => d.source !== "root").map((d) => {
-    const raw = d.file ? load(join(dir, d.file)) : {};
+    const raw = d.file ? load(ventureFile(dir, d.file)) : {};
     const record = d.decides?.record ?? null;
     // A foundation statement belongs to the strategic foundation whatever record holds it; so does a
     // decision about venture.json itself (the core product, the team).

package/schema/decisions.mjs

@@ -30,6 +30,9 @@ import { dirname, join, relative } from "node:path";
 import { FRAME, foundation } from "./foundation.mjs";
 import { agentFromEnv, record as prov } from "../interface/provenance.mjs";
 import { glob as routeFileGlob, routes } from "../interface/router.mjs";
+// Caching hook (F-12): the decision list is computed once per router action (schema/caching.mjs).
+import { memo } from "./caching.mjs";
+import { layoutOf, logicalFiles, ventureFile } from "./venture-paths.mjs";
 
 const repo = new URL("..", import.meta.url).pathname;
 const load = (f) => JSON.parse(readFileSync(f, "utf8"));
@@ -45,7 +48,9 @@ export function recordOf(file) {
 
 // Every *.decision.json in a venture, outside drafts, hidden folders and nested ventures.
 function decisionFiles(dir, sub = "") {
-  return readdirSync(join(dir, sub), { withFileTypes: true }).flatMap((e) => {
+  // A structured venture (EE-086): its decision files by their logical paths.
+  if (!sub && layoutOf(dir) === "structured") return logicalFiles(dir).filter((r) => r.endsWith(".decision.json") && r.split("/").at(-2) === "decisions" && !r.split("/").some((s) => s.startsWith(".") || s.startsWith("_")));
+  return readdirSync(ventureFile(dir, sub), { withFileTypes: true }).flatMap((e) => {
     const rel = sub ? `${sub}/${e.name}` : e.name;
     if (e.isDirectory()) return e.name.startsWith(".") || e.name.startsWith("_") || existsSync(join(dir, rel, "venture.json")) ? [] : decisionFiles(dir, rel);
     return e.name.endsWith(".decision.json") && sub.split("/").at(-1) === "decisions" ? [rel] : [];
@@ -53,7 +58,11 @@ function decisionFiles(dir, sub = "") {
 }
 
 /** Every decision of a venture, resolved: boundary, render state and what holds it. */
-export function decisions(dir, now = Date.parse(process.env.DECISIONS_NOW ?? "") || Date.now()) {
+// Caching hook (F-12): without an explicit now, one action shares one decision list; now is the action's.
+export function decisions(dir, now) {
+  return now === undefined ? memo("decisions", () => decisionsAt(dir), { dir }) : decisionsAt(dir, now);
+}
+function decisionsAt(dir, now = Date.parse(process.env.DECISIONS_NOW ?? "") || Date.now()) {
   const venture = load(join(dir, "venture.json"));
   const phase = PHASES.indexOf(venture.phase);
   const productOnly = venture.kind === "product";
@@ -68,7 +77,7 @@ export function decisions(dir, now = Date.parse(process.env.DECISIONS_NOW ?? "")
       status: settled ? "decided" : "open", decided_at: null, needed_in: venture.phase },
   ];
   for (const f of decisionFiles(dir)) {
-    const d = load(join(dir, f));
+    const d = load(ventureFile(dir, f));
     // decisions/<record>[.<topic>].decision.json decides <record>.json in the folder that holds decisions/.
     const at = f.split("/").slice(0, -2).join("/"), base = f.split("/").at(-1).split(".")[0];
     const path = d.decides?.path ?? (at ? `${at}/${base}.json` : `${base}.json`);
@@ -101,7 +110,7 @@ export function decisions(dir, now = Date.parse(process.env.DECISIONS_NOW ?? "")
   }
   const statementFor = (record) => list.find((x) => x.part_of === "foundation" && x.status === "open" && x.decides?.record === record);
   // An agent's draft of a gated record waits for a person to accept it.
-  const drafts = existsSync(join(dir, "_drafts")) ? readdirSync(join(dir, "_drafts")).filter((f) => f.endsWith(".draft")) : [];
+  const drafts = existsSync(join(ventureFile(dir, "_drafts"))) ? readdirSync(join(ventureFile(dir, "_drafts"))).filter((f) => f.endsWith(".draft")) : [];
   for (const d of drafts) {
     const path = d.replace(/\.draft$/, "").replace(/__/g, "/");
     const record = recordOf(path);
@@ -234,7 +243,7 @@ const routeGlob = (g) => new RegExp("^" + g.replace(/[.+^${}()|[\]\\]/g, "\\$&")
 /** The decision that keeps a route closed to an actor (EE-058): an undecided decision that unlocks it. */
 export function locked(dir, route, actorId) {
   if (!existsSync(join(dir, "venture.json"))) return null;
-  const files = decisionFiles(dir).map((f) => load(join(dir, f)));
+  const files = decisionFiles(dir).map((f) => load(ventureFile(dir, f)));
   const d = files.find((x) => x.status !== "decided" && x.status !== "withdrawn" && (x.unlocks ?? []).some((u) =>
     (u.routes ?? []).some((g) => routeGlob(g).test(route)) && (!u.for?.length || !actorId || u.for.includes(actorId))));
   return d ? { id: d.id, question: d.question } : null;
@@ -248,7 +257,7 @@ const validate = (d) => {
   rmSync(scratch, { recursive: true, force: true });
   return v.status === 0 ? null : (v.stdout + v.stderr).trim();
 };
-const fileOf = (dir, id) => decisionFiles(dir).find((f) => load(join(dir, f)).id === id);
+const fileOf = (dir, id) => decisionFiles(dir).find((f) => load(ventureFile(dir, f)).id === id);
 
 /** An agent proposes a decision, or new wording for an open one. It stays open until a person
  *  approves it: an agent never decides (EE-058). at: the folder beside the record it decides. */
@@ -257,16 +266,16 @@ export function propose(dir, input, { agentId, via = "router", harness, model }
   if (!rest.id || !rest.question) return { ok: false, error: "a decision needs an id and a question" };
   if (rest.status && rest.status !== "open") return { ok: false, error: "an agent may only propose an open decision; a person approves it" };
   const existing = fileOf(dir, rest.id);
-  if (existing && load(join(dir, existing)).status === "decided") return { ok: false, error: `${rest.id} is decided; only a person can change it` };
+  if (existing && load(ventureFile(dir, existing)).status === "decided") return { ok: false, error: `${rest.id} is decided; only a person can change it` };
   const file = existing ?? `${at ? `${at}/` : ""}decisions/${name ?? rest.id}.decision.json`;
   if (!existing && !/^([a-z0-9-]+\/)*decisions\/[a-z0-9.-]+\.decision\.json$/.test(file)) return { ok: false, error: `${file} is not a decisions/ path` };
   // New wording for an open decision keeps what the agent did not restate: its parent, boundary, unlocks.
-  const before = existing ? load(join(dir, existing)) : {};
+  const before = existing ? load(ventureFile(dir, existing)) : {};
   const d = { ...before, ...rest, status: "open", provenance: { drafted_by: { kind: "agent", ...(agentId ? { id: agentId } : {}) } } };
   const bad = validate(d);
   if (bad) return { ok: false, error: `does not match schema/decision-record.schema.json:\n${bad}` };
-  mkdirSync(dirname(join(dir, file)), { recursive: true });
-  writeFileSync(join(dir, file), JSON.stringify(d, null, 2) + "\n");
+  mkdirSync(dirname(ventureFile(dir, file)), { recursive: true });
+  writeFileSync(ventureFile(dir, file), JSON.stringify(d, null, 2) + "\n");
   const e = prov(dir, { entity: file, route: "governance/decisions", activity: "draft", agent: agentFromEnv("agent", via, { ...(agentId ? { id: agentId } : {}), ...(harness ? { harness } : {}), ...(model ? { model } : {}) }), note: `proposed decision ${d.id}` });
   return { ok: true, result: { proposed: d.id, file, awaiting: "approval", provenance: e.hash } };
 }
@@ -276,7 +285,7 @@ export function approve(dir, id, { by, answer, via = "cli", note } = {}) {
   const file = fileOf(dir, id);
   if (!file) return { ok: false, error: `no decision ${id}` };
   if (!by) return { ok: false, error: "approving needs the person's name (--by)" };
-  const d = load(join(dir, file));
+  const d = load(ventureFile(dir, file));
   if (d.status === "decided") return { ok: false, error: `${id} is already decided` };
   if (!answer && !d.answer) return { ok: false, error: `${id} has no wording to approve; give an answer` };
   const drafted = d.provenance?.drafted_by ?? { kind: "person", id: by };
@@ -285,7 +294,7 @@ export function approve(dir, id, { by, answer, via = "cli", note } = {}) {
   const out = { ...d, status: "decided", answer: answer ?? d.answer, provenance: { ...d.provenance, drafted_by: drafted, approved_by: by, approved_at: new Date().toISOString().replace(/\.\d+Z$/, "Z"), phase, wording, via } };
   const bad = validate(out);
   if (bad) return { ok: false, error: bad };
-  writeFileSync(join(dir, file), JSON.stringify(out, null, 2) + "\n");
+  writeFileSync(ventureFile(dir, file), JSON.stringify(out, null, 2) + "\n");
   const e = prov(dir, { entity: file, route: "governance/decisions", activity: "accept", agent: agentFromEnv("person", via, { id: by }), note: note ?? `approved decision ${id} (${wording})` });
   return { ok: true, result: { decided: id, wording, phase, provenance: e.hash, unlocks: (out.unlocks ?? []).map((u) => u.activity) } };
 }

package/schema/examples/frames/judge.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// A stand-in judge for the frames test (the Jev protocol): reads one request on stdin and answers every
+// noul question from the facts it was given, without a model. A premise is unknown (0.5) when a fact it
+// could rest on says "not on record", else no (0.1); the trade reads as a sequence.
+let input = "";
+for await (const c of process.stdin) input += c;
+const req = JSON.parse(input);
+const unknown = Object.values(req.state.venture ?? {}).some((v) => v === "not on record");
+const answers = Object.fromEntries(Object.keys(req.questions).map((k) => [k, { noul: k.startsWith("dichotomy:") ? (k === "dichotomy:sequence" ? 0.9 : 0.1) : k === "premise:needs-outside-money" && unknown ? 0.5 : 0.1 }]));
+console.log(JSON.stringify({ model: "stand-in", answers }));

package/schema/examples/venture-type/jev.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// A stand-in for Jev in tests (MENTURA_TYPE_CMD="node schema/examples/venture-type/jev.mjs"): reads the
+// typed request on stdin and answers each type:<id> question yes when the description uses one of that
+// type's examples, so the classifier's ranking and its uncertain path can be tested offline.
+import { readFileSync } from "node:fs";
+let input = "";
+for await (const c of process.stdin) input += c;
+const req = JSON.parse(input);
+const words = req.state.venture.description.toLowerCase();
+const types = JSON.parse(readFileSync(new URL("../../venture-types.json", import.meta.url), "utf8")).types;
+const answers = Object.fromEntries(types.map((t) => [`type:${t.id}`, { noul: t.examples.some((e) => words.includes(e.toLowerCase())) ? 0.92 : 0.04 }]));
+console.log(JSON.stringify({ model: "stand-in", answers }));

package/schema/examples/workspace/ventures/acme-labs/AGENTS.md

@@ -0,0 +1,17 @@
+# AGENTS.md: acme-labs
+
+The map of this venture for agents. Read it, then a route's layout, before writing anything here.
+
+## How to work here
+
+- List the routes with `mentura routes`. Read a route's `layout` and `template` before you write to it.
+- Write through the router (the CLI or the MCP server), not by editing files. Every write is checked against its schema and recorded in provenance.jsonl.
+- A write that fails closed comes back as a draft in `_drafts/`. A person accepts it with `mentura accept`.
+- Never read or send anything under `_private/` to a model.
+- A deeper AGENTS.md (for example `marketing/AGENTS.md`) adds to this one for the routes under it; the nearer one wins.
+
+## Instructions
+
+phase: discovery
+voice: plain words, in the founder's own terms
+private: _private/