naive-framework 0.0.0-stage → 0.1.0

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-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,66 @@
+// 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();
+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`);
+  });
+  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, and no two matrix rules tie.`);

package/schema/check-team.mjs

@@ -0,0 +1,94 @@
+// Checks each venture's team plan (operations/team-plan.json) against the agent capability register
+// (evidence/capabilities/agent-capabilities.json) and decision rights (EE-029). Rules:
+//   roles: ids unique; a role not in the registry has a name; an agent occupies only a role the
+//     registry gives to agents, or its own.
+//   authority: each delegated class exists in the venture's decision rights; its owner is this
+//     role; no agent holds an escalate class (those stay with a person).
+//   human loops: every task cites a known capability. An agent's task that is cannot, not-allowed
+//     or unknown names a human loop, a person role in the plan; can-with-review names one too.
+//   recruiting: an open person role needed by the current phase is a role to recruit now; it needs
+//     a recruiting entry, and the entry's brief exists (paths relative to the venture folder).
+//   routes (robots, EE-032): each glob a role lists matches at least one route.
+// Also checks the register: ids unique; an entry with a url has a checked date; not-allowed cites
+// a decision class that exists; an eval file exists.
+//
+//   node schema/check-team.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-team.mjs <workspace or venture dir>"); process.exit(2); }
+const repo = new URL("..", import.meta.url).pathname;
+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 PHASES = ["discovery", "validation", "beachhead", "scale", "platform"];
+const registry = new Map(load(join(repo, "governance/venture-template/roles/agent-roles.json")).roles.map((r) => [r.id, r]));
+const template = load(join(repo, "governance/venture-template/decision-rights.json"));
+const caps = load(join(repo, "evidence/capabilities/agent-capabilities.json"));
+const errors = [], warnings = [], recruitNow = [];
+const { routes, glob: routeGlob } = await import("../interface/router.mjs");
+const routeList = routes().map((r) => r.route.replace("[id]", "x"));
+
+const capIds = caps.capabilities.map((c) => c.id);
+if (new Set(capIds).size !== capIds.length) errors.push("agent-capabilities.json: duplicate ids");
+const templateClasses = new Set(template.classes.map((c) => c.id));
+for (const c of caps.capabilities) for (const b of c.basis) {
+  if (b.url && !b.checked) errors.push(`agent-capabilities.json: ${c.id} cites a url with no checked date`);
+  if (b.eval && !existsSync(join(repo, b.eval))) errors.push(`agent-capabilities.json: ${c.id} eval ${b.eval} not found`);
+  if (b.decision_class && !templateClasses.has(b.decision_class)) errors.push(`agent-capabilities.json: ${c.id} cites unknown decision class ${b.decision_class}`);
+}
+for (const c of caps.capabilities) if (c.status === "not-allowed" && !c.basis.some((b) => b.decision_class)) errors.push(`agent-capabilities.json: ${c.id} is not-allowed but cites no decision class`);
+const cap = new Map(caps.capabilities.map((c) => [c.id, c]));
+
+let checked = 0;
+for (const root of walk(dir)) {
+  const v = load(join(root, "venture.json"));
+  const pPath = [join(root, "people/team-plan.json"), join(root, "operations/team-plan.json")].find((p) => existsSync(p)) ?? join(root, "operations/team-plan.json");
+  if (!existsSync(pPath)) continue;
+  checked++;
+  const plan = load(pPath), at = `${v.id}/operations/team-plan.json`;
+  // The venture's decision rights: the template, tightened by the venture's own file.
+  const classes = new Map(template.classes.map((c) => [c.id, c]));
+  const own = join(root, "governance/decision-rights.json");
+  if (existsSync(own)) for (const c of load(own).classes) classes.set(c.id, { ...classes.get(c.id), ...c });
+  const ids = plan.roles.map((r) => r.id);
+  if (new Set(ids).size !== ids.length) errors.push(`${at}: duplicate role ids`);
+  const persons = new Set(plan.roles.filter((r) => r.occupant === "person").map((r) => r.id));
+  for (const r of plan.roles) {
+    const reg = registry.get(r.id);
+    if (!reg && !r.name) errors.push(`${at}: ${r.id} is not in the role registry, so it needs a name`);
+    for (const g of [...(r.routes?.read ?? []), ...(r.routes?.write ?? [])]) if (!routeList.some((x) => routeGlob(g).test(x))) errors.push(`${at}: ${r.id} lists route ${g}, which matches no route`);
+    if (reg && reg.occupant === "person" && r.occupant === "agent") errors.push(`${at}: ${r.id} is a person's role in the registry; an agent cannot occupy it`);
+    for (const a of r.authority ?? []) {
+      const c = classes.get(a);
+      if (!c) { errors.push(`${at}: ${r.id} holds unknown decision class ${a}`); continue; }
+      if (c.owner !== r.id) errors.push(`${at}: ${r.id} holds ${a}, which decision rights give to ${c.owner}`);
+      if (r.occupant === "agent" && c.level === "escalate") errors.push(`${at}: ${r.id} is an agent and holds ${a}, an escalate class; a person decides it`);
+    }
+    for (const t of r.tasks ?? []) {
+      const c = cap.get(t.capability);
+      if (!c) { errors.push(`${at}: ${r.id} task cites unknown capability ${t.capability}`); continue; }
+      if (r.occupant === "agent" && c.status !== "can") {
+        if (!t.human_loop) errors.push(`${at}: ${r.id} does ${t.capability} (${c.status}), so it names a human loop`);
+        else if (!persons.has(t.human_loop)) errors.push(`${at}: ${r.id}'s human loop ${t.human_loop} is not a person role in the plan`);
+      }
+      if (r.occupant === "agent" && c.status === "not-allowed") warnings.push(`${at}: ${r.id} does ${t.capability}, which agents may not do; the agent prepares and ${t.human_loop ?? "a person"} acts`);
+    }
+    if (r.occupant === "person" && r.status === "open" && PHASES.indexOf(r.needed_by) <= PHASES.indexOf(v.phase)) {
+      recruitNow.push(`${v.id}: ${r.id}`);
+      const rec = (plan.recruiting ?? []).find((x) => x.role === r.id);
+      if (!rec) errors.push(`${at}: ${r.id} is needed now and open, but has no recruiting entry`);
+    }
+  }
+  for (const rec of plan.recruiting ?? []) {
+    if (!ids.includes(rec.role)) errors.push(`${at}: recruiting for unknown role ${rec.role}`);
+    if (!existsSync(join(root, rec.brief))) errors.push(`${at}: recruiting brief ${rec.brief} not found (paths are relative to the venture folder)`);
+    if (rec.assisted_by && plan.roles.find((r) => r.id === rec.assisted_by)?.occupant !== "agent") warnings.push(`${at}: recruiting for ${rec.role} is assisted by ${rec.assisted_by}, which is not an agent role in the plan`);
+  }
+}
+
+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 team plan: every agent task has its human loop${recruitNow.length ? `; recruit now: ${recruitNow.join(", ")}` : ""}.`);

package/schema/check-telos.mjs

@@ -0,0 +1,59 @@
+// Checks each venture's telos (purpose/telos.json, EE-023): start with the end. Rules:
+//   measures: ids unique, exactly one primary.
+//   phases: each phase listed once; every exit criterion serves at least one known measure,
+//     so each phase's exit traces back to the end; the venture's current phase has exit
+//     criteria (warning when it has none).
+//   owner outcome: the path exit.json prefers is the telos path, and the telos path is not
+//     ruled out there; an ambition that cannot fit the path is a warning (aggressive growth
+//     that intends to hold, or a hobby that intends an IPO).
+//   presence: a venture past Discovery, with an ambition beyond hobby, and no telos is a
+//     warning: the method starts with the end, but only the owner can write it.
+//
+//   node schema/check-telos.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-telos.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 tPath = join(root, "purpose/telos.json");
+  if (!existsSync(tPath)) {
+    if (v.phase !== "discovery" && v.ambition && v.ambition !== "hobby") warnings.push(`${v.id}: past Discovery with no purpose/telos.json; the owner should state the end first`);
+    continue;
+  }
+  checked++;
+  const t = load(tPath), at = `${v.id}/purpose/telos.json`;
+  const ids = t.measures.map((m) => m.id);
+  if (new Set(ids).size !== ids.length) errors.push(`${at}: duplicate measure ids`);
+  if (t.measures.filter((m) => m.primary).length !== 1) errors.push(`${at}: exactly one measure is primary`);
+  const seen = new Set();
+  for (const p of t.phases ?? []) {
+    if (seen.has(p.phase)) errors.push(`${at}: phase ${p.phase} listed twice`);
+    seen.add(p.phase);
+    for (const c of p.exit_criteria) for (const s of c.serves) if (!ids.includes(s)) errors.push(`${at}: ${p.phase}/${c.id} serves unknown measure ${s}`);
+  }
+  if (!seen.has(v.phase)) warnings.push(`${at}: no exit criteria for the current phase, ${v.phase}`);
+
+  const path = t.owner_outcome.path;
+  if (v.ambition === "aggressive-growth" && path === "hold") warnings.push(`${at}: aggressive growth usually means investors expecting an exit, but the owners intend to hold`);
+  if (v.ambition === "hobby" && ["ipo", "acquisition"].includes(path)) warnings.push(`${at}: a hobby that intends ${path}; is the ambition still hobby?`);
+  const ePath = join(root, "governance/exit.json");
+  if (existsSync(ePath)) {
+    const paths = load(ePath).paths;
+    const preferred = paths.filter((p) => p.stance === "preferred").map((p) => p.kind);
+    if (paths.some((p) => p.kind === path && p.stance === "ruled-out")) errors.push(`${v.id}/governance/exit.json: rules out ${path}, the path the telos intends`);
+    if (preferred.length && !preferred.includes(path)) errors.push(`${v.id}/governance/exit.json: prefers ${preferred.join(", ")}, but the telos intends ${path}`);
+  }
+}
+
+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 telos: every exit criterion traces to the end.`);