naive-framework 0.0.0-stage → 0.1.0

package/interface/skills/install-mentura/SKILL.md

@@ -0,0 +1,88 @@
+---
+type: knowledge
+tags: [everything-ecosystem, mentura, skills, interface, install, mcp, cli]
+ai-model: claude-opus-5.5
+created: 2026-10-27T20:52:58Z
+source: hybrid
+name: install-mentura
+description: >
+  Install Mentura (the Everything Ecosystem) into a coding agent: the MCP server
+  for Claude Code or Cursor, the CLI, and a first venture, using the whole system
+  or only the layers the builder wants (EE-030).
+  MANDATORY TRIGGERS: install mentura, set up mentura, add the everything
+  ecosystem, use mentura in claude code, use mentura in cursor, mentura mcp,
+  adopt one layer, only the validation kit, start a venture.
+---
+
+# Install Mentura
+
+Interface layer (EE-030). Mentura is a set of records, checks and kits in a git repository. This skill connects an agent harness to it. Every interface (CLI, MCP server, HTTP API) goes through `interface/router.mjs`, so each one has the same routes and gates. The routes are listed in `docs/reference/ROUTES.md`.
+
+## 1. Ask what the builder wants to adopt
+
+Partial adoption is the default. Ask which of these they want, and do not install more:
+
+- **The whole system:** every layer, with the phase defaults.
+- **One layer:** for example `purpose` alone, to state a telos and validate.
+- **One kit inside a layer:** for example the validation kit. Turn on its layer only; the kit's routes need nothing else.
+
+A layer the builder leaves off is written as `false` in `venture.json`. The need-now score then lists that layer's records as "layer off" instead of suggesting them.
+
+## 2. Get the repository and check it runs
+
+```sh
+git clone <the Mentura repository> mentura
+cd mentura && node test.mjs        # Node 20+ and python3 with jsonschema (pip install jsonschema)
+```
+
+## 3. Start a venture, or point at existing ones
+
+```sh
+node interface/cli/mentura.mjs init <folder>/my-venture --id my-venture --layers purpose
+node interface/cli/mentura.mjs system/need-now run --venture my-venture --workspace <folder>
+```
+
+`init` creates new ventures only: it refuses a directory that already has files. To bring an existing project in, create the venture, then run `node interface/cli/naive.mjs port --from <project> --venture <folder>/my-venture`, read the plan it writes, and apply it with `--apply --confirm port`. To have an agent rewrite the project as Naive records instead, use `naive.mjs migrate` with the same flags, have the founder settle each `migrate-<function>` decision, then run `migrate --venture <folder>/my-venture --apply`. Never run `init` on someone's existing project.
+
+To use the whole system, leave out `--layers`. The workspace is the folder that holds the ventures. Set `MENTURA_WORKSPACE` to it so that you do not have to pass `--workspace` each time.
+
+## 4. Connect the harness
+
+**Claude Code** (one command; add `--scope project` to share it in the venture's repo through `.mcp.json`):
+
+```sh
+claude mcp add mentura --env MENTURA_WORKSPACE=<folder> --env MENTURA_HARNESS="Claude Code" -- node <mentura>/interface/mcp/server.mjs
+```
+
+**Cursor** (`.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project):
+
+```json
+{
+  "mcpServers": {
+    "mentura": {
+      "command": "node",
+      "args": ["<mentura>/interface/mcp/server.mjs"],
+      "env": { "MENTURA_WORKSPACE": "<folder>", "MENTURA_HARNESS": "Cursor" }
+    }
+  }
+}
+```
+
+**Any other harness or script:** use the CLI (`node interface/cli/mentura.mjs help`). You can also run `node interface/api/server.mjs`. It listens only on 127.0.0.1:4330 and has no authentication, so keep it on the builder's own machine.
+
+Use absolute paths in both configs. Check the connection by asking the agent to call `mentura_ventures`, then `mentura_view` on `system/overview`. Before an agent acts on a route, it should call `mentura_layout` for that route: it returns the kit's skills, references, template and gate.
+
+## 5. Tell the builder how gates work
+
+- An agent's write to a gated record becomes a draft in `<venture>/_drafts/`. The gated records are ownership, board, founder agreement, exit, telos, decision rights and publication policy. Writes through the MCP server and the API always count as an agent's.
+- A person accepts a draft with `mentura accept <route> --venture <id>`.
+- The CLI cannot tell whether a person or an agent is typing. The real gate is the repository's review: a person merges the pull request.
+- Every write is logged in `<venture>/provenance.jsonl` (EE-031): who wrote it, through which interface, what it came from and the decision it acted under. Set `MENTURA_ACTOR_ID`, `MENTURA_MODEL`, `MENTURA_SESSION` and `MENTURA_HARNESS` in the harness config so that each line names the agent. The MCP server also records the harness name that the client reports. For a venture that existed before the log, run `mentura baseline --venture <id>` once.
+- Every write is checked against the record's schema first. A record that does not match is refused, and nothing changes.
+
+## Sources
+
+- W3C PROV-DM, the provenance data model: https://www.w3.org/TR/prov-dm/ (checked 2026-10-27).
+- Model Context Protocol specification: https://modelcontextprotocol.io/specification/2025-06-18 (checked 2026-10-27).
+- Claude Code MCP setup (`claude mcp add`, scopes): https://docs.claude.com/en/docs/claude-code/mcp (checked 2026-10-27).
+- Cursor MCP configuration (`.cursor/mcp.json`): https://docs.cursor.com/context/model-context-protocol (checked 2026-10-27).

package/interface/tooling/integrations.json

@@ -0,0 +1,112 @@
+[
+  {
+    "id": "claude-code",
+    "name": "Claude Code",
+    "layer": "interface",
+    "role": "default interface: agent sessions over the vault, repos, skills and connectors",
+    "interfaces": [
+      "cli",
+      "app"
+    ],
+    "reach": [
+      "purpose",
+      "knowledge",
+      "operations",
+      "evidence",
+      "governance"
+    ],
+    "interface_kind": "agent-harness",
+    "status": "in-use",
+    "reason": "Reads and writes the vault and every repo, runs skills and hooks, reaches Linear, Notion and GitHub through connectors"
+  },
+  {
+    "id": "cursor",
+    "name": "Cursor",
+    "layer": "interface",
+    "role": "editor-centred agent harness over the repos and vault",
+    "interfaces": [
+      "app"
+    ],
+    "reach": [
+      "purpose",
+      "knowledge",
+      "operations",
+      "evidence",
+      "governance"
+    ],
+    "interface_kind": "agent-harness",
+    "status": "in-use",
+    "reason": ".cursor/ rules and agents in the vault and repos"
+  },
+  {
+    "id": "codex",
+    "name": "OpenAI Codex",
+    "layer": "interface",
+    "role": "agent harness (CLI and app)",
+    "interfaces": [
+      "cli",
+      "app"
+    ],
+    "reach": [
+      "knowledge",
+      "operations",
+      "evidence"
+    ],
+    "interface_kind": "agent-harness",
+    "status": "candidate",
+    "reason": "Named by the owner; same shape as Claude Code"
+  },
+  {
+    "id": "hermes-agent",
+    "name": "Hermes Agent",
+    "layer": "interface",
+    "role": "open-source agent harness",
+    "interfaces": [
+      "cli"
+    ],
+    "reach": [
+      "knowledge",
+      "operations",
+      "evidence"
+    ],
+    "interface_kind": "agent-harness",
+    "status": "candidate",
+    "reason": "Named by the owner; reach to confirm"
+  },
+  {
+    "id": "grok",
+    "name": "Grok agent",
+    "layer": "interface",
+    "role": "agent harness",
+    "interfaces": [
+      "app"
+    ],
+    "reach": [
+      "knowledge",
+      "operations",
+      "evidence"
+    ],
+    "interface_kind": "agent-harness",
+    "status": "candidate",
+    "reason": "Named by the owner as Grokbot; which xAI product is meant, and its reach, to confirm"
+  },
+  {
+    "id": "operator-console",
+    "name": "Operator console",
+    "layer": "interface",
+    "role": "local viewer over the records",
+    "interfaces": [
+      "app"
+    ],
+    "status": "candidate",
+    "reason": "interface/operator-console",
+    "reach": [
+      "purpose",
+      "knowledge",
+      "operations",
+      "evidence",
+      "governance"
+    ],
+    "interface_kind": "custom"
+  }
+]

package/knowledge/connectors/README.md

@@ -0,0 +1,54 @@
+---
+type: reference
+source: hybrid
+created: 2026-10-28T01:10:00Z
+ai-model: claude-opus-5.5
+tags: [everything-ecosystem, knowledge, connectors, storage]
+description: "How the knowledge layer reaches the sources a venture keeps records in: the connector contract, the source map, the catalog and the evals (EE-037)."
+---
+
+# Knowledge connectors
+
+The knowledge layer is where every record is stored and found. It does not copy records into one place. Each venture keeps its records wherever it already works, and Mentura reaches each source through a connector (EE-037).
+
+## The parts
+
+| Part | File | What it does |
+|---|---|---|
+| Contract | `contract.mjs` | The five things every connector does: `list`, `read`, `version`, `search`, `write`. A version is the git blob SHA-1 of the content in every source. |
+| Registry | `../tooling/integrations.json` | An integration with a `connector` names the module that implements the contract for it. |
+| Source map | `<venture>/knowledge/sources.json` | Optional. The venture's sources, and which record type lives in which. Unnamed record types stay in the venture folder. Schema: `schema/knowledge-sources.schema.json`; checked by `schema/check-sources.mjs`. |
+| Connectors | `filesystem.mjs` | A folder or git repository (writes in place). The framework ships only this one: it works offline and names no vendor. Connectors that reach a vendor, such as GitHub, are platform and live in `platform/connectors/` (EE-041). |
+| Matrix | `resolve.mjs` | The source-of-truth matrix (EE-042): `rules` in the source map name a system of record and owner per record type, attribute and context (phase, product, account, actor). The most specific rule wins; a tie is an error. `records` is shorthand for rules that match anything. An attribute rule (a price in another source) is read from and written to that source, so the record's own file holds no second copy. |
+| Where-used | `<venture>/knowledge/where-used.json` | For each fact kept once (a price, a product name), every place that repeats it, live or frozen. `schema/check-where-used.mjs` reports drift offline; delivering the change into vendors is the platform's. |
+| Catalog | `catalog.mjs` | One index over every source: address, version, route, title and words. No content. Routes `knowledge/catalog` and `knowledge/search`. |
+| Evals | `suite.mjs`, `eval.mjs` | `suite.mjs` is the contract suite every connector passes, framework or platform. `eval.mjs` runs it on the filesystem connector, then the router over a mapped folder and the catalog. The GitHub connector's evals are `platform/connectors/eval.mjs`. |
+
+## A source map
+
+```json
+{
+  "sources": [
+    { "id": "team-repo", "connector": "github", "repo": "acme/tandem", "ref": "main", "root": "ventures/tandem" }
+  ],
+  "records": { "product": "team-repo" }
+}
+```
+
+The `github` connector is a platform connector (`platform/connectors/github.mjs`). With this map, `purpose/product/kettle` reads `ventures/tandem/products/kettle.json` from `acme/tandem` and says which version and commit it came from. A write opens a draft pull request, which a person accepts by merging. Every other record stays in the venture folder. The venture folder always keeps `venture.json`, the provenance log and drafts.
+
+## Adding a connector
+
+1. Decide which side it is on. If it works offline, needs no credentials and names no vendor, it is framework and goes in `knowledge/connectors/<id>.mjs`. Otherwise it is platform and goes in `platform/connectors/<id>.mjs` (EE-041). `node schema/check-boundary.mjs` enforces this.
+2. Export `connect(options)`, returning an object that meets the contract.
+3. Add a `connector` to its entry in `knowledge/tooling/integrations.json`: the module, its write modes and its options.
+4. Run it through `contract()` from `suite.mjs`: against a fake of its API offline, and against the real one when credentials are given.
+
+## Running the evals
+
+```sh
+node knowledge/connectors/eval.mjs                                                       # framework
+node platform/connectors/eval.mjs                                                        # platform (GitHub, against a fake)
+MENTURA_EVAL_GITHUB_REPO=owner/name GITHUB_TOKEN=... node platform/connectors/eval.mjs   # also live
+MENTURA_EVAL_GITHUB_WRITE=1 ...                                                          # and open one real draft PR
+```

package/knowledge/connectors/catalog.mjs

@@ -0,0 +1,118 @@
+// The catalog (EE-037): one index over every item in every source of a venture, so a person or an
+// agent can find a record without knowing where it lives. For each item it keeps the address,
+// source, path, version, route and record type (when the item is a record), a title and the set
+// of words in it. It keeps no content: the words are a sorted set, not the text, and reading an
+// item always goes back to its source. A rebuild reads only items whose version changed.
+//
+//   node knowledge/connectors/catalog.mjs <venture dir> [--json]             build or refresh
+//   node knowledge/connectors/catalog.mjs <venture dir> --search <q> [--json] [--live]
+//          search the catalog (built first if there is none); --live asks each source instead
+//
+// The catalog is written to <venture>/_catalog/catalog.json. It is derived, so a venture may
+// ignore it in git; the router never routes _ folders.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { address, isText, words } from "./contract.mjs";
+import { connectAll } from "./index.mjs";
+
+export const FILE = "_catalog/catalog.json";
+const MAX_BYTES = 1_000_000;
+
+function title(path, content) {
+  if (path.endsWith(".json")) {
+    try { const j = JSON.parse(content); const t = j && typeof j === "object" && !Array.isArray(j) ? j.name ?? j.title ?? j.statement ?? j.id : null; if (typeof t === "string") return t.slice(0, 160); } catch {}
+  }
+  const fm = content.match(/^---\n[\s\S]*?\ntitle:\s*["']?(.+?)["']?\n[\s\S]*?\n---/);
+  if (fm) return fm[1];
+  const h = content.match(/^#\s+(.+)$/m);
+  return h ? h[1].trim() : path.split("/").at(-1);
+}
+
+// Which route a file in a source belongs to, from the route table (lazy, so the catalog works
+// without the router for a plain folder).
+let table = null;
+async function routeOf(path) {
+  if (!table) {
+    const { routes, glob } = await import("../../interface/router.mjs");
+    table = routes().filter((r) => r.kind === "record" && r.collection !== "list").map((r) => ({ r, res: r.files.map((g) => glob(g)) }));
+  }
+  for (const { r, res } of table) {
+    if (!res.some((re) => re.test(path))) continue;
+    if (r.collection !== "item") return { route: r.route, record: r.record };
+    for (const g of r.files) {
+      if (!g.includes("*")) continue;
+      const m = path.match(new RegExp("^" + g.split("*").map((s) => s.replace(/[.+^${}()|[\]\\]/g, "\\$&")).join("([^/]*)") + "$"));
+      if (m) return { route: r.route.replace("[id]", m[1]), record: r.record };
+    }
+    return { route: r.route, record: r.record };
+  }
+  return { route: null, record: null };
+}
+
+export const load = (dir) => existsSync(join(dir, FILE)) ? JSON.parse(readFileSync(join(dir, FILE), "utf8")) : null;
+
+/** Builds or refreshes the catalog. Returns it with stats: items, read (items fetched), reused. */
+export async function build(dir, { write = true, sources } = {}) {
+  const prior = new Map((load(dir)?.items ?? []).map((x) => [x.address, x]));
+  const conns = sources ?? await connectAll(dir);
+  const items = [];
+  const stats = { sources: conns.length, items: 0, read: 0, reused: 0, skipped: 0, errors: [] };
+  for (const { source, connector } of conns) {
+    let listed;
+    try { listed = await connector.list(); } catch (e) { stats.errors.push(`${source.id}: ${e.message}`); continue; }
+    for (const { path, version } of listed) {
+      const at = address(source.id, path);
+      const old = prior.get(at);
+      const where = await routeOf(path);
+      if (old && old.version === version) { items.push({ ...old, ...where }); stats.reused++; continue; }
+      if (!isText(path)) { items.push({ address: at, source: source.id, path, version, ...where, title: path.split("/").at(-1), terms: words(path) }); stats.skipped++; continue; }
+      const got = await connector.read(path);
+      stats.read++;
+      if (!got || got.content.length > MAX_BYTES || !isText(path, got.content)) { items.push({ address: at, source: source.id, path, version, ...where, title: path.split("/").at(-1), terms: words(path) }); continue; }
+      items.push({ address: at, source: source.id, path, version: got.version, ...where, title: title(path, got.content), terms: [...new Set(words(`${path}\n${got.content}`))].sort() });
+    }
+  }
+  stats.items = items.length;
+  const catalog = { built_at: new Date().toISOString(), sources: conns.map(({ source }) => ({ id: source.id, connector: source.connector })), items };
+  if (write) { mkdirSync(join(dir, "_catalog"), { recursive: true }); writeFileSync(join(dir, FILE), JSON.stringify(catalog) + "\n"); }
+  return { catalog, stats };
+}
+
+/** Items holding every word of the query, best first: words in the title count double. */
+export function search(catalog, query, { limit = 20 } = {}) {
+  const q = words(query);
+  if (!q.length) return [];
+  return catalog.items.map((x) => {
+    const terms = new Set(x.terms), t = words(x.title).join(" ");
+    if (!q.every((w) => terms.has(w) || x.terms.some((y) => y.startsWith(w)))) return null;
+    return { score: q.reduce((s, w) => s + (terms.has(w) ? 2 : 1) + (t.includes(w) ? 2 : 0), 0), ...x };
+  }).filter(Boolean).sort((a, b) => b.score - a.score || a.address.localeCompare(b.address)).slice(0, limit)
+    .map(({ terms, ...x }) => x);
+}
+
+/** Asks each source's own search instead of the catalog. */
+export async function searchLive(dir, query, { limit = 20 } = {}) {
+  const out = [];
+  for (const { source, connector } of await connectAll(dir)) {
+    try { for (const x of await connector.search(query, { limit })) out.push({ address: address(source.id, x.path), source: source.id, path: x.path, version: x.version, ...(await routeOf(x.path)) }); }
+    catch (e) { out.push({ source: source.id, error: e.message }); }
+  }
+  return out;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const [dir] = process.argv.slice(2).filter((a, i, all) => !a.startsWith("--") && all[i - 1] !== "--search");
+  const i = process.argv.indexOf("--search");
+  const json = process.argv.includes("--json");
+  if (!dir) { console.error("usage: node knowledge/connectors/catalog.mjs <venture dir> [--search <q>] [--live] [--json]"); process.exit(2); }
+  if (i >= 0) {
+    const q = process.argv[i + 1] ?? "";
+    const hits = process.argv.includes("--live") ? await searchLive(dir, q) : search(load(dir) ?? (await build(dir)).catalog, q);
+    console.log(json ? JSON.stringify({ query: q, hits }, null, 2) : hits.map((h) => `${h.address}  ${h.title ?? ""}${h.route ? `  (${h.route})` : ""}`).join("\n") || "no items match");
+  } else {
+    const { stats } = await build(dir);
+    console.log(json ? JSON.stringify(stats, null, 2) : `catalog: ${stats.items} items from ${stats.sources} sources (${stats.read} read, ${stats.reused} unchanged)${stats.errors.length ? `\n${stats.errors.join("\n")}` : ""}`);
+    if (stats.errors.length) process.exitCode = 1;
+  }
+}

package/knowledge/connectors/contract.mjs

@@ -0,0 +1,56 @@
+// The connector contract (EE-037). A connector reaches one source of records (a folder, a GitHub
+// repository, later a database, Notion or Salesforce) and does the same five things for every one:
+//
+//   list(prefix)            [{ path, version }] for every item under the prefix, sorted by path
+//   read(path)              { path, content, version, commit?, permalink? }, or null when it is missing
+//   version(path)           the item's version, or null when it is missing
+//   search(query, {limit})  [{ path, version }] for items whose text holds every word of the query
+//   write(path, content, {message, title})
+//                           { path, version, commit?, pull_request? }; how it writes is the
+//                           connector's `writes`: direct (in place), pull-request (a draft pull
+//                           request; merging it accepts the write) or none (read-only, write throws)
+//
+// Paths are relative to the source's root and use forward slashes; a path that leaves the root is
+// refused. Content is UTF-8 text. A version is the git blob SHA-1 of the content, whichever
+// connector holds it, so the same content has the same version in every source and a version
+// can be checked without asking the source. An item's address is <source id>://<path>; with its
+// version it is what provenance cites.
+
+import { createHash } from "node:crypto";
+
+export const METHODS = ["list", "read", "version", "search", "write"];
+export const WRITES = ["direct", "pull-request", "none"];
+
+/** The git blob SHA-1 of some content: what `git hash-object` prints. */
+export const blobSha = (content) => {
+  const buf = Buffer.isBuffer(content) ? content : Buffer.from(content, "utf8");
+  return createHash("sha1").update(`blob ${buf.length}\0`).update(buf).digest("hex");
+};
+
+/** A path inside a source, normalised, or an error for one that is empty or leaves the root. */
+export function safePath(p) {
+  if (typeof p !== "string" || !p.length || p.includes("\0") || p.includes("\\") || p.startsWith("/")) throw new Error(`${JSON.stringify(p)} is not a path inside the source`);
+  const parts = p.split("/").filter((s) => s && s !== ".");
+  if (!parts.length || parts.includes("..")) throw new Error(`${p} is not a path inside the source`);
+  return parts.join("/");
+}
+
+export const address = (sourceId, path) => `${sourceId}://${path}`;
+
+/** Every word of the query, lowercased, appears in the text. */
+export const matches = (text, query) => {
+  const t = text.toLowerCase();
+  return words(query).every((w) => t.includes(w));
+};
+export const words = (s) => String(s).toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((w) => w.length > 1);
+
+/** Text a catalog may index: small files that are not binary. */
+export const isText = (path, content) => !/\.(png|jpe?g|gif|webp|ico|pdf|zip|gz|woff2?|ttf|mp4|mov)$/i.test(path) && (content === undefined || !content.includes("\0"));
+
+/** Checks an object has the contract's methods and a known `writes`. Returns the problems. */
+export function conformance(c) {
+  const problems = METHODS.filter((m) => typeof c?.[m] !== "function").map((m) => `no ${m}()`);
+  if (!WRITES.includes(c?.writes)) problems.push(`writes is ${c?.writes}, not one of ${WRITES.join(", ")}`);
+  if (typeof c?.id !== "string") problems.push("no id");
+  return problems;
+}

package/knowledge/connectors/eval.mjs

@@ -0,0 +1,176 @@
+// Evals for the framework's connectors (EE-037, EE-041). The framework ships one connector, the
+// file system, which works offline and names no vendor; connectors that reach a vendor are
+// platform and have their own evals (platform/connectors/eval.mjs), against the same suite.
+// Three parts:
+//
+//   contract   the shared suite (suite.mjs) on the filesystem connector, in a plain folder and in
+//              a git repository, plus the venture-folder rules
+//   router     a venture whose source map keeps one record type in another folder: reads come
+//              from there with their version, a write lands there and is logged by address,
+//              nothing invalid reaches the source, and every other record stays in the venture
+//   catalog    one index across both sources, and a rebuild reads only what changed
+//
+//   node knowledge/connectors/eval.mjs
+
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdtempSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { blobSha } from "./contract.mjs";
+import { contract, FIXTURE, harness, OUTSIDE } from "./suite.mjs";
+import { connect as fsConnect } from "./filesystem.mjs";
+import { build, FILE, load, search } from "./catalog.mjs";
+
+const repo = new URL("../..", import.meta.url).pathname;
+const h = harness("connectors");
+const { expect, write, scratch, finish } = h;
+
+// The filesystem connector, in a plain folder.
+const fsMake = (git) => async ({ writes = "direct" } = {}) => {
+  const d = mkdtempSync(join(scratch, "fs-"));
+  write(join(d, "kb"), FIXTURE);
+  write(d, OUTSIDE);
+  if (git) {
+    const g = (...a) => spawnSync("git", ["-C", d, ...a], { encoding: "utf8" });
+    g("init", "-q"); g("add", "."); g("-c", "user.name=eval", "-c", "user.email=eval@example.com", "commit", "-qm", "fixture");
+  }
+  return { c: fsConnect({ id: "folder", root: join(d, "kb"), writes }), dir: d };
+};
+await contract(h, "filesystem (plain folder)", fsMake(false));
+const gitT = await contract(h, "filesystem (git repository)", fsMake(true));
+{
+  const fresh = await fsMake(true)();
+  const r = await fresh.c.read("notes/beta.md");
+  const head = spawnSync("git", ["-C", fresh.dir, "rev-parse", "HEAD"], { encoding: "utf8" }).stdout.trim();
+  expect("filesystem (git repository): a committed, unchanged item gives the commit that last touched it", r.commit === head);
+  await fresh.c.write("notes/beta.md", "changed\n");
+  expect("filesystem (git repository): a changed item gives no commit, since no commit holds that version", !(await fresh.c.read("notes/beta.md")).commit);
+  void gitT;
+}
+{
+  const d = mkdtempSync(join(scratch, "venture-"));
+  write(d, { "venture.json": "{}", "purpose/telos.json": "{}", "_drafts/x.draft": "{}", "studio/venture.json": "{}", "studio/purpose/telos.json": "{}" });
+  const v = fsConnect({ root: d, venture: true });
+  expect("filesystem (venture folder): listing stops at a nested venture and skips private _ folders", JSON.stringify((await v.list()).map((x) => x.path)) === JSON.stringify(["purpose/telos.json", "venture.json"]));
+}
+
+// ---- Router --------------------------------------------------------------------------------------
+console.log("\n# router over a mapped source");
+const ws = join(scratch, "workspace");
+cpSync(join(repo, "schema/examples/workspace"), ws, { recursive: true });
+process.env.MENTURA_WORKSPACE = ws;
+const tandem = join(ws, "ventures/tandem");
+const shared = join(ws, "shared");
+const { call } = await import("../../interface/router.mjs");
+const { entries } = await import("../../interface/provenance.mjs");
+const kettle = { ...Object.values((await call({ venture: "tandem", route: "purpose/product", action: "read" })).result)[0], id: "kettle", name: "Kettle (in the shared folder)" };
+write(shared, { "products/kettle.json": JSON.stringify(kettle, null, 2) + "\n", "notes/launch.md": "# Launch plan\n\nShip the kettle subscription in spring.\n" });
+const map = { sources: [{ id: "shared", connector: "filesystem", root: "../../shared" }], records: { product: "shared" } };
+write(tandem, { "knowledge/sources.json": JSON.stringify(map, null, 2) + "\n" });
+const localProducts = existsSync(join(tandem, "products")) ? spawnSync("ls", [join(tandem, "products")], { encoding: "utf8" }).stdout.trim().split("\n") : [];
+
+const list = await call({ venture: "tandem", route: "purpose/product", action: "read" });
+expect("router: a mapped record type is read from its source, not the venture folder", list.ok && JSON.stringify(Object.keys(list.result)) === JSON.stringify(["kettle"]) && localProducts.length > 0, JSON.stringify(list).slice(0, 300));
+const one = await call({ venture: "tandem", route: "purpose/product/kettle", action: "read" });
+expect("router: a read says which source and version it came from", one.result?.name === "Kettle (in the shared folder)" && one.source?.address === "shared://products/kettle.json"
+  && one.source.version === blobSha(JSON.stringify(kettle, null, 2) + "\n"), JSON.stringify(one.source));
+const local = await call({ venture: "tandem", route: "purpose/validation/problem", action: "read" });
+expect("router: every record type the map does not name stays in the venture folder", local.ok && local.source?.source === "venture" && local.source.version === blobSha(readFileSync(join(tandem, "purpose/validation/problem.json"))));
+const teapot = { ...kettle, id: "teapot", name: "Teapot" };
+const bad = await call({ venture: "tandem", route: "purpose/product/teapot", action: "write", input: { id: "teapot" } });
+expect("router: a write that does not match the schema never reaches the source", !bad.ok && /does not match/.test(bad.error) && !existsSync(join(shared, "products/teapot.json")));
+const w = await call({ venture: "tandem", route: "purpose/product/teapot", action: "write", input: teapot, actor: "person", via: "cli", provenance: { note: "add the teapot" } });
+expect("router: a write lands in the mapped source, not the venture folder", w.ok && JSON.parse(readFileSync(join(shared, "products/teapot.json"), "utf8")).name === "Teapot" && !existsSync(join(tandem, "products/teapot.json")), JSON.stringify(w));
+const e = entries(tandem).at(-1);
+expect("router: the write is logged by address, with the source's version", e.entity === "shared://products/teapot.json" && e.source?.connector === "filesystem" && e.source.version === blobSha(readFileSync(join(shared, "products/teapot.json"))), JSON.stringify(e));
+const prov = spawnSync("node", [join(repo, "schema/check-provenance.mjs"), ws], { encoding: "utf8" });
+const srcCheck = (d) => spawnSync("node", [join(repo, "schema/check-sources.mjs"), d], { encoding: "utf8" });
+expect("router: check-provenance accepts entries for records in another source", prov.status === 0, prov.stderr);
+expect("router: check-sources accepts the map", srcCheck(ws).status === 0, srcCheck(ws).stderr);
+const valid = spawnSync("python3", ["-I", join(repo, "schema/validate.py"), "--schema", "knowledge-sources.schema.json", "--file", join(tandem, "knowledge/sources.json")], { encoding: "utf8" });
+expect("router: the map matches its schema", valid.status === 0, valid.stdout + valid.stderr);
+write(tandem, { "knowledge/sources.json": JSON.stringify({ sources: [{ id: "team-repo", connector: "notion" }], records: { product: "team-repo", venture: "team-repo" } }) });
+const broken = srcCheck(ws);
+expect("router: check-sources refuses an unknown connector and a record type that must stay in the folder", broken.status === 1 && /no connector notion/.test(broken.stderr) && /venture stays in the venture folder/.test(broken.stderr), broken.stderr);
+const refused = await call({ venture: "tandem", route: "purpose/product", action: "read" });
+expect("router: a read through an unknown connector fails and says which connectors exist", !refused.ok && /no connector notion: .*filesystem/.test(refused.error), refused.error);
+write(tandem, { "knowledge/sources.json": JSON.stringify({ ...map, sources: [{ ...map.sources[0], writes: "none" }] }) });
+const ro = await call({ venture: "tandem", route: "purpose/product/teapot", action: "write", input: teapot, actor: "person" });
+expect("router: a write to a read-only source is refused", !ro.ok && /read-only/.test(ro.error));
+write(tandem, { "knowledge/sources.json": JSON.stringify(map, null, 2) + "\n" });
+
+// ---- Catalog -------------------------------------------------------------------------------------
+console.log("\n# catalog");
+const { stats } = await build(tandem);
+const cat = load(tandem);
+expect("catalog: indexes every item in both sources", cat.items.some((x) => x.source === "shared" && x.path === "notes/launch.md") && cat.items.some((x) => x.source === "venture" && x.path === "purpose/validation/problem.json") && stats.errors.length === 0, JSON.stringify(stats));
+expect("catalog: every item has an address and its version", cat.items.every((x) => x.address === `${x.source}://${x.path}` && /^[0-9a-f]{40}$/.test(x.version)));
+expect("catalog: records are tied to their routes, wherever they live", cat.items.find((x) => x.address === "shared://products/kettle.json")?.route === "product/kettle" && cat.items.find((x) => x.path === "purpose/validation/problem.json")?.route === "foundation/problem");
+const s1 = search(cat, "kettle subscription spring");
+expect("catalog: search finds an item in the mapped source", s1[0]?.address === "shared://notes/launch.md" && s1[0].title === "Launch plan", JSON.stringify(s1.slice(0, 2)));
+const research = readFileSync(join(tandem, "knowledge/research/pilot-2026-10.md"), "utf8");
+expect("catalog: search finds an item in the venture folder", search(cat, "pilot").some((x) => x.address === "venture://knowledge/research/pilot-2026-10.md"));
+const raw = readFileSync(join(tandem, FILE), "utf8");
+const phrase = research.split("\n").find((l) => l.split(" ").length > 6)?.slice(0, 40);
+expect("catalog: keeps no content (no sentence of an item appears in it)", phrase && !raw.includes(phrase) && !raw.includes("Ship the kettle subscription"), phrase);
+const again = (await build(tandem)).stats;
+expect("catalog: a rebuild with nothing changed reads nothing", again.read === 0 && again.reused === stats.items, JSON.stringify(again));
+write(shared, { "notes/later.md": "# Later\n\nAdded after the first build.\n" });
+const changed = (await build(tandem)).stats;
+expect("catalog: after a change, a rebuild reads only the new item", changed.read === 1 && load(tandem).items.some((x) => x.address === "shared://notes/later.md"), JSON.stringify(changed));
+
+// ---- Matrix (EE-042) ------------------------------------------------------------------------------
+console.log("\n# source-of-truth matrix");
+const { resolve: resolveRule } = await import("./resolve.mjs");
+const { sourceFor } = await import("./index.mjs");
+const rule = (o) => ({ record: "product", attribute: "*", phase: "*", product: "*", account: "*", actor: "*", owner: "founder", ...o });
+const matrix = { sources: map.sources, records: {}, rules: [
+  rule({ system_of_record: "venture" }),
+  rule({ phase: "validation", system_of_record: "shared" }),
+  rule({ product: "kettle", phase: "validation", system_of_record: "venture", note: "the kettle stays in the folder" }),
+  rule({ attribute: "price", system_of_record: "shared" }),
+] };
+expect("matrix: the most specific rule wins", resolveRule(matrix, { record: "product", phase: "validation", product: "kettle" }).rule.note === "the kettle stays in the folder");
+expect("matrix: a rule narrowed to a phase holds only in that phase", resolveRule(matrix, { record: "product", phase: "validation" }).rule.system_of_record === "shared" && resolveRule(matrix, { record: "product", phase: "scale" }).rule.system_of_record === "venture");
+expect("matrix: a field the query leaves out matches only \"*\"", resolveRule(matrix, { record: "product" }).rule.system_of_record === "venture");
+expect("matrix: an attribute rule answers for that attribute, not for whole-record reads", resolveRule(matrix, { record: "product", attribute: "price" }).rule.attribute === "price" && resolveRule(matrix, { record: "product" }).rule.attribute === "*");
+expect("matrix: a record type no rule names falls back to the records shorthand, then to nothing", resolveRule({ records: { account: "shared" } }, { record: "account" }).rule.system_of_record === "shared" && resolveRule(matrix, { record: "telos" }) === null);
+expect("matrix: two rules that hold at once at the same specificity tie", resolveRule({ rules: [rule({ phase: "validation", system_of_record: "a" }), rule({ actor: "agent", system_of_record: "b" })] }, { record: "product", phase: "validation", actor: "agent" }).ties.length === 2);
+write(tandem, { "knowledge/sources.json": JSON.stringify(matrix, null, 2) + "\n" });
+expect("matrix: sourceFor reads the venture's phase from venture.json (tandem is in validation)", sourceFor(tandem, "product").id === "shared" && sourceFor(tandem, "product", { product: "kettle" }).id === "venture");
+const viaRouter = await call({ venture: "tandem", route: "purpose/product/teapot", action: "read" });
+const kettleWrite = await call({ venture: "tandem", route: "purpose/product/kettle", action: "write", input: { ...kettle, name: "Kettle (kept in the folder)" }, actor: "person" });
+expect("matrix: the router routes each read and write by its context", viaRouter.source?.source === "shared" && kettleWrite.ok && existsSync(join(tandem, "products/kettle.json")) && JSON.parse(readFileSync(join(shared, "products/kettle.json"), "utf8")).name === "Kettle (in the shared folder)", JSON.stringify([viaRouter.source, kettleWrite]));
+expect("matrix: check-sources accepts the matrix", srcCheck(ws).status === 0, srcCheck(ws).stderr);
+write(tandem, { "knowledge/sources.json": JSON.stringify({ ...matrix, rules: [...matrix.rules, rule({ actor: "agent", system_of_record: "venture" })] }, null, 2) + "\n" });
+const tie = srcCheck(ws);
+expect("matrix: check-sources refuses two rules that can tie", tie.status === 1 && /tie at the same specificity/.test(tie.stderr), tie.stderr);
+const tieRead = await call({ venture: "tandem", route: "purpose/product", action: "read", actor: "agent" });
+expect("matrix: a read that two rules tie on fails and says so", !tieRead.ok && /tie at the same specificity/.test(tieRead.error), tieRead.error);
+
+// Attributes mastered elsewhere: the product's description lives in the shared folder, the rest
+// of the product in the venture folder.
+const byAttr = { sources: map.sources, records: {}, rules: [rule({ system_of_record: "venture" }), rule({ attribute: "description", system_of_record: "shared" })] };
+write(tandem, { "knowledge/sources.json": JSON.stringify(byAttr, null, 2) + "\n" });
+write(shared, { "products/shop-app.json": JSON.stringify({ description: "Mastered in the shared folder" }, null, 2) + "\n" });
+const shop = await call({ venture: "tandem", route: "purpose/product/shop-app", action: "read" });
+expect("attributes: a read fills each attribute from its own system of record and cites it", shop.result?.description === "Mastered in the shared folder" && shop.source?.source === "venture" && shop.source.attributes?.description?.address === "shared://products/shop-app.json", JSON.stringify(shop.source));
+const shopList = await call({ venture: "tandem", route: "purpose/product", action: "read" });
+expect("attributes: list reads overlay too", shopList.result?.["shop-app"]?.description === "Mastered in the shared folder");
+write(shared, { "products/kettle.json": "{}\n" });
+const noFrag = await call({ venture: "tandem", route: "purpose/product/kettle", action: "read" });
+expect("attributes: a source holding nothing for the attribute leaves the record's own value and says so", noFrag.result?.name === "Kettle (kept in the folder)" && noFrag.result?.description === kettle.description && noFrag.source.attributes?.description?.missing === true, JSON.stringify(noFrag.source));
+const shopWrite = await call({ venture: "tandem", route: "purpose/product/shop-app", action: "write", input: { ...shop.result, description: "Changed once, in one place" }, actor: "person", provenance: { note: "new description" } });
+const own = JSON.parse(readFileSync(join(tandem, "products/shop-app.json"), "utf8"));
+const frag = JSON.parse(readFileSync(join(shared, "products/shop-app.json"), "utf8"));
+expect("attributes: a write sends the attribute to its system of record and leaves it out of the record's own file", shopWrite.ok && frag.description === "Changed once, in one place" && !("description" in own) && shopWrite.result.attributes?.[0]?.written === "shared://products/shop-app.json", JSON.stringify(shopWrite));
+expect("attributes: the attribute write is logged by address and attribute", entries(tandem).some((x) => x.entity === "shared://products/shop-app.json#description"));
+const after = await call({ venture: "tandem", route: "purpose/product/shop-app", action: "read" });
+expect("attributes: the next read shows the one value", after.result?.description === "Changed once, in one place");
+const badAttr = await call({ venture: "tandem", route: "purpose/product/shop-app", action: "write", input: { id: "shop-app" }, actor: "person" });
+expect("attributes: a record that fails its schema writes nothing anywhere", !badAttr.ok && JSON.parse(readFileSync(join(shared, "products/shop-app.json"), "utf8")).description === "Changed once, in one place");
+write(tandem, { "knowledge/sources.json": JSON.stringify({ ...byAttr, sources: [{ ...map.sources[0], writes: "none" }] }, null, 2) + "\n" });
+const roAttr = await call({ venture: "tandem", route: "purpose/product/shop-app", action: "write", input: after.result, actor: "person" });
+expect("attributes: a write whose attribute is mastered in a read-only source is refused before anything lands", !roAttr.ok && /read-only/.test(roAttr.error));
+write(tandem, { "knowledge/sources.json": JSON.stringify(map, null, 2) + "\n" });
+
+finish();