naive-framework 0.0.0-stage → 0.2.0

package/schema/marketing-sitemap.schema.json

@@ -0,0 +1,232 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "marketing-sitemap.schema.json",
+  "title": "Marketing sitemap",
+  "description": "The planned public site (EE-064): which information is shown where, how (the MDX component), when and for whom, with the reasons, planned from the venture's records by operations/marketing/site/plan.mjs. A marketing record, part of the marketing package handed to engineering (EE-065). Version 0.x, unevaluated.",
+  "type": "object",
+  "required": [
+    "version",
+    "venture",
+    "facts",
+    "offerings",
+    "audience",
+    "pages",
+    "omitted",
+    "handoff"
+  ],
+  "properties": {
+    "version": {
+      "type": "string"
+    },
+    "venture": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string"
+    },
+    "phase": {
+      "type": "string"
+    },
+    "planned_at": {
+      "type": "string"
+    },
+    "planned_by": {
+      "enum": [
+        "jev",
+        "conventions"
+      ]
+    },
+    "facts": {
+      "type": "object"
+    },
+    "offerings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "offering",
+          "offered_to"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "offering": {
+            "enum": [
+              "product",
+              "service",
+              "platform",
+              "content",
+              "marketplace"
+            ]
+          },
+          "status": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "offered_to": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "serves": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "from": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "audience": {
+      "type": "object",
+      "required": [
+        "offered_to",
+        "partner_led",
+        "types"
+      ],
+      "properties": {
+        "offered_to": {
+          "type": "array"
+        },
+        "partner_led": {
+          "type": "boolean"
+        },
+        "types": {
+          "type": "array"
+        },
+        "weights": {
+          "type": "object"
+        },
+        "note": {
+          "type": "string"
+        }
+      }
+    },
+    "pages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "path",
+          "parent",
+          "label",
+          "type",
+          "level",
+          "sections"
+        ],
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "parent": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "label": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          },
+          "level": {
+            "enum": [
+              "home",
+              "nav",
+              "linked",
+              "anywhere"
+            ]
+          },
+          "sections": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "item",
+                "component",
+                "need",
+                "for",
+                "why",
+                "source",
+                "variant"
+              ],
+              "properties": {
+                "item": {
+                  "type": "string"
+                },
+                "label": {
+                  "type": "string"
+                },
+                "component": {
+                  "type": "string"
+                },
+                "need": {
+                  "type": "number"
+                },
+                "required": {
+                  "type": "string"
+                },
+                "for": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "why": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "when": {
+                  "type": "string"
+                },
+                "source": {
+                  "type": "object"
+                },
+                "variant": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "omitted": {
+      "type": "array"
+    },
+    "handoff": {
+      "type": "object",
+      "required": [
+        "to"
+      ],
+      "properties": {
+        "to": {
+          "const": "engineering"
+        },
+        "note": {
+          "type": "string"
+        },
+        "variants": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/schema/migrate-venture.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+// naive migrate: brings an existing project into a new venture by rewriting it into the Naive
+// convention (EE-076). An agent reads the project's text and proposes records in the shape of
+// Naive's own schemas; nothing lands until a person decides, one decision per function; then each
+// record is written through the router, so its schema, gates and provenance all apply. Port (files
+// kept as they are) is the other way in: schema/port-venture.mjs.
+//
+//   node schema/migrate-venture.mjs --from <project> --venture <new venture dir>
+//        the agent writes the plan to <venture>/.release/migrate-plan.json and proposes the decisions
+//   node schema/migrate-venture.mjs --venture <dir> --apply
+//        writes what a person decided ("bring in", "point to them" or "leave them"); open decisions wait
+//
+// The project is only ever read, and the agent gets its text and no tools. Files that look like
+// secrets are never opened. The agent is `claude -p` with no tools, or MENTURA_AGENT_CMD (a command
+// that reads the prompt on stdin and prints the answer).
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+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";
+
+export const PLAN = ".release/migrate-plan.json";
+const MAX_FILE = 512 * 1024;
+const MAX_PROMPT = 200_000;
+const SKIP = new Set(["node_modules", ".git", ".next", ".naive", "dist", "build", ".venv", "venv", "__pycache__"]);
+// Never opened: credentials and keys, by name, whatever is in them.
+export const SECRET = /(^|\/)(\.env(\..*)?|.*\.(pem|key|p12|pfx|secret)|id_rsa.*|id_ed25519.*|credentials(\.json)?|\.npmrc|\.netrc)$/i;
+const ANSWERS = { bring: "bring in", point: "point to them", leave: "leave them" };
+const load = (p) => JSON.parse(readFileSync(p, "utf8"));
+const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "project";
+const functionOf = (route) => route.split("/")[0];
+
+/** The project's readable text files; what it will not read is listed with why. */
+export function scan(src) {
+  const files = [], skipped = [];
+  const walk = (rel) => {
+    for (const e of readdirSync(join(src, rel), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const r = rel ? join(rel, e.name) : e.name;
+      if (e.isDirectory()) { if (!SKIP.has(e.name) && !e.name.startsWith(".")) walk(r); continue; }
+      if (!e.isFile()) continue;
+      if (SECRET.test(r)) { skipped.push({ from: r, why: "looks like a secret, so it was not opened" }); continue; }
+      if (e.name.startsWith(".")) continue;
+      if (statSync(join(src, r)).size > MAX_FILE) { skipped.push({ from: r, why: `larger than ${MAX_FILE / 1024} KB` }); continue; }
+      const buf = readFileSync(join(src, r));
+      if (buf.includes(0)) { skipped.push({ from: r, why: "not text, so the agent cannot read it" }); continue; }
+      files.push({ path: r, text: buf.toString("utf8") });
+    }
+  };
+  walk("");
+  return { files, skipped };
+}
+
+/** Runs the agent on a prompt and returns its text. A login problem or refusal is an error that says so. */
+export function runAgent(prompt) {
+  const cmd = process.env.MENTURA_AGENT_CMD ? process.env.MENTURA_AGENT_CMD.split(" ") : ["claude", "-p", "--output-format", "json", "--tools", "", "--strict-mcp-config"];
+  const p = spawnSync(cmd[0], cmd.slice(1), { input: prompt, encoding: "utf8", maxBuffer: 1 << 26 });
+  if (p.error) throw new Error(`could not run the agent (${cmd[0]}): ${p.error.message}`);
+  let text = p.stdout;
+  try { const r = JSON.parse(p.stdout); if (r && typeof r.result === "string") { if (r.is_error) throw new Error(`the agent stopped: ${r.result}`); text = r.result; } }
+  catch (e) { if (e.message.startsWith("the agent stopped")) throw e; }
+  if (p.status !== 0) throw new Error(`the agent stopped with status ${p.status}: ${(p.stderr || text).trim().slice(0, 500)}${/login/i.test(p.stderr + text) ? " (run claude, then /login)" : ""}`);
+  return text;
+}
+
+// The routes a migrated record can be written to: JSON records the router can write.
+const writable = () => routes().filter((r) => r.kind === "record" && r.record && r.actions.includes("write") && r.files?.some((g) => g.endsWith(".json")) && r.collection !== "list" && r.record !== "provenance");
+
+/** The plan for migrating `from` into the venture at `dir`: the agent's records, checked against the routes. */
+export function plan(from, dir, { agent = runAgent } = {}) {
+  const src = resolve(from);
+  if (!existsSync(src) || !statSync(src).isDirectory()) throw new Error(`${from} is not a directory`);
+  if (!existsSync(join(dir, "venture.json"))) throw new Error(`${dir} is not a venture: create one first with naive init`);
+  if (resolve(dir).startsWith(src + sep) || resolve(dir) === src) throw new Error("the venture cannot sit inside the project it migrates from");
+  const { files, skipped } = scan(src);
+  const left = [...skipped], given = [];
+  let size = 0;
+  for (const f of files) {
+    if (size + f.text.length > MAX_PROMPT) { left.push({ from: f.path, why: "past what one agent pass reads; migrate the rest in another pass" }); continue; }
+    size += f.text.length; given.push(f);
+  }
+  const rs = writable();
+  const schemaOf = (r) => { try { return load(join(dirname(fileURLToPath(import.meta.url)), "..", r.schema)); } catch { return null; } };
+  const prompt = `You are moving an existing project into Naive, a venture development framework. Read the files below and rewrite what they contain as Naive records.
+
+Rules:
+- Use only the routes listed, and make each record match its JSON schema exactly. For a route with [id], put the id in the route (product/kettle).
+- Use only what the files say. Do not invent facts; leave out a field you cannot fill from them.
+- One file can feed several records, and several files can feed one.
+- Every file you do not use goes in left_behind, with why.
+Answer with JSON only, no prose: {"items": [{"route": "...", "from": ["path", ...], "record": {...}, "reshaping": "what you changed and why", "confidence": 0.0-1.0}], "left_behind": [{"from": "path", "why": "..."}]}
+
+Routes and schemas: ${JSON.stringify(rs.map((r) => ({ route: r.route, record: r.record, schema: schemaOf(r) })))}
+
+Files: ${JSON.stringify(Object.fromEntries(given.map((f) => [f.path, f.text])))}`;
+  const text = agent(prompt);
+  const start = text.indexOf("{"), end = text.lastIndexOf("}");
+  if (start < 0) throw new Error(`the agent did not answer with JSON: ${text.trim().slice(0, 300)}`);
+  const answer = JSON.parse(text.slice(start, end + 1));
+  const known = new Map(rs.map((r) => [r.route, r]));
+  const items = [], used = new Set();
+  for (const it of answer.items ?? []) {
+    const base = it.route?.replace(/\/[a-z0-9-]+$/, "/[id]");
+    const r = known.get(it.route) ?? (known.get(base)?.collection === "item" ? known.get(base) : null);
+    const cited = (it.from ?? []).filter((p) => given.some((f) => f.path === p));
+    if (!r || !cited.length || typeof it.record !== "object") { left.push({ from: (it.from ?? []).join(", ") || "(none)", why: `the agent proposed ${it.route ?? "no route"}, which is not a record route or cites no file it was given` }); continue; }
+    cited.forEach((p) => used.add(p));
+    items.push({ id: `m-${items.length + 1}`, from: cited, route: it.route, record: it.record, reshaping: String(it.reshaping ?? ""), confidence: Number(it.confidence ?? 0.5), status: "planned" });
+  }
+  for (const l of answer.left_behind ?? []) if (l?.from) { used.add(l.from); left.push({ from: l.from, why: String(l.why ?? "the agent left it") }); }
+  for (const f of given) if (!used.has(f.path)) left.push({ from: f.path, why: "the agent did not place it" });
+  return { from: src, venture: load(join(dir, "venture.json")).id, at: new Date().toISOString(), items, left_behind: left };
+}
+
+/** 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");
+  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]);
+  const proposed = [];
+  for (const [fn, its] of groups) {
+    const r = propose(dir, {
+      id: `migrate-${fn}`,
+      question: `Migrate ${its.length} record${its.length === 1 ? "" : "s"} from ${basename(p.from)} into ${fn}, as ${PLAN} plans them?`,
+      options: Object.values(ANSWERS), answer: ANSWERS.bring, decides: { path: PLAN },
+      note: its.map((it) => `${it.id}: ${it.from.join(", ")} -> ${it.route}`).join("; "),
+    }, { agentId: "naive-migrate", via: "migrate" });
+    if (!r.ok) throw new Error(r.error);
+    proposed.push(r.result.proposed);
+  }
+  return proposed;
+}
+
+const answerOf = (d) => { const a = String(d?.answer ?? "").toLowerCase(); return a.startsWith("point") ? "point" : a.startsWith("leave") ? "leave" : a.startsWith("bring") ? "bring" : null; };
+
+/** 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 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")) {
+    const d = decisionOf(functionOf(it.route));
+    if (d?.status !== "decided") { done.waiting++; continue; }
+    const a = answerOf(d);
+    if (a === "leave" || !a) { it.status = "left"; done.left++; continue; }
+    if (a === "point") { it.status = "pointed"; pointed = true; done.pointed++; continue; }
+    const r = await call({ workspace: dirname(dir), venture: basename(dir), route: it.route, action: "write", input: it.record, actor: "agent", actor_id: "naive-migrate", via: "migrate",
+      provenance: { note: `migrated from ${it.from.map((f) => join(p.from, f)).join(", ")}: ${it.reshaping}`, decision: d.id, derived_from: it.from.map((f) => `file://${join(p.from, f)}`) } });
+    if (!r.ok) { it.status = "failed"; it.why = r.error; done.failed++; continue; }
+    it.status = r.result?.draft ? "drafted" : "brought";
+    it.at = r.result?.draft ?? r.result?.written;
+    done[it.status]++;
+  }
+  if (pointed) {
+    const f = join(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" });
+    mkdirSync(dirname(f), { recursive: true });
+    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");
+  return done;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = process.argv.slice(2);
+  const opt = (k) => { const i = args.indexOf(`--${k}`); return i < 0 ? undefined : args[i + 1]; };
+  const dir = opt("venture");
+  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); }
+      const d = await apply(dir);
+      console.log(Object.entries(d).filter(([, n]) => n).map(([k, n]) => `${n} ${k}`).join(", ") || "nothing to do");
+    } else {
+      if (!opt("from")) { console.error("--from <project> is needed to write a plan"); process.exit(2); }
+      const p = plan(opt("from"), dir);
+      const decisions = proposeDecisions(dir, p);
+      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.`);
+    }
+  } catch (e) { console.error(e.message); process.exit(1); }
+}

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

@@ -0,0 +1,94 @@
+// 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";
+
+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(join(dir, file))) return;
+    const before = readFileSync(join(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(join(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,86 @@
+// 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";
+
+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) {
+  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 = join(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(join(dir, rel)) ? readdirSync(join(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(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(join(dir, policy))) {
+    const text = readFileSync(join(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) });
+}