naive-framework 0.2.0 → 0.3.0

package/schema/decisions.mjs

@@ -32,6 +32,7 @@ import { agentFromEnv, record as prov } from "../interface/provenance.mjs";
 import { glob as routeFileGlob, routes } from "../interface/router.mjs";
 // Caching hook (F-12): the decision list is computed once per router action (schema/caching.mjs).
 import { memo } from "./caching.mjs";
+import { layoutOf, logicalFiles, ventureFile } from "./venture-paths.mjs";
 
 const repo = new URL("..", import.meta.url).pathname;
 const load = (f) => JSON.parse(readFileSync(f, "utf8"));
@@ -47,7 +48,9 @@ export function recordOf(file) {
 
 // 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) => {
+  // A structured venture (EE-086): its decision files by their logical paths.
+  if (!sub && layoutOf(dir) === "structured") return logicalFiles(dir).filter((r) => r.endsWith(".decision.json") && r.split("/").at(-2) === "decisions" && !r.split("/").some((s) => s.startsWith(".") || s.startsWith("_")));
+  return readdirSync(ventureFile(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] : [];
@@ -74,7 +77,7 @@ function decisionsAt(dir, now = Date.parse(process.env.DECISIONS_NOW ?? "") || D
       status: settled ? "decided" : "open", decided_at: null, needed_in: venture.phase },
   ];
   for (const f of decisionFiles(dir)) {
-    const d = load(join(dir, f));
+    const d = load(ventureFile(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`);
@@ -107,7 +110,7 @@ function decisionsAt(dir, now = Date.parse(process.env.DECISIONS_NOW ?? "") || D
   }
   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")) : [];
+  const drafts = existsSync(join(ventureFile(dir, "_drafts"))) ? readdirSync(join(ventureFile(dir, "_drafts"))).filter((f) => f.endsWith(".draft")) : [];
   for (const d of drafts) {
     const path = d.replace(/\.draft$/, "").replace(/__/g, "/");
     const record = recordOf(path);
@@ -240,7 +243,7 @@ const routeGlob = (g) => new RegExp("^" + g.replace(/[.+^${}()|[\]\\]/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 files = decisionFiles(dir).map((f) => load(ventureFile(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;
@@ -254,7 +257,7 @@ const validate = (d) => {
   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);
+const fileOf = (dir, id) => decisionFiles(dir).find((f) => load(ventureFile(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. */
@@ -263,16 +266,16 @@ export function propose(dir, input, { agentId, via = "router", harness, model }
   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` };
+  if (existing && load(ventureFile(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 before = existing ? load(ventureFile(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");
+  mkdirSync(dirname(ventureFile(dir, file)), { recursive: true });
+  writeFileSync(ventureFile(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 } };
 }
@@ -282,7 +285,7 @@ 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));
+  const d = load(ventureFile(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 };
@@ -291,7 +294,7 @@ export function approve(dir, id, { by, answer, via = "cli", note } = {}) {
   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");
+  writeFileSync(ventureFile(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) } };
 }

package/schema/foundation.mjs

@@ -15,6 +15,7 @@
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { ventureFile } from "./venture-paths.mjs";
 
 const repo = new URL("..", import.meta.url).pathname;
 const load = (f) => JSON.parse(readFileSync(f, "utf8"));
@@ -30,15 +31,15 @@ export function filesOf(dir, type) {
   const gs = (r?.paths ?? []).filter((p) => p.startsWith("instance/**/")).map((p) => p.slice("instance/**/".length));
   const found = [];
   for (const g of gs) {
-    if (!g.includes("*")) { if (existsSync(join(dir, g))) found.push(g); continue; }
+    if (!g.includes("*")) { if (existsSync(ventureFile(dir, g))) found.push(g); continue; }
     const star = g.indexOf("*");
     const folder = g.slice(0, star), rest = g.slice(star + 1);
     if (rest.includes("*")) continue;
-    const d = join(dir, folder);
+    const d = ventureFile(dir, folder);
     if (existsSync(d)) for (const f of readdirSync(d)) if (f.endsWith(rest)) found.push(folder + f);
   }
   if (found.length) return found;
-  const drafted = gs.filter((g) => !g.includes("*") && existsSync(join(dir, `_drafts/${g.replace(/\//g, "__")}.draft`)));
+  const drafted = gs.filter((g) => !g.includes("*") && existsSync(ventureFile(dir, `_drafts/${g.replace(/\//g, "__")}.draft`)));
   return drafted.length ? drafted : gs.slice(0, 1);
 }
 
@@ -47,7 +48,7 @@ export function filesOf(dir, type) {
 export function confirmedIn(dir, file, id, seen = new Set()) {
   if (seen.has(file)) return false;
   seen.add(file);
-  const log = join(dir, "provenance.jsonl");
+  const log = join(ventureFile(dir, "provenance.jsonl"));
   if (!existsSync(log)) return false;
   const draft = `_drafts/${file.replace(/\//g, "__")}.draft`;
   const es = readFileSync(log, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l)).filter((e) => e.entity === file || e.entity === draft);
@@ -64,8 +65,8 @@ export function foundation(dir) {
     if (!s.record) return { id: s.id, status: "planned", note: s.note ?? null };
     const files = filesOf(dir, s.record);
     // A retired product no longer answers for the venture.
-    const values = files.filter((f) => existsSync(join(dir, f)) && load(join(dir, f)).status !== "retired").map((f) => ({ f, v: get(load(join(dir, f)), s.attribute) })).filter((x) => filled(x.v));
-    const drafts = files.filter((f) => existsSync(join(dir, `_drafts/${f.replace(/\//g, "__")}.draft`)));
+    const values = files.filter((f) => existsSync(ventureFile(dir, f)) && load(ventureFile(dir, f)).status !== "retired").map((f) => ({ f, v: get(load(ventureFile(dir, f)), s.attribute) })).filter((x) => filled(x.v));
+    const drafts = files.filter((f) => existsSync(ventureFile(dir, `_drafts/${f.replace(/\//g, "__")}.draft`)));
     if (!values.length) return { id: s.id, record: s.record, attribute: s.attribute, status: drafts.length ? "draft" : "missing" };
     // A record with no log entry existed before the log; a person's baseline or write confirms it.
     const confirmed = values.every(({ f }) => confirmedIn(dir, f, s.id));
@@ -87,7 +88,7 @@ export function foundation(dir) {
 
 export function problems(dir) {
   const out = FRAME.questions.flatMap((q) => q.statements).filter((s) => s.record && !MODEL.records.some((r) => r.id === s.record)).map((s) => `frame: ${s.id} names record type ${s.record}, which the data model lacks`);
-  const there = (...fs) => fs.map((f) => join(dir, f)).find((p) => existsSync(p));
+  const there = (...fs) => fs.map((f) => ventureFile(dir, f)).find((p) => existsSync(p));
   const icp = there("foundation/icp.json", "purpose/icp.json"), prob = there("foundation/problem.json", "purpose/validation/problem.json");
   if (icp) {
     const forms = new Set(existsSync(prob) ? (load(prob).forms ?? []).map((f) => f.id) : []);

package/schema/founder.schema.json

@@ -8,7 +8,6 @@
     "id",
     "name",
     "role",
-    "hats",
     "joined"
   ],
   "additionalProperties": false,
@@ -46,7 +45,8 @@
           "capabilities"
         ]
       },
-      "uniqueItems": true
+      "uniqueItems": true,
+      "description": "The functions this founder owns, in the flat layout. In the structured layout (EE-086) they are read from venture.json"
     },
     "joined": {
       "type": "string",

package/schema/frames.mjs

@@ -23,6 +23,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
+import { ventureFile } from "./venture-paths.mjs";
 
 const repo = new URL("..", import.meta.url).pathname;
 const load = (p) => JSON.parse(readFileSync(p, "utf8"));
@@ -93,9 +94,9 @@ export async function props(dir) {
   const v = load(join(dir, "venture.json"));
   const ds = decisions(dir).decisions;
   const answer = (id) => { const d = ds.find((x) => x.id === id); return d?.status === "decided" ? d.answer : null; };
-  const sum = existsSync(join(dir, "money/_summary.json")) ? load(join(dir, "money/_summary.json")) : null;
-  const own = existsSync(join(dir, "governance/ownership.json")) ? load(join(dir, "governance/ownership.json")) : null;
-  const people = existsSync(join(dir, "people/people.json")) ? load(join(dir, "people/people.json")) : null;
+  const sum = existsSync(join(ventureFile(dir, "money/_summary.json"))) ? load(join(ventureFile(dir, "money/_summary.json"))) : null;
+  const own = existsSync(join(ventureFile(dir, "governance/ownership.json"))) ? load(join(ventureFile(dir, "governance/ownership.json"))) : null;
+  const people = existsSync(join(ventureFile(dir, "people/people.json"))) ? load(join(ventureFile(dir, "people/people.json"))) : null;
   const out = {
     phase: v.phase,
     goal: answer("discovery-goal") ?? NONE,

package/schema/freshness.mjs

@@ -39,6 +39,7 @@ import { agentFromEnv, entries as provEntries, record as prov } from "../interfa
 import { files as ventureFiles, glob, resolve as resolveRoute, routes } from "../interface/router.mjs";
 import { connect, LOCAL, sourcesOf } from "../knowledge/connectors/index.mjs";
 import { decisions as decisionMatrix, PHASES } from "./decisions.mjs";
+import { ventureFile } from "./venture-paths.mjs";
 
 const repo = new URL("..", import.meta.url).pathname;
 const load = (f) => JSON.parse(readFileSync(f, "utf8"));
@@ -83,7 +84,7 @@ const human = (s) => s % 604800 === 0 && s ? `${s / 604800}w` : s % 86400 === 0
  */
 export function profiles(dir) {
   const base = load(join(repo, DEFAULTS));
-  const cfg = dir && existsSync(join(dir, "naive.config.json")) ? load(join(dir, "naive.config.json")).freshness ?? {} : {};
+  const cfg = dir && existsSync(join(ventureFile(dir, "naive.config.json"))) ? load(join(ventureFile(dir, "naive.config.json"))).freshness ?? {} : {};
   const out = { default: cfg.default ?? base.default, profiles: { ...base.profiles, ...(cfg.profiles ?? {}) }, records: { ...base.records, ...(cfg.records ?? {}) }, overridden: Object.keys(cfg).length > 0 };
   const where = (k) => (cfg.profiles?.[k] || cfg.records?.[k] || k === "default") && out.overridden ? "naive.config.json freshness" : DEFAULTS;
   for (const [name, p] of Object.entries(out.profiles)) {
@@ -124,7 +125,7 @@ export function recordFiles(dir) {
 
 /** The freshness log: revalidate, verify and phase events, oldest first. */
 export function events(dir) {
-  const f = join(dir, LOG);
+  const f = ventureFile(dir, LOG);
   return existsSync(f) ? readFileSync(f, "utf8").split("\n").filter((l) => l.trim()).map((l) => JSON.parse(l)) : [];
 }
 
@@ -172,7 +173,7 @@ const at = (obj, pointer) => pointer.split("/").slice(1).map((k) => k.replace(/~
 // parent record; a child that does not show the parent's value has drifted. Children elsewhere
 // are read through their connector when it is a file system, else left to the platform.
 async function whereUsed(dir, byRoute, byPath, unchecked) {
-  const f = join(dir, "knowledge/where-used.json");
+  const f = join(ventureFile(dir, "knowledge/where-used.json"));
   if (!existsSync(f)) return [];
   const ids = new Map(sourcesOf(dir).sources.map((s) => [s.id, s]));
   const out = [];
@@ -181,13 +182,13 @@ async function whereUsed(dir, byRoute, byPath, unchecked) {
     const route = r ? (r.collection === "item" ? r.route.replace("[id]", params.id) : r.route) : fact.parent.route;
     const parent = byRoute.get(route);
     if (!parent || !parent.endsWith(".json")) { unchecked.push(`${fact.id}: parent ${fact.parent.route} is not a JSON record in the venture folder`); continue; }
-    const value = at(load(join(dir, parent)), fact.parent.pointer);
+    const value = at(load(ventureFile(dir, parent)), fact.parent.pointer);
     for (const child of fact.children) {
       if (child.status === "frozen") continue;
       const s = ids.get(child.source);
       if (!s || s.connector !== "filesystem") { unchecked.push(`${fact.id} -> ${child.source}://${child.path}: needs the platform to check`); continue; }
       let content;
-      if (s.id === LOCAL) content = existsSync(join(dir, child.path)) ? readFileSync(join(dir, child.path), "utf8") : null;
+      if (s.id === LOCAL) content = existsSync(ventureFile(dir, child.path)) ? readFileSync(ventureFile(dir, child.path), "utf8") : null;
       else content = (await (await connect(s, dir)).read(child.path))?.content ?? null;
       const shows = content === null ? false : child.match.kind === "json"
         ? (() => { try { return JSON.stringify(at(JSON.parse(content), child.match.pointer)) === JSON.stringify(value); } catch { return false; } })()
@@ -217,17 +218,17 @@ export async function freshness(dir, { now, light = false } = {}) {
   const change = phaseChange(dir, venture, evs, warnings);
   const lastOf = (path, kinds) => { const e = log.filter((x) => x.entity === path && kinds.has(x.activity)).at(-1); return e ? Date.parse(e.at) : null; };
   // The last time a file's content changed: its last logged write, else its file time.
-  const changedAt = (path) => lastOf(path, CONTENT) ?? (existsSync(join(dir, path)) ? statSync(join(dir, path)).mtimeMs : null);
+  const changedAt = (path) => lastOf(path, CONTENT) ?? (existsSync(ventureFile(dir, path)) ? statSync(ventureFile(dir, path)).mtimeMs : null);
 
   for (const i of items) {
     const write = lastOf(i.path, CONTENT), confirmed = lastOf(i.path, CHECKED);
     const verified = evs.filter((e) => e.event === "verify" && e.target && covers(e.target, i, dir)).map((e) => Date.parse(e.at)).at(-1) ?? null;
     const known = [[write, "provenance log: written"], [confirmed, "provenance log: confirmed"], [verified, "freshness log: verified"]].filter(([x]) => x !== null).sort((a, b) => b[0] - a[0]);
-    i.checked_at = known.length ? known[0][0] : statSync(join(dir, i.path)).mtimeMs;
+    i.checked_at = known.length ? known[0][0] : statSync(ventureFile(dir, i.path)).mtimeMs;
     i.basis = known.length ? known[0][1] : "file time (not in the provenance log)";
-    i.changed_at = write ?? statSync(join(dir, i.path)).mtimeMs;
+    i.changed_at = write ?? statSync(ventureFile(dir, i.path)).mtimeMs;
     const latest = log.filter((x) => x.entity === i.path && x.derived_from?.length && CONTENT.has(x.activity)).at(-1);
-    i.depends_on = normalizeDeps(latest?.derived_from, byRoute, log).filter((d) => d !== i.path && (byPath.has(d) || existsSync(join(dir, d))));
+    i.depends_on = normalizeDeps(latest?.derived_from, byRoute, log).filter((d) => d !== i.path && (byPath.has(d) || existsSync(ventureFile(dir, d))));
     i.profile = profileFor(P, i.record, i.route);
     i.reasons = [];
   }
@@ -356,7 +357,7 @@ function append(dir, event, by) {
   rmSync(scratch, { recursive: true, force: true });
   if (v.status !== 0) throw new Error(`does not match schema/freshness-log.schema.json:\n${(v.stdout + v.stderr).trim()}`);
   mkdirSync(join(dir, dirname(LOG)), { recursive: true });
-  appendFileSync(join(dir, LOG), JSON.stringify(line) + "\n");
+  appendFileSync(ventureFile(dir, LOG), JSON.stringify(line) + "\n");
   const what = event.target ? `${event.target.kind}:${event.target.value}` : `${event.from} -> ${event.to}`;
   const entry = prov(dir, { entity: LOG, route: "knowledge/freshness-log", activity: "write", agent: by, note: `${event.event} ${what}${event.reason ? `: ${event.reason}` : ""}` });
   return { line, provenance: entry.hash };
@@ -437,10 +438,10 @@ export async function freeze(dir, out, { now } = {}) {
   if (!rel.startsWith("..") && !isAbsolute(rel) && !rel.split("/")[0].startsWith(".")) return { ok: false, error: `${out} is inside the venture: freeze into a folder outside it, or under a dot folder such as .release/` };
   const byPath = new Map(f.items.map((i) => [i.path, i]));
   mkdirSync(target, { recursive: true });
-  for (const p of f.shell.frozen) { mkdirSync(dirname(join(target, p)), { recursive: true }); copyFileSync(join(dir, p), join(target, p)); }
+  for (const p of f.shell.frozen) { mkdirSync(dirname(join(target, p)), { recursive: true }); copyFileSync(ventureFile(dir, p), join(target, p)); }
   const manifest = {
     venture: f.venture, phase: f.phase, frozen_at: f.now,
-    frozen: f.shell.frozen.map((p) => { const i = byPath.get(p); return { path: p, route: i.route, record: i.record, state: i.state, sha256: createHash("sha256").update(readFileSync(join(dir, p))).digest("hex"), ...(i.state === "stale" ? { reasons: i.reasons.map((r) => r.note) } : {}) }; }),
+    frozen: f.shell.frozen.map((p) => { const i = byPath.get(p); return { path: p, route: i.route, record: i.record, state: i.state, sha256: createHash("sha256").update(readFileSync(ventureFile(dir, p))).digest("hex"), ...(i.state === "stale" ? { reasons: i.reasons.map((r) => r.note) } : {}) }; }),
     holes: f.shell.holes.map((p) => { const i = byPath.get(p); return { path: p, route: i.route, record: i.record, profile: i.profile, read: `mentura ${i.route} read --venture ${f.venture}` }; }),
   };
   writeFileSync(join(target, "shell.json"), JSON.stringify(manifest, null, 2) + "\n");

package/schema/gate-drafts.mjs

@@ -14,6 +14,7 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { approve } from "./decisions.mjs";
+import { ventureFile } from "./venture-paths.mjs";
 
 const sha = (s) => createHash("sha256").update(s).digest("hex");
 const LETTERS = "abcdefghijklmnopqrstuvwxyz";
@@ -42,7 +43,7 @@ export function sidecar(dir, draft) {
  * Returns { written, variant, variants, decision }.
  */
 export function writeHeld(dir, { draft, file, text, verdict, route, agent = {} }) {
-  const dest = join(dir, draft);
+  const dest = ventureFile(dir, draft);
   mkdirSync(dirname(dest), { recursive: true });
   const at = new Date().toISOString();
   const by = agent.id ?? agent.kind ?? "agent";
@@ -64,7 +65,7 @@ export function writeHeld(dir, { draft, file, text, verdict, route, agent = {} }
   const next = LETTERS[variants.length];
   if (!next) throw new Error(`${route} already holds ${variants.length} drafts side by side; accept one first`);
   const vfile = variantPath(draft, next);
-  writeFileSync(join(dir, vfile), text);
+  writeFileSync(ventureFile(dir, vfile), text);
   variants.push({ variant: next, file: vfile, by, at, sha256: sha(text) });
   const dec = variantsDecision(file);
   const record = {
@@ -79,8 +80,8 @@ export function writeHeld(dir, { draft, file, text, verdict, route, agent = {} }
     note: `The gate kept ${variants.length} differing drafts side by side (rule ${verdict.rule}). Accept one: mentura accept ${route} --pick <letter>`,
     provenance: { drafted_by: { kind: "framework" } },
   };
-  mkdirSync(dirname(join(dir, dec.path)), { recursive: true });
-  writeFileSync(join(dir, dec.path), JSON.stringify(record, null, 2) + "\n");
+  mkdirSync(dirname(ventureFile(dir, dec.path)), { recursive: true });
+  writeFileSync(ventureFile(dir, dec.path), JSON.stringify(record, null, 2) + "\n");
   writeFileSync(join(dir, sidecarOf(draft)), JSON.stringify({ ...(meta ?? { route, file, rule: verdict.rule, source: verdict.source, then: verdict.then, ...(verdict.owner ? { owner: verdict.owner, function: verdict.function ?? null } : {}) }), variants, decision: dec.id }, null, 2) + "\n");
   return { written: vfile, variant: next, variants: variants.map((v) => v.variant), decision: dec.id };
 }
@@ -99,8 +100,8 @@ export function pick(dir, draft, letter) {
 /** After a person accepts a draft: removes every variant and the sidecar, and decides the variants decision. */
 export function settle(dir, draft, { picked = "a", by } = {}) {
   const meta = sidecar(dir, draft);
-  for (const v of meta?.variants ?? []) rmSync(join(dir, v.file), { force: true });
-  rmSync(join(dir, draft), { force: true });
+  for (const v of meta?.variants ?? []) rmSync(ventureFile(dir, v.file), { force: true });
+  rmSync(ventureFile(dir, draft), { force: true });
   rmSync(join(dir, sidecarOf(draft)), { force: true });
   if (!meta?.decision) return { picked };
   const d = approve(dir, meta.decision, { by: by ?? process.env.MENTURA_PERSON ?? "founder", answer: picked, note: `accepted draft ${picked} of ${meta.route}` });
@@ -109,7 +110,7 @@ export function settle(dir, draft, { picked = "a", by } = {}) {
 
 /** The drafts waiting in a venture: route, rule, owner and variants. A draft with no sidecar was held by its decision class. */
 export function inbox(dir, owner) {
-  const d = join(dir, "_drafts");
+  const d = join(ventureFile(dir, "_drafts"));
   if (!existsSync(d)) return [];
   return readdirSync(d).filter((f) => f.endsWith(".draft")).sort().map((f) => {
     const draft = `_drafts/${f}`;

package/schema/init-venture.mjs

@@ -19,6 +19,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
+import { ventureFile } from "./venture-paths.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const repo = join(here, "..");
@@ -26,6 +27,10 @@ const { layers, formalized, pillars, readme } = JSON.parse(readFileSync(join(her
 const args = process.argv.slice(2);
 const flag = (name) => { const i = args.indexOf(`--${name}`); return i < 0 ? null : args.splice(i, 2)[1]; };
 const phase = flag("phase") ?? "discovery", parent = flag("parent"), legalForm = flag("legal-form"), only = flag("layers"), typeId = flag("type");
+// --layout structured (EE-086): knowledge/, meta/ and an org chart in venture.json; without it, the flat layout.
+const layout = flag("layout") ?? "flat";
+if (!["flat", "structured"].includes(layout)) { console.error(`unknown layout ${layout}: flat or structured`); process.exit(2); }
+const structured = layout === "structured";
 const vtype = typeId ? JSON.parse(readFileSync(join(here, "venture-types.json"), "utf8")).types.find((t) => t.id === typeId) : null;
 if (typeId && !vtype) { console.error(`unknown venture type ${typeId}: see node schema/venture-type.mjs list`); process.exit(2); }
 const [dir, id] = args;
@@ -41,27 +46,37 @@ mkdirSync(dir, { recursive: true });
 const venture = { id, name: id, ...(vtype ? { type: vtype.id } : {}), parent: parent ?? null, phase };
 if (legalForm || vtype?.funding) venture.form = { ...(legalForm ? { legal_form: legalForm } : {}), ...(vtype?.funding ? { funding: vtype.funding } : {}) };
 if (phase !== "discovery") venture.core = { promise: "", promised_to: "", must_not: "", competence: "" };
-Object.assign(venture, { owner: "self", status: "active", profile: "profile.md", layers: {} });
-for (const layer of ALL) {
+Object.assign(venture, { owner: "self", status: "active", profile: structured ? "README.md" : "profile.md", layers: {} });
+// The package folders (EE-070); a typed venture gets its type's packages.
+const packageDirs = vtype ? vtype.packages : ["foundation", "validation", "product", "marketing", "finance", "people", "customers", "investors", "money"];
+if (structured) {
+  // venture.json first, so every path below resolves into knowledge/ and meta/. The org chart starts flat:
+  // one function per package, owned by no one until create-venture or the founder names the owner.
+  venture.layout = "structured";
+  venture.functions = Object.fromEntries(packageDirs.map((p) => [p, { owner: null }]));
+  for (const layer of ALL) venture.layers[layer] = on.includes(layer) ? { location: "knowledge/" } : false;
+  writeFileSync(join(dir, "venture.json"), JSON.stringify(venture, null, 2) + "\n");
+  for (const sub of ["knowledge", "meta"]) mkdirSync(ventureFile(dir, sub), { recursive: true });
+}
+for (const layer of structured ? [] : ALL) {
   if (!on.includes(layer)) { if (only !== null || !["governance", "interface"].includes(layer)) venture.layers[layer] = false; continue; }
-  mkdirSync(join(dir, layer), { recursive: true });
+  mkdirSync(ventureFile(dir, layer), { recursive: true });
   writeFileSync(join(dir, layer, "README.md"), `# ${layer}\n\n${readme[layer]}\n`);
   venture.layers[layer] = { location: `${layer}/` };
 }
-for (const sub of ["products", "accounts"]) { mkdirSync(join(dir, sub), { recursive: true }); writeFileSync(join(dir, sub, ".gitkeep"), ""); }
+if (!structured) for (const sub of ["products", "accounts"]) { mkdirSync(ventureFile(dir, sub), { recursive: true }); writeFileSync(join(dir, sub, ".gitkeep"), ""); }
 // The package folder layout (EE-070). Old layer folders above stay for one release.
 // A typed venture gets its type's packages; the rest stay out until need-now suggests them.
-const packageDirs = vtype ? vtype.packages : ["foundation", "validation", "product", "marketing", "finance", "people", "customers", "investors", "money"];
-for (const sub of ["raw/dump", "raw/sources", "ideas", ...packageDirs, "decisions", "evidence", "public", "_private", "_drafts", ".release"]) {
-  mkdirSync(join(dir, sub), { recursive: true });
+for (const sub of ["raw/dump", "raw/sources", "ideas", ...packageDirs, "decisions", "evidence", ...(structured ? [] : ["public"]), "_private", "_drafts", ".release"]) {
+  mkdirSync(ventureFile(dir, sub), { recursive: true });
 }
-mkdirSync(join(dir, "pillars"), { recursive: true });
-for (const [name, what] of Object.entries(pillars.stubs)) {
-  const guide = relative(join(dir, "pillars"), join(repo, pillars.guides, `${name}.md`));
-  writeFileSync(join(dir, "pillars", `${name}.md`), `# ${name[0].toUpperCase() + name.slice(1)} pillar\n\n${what}\n\nGuide: [${name} pillar](${guide})\n`);
+if (!structured) mkdirSync(join(ventureFile(dir, "pillars")), { recursive: true });
+for (const [name, what] of Object.entries(structured ? {} : pillars.stubs)) {
+  const guide = relative(join(ventureFile(dir, "pillars")), join(repo, pillars.guides, `${name}.md`));
+  writeFileSync(join(ventureFile(dir, "pillars"), `${name}.md`), `# ${name[0].toUpperCase() + name.slice(1)} pillar\n\n${what}\n\nGuide: [${name} pillar](${guide})\n`);
 }
-writeFileSync(join(dir, "profile.md"), `# ${id}\n\nWhat this venture is, in a few sentences. Its machine fields are in venture.json (EE-011).\n\n## Changelog\n`);
-writeFileSync(join(dir, "venture.json"), JSON.stringify(venture, null, 2) + "\n");
+writeFileSync(join(ventureFile(dir, "profile.md")), `# ${id}\n\nWhat this venture is, in a few sentences. Its machine fields are in venture.json (EE-011).\n\n## Changelog\n`);
+if (!structured) writeFileSync(join(dir, "venture.json"), JSON.stringify(venture, null, 2) + "\n");
 // The venture's root layout (EE-072, I-4): every route's layout chain starts here. Lines shaped
 // "key: value" are instructions the router hands an agent with the layout.
 writeFileSync(join(dir, "AGENTS.md"), `# AGENTS.md: ${id}
@@ -97,8 +112,8 @@ const productFoundation = [
 ];
 // The team question (EE-060): asked in Discovery, failing open, so validation never waits on it. A
 // founding team, or a founder looking for one, gets the founder-agreement kit beside validation.
-mkdirSync(join(dir, "decisions"), { recursive: true });
-writeFileSync(join(dir, "decisions/venture.team.decision.json"), JSON.stringify({ id: "founding-team", question: "Who is founding this venture: you alone, you with cofounders, or you looking for cofounders?",
+mkdirSync(join(ventureFile(dir, "decisions")), { recursive: true });
+writeFileSync(join(ventureFile(dir, "decisions/venture.team.decision.json")), JSON.stringify({ id: "founding-team", question: "Who is founding this venture: you alone, you with cofounders, or you looking for cofounders?",
   decides: { record: "founder-agreement", path: "governance/founder-agreement.json" }, layer: "governance", boundary: "fail-open", needed_in: phase, status: "open",
   options: ["Solo: I am founding it alone", "Cofounders: we are founding it together", "Looking: I want cofounders"],
   unlocks: [{ activity: "Draft the founder agreement with the founding-agreement kit", routes: ["governance/founder-agreement"] }], provenance: framework }, null, 2) + "\n");
@@ -113,15 +128,18 @@ const fundFoundation = [
 ];
 const decisionSet = vtype?.decisions ?? "product-foundation";
 if (decisionSet === "fund-foundation") {
-  mkdirSync(join(dir, "fund/decisions"), { recursive: true });
-  for (const d of fundFoundation) writeFileSync(join(dir, "fund/decisions", `${d.id === "first-close" ? "terms.first-close" : d.id.replace(/^fund-/, "")}.decision.json`),
+  mkdirSync(join(ventureFile(dir, "fund/decisions")), { recursive: true });
+  for (const d of fundFoundation) writeFileSync(join(ventureFile(dir, "fund/decisions"), `${d.id === "first-close" ? "terms.first-close" : d.id.replace(/^fund-/, "")}.decision.json`),
     JSON.stringify({ ...d, layer: "purpose", boundary: "fail-closed", needed_in: phase, status: "open", provenance: framework }, null, 2) + "\n");
 }
-if (decisionSet === "product-foundation") mkdirSync(join(dir, "products/decisions"), { recursive: true });
-if (decisionSet === "product-foundation") for (const d of productFoundation) writeFileSync(join(dir, "products/decisions", `product.${d.id.replace(/^product-/, "")}.decision.json`),
+// The product questions sit beside the products: product/ in the structured layout, products/ in the flat one.
+const productDecisions = structured ? "product/decisions" : "products/decisions";
+if (decisionSet === "product-foundation") mkdirSync(join(ventureFile(dir, productDecisions)), { recursive: true });
+if (decisionSet === "product-foundation") for (const d of productFoundation) writeFileSync(join(ventureFile(dir, productDecisions), `product.${d.id.replace(/^product-/, "")}.decision.json`),
   JSON.stringify({ ...d, layer: "purpose", boundary: "fail-closed", needed_in: phase, status: "open", provenance: framework }, null, 2) + "\n");
 // The type's functions are imported like any department (EE-047): listed in venture.json, with their folders.
-if (vtype) for (const d of vtype.departments) {
+// In the structured layout the org chart is venture.json's functions; the flat layout imports departments.
+if (vtype && !structured) for (const d of vtype.departments) {
   const r = spawnSync("node", [join(here, "add-department.mjs"), dir, d], { encoding: "utf8" });
   if (r.status !== 0) { console.error((r.stderr || r.stdout).trim()); process.exit(1); }
 }

package/schema/migrate-venture.mjs

@@ -21,6 +21,7 @@ import { fileURLToPath } from "node:url";
 import { call, routes } from "../interface/router.mjs";
 import { agentFromEnv, record as prov } from "../interface/provenance.mjs";
 import { propose } from "./decisions.mjs";
+import { ventureFile } from "./venture-paths.mjs";
 
 export const PLAN = ".release/migrate-plan.json";
 const MAX_FILE = 512 * 1024;
@@ -117,7 +118,7 @@ Files: ${JSON.stringify(Object.fromEntries(given.map((f) => [f.path, f.text])))}
 /** Writes the plan into the venture and proposes one open decision per function it touches. */
 export function proposeDecisions(dir, p) {
   mkdirSync(join(dir, dirname(PLAN)), { recursive: true });
-  writeFileSync(join(dir, PLAN), JSON.stringify(p, null, 2) + "\n");
+  writeFileSync(ventureFile(dir, PLAN), JSON.stringify(p, null, 2) + "\n");
   prov(dir, { entity: PLAN, activity: "draft", agent: agentFromEnv("agent", "migrate", { id: "naive-migrate" }), note: `migrate plan from ${p.from}: ${p.items.length} records, ${p.left_behind.length} left behind` });
   const groups = new Map();
   for (const it of p.items) groups.set(functionOf(it.route), [...(groups.get(functionOf(it.route)) ?? []), it]);
@@ -139,8 +140,8 @@ const answerOf = (d) => { const a = String(d?.answer ?? "").toLowerCase(); retur
 
 /** Writes what a person decided, through the router. Open decisions wait. */
 export async function apply(dir) {
-  const p = load(join(dir, PLAN));
-  const decisionOf = (fn) => { const f = join(dir, "decisions", `migrate-${fn}.decision.json`); return existsSync(f) ? load(f) : null; };
+  const p = load(ventureFile(dir, PLAN));
+  const decisionOf = (fn) => { const f = join(ventureFile(dir, "decisions"), `migrate-${fn}.decision.json`); return existsSync(f) ? load(f) : null; };
   const done = { brought: 0, drafted: 0, pointed: 0, left: 0, waiting: 0, failed: 0 };
   let pointed = false;
   for (const it of p.items.filter((x) => x.status === "planned")) {
@@ -157,7 +158,7 @@ export async function apply(dir) {
     done[it.status]++;
   }
   if (pointed) {
-    const f = join(dir, "knowledge/sources.json");
+    const f = join(ventureFile(dir, "knowledge/sources.json"));
     const s = existsSync(f) ? load(f) : { sources: [], records: {} };
     const id = slug(basename(p.from));
     if (!s.sources.some((x) => x.id === id)) s.sources.push({ id, connector: "filesystem", writes: "none", root: p.from, note: "migrate: a person chose to point to these files rather than rewrite them" });
@@ -165,7 +166,7 @@ export async function apply(dir) {
     writeFileSync(f, JSON.stringify(s, null, 2) + "\n");
     prov(dir, { entity: "knowledge/sources.json", activity: "write", agent: agentFromEnv("agent", "migrate", { id: "naive-migrate" }), note: `points to ${p.from}, read-only` });
   }
-  writeFileSync(join(dir, PLAN), JSON.stringify(p, null, 2) + "\n");
+  writeFileSync(ventureFile(dir, PLAN), JSON.stringify(p, null, 2) + "\n");
   return done;
 }
 
@@ -176,7 +177,7 @@ if (import.meta.url === `file://${process.argv[1]}`) {
   if (!dir || !existsSync(join(dir, "venture.json"))) { console.error("usage: node schema/migrate-venture.mjs --from <project> --venture <dir> | --venture <dir> --apply"); process.exit(2); }
   try {
     if (args.includes("--apply")) {
-      if (!existsSync(join(dir, PLAN))) { console.error(`no plan at ${join(dir, PLAN)}: run with --from first`); process.exit(1); }
+      if (!existsSync(ventureFile(dir, PLAN))) { console.error(`no plan at ${ventureFile(dir, PLAN)}: run with --from first`); process.exit(1); }
       const d = await apply(dir);
       console.log(Object.entries(d).filter(([, n]) => n).map(([k, n]) => `${n} ${k}`).join(", ") || "nothing to do");
     } else {
@@ -186,7 +187,7 @@ if (import.meta.url === `file://${process.argv[1]}`) {
       for (const i of p.items) console.log(`${i.id}  ${i.from.join(", ")}  ->  ${i.route}   (${i.reshaping})`);
       for (const l of p.left_behind) console.log(`left  ${l.from}   (${l.why})`);
       console.log(`\n${p.items.length} records planned, ${p.left_behind.length} left behind. Nothing is written yet.`);
-      if (decisions.length) console.log(`Read ${relative(process.cwd(), join(dir, PLAN))}, then decide ${decisions.join(", ")} with mentura decide (answer "bring in", "point to them" or "leave them"), then run with --apply.`);
+      if (decisions.length) console.log(`Read ${relative(process.cwd(), ventureFile(dir, PLAN))}, then decide ${decisions.join(", ")} with mentura decide (answer "bring in", "point to them" or "leave them"), then run with --apply.`);
     }
   } catch (e) { console.error(e.message); process.exit(1); }
 }

package/schema/migrations/kit-to-package.mjs

@@ -14,6 +14,7 @@
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { ventureFile } from "../venture-paths.mjs";
 
 export const id = "kit-to-package";
 export const describe = "Moves Naive packages out of naive.config.json kits into packages, and rewrites layer and kit routes inside records (decision unlocks, team-plan access, where-used parents) to package routes";
@@ -67,15 +68,15 @@ export function apply(dir, ctx) {
     return r.to;
   };
   const rewriteFile = (file, fn) => {
-    if (!existsSync(join(dir, file))) return;
-    const before = readFileSync(join(dir, file), "utf8");
+    if (!existsSync(ventureFile(dir, file))) return;
+    const before = readFileSync(ventureFile(dir, file), "utf8");
     const rec = JSON.parse(before);
     fn(rec);
     const after = JSON.stringify(rec, null, 2) + "\n";
     if (after.trim() !== before.trim()) ctx.write(file, after, { note: "routes renamed from layer and kit routes to package routes (EE-071)" });
   };
 
-  const decisionFiles = (sub = "") => readdirSync(join(dir, sub), { withFileTypes: true }).flatMap((e) => {
+  const decisionFiles = (sub = "") => readdirSync(ventureFile(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(rel);
     return e.name.endsWith(".decision.json") ? [rel] : [];

package/schema/migrations/package-layout.mjs

@@ -8,16 +8,20 @@
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { ventureFile } from "../venture-paths.mjs";
+import { layoutOf } from "../venture-paths.mjs";
 
 export const id = "package-layout";
 export const describe = "Moves records from the layer folders (purpose/, pillars/, products/, knowledge/) into package folders (foundation/, validation/, product/, marketing/, people/, decisions/)";
 
 export function apply(dir, ctx) {
+  // A venture in the structured layout (EE-086) is already past this layout: nothing to move.
+  if (layoutOf(dir) === "structured") return;
   const load = (p) => JSON.parse(readFileSync(p, "utf8"));
   // A decision file infers its target from the folder it sits in. Stamp that path before the file
   // moves, so the decision still points at the same record.
   const stampDecisions = (folder) => {
-    const d = join(dir, folder);
+    const d = ventureFile(dir, folder);
     if (!existsSync(d)) return;
     for (const f of readdirSync(d).filter((x) => x.endsWith(".decision.json"))) {
       const rec = load(join(d, f));
@@ -45,7 +49,7 @@ export function apply(dir, ctx) {
   ];
   for (const [a, b] of pairs) ctx.mv(a, b);
 
-  const list = (rel, ext) => existsSync(join(dir, rel)) ? readdirSync(join(dir, rel)).filter((f) => f.endsWith(ext)) : [];
+  const list = (rel, ext) => existsSync(ventureFile(dir, rel)) ? readdirSync(ventureFile(dir, rel)).filter((f) => f.endsWith(ext)) : [];
   for (const f of list("products", ".json")) ctx.mv(`products/${f}`, `product/${f}`);
   for (const f of list("purpose/anatomy", ".json")) ctx.mv(`purpose/anatomy/${f}`, `product/anatomy/${f}`);
 
@@ -55,7 +59,7 @@ export function apply(dir, ctx) {
   }
 
   for (const f of ["product.md", "business.md"]) {
-    if (existsSync(join(dir, "pillars", f))) {
+    if (existsSync(join(ventureFile(dir, "pillars"), f))) {
       ctx.mv(`pillars/${f}`, `_private/pillars/${f}`);
       ctx.escalate(`${f.replace(".md", "")} pillar: the brief names a home only for brand (marketing/). Archived at _private/pillars/${f} rather than guessed.`);
     }
@@ -68,8 +72,8 @@ export function apply(dir, ctx) {
   for (const gone of ["purpose", "pillars", "knowledge", "products"]) ctx.removeEmpty(gone);
 
   const policy = "governance/publication-policy.json";
-  if (existsSync(join(dir, policy))) {
-    const text = readFileSync(join(dir, policy), "utf8");
+  if (existsSync(ventureFile(dir, policy))) {
+    const text = readFileSync(ventureFile(dir, policy), "utf8");
     if (text.includes("pillars/brand.md")) ctx.write(policy, text.replaceAll("pillars/brand.md", "marketing/brand.md"), { note: "the brand pillar moved to marketing/brand.md (EE-070)" });
   }