naive-framework 0.1.0 → 0.2.0

package/interface/adapters.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+// Adapters (Z-4). Next.js adapters let a platform customize build and deploy, and a verified adapter
+// passes the Next.js test suite. Naive's adapters run the framework on a platform or in an agent
+// harness. Mentura is the first, as Vercel is for Next.js (platform/adapter.json). Claude Code, Codex and
+// Cursor adapt the framework through the venture's AGENTS.md and skills (interface/adapters/*.json):
+// adapt() writes the entry files a harness reads and copies the skills of the packages open now. An
+// adapter is verified when it passes the framework's tests: verify() runs them.
+//
+//   node interface/adapters.mjs [--json]                        the adapters
+//   node interface/adapters.mjs adapt <adapter> <venture dir>   write a harness's files into a venture
+//   node interface/adapters.mjs verify [<adapter>] [--json]     run the framework's tests an adapter must pass
+//
+// adapt() records what it wrote in <venture>/.naive/adapters.json and never overwrites a file it did not
+// write, or one a person changed since: it keeps theirs and says so. An upgrade refreshes the adapters
+// a venture has (schema/upgrades.mjs), so the skill copies follow the installed packages.
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+const repo = new URL("..", import.meta.url).pathname;
+export const STATE = ".naive/adapters.json";
+const load = (p) => JSON.parse(readFileSync(p, "utf8"));
+const sha = (s) => createHash("sha256").update(s).digest("hex");
+
+/** Every adapter: the harness adapters in interface/adapters/, and the platform's if this copy has one. */
+export function adapters() {
+  const d = join(repo, "interface/adapters");
+  const out = existsSync(d) ? readdirSync(d).filter((f) => f.endsWith(".json")).sort().map((f) => ({ ...load(join(d, f)), path: `interface/adapters/${f}` })) : [];
+  if (existsSync(join(repo, "platform/adapter.json"))) out.unshift({ ...load(join(repo, "platform/adapter.json")), path: "platform/adapter.json" });
+  return out;
+}
+const byName = (name) => { const a = adapters().find((x) => x.name === name); if (!a) throw new Error(`no adapter ${name}: ${adapters().map((x) => x.name).join(", ")}`); return a; };
+
+/** The skills of the packages open now in a venture: [{ id, path, package }]. */
+export async function skillsFor(dir) {
+  const { packages } = await import("../schema/packages.mjs");
+  const p = packages(dir);
+  return [...p.core, ...p.handoff].filter((x) => x.in === "now").flatMap((x) => {
+    const f = join(repo, "packages", x.id, "package.json");
+    const s = existsSync(f) ? load(f).skill : null;
+    return s && existsSync(join(repo, s.path)) ? [{ id: s.id, path: s.path, package: x.id }] : [];
+  });
+}
+
+const readState = (dir) => (existsSync(join(dir, STATE)) ? load(join(dir, STATE)) : { adapters: {} });
+
+/**
+ * Writes a harness adapter's files into a venture: its entry files, and a copy of each open package's
+ * skill in its skills folder. Returns what it wrote, what was already current, and what it kept.
+ */
+export async function adapt(dir, name) {
+  if (!existsSync(join(dir, "venture.json"))) throw new Error(`${dir} is not a venture`);
+  const a = byName(name);
+  if (a.kind !== "harness") throw new Error(`${name} is a ${a.kind} adapter: it runs the framework itself and writes nothing into a venture`);
+  const state = readState(dir);
+  const mine = state.adapters[name]?.files ?? {};
+  const want = [...a.files.map((f) => ({ path: f.path, text: f.text }))];
+  if (a.skills) for (const s of await skillsFor(dir)) want.push({ path: `${a.skills}/${s.id}/SKILL.md`, text: readFileSync(join(repo, s.path), "utf8"), skill: s.id, package: s.package });
+  const written = [], current = [], kept = [], files = {};
+  for (const w of want) {
+    const f = join(dir, w.path);
+    const now = existsSync(f) ? readFileSync(f, "utf8") : null;
+    if (now === w.text) { current.push(w.path); files[w.path] = sha(w.text); continue; }
+    // Never overwrite a file a person wrote, or one they changed after the adapter wrote it.
+    if (now !== null && mine[w.path] !== sha(now)) { kept.push({ path: w.path, why: mine[w.path] ? "changed since the adapter wrote it" : "it was there before the adapter" }); if (mine[w.path]) files[w.path] = mine[w.path]; continue; }
+    mkdirSync(dirname(f), { recursive: true });
+    writeFileSync(f, w.text);
+    written.push(w.path);
+    files[w.path] = sha(w.text);
+  }
+  // A skill copy for a package that is no longer open goes, if the adapter wrote it and nobody changed it.
+  const removed = [];
+  for (const [p, h] of Object.entries(mine)) {
+    if (want.some((w) => w.path === p) || !existsSync(join(dir, p))) continue;
+    if (sha(readFileSync(join(dir, p), "utf8")) === h) { rmSync(join(dir, p)); removed.push(p); } else kept.push({ path: p, why: "no longer needed, but changed by a person, so kept" });
+  }
+  state.adapters[name] = { at: new Date().toISOString(), files };
+  mkdirSync(join(dir, ".naive"), { recursive: true });
+  writeFileSync(join(dir, STATE), JSON.stringify(state, null, 2) + "\n");
+  return { adapter: name, written, current, kept, removed, skills: want.filter((w) => w.skill).map((w) => w.skill) };
+}
+
+/** Re-adapts every adapter the venture has, after an upgrade. */
+export async function refresh(dir) {
+  const names = Object.keys(readState(dir).adapters);
+  const out = [];
+  for (const n of names) { try { out.push(await adapt(dir, n)); } catch (e) { out.push({ adapter: n, error: e.message }); } }
+  return out;
+}
+
+// The framework's tests for a harness adapter, run on a new venture in a temporary folder.
+async function harnessSuite(a) {
+  const results = [];
+  const t = (test, passed, detail = "") => results.push({ test, passed: !!passed, detail });
+  const ws = mkdtempSync(join(tmpdir(), `naive-adapter-${a.name}-`));
+  try {
+    const dir = join(ws, "adapted");
+    const init = spawnSync("node", [join(repo, "schema/init-venture.mjs"), dir, "adapted"], { encoding: "utf8" });
+    const up = spawnSync("node", [join(repo, "schema/upgrade-venture.mjs"), dir], { encoding: "utf8" });
+    t("a new venture is created and upgraded to the installed framework", init.status === 0 && up.status === 0, init.stderr + up.stderr);
+    const first = await adapt(dir, a.name);
+    t("every entry file is written with the adapter's text", a.files.every((f) => existsSync(join(dir, f.path)) && readFileSync(join(dir, f.path), "utf8") === f.text), JSON.stringify(first.written));
+    t("the harness reaches the venture's AGENTS.md (it reads it, or an entry file imports or names it)", a.reads.includes("AGENTS.md") || a.files.some((f) => /(^|\s)@AGENTS\.md\b|AGENTS\.md/.test(f.text)));
+    t("no entry file is private or outside the venture", a.files.every((f) => !f.path.startsWith("_private/") && !f.path.includes("..") && !f.path.startsWith("/")));
+    const { call } = await import("./router.mjs");
+    const lay = await call({ venture: "adapted", workspace: ws, route: "foundation/problem", action: "layout" });
+    t("the layout an agent gets starts with the venture's AGENTS.md and its instructions", lay.ok && lay.result.chain[0]?.path === "AGENTS.md" && lay.result.instructions.private === "_private/", lay.error ?? "");
+    if (a.skills) {
+      const want = await skillsFor(dir);
+      t("the venture has packages open now with skills to copy", want.length > 0, "no open package has a skill");
+      t("each open package's skill is copied byte for byte where the harness loads skills", want.every((s) => existsSync(join(dir, a.skills, s.id, "SKILL.md")) && readFileSync(join(dir, a.skills, s.id, "SKILL.md"), "utf8") === readFileSync(join(repo, s.path), "utf8")), JSON.stringify(want.map((s) => s.id)));
+      rmSync(join(dir, a.skills, want[0].id, "SKILL.md"));
+      const back = await refresh(dir);
+      t("a refresh (as after an upgrade) puts a missing skill copy back", back[0]?.written?.includes(`${a.skills}/${want[0].id}/SKILL.md`), JSON.stringify(back));
+    }
+    const again = await adapt(dir, a.name);
+    t("adapting again changes nothing", again.written.length === 0 && again.kept.length === 0, JSON.stringify(again));
+    if (a.files.length) {
+      const f = join(dir, a.files[0].path);
+      writeFileSync(f, readFileSync(f, "utf8") + "\nThe founder's own line.\n");
+      const edited = readFileSync(f, "utf8");
+      const kept = await adapt(dir, a.name);
+      t("a file the founder changed is kept, never overwritten", kept.kept.some((k) => k.path === a.files[0].path) && readFileSync(f, "utf8") === edited, JSON.stringify(kept));
+      const other = join(ws, "own");
+      spawnSync("node", [join(repo, "schema/init-venture.mjs"), other, "own"], { encoding: "utf8" });
+      mkdirSync(dirname(join(other, a.files[0].path)), { recursive: true });
+      writeFileSync(join(other, a.files[0].path), "the founder's own file\n");
+      const theirs = await adapt(other, a.name);
+      t("a file that was there before the adapter is kept", theirs.kept.some((k) => k.path === a.files[0].path) && readFileSync(join(other, a.files[0].path), "utf8") === "the founder's own file\n", JSON.stringify(theirs));
+    }
+  } catch (e) { t("the suite ran to the end", false, String(e.stack ?? e)); }
+  finally { rmSync(ws, { recursive: true, force: true }); }
+  return results;
+}
+
+// A platform adapter runs the framework itself; it is verified by the test programs it names.
+function platformSuite(a) {
+  if (!a.verify?.length) return [{ test: "names the framework tests it must pass", passed: false, detail: "verify is empty" }];
+  return a.verify.map((p) => {
+    if (!existsSync(join(repo, p))) return { test: p, passed: false, detail: "not found" };
+    const r = spawnSync("node", [join(repo, p)], { cwd: repo, encoding: "utf8", timeout: 600000 });
+    const tail = (r.stdout + r.stderr).trim().split("\n").slice(-4).join(" / ");
+    return { test: p, passed: r.status === 0, detail: tail };
+  });
+}
+
+/** Runs the framework's tests for one adapter: { adapter, kind, verified, results }. */
+export async function verify(name) {
+  const a = byName(name);
+  const results = a.kind === "harness" ? await harnessSuite(a) : platformSuite(a);
+  return { adapter: a.name, kind: a.kind, verified: results.every((r) => r.passed), results };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const [cmd, ...rest] = process.argv.slice(2).filter((x) => x !== "--json");
+  const json = process.argv.includes("--json");
+  try {
+    if (!cmd) {
+      const list = adapters().map((a) => ({ name: a.name, title: a.title, kind: a.kind, path: a.path, reads: a.reads }));
+      console.log(json ? JSON.stringify(list, null, 2) : list.map((a) => `${a.name.padEnd(12)} ${a.kind.padEnd(9)} ${a.path}  reads ${a.reads.join(", ")}`).join("\n"));
+    } else if (cmd === "adapt") {
+      const [name, dir] = rest;
+      if (!name || !dir) throw new Error("usage: node interface/adapters.mjs adapt <adapter> <venture dir>");
+      const r = await adapt(dir, name);
+      console.log(json ? JSON.stringify(r, null, 2) : [`adapted for ${r.adapter}: ${r.written.length} written, ${r.current.length} already current, ${r.kept.length} kept${r.skills.length ? `; skills: ${r.skills.join(", ")}` : ""}`,
+        ...r.written.map((p) => `wrote     ${p}`), ...r.kept.map((k) => `kept      ${k.path} (${k.why})`), ...r.removed.map((p) => `removed   ${p}`)].join("\n"));
+    } else if (cmd === "verify") {
+      const names = rest.length ? rest : adapters().map((a) => a.name);
+      const rs = [];
+      for (const n of names) rs.push(await verify(n));
+      if (json) console.log(JSON.stringify(rs, null, 2));
+      else for (const r of rs) {
+        console.log(`${r.verified ? "verified" : "NOT verified"}  ${r.adapter} (${r.kind})`);
+        for (const x of r.results) console.log(`  ${x.passed ? "pass" : "FAIL"}  ${x.test}${x.passed ? "" : `  ${x.detail}`}`);
+      }
+      process.exit(rs.every((r) => r.verified) ? 0 : 1);
+    } else throw new Error("usage: node interface/adapters.mjs [adapt <adapter> <venture dir> | verify [<adapter>]] [--json]");
+  } catch (e) { console.error(e.message); process.exit(1); }
+}

package/interface/api/server.mjs

@@ -14,7 +14,8 @@
 //   GET  /ventures/<venture>/<route>/layout         the layout an agent gets before acting
 //   PUT  /ventures/<venture>/<route>                write a record (JSON body); provenance from the
 //        headers x-mentura-derived-from (comma-separated), x-mentura-decision, x-mentura-model;
-//        the role acting from x-mentura-actor (checked against the team plan's routes)
+//        the role acting from x-mentura-actor (checked against the team plan's routes); a confidence
+//        score computed before the write from x-mentura-confidence
 //   POST /ventures/<venture>/<route>/check          run its checks
 //   POST /ventures/<venture>/<route>/run            run a command route (optional JSON body {value})
 //
@@ -47,7 +48,8 @@ export async function route(method, url, body, headers = {}) {
   if (!action || (verb && VERBS[verb] !== method)) return [405, { ok: false, error: `${method} is not allowed on ${path}` }];
   const h = (k) => headers[k] || undefined;
   const r = await call({ venture, route: rt, action, input: body, actor: "agent", actor_id: h("x-mentura-actor"), via: "api",
-    provenance: { derived_from: h("x-mentura-derived-from")?.split(",").map((x) => x.trim()).filter(Boolean), decision: h("x-mentura-decision"),
+    // Gate group hook (X-4): x-mentura-confidence carries a score computed before the write, for the gate's confidence rules.
+    provenance: { derived_from: h("x-mentura-derived-from")?.split(",").map((x) => x.trim()).filter(Boolean), decision: h("x-mentura-decision"), confidence: h("x-mentura-confidence"),
       agent: Object.fromEntries(Object.entries({ model: h("x-mentura-model"), harness: h("user-agent") }).filter(([, v]) => v)) } });
   return [status(r), r];
 }

package/interface/boundaries.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+// Error boundaries (Next.js translation P-15, E-5, E-6, E-8). Expected errors stay answers, never throws.
+//
+//   global-error  a broken venture.json, or a broken framework file (the data model, a layer or package
+//                 manifest), answers with what is wrong and the recovery steps, instead of a stack trace.
+//                 One broken venture never stops the router from finding the others.
+//   boundary      a failing check in one package is contained there: the other packages proceed, and
+//                 only a venture-level failure (venture.json, the folder structure) reaches the venture.
+//   per record    one bad record (a file that does not parse or does not match its schema) does not fail
+//                 its package's read or check: the others come back, and the bad one is named with its fix.
+//
+//   node interface/boundaries.mjs check <venture dir> [--package <name>] [--json]   the boundaries, exit 1 on a failure
+//   node interface/boundaries.mjs recover <venture dir> --confirm recover           rebuild a broken venture.json
+//
+// The router calls these through interface/writes.mjs; `mentura venture check` and `mentura <package> check`
+// run them. Never calls a model.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+const repo = new URL("..", import.meta.url).pathname;
+const load = (f) => JSON.parse(readFileSync(f, "utf8"));
+
+// Where a JSON parse failed: line and column from the position in the message, when it gives one.
+function where(text, message) {
+  const m = message.match(/position (\d+)/);
+  if (!m && /end of JSON input/.test(message)) return ` (at the end of the file, line ${text.split("\n").length})`;
+  if (!m || /line \d+/.test(message)) return "";
+  const before = text.slice(0, Number(m[1]));
+  const line = before.split("\n").length, col = before.length - before.lastIndexOf("\n");
+  return ` (line ${line}, column ${col})`;
+}
+
+/** Why a JSON file is broken, or null. */
+export function jsonProblem(file) {
+  if (!existsSync(file)) return "is missing";
+  const text = readFileSync(file, "utf8");
+  try { JSON.parse(text); return null; } catch (e) { return `does not parse: ${String(e.message).split("\n")[0]}${where(text, String(e.message))}`; }
+}
+
+const VENTURE_SCHEMA = () => load(join(repo, "schema/venture.schema.json"));
+
+/** A minimal venture.json for a folder, from the schema's required fields: what recover writes. */
+export function minimalVenture(dir) {
+  const id = basename(dir).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "venture";
+  return { id, name: id, parent: null, phase: "discovery", owner: "self", status: "active", profile: "profile.md",
+    layers: Object.fromEntries(["purpose", "knowledge", "operations", "evidence", "governance", "interface"].map((l) => [l, existsSync(join(dir, l)) ? { location: `${l}/` } : false])) };
+}
+
+/**
+ * The venture's global error (E-8, P-15): null when venture.json is sound, else what is wrong and
+ * how to recover. Checks what the router needs before anything else runs: it parses, its required
+ * fields are there, its id and phase are valid. The full schema check stays in schema/validate.py.
+ */
+export function ventureHealth(dir) {
+  const file = join(dir, "venture.json");
+  let problem = jsonProblem(file);
+  if (!problem) {
+    const v = load(file), s = VENTURE_SCHEMA();
+    const missing = v && typeof v === "object" ? s.required.filter((k) => !(k in v)) : [];
+    if (!v || typeof v !== "object" || Array.isArray(v)) problem = "is not a JSON object";
+    else if (missing.length) problem = `is missing ${missing.join(", ")}`;
+    else if (!new RegExp(s.properties.id.pattern).test(String(v.id))) problem = `has id ${JSON.stringify(v.id)}, which is not lowercase letters, digits and hyphens`;
+    else if (!s.properties.phase.enum.includes(v.phase)) problem = `has phase ${JSON.stringify(v.phase)}, which is not one of ${s.properties.phase.enum.join(", ")}`;
+    else if (typeof v.layers !== "object" || v.layers === null) problem = "has layers that are not an object";
+  }
+  if (!problem) return null;
+  const git = spawnSync("git", ["-C", dir, "ls-files", "--error-unmatch", "venture.json"], { encoding: "utf8" }).status === 0;
+  return {
+    scope: "venture", file, problem: `venture.json ${problem}`,
+    recovery: [
+      ...(git ? [`Restore the last committed version: git -C ${dir} checkout -- venture.json`] : []),
+      `Fix it by hand: it must be a JSON object with ${VENTURE_SCHEMA().required.join(", ")}`,
+      `Or rebuild a minimal one, keeping the broken file in _private/: node interface/boundaries.mjs recover ${dir} --confirm recover`,
+      `Then check it: python3 schema/validate.py --schema venture.schema.json --file ${file}`,
+    ],
+    template: minimalVenture(dir),
+  };
+}
+
+// The framework files every route depends on. A broken one stops every route, so it is checked first.
+function frameworkFiles() {
+  const fixed = ["schema/data-model.json", "schema/need-now.json", "schema/venture.schema.json", "packages/catalog.json", "purpose/frameworks/product-anatomy/phases.json", "purpose/strategic-foundation.json", "operations/departments.json"];
+  let layers = [];
+  try { layers = load(join(repo, "schema/data-model.json")).layers.map((l) => `${l}/layer.json`); } catch {}
+  const pkgs = existsSync(join(repo, "packages")) ? readdirSync(join(repo, "packages")).map((n) => `packages/${n}/package.json`).filter((f) => existsSync(join(repo, f))) : [];
+  return [...fixed, ...layers, "schema/layer.json", ...pkgs];
+}
+
+/** The framework's global error (E-8): null when the data model and manifests parse, else the file, the problem and how to recover. */
+export function frameworkHealth() {
+  for (const f of frameworkFiles()) {
+    const problem = jsonProblem(join(repo, f));
+    if (!problem) continue;
+    return { scope: "framework", file: f, problem: `${f} ${problem}`, recovery: [
+      `Restore it: git -C ${repo} checkout -- ${f}`,
+      "Then check the data model and the manifests: node schema/check-data-model.mjs",
+      "No venture record was touched: every route stops until the framework file parses again.",
+    ] };
+  }
+  return null;
+}
+
+/** The answer a global error gives: an expected error with its recovery steps, never a throw. */
+export function globalError(h, venture) {
+  const head = h.scope === "venture" ? `${venture ?? basename(dirname(h.file))}: ${h.problem}` : `the framework is broken: ${h.problem}`;
+  return { ok: false, outcome: "error", error: [head, "Recovery:", ...h.recovery.map((s, i) => `  ${i + 1}. ${s}`)].join("\n"), global_error: h };
+}
+
+/** Per-record containment (E-6): parses each item on its own; a bad one becomes an error beside the good ones. */
+export function contain(items, parse, idOf = (x) => x.path) {
+  const values = [], errors = {};
+  for (const x of items) {
+    try { values.push([x, parse(x)]); } catch (e) { errors[idOf(x.path)] = { file: x.path, error: `${x.path} does not parse: ${String(e.message ?? e).split("\n")[0]}` }; }
+  }
+  return { values, errors };
+}
+
+function validateFile(file, schema) {
+  const p = spawnSync("python3", [join(repo, "schema/validate.py"), "--schema", schema.replace(/^schema\//, ""), "--file", file], { encoding: "utf8" });
+  return p.status === 0 ? null : (p.stdout + p.stderr).trim();
+}
+
+/**
+ * The boundaries of a venture (E-5): the venture level first (venture.json and its folder structure),
+ * then each package the venture uses, each contained. Inside a package each record is checked on its
+ * own (E-6), then the package's checks run. options.only limits it to some packages.
+ */
+export async function boundaries(dir, { only = null } = {}) {
+  const { structure, checkManifest, manifest } = await import("../schema/structure.mjs");
+  const { routes, glob } = await import("./router.mjs");
+  const { routable } = await import("../schema/structure.mjs");
+  const h = ventureHealth(dir);
+  if (h) return { ok: false, reached: "venture", venture: { ok: false, error: h.problem, recovery: h.recovery }, packages: [], proceeds: [] };
+  const s = structure(dir);
+  const verrors = [...s.errors, ...checkManifest(dir)];
+  const venture = { ok: !verrors.length, ...(verrors.length ? { errors: verrors, fix: "node schema/structure.mjs " + dir } : {}), warnings: s.warnings };
+  const m = await manifest(dir);
+  // Asked for by name, a package is checked whether or not the venture lists it.
+  const names = only ? only.filter((n) => existsSync(join(repo, "packages", n, "package.json"))) : m.packages.list.filter((p) => p.known).map((p) => p.name);
+  const rs = routes().filter((r) => r.kind === "record" && r.collection !== "list");
+  const out = [];
+  for (const name of names) {
+    // A package's failure stays in its result: an exception here is caught and reported as that package's.
+    try {
+      const pkg = load(join(repo, "packages", name, "package.json"));
+      const types = [...new Set([...(pkg.required ?? []), ...(pkg.optional ?? []), ...(pkg.records ?? [])])];
+      const records = [], checks = new Set((pkg.checks ?? []).filter((c) => /^schema\/check-[a-z-]+\.mjs$/.test(c) && c !== "schema/check-data-model.mjs" && existsSync(join(repo, c))));
+      for (const t of types) {
+        const r = rs.find((x) => x.record === t);
+        if (!r) continue;
+        for (const c of r.checks ?? []) checks.add(c);
+        const pats = r.files;
+        const hits = files(dir).filter((f) => pats.some((g) => glob(g).test(f) && routable(f, g)));
+        for (const f of hits) {
+          const problem = f.endsWith(".json") ? jsonProblem(join(dir, f)) ?? (r.schema ? validateFile(join(dir, f), r.schema) : null) : null;
+          records.push({ record: t, route: r.collection === "item" ? r.route.replace("[id]", starOf(f, pats) ?? basename(f)) : r.route, file: f, ok: !problem,
+            ...(problem ? { error: problem, fix: { schema: r.schema, template: r.template, skills: pkg.skill?.path ? [pkg.skill.path] : [] } } : {}) });
+        }
+      }
+      const ran = [...checks].map((c) => { const p = spawnSync("node", [join(repo, c), dir], { encoding: "utf8" }); return { check: c, passed: p.status === 0, output: (p.stdout + p.stderr).trim().split("\n").slice(-5).join("\n") }; });
+      const ok = records.every((x) => x.ok) && ran.every((x) => x.passed);
+      out.push({ package: name, ok, records, checks: ran });
+    } catch (e) {
+      out.push({ package: name, ok: false, error: `uncaught in ${name}: ${String(e.message ?? e).split("\n")[0]}`, records: [], checks: [] });
+    }
+  }
+  const failed = out.filter((p) => !p.ok).map((p) => p.package);
+  return { ok: venture.ok && !failed.length, reached: !venture.ok ? "venture" : failed.length ? "package" : null, venture, packages: out, contained: failed, proceeds: out.filter((p) => p.ok).map((p) => p.package) };
+}
+
+// The id a collection pattern's one star matches in a file (customers/[id].json, accounts/[id]/account.json).
+export function starOf(file, patterns) {
+  for (const g of patterns) {
+    if (!g.includes("*") || g.includes("**")) continue;
+    const m = file.match(new RegExp("^" + g.split("*").map((x) => x.replace(/[.+^${}()|[\]\\]/g, "\\$&")).join("([^/]*)") + "$"));
+    if (m) return m[1];
+  }
+  return null;
+}
+
+// A venture's files, skipping dot folders, nested ventures and the root's private folders (as the router does).
+function files(d, base = d) {
+  return existsSync(d) ? readdirSync(d, { withFileTypes: true }).flatMap((e) => e.name.startsWith(".") ? [] : e.isDirectory()
+    ? (existsSync(join(d, e.name, "venture.json")) || (d === base && e.name.startsWith("_")) ? [] : files(join(d, e.name), base)) : [join(d, e.name).slice(base.length + 1)]) : [];
+}
+
+/** Rebuilds a broken venture.json (E-8): the broken file moves to _private/, and a minimal one takes its place. */
+export function recover(dir) {
+  const h = ventureHealth(dir);
+  if (!h) return { ok: true, result: "venture.json is sound: nothing to recover" };
+  const kept = join("_private", `venture.json.broken-${new Date().toISOString().replace(/[:.]/g, "-")}`);
+  if (existsSync(join(dir, "venture.json"))) { mkdirSync(join(dir, "_private"), { recursive: true }); renameSync(join(dir, "venture.json"), join(dir, kept)); }
+  writeFileSync(join(dir, "venture.json"), JSON.stringify(minimalVenture(dir), null, 2) + "\n");
+  return { ok: true, result: { written: "venture.json", kept: existsSync(join(dir, kept)) ? kept : null, note: "a minimal venture.json: copy back what you need from the kept file, then check it" } };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const [cmd, dir] = process.argv.slice(2);
+  const opt = (n) => { const i = process.argv.indexOf(`--${n}`); return i >= 0 ? process.argv[i + 1] : undefined; };
+  if (!["check", "recover"].includes(cmd) || !dir || !existsSync(dir)) { console.error("usage: node interface/boundaries.mjs check <venture dir> [--package <name>] [--json] | recover <venture dir> --confirm recover"); process.exit(2); }
+  if (cmd === "recover") {
+    if (opt("confirm") !== "recover") { console.error("recover rewrites venture.json: pass --confirm recover"); process.exit(1); }
+    const r = recover(dir);
+    console.log(typeof r.result === "string" ? r.result : JSON.stringify(r.result, null, 2));
+    process.exit(0);
+  }
+  const fw = frameworkHealth();
+  if (fw) { console.error(globalError(fw).error); process.exit(1); }
+  const b = await boundaries(dir, { only: opt("package") ? [opt("package")] : null });
+  if (process.argv.includes("--json")) console.log(JSON.stringify(b, null, 2));
+  else {
+    console.log(`venture: ${b.venture.ok ? "ok" : `failed: ${(b.venture.errors ?? [b.venture.error]).join("; ")}`}`);
+    for (const p of b.packages) console.log(`${p.package.padEnd(14)} ${p.ok ? "ok" : `contained: ${[p.error, ...p.records.filter((x) => !x.ok).map((x) => `${x.file} ${x.error.split("\n")[0]}`), ...p.checks.filter((x) => !x.passed).map((x) => `${x.check} failed`)].filter(Boolean).join("; ")}`}`);
+  }
+  process.exit(b.ok ? 0 : 1);
+}