naive-framework 0.1.0 → 0.3.0

package/schema/kits.mjs

@@ -0,0 +1,24 @@
+// Mentura kits, as the framework sees them (EE-071): data only. A kit lives at
+// platform/kits/<name>/kit.json and extends one Naive package or one framework command. The framework
+// reads a kit's manifest by path and runs its entry as a separate process, never importing platform
+// code (schema/check-boundary.mjs), the way a Next.js build loads a deployment adapter it was pointed
+// at. A copy of the framework without platform/ has no kits, and nothing here fails because of it.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const repo = new URL("..", import.meta.url).pathname;
+export const KITS = "platform/kits";
+
+/** Every installed kit: { name, path, dir, ...kit.json }. */
+export function kits(root = process.env.NAIVE_KITS ?? join(repo, KITS)) {
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory() && existsSync(join(root, e.name, "kit.json")))
+    .map((e) => ({ ...JSON.parse(readFileSync(join(root, e.name, "kit.json"), "utf8")), dir: join(root, e.name), path: join(root, e.name, "kit.json") }));
+}
+
+/** The kit that extends a framework command (such as "upgrade --agent"), or null. */
+export const kitFor = (command) => kits().find((k) => k.extends?.command === command) ?? null;
+
+/** One kit by name, or null. */
+export const kit = (name) => kits().find((k) => k.name === name) ?? null;

package/schema/knowledge-sources.schema.json

@@ -2,27 +2,75 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "knowledge-sources.schema.json",
   "title": "Knowledge sources",
-  "description": "A venture's source map (<venture>/knowledge/sources.json, EE-037): the sources its records live in and which record types live where. Optional: a record type it does not name, and every record of a venture without one, lives in the venture's own folder (the implicit `venture` source). The venture decides its own layout; Mentura does not. Rules make it a source-of-truth matrix: a system of record per record type, attribute and context, written for a fast model to read (EE-042). Each source names a connector from the registry (an integration with a `connector` in knowledge/tooling/integrations.json). Credentials are named by environment variable, never stored.",
+  "description": "A venture's source map (<venture>/knowledge/sources.json, EE-037): the sources its records live in and which record types live where. Optional: a record type it does not name, and every record of a venture without one, lives in the venture's own folder (the implicit `venture` source). The venture decides its own layout; Mentura does not. Rules make it a source-of-truth matrix: a system of record per record type, attribute and context, written for a fast model to read (EE-042). Each source names a connector from the registry (an integration with a `connector` in knowledge/tooling/integrations.json). Credentials are named by environment variable, never stored. Beside the sources Naive reads records from, `functions` says where each of the venture's functions keeps its truth outside Naive (EE-083): the repo, hosting and analytics for the product, a payments or store account for sales, the bank for money, a folder or signing service for legal documents. Those are pointers to systems of record; a system Naive reads through code is connected, one it only knows of is pointed. `truth` says where the venture's source of truth as a whole lives.",
   "type": "object",
-  "required": ["sources", "records"],
+  "required": [
+    "sources",
+    "records"
+  ],
   "additionalProperties": false,
   "properties": {
     "sources": {
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["id", "connector"],
+        "required": [
+          "id",
+          "connector"
+        ],
         "properties": {
-          "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$", "not": { "const": "venture" }, "description": "The source's id; `venture` is reserved for the venture's own folder" },
-          "connector": { "type": "string", "description": "An integration id with a connector: filesystem, github" },
-          "writes": { "enum": ["direct", "pull-request", "none"], "description": "How writes reach it; the connector's default when left out" },
-          "root": { "type": "string", "description": "filesystem: the folder, relative to the venture folder or absolute. github: the folder inside the repository" },
-          "repo": { "type": "string", "pattern": "^[\\w.-]+/[\\w.-]+$", "description": "github: owner/name" },
-          "ref": { "type": "string", "description": "github: the branch (default main)" },
-          "token": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$", "description": "github: the environment variable holding a token (default GITHUB_TOKEN)" },
-          "api": { "type": "string", "description": "github: the API base, for GitHub Enterprise" },
-          "search": { "enum": ["api", "scan"], "description": "github: code search (default) or a scan of the files" },
-          "note": { "type": "string" }
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$",
+            "not": {
+              "const": "venture"
+            },
+            "description": "The source's id; `venture` is reserved for the venture's own folder"
+          },
+          "connector": {
+            "type": "string",
+            "description": "An integration id with a connector: filesystem, github"
+          },
+          "writes": {
+            "enum": [
+              "direct",
+              "pull-request",
+              "none"
+            ],
+            "description": "How writes reach it; the connector's default when left out"
+          },
+          "root": {
+            "type": "string",
+            "description": "filesystem: the folder, relative to the venture folder or absolute. github: the folder inside the repository"
+          },
+          "repo": {
+            "type": "string",
+            "pattern": "^[\\w.-]+/[\\w.-]+$",
+            "description": "github: owner/name"
+          },
+          "ref": {
+            "type": "string",
+            "description": "github: the branch (default main)"
+          },
+          "token": {
+            "type": "string",
+            "pattern": "^[A-Z][A-Z0-9_]*$",
+            "description": "github: the environment variable holding a token (default GITHUB_TOKEN)"
+          },
+          "api": {
+            "type": "string",
+            "description": "github: the API base, for GitHub Enterprise"
+          },
+          "search": {
+            "enum": [
+              "api",
+              "scan"
+            ],
+            "description": "github: code search (default) or a scan of the files"
+          },
+          "note": {
+            "type": "string"
+          }
         },
         "additionalProperties": false
       }
@@ -30,7 +78,9 @@
     "records": {
       "type": "object",
       "description": "Record type id (from schema/data-model.json) -> source id. Unnamed record types stay in the venture folder.",
-      "additionalProperties": { "type": "string" }
+      "additionalProperties": {
+        "type": "string"
+      }
     },
     "rules": {
       "type": "array",
@@ -125,6 +175,86 @@
         }
       }
     },
-    "note": { "type": "string" }
+    "note": {
+      "type": "string"
+    },
+    "truth": {
+      "type": "string",
+      "description": "local: this device is the source of truth; otherwise the address of the host every system is backed up to or hosted on (EE-083)"
+    },
+    "functions": {
+      "type": "object",
+      "description": "Each function's systems of record, by department id (operations/departments.json) or legal (EE-083)",
+      "propertyNames": {
+        "enum": [
+          "strategy",
+          "products",
+          "marketing-and-sales",
+          "supply-chain",
+          "service-delivery",
+          "customer-service",
+          "human-capital",
+          "it",
+          "finance",
+          "assets",
+          "risk-and-compliance",
+          "external-relationships",
+          "capabilities",
+          "legal"
+        ]
+      },
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "systems"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "systems": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "system",
+                "status"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "system": {
+                  "type": "string",
+                  "description": "A system id from schema/systems-catalog.json"
+                },
+                "address": {
+                  "type": "string"
+                },
+                "source": {
+                  "type": "string",
+                  "description": "The source in `sources` that reads it, when it is one"
+                },
+                "status": {
+                  "enum": [
+                    "connected",
+                    "pointed"
+                  ],
+                  "description": "connected: read by code (a connector or an integration); pointed: known, not read yet"
+                },
+                "synced": {
+                  "type": "string",
+                  "format": "date-time"
+                },
+                "fixture": {
+                  "type": "boolean",
+                  "description": "The last sync replayed a saved answer, not the live system"
+                }
+              }
+            }
+          },
+          "note": {
+            "type": "string",
+            "description": "What the founder said about this function, in their words"
+          }
+        }
+      }
+    }
   }
 }

package/schema/layer.json

@@ -16,12 +16,19 @@
     "need-now",
     "provenance",
     "venture-packages",
-    "venture-package"
+    "venture-package",
+    "release",
+    "naive-config",
+    "venture-types",
+    "frame",
+    "upgrade-registry",
+    "kit"
   ],
   "reads": [
     "product",
     "account",
-    "decision"
+    "decision",
+    "team-plan"
   ],
   "writes": [],
   "checks": [
@@ -39,7 +46,13 @@
     "schema/packages.mjs",
     "schema/packages-test.mjs",
     "schema/decision-analytics.mjs",
-    "schema/decision-analytics-test.mjs"
+    "schema/decision-analytics-test.mjs",
+    "schema/check-config.mjs",
+    "schema/gate-test.mjs",
+    "schema/upgrades.mjs",
+    "schema/upgrades-test.mjs",
+    "schema/triggers.mjs",
+    "schema/stale.mjs"
   ],
   "gaps": [],
   "name": "system"

package/schema/marketing-brand.schema.json

@@ -0,0 +1,116 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "marketing-brand.schema.json",
+  "title": "Brand",
+  "description": "The venture's brand tokens, in the marketing package at marketing/brand.json: colors, typefaces with their licenses, the font each role uses, voice rules (the global stylesheet for words), the logo and marks, outside design systems by reference, and scopes where a route prefix overrides the venture brand (nearer context wins). Read by every agent's layout and every interface; checked by schema/check-brand.mjs. Translates Next.js global CSS, next/font and file-based icons (Y-3, Y-4, Y-5, T-1, T-2, P-24). Version 0.x, unevaluated.",
+  "type": "object",
+  "required": ["version", "venture"],
+  "additionalProperties": false,
+  "$defs": {
+    "colors": {
+      "type": "object",
+      "description": "Token name -> hex color",
+      "propertyNames": { "pattern": "^[a-z][a-z0-9-]*$" },
+      "additionalProperties": { "type": "string", "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }
+    },
+    "fonts": {
+      "type": "object",
+      "description": "Role (body, heading, mono, display...) -> typeface id",
+      "propertyNames": { "pattern": "^[a-z][a-z0-9-]*$" },
+      "additionalProperties": { "type": "string" }
+    },
+    "rule": {
+      "type": "object",
+      "required": ["id", "avoid"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+        "avoid": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }], "description": "A phrase, or phrases, the venture's words never use; matched as whole words, ignoring case" },
+        "use": { "type": "string", "description": "What to write instead" },
+        "why": { "type": "string" }
+      }
+    },
+    "voice": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tone": { "type": "array", "items": { "type": "string" }, "description": "How the venture sounds, in a few words each" },
+        "rules": { "type": "array", "items": { "$ref": "#/$defs/rule" } }
+      }
+    }
+  },
+  "properties": {
+    "version": { "type": "string" },
+    "venture": { "type": "string" },
+    "name": { "type": "string", "description": "The name as the brand writes it" },
+    "colors": { "$ref": "#/$defs/colors" },
+    "typefaces": {
+      "type": "array",
+      "description": "Each typeface, defined once with its license (T-1). self-hosted: its files are in public/ and registered, so a browser makes no outside request; system: the reader's own fonts; remote: served from another host (the check fails it)",
+      "items": {
+        "type": "object",
+        "required": ["id", "family", "source"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+          "family": { "type": "string" },
+          "source": { "enum": ["self-hosted", "system", "remote"] },
+          "license": { "type": "string", "description": "An SPDX id such as OFL-1.1, or owned, or licensed" },
+          "files": { "type": "array", "items": { "type": "string", "pattern": "^public/" } },
+          "url": { "type": "string" },
+          "fallback": { "type": "array", "items": { "type": "string" } },
+          "credit": { "type": "string" }
+        }
+      }
+    },
+    "fonts": { "$ref": "#/$defs/fonts", "description": "The font each role uses everywhere, as the root layout applies it (T-2)" },
+    "voice": { "$ref": "#/$defs/voice" },
+    "marks": {
+      "type": "array",
+      "description": "The logo and marks (P-24), each a registered file in public/",
+      "items": {
+        "type": "object",
+        "required": ["kind", "asset"],
+        "additionalProperties": false,
+        "properties": {
+          "kind": { "enum": ["logo", "icon", "apple-icon", "favicon"] },
+          "asset": { "type": "string", "pattern": "^public/" },
+          "use": { "type": "string" }
+        }
+      }
+    },
+    "design_systems": {
+      "type": "array",
+      "description": "Outside design systems the brand builds on, by reference: linked, with a version and license, never copied in (Y-4)",
+      "items": {
+        "type": "object",
+        "required": ["id", "name", "url", "license"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+          "name": { "type": "string" },
+          "url": { "type": "string" },
+          "version": { "type": "string" },
+          "license": { "type": "string" },
+          "uses": { "type": "array", "items": { "type": "string" }, "description": "What the venture takes from it" }
+        }
+      }
+    },
+    "scopes": {
+      "type": "array",
+      "description": "Overrides for a route prefix (a package such as investors, or one item such as investors/deck). Nearer context wins: a deeper prefix over a shallower one, any scope over the venture brand (Y-5, T-2)",
+      "items": {
+        "type": "object",
+        "required": ["for"],
+        "additionalProperties": false,
+        "properties": {
+          "for": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*(/[a-z0-9][a-z0-9-]*)*$" },
+          "colors": { "$ref": "#/$defs/colors" },
+          "fonts": { "$ref": "#/$defs/fonts" },
+          "voice": { "$ref": "#/$defs/voice" },
+          "note": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/schema/migrate-venture.mjs

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

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

@@ -0,0 +1,95 @@
+// Migration kit-to-package (framework 0.3.0, EE-071): packages are Naive's, kits are Mentura's. The
+// first record migration, like a Next.js codemod that rewrites code for a renamed API:
+//
+//   1. naive.config.json: before 0.3.0, `kits` listed the venture's Naive packages. A name that is a
+//      Naive package moves into `packages` (pinned by the upgrader); a Mentura kit stays in `kits`; any
+//      other name is escalated, never guessed.
+//   2. Routes inside records: decision unlocks, the team plan's route globs (who may read and write
+//      what) and the where-used list's parent routes still name layer and kit routes
+//      (purpose/validation/solution). Each is rewritten to its package route through the route aliases
+//      (validation/solution), so access and locks keep meaning what they meant. A glob that spans
+//      routes now in several packages (purpose/**) cannot be rewritten safely and is escalated.
+//
+// Every change goes through ctx (schema/upgrades.mjs).
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ventureFile } from "../venture-paths.mjs";
+
+export const id = "kit-to-package";
+export const describe = "Moves Naive packages out of naive.config.json kits into packages, and rewrites layer and kit routes inside records (decision unlocks, team-plan access, where-used parents) to package routes";
+
+const repo = new URL("../..", import.meta.url).pathname;
+
+function aliases() {
+  const f = process.env.MENTURA_ROUTE_ALIASES ?? join(repo, "interface/route-aliases.json");
+  // Longest first, so purpose/validation/problem wins over a shorter alias it starts with.
+  return existsSync(f) ? JSON.parse(readFileSync(f, "utf8")).aliases.slice().sort((a, b) => b.from.length - a.from.length) : [];
+}
+
+/** A route or route glob rewritten through the aliases: { to } when it moved, { escalate } when it spans moved routes, else null. */
+export function rewriteRoute(route, list = aliases()) {
+  if (typeof route !== "string") return null;
+  const hit = list.find((a) => route === a.from || route.startsWith(`${a.from}/`));
+  if (hit) return { to: hit.to + route.slice(hit.from.length), alias: hit };
+  const star = route.indexOf("*");
+  if (star >= 0) {
+    const head = route.slice(0, star).replace(/\/$/, "");
+    // A glob from the root (**) still covers every route after the move.
+    const spans = head === "" ? [] : list.filter((a) => a.from === head || a.from.startsWith(`${head}/`));
+    if (spans.length) return { escalate: `${route} spans routes that moved to ${[...new Set(spans.map((a) => a.to.split("/")[0]))].join(", ")}` };
+  }
+  return null;
+}
+
+export function apply(dir, ctx) {
+  const list = aliases();
+
+  // 1. kits that are Naive packages become packages.
+  const cfg = ctx.config;
+  if (Array.isArray(cfg.kits) && cfg.kits.length) {
+    const keep = [];
+    for (const name of cfg.kits) {
+      if (existsSync(join(repo, "packages", name, "package.json"))) {
+        cfg.packages = { ...(cfg.packages ?? {}), [name]: cfg.packages?.[name] ?? {} };
+        ctx.note(`naive.config.json: ${name} is a Naive package, so it moved from kits to packages`);
+      } else if (existsSync(join(repo, "platform/kits", name, "kit.json"))) keep.push(name);
+      else { keep.push(name); ctx.escalate(`naive.config.json: kits names ${name}, which is neither a Naive package nor a Mentura kit; left as it is`); }
+    }
+    if (keep.length !== cfg.kits.length) ctx.configChanged();
+    if (keep.length) cfg.kits = keep; else delete cfg.kits;
+  }
+
+  // 2. Routes inside records.
+  const rewrite = (file, value, where) => {
+    const r = rewriteRoute(value, list);
+    if (!r) return value;
+    if (r.escalate) { ctx.escalate(`${file}: ${where} ${r.escalate}; rewrite it yourself`); return value; }
+    return r.to;
+  };
+  const rewriteFile = (file, fn) => {
+    if (!existsSync(ventureFile(dir, file))) return;
+    const before = readFileSync(ventureFile(dir, file), "utf8");
+    const rec = JSON.parse(before);
+    fn(rec);
+    const after = JSON.stringify(rec, null, 2) + "\n";
+    if (after.trim() !== before.trim()) ctx.write(file, after, { note: "routes renamed from layer and kit routes to package routes (EE-071)" });
+  };
+
+  const decisionFiles = (sub = "") => readdirSync(ventureFile(dir, sub), { withFileTypes: true }).flatMap((e) => {
+    const rel = sub ? `${sub}/${e.name}` : e.name;
+    if (e.isDirectory()) return e.name.startsWith(".") || e.name.startsWith("_") || existsSync(join(dir, rel, "venture.json")) ? [] : decisionFiles(rel);
+    return e.name.endsWith(".decision.json") ? [rel] : [];
+  });
+  for (const f of decisionFiles()) rewriteFile(f, (d) => {
+    for (const u of d.unlocks ?? []) if (Array.isArray(u.routes)) u.routes = u.routes.map((g) => rewrite(f, g, "unlocks route"));
+  });
+
+  for (const f of ["people/team-plan.json", "operations/team-plan.json"]) rewriteFile(f, (p) => {
+    for (const role of p.roles ?? []) for (const k of ["read", "write"]) if (Array.isArray(role.routes?.[k])) role.routes[k] = role.routes[k].map((g) => rewrite(f, g, `role ${role.id} ${k}`));
+  });
+
+  rewriteFile("knowledge/where-used.json", (w) => {
+    for (const fact of w.facts ?? []) if (fact.parent?.route) fact.parent.route = rewrite("knowledge/where-used.json", fact.parent.route, `fact ${fact.id} parent`);
+  });
+}

package/schema/migrations/package-layout.mjs

@@ -0,0 +1,90 @@
+// Migration package-layout (framework 0.2.0, EE-070): moves a venture from the layer layout onto
+// the package folder layout, like a Next.js codemod. Files move with git mv when git tracks them and
+// with a plain rename otherwise. A file with no clear new home is archived under _private/ and
+// escalated for a person, never guessed. Old routes keep resolving through interface/route-aliases.json.
+//
+// Every change goes through ctx (schema/upgrades.mjs), so a dry run (--check) reports the same moves
+// without touching anything, and the upgrader records each one in provenance.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ventureFile } from "../venture-paths.mjs";
+import { layoutOf } from "../venture-paths.mjs";
+
+export const id = "package-layout";
+export const describe = "Moves records from the layer folders (purpose/, pillars/, products/, knowledge/) into package folders (foundation/, validation/, product/, marketing/, people/, decisions/)";
+
+export function apply(dir, ctx) {
+  // A venture in the structured layout (EE-086) is already past this layout: nothing to move.
+  if (layoutOf(dir) === "structured") return;
+  const load = (p) => JSON.parse(readFileSync(p, "utf8"));
+  // A decision file infers its target from the folder it sits in. Stamp that path before the file
+  // moves, so the decision still points at the same record.
+  const stampDecisions = (folder) => {
+    const d = ventureFile(dir, folder);
+    if (!existsSync(d)) return;
+    for (const f of readdirSync(d).filter((x) => x.endsWith(".decision.json"))) {
+      const rec = load(join(d, f));
+      if (rec.decides?.path) continue;
+      const at = folder.split("/").slice(0, -1).join("/");
+      const base = f.split(".")[0];
+      rec.decides = { ...(rec.decides ?? {}), path: at ? `${at}/${base}.json` : `${base}.json` };
+      ctx.write(`${folder}/${f}`, JSON.stringify(rec, null, 2) + "\n", { note: "stamped the record it decides before the move (EE-070)", log: false });
+    }
+  };
+
+  const pairs = [
+    ["purpose/validation/problem.json", "foundation/problem.json"],
+    ["purpose/icp.json", "foundation/icp.json"],
+    ["purpose/alignment.json", "foundation/alignment.json"],
+    ["purpose/telos.draft.md", "foundation/telos.draft.md"],
+    ["purpose/validation/solution.json", "validation/solution.json"],
+    ["purpose/validation/go-to-market.json", "validation/go-to-market.json"],
+    ["operations/team-plan.json", "people/team-plan.json"],
+    ["pillars/brand.md", "marketing/brand.md"],
+    // A venture made since init writes a root AGENTS.md keeps it; the old README becomes the knowledge layout.
+    ["knowledge/README.md", existsSync(join(dir, "AGENTS.md")) ? "knowledge/AGENTS.md" : "AGENTS.md"],
+    ["purpose/anatomy.answers.reasoned.json", "product/anatomy.answers.reasoned.json"],
+    ["purpose/anatomy.matrix.md", "product/anatomy.matrix.md"],
+  ];
+  for (const [a, b] of pairs) ctx.mv(a, b);
+
+  const list = (rel, ext) => existsSync(ventureFile(dir, rel)) ? readdirSync(ventureFile(dir, rel)).filter((f) => f.endsWith(ext)) : [];
+  for (const f of list("products", ".json")) ctx.mv(`products/${f}`, `product/${f}`);
+  for (const f of list("purpose/anatomy", ".json")) ctx.mv(`purpose/anatomy/${f}`, `product/anatomy/${f}`);
+
+  for (const folder of ["purpose/decisions", "purpose/anatomy/decisions", "operations/decisions"]) {
+    stampDecisions(folder);
+    for (const f of list(folder, ".decision.json")) ctx.mv(`${folder}/${f}`, `decisions/${f}`);
+  }
+
+  for (const f of ["product.md", "business.md"]) {
+    if (existsSync(join(ventureFile(dir, "pillars"), f))) {
+      ctx.mv(`pillars/${f}`, `_private/pillars/${f}`);
+      ctx.escalate(`${f.replace(".md", "")} pillar: the brief names a home only for brand (marketing/). Archived at _private/pillars/${f} rather than guessed.`);
+    }
+  }
+  for (const f of list("purpose/research", "")) {
+    ctx.mv(`purpose/research/${f}`, `_private/research/${f}`);
+    ctx.escalate(`purpose/research/${f}: no package home in the route table. Archived at _private/research/${f}.`);
+  }
+
+  for (const gone of ["purpose", "pillars", "knowledge", "products"]) ctx.removeEmpty(gone);
+
+  const policy = "governance/publication-policy.json";
+  if (existsSync(ventureFile(dir, policy))) {
+    const text = readFileSync(ventureFile(dir, policy), "utf8");
+    if (text.includes("pillars/brand.md")) ctx.write(policy, text.replaceAll("pillars/brand.md", "marketing/brand.md"), { note: "the brand pillar moved to marketing/brand.md (EE-070)" });
+  }
+
+  for (const sub of ["raw/dump", "raw/sources", "ideas", "finance", "customers", "investors", "money", "public"]) ctx.keep(sub);
+
+  // The layout release, as before: the moves this migration made and what it escalated.
+  if (ctx.moved.length || ctx.escalated.length) ctx.write(".release/layout.json", JSON.stringify({
+    version: 1,
+    at: ctx.at,
+    note: "Moved onto the package folder layout (EE-070). Old routes stay as aliases for one release.",
+    moves: ctx.moved.map(([from, to]) => ({ from, to })),
+    escalated: ctx.escalated,
+  }, null, 2) + "\n", { activity: "release", note: "package folder layout", derived_from: ctx.moved.map(([, to]) => to) });
+}