naive-framework 0.2.0 → 0.4.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/layer.json

@@ -10,6 +10,10 @@
     {
       "id": "naive-setup",
       "path": "interface/skills/naive-setup/SKILL.md"
+    },
+    {
+      "id": "choosing-artifacts",
+      "path": "interface/skills/choosing-artifacts/SKILL.md"
     }
   ],
   "records": [

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/skills/choosing-artifacts/SKILL.md

@@ -0,0 +1,113 @@
+---
+type: knowledge
+tags: [everything-ecosystem, naive, skills, interface, artifacts, records, views]
+ai-model: claude-opus-5.5
+created: 2026-10-29T20:12:08Z
+source: hybrid
+name: choosing-artifacts
+description: >
+  Decide whether a venture action should build an artifact (a rendered view a
+  person reads, presents, shares or fills in) and which kind, and keep records,
+  the source of truth in k-base/, separate from artifacts, which are views built
+  from records and cite them. General for any agent, with a section for Claude's
+  own artifacts in Claude Code and claude.ai.
+  MANDATORY TRIGGERS: make an artifact, build a page, make a deck, make a
+  dashboard, pitch deck, investor update, show me, visualize, one-pager, which
+  artifact, should this be a doc, render this record.
+---
+
+# Choosing artifacts
+
+Interface layer. An artifact is a rendered view; a record is the source of truth. Build an artifact from records when a person needs to look at, present, share or fill in something. Never let the artifact become the record.
+
+## The core rule: records are not artifacts
+
+- A **record** is a file in the venture's `k-base/` with a schema. It is what agents read, what decisions cite and what `naive check` tests.
+- An **artifact** is a page, deck, dashboard or file made from one or more records for a reader. A marketing site describes the company, but the company's facts live in its records, not on the site.
+- Every artifact names the records it was built from (route and revision or date), so a reader can trace each claim.
+- When a record changes, rebuild the artifact. Never hand-edit an artifact to change a fact.
+- What people type into an artifact (a form, a docket, comments) is input. Write it back through the router as a proposal or a draft in `_drafts/`; a person settles it. The artifact's own stored state is never the source of truth.
+- Outside a Naive venture the same rule holds: name what the view was made from, and keep the facts where they already live.
+
+## Should this be an artifact at all?
+
+Answer in the conversation when the result is short, read once and acted on now. Build an artifact when any of these is true:
+
+1. Someone other than the requester will read or use it.
+2. It will be presented, printed, exported or sent.
+3. A person needs to fill it in, decide on it or come back to it.
+4. It is longer than about fifteen lines, or a picture explains it better than prose.
+
+If it belongs in the venture's code (a README, a spec that ships, code docs), write a file in `codebase/` instead.
+
+## Kinds of artifact
+
+| Kind | Use it for |
+|---|---|
+| Document | Writing people keep editing or pass around: memo, plan, spec, brief, report, notes |
+| Deck | Something to present or page through: pitch, investor update, demo-day talk |
+| Dashboard | Numbers people read: KPIs, runway, scorecards. Every number shows its source record |
+| Design | Visual work: landing pages, screens, mockups, ads, social posts |
+| Design system | The brand's tokens, type, components and assets, built from the brand record |
+| Page | Explainers, diagrams, interactive tools, trackers, forms |
+| File | Only when a format is named (.pptx, .docx, .xlsx, PDF) or an existing file is to be changed |
+
+## Decide in order
+
+1. Is it an artifact at all? (above)
+2. Did the person name a format? Use it.
+3. Writing to edit: document. To present: deck. Data to read: dashboard. A visual: design. A brand: design system.
+4. Otherwise a page. Add a diagram, charts or interactivity only when each earns its place.
+5. List the records it reads, and put that source list in the artifact.
+6. Read the records through Naive (`mentura_read`, or `naive` routes), never from memory. A record that is missing, a draft or stale is shown as such, never filled in.
+
+## Actions and their artifacts
+
+Each function's skills say which of its actions build which artifact. This is the starting map; it is a proposal until the founder confirms it in `naive.config.json` or the function's own skill.
+
+| Function | Action | Artifact | Built from |
+|---|---|---|---|
+| Foundation | Review the strategic foundation | Document (brief) | foundation/problem, foundation/icp, telos, the phase in venture.json |
+| Foundation | Decide pending decisions | Page that collects answers (the docket) | decisions/; answers go back as decisions a person settles |
+| Validation | Plan or report an experiment | Document | validation records and evidence/ |
+| Validation | Track evidence over time | Dashboard | evidence/ and metric records |
+| Validation | Run interviews | Page that collects answers (intake form) | the interview schema; answers become records |
+| Marketing | Draft a landing page or ad | Design | positioning and marketing/brand |
+| Marketing | Set up the brand | Design system | marketing/brand |
+| Marketing | Plan content | Document | positioning and calendar records |
+| Product | Write a spec or roadmap | Document | product/ and decisions/ |
+| Product | Show a flow or architecture | Page with a diagram | product/ |
+| Product | Prototype a screen | Design | product specs |
+| Money | Show runway, burn, revenue | Dashboard | money/ (from the bank or accounting source in sources.json) |
+| Money | Build a model or budget | File (.xlsx) when asked, else dashboard | money/ and finance/ |
+| Investors | Pitch or investor update | Deck | foundation/, evidence/ (traction) and money/ |
+| Any | Release notes for a release | Document | the release in meta/releases/ |
+
+## Checks before you publish
+
+- [ ] The artifact names its source records.
+- [ ] No fact appears that is missing from a record. If one is needed, write the record first (as a draft) or mark the claim as a proposal.
+- [ ] Agent-drafted content is marked as a proposal, never as the founder's words.
+- [ ] Input the artifact collects has a path back to records.
+- [ ] Nothing from `_private/`, no secrets, keys or `.env` contents.
+- [ ] Nothing imitates a real person or organization.
+
+## In Claude (Claude Code and claude.ai)
+
+Claude publishes artifacts with its `Artifact` tool. The kinds above map onto the artifact types on the person's account, which change, so always start a new artifact with `Artifact` `action: "quickstart"` and the fitting `intent`; it names the type to start from and the default design system.
+
+| Kind | Claude artifact type | Intent |
+|---|---|---|
+| Document | Docs (through the Claude Docs connector) | `document` |
+| Deck | Slides | `slides` |
+| Dashboard | Dashboard | `other` |
+| Design | Design | `design` |
+| Design system | Design System | `other` |
+| Page | plain HTML page, after loading `artifact-design` | `other` |
+| File | the matching file skill (docx, pptx, xlsx, pdf) | none |
+
+- **Diagram:** load `artifact-diagramming` when a picture shows the real mechanism.
+- **Charts:** load `dataviz` before drawing any chart; prefer the Dashboard type when the page is mostly data.
+- **Collecting input:** load `artifact-capabilities` and declare the smallest set: `db` and `user` for answers from several people (the docket, an intake form), `artifact` for a page that saves its own versions. Sync what it holds back to records through Naive; never treat the page's store as the record.
+- **Updating:** republish to the same URL when the records change, so the link people hold stays current.
+- Publish privately and give the link. Sharing it further is the founder's call.

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));