naive-framework 0.2.0 → 0.3.0

package/interface/harness/run.mjs

@@ -42,6 +42,7 @@ import { understood } from "../../purpose/frameworks/idea-map/route.mjs";
 import { createHash } from "node:crypto";
 import { agentFromEnv, record as prov } from "../provenance.mjs";
 import { evaluate } from "./evals.mjs";
+import { ventureFile } from "../../schema/venture-paths.mjs";
 
 const repo = new URL("../../", import.meta.url).pathname;
 const argv = process.argv.slice(2);
@@ -71,8 +72,8 @@ if (!existsSync(join(dir, "venture.json"))) {
   if (p.status !== 0) { console.error(p.stderr || p.stdout); process.exit(1); }
   if (opt("name")) { const v = JSON.parse(readFileSync(join(dir, "venture.json"), "utf8")); v.name = opt("name"); writeFileSync(join(dir, "venture.json"), JSON.stringify(v, null, 2) + "\n"); }
 }
-mkdirSync(join(dir, "purpose/ideas"), { recursive: true });
-copyFileSync(dumpFile, join(dir, DUMP));
+mkdirSync(join(ventureFile(dir, "purpose/ideas")), { recursive: true });
+copyFileSync(dumpFile, ventureFile(dir, DUMP));
 prov(dir, { entity: DUMP, route: "purpose/idea-dump", activity: "create", agent: agentFromEnv("person", "harness", { id: founder }), note: "the founder's idea dump, verbatim" });
 lap(`venture ${id} scaffolded in ${ws}; idea dump saved (${readFileSync(dumpFile, "utf8").length} characters)`);
 
@@ -83,8 +84,8 @@ if (opt("money")) {
   const m = opt("money");
   const src = m === "live" ? ["--live"] : m === "sandbox" ? [] : ["--fixture", resolve(m)];
   const p = spawnSync("node", [join(repo, "platform/integrations/rho.mjs"), "sync", "--venture", dir, ...src], { encoding: "utf8" });
-  if (p.status === 0 && existsSync(join(dir, "money/_summary.json"))) {
-    money = JSON.parse(readFileSync(join(dir, "money/_summary.json"), "utf8"));
+  if (p.status === 0 && existsSync(join(ventureFile(dir, "money/_summary.json")))) {
+    money = JSON.parse(readFileSync(join(ventureFile(dir, "money/_summary.json")), "utf8"));
     prov(dir, { entity: "money/_summary.json", route: "money/_summary", activity: "create", agent: agentFromEnv("agent", "harness", { id: "naive-money" }), note: `synced from ${money.source}; ${money.transactions} transactions kept as pointers in a sensitive stream` });
     lap(`money synced from ${money.source}${money.business ? ` (${money.business})` : ""}: cash ${(money.cash.amount / 100).toFixed(2)} ${money.cash.currency}, monthly net ${(money.monthly_net.amount / 100).toFixed(2)}, runway ${money.runway_months ?? "not limited by burn"}, as of ${money.as_of}`);
   } else console.log(`   money sync failed, so the run goes on without it: ${(p.stderr || p.stdout).trim().slice(0, 300)}`);
@@ -100,7 +101,7 @@ if (flag("board")) { process.env.MENTURA_WORKSPACE = ws; board = (await import("
 
 // The trace (EE-058): every step and every tool call the agent made, with timings, for LangSmith.
 const iso = () => new Date().toISOString();
-const trace = { name: `naive discovery: ${id}`, run_type: "chain", start: iso(), inputs: { dump: DUMP, ideas: readFileSync(join(dir, DUMP), "utf8"), founder, phase }, children: [], metadata: {
+const trace = { name: `naive discovery: ${id}`, run_type: "chain", start: iso(), inputs: { dump: DUMP, ideas: readFileSync(ventureFile(dir, DUMP), "utf8"), founder, phase }, children: [], metadata: {
   venture: id, venture_id: id, pipeline_step: phase, money: money?.source ?? null,
   // LangSmith groups a founder's runs into one thread by thread_id: one session per venture per day.
   thread_id: process.env.NAIVE_SESSION ?? `${id}-${new Date().toISOString().slice(0, 10)}`,
@@ -155,11 +156,11 @@ async function agent(prompt, label, { tools = "mcp__naive__*,mcp__research__*",
 // The run's evals and trace: written beside the workspace, and sent to LangSmith when a key is set.
 function finish(code = 0) {
   trace.end = iso();
-  const evals = existsSync(join(dir, DUMP)) ? evaluate(dir, { researched, settled }) : [];
+  const evals = existsSync(ventureFile(dir, DUMP)) ? evaluate(dir, { researched, settled }) : [];
   trace.feedback = evals;
   // What the run drafted, so a judge reading only the root run (LangSmith's online evaluators, Jev)
   // sees the problem record and the agent's reports beside the founder's dump in the inputs.
-  const problem = join(dir, "purpose/validation/problem.json");
+  const problem = join(ventureFile(dir, "purpose/validation/problem.json"));
   const drafted = { problem: existsSync(problem) ? JSON.parse(readFileSync(problem, "utf8")) : null, reports: trace.children.filter((c) => c.outputs?.report).map((c) => ({ pass: c.name, report: c.outputs.report })) };
   trace.outputs = { settled, docket: { steps: docketSteps, now: compact(docket(dir)) }, drafted, evals: Object.fromEntries(evals.map((e) => [e.key, e.score])), laps };
   writeFileSync(join(ws, "trace.json"), JSON.stringify(trace, null, 2) + "\n");
@@ -180,7 +181,7 @@ const compact = (k) => ({ leading: k.functions[0]?.function ?? null, functions:
 
 // 1. The idea map: Jev tags each idea with Naive's conventions; without Jev, the agent does, with the
 //    same vocabulary. Either way the ideas stay verbatim and unknown tags are dropped.
-const ideas = split(readFileSync(join(dir, DUMP), "utf8"));
+const ideas = split(readFileSync(ventureFile(dir, DUMP), "utf8"));
 const venture = JSON.parse(readFileSync(join(dir, "venture.json"), "utf8"));
 let tags, tagger;
 const mapNode = { name: "idea map", run_type: "tool", start: iso(), inputs: { ideas: ideas.length }, children: [] };
@@ -200,24 +201,24 @@ Ideas: ${JSON.stringify(Object.fromEntries(ideas.map((i) => [i.id, i.section ? `
   tags = JSON.parse(text.slice(text.indexOf("{"), text.lastIndexOf("}") + 1));
   tagger = "claude-code";
 }
-writeFileSync(join(dir, MAP), render(ideas, clean(tags), { venture: id, tagger }));
+writeFileSync(ventureFile(dir, MAP), render(ideas, clean(tags), { venture: id, tagger }));
 prov(dir, { entity: MAP, route: "purpose/idea-map", activity: "create", derived_from: [DUMP], agent: agentFromEnv("agent", "harness", { id: tagger }), note: `${ideas.length} ideas tagged with Naive's conventions` });
-const sum = summary(parse(readFileSync(join(dir, MAP), "utf8")), phase);
+const sum = summary(parse(readFileSync(ventureFile(dir, MAP), "utf8")), phase);
 trace.children.push(Object.assign(mapNode, { end: iso(), outputs: { tagger, summary: sum }, metadata: { tagger } }));
 lap(`idea map: ${sum.ideas} ideas; ${Object.entries(sum.by_pillar).map(([k, v]) => `${k} ${v}`).join(", ")}; clusters ${sum.strengths.map((s) => s.department).join(", ")}; ${sum.product.reading}`);
 
 // 1b. The idea graph: the map's structured form. Jev judges which ideas build on which; without Jev,
 //     Naive's record order does. Signal, lanes and layout follow in code.
 const graphNode = { name: "idea graph", run_type: "tool", start: iso(), inputs: { ideas: ideas.length }, children: [] };
-const mapIdeas = parse(readFileSync(join(dir, MAP), "utf8")).ideas;
+const mapIdeas = parse(readFileSync(ventureFile(dir, MAP), "utf8")).ideas;
 let graphAnswers = null;
 if (jev) {
   const p = spawnSync("node", [join(repo, "platform/integrations/jev.mjs")], { input: JSON.stringify(graphRequest(mapIdeas, venture)), encoding: "utf8", maxBuffer: 1 << 26 });
   if (p.status === 0) { const out = JSON.parse(p.stdout); graphAnswers = out.answers; console.log(`   Jev answered ${Object.keys(out.answers).length} dependency and concreteness questions in ${out.ms} ms`); }
   else console.log(`   Jev could not judge the dependencies (${p.stderr.trim().slice(0, 200)}); using Naive's record order`);
 }
-const g = buildGraph(mapIdeas, { answers: graphAnswers, phase, venture: id, source: `${MAP}@${createHash("sha256").update(readFileSync(join(dir, MAP))).digest("hex").slice(0, 16)}` });
-writeFileSync(join(dir, GRAPH), JSON.stringify(g, null, 2) + "\n");
+const g = buildGraph(mapIdeas, { answers: graphAnswers, phase, venture: id, source: `${MAP}@${createHash("sha256").update(readFileSync(ventureFile(dir, MAP))).digest("hex").slice(0, 16)}` });
+writeFileSync(ventureFile(dir, GRAPH), JSON.stringify(g, null, 2) + "\n");
 prov(dir, { entity: GRAPH, route: "purpose/idea-graph", activity: "create", derived_from: [MAP], agent: agentFromEnv("agent", "harness", { id: g.judged_by }), note: `Merkle root ${g.root}` });
 trace.children.push(Object.assign(graphNode, { end: iso(), outputs: { root: g.root, edges: g.edges.length, lanes: g.lanes.map((l) => ({ mode: l.mode, ideas: l.ideas.length })), next: g.next } }));
 lap(`idea graph: ${g.edges.length} dependencies (${g.judged_by}); ${g.lanes.filter((l) => l.mode === "sync").length} lane(s) in order, ${g.lanes.filter((l) => l.mode === "async").length} on their own; develop next: ${g.next.join(", ")}; root ${g.root}`);

package/interface/instrumentation.mjs

@@ -17,6 +17,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { ventureFile } from "../schema/venture-paths.mjs";
 
 export const EVENTS = ".naive/events.jsonl";
 const listeners = new Set();
@@ -29,7 +30,7 @@ export const tokens = (x) => Math.ceil((x === undefined ? 0 : typeof x === "stri
 export function register(fn) { listeners.add(fn); return () => listeners.delete(fn); }
 
 const configOf = (dir) => {
-  const f = dir && join(dir, "naive.config.json");
+  const f = dir && join(ventureFile(dir, "naive.config.json"));
   if (!f || !existsSync(f)) return {};
   try { return JSON.parse(readFileSync(f, "utf8")); } catch { return {}; }
 };
@@ -48,14 +49,14 @@ export function emit(dir, event) {
   for (const k of Object.keys(e)) if (e[k] === undefined) delete e[k];
   for (const fn of listeners) { try { fn(e, dir); } catch {} }
   if (dir && enabled(dir)) {
-    try { mkdirSync(join(dir, ".naive"), { recursive: true }); appendFileSync(join(dir, EVENTS), JSON.stringify(e) + "\n"); } catch {}
+    try { mkdirSync(join(dir, ".naive"), { recursive: true }); appendFileSync(ventureFile(dir, EVENTS), JSON.stringify(e) + "\n"); } catch {}
   }
   return e;
 }
 
 /** The venture's events, oldest first. */
 export function events(dir) {
-  const f = join(dir, EVENTS);
+  const f = ventureFile(dir, EVENTS);
   if (!existsSync(f)) return [];
   return readFileSync(f, "utf8").split("\n").filter((l) => l.trim()).flatMap((l) => { try { return [JSON.parse(l)]; } catch { return []; } });
 }

package/interface/package-routes.mjs

@@ -19,6 +19,7 @@
 
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
+import { ventureFile } from "../schema/venture-paths.mjs";
 
 const repo = new URL("..", import.meta.url).pathname;
 const load = (f) => JSON.parse(readFileSync(f, "utf8"));
@@ -33,7 +34,7 @@ export const packageDef = (n) => load(join(repo, "packages", n, "package.json"))
 
 /** The venture's route groups: the framework's, then its own from naive.config.json. */
 export function groupsOf(dir) {
-  const f = dir && join(dir, "naive.config.json");
+  const f = dir && join(ventureFile(dir, "naive.config.json"));
   const own = f && existsSync(f) ? load(f).groups ?? {} : {};
   return { ...GROUPS, ...own };
 }
@@ -78,7 +79,7 @@ export const routeOfType = async (type) => {
 async function pendingIn(dir, types, venture) {
   const { recordOf } = await import("../schema/decisions.mjs");
   const { entries } = await import("./provenance.mjs");
-  const d = join(dir, "_drafts");
+  const d = join(ventureFile(dir, "_drafts"));
   if (!existsSync(d)) return [];
   const log = entries(dir);
   const out = [];
@@ -179,7 +180,7 @@ export async function specialCall({ venture, route, action, workspace }) {
     const g = gs[sp.id];
     if (!g) return { ok: false, error: `no route group (${sp.id}): the groups are ${Object.keys(gs).map((x) => `(${x})`).join(", ")}` };
     const lay = groupLayout(g.packages[0], dir);
-    if (action === "layout" || !dir) return { ok: true, result: { ...lay, chain: lay.agents && dir ? [{ path: lay.agents, text: readFileSync(join(dir, lay.agents), "utf8") }] : [] } };
+    if (action === "layout" || !dir) return { ok: true, result: { ...lay, chain: lay.agents && dir ? [{ path: lay.agents, text: readFileSync(ventureFile(dir, lay.agents), "utf8") }] : [] } };
     const states = [];
     for (const n of g.packages.filter((x) => packageNames().includes(x))) states.push(await packageState(dir, n, venture));
     const res = { group: `(${sp.id})`, context: g.context ?? null, packages: states.map((s) => ({ package: s.package, state: s.state, progress: s.progress ?? null, pending: s.loading?.drafts.length ?? 0 })) };

package/interface/provenance.mjs

@@ -9,6 +9,7 @@ import { spawnSync } from "node:child_process";
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { emit } from "./instrumentation.mjs";
+import { ventureFile } from "../schema/venture-paths.mjs";
 
 export const LOG = "provenance.jsonl";
 const sha = (s) => createHash("sha256").update(s).digest("hex");
@@ -17,7 +18,7 @@ export const lineHash = (prev, entry) => { const { hash, ...rest } = entry; retu
 export const contentHash = (file) => sha(readFileSync(file));
 
 export function entries(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)) : [];
 }
 
@@ -37,9 +38,9 @@ export function record(dir, { entity, route, activity, agent, derived_from, deci
   const prior = entries(dir);
   const prev = prior.length ? prior.at(-1).hash : "genesis";
   const entry = Object.fromEntries(Object.entries({ at: new Date().toISOString(), entity, route, activity, agent,
-    derived_from: derived_from?.length ? derived_from : undefined, decision, note, source, statement, sha256: sha256 ?? contentHash(join(dir, entity)), prev }).filter(([, v]) => v !== undefined));
+    derived_from: derived_from?.length ? derived_from : undefined, decision, note, source, statement, sha256: sha256 ?? contentHash(ventureFile(dir, entity)), prev }).filter(([, v]) => v !== undefined));
   entry.hash = lineHash(prev, entry);
-  appendFileSync(join(dir, LOG), JSON.stringify(entry) + "\n");
+  appendFileSync(ventureFile(dir, LOG), JSON.stringify(entry) + "\n");
   // Context hook: every provenance entry (write, draft, accept, confirm, decision) is an instrumentation event (P-4).
   emit(dir, { kind: "provenance", activity: entry.activity, entity: entry.entity, route: entry.route, decision: entry.decision, by: entry.agent?.kind, via: entry.agent?.via });
   fireTriggers(dir);
@@ -52,7 +53,7 @@ export function record(dir, { entity, route, activity, agent, derived_from, deci
 function fireTriggers(dir) {
   if (process.env.NAIVE_TRIGGERS_ACTIVE) return;
   let cfg;
-  try { cfg = JSON.parse(readFileSync(join(dir, "naive.config.json"), "utf8")); } catch { return; }
+  try { cfg = JSON.parse(readFileSync(join(ventureFile(dir, "naive.config.json")), "utf8")); } catch { return; }
   if (!cfg?.triggers?.length && !cfg?.kits?.length) return;
   // The write has landed; nothing here may undo it or throw past it.
   try {

package/interface/reads.mjs

@@ -23,6 +23,7 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { entries } from "./provenance.mjs";
+import { ventureFile } from "../schema/venture-paths.mjs";
 
 const load = (f) => JSON.parse(readFileSync(f, "utf8"));
 const get = (o, p) => p.split(".").reduce((x, k) => (x == null ? undefined : x[k]), o);
@@ -45,7 +46,7 @@ export function frontmatter(text) {
 /** A record's state from the log and the drafts folder (O-2). */
 export async function stateOf(dir, file) {
   const { confirmedIn } = await import("../schema/foundation.mjs");
-  if (existsSync(join(dir, "_drafts", `${file.replace(/\//g, "__")}.draft`))) return "draft";
+  if (existsSync(join(ventureFile(dir, "_drafts"), `${file.replace(/\//g, "__")}.draft`))) return "draft";
   const es = entries(dir).filter((e) => e.entity === file);
   if (!es.length) return "unlogged";
   return confirmedIn(dir, file, null) ? "confirmed" : "agent";
@@ -58,7 +59,7 @@ export function defaults(dir, file, id) {
     const last = es.at(-1);
     return { id, created: es[0].at, updated: last.at, by: { kind: last.agent?.kind ?? null, ...(last.agent?.id ? { id: last.agent.id } : {}), via: last.agent?.via ?? null }, activity: last.activity, writes: es.length, from: "provenance" };
   }
-  const st = existsSync(join(dir, file)) ? statSync(join(dir, file)) : null;
+  const st = existsSync(ventureFile(dir, file)) ? statSync(ventureFile(dir, file)) : null;
   return { id, created: st ? new Date(st.birthtimeMs || st.mtimeMs).toISOString() : null, updated: st ? st.mtime.toISOString() : null, by: null, writes: 0, from: "file", note: "written outside the router: mentura baseline adopts it into the log" };
 }
 
@@ -138,7 +139,7 @@ const parseInstructions = (chain) => {
 export function withParams(layout, { dir, params, file, group }) {
   const chain = [...(layout.chain ?? [])];
   const have = new Set(chain.map((c) => c.path));
-  const add = (rel, at = chain.length) => { if (dir && !have.has(rel) && existsSync(join(dir, rel))) { chain.splice(at, 0, { path: rel, text: readFileSync(join(dir, rel), "utf8") }); have.add(rel); } };
+  const add = (rel, at = chain.length) => { if (dir && !have.has(rel) && existsSync(ventureFile(dir, rel))) { chain.splice(at, 0, { path: rel, text: readFileSync(ventureFile(dir, rel), "utf8") }); have.add(rel); } };
   if (group?.agents) add(group.agents, chain.findIndex((c) => c.path === "AGENTS.md") + 1);
   if (file) {
     const parts = dirname(file).split("/").filter((p) => p && p !== ".");

package/interface/release-card.mjs

@@ -8,6 +8,7 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { ventureFile } from "../schema/venture-paths.mjs";
 
 const esc = (s) => String(s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 const day = (t) => (t ? String(t).slice(0, 10) : "");
@@ -36,7 +37,7 @@ export function svg(card) {
 
 if (import.meta.url === `file://${process.argv[1]}`) {
   const dir = process.argv[2];
-  const f = dir && join(dir, ".release/card.json");
+  const f = dir && join(ventureFile(dir, ".release/card.json"));
   if (!f || !existsSync(f)) { console.error("usage: node interface/release-card.mjs <venture dir> (after node schema/build-release.mjs)"); process.exit(2); }
   process.stdout.write(svg(JSON.parse(readFileSync(f, "utf8"))));
 }

package/interface/router.mjs

@@ -65,6 +65,7 @@ import { routable } from "../schema/structure.mjs";
 import { BRAND_ROUTES, brandCommands, brandLayout } from "../schema/brand.mjs";
 // Upgrades hook (V-9): a read says when what the record reads changed in its system of record.
 import { staleOf } from "../schema/stale.mjs";
+import { ventureFile } from "../schema/venture-paths.mjs";
 
 export const repo = new URL("..", import.meta.url).pathname;
 const load = (p) => JSON.parse(readFileSync(p, "utf8"));
@@ -223,7 +224,7 @@ export function ventures(workspace = defaultWorkspace()) {
 function decisionRights(dir) {
   const t = load(join(repo, "governance/venture-template/decision-rights.json"));
   const classes = new Map(t.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, level: classes.get(c.id)?.level === "escalate" ? "escalate" : c.level });
   return classes;
 }
@@ -239,7 +240,7 @@ export function gateOf(r, dir) {
 // Robots: a team-plan role may list the routes it may read and write (globs over routes).
 export function allowed(dir, actorId, action, route) {
   if (!actorId || !dir) return true;
-  const plan = [join(dir, "people/team-plan.json"), join(dir, "operations/team-plan.json")].find((p) => existsSync(p));
+  const plan = [join(ventureFile(dir, "people/team-plan.json")), join(ventureFile(dir, "operations/team-plan.json"))].find((p) => existsSync(p));
   if (!plan) return true;
   const role = load(plan).roles.find((x) => x.id === actorId);
   if (!role?.routes) return true;
@@ -264,11 +265,11 @@ const PACKAGE_ROUTE = {
 const fileFor = (r, params, dir) => {
   const cands = (r.collection === "item" ? r.files.map((f) => f.replace("*", params.id)) : r.files).filter((f) => !f.includes("*"));
   if (dir) {
-    const hit = cands.find((f) => existsSync(join(dir, f)));
+    const hit = cands.find((f) => existsSync(ventureFile(dir, f)));
     if (hit) return hit;
     // A new collection item joins the folder the venture already keeps that collection in.
     if (r.collection === "item") {
-      const lived = cands.find((f) => { const d = join(dir, dirname(f)); return existsSync(d) && readdirSync(d).some((n) => n.endsWith(".json") || n.endsWith(".md") || n.endsWith(".mdx")); });
+      const lived = cands.find((f) => { const d = ventureFile(dir, dirname(f)); return existsSync(d) && readdirSync(d).some((n) => n.endsWith(".json") || n.endsWith(".md") || n.endsWith(".mdx")); });
       if (lived) return lived;
     }
   }
@@ -289,7 +290,7 @@ export function draftOf(route, venture, workspace) {
 function agentsChain(dir, route) {
   if (!dir) return [];
   const chain = [];
-  const add = (rel) => { const f = join(dir, rel); if (existsSync(f)) chain.push({ path: rel, text: readFileSync(f, "utf8") }); };
+  const add = (rel) => { const f = ventureFile(dir, rel); if (existsSync(f)) chain.push({ path: rel, text: readFileSync(f, "utf8") }); };
   add("AGENTS.md");
   const parts = route.split("/").filter(Boolean);
   let acc = "";
@@ -392,7 +393,7 @@ async function callInAction({ venture, route, action, input, actor = "agent", ac
     if (r.internal === "robots") return { ok: true, result: robots(dir), ...deprecated };
     // Caching hook: system/cache, system/judge and system/answer are handled in schema/caching.mjs.
     if (["cache", "judge", "answer"].includes(r.internal)) return { ...(await cacheInternal(r.internal, { dir, venture, workspace, input, actor, actor_id, via, provenance }, { call, resolve, draftOf })), ...deprecated };
-    const lacking = (r.needs ?? []).filter((f) => !existsSync(join(dir, f)));
+    const lacking = (r.needs ?? []).filter((f) => !existsSync(ventureFile(dir, f)));
     if (lacking.length) return { ok: false, error: `${route} needs ${lacking.join(", ")} in ${venture}`, fix: { missing: lacking } };
     if (r.value_flag && !input?.value) return { ok: false, error: `${route} needs a value (${r.note})` };
     const args = r.venture_arg === "id" ? [dir, ...(input?.value ? [String(input.value)] : []), "--json"] : r.value_flag ? [dir, r.value_flag, String(input.value), "--json"] : [dir, ...(r.args ?? []), ...(r.as_is && input?.as_is ? ["--as-is"] : []), "--json"];
@@ -430,7 +431,7 @@ async function callInAction({ venture, route, action, input, actor = "agent", ac
       if (r.collection === "list" && actor_id) items = items.filter((x) => mayReadItem(dir, actor_id, route, itemId(r.files, x.path)));
     } catch (e) { return { ok: false, error: `${src.id}: ${String(e.message ?? e)}` }; }
     const found = items.map((x) => x.path);
-    const draft = !remote && r.collection !== "list" && fileFor(r, params, dir) && existsSync(join(dir, draftPath(fileFor(r, params, dir)))) ? draftPath(fileFor(r, params, dir)) : null;
+    const draft = !remote && r.collection !== "list" && fileFor(r, params, dir) && existsSync(ventureFile(dir, draftPath(fileFor(r, params, dir)))) ? draftPath(fileFor(r, params, dir)) : null;
     const loading = draft ? { pending_draft: { file: draft, since: provEntries(dir).filter((e) => e.entity === draft).at(-1)?.at ?? null, accept: `mentura accept ${route} --venture ${venture}` } } : {};
     if (remote) {
       const prs = provEntries(dir).filter((e) => e.source?.pull_request && found.concat(patterns).some((f) => e.entity === address(src.id, f)));
@@ -493,7 +494,7 @@ async function callInAction({ venture, route, action, input, actor = "agent", ac
     if (!input || typeof input !== "object") return { ok: false, error: "write needs the record as input" };
     if (r.collection === "item" && !/^[a-z0-9][a-z0-9-]*$/.test(params.id)) return { ok: false, error: `${params.id} is not a valid id (lowercase letters, digits and hyphens)` };
     const file = fileFor(r, params, dir);
-    if (["idea-dump", "raw-source", "raw-text"].includes(r.record) && existsSync(join(dir, file))) return { ok: false, error: `${route} is raw and immutable: add a new capture, do not edit this one` };
+    if (["idea-dump", "raw-source", "raw-text"].includes(r.record) && existsSync(ventureFile(dir, file))) return { ok: false, error: `${route} is raw and immutable: add a new capture, do not edit this one` };
     const gate = gateOf(r, dir);
     const text = JSON.stringify(input, null, 2) + "\n";
     // The schema first, on a scratch copy, so nothing reaches any source unless it matches.
@@ -619,7 +620,7 @@ async function overview(venture, workspace) {
 
 // Robots: per role, the routes it may read and write.
 function robots(dir) {
-  const plan = [join(dir, "people/team-plan.json"), join(dir, "operations/team-plan.json")].find((p) => existsSync(p));
+  const plan = [join(ventureFile(dir, "people/team-plan.json")), join(ventureFile(dir, "operations/team-plan.json"))].find((p) => existsSync(p));
   if (!plan) return { note: "no team plan: every actor may reach every route; gates still apply", roles: [] };
   return { note: "a role without routes may reach every route; gates still apply", roles: load(plan).roles.map((r) => ({ role: r.id, occupant: r.occupant, read: (r.routes?.read ?? ["**"]).join(", "), write: (r.routes?.write ?? (r.routes ? [] : ["**"])).join(", ") || "none" })) };
 }

package/interface/vitals.mjs

@@ -21,6 +21,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { events } from "./instrumentation.mjs";
 import { entries } from "./provenance.mjs";
+import { ventureFile } from "../schema/venture-paths.mjs";
 
 export const THRESHOLDS = { calls_per_task: 25, tokens_per_call: 6000, time_to_useful_ms: 10000, decision_hours: 72 };
 const DECISION = /(^|\/)decisions\/[^/]+\.decision\.json$/;
@@ -28,7 +29,7 @@ const DECISION = /(^|\/)decisions\/[^/]+\.decision\.json$/;
 /** The 75th percentile, nearest rank. */
 export const p75 = (xs) => { if (!xs.length) return null; const s = [...xs].sort((a, b) => a - b); return s[Math.ceil(0.75 * s.length) - 1]; };
 const startOf = (e) => Date.parse(e.at) - (e.ms ?? 0);
-const config = (dir) => { const f = join(dir, "naive.config.json"); try { return existsSync(f) ? JSON.parse(readFileSync(f, "utf8")) : {}; } catch { return {}; } };
+const config = (dir) => { const f = join(ventureFile(dir, "naive.config.json")); try { return existsSync(f) ? JSON.parse(readFileSync(f, "utf8")) : {}; } catch { return {}; } };
 
 /** Top-level calls grouped by session: one task per session. */
 export function tasks(dir) {
@@ -55,7 +56,7 @@ export function decisionLatency(dir, now = Date.now()) {
   }
   return [...by.values()].map((d) => {
     let id = d.file.split("/").at(-1).replace(/\.decision\.json$/, "");
-    try { id = JSON.parse(readFileSync(join(dir, d.file), "utf8")).id ?? id; } catch {}
+    try { id = JSON.parse(readFileSync(ventureFile(dir, d.file), "utf8")).id ?? id; } catch {}
     const end = d.decided ? Date.parse(d.decided) : now;
     return { id, ...d, open: !d.decided, hours: Math.round(((end - Date.parse(d.opened)) / 36e5) * 100) / 100 };
   });

package/knowledge/connectors/catalog.mjs

@@ -15,6 +15,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { address, isText, words } from "./contract.mjs";
 import { connectAll } from "./index.mjs";
+import { ventureFile } from "../../schema/venture-paths.mjs";
 
 export const FILE = "_catalog/catalog.json";
 const MAX_BYTES = 1_000_000;
@@ -50,7 +51,7 @@ async function routeOf(path) {
   return { route: null, record: null };
 }
 
-export const load = (dir) => existsSync(join(dir, FILE)) ? JSON.parse(readFileSync(join(dir, FILE), "utf8")) : null;
+export const load = (dir) => existsSync(ventureFile(dir, FILE)) ? JSON.parse(readFileSync(ventureFile(dir, FILE), "utf8")) : null;
 
 /** Builds or refreshes the catalog. Returns it with stats: items, read (items fetched), reused. */
 export async function build(dir, { write = true, sources } = {}) {
@@ -75,7 +76,7 @@ export async function build(dir, { write = true, sources } = {}) {
   }
   stats.items = items.length;
   const catalog = { built_at: new Date().toISOString(), sources: conns.map(({ source }) => ({ id: source.id, connector: source.connector })), items };
-  if (write) { mkdirSync(join(dir, "_catalog"), { recursive: true }); writeFileSync(join(dir, FILE), JSON.stringify(catalog) + "\n"); }
+  if (write) { mkdirSync(join(dir, "_catalog"), { recursive: true }); writeFileSync(ventureFile(dir, FILE), JSON.stringify(catalog) + "\n"); }
   return { catalog, stats };
 }
 

package/knowledge/connectors/filesystem.mjs

@@ -13,6 +13,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { blobSha, isText, matches, safePath } from "./contract.mjs";
+import { layoutOf, logicalFiles, ventureFile } from "../../schema/venture-paths.mjs";
 
 const SKIP = new Set(["node_modules"]);
 
@@ -29,7 +30,11 @@ export function connect({ id = "venture", root, writes = "direct", venture = fal
     }
     return e.isFile() ? [r] : [];
   });
-  const file = (p) => join(root, safePath(p));
+  // A venture in the structured layout (EE-086) keeps its records in knowledge/ and meta/: read and write them
+  // by their logical paths, and list them that way, so routes never see the layout.
+  const structured = venture && layoutOf(root) === "structured";
+  const file = (p) => (structured ? ventureFile(root, safePath(p)) : join(root, safePath(p)));
+  const listed = () => structured ? logicalFiles(root).filter((r) => !r.split("/").some((s) => s.startsWith(".")) && !r.startsWith("_") && !r.startsWith("node_modules/")) : walk(root);
   const git = (...args) => spawnSync("git", ["-C", root, ...args], { encoding: "utf8" });
   const lastCommit = (p, content) => {
     const tracked = git("ls-files", "-s", "--", p);
@@ -42,8 +47,8 @@ export function connect({ id = "venture", root, writes = "direct", venture = fal
     id, kind: "filesystem", writes, root,
     async list(prefix = "") {
       const pre = prefix ? safePath(prefix) : "";
-      return walk(root).filter((p) => !pre || p === pre || p.startsWith(`${pre}/`)).sort()
-        .map((path) => ({ path, version: blobSha(readFileSync(join(root, path))) }));
+      return listed().filter((p) => !pre || p === pre || p.startsWith(`${pre}/`)).sort()
+        .map((path) => ({ path, version: blobSha(readFileSync(file(path))) }));
     },
     async read(p) {
       const f = file(p);
@@ -58,9 +63,9 @@ export function connect({ id = "venture", root, writes = "direct", venture = fal
     },
     async search(query, { limit = 50 } = {}) {
       const out = [];
-      for (const path of walk(root).sort()) {
+      for (const path of listed().sort()) {
         if (out.length >= limit) break;
-        const content = readFileSync(join(root, path), "utf8");
+        const content = readFileSync(file(path), "utf8");
         if (isText(path, content) && matches(`${path}\n${content}`, query)) out.push({ path, version: blobSha(content) });
       }
       return out;

package/knowledge/connectors/index.mjs

@@ -17,6 +17,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
 import { conformance } from "./contract.mjs";
 import { ANY, resolve as resolveRule } from "./resolve.mjs";
+import { ventureFile } from "../../schema/venture-paths.mjs";
 
 const repo = new URL("../..", import.meta.url).pathname;
 const load = (p) => JSON.parse(readFileSync(p, "utf8"));
@@ -34,8 +35,8 @@ export function registry() {
 
 /** A venture's source map, with the implicit venture source first. */
 export function sourcesOf(dir) {
-  const own = existsSync(join(dir, MAP)) ? load(join(dir, MAP)) : { sources: [], records: {} };
-  return { sources: [{ id: LOCAL, connector: "filesystem", root: ".", writes: "direct", implicit: true }, ...(own.sources ?? [])], records: own.records ?? {}, rules: own.rules ?? [], mapped: existsSync(join(dir, MAP)) };
+  const own = existsSync(ventureFile(dir, MAP)) ? load(ventureFile(dir, MAP)) : { sources: [], records: {} };
+  return { sources: [{ id: LOCAL, connector: "filesystem", root: ".", writes: "direct", implicit: true }, ...(own.sources ?? [])], records: own.records ?? {}, rules: own.rules ?? [], mapped: existsSync(ventureFile(dir, MAP)) };
 }
 
 /**

package/operations/marketing/check-public.mjs

@@ -10,6 +10,7 @@
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
+import { ventureFile } from "../../schema/venture-paths.mjs";
 
 export const CONTENT = "operations/marketing/content";
 const RUN = 10;
@@ -27,24 +28,24 @@ export function frontmatter(text) {
 
 function files(dir) {
   if (!existsSync(dir)) return [];
-  return readdirSync(dir).flatMap((f) => statSync(join(dir, f)).isDirectory() ? files(join(dir, f)) : f.endsWith(".mdx") ? [join(dir, f)] : []);
+  return readdirSync(dir).flatMap((f) => statSync(ventureFile(dir, f)).isDirectory() ? files(ventureFile(dir, f)) : f.endsWith(".mdx") ? [ventureFile(dir, f)] : []);
 }
 
 export function check(dir) {
   const venture = existsSync(join(dir, "venture.json")) ? JSON.parse(readFileSync(join(dir, "venture.json"), "utf8")) : {};
   const publicText = [venture.name, venture.brand?.tagline].filter(Boolean);
-  const pdir = join(dir, "products");
+  const pdir = join(ventureFile(dir, "products"));
   if (existsSync(pdir)) for (const f of readdirSync(pdir).filter((f) => f.endsWith(".json"))) publicText.push(JSON.parse(readFileSync(join(pdir, f), "utf8")).name ?? "");
   const allowed = new Set(publicText.flatMap((t) => [...runs(t)]));
-  const results = files(join(dir, CONTENT)).map((f) => {
+  const results = files(ventureFile(dir, CONTENT)).map((f) => {
     const rel = relative(dir, f), { meta, body } = frontmatter(readFileSync(f, "utf8")), errors = [];
     if (!meta.variant_of) errors.push("names no internal record (variant_of): marketing content is a variant of an internal record");
-    else if (!existsSync(join(dir, meta.variant_of))) errors.push(`variant_of ${meta.variant_of} does not exist`);
+    else if (!existsSync(ventureFile(dir, meta.variant_of))) errors.push(`variant_of ${meta.variant_of} does not exist`);
     if (!meta.audience) errors.push("names no audience");
     if (meta.publish === undefined) errors.push("does not say whether it is published (publish: true or false)");
     if (meta.publish === true && !meta.approved_by) errors.push("is published without a person's approval (approved_by, EE-025)");
-    if (meta.variant_of && existsSync(join(dir, meta.variant_of))) {
-      const src = join(dir, meta.variant_of);
+    if (meta.variant_of && existsSync(ventureFile(dir, meta.variant_of))) {
+      const src = ventureFile(dir, meta.variant_of);
       const raw = readFileSync(src, "utf8");
       const internal = new Set(strings(src.endsWith(".json") ? JSON.parse(raw) : raw).flatMap((s) => [...runs(s)]));
       const leaks = [...runs(body)].filter((r) => internal.has(r) && !allowed.has(r));

package/operations/marketing/site/plan.mjs

@@ -19,6 +19,7 @@
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { customerNeeds, factsOf, MATRIX, needs, typesOf, weights } from "./presence.mjs";
+import { ventureFile } from "../../../schema/venture-paths.mjs";
 
 const load = (p) => JSON.parse(readFileSync(p, "utf8"));
 export const SITEMAP = "operations/marketing/sitemap.json";
@@ -33,10 +34,10 @@ const RECORD_FILE = { venture: "venture.json", icp: "purpose/icp.json", "validat
 
 /** The offerings: each product, what kind of offering it is, whom it is offered to and whom it serves through them. */
 export function offeringsOf(dir) {
-  const icp = existsSync(join(dir, "purpose/icp.json")) ? load(join(dir, "purpose/icp.json")) : { profiles: [] };
+  const icp = existsSync(join(ventureFile(dir, "purpose/icp.json"))) ? load(join(ventureFile(dir, "purpose/icp.json"))) : { profiles: [] };
   const profiles = new Map(icp.profiles.map((p) => [p.id, p]));
   const primary = icp.profiles.find((p) => p.primary) ?? icp.profiles[0];
-  const pdir = join(dir, "products");
+  const pdir = join(ventureFile(dir, "products"));
   const products = existsSync(pdir) ? readdirSync(pdir).filter((f) => f.endsWith(".json")).map((f) => load(join(pdir, f))).filter((p) => !["retired", "archived", "idea"].includes(p.status)) : [];
   return { profiles, products: products.map((p) => {
     // Who it is offered to: the product says so; otherwise the profiles others are reached through
@@ -104,7 +105,7 @@ if (import.meta.url === `file://${process.argv[1]}`) {
   if (!dir || !existsSync(join(dir, "venture.json"))) { console.error("usage: node plan.mjs <venture> [--raising] [--hiring] [--contributors] [--write] [--json]"); process.exit(2); }
   const has = (n) => process.argv.includes(`--${n}`);
   const r = plan(dir, { flags: Object.fromEntries(["raising", "hiring", "contributors"].filter(has).map((k) => [k, true])) });
-  if (has("write")) { mkdirSync(join(dir, dirname(SITEMAP)), { recursive: true }); writeFileSync(join(dir, SITEMAP), JSON.stringify(r, null, 2) + "\n"); }
+  if (has("write")) { mkdirSync(join(dir, dirname(SITEMAP)), { recursive: true }); writeFileSync(ventureFile(dir, SITEMAP), JSON.stringify(r, null, 2) + "\n"); }
   if (has("json")) console.log(JSON.stringify(r, null, 2));
   else {
     console.log(`${r.name}: site planned for ${r.audience.offered_to.map((p) => p.id).join(", ") || "no ICP yet"} (${r.audience.types.map((t) => t.label).join(", ") || "customers in general"})${r.audience.partner_led ? "; partner-led" : ""}`);

package/operations/marketing/site/presence.mjs

@@ -22,6 +22,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { ventureFile } from "../../../schema/venture-paths.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const load = (p) => JSON.parse(readFileSync(p, "utf8"));
@@ -34,7 +35,7 @@ const r2 = (x) => Math.round(x * 100) / 100;
 /** The venture's facts: flags the founder gave, else what its ICP record says about who it courts. */
 export function factsOf(dir, flags = {}) {
   const f = { raising: false, hiring: false, contributors: false };
-  const icpFile = dir && join(dir, "purpose/icp.json");
+  const icpFile = dir && join(ventureFile(dir, "purpose/icp.json"));
   if (icpFile && existsSync(icpFile)) {
     const said = JSON.stringify(load(icpFile)).toLowerCase();
     if (/investor|angel|\bvc\b/.test(said)) f.raising = true;
@@ -57,7 +58,7 @@ export function icpOf(dir, site) {
   const who = ok.filter((p) => /customer|solution|who|industr|use-case|about|for-/i.test(p.path));
   const says = [...new Set([home, ...who].filter(Boolean).flatMap((p) => (p.text ?? "").match(SAYS) ?? []).map((x) => x.trim()))].slice(0, 8);
   const opening = (home?.text ?? "").slice(0, 500);
-  const icpFile = dir && join(dir, "purpose/icp.json");
+  const icpFile = dir && join(ventureFile(dir, "purpose/icp.json"));
   const stated = icpFile && existsSync(icpFile) ? (load(icpFile).profiles ?? []).map((p) => p.who ?? p.description ?? p.name).filter(Boolean) : null;
   return { text: [says.join(" | "), opening].filter(Boolean).join(" || "), source: says.length ? "site" : "inferred", says,
     cite: says.length ? `what the site says about who it is for (${says.length} phrase${says.length > 1 ? "s" : ""}), with the home page's opening` : "the home page's opening text (inferred: the site does not say outright who it is for)",
@@ -237,7 +238,7 @@ if (import.meta.url === `file://${process.argv[1]}`) {
     const answers = opt("answers") ? (load(opt("answers")).answers ?? load(opt("answers"))) : null;
     const facts = factsOf(dir, Object.fromEntries(["raising", "hiring", "contributors"].filter(has).map((k) => [k, true])));
     const r = score(site, { answers, facts, icp: icpOf(dir, site), venture: dir ? load(join(dir, "venture.json")).id : null });
-    if (dir) { mkdirSync(join(dir, dirname(PRESENCE)), { recursive: true }); writeFileSync(join(dir, PRESENCE), JSON.stringify(r, null, 2) + "\n"); }
+    if (dir) { mkdirSync(join(dir, dirname(PRESENCE)), { recursive: true }); writeFileSync(ventureFile(dir, PRESENCE), JSON.stringify(r, null, 2) + "\n"); }
     console.log(JSON.stringify(r, null, 2));
   } else if (a && existsSync(join(a, "venture.json"))) {
     if (!existsSync(join(a, PRESENCE))) { console.error(`${PRESENCE} does not exist yet: read the site first (node interface/harness/site.mjs <url> --venture <dir>)`); process.exit(1); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "naive-framework",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Naive, a venture development framework: conventions, routes, records, checks and an agent interface for building a venture.",
   "type": "module",
   "license": "MIT",

package/platform/integrations/rho.mjs

@@ -21,6 +21,7 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { ventureFile } from "../../schema/venture-paths.mjs";
 
 export const SANDBOX = "https://rhoapi-sandbox.rho.co/mcp/v1";
 export const LIVE = "https://rhoapi.rho.co/mcp/v1";
@@ -107,7 +108,7 @@ export function summarize(data, syncedAt) {
 const json = (f, v) => { mkdirSync(join(f, ".."), { recursive: true }); writeFileSync(f, `${JSON.stringify(v, null, 2)}\n`); };
 
 export function write(venture, data, syncedAt = new Date().toISOString()) {
-  const money = join(venture, "money");
+  const money = join(ventureFile(venture, "money"));
   const pointer = (kind, id) => `${data.source}:${kind}:${id}`;
   for (const a of data.accounts)
     json(join(money, `${a.id}.json`), { id: a.id, name: a.account_name, type: a.account_type, last_4: a.account_number_last_4 ?? null, balance: a.balance, source: pointer("account", a.id), synced_at: syncedAt });