naive-framework 0.0.0-stage → 0.2.0

package/schema/check-nextjs-status.mjs

@@ -0,0 +1,79 @@
+#!/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))];
+  // MDX reads { and < as code outside backticks, so they are escaped there.
+  const mdx = (t) => t.split(/(`[^`]*`)/).map((x, i) => i % 2 ? x : x.replace(/[{}]/g, (c) => `\\${c}`).replace(/</g, "&lt;").replace(/>/g, "&gt;")).join("");
+  const cell = (s) => mdx(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(", ")}`);

package/schema/check-nouns.mjs

@@ -0,0 +1,49 @@
+// Checks the system's nouns (EE-014). Fails when a retired noun from docs/ontology.json
+// reappears in the checked files, or when a noun cites a reference id that no layer's
+// references/references.json holds. With --md, prints the glossary as Markdown instead.
+//
+//   node schema/check-nouns.mjs            check
+//   node schema/check-nouns.mjs --md       print docs/ontology.md's glossary tables
+//
+// A line that names a retired noun on purpose (to say what replaced it) carries "(was"
+// or "retired" and is skipped.
+
+import { existsSync, readFileSync, readdirSync, statSync } 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 { check, nouns } = JSON.parse(readFileSync(join(root, "docs/ontology.json"), "utf8"));
+
+if (process.argv.includes("--md")) {
+  const row = (n) => `| ${n.noun} | ${n.meaning} | ${n.standard} | ${(n.references ?? []).join(", ")} |`;
+  for (const level of [...new Set(nouns.filter((n) => n.status !== "retired").map((n) => n.level))]) {
+    console.log(`\n### ${level[0].toUpperCase() + level.slice(1)}\n\n| Noun | Meaning | Standard | References |\n| --- | --- | --- | --- |`);
+    nouns.filter((n) => n.level === level && n.status !== "retired").forEach((n) => console.log(row(n)));
+  }
+  console.log(`\n### Retired\n\n| Noun | Status |\n| --- | --- |`);
+  nouns.filter((n) => n.status === "retired").forEach((n) => console.log(`| ${n.noun} | retired; use ${n.replaced_by} |`));
+  process.exit(0);
+}
+
+const walk = (p) => statSync(p).isDirectory()
+  ? readdirSync(p).flatMap((e) => walk(join(p, e)))
+  : /\.(mdx?|json|mjs)$/.test(p) ? [p] : [];
+const files = check.map((c) => join(root, c)).filter(existsSync).flatMap(walk)
+  .filter((f) => !f.endsWith("docs/ontology.json") && !f.endsWith("check-nouns.mjs"));
+const errors = [];
+for (const n of nouns.filter((x) => x.retired_pattern)) {
+  const re = new RegExp(n.retired_pattern, "i");
+  for (const f of files) readFileSync(f, "utf8").split("\n").forEach((line, i) => {
+    if (re.test(line) && !/\(was|retired/i.test(line)) errors.push(`${f.slice(root.length)}:${i + 1}: retired noun "${n.noun}" (use ${n.replaced_by})`);
+  });
+}
+// Layer references, and those of any kit inside a layer (<layer>/kits/<kit>/references).
+const refFiles = readdirSync(root).flatMap((d) => [join(d, "references/references.json"),
+  ...(existsSync(join(root, d, "kits")) ? readdirSync(join(root, d, "kits")).map((k) => join(d, "kits", k, "references/references.json")) : [])]);
+const known = new Set(refFiles.filter((f) => existsSync(join(root, f)))
+  .flatMap((f) => JSON.parse(readFileSync(join(root, f), "utf8")).references.map((r) => r.id)));
+for (const n of nouns) for (const r of n.references ?? []) if (!known.has(r)) errors.push(`docs/ontology.json: ${n.noun} cites unknown reference ${r}`);
+
+if (errors.length) { console.error(errors.join("\n")); process.exit(1); }
+console.log(`${nouns.length} nouns (${nouns.filter((n) => n.status === "retired").length} retired), ${files.length} files checked: no retired noun in use, every reference resolves.`);

package/schema/check-people.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// Checks venture types and people (EE-082) in a workspace: a venture's type is in schema/venture-types.json;
+// in people/people.json every role is in the role registry and allowed for the venture's type, every hat
+// is a function the venture imports, a solo venture has one person who wears every hat, and every
+// founder has a file in people/founders/ that agrees with the roster (and the roster lists every file).
+//
+//   node schema/check-people.mjs <workspace>
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { roles as ROLES, types as TYPES } from "./venture-type.mjs";
+
+const ws = process.argv[2];
+if (!ws || !existsSync(ws)) { console.error("usage: node schema/check-people.mjs <workspace>"); 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 types = new Map(TYPES().map((t) => [t.id, t]));
+const roles = new Map(ROLES().map((r) => [r.id, r]));
+const errors = [];
+let ventures = 0, rosters = 0;
+for (const dir of walk(ws)) {
+  ventures++;
+  const v = load(join(dir, "venture.json"));
+  const at = (m) => errors.push(`${v.id}: ${m}`);
+  const type = v.type ? types.get(v.type) : null;
+  if (v.type && !type) at(`type ${v.type} is not in schema/venture-types.json`);
+  const rosterFile = join(dir, "people/people.json");
+  const fdir = join(dir, "people/founders");
+  const files = existsSync(fdir) ? readdirSync(fdir).filter((f) => f.endsWith(".json")) : [];
+  if (!existsSync(rosterFile)) { if (files.length) at("people/founders/ has files but there is no people/people.json"); continue; }
+  rosters++;
+  const roster = load(rosterFile);
+  const imported = new Set(v.departments ?? []);
+  for (const p of roster.people) {
+    const role = roles.get(p.role);
+    if (!role) { at(`${p.id} has role ${p.role}, which is not in governance/venture-template/roles/venture-roles.json`); continue; }
+    if (type && !type.roles.includes(p.role)) at(`${p.id} is a ${p.role}, which a ${type.label.toLowerCase()} does not have (${type.roles.join(", ")})`);
+    for (const h of p.hats) if (imported.size && !imported.has(h)) at(`${p.id} wears the ${h} hat, but venture.json does not import ${h}`);
+    if (!role.owns_when_solo && p.hats.length) at(`${p.id} is a ${p.role}, who owns no function, but wears ${p.hats.join(", ")}`);
+    if (role.founder) {
+      const f = `people/founders/${p.id}.json`;
+      if (p.founder_file !== f) at(`${p.id} is a founder, so founder_file is ${f}`);
+      else if (!existsSync(join(dir, f))) at(`${f} is missing`);
+      else {
+        const rec = load(join(dir, f));
+        if (rec.id !== p.id || rec.role !== p.role) at(`${f} says ${rec.id} is a ${rec.role}; the roster says ${p.id} is a ${p.role}`);
+        if (JSON.stringify([...rec.hats].sort()) !== JSON.stringify([...p.hats].sort())) at(`${f} and the roster disagree on ${p.id}'s hats`);
+        if (rec.agreement && !existsSync(join(dir, rec.agreement.path))) at(`${f} links a founder agreement at ${rec.agreement.path}, which does not exist`);
+      }
+    }
+  }
+  if (roster.mode === "solo") {
+    if (roster.people.length !== 1) at(`a solo venture has one person; people/people.json lists ${roster.people.length}`);
+    else if (roles.get(roster.people[0].role)?.owns_when_solo && imported.size) {
+      const missing = [...imported].filter((h) => !roster.people[0].hats.includes(h));
+      if (missing.length) at(`${roster.people[0].id} is alone, so owns every function; missing ${missing.join(", ")}`);
+    }
+  }
+  if (roster.mode === "team" && imported.size) {
+    const worn = new Set(roster.people.flatMap((p) => p.hats));
+    const unowned = [...imported].filter((h) => !worn.has(h));
+    if (unowned.length) at(`no one owns ${unowned.join(", ")}`);
+  }
+  for (const f of files) if (!roster.people.some((p) => p.founder_file === `people/founders/${f}`)) at(`people/founders/${f} is not in people/people.json`);
+}
+for (const e of errors) console.log(`FAIL  ${e}`);
+console.log(`${ventures} ventures, ${rosters} people rosters: ${errors.length ? `${errors.length} error(s)` : "every role, hat and founder file agrees"}.`);
+process.exit(errors.length ? 1 : 0);

package/schema/check-private.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// Private records, fields, and sensitive streams never reach a model (EE-073).
+// Fails when a private target is named in a package use_model step's inputs, or when
+// a private record sits in a release that a package with use_model would read.
+//
+//   node schema/check-private.mjs <venture dir>
+
+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-private.mjs <venture dir>"); process.exit(2); }
+const repo = process.env.EE_ROOT?.replace(/\/?$/, "/") ?? new URL("..", import.meta.url).pathname;
+const load = (p) => JSON.parse(readFileSync(p, "utf8"));
+
+const packages = readdirSync(join(repo, "packages")).flatMap((name) => {
+  const p = join(repo, "packages", name, "package.json");
+  return existsSync(p) ? [load(p)] : [];
+});
+const inputs = packages.flatMap((pkg) => (pkg.use_model ?? []).flatMap((step) => {
+  if (typeof step === "string") return [{ package: pkg.name, input: step }];
+  return (step.inputs ?? []).map((input) => ({ package: pkg.name, input }));
+}));
+const readsRelease = packages.some((pkg) => (pkg.use_model ?? []).length > 0);
+
+function walk(d) {
+  if (!existsSync(d)) return [];
+  return readdirSync(d, { withFileTypes: true }).flatMap((e) => {
+    if (e.name === "node_modules" || e.name === ".git") return [];
+    const p = join(d, e.name);
+    return e.isDirectory() ? walk(p) : [p];
+  });
+}
+
+const privateTargets = new Set();
+const privateRecords = new Set();
+for (const f of walk(dir).filter((p) => p.endsWith(".json"))) {
+  let rec;
+  try { rec = load(f); } catch { continue; }
+  if (!rec || typeof rec !== "object" || Array.isArray(rec)) continue;
+  const id = typeof rec.id === "string" ? rec.id : null;
+  if (rec.private === true && id) { privateTargets.add(id); privateRecords.add(id); }
+  for (const field of rec.private_fields ?? []) if (id) privateTargets.add(`${id}.${field}`);
+  if (rec.sensitive === true && id) privateTargets.add(id);
+}
+
+const errors = [];
+for (const { package: name, input } of inputs) {
+  if (privateTargets.has(input) || privateRecords.has(input.split(".")[0])) errors.push(`${name}: use_model input ${input} is private and must not reach a model`);
+}
+if (readsRelease) {
+  const release = join(dir, ".release");
+  if (existsSync(release) && statSync(release).isDirectory()) {
+    for (const f of walk(release).filter((p) => p.endsWith(".json"))) {
+      const text = readFileSync(f, "utf8");
+      for (const id of privateRecords) if (text.includes(`"${id}"`)) errors.push(`.release mentions private record ${id}, and a package with use_model would read it`);
+    }
+  }
+}
+if (errors.length) { console.error(errors.join("\n")); process.exit(1); }
+console.log(`${dir}: private records stay off the model.`);

package/schema/check-provenance.mjs

@@ -0,0 +1,55 @@
+// Checks each venture's provenance log (<venture>/provenance.jsonl, EE-031).
+//   errors: a line that is not JSON; a broken chain (a line's prev is not the hash of the line
+//     before, or its hash does not match its content), which means a line was edited, removed or
+//     reordered; an entity outside the venture folder (a record in another source is logged by
+//     its address, <source>://<path>, and carries the source's version; EE-037).
+//   warnings: a logged file that has changed since its last entry, or is gone, so its later
+//     history is only in git; a derived_from path (not a URL or a decision id) that is not in the
+//     venture folder; time going backwards.
+// The schema of each line is checked by schema/validate.py.
+//
+//   node schema/check-provenance.mjs <workspace or venture dir>
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { contentHash, lineHash, LOG } from "../interface/provenance.mjs";
+
+const dir = process.argv[2];
+if (!dir) { console.error("usage: node schema/check-provenance.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 errors = [], warnings = [];
+let logs = 0, lines = 0;
+
+for (const root of walk(dir)) {
+  const f = join(root, LOG);
+  if (!existsSync(f)) continue;
+  logs++;
+  const id = JSON.parse(readFileSync(join(root, "venture.json"), "utf8")).id;
+  let prev = "genesis", at = "";
+  const last = new Map();
+  readFileSync(f, "utf8").split("\n").forEach((l, i) => {
+    if (!l.trim()) return;
+    const where = `${id}/${LOG}:${i + 1}`;
+    let e;
+    try { e = JSON.parse(l); } catch { errors.push(`${where}: not JSON`); prev = null; return; }
+    lines++;
+    if (prev !== null && e.prev !== prev) errors.push(`${where}: chain broken: prev does not match the line before (a line was edited, removed or reordered)`);
+    if (e.hash !== lineHash(e.prev, e)) errors.push(`${where}: hash does not match the line's content (the line was edited)`);
+    if (/^\/|(^|\/)\.\.(\/|$)/.test(e.entity ?? "") || (/^[a-z][a-z0-9+.-]*:\/\//.test(e.entity ?? "") && !e.source)) errors.push(`${where}: entity ${e.entity} is outside the venture folder`);
+    if (e.at < at) warnings.push(`${where}: time goes backwards`);
+    at = e.at; prev = e.hash;
+    if (typeof e.entity !== "string") { errors.push(`${where}: no entity`); return; }
+    if (!e.source) last.set(e.entity, e);
+    for (const d of e.derived_from ?? []) if (!/^[a-z][a-z0-9+.-]*:\/\//.test(d) && !/^[A-Z]+-\d+$/.test(d) && !d.startsWith("_drafts/") && !existsSync(join(root, d))) warnings.push(`${where}: derived from ${d}, which is not in the venture folder`);
+  });
+  for (const [entity, e] of last) {
+    const p = join(root, entity);
+    if (!existsSync(p)) { if (e.activity !== "draft") warnings.push(`${id}: ${entity} is in the log but gone; git holds what happened`); continue; }
+    if (contentHash(p) !== e.sha256) warnings.push(`${id}: ${entity} changed outside the router since ${e.at}; git holds that history`);
+  }
+}
+
+for (const w of warnings) console.warn(`warning: ${w}`);
+if (errors.length) { console.error(errors.join("\n")); process.exit(1); }
+console.log(`${logs} provenance logs, ${lines} entries: every chain holds.`);

package/schema/check-publication.mjs

@@ -0,0 +1,96 @@
+// Checks each venture's publication policy (governance/publication-policy.json, EE-025) and the
+// handoffs that publish. Every publication passes the gate. Rules:
+//   policy: channel, guideline and team ids unique; a team's members are known roles; a channel's
+//     guidelines are known; a guideline or channel config named by path exists (paths are
+//     relative to the venture folder); an outside guideline with a URL states when it was
+//     checked (warning); a channel following no brand or editorial guideline is a warning.
+//   platforms: a channel on a platform cites a platform guideline; a social, newsletter or
+//     app-store channel names its platform.
+//   replies: a social, newsletter or blog channel says how replies and comments are handled;
+//     delegated replies go to known roles or teams that include a person, never to agents alone.
+//   rights: drafters and approvers are known roles or teams; no agent approves, and a team
+//     approves only if a person is among its members; every rule has a person approving.
+//   handoffs: a handoff that publishes (public-commitment in its decision classes or its
+//     escalations) names a channel and a content rule the policy holds; a venture with such a
+//     handoff and no policy fails.
+//
+//   node schema/check-publication.mjs <workspace or venture dir>
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+const dir = process.argv[2];
+if (!dir) { console.error("usage: node schema/check-publication.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 roles = new Map(load(new URL("../governance/venture-template/roles/agent-roles.json", import.meta.url)).roles.map((r) => [r.id, r]));
+const errors = [], warnings = [];
+let checked = 0;
+
+for (const root of walk(dir)) {
+  const v = load(join(root, "venture.json"));
+  const pPath = join(root, "governance/publication-policy.json");
+  const policy = existsSync(pPath) ? load(pPath) : null;
+  const at = `${v.id}/governance/publication-policy.json`;
+  const hDir = join(root, "operations/handoffs");
+  const handoffs = existsSync(hDir) ? readdirSync(hDir).filter((f) => f.endsWith(".json")).map((f) => [f, load(join(hDir, f))]) : [];
+
+  for (const [f, h] of handoffs) {
+    const publishes = (h.decision_classes ?? []).includes("public-commitment") || (h.escalations ?? []).some((e) => e.class === "public-commitment");
+    const where = `${v.id}/operations/handoffs/${f}`;
+    if (!publishes) { if (h.publication) warnings.push(`${where}: names a publication but has no public-commitment class`); continue; }
+    if (!policy) { errors.push(`${where}: publishes, but the venture has no governance/publication-policy.json`); continue; }
+    if (!h.publication) { errors.push(`${where}: publishes, so it names its channel and content (publication)`); continue; }
+    const ch = policy.channels.find((c) => c.id === h.publication.channel);
+    if (!ch) errors.push(`${where}: unknown channel ${h.publication.channel}`);
+    else if (!ch.rules.some((r) => r.content === h.publication.content)) errors.push(`${where}: channel ${ch.id} has no rule for "${h.publication.content}"`);
+  }
+  if (!policy) continue;
+  checked++;
+
+  const dup = (xs, what) => { const ids = xs.map((x) => x.id); if (new Set(ids).size !== ids.length) errors.push(`${at}: duplicate ${what} ids`); };
+  dup(policy.channels, "channel"); dup(policy.guidelines ?? [], "guideline"); dup(policy.teams ?? [], "team");
+  const teams = new Map((policy.teams ?? []).map((t) => [t.id, t]));
+  for (const t of teams.values()) {
+    if (roles.has(t.id)) errors.push(`${at}: team ${t.id} has the same id as a role`);
+    for (const m of t.members) if (!roles.has(m)) errors.push(`${at}: team ${t.id} has unknown role ${m}`);
+  }
+  const guidelines = new Map((policy.guidelines ?? []).map((g) => [g.id, g]));
+  for (const g of guidelines.values()) {
+    if (g.path && !existsSync(join(root, g.path))) errors.push(`${at}: guideline ${g.id} not found at ${g.path} (paths are relative to the venture folder)`);
+    if (!g.path && !g.url) errors.push(`${at}: guideline ${g.id} needs a path or a url`);
+    if (g.url && !g.checked) warnings.push(`${at}: guideline ${g.id} has a url but no checked date`);
+  }
+
+  const person = (id) => roles.get(id)?.occupant === "person";
+  for (const c of policy.channels) {
+    for (const g of c.guidelines ?? []) if (!guidelines.has(g)) errors.push(`${at}: channel ${c.id} follows unknown guideline ${g}`);
+    if (!(c.guidelines ?? []).some((g) => ["brand", "editorial"].includes(guidelines.get(g)?.kind))) warnings.push(`${at}: channel ${c.id} follows no brand or editorial guideline`);
+    const onPlatform = ["social", "newsletter", "app-store"].includes(c.kind);
+    if (onPlatform && !c.platform) errors.push(`${at}: channel ${c.id} is ${c.kind}, so it names its platform`);
+    if (c.platform && !(c.guidelines ?? []).some((g) => guidelines.get(g)?.kind === "platform")) errors.push(`${at}: channel ${c.id} runs on ${c.platform} but cites none of its rules (a guideline of kind platform)`);
+    if (["social", "newsletter", "blog"].includes(c.kind) && !c.replies) errors.push(`${at}: channel ${c.id} says how replies and comments are handled (replies: gated, delegated or none)`);
+    if (c.replies?.mode === "delegated") {
+      const ds = c.replies.delegates ?? [];
+      if (!ds.length) errors.push(`${at}: channel ${c.id} delegates replies to no one`);
+      for (const id of ds) if (!roles.has(id) && !teams.has(id)) errors.push(`${at}: channel ${c.id} delegates replies to unknown role or team ${id}`);
+      if (ds.length && !ds.some((id) => person(id) || teams.get(id)?.members.some(person))) errors.push(`${at}: channel ${c.id} delegates replies to agents only; a person answers for the venture`);
+    }
+    if (c.config && !existsSync(join(root, c.config))) errors.push(`${at}: channel ${c.id} config not found at ${c.config}`);
+    for (const r of c.rules) {
+      const rule = `${at}: ${c.id} "${r.content}"`;
+      for (const id of [...(r.drafters ?? []), ...r.approvers]) if (!roles.has(id) && !teams.has(id)) errors.push(`${rule}: unknown role or team ${id}`);
+      for (const id of r.approvers) {
+        if (roles.has(id) && !person(id)) errors.push(`${rule}: ${id} is an agent role; agents draft and check, a person approves`);
+        if (teams.has(id) && !teams.get(id).members.some(person)) errors.push(`${rule}: team ${id} has no person, so it cannot approve`);
+      }
+      if (!r.approvers.some((id) => person(id) || teams.get(id)?.members.some(person))) errors.push(`${rule}: no person approves`);
+      for (const l of r.from_layers ?? []) if (v.layers && v.layers[l] === false) warnings.push(`${rule}: publishes from ${l}, which this venture has turned off`);
+    }
+  }
+}
+
+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 a publication policy: every publication passes the gate.`);

package/schema/check-ready.mjs

@@ -0,0 +1,89 @@
+// Checks that a handoff is ready to execute before anyone starts on it (EE-019): its
+// definition of ready. An agent that claims a handoff runs this first; a gap it finds is a
+// question for the handoff's author, asked before work starts, not an ambiguity discovered
+// halfway through. Every item is objective; judging whether the brief says enough is the
+// holder's first act, recorded with --record.
+//
+//   node schema/check-ready.mjs <venture dir> <handoff id>
+//   node schema/check-ready.mjs <venture dir> <handoff id> --record --by <role or session>
+//
+// --record writes `ready_check` into the handoff (and moves a draft to ready) only when
+// every item passes. check-execution.mjs refuses an in-progress handoff without one.
+
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const [dir, id] = process.argv.slice(2);
+if (!dir || !id) { console.error("usage: node schema/check-ready.mjs <venture dir> <handoff id> [--record --by <who>]"); process.exit(2); }
+const opt = (k) => process.argv.includes(k) ? process.argv[process.argv.indexOf(k) + 1] : undefined;
+const root = new URL("..", import.meta.url).pathname;
+const load = (p) => JSON.parse(readFileSync(p, "utf8"));
+const hPath = join(dir, "operations/handoffs", `${id}.json`);
+const h = load(hPath);
+const items = [];
+const item = (name, ok, why = "") => items.push({ name, ok, why });
+
+// 1. The brief says what done looks like and what to do, with no placeholders left.
+const bPath = join(dir, "operations/handoffs", h.brief);
+const brief = existsSync(bPath) ? readFileSync(bPath, "utf8") : "";
+item("brief exists", !!brief, bPath);
+const section = (name) => { const m = brief.match(new RegExp(`^##\\s+(?:\\d+\\.\\s*)?${name}\\b[^\\n]*\\n([\\s\\S]*?)(?=^##\\s|$(?![\\s\\S]))`, "mi")); return m ? m[1].trim() : null; };
+for (const s of ["Outcome", "Work"]) { const t = section(s); item(`brief has its ${s} section, with text`, !!t, t === null ? "missing" : "empty"); }
+const holes = brief.match(/\b(TBD|TODO|FIXME)\b|\?\?\?|<(?:title|role|entity|outcome|id|date)[^>]*>/gi) ?? [];
+item("brief has no placeholders left", !holes.length, holes.slice(0, 3).join(", "));
+
+// 2. Everything it names exists.
+const products = new Set(["products", "product"].flatMap((folder) => existsSync(join(dir, folder)) ? readdirSync(join(dir, folder)).filter((f) => f.endsWith(".json")).map((f) => f.slice(0, -5)) : []));
+const missingProducts = (h.products ?? []).filter((p) => !products.has(p));
+item("every product it serves exists", !missingProducts.length, missingProducts.join(", "));
+const logs = [join(root, "docs/decisions/decisions.json"), join(dir, "knowledge/decisions.json")].filter(existsSync).flatMap((f) => load(f).decisions);
+const decisions = new Map(logs.map((d) => [d.id, d]));
+const badDecisions = (h.governed_by ?? []).filter((d) => !decisions.has(d) || ["withdrawn", "superseded"].includes(decisions.get(d).status));
+item("every governing decision exists and is in force or proposed", !badDecisions.length, badDecisions.join(", "));
+// A method assignment (such as a MAD A-NNN) belongs to the build method a venture uses, which is
+// not part of Mentura (EE-038); a handoff may cite one, and this does not check it.
+const missingInputs = (h.inputs ?? []).filter((p) => !existsSync(join(root, p)));
+item("every input it needs exists", !missingInputs.length, missingInputs.join(", "));
+
+// 3. The holder can act inside its rights.
+const roles = new Set(load(join(root, "governance/venture-template/roles/agent-roles.json")).roles.map((r) => r.id));
+const classes = new Map(load(join(root, "governance/venture-template/decision-rights.json")).classes.map((c) => [c.id, c]));
+const own = join(dir, "governance/decision-rights.json");
+if (existsSync(own)) for (const c of load(own).classes) classes.set(c.id, { ...classes.get(c.id), ...c });
+item(`role ${h.role} exists`, roles.has(h.role));
+const foreign = h.decision_classes.filter((c) => classes.get(c)?.owner !== h.role);
+item("every decision class it carries belongs to its role", !foreign.length, foreign.join(", "));
+const open = (h.escalations ?? []).filter((e) => !e.answer);
+item("no escalation is waiting for an answer", !open.length, open.map((e) => `${e.class} to ${e.to}`).join(", "));
+item("attempts remain", h.attempts < h.max_attempts, `${h.attempts} of ${h.max_attempts}`);
+
+// 4. Done can be proved: the criteria exist and the scripts they call are there.
+const kinds = new Set(h.done_criteria.map((d) => d.kind));
+item("has a conformance and a self-proof criterion", kinds.has("conformance") && kinds.has("self-proof"));
+const scripts = h.done_criteria.filter((d) => d.kind !== "review").flatMap((d) => {
+  let cwd = root;
+  return d.check.split(/&&|\|/).flatMap((part) => {
+    const words = part.trim().split(/\s+/);
+    if (words[0] === "cd") { cwd = join(cwd, words[1]); return []; }
+    return words.filter((w) => /\.(mjs|js|py|sh)$/.test(w)).map((w) => ({ d: d.id, path: join(cwd, w) }));
+  });
+});
+const lost = scripts.filter((s) => !existsSync(s.path));
+item("every script a criterion runs exists", !lost.length, lost.map((s) => `${s.d}: ${s.path.slice(root.length)}`).join(", "));
+const badReview = h.done_criteria.filter((d) => d.kind === "review" && (!roles.has(d.reviewer) || d.reviewer === h.role));
+item("every review names a reviewer other than the holder", !badReview.length, badReview.map((d) => d.id).join(", "));
+
+for (const i of items) console.log(`${i.ok ? "pass" : "FAIL"}  ${i.name}${!i.ok && i.why ? `: ${i.why}` : ""}`);
+const ready = items.every((i) => i.ok);
+console.log(ready ? `${h.id} is ready to execute.` : `${h.id} is not ready: ask its author before starting.`);
+if (process.argv.includes("--record")) {
+  if (!ready) process.exit(1);
+  if (!opt("--by")) { console.error("--record needs --by <role or session>"); process.exit(2); }
+  const version = execSync("git rev-parse --short HEAD", { cwd: root, encoding: "utf8" }).trim();
+  h.ready_check = { at: new Date().toISOString().replace(/\.\d+Z$/, "Z"), by: opt("--by"), version, items: items.length };
+  if (h.status === "draft") h.status = "ready";
+  writeFileSync(hPath, JSON.stringify(h, null, 2) + "\n");
+  console.log(`recorded in ${hPath}`);
+}
+process.exit(ready ? 0 : 1);

package/schema/check-sources.mjs

@@ -0,0 +1,74 @@
+// Checks each venture's source map (<venture>/knowledge/sources.json, EE-037) for what its schema
+// cannot state: source ids are unique; each names a connector in the registry
+// (knowledge/tooling/integrations.json) and a write mode that connector supports; a GitHub source
+// names its repository; every record type it maps is a venture record type and goes to a source
+// it lists. The venture, its provenance log and the map itself stay in the venture folder, so they
+// cannot be mapped away. It does not connect to any source: the connector evals do that.
+//
+//   node schema/check-sources.mjs <workspace or venture dir>
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { LOCAL, MAP, registry } from "../knowledge/connectors/index.mjs";
+import { ANY, CONTEXT, specificity } from "../knowledge/connectors/resolve.mjs";
+
+const dir = process.argv[2];
+if (!dir) { console.error("usage: node schema/check-sources.mjs <workspace or venture dir>"); process.exit(2); }
+const root = new URL("..", import.meta.url).pathname;
+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 model = JSON.parse(readFileSync(join(root, "schema/data-model.json"), "utf8"));
+const ventureTypes = new Set(model.records.filter((r) => r.level === "venture").map((r) => r.id));
+const PINNED = new Set(["venture", "provenance", "knowledge-sources"]);
+const reg = registry();
+// The systems a function's truth can live in (EE-083); a connected one must have code that reads it.
+const catalog = JSON.parse(readFileSync(join(root, "schema/systems-catalog.json"), "utf8"));
+const errors = [];
+let maps = 0;
+
+for (const v of walk(dir)) {
+  const f = join(v, MAP);
+  if (!existsSync(f)) continue;
+  maps++;
+  const id = JSON.parse(readFileSync(join(v, "venture.json"), "utf8")).id;
+  const m = JSON.parse(readFileSync(f, "utf8"));
+  const ids = new Set([LOCAL]);
+  for (const s of m.sources ?? []) {
+    const where = `${id}: source ${s.id}`;
+    if (ids.has(s.id)) errors.push(`${where}: duplicate id${s.id === LOCAL ? " (venture is the venture's own folder)" : ""}`);
+    ids.add(s.id);
+    const c = reg.get(s.connector);
+    if (!c) { errors.push(`${where}: no connector ${s.connector} (the registry has ${[...reg.keys()].join(", ")})`); continue; }
+    if (s.writes && !c.writes.includes(s.writes)) errors.push(`${where}: ${s.connector} writes ${c.writes.join(" or ")}, not ${s.writes}`);
+    if (s.connector === "github" && !s.repo) errors.push(`${where}: a github source names its repo`);
+    for (const k of Object.keys(s).filter((k) => !["id", "connector", "writes", "note"].includes(k))) if (!(c.options ?? []).includes(k)) errors.push(`${where}: ${s.connector} takes no option ${k}`);
+  }
+  for (const [type, src] of Object.entries(m.records ?? {})) {
+    if (!ventureTypes.has(type)) errors.push(`${id}: ${type} is not a venture record type`);
+    if (PINNED.has(type)) errors.push(`${id}: ${type} stays in the venture folder`);
+    if (!ids.has(src)) errors.push(`${id}: ${type} goes to ${src}, which is not one of its sources`);
+  }
+  // The matrix (EE-042): every rule names a known record type and a known source, and two rules
+  // that can hold at once never tie. Product and account ids are not checked here: those records
+  // may themselves live in another source.
+  const rules = m.rules ?? [];
+  rules.forEach((rule, i) => {
+    const where = `${id}: rule ${i + 1} (${rule.record}${rule.attribute !== ANY ? `.${rule.attribute}` : ""})`;
+    if (!ventureTypes.has(rule.record)) errors.push(`${where}: ${rule.record} is not a venture record type`);
+    if (PINNED.has(rule.record)) errors.push(`${where}: ${rule.record} stays in the venture folder`);
+    if (!ids.has(rule.system_of_record)) errors.push(`${where}: system of record ${rule.system_of_record} is not one of its sources`);
+    for (const s of rule.survivorship?.also_in ?? []) if (!ids.has(s) || s === rule.system_of_record) errors.push(`${where}: survivorship names ${s}, which is not another of its sources`);
+  });
+  for (const [fn, f] of Object.entries(m.functions ?? {})) for (const s of f.systems) {
+    const sys = catalog.systems[s.system];
+    if (!sys) { errors.push(`${id}: ${fn} keeps its truth in ${s.system}, which is not in schema/systems-catalog.json`); continue; }
+    if (s.status === "connected" && !sys.connect) errors.push(`${id}: ${fn} says ${s.system} is connected, but no code reads ${sys.label} yet; it is pointed`);
+    if (s.source && !ids.has(s.source)) errors.push(`${id}: ${fn} names source ${s.source}, which is not in sources`);
+  }
+  const overlap = (a, b) => a.record === b.record && ["attribute", ...CONTEXT].every((k) => a[k] === ANY || b[k] === ANY || a[k] === b[k]);
+  for (let i = 0; i < rules.length; i++) for (let j = i + 1; j < rules.length; j++)
+    if (overlap(rules[i], rules[j]) && specificity(rules[i]) === specificity(rules[j]) && rules[i].attribute === rules[j].attribute)
+      errors.push(`${id}: rules ${i + 1} and ${j + 1} (${rules[i].record}) can both hold and tie at the same specificity; narrow one`);
+}
+if (errors.length) { console.error(errors.join("\n")); process.exit(1); }
+console.log(`${maps} source maps: every source has a connector, every record type a source, every function's systems are known, and no two matrix rules tie.`);