naive-framework 0.2.0 → 0.4.0

package/schema/check-ready.mjs

@@ -13,19 +13,20 @@
 import { execSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { ventureFile } from "./venture-paths.mjs";
 
 const [dir, id] = process.argv.slice(2);
 if (!dir || !id) { console.error("usage: node schema/check-ready.mjs <venture dir> <handoff id> [--record --by <who>]"); process.exit(2); }
 const opt = (k) => process.argv.includes(k) ? process.argv[process.argv.indexOf(k) + 1] : undefined;
 const root = new URL("..", import.meta.url).pathname;
 const load = (p) => JSON.parse(readFileSync(p, "utf8"));
-const hPath = join(dir, "operations/handoffs", `${id}.json`);
+const hPath = join(ventureFile(dir, "operations/handoffs"), `${id}.json`);
 const h = load(hPath);
 const items = [];
 const item = (name, ok, why = "") => items.push({ name, ok, why });
 
 // 1. The brief says what done looks like and what to do, with no placeholders left.
-const bPath = join(dir, "operations/handoffs", h.brief);
+const bPath = join(ventureFile(dir, "operations/handoffs"), h.brief);
 const brief = existsSync(bPath) ? readFileSync(bPath, "utf8") : "";
 item("brief exists", !!brief, bPath);
 const section = (name) => { const m = brief.match(new RegExp(`^##\\s+(?:\\d+\\.\\s*)?${name}\\b[^\\n]*\\n([\\s\\S]*?)(?=^##\\s|$(?![\\s\\S]))`, "mi")); return m ? m[1].trim() : null; };
@@ -34,10 +35,10 @@ const holes = brief.match(/\b(TBD|TODO|FIXME)\b|\?\?\?|<(?:title|role|entity|out
 item("brief has no placeholders left", !holes.length, holes.slice(0, 3).join(", "));
 
 // 2. Everything it names exists.
-const products = new Set(["products", "product"].flatMap((folder) => existsSync(join(dir, folder)) ? readdirSync(join(dir, folder)).filter((f) => f.endsWith(".json")).map((f) => f.slice(0, -5)) : []));
+const products = new Set(["products", "product"].flatMap((folder) => existsSync(ventureFile(dir, folder)) ? readdirSync(ventureFile(dir, folder)).filter((f) => f.endsWith(".json")).map((f) => f.slice(0, -5)) : []));
 const missingProducts = (h.products ?? []).filter((p) => !products.has(p));
 item("every product it serves exists", !missingProducts.length, missingProducts.join(", "));
-const logs = [join(root, "docs/decisions/decisions.json"), join(dir, "knowledge/decisions.json")].filter(existsSync).flatMap((f) => load(f).decisions);
+const logs = [join(root, "docs/decisions/decisions.json"), join(ventureFile(dir, "knowledge/decisions.json"))].filter(existsSync).flatMap((f) => load(f).decisions);
 const decisions = new Map(logs.map((d) => [d.id, d]));
 const badDecisions = (h.governed_by ?? []).filter((d) => !decisions.has(d) || ["withdrawn", "superseded"].includes(decisions.get(d).status));
 item("every governing decision exists and is in force or proposed", !badDecisions.length, badDecisions.join(", "));
@@ -49,7 +50,7 @@ item("every input it needs exists", !missingInputs.length, missingInputs.join(",
 // 3. The holder can act inside its rights.
 const roles = new Set(load(join(root, "governance/venture-template/roles/agent-roles.json")).roles.map((r) => r.id));
 const classes = new Map(load(join(root, "governance/venture-template/decision-rights.json")).classes.map((c) => [c.id, c]));
-const own = join(dir, "governance/decision-rights.json");
+const own = join(ventureFile(dir, "governance/decision-rights.json"));
 if (existsSync(own)) for (const c of load(own).classes) classes.set(c.id, { ...classes.get(c.id), ...c });
 item(`role ${h.role} exists`, roles.has(h.role));
 const foreign = h.decision_classes.filter((c) => classes.get(c)?.owner !== h.role);

package/schema/check-sources.mjs

@@ -11,6 +11,7 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { LOCAL, MAP, registry } from "../knowledge/connectors/index.mjs";
 import { ANY, CONTEXT, specificity } from "../knowledge/connectors/resolve.mjs";
+import { ventureFile } from "./venture-paths.mjs";
 
 const dir = process.argv[2];
 if (!dir) { console.error("usage: node schema/check-sources.mjs <workspace or venture dir>"); process.exit(2); }
@@ -27,7 +28,7 @@ const errors = [];
 let maps = 0;
 
 for (const v of walk(dir)) {
-  const f = join(v, MAP);
+  const f = ventureFile(v, MAP);
   if (!existsSync(f)) continue;
   maps++;
   const id = JSON.parse(readFileSync(join(v, "venture.json"), "utf8")).id;

package/schema/check-where-used.mjs

@@ -10,6 +10,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { connect, sourceFor, sourcesOf } from "../knowledge/connectors/index.mjs";
 import { resolve } from "../interface/router.mjs";
+import { ventureFile } from "./venture-paths.mjs";
 
 const dir = process.argv[2];
 if (!dir) { console.error("usage: node schema/check-where-used.mjs <workspace or venture dir> [--json]"); process.exit(2); }
@@ -21,18 +22,18 @@ const at = (obj, pointer) => pointer.split("/").slice(1).map((k) => k.replace(/~
 const errors = [], drift = [], unchecked = [];
 let lists = 0, checked = 0;
 for (const v of walk(dir)) {
-  if (!existsSync(join(v, FILE))) continue;
+  if (!existsSync(ventureFile(v, FILE))) continue;
   lists++;
   const id = JSON.parse(readFileSync(join(v, "venture.json"), "utf8")).id;
   const ids = new Map(sourcesOf(v).sources.map((s) => [s.id, s]));
-  for (const fact of JSON.parse(readFileSync(join(v, FILE), "utf8")).facts) {
+  for (const fact of JSON.parse(readFileSync(ventureFile(v, FILE), "utf8")).facts) {
     const where = `${id}: ${fact.id}`;
     const { r, params } = resolve(fact.parent.route);
     if (!r || r.kind !== "record" || r.collection === "list") { errors.push(`${where}: parent ${fact.parent.route} is not a record route`); continue; }
     const context = r.collection === "item" && (r.record === "product" || r.record === "account") ? { [r.record]: params.id } : {};
     const src = sourceFor(v, r.record, context);
     const cands = (r.collection === "item" ? r.files.map((f) => f.replace("*", params.id)) : r.files).filter((f) => !f.includes("*"));
-    const path = cands.find((f) => existsSync(join(v, f))) ?? cands[0];
+    const path = cands.find((f) => existsSync(ventureFile(v, f))) ?? cands[0];
     if (src.connector !== "filesystem") { unchecked.push(`${where}: parent is in ${src.id}`); continue; }
     const parent = await (await connect(src, v)).read(path);
     const value = parent && at(JSON.parse(parent.content), fact.parent.pointer);

package/schema/decision-analytics.mjs

@@ -19,6 +19,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { decisions } from "./decisions.mjs";
 import { HOME, PACKAGES, TITLES } from "./packages.mjs";
+import { ventureFile } from "./venture-paths.mjs";
 
 const load = (f) => JSON.parse(readFileSync(f, "utf8"));
 const titleOf = (t) => ({ icp: "ICP", "venture-core": "Core product" })[t] ?? TITLES[t] ?? t.replace(/^validation-/, "").replace(/-/g, " ").replace(/^./, (c) => c.toUpperCase());
@@ -30,7 +31,7 @@ const OPEN = new Set(["now", "overdue", "waiting", "stale", "later"]);
 export function analytics(dir, now) {
   const r = decisions(dir, now);
   const rows = r.decisions.filter((d) => d.source !== "root").map((d) => {
-    const raw = d.file ? load(join(dir, d.file)) : {};
+    const raw = d.file ? load(ventureFile(dir, d.file)) : {};
     const record = d.decides?.record ?? null;
     // A foundation statement belongs to the strategic foundation whatever record holds it; so does a
     // decision about venture.json itself (the core product, the team).

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 { KBASE, 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,47 @@ 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 k-base/ 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: `${KBASE}/` } : false;
+  writeFileSync(join(dir, "venture.json"), JSON.stringify(venture, null, 2) + "\n");
+  for (const sub of [KBASE, "meta"]) mkdirSync(join(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 });
+}
+// Every package folder explains itself (EE-086): a README.md from its package, for people. GitHub and
+// editors show it when the folder is opened; an AGENTS.md beside it is the founder's, for agents.
+if (structured) for (const pkg of packageDirs) {
+  const f = join(repo, "packages", pkg, "package.json");
+  if (!existsSync(f)) continue;
+  const p = JSON.parse(readFileSync(f, "utf8"));
+  const lines = [`# ${p.title ?? pkg}`, "", p.purpose ?? "", ...(p.required?.length ? ["", `What goes in it first: ${p.required.join(", ")}.`] : []), ...(p.optional?.length ? [`Also: ${p.optional.join(", ")}.`] : []),
+    ...(p.gates?.length ? ["", `It is ready when ${p.gates.join("; ")}.`] : []), "", `Owner: whoever owns the ${pkg} function in venture.json.`, ""];
+  writeFileSync(join(ventureFile(dir, pkg), "README.md"), lines.join("\n"));
 }
-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 +122,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 +138,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); }
 }