naive-framework 0.0.0-stage → 0.1.0

package/schema/check-data-model.mjs

@@ -0,0 +1,170 @@
+// Checks the data model (schema/data-model.json), the layer manifests and the venture
+// packages against the repository (EE-018, EE-071). Rules: record type ids are unique and
+// owned by a known layer; every JSON file in the repo is a record of some type (or ignored
+// with a reason), and every schema file governs one (or is a part one $refs); each reference
+// names a known record type and a check that exists, or says that nothing checks it yet;
+// every layer has a manifest at <layer>/layer.json; each record type is owned by exactly one
+// layer or one package; a layer that owns a record is of that record's layer; a package
+// declares use_model (an array, empty when it calls no model) and at most one skill;
+// layers and packages read and write only known types they do not own; every SKILL.md
+// belongs to exactly one layer or package.
+//
+//   node schema/check-data-model.mjs          check, and list unchecked references
+//   node schema/check-data-model.mjs --md     print the layer relationships derived from the manifests
+//
+// Layer relationships are never written by hand: they come from each manifest's reads and writes.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+
+// EE_ROOT points the check at another copy of the repository (used by schema/test.mjs).
+const root = process.env.EE_ROOT?.replace(/\/?$/, "/") ?? new URL("..", import.meta.url).pathname;
+const load = (p) => JSON.parse(readFileSync(join(root, p), "utf8"));
+const model = load("schema/data-model.json");
+const errors = [];
+const warnings = [];
+
+const files = (dir) => readdirSync(join(root, dir), { withFileTypes: true }).flatMap((e) =>
+  [".git", "node_modules", ".naive"].includes(e.name) ? [] : e.isDirectory() ? files(join(dir, e.name)) : [join(dir, e.name)]);
+// The files git would track (so build output and installed packages under .gitignore are left out); a
+// copy outside git, as the tests use, is walked instead.
+const tracked = spawnSync("git", ["ls-files", "--cached", "--others", "--exclude-standard"], { cwd: root, encoding: "utf8" });
+const all = tracked.status === 0 && tracked.stdout.trim() && !process.env.EE_ROOT ? tracked.stdout.trim().split("\n").filter((f) => existsSync(join(root, f))) : files(".").map((f) => relative(".", f));
+const glob = (g) => new RegExp("^" + g.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*\//g, "\0").replace(/\*/g, "[^/]*").replace(/\0/g, "(?:[^/]+/)*") + "$");
+const matches = (g) => all.filter((f) => glob(g).test(f));
+
+// Record types.
+const types = new Map();
+const layers = new Set(["system", ...model.layers]);
+for (const r of model.records) {
+  if (types.has(r.id)) errors.push(`data model: duplicate record type ${r.id}`);
+  types.set(r.id, r);
+  if (!layers.has(r.layer)) errors.push(`${r.id}: unknown layer ${r.layer}`);
+  if (r.schema && !existsSync(join(root, r.schema))) errors.push(`${r.id}: schema ${r.schema} not found`);
+  r.files = [...new Set(r.paths.flatMap(matches))];
+  if (!r.files.length) warnings.push(`${r.id}: no records yet at ${r.paths.join(", ")}`);
+}
+for (const r of types.values()) for (const ref of r.refs ?? []) {
+  if (!ref.to.startsWith("(") && !types.has(ref.to)) errors.push(`${r.id}.${ref.field}: refers to unknown record type ${ref.to}`);
+  if (ref.checked_by && !existsSync(join(root, ref.checked_by))) errors.push(`${r.id}.${ref.field}: check ${ref.checked_by} not found`);
+  if (!ref.checked_by) warnings.push(`${r.id}.${ref.field} -> ${ref.to}: nothing checks this reference yet`);
+}
+for (const c of model.records.filter((r) => r.contains)) for (const t of c.contains) if (!types.has(t)) errors.push(`${c.id}: contains unknown record type ${t}`);
+
+// Every JSON file is a record of some type; every schema file governs one.
+const claimed = new Set([...types.values()].flatMap((r) => r.files));
+const ignored = new Set(model.ignore.map((i) => i.path));
+const schemas = new Set([...types.values()].map((r) => r.schema).filter(Boolean));
+// A schema that a named schema $refs (a shared part, such as the validation evidence item) counts as named.
+for (const s of [...schemas]) for (const m of readFileSync(join(root, s), "utf8").matchAll(/"\$ref":\s*"([a-z0-9-]+\.schema\.json)/g)) schemas.add(`schema/${m[1]}`);
+for (const f of all.filter((f) => f.endsWith(".json"))) {
+  if (f.endsWith(".schema.json")) { if (!schemas.has(f)) errors.push(`${f}: a schema no record type names`); continue; }
+  if (!claimed.has(f) && !ignored.has(f)) errors.push(`${f}: no record type in schema/data-model.json covers this file`);
+}
+
+// Decision classes a record type names must exist in the decision-rights template (EE-032).
+const classIds = new Set(load("governance/venture-template/decision-rights.json").classes.map((c) => c.id));
+for (const r of types.values()) if (r.decision_class && !classIds.has(r.decision_class)) errors.push(`${r.id}: unknown decision class ${r.decision_class}`);
+
+// Layers and packages (EE-071). A layer manifest is <layer>/layer.json. A package that lists
+// `records` owns those record types (the validation package absorbed the old validation kit).
+const layerFiles = [...model.layers.map((l) => `${l}/layer.json`), "schema/layer.json"];
+const packageFiles = all.filter((f) => /^packages\/[^/]+\/package\.json$/.test(f));
+const skillsOf = (k) => [...(k.skills ?? []), ...(k.skill ? [k.skill] : [])];
+const kits = new Map();
+const owner = new Map();
+const own = (id, t, k, p) => {
+  if (!types.has(t)) { errors.push(`${id}: owns unknown record type ${t}`); return; }
+  if (owner.has(t)) errors.push(`${t}: owned by both ${owner.get(t)} and ${id}`);
+  owner.set(t, id);
+  if (k.layer && types.get(t).layer !== k.layer) errors.push(`${id}: owns ${t}, which the data model gives to ${types.get(t).layer}`);
+  if (!k.layer && p.startsWith("packages/")) errors.push(`${id}: owns ${t} but names no layer`);
+};
+for (const p of layerFiles) {
+  if (!existsSync(join(root, p))) { errors.push(`${p}: missing; every layer has a manifest`); continue; }
+  const k = { ...load(p), path: p };
+  const folderLayer = p === "schema/layer.json" ? "system" : p.split("/")[0];
+  if (k.layer !== folderLayer) errors.push(`${p}: layer says ${k.layer}`);
+  const id = k.name ?? k.kit;
+  kits.set(id, k);
+  for (const t of k.records ?? []) own(id, t, k, p);
+  for (const c of k.checks ?? []) if (!existsSync(join(root, c))) errors.push(`${id}: check ${c} not found`);
+}
+for (const p of packageFiles) {
+  const k = { ...load(p), path: p };
+  if (!Array.isArray(k.use_model)) errors.push(`${p}: a package declares use_model, an array, empty when it calls no model`);
+  if (skillsOf(k).length > 1) errors.push(`${p}: a package has at most one skill`);
+  const id = k.name;
+  if ((k.records ?? []).length) {
+    kits.set(id, k);
+    for (const t of k.records) own(id, t, k, p);
+  }
+  for (const c of k.checks ?? []) if (!existsSync(join(root, c))) errors.push(`${id}: check ${c} not found`);
+  if (k.skill && !existsSync(join(root, k.skill.path))) errors.push(`${id}: skill ${k.skill.path} not found`);
+  if (k.template_dir && !existsSync(join(root, k.template_dir))) errors.push(`${id}: template dir ${k.template_dir} not found`);
+}
+for (const t of types.keys()) if (!owner.has(t)) errors.push(`${t}: no layer or package owns this record type`);
+for (const k of kits.values()) for (const rel of ["reads", "writes"]) for (const t of k[rel] ?? []) {
+  const id = k.name ?? k.kit;
+  if (!types.has(t)) errors.push(`${id}: ${rel} unknown record type ${t}`);
+  else if (owner.get(t) === id) errors.push(`${id}: ${rel} ${t}, which it owns; list only records owned elsewhere`);
+}
+for (const k of kits.values()) if (k.product) {
+  const id = k.name ?? k.kit;
+  const [v, pid] = k.product.split("/");
+  const card = all.find((f) => f.endsWith(`/${v}/products/${pid}.json`) || f.endsWith(`/${v}/product/${pid}.json`));
+  if (!card) errors.push(`${id}: product card ${k.product} not found`);
+}
+
+// Skills: each SKILL.md belongs to exactly one layer or package.
+const skillFiles = all.filter((f) => /(^|\/)SKILL\.md$/.test(f) && !f.includes("/_archive/") && model.layers.includes(f.split("/")[0]));
+const listed = new Map();
+for (const k of kits.values()) for (const s of skillsOf(k)) {
+  const id = k.name ?? k.kit;
+  if (!existsSync(join(root, s.path))) errors.push(`${id}/${s.id}: ${s.path} not found`);
+  if (listed.has(s.path)) errors.push(`${s.path}: listed by ${listed.get(s.path)} and ${id}`);
+  listed.set(s.path, id);
+  if (s.move_to && !kits.has(s.move_to)) errors.push(`${id}/${s.id}: move_to unknown owner ${s.move_to}`);
+}
+for (const f of skillFiles) if (!listed.has(f)) errors.push(`${f}: no layer or package lists this skill`);
+
+// Layer relationships, derived. The layer is the record type's layer (EE-071).
+const layerOf = (t) => types.get(t)?.layer;
+const edges = new Map();
+const edge = (from, to, t) => { if (!from || from === to) return; const key = `${from}>${to}`; edges.set(key, [...(edges.get(key) ?? []), t]); };
+for (const k of kits.values()) {
+  for (const t of k.reads ?? []) edge(layerOf(t), k.layer, t);
+  for (const t of k.writes ?? []) edge(k.layer, layerOf(t), t);
+}
+
+if (process.argv.includes("--md")) {
+  const order = [...model.layers, "system"];
+  const rows = order.map((l) => {
+    const k = [...kits.values()].find((x) => x.layer === l && String(x.path).endsWith("/layer.json"));
+    const from = [...edges].filter(([e]) => e.endsWith(`>${l}`)).map(([e, ts]) => `${e.split(">")[0]} (${[...new Set(ts)].join(", ")})`);
+    const to = [...edges].filter(([e]) => e.startsWith(`${l}>`)).map(([e, ts]) => `${e.split(">")[1]} (${[...new Set(ts)].join(", ")})`);
+    return `| ${l} | ${k?.skills.length ?? 0} | ${k?.records.join(", ") || "none"} | ${from.join("; ") || "none"} | ${to.join("; ") || "none"} |`;
+  });
+  console.log([
+    "### Layer relationships (generated by `node schema/check-data-model.mjs --md`)",
+    "",
+    "Each arrow is a record type one layer owns and another reads, or one layer writes into another. A reader depends on the owner: change the owner's record and the reader's checks run.",
+    "",
+    "| Layer | Skills | Owns | Takes from | Gives to |",
+    "| --- | --- | --- | --- | --- |",
+    ...rows,
+    "",
+    "```mermaid",
+    "flowchart LR",
+    ...[...edges].map(([e, ts]) => `  ${e.split(">")[0]} -->|${[...new Set(ts)].join(", ")}| ${e.split(">")[1]}`),
+    "```",
+  ].join("\n"));
+  process.exit(0);
+}
+
+for (const w of warnings) console.log(`warn  ${w}`);
+if (errors.length) { for (const e of errors) console.error(`FAIL  ${e}`); process.exit(1); }
+const moves = [...kits.values()].flatMap((k) => skillsOf(k).filter((s) => s.move_to)).length;
+const layerCount = layerFiles.filter((p) => existsSync(join(root, p))).length;
+console.log(`${types.size} record types, ${claimed.size} record files, ${layerCount} layers, ${packageFiles.length} packages, ${listed.size} skills (${moves} proposed moves): the data model holds.`);

package/schema/check-data-packages.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// Data packages and raw (EE-070). customers, investors and money hold [id].json master
+// records plus append-only _streams/<id>/. A stream.json declares sensitive. A sensitive
+// stream may version only stream.json and summary.md. raw/ is immutable: sources/<id>/
+// holds source.json and text.md, and original.* stays out of git. An idea map cites raw
+// ids once the venture has raw material.
+//
+//   node schema/check-data-packages.mjs <workspace or venture dir>
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const dir = process.argv[2];
+if (!dir) { console.error("usage: node schema/check-data-packages.mjs <workspace or venture dir>"); process.exit(2); }
+
+const PACKS = ["customers", "investors", "money"];
+const KEEP = new Set(["stream.json", "summary.md"]);
+const walk = (d) => existsSync(d) ? readdirSync(d, { withFileTypes: true }).flatMap((e) => e.name === "node_modules" || e.name.startsWith(".") ? []
+  : e.isDirectory() ? walk(join(d, e.name)) : e.name === "venture.json" ? [d] : []) : [];
+const load = (p) => JSON.parse(readFileSync(p, "utf8"));
+const tracked = (root, rel) => {
+  const g = spawnSync("git", ["ls-files", "--error-unmatch", "--", rel], { cwd: root, encoding: "utf8" });
+  return g.status === 0;
+};
+const inGit = (root) => spawnSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: root, encoding: "utf8" }).status === 0;
+
+const errors = [];
+let n = 0;
+for (const v of walk(dir)) {
+  n++;
+  const id = load(join(v, "venture.json")).id;
+  const git = inGit(v);
+  for (const pack of PACKS) {
+    const base = join(v, pack);
+    if (!existsSync(base)) continue;
+    for (const name of readdirSync(base)) {
+      if (name.startsWith("_") || name.startsWith(".")) continue;
+      const p = join(base, name);
+      if (!statSync(p).isFile() || !name.endsWith(".json")) errors.push(`${id}/${pack}/${name}: a master record is <id>.json`);
+    }
+    const streams = join(base, "_streams");
+    if (!existsSync(streams)) continue;
+    for (const s of readdirSync(streams)) {
+      const sd = join(streams, s);
+      if (!statSync(sd).isDirectory()) { errors.push(`${id}/${pack}/_streams/${s}: a stream is a folder`); continue; }
+      const meta = join(sd, "stream.json");
+      if (!existsSync(meta)) { errors.push(`${id}/${pack}/_streams/${s}: missing stream.json`); continue; }
+      const rec = load(meta);
+      if (typeof rec.sensitive !== "boolean") errors.push(`${id}/${pack}/_streams/${s}: stream.json must declare sensitive`);
+      if (rec.sensitive !== true) continue;
+      for (const f of readdirSync(sd)) {
+        if (KEEP.has(f)) continue;
+        const rel = join(pack, "_streams", s, f);
+        if (!git || tracked(v, rel)) errors.push(`${id}/${rel}: a sensitive stream versions only stream.json and summary.md`);
+      }
+    }
+  }
+  const sources = join(v, "raw/sources");
+  if (existsSync(sources)) for (const s of readdirSync(sources)) {
+    const sd = join(sources, s);
+    if (!statSync(sd).isDirectory() || s.startsWith(".")) continue;
+    if (!existsSync(join(sd, "source.json"))) errors.push(`${id}/raw/sources/${s}: missing source.json`);
+    if (!existsSync(join(sd, "text.md"))) errors.push(`${id}/raw/sources/${s}: missing text.md`);
+    for (const f of readdirSync(sd)) if (f.startsWith("original.") && (!git || tracked(v, join("raw/sources", s, f)))) errors.push(`${id}/raw/sources/${s}/${f}: original.* stays out of git`);
+  }
+  const map = ["ideas/map.mdx", "purpose/ideas/map.mdx"].map((f) => join(v, f)).find((p) => existsSync(p));
+  const rawIds = new Set();
+  const dump = join(v, "raw/dump");
+  if (existsSync(dump)) for (const f of readdirSync(dump)) if (f !== ".gitkeep") rawIds.add(f.replace(/\.[^.]+$/, ""));
+  if (existsSync(sources)) for (const s of readdirSync(sources)) if (!s.startsWith(".")) rawIds.add(s);
+  if (map && rawIds.size) {
+    const text = readFileSync(map, "utf8");
+    for (const m of text.matchAll(/<Idea ([^>]*)>/g)) {
+      const raw = m[1].match(/\braw="([^"]*)"/);
+      const ids = raw ? raw[1].split(",").map((x) => x.trim()).filter(Boolean) : [];
+      if (!ids.length) errors.push(`${id}: an idea map node cites no raw id`);
+      for (const rid of ids) if (!rawIds.has(rid)) errors.push(`${id}: idea map cites raw id ${rid}, which is not in raw/`);
+    }
+  }
+}
+if (errors.length) { console.error(errors.join("\n")); process.exit(1); }
+console.log(`${n} ventures: data packages and raw hold.`);

package/schema/check-departments.mjs

@@ -0,0 +1,45 @@
+// Checks each venture's departments (EE-047): every id in venture.json `departments` is in the
+// catalog (operations/departments.json) and has at least one folder; every department folder
+// holds a department.json whose tags match the catalog, is named for its department, sits
+// directly under departments/ or under the grouping folder for its place in the value chain, and
+// is listed in `departments`. A venture with no departments passes: they are imported only when
+// needed (EE-048).
+//
+//   node schema/check-departments.mjs <workspace or venture dir>
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { catalog, foldersOf } from "./departments.mjs";
+
+const dir = process.argv[2];
+if (!dir) { console.error("usage: node schema/check-departments.mjs <workspace or venture dir>"); process.exit(2); }
+const walk = (d) => readdirSync(d, { withFileTypes: true }).flatMap((e) => e.name === "node_modules" || e.name.startsWith(".") ? []
+  : e.isDirectory() ? walk(join(d, e.name)) : e.name === "venture.json" ? [d] : []);
+const byId = new Map(catalog().map((d) => [d.id, d]));
+const errors = [];
+let ventures = 0, folders = 0;
+for (const v of walk(dir)) {
+  const venture = JSON.parse(readFileSync(join(v, "venture.json"), "utf8"));
+  const listed = venture.departments ?? [];
+  const found = foldersOf(v);
+  if (!listed.length && !found.length) continue;
+  ventures++;
+  for (const id of listed) {
+    if (!byId.has(id)) errors.push(`${venture.id}: departments lists ${id}, which is not in operations/departments.json`);
+    else if (!found.some((f) => f.tag?.department === id)) errors.push(`${venture.id}: ${id} is listed but has no folder (node schema/add-department.mjs ${v} ${id})`);
+  }
+  for (const f of found) {
+    folders++;
+    const where = `${venture.id}: ${f.path}`;
+    if (!f.tag) { errors.push(`${where} has no department.json`); continue; }
+    const d = byId.get(f.tag.department);
+    if (!d) { errors.push(`${where}: unknown department ${f.tag.department}`); continue; }
+    if (f.folder !== d.id) errors.push(`${where}: folder is named ${f.folder} but holds ${d.id}`);
+    if (f.tag.value_chain !== d.value_chain) errors.push(`${where}: value_chain ${f.tag.value_chain}, the catalog says ${d.value_chain}`);
+    if (f.tag.apqc !== d.apqc.id) errors.push(`${where}: apqc ${f.tag.apqc}, the catalog says ${d.apqc.id}`);
+    if (f.group && f.group !== d.value_chain) errors.push(`${where}: grouped under ${f.group}/ but ${d.id} is a ${d.value_chain} activity`);
+    if (!listed.includes(d.id)) errors.push(`${where}: ${d.id} is not in venture.json departments`);
+  }
+}
+if (errors.length) { console.error(errors.join("\n")); process.exit(1); }
+console.log(`departments: ${ventures} venture(s), ${folders} folder(s), all match the catalog`);

package/schema/check-execution.mjs

@@ -0,0 +1,85 @@
+// Checks a venture's handoffs (operations, EE-038) and evidence records against its decision rights (EE-017).
+// Validate each file against its schema first; this checks how they fit together.
+//
+//   node schema/check-execution.mjs <venture dir>
+//
+// Rules: a venture's decision rights only tighten the template unless a decision is named;
+// every handoff names a known role, carries only classes that role owns, has a brief, at
+// least one conformance and one self-proof criterion (EE-006), stays within max_attempts
+// or is escalated, has passed its readiness check before going in progress (EE-019), and is escalated with an open question when its status says so. A done
+// handoff has a PR and passing evidence for every done-criterion; a review passes only from
+// its named reviewer, who is never the holder's role. Every evidence file's
+// passed flag matches its results.
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+const dir = process.argv[2];
+if (!dir) { console.error("usage: node schema/check-execution.mjs <venture dir>"); process.exit(2); }
+const root = new URL("..", import.meta.url).pathname;
+const load = (p) => JSON.parse(readFileSync(p, "utf8"));
+const jsonIn = (d) => existsSync(d) ? readdirSync(d).filter((f) => f.endsWith(".json")).map((f) => join(d, f)) : [];
+const RANK = { decide: 0, "decide-inform": 1, "recommend-approve": 2, escalate: 3 };
+
+const venture = load(join(dir, "venture.json"));
+const roles = new Set(load(join(root, "governance/venture-template/roles/agent-roles.json")).roles.map((r) => r.id));
+const template = load(join(root, "governance/venture-template/decision-rights.json"));
+const errors = [];
+
+const classes = new Map(template.classes.map((c) => [c.id, c]));
+const own = join(dir, "governance/decision-rights.json");
+if (existsSync(own)) for (const c of load(own).classes) {
+  const t = classes.get(c.id);
+  if (t && RANK[c.level] < RANK[t.level] && !c.decision) errors.push(`decision-rights/${c.id}: loosens ${t.level} to ${c.level} without naming a decision`);
+  classes.set(c.id, { ...t, ...c });
+}
+for (const c of classes.values()) if (!roles.has(c.owner)) errors.push(`decision-rights/${c.id}: owner ${c.owner} is not a role`);
+
+const results = new Map();
+for (const f of jsonIn(join(dir, "evidence/results"))) {
+  const e = load(f);
+  if (e.passed !== e.results.every((r) => r.passed)) errors.push(`evidence/${e.id}: passed says ${e.passed} but its results disagree`);
+  results.set(resolve(f), e);
+}
+
+let count = 0;
+for (const f of jsonIn(join(dir, "operations/handoffs"))) {
+  const h = load(f), at = `handoff/${h.id}`;
+  count++;
+  if (h.venture !== venture.id) errors.push(`${at}: venture ${h.venture} is not ${venture.id}`);
+  if (!roles.has(h.role)) errors.push(`${at}: role ${h.role} is not a role`);
+  if (!existsSync(join(dirname(f), h.brief))) errors.push(`${at}: brief ${h.brief} not found`);
+  for (const id of h.decision_classes) {
+    const c = classes.get(id);
+    if (!c) errors.push(`${at}: unknown decision class ${id}`);
+    else if (c.owner !== h.role) errors.push(`${at}: class ${id} belongs to ${c.owner}, not ${h.role}`);
+  }
+  const kinds = new Set(h.done_criteria.map((d) => d.kind));
+  if (!kinds.has("conformance")) errors.push(`${at}: no conformance criterion`);
+  if (!kinds.has("self-proof")) errors.push(`${at}: no self-proof criterion (EE-006)`);
+  for (const d of h.done_criteria) if (d.kind === "review" && (!roles.has(d.reviewer) || d.reviewer === h.role)) errors.push(`${at}/${d.id}: review needs a reviewer role other than the holder's`);
+  if (h.attempts > h.max_attempts) errors.push(`${at}: ${h.attempts} attempts exceed max_attempts ${h.max_attempts}`);
+  if (h.attempts === h.max_attempts && !["done", "escalated"].includes(h.status)) errors.push(`${at}: attempts used up, so it is done or escalated`);
+  const open = (h.escalations ?? []).filter((e) => !e.answer);
+  if (h.status === "escalated" && !open.length) errors.push(`${at}: escalated with no open question`);
+  if (h.status === "in-progress" && !h.ready_check) errors.push(`${at}: in progress without a recorded readiness check (node schema/check-ready.mjs --record)`);
+  if (!["draft", "ready"].includes(h.status) && !h.claimed_by) errors.push(`${at}: ${h.status} but not claimed`);
+  if (h.status === "done") {
+    if (!h.pr) errors.push(`${at}: done without a PR`);
+    const proved = new Set();
+    for (const p of h.evidence ?? []) {
+      const e = results.get(resolve(dirname(f), p));
+      if (!e) { errors.push(`${at}: evidence ${p} not found under evidence/results`); continue; }
+      if (e.subject.kind !== "handoff" || e.subject.id !== h.id) errors.push(`${at}: evidence ${e.id} is about ${e.subject.kind} ${e.subject.id}`);
+      for (const r of e.results.filter((x) => x.passed)) {
+        const c = h.done_criteria.find((d) => d.id === r.criterion);
+        if (c?.kind === "review" && (r.by !== c.reviewer || r.by === h.role)) { errors.push(`${at}: review ${c.id} must be passed by ${c.reviewer}, not ${r.by ?? "nobody named"}`); continue; }
+        proved.add(r.criterion);
+      }
+    }
+    for (const d of h.done_criteria) if (!proved.has(d.id)) errors.push(`${at}: done, but criterion ${d.id} has no passing evidence`);
+  }
+}
+
+if (errors.length) { console.error(errors.join("\n")); process.exit(1); }
+console.log(`${venture.id}: ${classes.size} decision classes, ${count} handoffs, ${results.size} evidence files: all execution rules hold.`);

package/schema/check-governance.mjs

@@ -0,0 +1,98 @@
+// Checks each venture's ownership-and-control records (EE-022): governance/ownership.json,
+// board.json, founder-agreement.json and exit.json, against each other and against
+// venture.json. These are records of legal facts; the check catches records that cannot
+// all be true, not bad advice. Rules:
+//   ownership: ids unique; grants and instruments name known holders and classes; a
+//     preferred class states its issue price; a cliff is no longer than its vesting; a
+//     percent split adds up to 100; an S corporation has one class of stock (IRC 1361);
+//     an LLC counts units and a corporation shares (warning).
+//   founders: two or more founder holders need a founder agreement that lists exactly
+//     them; unsigned or IP not assigned is a warning.
+//   boards: at most one formal board; reserved matters only on it; a seat is appointed by
+//     a known holder or class, or by the board; an investor seat by one holding board-seat.
+//   venture: venture-capital funding needs a cap table and a formal board; angel funding
+//     a cap table; two or more people in a formalized venture should have one (warning).
+//   exit: scenario ids unique, and every scenario's payouts add up to its value.
+//
+//   node schema/check-governance.mjs <workspace or venture dir>
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { payouts } from "./payouts.mjs";
+
+const dir = process.argv[2];
+if (!dir) { console.error("usage: node schema/check-governance.mjs <workspace or venture dir>"); process.exit(2); }
+const load = (p) => JSON.parse(readFileSync(p, "utf8"));
+const walk = (d) => readdirSync(d, { withFileTypes: true }).flatMap((e) => e.name === "node_modules" || e.name.startsWith(".") ? []
+  : e.isDirectory() ? walk(join(d, e.name)) : e.name === "venture.json" ? [d] : []);
+const errors = [], warnings = [];
+let checked = 0;
+
+for (const root of walk(dir)) {
+  const v = load(join(root, "venture.json"));
+  const g = (f) => { const p = join(root, "governance", f); return existsSync(p) ? load(p) : null; };
+  const own = g("ownership.json"), boards = g("board.json"), fa = g("founder-agreement.json"), exit = g("exit.json");
+  const at = (f) => `${v.id}/governance/${f}`;
+  const people = (v.members ?? []).filter((m) => typeof m === "string" || m.kind !== "agent").length;
+  const form = v.form ?? {};
+  if (form.funding === "venture-capital" && (!own || !boards?.boards.some((b) => b.kind === "formal"))) errors.push(`${v.id}: venture-capital funding needs governance/ownership.json and a formal board in governance/board.json`);
+  if (form.funding === "angel" && !own) errors.push(`${v.id}: angel funding needs governance/ownership.json`);
+  if (!own && people >= 2 && form.legal_form && form.legal_form !== "none") warnings.push(`${v.id}: ${people} people in a ${form.legal_form} but no governance/ownership.json`);
+  if (!own) { if (boards || fa || exit) errors.push(`${v.id}: board, founder agreement or exit records need governance/ownership.json`); continue; }
+  checked++;
+
+  const holders = new Map(), classes = new Map();
+  for (const h of own.holders) { if (holders.has(h.id)) errors.push(`${at("ownership.json")}: duplicate holder ${h.id}`); holders.set(h.id, h); }
+  for (const c of own.classes) { if (classes.has(c.id)) errors.push(`${at("ownership.json")}: duplicate class ${c.id}`); classes.set(c.id, c); }
+  for (const c of own.classes) if (c.kind === "preferred" && !(c.price_per_share > 0)) errors.push(`${at("ownership.json")}: preferred class ${c.id} needs price_per_share, the basis of its preference`);
+  for (const gr of own.grants) {
+    if (!holders.has(gr.holder)) errors.push(`${at("ownership.json")}: grant to unknown holder ${gr.holder}`);
+    if (!classes.has(gr.class)) errors.push(`${at("ownership.json")}: grant of unknown class ${gr.class}`);
+    if (gr.vesting && (gr.vesting.cliff_months ?? 0) > gr.vesting.months) errors.push(`${at("ownership.json")}: ${gr.holder}'s cliff is longer than their vesting`);
+  }
+  for (const i of own.instruments ?? []) if (!holders.has(i.holder)) errors.push(`${at("ownership.json")}: instrument ${i.id} held by unknown holder ${i.holder}`);
+  if (own.unit === "percent") { const sum = own.grants.reduce((n, gr) => n + gr.amount, 0); if (Math.abs(sum - 100) > 0.01) errors.push(`${at("ownership.json")}: a percent split adds up to ${sum}, not 100`); }
+  if (form.legal_form === "s-corp" && new Set(own.classes.map((c) => `${c.kind}:${c.price_per_share ?? ""}:${JSON.stringify(c.liquidation ?? {})}`)).size > 1) errors.push(`${at("ownership.json")}: an S corporation may have only one class of stock (classes may differ in votes only)`);
+  if (form.legal_form === "llc" && own.unit === "shares") warnings.push(`${at("ownership.json")}: an LLC usually counts units, not shares`);
+  if (["c-corp", "s-corp", "benefit-corp"].includes(form.legal_form) && own.unit === "units") warnings.push(`${at("ownership.json")}: a corporation counts shares, not units`);
+
+  const founders = own.holders.filter((h) => h.kind === "founder").map((h) => h.id);
+  if (founders.length >= 2 && !fa) errors.push(`${v.id}: ${founders.length} founders share ownership but there is no governance/founder-agreement.json`);
+  if (fa) {
+    const listed = fa.founders.map((f) => f.holder);
+    for (const f of founders) if (!listed.includes(f)) errors.push(`${at("founder-agreement.json")}: founder ${f} is not in the agreement`);
+    for (const f of listed) if (!founders.includes(f)) errors.push(`${at("founder-agreement.json")}: ${f} is not a founder holder in ownership.json`);
+    if (!fa.signed) warnings.push(`${at("founder-agreement.json")}: not signed yet`);
+    for (const f of fa.founders) if (!f.ip_assigned) warnings.push(`${at("founder-agreement.json")}: ${f.holder} has not assigned their IP to the venture`);
+    if (!existsSync(join(root, fa.document))) errors.push(`${at("founder-agreement.json")}: document ${fa.document} not found (paths are relative to the venture folder)`);
+  }
+
+  if (boards) {
+    if (boards.boards.filter((b) => b.kind === "formal").length > 1) errors.push(`${at("board.json")}: more than one formal board`);
+    for (const b of boards.boards) {
+      if (b.kind !== "formal" && b.reserved_matters?.length) errors.push(`${at("board.json")}: advisory board ${b.id} has reserved matters; an advisory board decides nothing`);
+      for (const s of b.seats) {
+        const by = s.appointed_by;
+        if (by !== "board" && !holders.has(by) && !classes.has(by)) errors.push(`${at("board.json")}: seat ${s.id} appointed by unknown ${by}`);
+        if (s.type === "investor" && b.kind === "formal") {
+          const rights = classes.get(by)?.rights ?? (own.instruments ?? []).filter((i) => i.holder === by).flatMap((i) => i.rights ?? []).concat(own.grants.filter((gr) => gr.holder === by).flatMap((gr) => classes.get(gr.class)?.rights ?? []));
+          if (!rights.includes("board-seat")) errors.push(`${at("board.json")}: investor seat ${s.id} is appointed by ${by}, which holds no board-seat right`);
+        }
+      }
+    }
+  }
+
+  if (exit) {
+    const ids = (exit.scenarios ?? []).map((s) => s.id);
+    if (new Set(ids).size !== ids.length) errors.push(`${at("exit.json")}: duplicate scenario ids`);
+    for (const s of exit.scenarios ?? []) {
+      const r = payouts(own, s.value);
+      const sum = r.payouts.reduce((n, p) => n + p.amount, 0);
+      if (Math.abs(sum - s.value) > 1) errors.push(`${at("exit.json")}: scenario ${s.id} pays out ${sum}, not ${s.value}`);
+    }
+  }
+}
+
+for (const w of warnings) console.warn(`warning: ${w}`);
+if (errors.length) { console.error(errors.join("\n")); process.exit(1); }
+console.log(`${checked} ventures with ownership records: every governance rule holds.`);

package/schema/check-integrations.mjs

@@ -0,0 +1,33 @@
+// Checks every layer's tooling/integrations.json for the rules one entry's schema cannot
+// state: ids are unique within a layer, each entry's layer matches its folder, and every
+// entry under interface/ is an interface: it names its kind and reaches at least three of
+// the five other layers in one session (four of six before execution folded into operations, EE-038). A tool that serves one or two layers is an
+// integration of those layers (Obsidian under knowledge), however good its screen is.
+//
+//   node schema/check-integrations.mjs
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+// EE_ROOT points the check at another copy of the repository (used by schema/test.mjs).
+const root = process.env.EE_ROOT?.replace(/\/?$/, "/") ?? new URL("..", import.meta.url).pathname;
+const MIN_REACH = 3;
+const errors = [];
+let count = 0;
+for (const layer of readdirSync(root)) {
+  const f = join(root, layer, "tooling/integrations.json");
+  if (!existsSync(f)) continue;
+  const ids = new Set();
+  for (const t of JSON.parse(readFileSync(f, "utf8"))) {
+    count++;
+    if (ids.has(t.id)) errors.push(`${layer}: duplicate id ${t.id}`);
+    ids.add(t.id);
+    if (t.layer !== layer) errors.push(`${layer}/${t.id}: layer says ${t.layer}`);
+    if (layer === "interface") {
+      if (!t.interface_kind) errors.push(`interface/${t.id}: no interface_kind`);
+      if ((t.reach ?? []).length < MIN_REACH) errors.push(`interface/${t.id}: reaches ${(t.reach ?? []).length} layers; an interface reaches at least ${MIN_REACH}, so list it under the layers it serves`);
+    } else if (t.reach || t.interface_kind) errors.push(`${layer}/${t.id}: reach and interface_kind belong to interface entries only`);
+  }
+}
+if (errors.length) { console.error(errors.join("\n")); process.exit(1); }
+console.log(`${count} integrations: every interface reaches at least ${MIN_REACH} layers.`);

package/schema/check-nextjs-status.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// Checks docs/design/naive-nextjs-status.json against the Next.js translation ledger and the code: every
+// concept row in the ledger has exactly one status; a built or partial row cites files that exist and a
+// docs page that exists; and the generated "What's built" page matches the data.
+//
+//   node schema/check-nextjs-status.mjs            check, and print the counts
+//   node schema/check-nextjs-status.mjs --write    write site/content/docs/get-started/whats-built.mdx
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const repo = new URL("..", import.meta.url).pathname;
+const LEDGER = "docs/design/NAIVE_NEXTJS_TRANSLATION_2026-10-28.md";
+const STATUS = "docs/design/naive-nextjs-status.json";
+const PAGE = "site/content/docs/get-started/whats-built.mdx";
+const STATES = ["built", "partial", "not built", "n/a"];
+
+const ids = [...readFileSync(join(repo, LEDGER), "utf8").matchAll(/^\| ([A-Z]-\d+) \|/gm)].map((m) => m[1]);
+const data = JSON.parse(readFileSync(join(repo, STATUS), "utf8"));
+const errors = [];
+const seen = new Map();
+for (const r of data.rows) {
+  if (seen.has(r.id)) errors.push(`${r.id} has two entries`);
+  seen.set(r.id, r);
+  if (!ids.includes(r.id)) errors.push(`${r.id} is not a row of the ledger`);
+  if (!STATES.includes(r.status)) errors.push(`${r.id}: status ${r.status} is not one of ${STATES.join(", ")}`);
+  if (r.status === "built" || r.status === "partial") {
+    if (!r.evidence?.length) errors.push(`${r.id} is ${r.status} but cites no file`);
+    for (const f of r.evidence ?? []) if (!existsSync(join(repo, f))) errors.push(`${r.id} cites ${f}, which does not exist`);
+    if (!r.page) errors.push(`${r.id} is ${r.status} but names no docs page`);
+    else if (!existsSync(join(repo, "site/content/docs", `${r.page}.mdx`))) errors.push(`${r.id} names page ${r.page}, which does not exist`);
+  }
+}
+for (const id of ids) if (!seen.has(id)) errors.push(`${id} is in the ledger but has no status`);
+
+const count = (s) => data.rows.filter((r) => r.status === s).length;
+const counts = Object.fromEntries(STATES.map((s) => [s, count(s)]));
+
+function page() {
+  const chapters = [...new Set(data.rows.map((r) => r.chapter))];
+  const cell = (s) => String(s ?? "").replace(/\|/g, "\\|");
+  const lines = [
+    "---",
+    "title: What's built",
+    "description: Which of the 234 concepts translated from Next.js work today, which partly work, and which are design only.",
+    "type: reference",
+    "status: draft",
+    `lastReviewed: ${data.checked}`,
+    "owner: builder",
+    "---",
+    "",
+    `Use this page to tell what you can run today from what is designed but not built. Every concept in the Next.js translation ledger is listed, in the ledger's chapter order. It is generated from \`${STATUS}\` by \`node schema/check-nextjs-status.mjs --write\`, and the test suite fails when the two disagree.`,
+    "",
+    "## Summary",
+    "",
+    "| Status | Concepts | Meaning |",
+    "| --- | --- | --- |",
+    `| built | ${counts.built} | Works end to end and is tested |`,
+    `| partial | ${counts.partial} | Some of it works; the note says what is missing |`,
+    `| not built | ${counts["not built"]} | Designed in the ledger, not in the code yet |`,
+    `| n/a | ${counts["n/a"]} | The ledger marks it as not converting from Next.js |`,
+    "",
+  ];
+  for (const c of chapters) {
+    const rows = data.rows.filter((r) => r.chapter === c);
+    lines.push(`## ${c.replace(/^Chapter \d+: /, "")}`, "", "| Concept | Status | Explained in | Note |", "| --- | --- | --- | --- |");
+    for (const r of rows) lines.push(`| ${r.id} | ${r.status} | ${r.page && r.page !== "get-started/whats-built" ? `[${r.page.split("/").at(-1)}](/docs/${r.page})` : ""} | ${cell(r.note)} |`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+if (process.argv.includes("--write")) { writeFileSync(join(repo, PAGE), page()); console.log(`wrote ${PAGE}`); }
+else if (!existsSync(join(repo, PAGE)) || readFileSync(join(repo, PAGE), "utf8") !== page()) errors.push(`${PAGE} is out of date: run node schema/check-nextjs-status.mjs --write`);
+
+if (errors.length) { console.error(errors.join("\n")); process.exit(1); }
+console.log(`${data.rows.length} concepts: ${STATES.map((s) => `${counts[s]} ${s}`).join(", ")}`);