naive-framework 0.0.0-stage → 0.1.0

package/schema/decisions.mjs

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+// The decision matrix (EE-054, EE-057): every decision a venture has open, by layer and phase,
+// with its parent, its boundary and whether it renders now. Behaviors:
+// purpose/features/decisions.feature.
+//
+//   node schema/decisions.mjs <venture or workspace dir> [--json | --md]
+//
+// Sources: decision records (decisions/*.decision.json beside the record they decide), foundation
+// statements no person has confirmed, and agents' drafts of gated records waiting in _drafts/.
+// Need-now suggestions, failing checks and forecasts are not gathered yet.
+//
+// Like React's error boundaries, a boundary holds for everything under it: the venture root and
+// the foundation fail closed (a product-only workspace, venture.json kind "product", fails open),
+// a product fails open, and any other decision inherits its parent's boundary unless it sets one.
+// Under an open fail-closed decision, children wait and agents only draft (Suspense). A decision
+// made before its parent last changed is stale and shown to the owner again (revalidation). Like
+// a component rendered only when needed, a decision needed in a later phase is held back.
+// In Discovery a decided decision is still a working draft (EE-057). A decision is decided only
+// when a person approved its wording; provenance says who, when and in which phase (EE-058).
+//
+// render: overdue (open and past its due time), now (open, needed in this phase or earlier,
+//   nothing above it open and fail-closed),
+//   later (needed in a later phase; checked before waiting), waiting, stale, deferred, done, withdrawn.
+// Exit 1 on a duplicate id, an unknown parent, a cycle, or an id that takes a reserved root name.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative } from "node:path";
+import { FRAME, foundation } from "./foundation.mjs";
+import { agentFromEnv, record as prov } from "../interface/provenance.mjs";
+import { glob as routeFileGlob, routes } from "../interface/router.mjs";
+
+const repo = new URL("..", import.meta.url).pathname;
+const load = (f) => JSON.parse(readFileSync(f, "utf8"));
+const MODEL = load(join(repo, "schema/data-model.json"));
+export const PHASES = ["discovery", "validation", "beachhead", "scale", "platform"];
+const glob = (g) => new RegExp("^" + g.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*\//g, "\0").replace(/\*/g, "[^/]*").replace(/\0/g, "(?:[^/]+/)*") + "$");
+const FOUNDATION_RECORDS = new Set(FRAME.questions.flatMap((q) => q.statements).map((s) => s.record).filter(Boolean));
+
+/** The record type a venture-relative file belongs to. */
+export function recordOf(file) {
+  return MODEL.records.find((r) => r.level === "venture" && r.paths.some((p) => p.startsWith("instance/**/") && glob(p.slice("instance/**/".length)).test(file)))?.id ?? null;
+}
+
+// Every *.decision.json in a venture, outside drafts, hidden folders and nested ventures.
+function decisionFiles(dir, sub = "") {
+  return readdirSync(join(dir, sub), { withFileTypes: true }).flatMap((e) => {
+    const rel = sub ? `${sub}/${e.name}` : e.name;
+    if (e.isDirectory()) return e.name.startsWith(".") || e.name.startsWith("_") || existsSync(join(dir, rel, "venture.json")) ? [] : decisionFiles(dir, rel);
+    return e.name.endsWith(".decision.json") && sub.split("/").at(-1) === "decisions" ? [rel] : [];
+  });
+}
+
+/** Every decision of a venture, resolved: boundary, render state and what holds it. */
+export function decisions(dir, now = Date.parse(process.env.DECISIONS_NOW ?? "") || Date.now()) {
+  const venture = load(join(dir, "venture.json"));
+  const phase = PHASES.indexOf(venture.phase);
+  const productOnly = venture.kind === "product";
+  const report = foundation(dir);
+  const statements = report.flatMap((q) => q.statements);
+  const settled = statements.filter((s) => s.status !== "planned").every((s) => s.status === "confirmed");
+  const errors = [];
+
+  const list = [
+    { id: "venture", question: `Build ${venture.name} as a venture`, source: "root", layer: "governance", parent: null, boundary: productOnly ? "fail-open" : "fail-closed", status: "decided", decided_at: null },
+    { id: "foundation", question: `Settle the strategic foundation (${statements.filter((s) => !["confirmed", "planned"].includes(s.status)).length} statements open)`, source: "root", layer: "purpose", parent: "venture", boundary: productOnly ? "fail-open" : "fail-closed",
+      status: settled ? "decided" : "open", decided_at: null, needed_in: venture.phase },
+  ];
+  for (const f of decisionFiles(dir)) {
+    const d = load(join(dir, f));
+    // decisions/<record>[.<topic>].decision.json decides <record>.json in the folder that holds decisions/.
+    const at = f.split("/").slice(0, -2).join("/"), base = f.split("/").at(-1).split(".")[0];
+    const path = d.decides?.path ?? (at ? `${at}/${base}.json` : `${base}.json`);
+    const record = d.decides?.record ?? recordOf(path);
+    const layer = d.layer ?? MODEL.records.find((r) => r.id === record)?.layer ?? f.split("/")[0];
+    if (["venture", "foundation"].includes(d.id)) errors.push(`${f}: ${d.id} is a reserved root`);
+    // Provenance (EE-058): a decision is decided only when a person approved its wording, at a
+    // time and in a phase; an agent's wording waits for that approval.
+    const pv = d.provenance;
+    if (d.status === "decided" && !pv?.approved_by) errors.push(`${f}: decided, but names no one who decided`);
+    else if (d.status === "decided" && (!pv.approved_at || !pv.phase)) errors.push(`${f}: decided, but its provenance has no ${!pv.approved_at ? "approved_at" : "phase"}`);
+    if (pv?.approved_by && d.decided_by && pv.approved_by !== d.decided_by) errors.push(`${f}: decided_by ${d.decided_by} differs from provenance.approved_by ${pv.approved_by}`);
+    if (pv?.phase && PHASES.indexOf(pv.phase) > phase) errors.push(`${f}: approved in ${pv.phase}, a phase the venture has not reached`);
+    for (const o of d.outcomes ?? []) if (["met", "partly", "missed"].includes(o.result) && !o.actual) errors.push(`${f}: outcome ${o.id} is ${o.result} but records no actual outcome`);
+    const boundary = d.boundary && d.boundary !== "inherit" ? d.boundary : record === "product" ? "fail-open" : "inherit";
+    // A decision that settles a foundation statement is part of the foundation, not under it. One
+    // about a foundation record waits on that record's open statement, set below, not the whole foundation.
+    const parent = d.parent ?? (d.statement ? "venture" : null);
+    list.push({ ...d, file: f, source: "file", decides: { record, path }, layer, boundary, parent, ...(d.statement ? { part_of: "foundation" } : {}) });
+  }
+  const covered = new Set(list.map((d) => d.statement).filter(Boolean));
+  // The roll-up counts only the statements still open after decision records stand in for some.
+  list[1].question = `Settle the strategic foundation (${statements.filter((s) => !["confirmed", "planned"].includes(s.status) && !s.derived_from && !list.some((d) => d.statement === s.id && d.status === "decided")).length} statements open)`;
+  // A foundation statement no person has confirmed is a decision the founder still owes. It is
+  // part of the foundation rather than under it, so the foundation does not hold it.
+  for (const s of statements.filter((x) => !["confirmed", "planned"].includes(x.status) && !x.derived_from && !covered.has(x.id))) {
+    const question = { missing: `Write the ${s.id} statement`, draft: `Accept or change the agent's draft of the ${s.id} statement`, agent: `Confirm the ${s.id} statement an agent wrote` }[s.status] ?? `Confirm the ${s.id} statement (${s.status})`;
+    list.push({ id: `foundation-${s.id}`, question, source: "foundation", statement_status: s.status, layer: MODEL.records.find((r) => r.id === s.record)?.layer ?? "purpose",
+      decides: { record: s.record }, parent: "venture", part_of: "foundation", boundary: "inherit", status: "open", needed_in: venture.phase });
+  }
+  const statementFor = (record) => list.find((x) => x.part_of === "foundation" && x.status === "open" && x.decides?.record === record);
+  // An agent's draft of a gated record waits for a person to accept it.
+  const drafts = existsSync(join(dir, "_drafts")) ? readdirSync(join(dir, "_drafts")).filter((f) => f.endsWith(".draft")) : [];
+  for (const d of drafts) {
+    const path = d.replace(/\.draft$/, "").replace(/__/g, "/");
+    const record = recordOf(path);
+    // A draft of a foundation record is settled through its statement, which says to accept it.
+    const s = statementFor(record);
+    if (s?.statement_status === "draft") { s.decides = { record, path }; continue; }
+    list.push({ id: `draft-${path.replace(/[^a-z0-9]+/g, "-").replace(/-json$/, "")}`, question: `Accept or reject the agent's draft of ${path}`, source: "draft",
+      layer: MODEL.records.find((r) => r.id === record)?.layer ?? path.split("/")[0], decides: { record, path }, parent: FOUNDATION_RECORDS.has(record) ? (statementFor(record)?.id ?? "venture") : "venture",
+      boundary: "inherit", status: "open", needed_in: venture.phase });
+  }
+  // A decision about a foundation record waits on that record's open statement only, so one open
+  // statement does not hold every decision about the foundation.
+  for (const d of list) if (d.parent === null && d.source === "file") d.parent = (FOUNDATION_RECORDS.has(d.decides?.record) ? statementFor(d.decides.record)?.id : null) ?? "venture";
+
+  const byId = new Map();
+  for (const d of list) { if (byId.has(d.id)) errors.push(`decision ${d.id}: duplicate id`); else byId.set(d.id, d); }
+  for (const d of list) if (d.parent && !byId.has(d.parent)) { errors.push(`decision ${d.id}: unknown parent ${d.parent}`); d.parent = "venture"; }
+  const ancestors = (d) => {
+    const out = [];
+    for (let p = byId.get(d.parent); p; p = byId.get(p.parent)) {
+      if (p === d || out.includes(p)) { errors.push(`decision ${d.id}: its parents form a cycle`); break; }
+      out.push(p);
+    }
+    return out;
+  };
+  const chains = new Map(list.map((d) => [d.id, ancestors(d)]));
+  const boundaryOf = (d) => d.boundary !== "inherit" ? d.boundary : (chains.get(d.id).find((a) => a.boundary !== "inherit")?.boundary ?? "fail-closed");
+
+  const resolved = list.map((d) => {
+    const boundary = boundaryOf(d);
+    // An open decision above that fails closed holds this one. As with React's error boundaries the
+    // nearest boundary governs: a decision that fails open (a product) shields everything under it
+    // from the fail-closed decisions above it.
+    const holder = (() => {
+      if (d.boundary === "fail-open") return null;
+      for (const a of chains.get(d.id)) {
+        if (a.boundary === "fail-open") return null;
+        if (a.status !== "decided" && boundaryOf(a) === "fail-closed") return a;
+      }
+      return null;
+    })();
+    const parent = byId.get(d.parent);
+    const at = (x) => x?.provenance?.approved_at ?? x?.decided_at;
+    const stale = d.status === "decided" && at(d) && at(parent) && at(parent) > at(d);
+    // A due time is a real deadline: it overrides needed_in, and an open decision past it is overdue.
+    const later = !d.due && d.needed_in && PHASES.indexOf(d.needed_in) > phase;
+    const overdue = d.status === "open" && d.due && Date.parse(d.due) < now;
+    const render = d.status === "withdrawn" ? "withdrawn" : d.status === "deferred" ? "deferred" : stale ? "stale" : overdue ? "overdue"
+      : d.status === "decided" ? "done" : later ? "later" : holder ? "waiting" : "now";
+    const firmness = d.status !== "decided" ? "open" : venture.phase === "discovery" ? "working" : "firm";
+    // Lane (EE-060): a fail-closed decision is on the venture's ordered path, so what is under it waits;
+    // a fail-open one can move on its own, beside the rest, at whatever priority it ranks.
+    const lane = boundary === "fail-open" ? "async" : "sync";
+    return { id: d.id, question: d.question, source: d.source, layer: d.layer, parent: d.parent, boundary, lane, needed_in: d.needed_in ?? null, status: d.status, render, firmness,
+      ...(render === "waiting" || (overdue && holder) ? { held_by: holder.id } : {}),
+      ...(d.due ? { due: d.due, due_in_hours: Math.round((Date.parse(d.due) - now) / 36e5) } : {}), ...(d.part_of ? { part_of: d.part_of } : {}), ...(d.decides ? { decides: d.decides } : {}), ...(d.file ? { file: d.file } : {}), ...(d.answer ? { answer: d.answer } : {}), ...(d.ideas?.length ? { ideas: d.ideas } : {}),
+      ...(d.status === "open" && d.answer && d.provenance?.drafted_by?.kind === "agent" ? { awaiting: "approval" } : {}),
+      ...(d.provenance ? { provenance: d.provenance } : {}),
+      ...(d.outcomes?.length ? { outcomes: { total: d.outcomes.length, pending: d.outcomes.filter((o) => (o.result ?? "pending") === "pending").length,
+        due: d.outcomes.filter((o) => (o.result ?? "pending") === "pending" && /^\d{4}-\d{2}-\d{2}/.test(o.by ?? "") && Date.parse(o.by) < now).map((o) => o.id) } } : {}),
+      ...(d.unlocks?.length ? { unlocks: d.unlocks.map((u) => u.activity) } : {}),
+      ...(["open", "deferred"].includes(d.status) ? { action: actionFor(d, venture.id) } : {}) };
+  });
+  return { venture: venture.id, phase: venture.phase, kind: productOnly ? "product" : "venture", errors, decisions: rank(resolved, venture.phase, now) };
+}
+
+// The route that writes a venture-relative file, for the commands a founder runs.
+function routeOf(path, record) {
+  const r = routes().find((x) => x.kind === "record" && (path ? x.files.some((g) => routeFileGlob(g).test(path)) : x.record === record && x.collection !== "item"));
+  if (!r) return null;
+  return r.collection === "item" && path ? r.route.replace("[id]", path.split("/").at(-1).replace(/\.json$/, "")) : r.route;
+}
+
+/** How a person settles an open decision: the command to run, and the word to type to confirm it. */
+export function actionFor(d, venture) {
+  const v = `--venture ${venture}`;
+  if (d.source === "file") return { kind: "decide", confirm: d.id, command: `mentura decide ${d.id} ${v} --by <your name> [--answer "<your words>"]` };
+  const route = routeOf(d.decides?.path, d.decides?.record);
+  if (d.source === "draft" || d.statement_status === "draft") return { kind: "accept", route, confirm: route, command: `mentura accept ${route} ${v}` };
+  if (d.source === "foundation" && d.statement_status === "agent") { const id = d.id.replace(/^foundation-/, ""); return { kind: "confirm", statement: id, confirm: id, command: `mentura confirm ${id} ${v}` }; }
+  if (d.source === "foundation") return { kind: "write", route, command: `write ${route}${route ? "" : ` (${d.decides?.record})`} yourself, or ask an agent to draft it` };
+  return { kind: "settle", command: d.question };
+}
+
+/** A decision's own weight, before anything that waits on it (EE-057): a deadline, a stale parent, what
+ *  it unlocks, whether it settles the foundation, a draft ready to approve, outcomes to test. Scored for
+ *  every open decision, so a gate can carry the weight of what it holds (schema/docket.mjs). */
+export function ownScore(d, phase, now = Date.now()) {
+  const why = [];
+  let s = 0;
+  if (d.render === "overdue") { s += 100; why.push("past its due time"); }
+  // Cost of delay grows as the deadline nears: 40 at three days, 60 at two, 120 at one, up to 300.
+  else if (d.due) { const h = (Date.parse(d.due) - now) / 36e5; if (h <= 72) { s += Math.min(300, Math.round((60 * 48) / Math.max(h, 1))); why.push(`due in ${Math.max(0, Math.round(h))}h`); } }
+  if (d.render === "stale") { s += 30; why.push("its parent changed after it was decided"); }
+  if (d.unlocks?.length) { s += 10 * d.unlocks.length; why.push(`unlocks ${d.unlocks.join("; ")}`); }
+  if (d.part_of === "foundation") { s += phase === "discovery" ? 20 : 10; why.push("settles the strategic foundation"); }
+  if (d.awaiting) { s += 8; why.push("an agent has drafted it: approving takes a minute"); }
+  if (d.outcomes?.total) { s += 3 * d.outcomes.total; why.push(`${d.outcomes.total} expected outcome${d.outcomes.total > 1 ? "s" : ""} to test`); }
+  return { score: s, why };
+}
+
+/** Which open decisions matter most now, and why (EE-057): a decision's own weight plus 12 for each
+ *  decision that waits on it. Ranks the decisions that render now, overdue or stale; the others keep
+ *  rank null. Higher first; ties keep their order. */
+export function rank(ds, phase, now = Date.now()) {
+  const below = (id) => ds.filter((x) => x.held_by === id || x.parent === id).length;
+  const scored = ds.map((d) => {
+    if (!["now", "overdue", "stale"].includes(d.render) || d.source === "root") return { ...d, rank: null };
+    const { score, why } = ownScore(d, phase, now);
+    const n = below(d.id);
+    // Kept in the order the reasons were always given: deadline and staleness first, then what waits.
+    if (n) why.splice(why.findIndex((w) => !/due|parent changed/.test(w)) === -1 ? why.length : why.findIndex((w) => !/due|parent changed/.test(w)), 0, `${n} decision${n > 1 ? "s" : ""} wait on it`);
+    return { ...d, rank: score + 12 * n, why };
+  });
+  const order = scored.map((d, i) => [d, i]).sort(([a, i], [b, j]) => (b.rank ?? -1) - (a.rank ?? -1) || i - j).map(([d]) => d);
+  return order;
+}
+
+export function holding(dir, file) {
+  if (!existsSync(join(dir, "venture.json"))) return null;
+  const record = recordOf(file);
+  const m = decisions(dir).decisions.find((d) => d.source === "file" && (d.decides?.path === file || (!d.decides?.path && d.decides?.record === record))
+    && (d.render === "waiting" || d.render === "stale" || (d.status === "open" && d.boundary === "fail-closed")));
+  return m ? { id: m.id, why: m.render === "waiting" ? `waits on ${m.held_by}` : m.render === "stale" ? "is stale" : "is open and fails closed" } : null;
+}
+
+// Routes an unlock names are globs over routes, as in the team plan's robots.
+const routeGlob = (g) => new RegExp("^" + g.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "\0").replace(/\*/g, "[^/]*").replace(/\0/g, ".*") + "$");
+
+/** The decision that keeps a route closed to an actor (EE-058): an undecided decision that unlocks it. */
+export function locked(dir, route, actorId) {
+  if (!existsSync(join(dir, "venture.json"))) return null;
+  const files = decisionFiles(dir).map((f) => load(join(dir, f)));
+  const d = files.find((x) => x.status !== "decided" && x.status !== "withdrawn" && (x.unlocks ?? []).some((u) =>
+    (u.routes ?? []).some((g) => routeGlob(g).test(route)) && (!u.for?.length || !actorId || u.for.includes(actorId))));
+  return d ? { id: d.id, question: d.question } : null;
+}
+
+const validate = (d) => {
+  const scratch = mkdtempSync(join(tmpdir(), "decision-"));
+  const f = join(scratch, "d.json");
+  writeFileSync(f, JSON.stringify(d));
+  const v = spawnSync("python3", [join(repo, "schema/validate.py"), "--schema", "decision-record.schema.json", "--file", f], { encoding: "utf8" });
+  rmSync(scratch, { recursive: true, force: true });
+  return v.status === 0 ? null : (v.stdout + v.stderr).trim();
+};
+const fileOf = (dir, id) => decisionFiles(dir).find((f) => load(join(dir, f)).id === id);
+
+/** An agent proposes a decision, or new wording for an open one. It stays open until a person
+ *  approves it: an agent never decides (EE-058). at: the folder beside the record it decides. */
+export function propose(dir, input, { agentId, via = "router", harness, model } = {}) {
+  const { at = "", name, ...rest } = input ?? {};
+  if (!rest.id || !rest.question) return { ok: false, error: "a decision needs an id and a question" };
+  if (rest.status && rest.status !== "open") return { ok: false, error: "an agent may only propose an open decision; a person approves it" };
+  const existing = fileOf(dir, rest.id);
+  if (existing && load(join(dir, existing)).status === "decided") return { ok: false, error: `${rest.id} is decided; only a person can change it` };
+  const file = existing ?? `${at ? `${at}/` : ""}decisions/${name ?? rest.id}.decision.json`;
+  if (!existing && !/^([a-z0-9-]+\/)*decisions\/[a-z0-9.-]+\.decision\.json$/.test(file)) return { ok: false, error: `${file} is not a decisions/ path` };
+  // New wording for an open decision keeps what the agent did not restate: its parent, boundary, unlocks.
+  const before = existing ? load(join(dir, existing)) : {};
+  const d = { ...before, ...rest, status: "open", provenance: { drafted_by: { kind: "agent", ...(agentId ? { id: agentId } : {}) } } };
+  const bad = validate(d);
+  if (bad) return { ok: false, error: `does not match schema/decision-record.schema.json:\n${bad}` };
+  mkdirSync(dirname(join(dir, file)), { recursive: true });
+  writeFileSync(join(dir, file), JSON.stringify(d, null, 2) + "\n");
+  const e = prov(dir, { entity: file, route: "governance/decisions", activity: "draft", agent: agentFromEnv("agent", via, { ...(agentId ? { id: agentId } : {}), ...(harness ? { harness } : {}), ...(model ? { model } : {}) }), note: `proposed decision ${d.id}` });
+  return { ok: true, result: { proposed: d.id, file, awaiting: "approval", provenance: e.hash } };
+}
+
+/** A person approves a decision: as worded, or with their own answer. */
+export function approve(dir, id, { by, answer, via = "cli", note } = {}) {
+  const file = fileOf(dir, id);
+  if (!file) return { ok: false, error: `no decision ${id}` };
+  if (!by) return { ok: false, error: "approving needs the person's name (--by)" };
+  const d = load(join(dir, file));
+  if (d.status === "decided") return { ok: false, error: `${id} is already decided` };
+  if (!answer && !d.answer) return { ok: false, error: `${id} has no wording to approve; give an answer` };
+  const drafted = d.provenance?.drafted_by ?? { kind: "person", id: by };
+  const wording = !d.answer || drafted.kind === "framework" ? "own" : answer && answer !== d.answer ? (drafted.kind === "person" && drafted.id === by ? "own" : "changed") : drafted.kind === "person" ? "own" : "approved";
+  const phase = load(join(dir, "venture.json")).phase;
+  const out = { ...d, status: "decided", answer: answer ?? d.answer, provenance: { ...d.provenance, drafted_by: drafted, approved_by: by, approved_at: new Date().toISOString().replace(/\.\d+Z$/, "Z"), phase, wording, via } };
+  const bad = validate(out);
+  if (bad) return { ok: false, error: bad };
+  writeFileSync(join(dir, file), JSON.stringify(out, null, 2) + "\n");
+  const e = prov(dir, { entity: file, route: "governance/decisions", activity: "accept", agent: agentFromEnv("person", via, { id: by }), note: note ?? `approved decision ${id} (${wording})` });
+  return { ok: true, result: { decided: id, wording, phase, provenance: e.hash, unlocks: (out.unlocks ?? []).map((u) => u.activity) } };
+}
+
+/** The matrix: for each layer, the decisions that render now, wait, or come later, by phase. */
+export function matrix(r) {
+  const live = r.decisions.filter((d) => !["done", "withdrawn"].includes(d.render) && d.source !== "root");
+  const layers = [...new Set(live.map((d) => d.layer))].sort();
+  return layers.map((l) => ({ layer: l, ...Object.fromEntries(PHASES.map((p) => [p, live.filter((d) => d.layer === l && (d.needed_in ?? r.phase) === p).map((d) => `${d.id} (${d.render})`)])) }));
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const arg = process.argv[2];
+  if (!arg) { console.error("usage: node schema/decisions.mjs <venture or workspace dir> [--json | --md]"); process.exit(2); }
+  const walk = (d) => existsSync(join(d, "venture.json")) ? [d] : readdirSync(d, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith(".") && !e.name.startsWith("_")).flatMap((e) => walk(join(d, e.name)));
+  const dirs = walk(arg);
+  const rs = dirs.map((d) => ({ dir: d, ...decisions(d) }));
+  if (process.argv.includes("--json")) console.log(JSON.stringify(rs.length === 1 ? rs[0] : rs, null, 2));
+  else for (const r of rs) {
+    console.log(`\n${relative(process.cwd(), r.dir) || "."} (${r.phase}, ${r.kind})`);
+    const order = ["overdue", "stale", "now", "waiting", "later", "deferred", "done"];
+    const byDue = (a, b) => (b.rank ?? -1) - (a.rank ?? -1) || (a.due ?? "~").localeCompare(b.due ?? "~");
+    for (const state of order) for (const d of r.decisions.filter((x) => x.render === state && x.source !== "root" || (x.id === "foundation" && x.render === state)).sort(byDue)) console.log(`  ${state.padEnd(8)} ${d.id.padEnd(30)} ${d.boundary.padEnd(11)} ${d.layer.padEnd(10)} ${d.question}${d.held_by ? ` [held by ${d.held_by}]` : ""}${d.render === "done" ? ` [${d.firmness}${d.provenance?.approved_by ? `, approved by ${d.provenance.approved_by} in ${d.provenance.phase}` : ""}]` : ""}${d.awaiting ? " [agent's wording, awaiting approval]" : ""}${d.due && d.render !== "done" ? ` [due ${d.due}, ${d.due_in_hours}h]` : ""}${d.outcomes?.due?.length ? ` [outcomes due: ${d.outcomes.due.join(", ")}]` : ""}${d.why?.length ? `\n           why now: ${d.why.join("; ")}` : ""}`);
+    if (process.argv.includes("--md")) {
+      const m = matrix(r);
+      console.log(`\n| layer | ${PHASES.join(" | ")} |\n| --- | ${PHASES.map(() => "---").join(" | ")} |`);
+      for (const row of m) console.log(`| ${row.layer} | ${PHASES.map((p) => row[p].join("<br>")).join(" | ")} |`);
+    }
+  }
+  const errs = rs.flatMap((r) => r.errors.map((e) => `${r.dir}: ${e}`));
+  for (const e of errs) console.error(`FAIL  ${e}`);
+  process.exit(errs.length ? 1 : 0);
+}

package/schema/department-catalog.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "department-catalog.schema.json",
+  "title": "Department catalog",
+  "description": "The departments a venture can import (EE-047): APQC Process Classification Framework categories, each tagged with its place in Porter's value chain and given need-now priors (EE-028). The framework's copy is operations/departments.json.",
+  "type": "object",
+  "required": ["version", "departments"],
+  "properties": {
+    "version": { "type": "string" },
+    "note": { "type": "string" },
+    "departments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "label", "apqc", "value_chain", "porter", "governance", "operations", "base", "why"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+          "label": { "type": "string" },
+          "apqc": {
+            "type": "object",
+            "required": ["id", "name"],
+            "properties": { "id": { "type": "string", "pattern": "^\\d+\\.0$" }, "name": { "type": "string" } },
+            "additionalProperties": false
+          },
+          "value_chain": { "enum": ["primary", "support"] },
+          "porter": { "type": "string", "description": "The value-chain activity it falls under (Porter 1985)" },
+          "governance": { "type": "string", "description": "What its folder in the governance layer holds" },
+          "operations": { "type": "string", "description": "What its folder in the operations layer holds" },
+          "base": {
+            "type": "object",
+            "description": "Probability a venture needs it, per phase",
+            "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 }
+          },
+          "when": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["if"],
+              "properties": {
+                "if": { "type": "string" },
+                "phase": { "type": "string" },
+                "at_least": { "type": "number", "minimum": 0, "maximum": 1 },
+                "at_most": { "type": "number", "minimum": 0, "maximum": 1 }
+              },
+              "additionalProperties": false
+            }
+          },
+          "why": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schema/department.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "department.schema.json",
+  "title": "Department",
+  "description": "The tag in each of a venture's department folders (EE-047): which department the folder is and where it sits in the value chain. It lives in the folder at <layer>/departments/<id>/department.json, or under an optional grouping folder, <layer>/departments/primary/<id>/ or support/<id>/, which is for looking at only; the tag, not the folder, says what the department is. Its values must match operations/departments.json.",
+  "type": "object",
+  "required": ["department", "value_chain", "apqc"],
+  "properties": {
+    "department": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+    "value_chain": { "enum": ["primary", "support"] },
+    "apqc": { "type": "string", "pattern": "^\\d+\\.0$", "description": "The APQC category id" },
+    "owner": { "type": "string", "description": "The role that heads it, from the roles register" }
+  },
+  "additionalProperties": false
+}

package/schema/departments.mjs

@@ -0,0 +1,32 @@
+// Departments (EE-047): the catalog, and the department folders a venture holds. A department
+// folder is any folder under <layer>/departments/ that holds a department.json; it may sit under
+// an optional grouping folder named for its place in the value chain (primary/ or support/).
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const root = new URL("..", import.meta.url).pathname;
+export const LAYERS = ["governance", "operations"];
+export const GROUPS = ["primary", "support"];
+
+export const catalog = () => JSON.parse(readFileSync(join(root, "operations/departments.json"), "utf8")).departments;
+
+/** Every department folder in a venture: { layer, path (relative to the venture), folder, group, tag }. */
+export function foldersOf(dir) {
+  const out = [];
+  for (const layer of LAYERS) {
+    const base = join(dir, layer, "departments");
+    if (!existsSync(base)) continue;
+    for (const e of readdirSync(base, { withFileTypes: true }).filter((e) => e.isDirectory())) {
+      const inside = GROUPS.includes(e.name) && !existsSync(join(base, e.name, "department.json"))
+        ? readdirSync(join(base, e.name), { withFileTypes: true }).filter((x) => x.isDirectory()).map((x) => [e.name, x.name])
+        : [[null, e.name]];
+      for (const [group, folder] of inside) {
+        const rel = join(layer, "departments", ...(group ? [group] : []), folder);
+        const file = join(dir, rel, "department.json");
+        out.push({ layer, path: rel, folder, group, tag: existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : null });
+      }
+    }
+  }
+  return out;
+}

package/schema/docket-eval.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// Evidence for the docket (EE-075): scores its next step against venture states where the right next
+// step is argued from a cited source (schema/examples/docket-scenarios.json), and builds the same
+// question for an independent judge, so the docket, the judge and the source can be compared.
+//
+//   node schema/docket-eval.mjs [--json]                    the docket against the scenarios
+//   node schema/docket-eval.mjs request | <judge> > a.json  the judge's request (Jev: platform/integrations/jev.mjs)
+//   node schema/docket-eval.mjs --answers a.json [--json]   the docket and the judge against the scenarios
+//
+// Per state: does the docket's next decision match the expected one, and its leading function? For the
+// judge, each open decision the founder can act on is one question ("is this the best next step?") and
+// the judge's pick is the one it is most sure of. A day scenario is scored at every step, settling the
+// expected decision before the next, so a miss early does not cascade.
+
+import { readFileSync } from "node:fs";
+import { rankDocket } from "./docket.mjs";
+
+const FILE = new URL("examples/docket-scenarios.json", import.meta.url).pathname;
+const NOW = Date.parse("2026-10-29T12:00:00Z");
+const TITLE = { foundation: "Foundation", validation: "Validation", product: "Product", marketing: "Marketing and sales", finance: "Finance", people: "People", legal: "Legal and governance", operations: "Operations" };
+
+/** The decisions as decisions.mjs would resolve them, after the given ones are settled. */
+function resolve(decisions, settled) {
+  const open = decisions.filter((d) => !settled.has(d.id));
+  return open.map((d) => {
+    const held = d.held_by && !settled.has(d.held_by);
+    const render = d.state === "waiting" ? (held ? "waiting" : "now") : d.state;
+    return { id: d.id, question: d.question, source: "file", render, ...(held ? { held_by: d.held_by } : {}),
+      ...(d.due_in_hours != null ? { due: new Date(NOW + d.due_in_hours * 36e5).toISOString() } : {}),
+      ...(d.unlocks?.length ? { unlocks: d.unlocks } : {}), ...(d.foundation ? { part_of: "foundation" } : {}),
+      ...(d.drafted ? { awaiting: "approval" } : {}), ...(d.outcomes ? { outcomes: { total: d.outcomes, pending: d.outcomes } } : {}),
+      function: { id: d.function, title: TITLE[d.function] ?? d.function } };
+  });
+}
+
+/** Every moment to score: one per scenario, or one per step of a day. */
+export function states(file = FILE) {
+  const { scenarios } = JSON.parse(readFileSync(file, "utf8"));
+  return scenarios.flatMap((s) => {
+    const steps = s.steps ?? [s.expected];
+    const settled = new Set();
+    return steps.map((exp, i) => {
+      const st = { id: steps.length > 1 ? `${s.id}#${i + 1}` : s.id, scenario: s, phase: s.phase, decisions: resolve(s.decisions, settled), expected: exp };
+      settled.add(exp.decision);
+      return st;
+    });
+  });
+}
+
+const actionable = (st) => st.decisions.filter((d) => ["now", "overdue", "stale"].includes(d.render));
+
+export function request(list = states()) {
+  const questions = {};
+  for (const st of list) for (const d of actionable(st))
+    questions[`next:${st.id}:${d.id}`] = { type: "noul", instructions: `In the venture state \`states.${st.id}\`, is the open decision \`${d.id}\` the single best next step for the founder to settle now, before every other open decision listed there?`,
+      criteria: { true: "Yes: this one should come first", false: "No: another listed decision should come first" } };
+  const state = Object.fromEntries(list.map((st) => [st.id, { phase: st.phase, situation: st.scenario.situation,
+    open: Object.fromEntries(st.decisions.map((d) => [d.id, `${d.question} [${d.function.title}; ${d.render}${d.held_by ? `, waits on ${d.held_by}` : ""}${d.due ? `; due ${d.due}` : ""}]`])) }]));
+  return { state: { guidelines: "Each state is a venture at one moment: its phase, its situation, and its open decisions with their function and whether each can be settled now or waits on another. Judge as an experienced startup advisor would.", states: state }, model: "jev-latest", questions };
+}
+
+export function score(answers = null, list = states()) {
+  const rows = list.map((st) => {
+    const k = rankDocket(st.decisions, st.phase, NOW);
+    const judge = answers ? actionable(st).map((d) => {
+      const a = answers[`next:${st.id}:${d.id}`];
+      return { id: d.id, fn: d.function.id, p: typeof a?.noul === "number" ? a.noul : a?.noul === true ? 1 : 0 };
+    }).sort((a, b) => b.p - a.p)[0] : null;
+    return { state: st.id, expected: st.expected, docket: { decision: k.next?.decision, function: k.next?.function_id, dominant: k.next?.dominant, leading: k.functions.map((f) => `${f.id} ${f.attention}`) },
+      ...(judge ? { judge: { decision: judge.id, function: judge.fn, p: Math.round(judge.p * 100) / 100 } } : {}),
+      docket_right: k.next?.decision === st.expected.decision, docket_function_right: k.next?.function_id === st.expected.function,
+      ...(judge ? { judge_right: judge.id === st.expected.decision, agree: judge.id === k.next?.decision } : {}) };
+  });
+  const rate = (k) => Math.round((rows.filter((r) => r[k]).length / rows.length) * 100) / 100;
+  return { states: rows.length, docket_next: rate("docket_right"), docket_function: rate("docket_function_right"),
+    ...(answers ? { judge_next: rate("judge_right"), docket_judge_agree: rate("agree") } : {}), rows };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  if (process.argv[2] === "request") { console.log(JSON.stringify(request())); process.exit(0); }
+  const i = process.argv.indexOf("--answers");
+  const answers = i >= 0 ? JSON.parse(readFileSync(process.argv[i + 1], "utf8")).answers : null;
+  const r = score(answers);
+  if (process.argv.includes("--json")) console.log(JSON.stringify(r, null, 2));
+  else {
+    for (const x of r.rows) console.log(`${x.docket_right ? "right" : "MISS "}  ${x.state.padEnd(34)} expected ${x.expected.decision.padEnd(22)} docket ${String(x.docket.decision).padEnd(22)}${x.judge ? ` judge ${x.judge.decision} (${x.judge.p})${x.judge_right ? "" : " MISS"}` : ""}`);
+    console.log(`\n${r.states} states: the docket picked the expected next step in ${Math.round(r.docket_next * 100)}% and the expected function in ${Math.round(r.docket_function * 100)}%${answers ? `; the judge picked it in ${Math.round(r.judge_next * 100)}%, and agreed with the docket in ${Math.round(r.docket_judge_agree * 100)}%` : ""}`);
+  }
+}