naive-framework 0.1.0 → 0.3.0

package/interface/router.mjs

@@ -24,6 +24,11 @@
 //                 record (escalate -> an agent's write is a draft), and the role's allowed routes
 //   robots        a team-plan role may list the routes it may read and write; system/robots shows them
 //   aliases       interface/route-aliases.json maps a renamed route to its new one, with a note
+//   hierarchy     a read resolves layout, template, error, loading, not-found, then page (P-28);
+//                 resolved_by names the level that answered (interface/reads.mjs)
+//   writes        a write answers with what it changed and the next route to act on; a layout lists
+//                 the actions open to the actor; package, group and venture routes; global errors
+//                 (interface/writes.mjs wraps call)
 //   storage       a record is read and written through the connector for the source its record
 //                 type lives in (knowledge/connectors, EE-037): the venture's own folder unless its
 //                 knowledge/sources.json names another, such as a GitHub repository, where a write
@@ -40,7 +45,27 @@ import { agentFromEnv, entries as provEntries, record as prov } from "./provenan
 import { address } from "../knowledge/connectors/contract.mjs";
 import { holding, locked } from "../schema/decisions.mjs";
 import { configOf, hold } from "../schema/gate.mjs";
+// Freshness (Revalidating, V-1 to V-8): stale flags on reads, and the freshness and revalidate commands.
+import { readFlag as freshnessFlag } from "../schema/freshness.mjs";
+// Gate group hooks (M-18, F-5, X-2, X-4 to X-6, P-2, P-7, U-4): who is acting, access at the record,
+// the gate's verdict, where held drafts wait, and check settings. The logic lives in these modules.
+import { actingCall, itemId, mayReadItem, mayReadSome } from "./acting.mjs";
+import { checkPlan, gateWrite, heldDraft } from "./gate-hooks.mjs";
 import { LOCAL, attributeSources, connect, sourceFor } from "../knowledge/connectors/index.mjs";
+// Caching (schema/caching.mjs): per-action memo, the record-level cache for command routes, and system/cache, system/judge, system/answer.
+import { actionScope, cacheRoutes, command as cachedCommand, forget, internal as cacheInternal, memo } from "../schema/caching.mjs";
+// Context hook: instrumentation of every call and judgment (interface/instrumentation.mjs, P-4, F-4).
+import { instrumented, judgment } from "./instrumentation.mjs";
+// Hooks for writes, reads and boundaries (wf/writes): the wrapper around call, per-record containment and private folders.
+import { around } from "./writes.mjs";
+import { contain } from "./boundaries.mjs";
+import { packageSlots } from "./package-routes.mjs";
+import { routable } from "../schema/structure.mjs";
+// Brand hook (Y-2..Y-4, J-2..J-4, T-1, T-2, P-24, P-26): routes, commands and layout context from schema/brand.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"));
@@ -70,7 +95,9 @@ export function kits() {
 const needNowPriors = () => load(join(repo, "schema/need-now.json"));
 
 /** The route table, generated from schema/data-model.json, the kit manifests and schema/need-now.json. */
-export function routes() {
+// Caching hook (F-12): built once per action and shared.
+export function routes() { return memo("routes", buildRoutes); }
+function buildRoutes() {
   const model = load(join(repo, "schema/data-model.json"));
   const ks = kits();
   const owner = new Map(ks.flatMap((k) => k.records.map((r) => [r, k])));
@@ -110,6 +137,8 @@ export function routes() {
     cmd("system/package", "schema/packages.mjs", "The venture package (EE-067, EE-069): the core packages open now and the handoffs, each record confirmed, to review or to write, what moves on its own and what waits, and what completion unlocks; --write renders the view and records a version. Assumes a solo founder or small founding team in Discovery and Validation; agents are a package enhancement"),
     cmd("system/need-now", "schema/need-now.mjs", "What the venture needs now, soon, or should hold back (EE-028)"),
     cmd("system/time-to-ready", "schema/time-to-ready.mjs", "Time to running, and to ready per layer and MAD tier"),
+    // Model steps hook (use model, EE-073): the logic is schema/model-steps.mjs; this route only shows the payload.
+    cmd("system/steps", "schema/model-steps.mjs", "The model steps' payload (use model, EE-073): what code computed, a placeholder for each judgment a model has yet to give, and the only fields each one receives; asks no model. mentura steps run asks one", { args: ["payload"] }),
     cmd("purpose/validation/assess", "schema/assess-problem.mjs", "What the problem's evidence is strong enough for: each assumption labelled demonstrated, inferred, assumed, unknown or contradicted, the commitment it supports and the next test (EE-050). Asks first when the record is incomplete; input as_is runs it anyway", { as_is: true }),
     cmd("governance/analytics", "schema/decision-analytics.mjs", "Decision analytics (EE-072): how many decisions of each type each function has made, open against decided, in whose words, in which phase, and their outcomes. Data only; a view is the platform's, or a visualization skill's", { actions: ["run", "layout"] }),
     cmd("governance/decisions", "schema/decisions.mjs", "The decision matrix: every decision the venture owes by layer and phase, with its parent and boundary, and whether it renders now, waits, comes later, is stale or deferred (EE-054, EE-057)"),
@@ -124,9 +153,17 @@ export function routes() {
     cmd("governance/payouts", "schema/payouts.mjs", "Who gets what at a sale value, from the cap table (EE-022); input value, else the scenarios in exit.json", { needs: ["governance/ownership.json"], venture_arg: "id" }),
     cmd("system/overview", null, "The venture at a glance: telos, validation, need-now, time to ready, team and recent provenance, rendered as parallel slots", { internal: "overview" }),
     cmd("system/robots", null, "Which roles may read and write which routes, from the team plan", { internal: "robots" }),
+    // Context hook (interface/vitals.mjs, interface/context.mjs): agent vitals and the context budget (N-6, C-15, N-13).
+    cmd("system/vitals", "interface/vitals.mjs", "Agent vitals (N-6): calls per task, tokens of context per call, time to a useful answer and time from a decision opening to a person deciding it, at the 75th percentile, each checked against its threshold (C-15). Reads the events log that instrumentation writes"),
+    cmd("system/context", "interface/context.mjs", "The context budget (N-13): what every route sends an agent, in tokens, against its budget, with the largest part and where to move it (S-14, F-6)", { args: ["budget"] }),
     cmd("knowledge/catalog", "knowledge/connectors/catalog.mjs", "Build or refresh the catalog: every item in every source the venture keeps records in, with its address and version, no content (EE-037)"),
     cmd("knowledge/search", "knowledge/connectors/catalog.mjs", "Find items across every source through the catalog; input value is the query (EE-037)", { value_flag: "--search" }),
+    // Freshness (Revalidating, V-1 to V-8): schema/freshness.mjs.
+    cmd("system/freshness", "schema/freshness.mjs", "What is fresh, stale or expired, and which records are live holes: by time (freshness profiles, per phase too) and on demand (a dependency changed, a where-used parent drifted, a tag, path or package was revalidated)"),
+    cmd("system/revalidate", "schema/freshness.mjs", "Mark records stale on demand: input value tag:<route> (the record and what depends on it), path:<folder>, package:<name>, or pivot (the validation package); a plain folder is refused in favour of exact tags", { value_flag: "--revalidate" }),
   );
+  out.push(...cacheRoutes(cmd)); // Caching hook: system/cache, system/judge, system/answer (schema/caching.mjs).
+  out.push(...brandCommands(cmd)); // Brand hook: brand tokens, voice, glossary terms, sitemap.xml, asset facts (schema/brand.mjs).
   return out.sort((a, b) => a.route.localeCompare(b.route));
 }
 
@@ -172,21 +209,22 @@ export function ventureDir(id, workspace = defaultWorkspace()) {
     }
     return null;
   }
-  for (const d of walkVentures(workspace)) if (load(join(d, "venture.json")).id === id) return d;
+  // A broken venture.json is found by its folder name, so its global error can answer (E-8, interface/boundaries.mjs).
+  for (const d of walkVentures(workspace)) { let vid; try { vid = load(join(d, "venture.json")).id; } catch { vid = basename(d); } if (vid === id) return d; }
   return null;
 }
 
 /** The ventures under a workspace: id, name, phase, path (the [...venture] segment) and folder. */
 export function ventures(workspace = defaultWorkspace()) {
   const root = existsSync(join(workspace, "ventures")) ? join(workspace, "ventures") : workspace;
-  return walkVentures(workspace).map((d) => { const v = load(join(d, "venture.json")); return { id: v.id, name: v.name, phase: v.phase, path: relative(root, d), dir: d }; });
+  return walkVentures(workspace).map((d) => { let v; try { v = load(join(d, "venture.json")); } catch { return { id: basename(d), name: null, phase: null, path: relative(root, d), dir: d, broken: true }; } return { id: v.id, name: v.name, phase: v.phase, path: relative(root, d), dir: d }; });
 }
 
 // The venture's decision rights: the template, tightened by the venture's own file.
 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;
 }
@@ -200,9 +238,9 @@ export function gateOf(r, dir) {
 }
 
 // Robots: a team-plan role may list the routes it may read and write (globs over routes).
-function allowed(dir, actorId, action, route) {
+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;
@@ -219,17 +257,19 @@ const PACKAGE_ROUTE = {
   "anatomy-answers": "product/anatomy-answers", "anatomy-input": "product/anatomy", "venture-package": ".release/venture-package",
   "decision-record": "decisions",
   customer: "customers", investor: "investors", "money-account": "money", "raw-source": "raw/sources",
+  people: "people", founder: "people/founders", "fund-thesis": "fund/thesis", "fund-terms": "fund/terms", deal: "deals",
+  ...BRAND_ROUTES, // Brand hook: marketing/brand, public/assets, glossary (schema/brand.mjs).
 };
 
 // Prefer a file that is already there, so an unmigrated venture keeps its old path. A new write uses the first path, which is the package layout.
 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;
     }
   }
@@ -243,13 +283,14 @@ export function draftOf(route, venture, workspace) {
   const dir = ventureDir(venture, workspace);
   if (!r || r.kind !== "record" || r.collection === "list" || !dir) return null;
   const file = fileFor(r, params, dir);
+  if (!file) return null; // a route with no concrete file (a pattern-only slot) has no draft
   return { dir, file, draft: draftPath(file), gate: gateOf(r, dir), route: r.collection === "item" ? r.route.replace("[id]", params.id) : r.route };
 }
 
 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 = "";
@@ -266,9 +307,11 @@ function instructionsOf(chain) {
 }
 
 /** A score below its threshold is uncertain: not an error and not an answer. It routes to the function owner. */
-export function judge(score, threshold, owner) {
-  if (typeof score !== "number" || score < threshold) return { outcome: "uncertain", owner, result: null };
-  return { outcome: "answer", result: score };
+export function judge(score, threshold, owner, at) {
+  const out = typeof score !== "number" || score < threshold ? { outcome: "uncertain", owner, result: null } : { outcome: "answer", result: score };
+  // Context hook: a judgment made for a venture (at.dir) is an instrumentation event (F-4).
+  if (at?.dir) judgment(at.dir, { question: at.question, route: at.route, model: at.model, score, threshold, outcome: out.outcome, owner });
+  return out;
 }
 
 /** Runs fn. A throw is the uncaught outcome. */
@@ -292,9 +335,11 @@ export function layout(r, dir) {
   const pkg = owned ? { skill: skillsOf(owned).map((s) => s.path), template: r.template ?? null, gates: owned.gates ?? [] } : null;
   const out = { route: r.route, stack, chain, instructions: instructionsOf(chain), package: pkg, note: r.note, groups: r.groups ?? [] };
   if (r.kind === "record") Object.assign(out, { schema: r.schema, template: r.template, checks: r.checks, gate: gateOf(r, dir) });
+  { const brand = brandLayout(dir, r.route); if (brand) out.brand = brand; } // Brand hook: brand, voice and package terms at this route (Y-2, Y-3, T-2).
   if (dir && r.kind === "record") {
     try {
-      const nn = JSON.parse(spawnSync("node", [join(repo, "schema/need-now.mjs"), dir, "--json"], { encoding: "utf8" }).stdout);
+      // Caching hook (O-5): shared with the system/need-now command in the same action.
+      const nn = JSON.parse(memo(`cmd:schema/need-now.mjs ${dir} --json`, () => spawnSync("node", [join(repo, "schema/need-now.mjs"), dir, "--json"], { encoding: "utf8" }), { dir }).stdout);
       const row = nn.rows.find((x) => x.type === r.record);
       if (row) out.need_now = { phase: nn.phase, status: row.status, now: row.now, next: row.next, why: row.why };
     } catch {}
@@ -311,10 +356,18 @@ const fix = (r) => ({ skills: r.kit_path ? skillsOf(kits().find((k) => k.path ==
  * routes; via: the interface (cli, mcp, api; default router); provenance: { derived_from,
  * decision, note, agent } for the log.
  */
-export async function call({ venture, route, action, input, actor = "agent", actor_id = process.env.MENTURA_ACTOR_ID, workspace, via = "router", provenance = {} }) {
+// Caching hook (F-2): one top-level call is one action; the calls it makes join it and share its memo.
+// Context hook: every call is timed and measured for agent vitals (interface/instrumentation.mjs).
+// Gate group hook (M-18): who is acting is checked on every call and carried on the answer.
+// Writes hook (interface/writes.mjs): adds what reads, layouts and writes answer.
+export const call = (args) => actionScope(() => instrumented(args, (a) => actingCall(a, (b) => around(callInAction, b), ventureDir), ventureDir));
+async function callInAction({ venture, route, action, input, actor = "agent", actor_id = process.env.MENTURA_ACTOR_ID, workspace, via = "router", provenance = {} }) {
   const requested = route;
   const { r, params, alias } = resolve(route);
   if (!r) return { ok: false, outcome: "error", error: `no route ${route}` };
+  // Context hook (interface/context.mjs): navigate reads a route header first, with its layout once per
+  // session, its template and prefetched refs; head stops after the header (N-3, L-2, O-4).
+  if (action === "navigate" || action === "head") return (await import("./context.mjs")).navigate({ ...(input ?? {}), venture, route: requested, workspace, actor, actor_id, via, header_only: action === "head" || !!input?.header_only });
   const deprecated = alias ? { deprecated: `${alias.from} is now ${alias.to}${alias.note ? `: ${alias.note}` : ""}` } : {};
   route = r.collection === "item" ? r.route.replace("[id]", params.id) : r.route;
   if (!r.actions.includes(action)) return { ok: false, error: `${route} has no action ${action} (it has ${r.actions.join(", ")})` };
@@ -323,7 +376,8 @@ export async function call({ venture, route, action, input, actor = "agent", act
   if (action === "layout") { if (venture && !dir) return { ok: false, error: `no venture ${venture}` }; return { ok: true, result: layout(r, dir), ...deprecated }; }
   if (!dir) return { ok: false, error: `no venture ${venture}` };
   const act = action === "write" ? "write" : "read";
-  if (!allowed(dir, actor_id, act, requested) && !allowed(dir, actor_id, act, route)) return { ok: false, error: `${actor_id} may not ${act} ${route} (team plan routes)` };
+  // Gate group hook (F-5): a role that may read some items of a collection may read its list, filtered below.
+  if (!allowed(dir, actor_id, act, requested) && !allowed(dir, actor_id, act, route) && !(act === "read" && r.collection === "list" && mayReadSome(dir, actor_id, route))) return { ok: false, error: `${actor_id} may not ${act} ${route} (team plan routes)` };
   // An activity a decision unlocks stays closed to agents until a person makes that decision (EE-058).
   const lock = actor !== "person" && (action === "write" || action === "run") ? (locked(dir, requested, actor_id) || locked(dir, route, actor_id)) : null;
   if (lock) return { ok: false, error: `${route} is locked until decision ${lock.id} is made: ${lock.question}`, locked_by: lock.id,
@@ -337,15 +391,19 @@ export async function call({ venture, route, action, input, actor = "agent", act
   if (r.kind === "command") {
     if (r.internal === "overview") return { ok: true, result: await overview(venture, workspace), ...deprecated };
     if (r.internal === "robots") return { ok: true, result: robots(dir), ...deprecated };
-    const lacking = (r.needs ?? []).filter((f) => !existsSync(join(dir, f)));
+    // 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(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"];
-    const p = spawnSync("node", [join(repo, r.script), ...args], { encoding: "utf8" });
+    // Caching hook (C-3, H-3): a declared command's result comes from the record-level cache; the spawn is memoized per action (O-5).
+    const p = await cachedCommand({ dir, route, script: r.script, args, input, actor, actor_id }, () => memo(`cmd:${r.script} ${args.join(" ")}`, () => spawnSync("node", [join(repo, r.script), ...args], { encoding: "utf8" }), { dir }));
+    const cache = p.cache ? { cache: p.cache } : {};
     if (p.status !== 0) return { ok: false, error: (p.stderr || p.stdout).trim() };
     // A command that needs input first (EE-050) answers needs_input: the caller asks the person
     // whether to fill the record in or run as is, and runs again with input as_is to go on.
-    try { const out = JSON.parse(p.stdout); return { ok: true, result: out.needs_input ? null : out, ...(out.needs_input ? { needs_input: out.needs_input } : {}), ...deprecated }; } catch { return { ok: true, result: p.stdout, ...deprecated }; }
+    try { const out = JSON.parse(p.stdout); return { ok: true, result: out.needs_input ? null : out, ...(out.needs_input ? { needs_input: out.needs_input } : {}), ...cache, ...deprecated }; } catch { return { ok: true, result: p.stdout, ...cache, ...deprecated }; }
   }
 
   // Storage: the connector for the source this record type lives in.
@@ -365,11 +423,15 @@ export async function call({ venture, route, action, input, actor = "agent", act
     const patterns = r.collection === "item" ? [fileFor(r, params, dir)] : r.files;
     let items;
     try {
-      const paths = patterns.some((g) => g.includes("*")) ? (await store.list()).map((x) => x.path).filter((f) => patterns.some((g) => glob(g).test(f))) : patterns;
-      items = (await Promise.all(paths.map((f) => store.read(f)))).filter(Boolean);
+      // a file named _* is never an item; routable: private _folders (P-22)
+      const paths = patterns.some((g) => g.includes("*")) ? (await store.list()).map((x) => x.path).filter((f) => !/(^|\/)_[^/]*$/.test(f) && patterns.some((g) => glob(g).test(f) && routable(f, g))) : patterns;
+      // Caching hook (F-2): each record is read once per action and shared.
+      items = (await Promise.all(paths.map((f) => memo(`read:${src.id}:${f}`, () => store.read(f), { dir })))).filter(Boolean);
+      // Gate group hook (F-5): access is checked again at the record; a list holds only the items the role may read.
+      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" && 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)));
@@ -394,6 +456,9 @@ export async function call({ venture, route, action, input, actor = "agent", act
       }
       if (attrs.length) x.attributes = cites;
     }
+    // Freshness (V-5): a stale record is still read, flagged stale until it is redone (stale-while-revalidate).
+    const fresh = remote ? {} : await freshnessFlag(dir, found, r.collection === "list");
+    Object.assign(loading, fresh);
     const parseOne = parse;
     const parseWith = (x) => { const v = parseOne(x); return overlays.has(x.path) ? { ...v, ...overlays.get(x.path) } : v; };
     if (r.collection === "list") {
@@ -406,23 +471,30 @@ export async function call({ venture, route, action, input, actor = "agent", act
         }
         return path;
       };
-      return { ok: true, result: Object.fromEntries(items.map((x) => [idOf(x.path), parseWith(x)])), sources: Object.fromEntries(items.map((x) => [idOf(x.path), cite(x)])), ...deprecated };
+      // Per-record containment (E-6): an item that does not parse is named in errors; the rest come back.
+      const { values, errors } = contain(items, parseWith, idOf);
+      return { ok: true, result: Object.fromEntries(values.map(([x, v]) => [idOf(x.path), v])), sources: Object.fromEntries(values.map(([x]) => [idOf(x.path), cite(x)])), ...(Object.keys(errors).length ? { errors } : {}), ...fresh, ...deprecated };
     }
     const data = Object.fromEntries(items.map((x) => [x.path, parseWith(x)]));
-    return { ok: true, result: items.length === 1 ? data[found[0]] : data, ...(items.length === 1 ? { source: cite(items[0]) } : { sources: Object.fromEntries(items.map((x) => [x.path, cite(x)])) }), ...loading, ...deprecated };
+    // V-9 hook: a summary whose source changed since it was written is marked stale (schema/stale.mjs).
+    const stale = !remote && items.length === 1 ? staleOf(dir, found[0]) : null;
+    return { ok: true, result: items.length === 1 ? data[found[0]] : data, ...(items.length === 1 ? { source: cite(items[0]) } : { sources: Object.fromEntries(items.map((x) => [x.path, cite(x)])) }), ...loading, ...(stale ? { stale } : {}), ...deprecated };
   }
 
   if (action === "check") {
-    const outs = r.checks.map((c) => ({ check: c, ...spawnSync("node", [join(repo, c), dir], { encoding: "utf8" }) }));
-    const ok = outs.every((o) => o.status === 0);
-    return { ok, result: outs.map((o) => ({ check: o.check, passed: o.status === 0, output: (o.stdout + o.stderr).trim() })), ...(ok ? {} : { fix: fix(r) }), ...deprecated };
+    // Gate group hook (P-7): the checks settings in naive.config.json turn a check off or make it warn only.
+    const plan = checkPlan(dir, r.checks);
+    const outs = plan.filter((p) => p.mode !== "off").map((p) => ({ check: p.check, mode: p.mode, ...spawnSync("node", [join(repo, p.check), dir], { encoding: "utf8" }) }));
+    const ok = outs.every((o) => o.status === 0 || o.mode === "warn");
+    return { ok, result: [...outs.map((o) => ({ check: o.check, passed: o.status === 0, ...(o.mode === "warn" ? { warn_only: true } : {}), output: (o.stdout + o.stderr).trim() })), ...plan.filter((p) => p.mode === "off").map((p) => ({ check: p.check, passed: null, off: true }))], ...(ok ? {} : { fix: fix(r) }), ...deprecated };
   }
 
   if (action === "write") {
+    forget(dir); // Caching hook (H-3): a write never uses the cache, and what this action memoized for the venture is read again after it.
     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.
@@ -444,7 +516,9 @@ export async function call({ venture, route, action, input, actor = "agent", act
     // (EE-054): an agent's write becomes a draft, as for a gated record.
     const held = !remote && actor !== "person" ? holding(dir, file) : null;
     // The venture's own fail-closed routes (naive.config.json, the gate, EE-073) hold an agent's write too.
-    const configured = !remote ? hold(configOf(dir), r.route, actor) : null;
+    // Gate group hook (X-1 to X-6, U-4): the venture's gate decides; a refusal stops the write here.
+    const configured = !remote ? gateWrite({ dir, r, route, requested, file, actor, actor_id, provenance, gate }) : null;
+    if (configured?.then === "refuse") return { ok: false, error: configured.why, gate_rule: configured.rule, refused_by: configured.source };
     const gatedDraft = !remote && (!!gate?.drafts || !!held || !!configured) && actor !== "person";
     const attributeWrites = [];
     if (split.length && !gatedDraft) {
@@ -482,13 +556,12 @@ export async function call({ venture, route, action, input, actor = "agent", act
     }
 
     const draft = gatedDraft;
-    if (draft) {
-      const dest = join(dir, draftPath(file));
-      mkdirSync(dirname(dest), { recursive: true });
-      writeFileSync(dest, text);
-    } else await store.write(file, recordText);
-    const entry = log(draft ? draftPath(file) : file, draft ? "draft" : provenance.activity ?? "write");
-    return { ok: true, result: { written: draft ? draftPath(file) : file, draft, gate: gate?.class ?? null, provenance: entry.hash, note: draft ? (gate?.drafts ? `${r.record} is a ${gate.class} decision (${gate.level}, owner ${gate.owner}): written as a draft for a person to accept` : held ? `decision ${held.id} ${held.why}: written as a draft for a person to accept` : `${configured.rule} fails closed in naive.config.json: written as a draft for a person to accept`) : "written", ...(held ? { held_by: held.id } : {}), ...(configured ? { gate_rule: configured.rule } : {}), ...attributesOut }, ...deprecated };
+    // Gate group hook (X-2): the held draft, the owner it was sent to and any variants kept side by side.
+    let held2 = null;
+    if (draft) held2 = heldDraft(dir, { draft: draftPath(file), file, text, verdict: configured, route, agent });
+    else await store.write(file, recordText);
+    const entry = log(draft ? held2.written : file, draft ? "draft" : provenance.activity ?? "write");
+    return { ok: true, result: { written: draft ? held2.written : file, draft, gate: gate?.class ?? null, provenance: entry.hash, note: draft ? (gate?.drafts ? `${r.record} is a ${gate.class} decision (${gate.level}, owner ${gate.owner}): written as a draft for a person to accept` : held ? `decision ${held.id} ${held.why}: written as a draft for a person to accept` : configured.why) : "written", ...(held ? { held_by: held.id } : {}), ...(configured ? { gate_rule: configured.rule, ...(configured.owner ? { owner: configured.owner } : {}) } : {}), ...(held2?.variants ? { variant: held2.variant, variants: held2.variants, decision: held2.decision } : {}), ...attributesOut }, ...deprecated };
   }
   return { ok: false, error: `unhandled action ${action}` };
 }
@@ -539,6 +612,7 @@ async function overview(venture, workspace) {
       slot("@need-now", async () => (await run("system/need-now")).rows.filter((x) => x.status === "suggest now").map((x) => ({ record: x.type, now: x.now, why: x.why }))),
       slot("@ready", async () => { const t = await run("system/time-to-ready"); return { running: t.running.on ?? `not yet: ${t.running.missing.join(", ")}`, layers: t.layers.map((l) => ({ layer: l.layer, ready: l.ready_on ?? `missing ${l.missing.join(", ")}` })) }; }),
       slot("@team", async () => { const p = await read("people/team-plan"); if (typeof p === "string") return p; return p.roles.map((x) => ({ role: x.id, occupant: x.occupant, status: x.status, needed_by: x.needed_by })); }),
+      slot("@packages", () => packageSlots(dir, venture)), // P-17: a package with nothing in it shows its default
       slot("@provenance", () => provEntries(dir).slice(-5).reverse().map((e) => ({ at: e.at, activity: e.activity, entity: e.entity, by: `${e.agent.kind}${e.agent.id ? ` ${e.agent.id}` : ""} via ${e.agent.via}` }))),
     ]),
   };
@@ -546,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/naive-setup/SKILL.md

@@ -0,0 +1,71 @@
+---
+type: knowledge
+tags: [everything-ecosystem, naive, skills, interface, setup, artifacts, docket]
+ai-model: claude-opus-5.5
+created: 2026-10-29T06:30:00Z
+source: hybrid
+name: naive-setup
+description: >
+  Walk a founder through setting up a new Naive venture inside the model's own
+  harness: their people and hats, where each function keeps its truth, the
+  strategic foundation and first decisions, and a goal for discovery. Show the
+  progress as a Claude artifact where the harness has artifacts (EE-083).
+  MANDATORY TRIGGERS: set up my venture, naive setup, finish setup, walk me
+  through setup, I just ran create-venture, establish my venture, structure my
+  business, what do I do after create-venture.
+---
+
+# Naive setup
+
+Interface layer (EE-083). `create-venture` scaffolds the venture. This skill finishes the job in conversation. You ask the questions, the founder answers in their own words, and Naive writes each answer as a decision or a source-of-truth pointer, with provenance. The progress is a view the harness renders, not a server Naive runs. In Claude, it is an artifact.
+
+The questions and their order come from Naive, not from you. Read them from `mentura_setup` (MCP) or `node schema/setup.mjs <venture dir> state`, and never invent a question.
+
+## 1. Read the state
+
+Call `mentura_setup` with the venture id. The result has:
+
+- `state`: the people, sources of truth, docket and goal, plus `steps` (which of the four are done), `done`, and `counts`.
+- `artifact`: the state, already rendered into `interface/skills/naive-setup/artifact.html`, as one self-contained HTML page.
+
+Without MCP, run `node schema/setup.mjs <venture dir> state` and `node schema/setup.mjs <venture dir> artifact`.
+
+## 2. Show it
+
+- **Claude (claude.ai, the desktop app, or Claude Code with the Artifact tool):** render `artifact` as an HTML artifact. Do not edit its contents; it is generated. Render it again after every answer, so the founder sees the progress bar move.
+- **A harness without artifacts:** show the four steps as a short checklist in Markdown, with the next open question underneath.
+
+## 3. Ask one question at a time, in order
+
+Work through the first step that is not done, and ask only its next open question:
+
+1. **People and hats.** If `state.people` is missing, ask for the founder's name, role, and whether they are solo or a team. A solo founder wears every hat. These come from `create-venture`. If they are missing, tell the founder to run `npx create-venture` again with `--name`, `--role` and `--team`. Do not write `people/` by hand.
+2. **Sources of truth.** For each function, ask where its truth lives, offering the systems in `state.catalog.functions[<function>]`. Write each answer with `mentura_setup_point` (`function`, `system`, and an `address` such as `acme/app`). If the founder has nothing for a function yet, leave it unpointed and move on. For legal, if there are no documents, say so and name the options in the catalog.
+3. **Foundation and first decisions.** These are the `state.docket` items whose status is not `decided`, taken in order. Ask the question as written. If it has options, offer them, but take the founder's own words. Write the answer with `mentura_setup_answer` (`id` and `answer`).
+4. **A goal for discovery.** Ask what must be true for the venture to leave discovery. Write it with `mentura_setup_answer`, using `id: "discovery-goal"`.
+
+## 4. The founder's words, not yours
+
+- Pass the founder's answer exactly as they wrote it. Do not polish it, summarize it, or fill in an answer they did not give.
+- If an answer is unclear, ask a follow-up question. Do not guess.
+- A foundation statement is the founder's to state. If they ask you to draft one, show the draft and ask them to accept it or rewrite it in their own words. Write it only after they reply, and write what they replied.
+
+## 5. When every step is done
+
+`state.done` is true. Render the artifact one last time: it shows "Your venture is structured." Then tell the founder, in a few lines:
+
+- the venture now has its people, its sources of truth, its foundation and first decisions, and a discovery goal;
+- how many decisions wait for later phases (`state.later`); the docket brings each one up when it matters;
+- each next decision should be oriented around the discovery goal;
+- to operate the business day to day, with a team and agents, they use Mentura. Naive is the structure; Mentura is where it runs, the way a Next.js app is deployed on Vercel.
+
+## Without a model
+
+The same steps run from the command line:
+
+```sh
+node schema/setup.mjs ~/ventures/acme state
+node schema/setup.mjs ~/ventures/acme point finance rho
+node schema/setup.mjs ~/ventures/acme answer discovery-goal "Ten clinic owners confirm the scheduling problem by December"
+node schema/setup.mjs ~/ventures/acme artifact > setup.html
+```

package/interface/skills/naive-setup/artifact.html

@@ -0,0 +1,83 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Venture setup</title>
+<style>
+:root { --bg:#f6f7f4; --panel:#fff; --fg:#1d2320; --muted:#5d675f; --line:#d9ded8; --accent:#2f6b4f; --accent-soft:#e3efe8; --warn:#8a5a00; --warn-soft:#f6ecd8;
+  --body: system-ui, -apple-system, "Segoe UI", sans-serif; --mono: ui-monospace, "SF Mono", Menlo, monospace; color-scheme: light; }
+@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --bg:#121614; --panel:#1a201d; --fg:#e4e9e5; --muted:#9aa59d; --line:#2b332e; --accent:#86c4a3; --accent-soft:#1d2b24; --warn:#e3b25c; --warn-soft:#2c2414; color-scheme: dark; } }
+:root[data-theme="dark"] { --bg:#121614; --panel:#1a201d; --fg:#e4e9e5; --muted:#9aa59d; --line:#2b332e; --accent:#86c4a3; --accent-soft:#1d2b24; --warn:#e3b25c; --warn-soft:#2c2414; color-scheme: dark; }
+* { box-sizing: border-box }
+body { margin:0; background:var(--bg); color:var(--fg); font:16px/1.55 var(--body); }
+.wrap { max-width: 820px; margin: 0 auto; padding: 28px 16px 64px; display: grid; gap: 22px; }
+header { display:grid; gap:6px } h1 { margin:0; font-size:1.7rem; letter-spacing:-.01em } h2 { margin:0 0 2px; font-size:1.1rem }
+.muted { color: var(--muted) } .mono { font-family: var(--mono); font-size: .86em; overflow-wrap: anywhere }
+.bar { height: 8px; border-radius: 999px; background: var(--line); overflow: hidden } .bar > div { height: 100%; background: var(--accent) }
+.steps { display:flex; gap:6px; flex-wrap:wrap } .step { font:600 .76rem/1 var(--mono); padding:6px 9px; border-radius:999px; border:1px solid var(--line); color:var(--muted) }
+.step.ok { background: var(--accent-soft); color: var(--accent); border-color: transparent } .step.next { border-color: var(--accent); color: var(--accent) }
+section { background: var(--panel); border:1px solid var(--line); border-radius:10px; padding:18px; display:grid; gap:12px; min-width: 0 }
+.table { overflow-x: auto } table { width:100%; border-collapse: collapse; font-size:.93rem }
+td.mono { white-space: nowrap }
+td, th { text-align:left; padding:7px 6px; border-bottom:1px solid var(--line); vertical-align: top }
+th { font: 600 .72rem/1.2 var(--mono); text-transform: uppercase; letter-spacing:.05em; color: var(--muted) }
+.pill { display:inline-block; font:600 .72rem/1.2 var(--mono); padding:4px 7px; border-radius:999px; background: var(--accent-soft); color: var(--accent); margin: 0 4px 4px 0 }
+.pill.pointed { background: var(--line); color: var(--fg) } .pill.none { background: var(--warn-soft); color: var(--warn) }
+.card { border:1px solid var(--line); border-radius:8px; padding:12px; display:grid; gap:6px } .card.done { opacity:.7 } .card.next { border-color: var(--accent) }
+.q { font-weight:600 } .hint { font-size:.88rem; color: var(--muted) }
+.celebrate { text-align:center; padding: 28px 18px; background: var(--accent-soft); border-color: transparent }
+.celebrate .big { font-size: 1.9rem; font-weight: 700; color: var(--accent) } ol { margin:0; padding-left: 1.2em; display:grid; gap:6px; text-align:left }
+</style>
+</head>
+<body>
+<div class="wrap" id="app"></div>
+<script id="naive-setup-state" type="application/json">__NAIVE_SETUP_STATE__</script>
+<script>
+// A view of the venture's setup state, filled in by `node schema/setup.mjs <venture dir> artifact`.
+// It reads nothing from the network and writes nothing: the founder answers in the chat, the model writes
+// each answer through Naive, and renders this page again.
+const S = JSON.parse(document.getElementById("naive-setup-state").textContent);
+const esc = (s) => String(s ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+const st = S.steps, v = S.venture;
+const order = [["people", "People and hats"], ["truth", "Sources of truth"], ["docket", "Foundation and first decisions"], ["goal", "A goal for discovery"]];
+const next = order.find(([k]) => !st[k])?.[0];
+const doneCount = order.filter(([k]) => st[k]).length;
+const label = ([k, t]) => '<span class="step ' + (st[k] ? "ok" : k === next ? "next" : "") + '">' + (st[k] ? "&#10003; " : "") + t + "</span>";
+
+const people = S.people
+  ? '<div class="table"><table><tr><th>Person</th><th>Role</th><th>Hats</th></tr>' + S.people.people.map((p) => "<tr><td>" + esc(p.name) + '</td><td class="mono">' + esc(p.role) + "</td><td>" + (p.hats.map((h) => '<span class="pill pointed">' + esc(h) + "</span>").join("") || '<span class="muted">none</span>') + "</td></tr>").join("") + "</table></div>"
+  : '<p class="muted">Nobody is listed yet. Tell me your name, your role, and whether you are solo or a team.</p>';
+
+const fns = [...new Set([...Object.keys(S.catalog.functions).filter((f) => f === "legal" || (S.people?.people ?? []).some((p) => p.hats.includes(f))), ...Object.keys(S.functions)])];
+const systemsOf = (f) => { const x = S.functions[f]; return x?.systems?.length ? x.systems.map((s) => '<span class="pill ' + (s.status === "connected" ? "" : "pointed") + '">' + esc(S.catalog.systems[s.system]?.label ?? s.system) + (s.address ? " &middot; " + esc(s.address) : "") + " &middot; " + esc(s.status) + (s.fixture ? " (fixture)" : "") + "</span>").join("") : '<span class="pill none">not pointed yet</span>'; };
+const offered = (f) => (S.catalog.functions[f] ?? []).map((s) => esc(S.catalog.systems[s]?.label ?? s)).join(", ");
+const truth = '<div class="table"><table><tr><th>Function</th><th>Source of truth</th><th>You can point it at</th></tr>' + fns.map((f) => "<tr><td>" + esc(f) + "</td><td>" + systemsOf(f) + '</td><td class="hint">' + offered(f) + "</td></tr>").join("") + "</table></div>";
+
+const open = S.docket.filter((d) => d.status !== "decided");
+const cards = S.docket.map((d) => '<div class="card ' + (d.status === "decided" ? "done" : d === open[0] ? "next" : "") + '"><div class="q">' + esc(d.question) + "</div>"
+  + (d.status === "decided" ? "<div>&#10003; " + esc(d.answer) + "</div>"
+    : d.relayed ? "<div>" + esc(d.answer) + '</div><div class="hint">Your answer, waiting for you to confirm it.</div>'
+
+    : (d.options.length ? '<div class="hint">Options: ' + d.options.map(esc).join(" / ") + "</div>" : "") + '<div class="hint">Answer in the chat, in your own words.</div>')
+  + "</div>").join("");
+
+const goal = S.goal?.status === "decided" ? "<p>&#10003; " + esc(S.goal.answer) + "</p>" : S.goal?.relayed ? "<p>" + esc(S.goal.answer) + '</p><p class="hint">Your answer, waiting for you to confirm it.</p>' : '<p class="muted">What must be true for ' + esc(v.name) + " to leave discovery? For example: ten clinic owners confirm the scheduling problem in interviews by December.</p>";
+
+const done = S.done
+  ? '<section class="celebrate"><div class="big">Your venture is structured.</div><p>' + esc(v.name) + " has its people and their hats, a source of truth for each function, a settled foundation and first decisions, and a goal for discovery. Every decision from here routes through the docket.</p><ol>"
+    + "<li>Orient each next decision around the discovery goal.</li><li>" + (S.later ? S.later + " more decisions wait for later phases; the docket brings each one up when it matters." : "The docket brings up each new decision when it matters.") + "</li><li>To operate the business day to day, with your team and your agents, use Mentura.</li></ol></section>"
+  : "";
+
+document.getElementById("app").innerHTML =
+  '<header><span class="muted mono">' + esc(v.type?.label ?? "venture") + " &middot; " + esc(v.phase) + "</span><h1>Set up " + esc(v.name) + '</h1><p class="muted">The structure of your venture, step by step. Answer in the chat; each answer is saved as a decision, and this page updates.</p>'
+  + '<div class="bar" role="progressbar" aria-valuemin="0" aria-valuemax="4" aria-valuenow="' + doneCount + '"><div style="width:' + doneCount * 25 + '%"></div></div><div class="steps">' + order.map(label).join("") + "</div></header>"
+  + (S.waiting.length ? '<section><h2>' + S.waiting.length + (S.waiting.length === 1 ? " answer waits" : " answers wait") + ' for you</h2><p class="muted">The model wrote these down from your words. They become your decisions when you confirm them yourself: run <span class="mono">npx naive setup confirm</span> in the venture.</p></section>' : "")
+  + done
+  + "<section><h2>1. People and hats</h2>" + people + "</section>"
+  + '<section><h2>2. Sources of truth</h2><p class="muted">Where each function keeps its truth. Naive keeps pointers, never copies.</p>' + truth + "</section>"
+  + '<section><h2>3. Foundation and first decisions</h2><p class="muted">The decision docket: ' + S.counts.settled + " of " + S.counts.of + " settled.</p>" + cards + "</section>"
+  + "<section><h2>4. A goal for discovery</h2>" + goal + "</section>";
+</script>
+</body>
+</html>