naive-framework 0.2.0 → 0.4.0

package/schema/port-venture.mjs

@@ -1,161 +1,235 @@
 #!/usr/bin/env node
-// naive port: brings an existing project into a new venture by keeping its files as they are (EE-076).
-// Each file is placed, unchanged, in the package directory its name or folder points to; a code
-// repository or anything that should stay where it is becomes a pointer in knowledge/sources.json;
-// what fits nowhere is left behind, by name, so nothing disappears silently. Migrate (rewriting a
-// project into the Naive convention) is the other way in, and is not this command.
+// naive port: moves an existing folder into a venture, as it is (EE-076, revised by Torian on
+// 2026-10-29: port moves, it no longer copies files into packages). The folder is moved whole, with a
+// rename, so not one file in it is opened or changed; the venture names it in sources.json as a source
+// of truth (a read-only filesystem source) and logs the move in provenance.jsonl with the path it came
+// from. Migrate (rewriting a project into the Naive convention) is the other way in.
 //
-//   node schema/port-venture.mjs --from <project> --venture <new venture dir>
-//        writes the plan to <venture>/.release/port-plan.json and prints it; changes nothing else
-//   node schema/port-venture.mjs --venture <dir> --apply --confirm port
-//        carries out the plan as it now reads; the founder may first set any item's action to
-//        port, point or leave
+//   node schema/port-venture.mjs <folder> --venture <dir> [--to <path>] [--links <dir> ...]
+//        adds the move to the plan at <venture>/.release/port-plan.json and prints it; moves nothing.
+//        The folder goes to <venture>/codebase/<its name> unless --to says where (relative to the venture
+//        or absolute). Run once per folder: each run adds or replaces that folder's item.
+//   node schema/port-venture.mjs --venture <dir> --apply --confirm port [--even-if-busy]
+//        carries out every planned move the founder left as move; any item can be set to leave first
 //
-// The project is only ever read. A port never overwrites a file in the venture, refuses a plan
-// whose source files changed since it was written, and records every copy in provenance.jsonl
-// with the source path it was derived from.
+// The plan says what a move would break: worktrees of a git repository (they point at its old path
+// until `git worktree repair` runs from the new one), symbolic links that point into the folder, and
+// processes working inside it, which refuse the apply unless --even-if-busy. A port never overwrites,
+// never copies (a move across disks is refused, not copied), and refuses an item whose folder changed
+// identity since the plan. Every run writes a trace to .release/port-trace.json, in the shape
+// platform/integrations/langsmith.mjs uploads.
 
+import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
-import { record } from "../interface/provenance.mjs";
-import { SECRET } from "./migrate-venture.mjs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { agentFromEnv, record } from "../interface/provenance.mjs";
+import { CODEBASE, ventureFile } from "./venture-paths.mjs";
 
 export const PLAN = ".release/port-plan.json";
-const SKIP = new Set([".git", "node_modules", ".next", ".turbo", "dist", "build", ".venv", "__pycache__", ".DS_Store"]);
-const REPO_MARKERS = [".git", "package.json", "Cargo.toml", "go.mod", "pyproject.toml", "Gemfile", "pom.xml"];
-const CODE = new Set([".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx", ".py", ".rb", ".go", ".rs", ".java", ".kt", ".swift", ".c", ".h", ".cpp", ".cs", ".php", ".sh", ".sql", ".css", ".scss", ".html", ".lock", ".yml", ".yaml", ".toml"]);
-const MAX_BYTES = 5 * 1024 * 1024;
+export const TRACE = ".release/port-trace.json";
+const MAP = "knowledge/sources.json";
+const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^[^a-z]+|-$/g, "") || "folder";
+const inside = (a, b) => a === b || a.startsWith(b + sep);
+const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
 
-// The first rule whose pattern matches wins: the file name is tried before its folders, so a file
-// says more about itself than the folder it sits in. Patterns match words in lowercase paths.
-const RULES = [
-  [/\b(problem|pain[- ]?points?)\b/, "foundation", "states the problem"],
-  [/\b(icp|personas?|ideal[- ]customer|customer[- ]profile|segments?)\b/, "foundation", "describes the customer"],
-  [/\b(vision|mission|tagline|values|manifesto|one[- ]pager|strategy)\b/, "foundation", "states what the venture is for"],
-  [/\b(interviews?|surveys?|user[- ]research|customer[- ]research|discovery|experiments?|hypothes[ie]s|validation)\b/, "validation", "is evidence about the problem or the solution"],
-  [/\b(investors?|pitch|deck|fundrais\w*|safe|term[- ]sheet|cap[- ]table|data[- ]room)\b/, "investors", "is for or about investors"],
-  [/\b(pricing|prices?|revenue|budget|forecast|runway|financ\w*|p&l|burn|unit[- ]economics|model)\b/, "finance", "is about money the venture plans or earns"],
-  [/\b(brand\w*|marketing|copy|landing|seo|social|launch|blog|newsletter|campaigns?|content|go[- ]to[- ]market|gtm)\b/, "marketing", "is marketing or sales"],
-  [/\b(roadmap|specs?|prd|requirements|features?|product|designs?|ux|ui|wireframes?|mockups?|backlog)\b/, "product", "describes the product"],
-  [/\b(team|hiring|roles?|org[- ]chart|founders?|equity|vesting|people|onboarding|handbook|culture)\b/, "people", "is about the people"],
-  [/\b(customers?|clients?|accounts|crm|leads|pipeline)\b/, "customers", "is about customers"],
-  [/\b(decisions?|adrs?|decision[- ]log)\b/, "decisions", "records decisions"],
-  [/\b(legal|contracts?|agreements?|incorporation|bylaws|operating[- ]agreement|nda|terms|privacy|trademark|ip)\b/, "_private/legal", "is a legal document, kept private so it never reaches a model"],
-];
-const BANK = /\b(bank|transactions?|ledger|payroll|tax(es)?)\b/;
+// Files and bytes under a folder, without following links, to show the size of what moves, and a
+// manifest hash (each path with its size, never its contents) for the provenance entry.
+function measure(root) {
+  let files = 0, bytes = 0;
+  const lines = [];
+  const stack = [root];
+  while (stack.length) {
+    const d = stack.pop();
+    let list = [];
+    try { list = readdirSync(d, { withFileTypes: true }); } catch { continue; }
+    for (const e of list) {
+      const p = join(d, e.name);
+      if (e.isDirectory()) stack.push(p);
+      else { files++; let n = 0; try { n = lstatSync(p).size; } catch {} bytes += n; lines.push(`${relative(root, p)} ${n}`); }
+    }
+  }
+  return { files, bytes, manifest: createHash("sha256").update(lines.sort().join("\n")).digest("hex") };
+}
 
-const words = (s) => s.toLowerCase().replace(/[_.]+/g, " ");
-const sha = (f) => createHash("sha256").update(readFileSync(f)).digest("hex");
-const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "project";
+// Symbolic links under `roots` (to `depth` levels, skipping node_modules) whose target is inside `src`.
+// A link inside `src` that points inside it with a relative path keeps working, so only absolute ones count.
+export function linksInto(src, roots, depth = 4) {
+  const out = [];
+  const seen = new Set();
+  const visit = (d, n) => {
+    if (n > depth || seen.has(d)) return;
+    seen.add(d);
+    let list = [];
+    try { list = readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of list) {
+      if (e.name === "node_modules" || e.name === ".git") continue;
+      const p = join(d, e.name);
+      if (e.isSymbolicLink()) {
+        const t = readlinkSync(p);
+        const target = resolve(dirname(p), t);
+        if (inside(target, src) && !(inside(p, src) && !isAbsolute(t))) out.push({ link: p, target: t });
+      } else if (e.isDirectory()) visit(p, n + 1);
+    }
+  };
+  for (const r of roots) visit(resolve(r), 0);
+  return out;
+}
 
-/** Where one file goes, or why it stays behind. `rel` is relative to the project root. */
-export function place(rel, bytes) {
-  const name = basename(rel, extname(rel));
-  const ext = extname(rel).toLowerCase();
-  if (bytes > MAX_BYTES) return { action: "leave", reason: `larger than ${MAX_BYTES / 1024 / 1024} MB; point to it instead` };
-  if (CODE.has(ext)) return { action: "leave", reason: "code or configuration: it stays in its repository" };
-  const folders = dirname(rel) === "." ? [] : dirname(rel).split(sep).reverse();
-  for (const [where, confidence] of [[name, "high"], ...folders.map((f) => [f, "low"])]) {
-    if (BANK.test(words(where))) return { action: "leave", reason: "bank and payroll data come from the bank connection, not from files" };
-    const hit = RULES.find(([re]) => re.test(words(where)));
-    if (hit) return { action: "port", to: `${hit[1]}/${basename(rel)}`, function: hit[1].split("/").at(-1), confidence, reason: `${confidence === "high" ? "its name" : `its folder ${where}`} ${hit[2]}` };
-  }
-  if (/^readme$/i.test(name)) return { action: "leave", reason: "the venture has its own AGENTS.md and profile.md; read this to write profile.md" };
-  return { action: "leave", reason: "nothing in its name or folders matches a package; place it by hand or migrate it" };
+// The git facts a move touches: whether the folder is a repository, its other worktrees, and how
+// many changes are uncommitted (the move keeps them; it is only said).
+function git(src) {
+  const g = join(src, ".git");
+  if (!existsSync(g)) return null;
+  if (statSync(g).isFile()) return { linked: true, worktrees: [], uncommitted: null };
+  const run = (...a) => spawnSync("git", ["-C", src, ...a], { encoding: "utf8" });
+  const wt = (run("worktree", "list", "--porcelain").stdout ?? "").split("\n").filter((l) => l.startsWith("worktree ")).map((l) => l.slice(9)).filter((p) => real(p) !== real(src));
+  const st = run("status", "--porcelain");
+  return { linked: false, worktrees: wt, uncommitted: st.status === 0 ? st.stdout.split("\n").filter(Boolean).length : null };
 }
 
-function walk(root, rel = "", out = { files: [], repos: [], secrets: [] }) {
-  for (const e of readdirSync(join(root, rel), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-    if (SKIP.has(e.name) || e.isSymbolicLink()) continue;
-    const r = rel ? join(rel, e.name) : e.name;
-    if (e.isDirectory()) {
-      if (REPO_MARKERS.some((m) => existsSync(join(root, r, m)))) out.repos.push(r);
-      else walk(root, r, out);
-    } else if (e.isFile() && SECRET.test(r)) out.secrets.push(r);
-    else if (e.isFile() && !e.name.startsWith(".")) out.files.push(r);
+// Processes whose working directory is inside the folder (macOS and Linux lsof).
+export function busy(src) {
+  const r = spawnSync("lsof", ["-d", "cwd", "-Fpcn"], { encoding: "utf8" });
+  if (r.error || !r.stdout) return [];
+  const out = [];
+  let p = null, c = null;
+  for (const l of r.stdout.split("\n")) {
+    if (l[0] === "p") p = l.slice(1);
+    else if (l[0] === "c") c = l.slice(1);
+    else if (l[0] === "n" && inside(l.slice(1), real(src)) && p !== String(process.pid)) out.push({ pid: Number(p), command: c, cwd: l.slice(1) });
   }
   return out;
 }
 
-/** The plan for porting `from` into the venture at `dir`. Reads both, writes neither. */
-export function plan(from, dir) {
-  const src = resolve(from);
-  if (!existsSync(src) || !statSync(src).isDirectory()) throw new Error(`${from} is not a directory`);
+const readPlan = (dir) => existsSync(ventureFile(dir, PLAN)) ? JSON.parse(readFileSync(ventureFile(dir, PLAN), "utf8")) : null;
+const readMap = (dir) => existsSync(ventureFile(dir, MAP)) ? JSON.parse(readFileSync(ventureFile(dir, MAP), "utf8")) : { sources: [], records: {} };
+
+/** The planned move of `folder` into the venture at `dir`. Reads both, writes neither. */
+export function planOne(folder, dir, { to, links = [] } = {}) {
+  if (!existsSync(folder) || !lstatSync(folder).isDirectory()) throw new Error(`${folder} 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 ports from");
-  const { files, repos, secrets } = walk(src);
-  const items = secrets.map((f) => ({ from: f, action: "leave", reason: "looks like a secret, so it was never opened" }));
-  // The project itself is a repository when it carries a marker at its root: point to it, and still
-  // port its documents.
-  for (const r of REPO_MARKERS.some((m) => existsSync(join(src, m))) ? ["", ...repos] : repos)
-    items.push({ from: r || ".", action: "point", source: slug(r ? basename(r) : basename(src)), reason: "a code repository stays where it is; the venture points to it" });
-  const taken = new Set();
-  for (const f of files) {
-    const p = place(f, statSync(join(src, f)).size);
-    if (p.action === "port") {
-      // Two files with one name in one package: the second keeps its folder name in front.
-      if (taken.has(p.to)) p.to = `${dirname(p.to)}/${slug(basename(dirname(f)))}-${basename(f)}`;
-      if (taken.has(p.to) || existsSync(join(dir, p.to))) Object.assign(p, { action: "leave", reason: `${p.to} already exists in the venture; a port never overwrites` });
-      else taken.add(p.to);
-    }
-    items.push({ from: f, sha256: sha(join(src, f)), ...p });
-  }
-  const count = (a) => items.filter((i) => i.action === a).length;
-  return { from: src, venture: JSON.parse(readFileSync(join(dir, "venture.json"), "utf8")).id, at: new Date().toISOString(),
-    summary: { port: count("port"), point: count("point"), leave: count("leave") }, items };
+  const src = real(folder);
+  const v = real(dir);
+  if (inside(v, src)) throw new Error("the venture cannot sit inside the folder it ports");
+  const dest = resolve(v, to ?? join(CODEBASE, basename(src)));
+  const s = statSync(src);
+  const item = { action: "move", from: src, to: dest, source: slug(basename(src)), identity: { dev: s.dev, ino: s.ino }, ...measure(src) };
+  const warnings = [];
+  const leave = (why) => Object.assign(item, { action: "leave", reason: why });
+  if (existsSync(dest)) leave(`${dest} already exists; a port never overwrites`);
+  else if (inside(dest, src)) leave("the destination is inside the folder itself");
+  else if (!inside(dest, v)) warnings.push("the destination is outside the venture folder; sources.json will name it by absolute path");
+  // A rename only works on one disk: the nearest existing parent of the destination must share it.
+  let up = dirname(dest);
+  while (!existsSync(up)) up = dirname(up);
+  if (item.action === "move" && statSync(up).dev !== s.dev) leave("the destination is on another disk; a port moves, it never copies");
+  if (item.action === "move" && readMap(dir).sources.some((x) => x.id === item.source)) leave(`sources.json already has a source ${item.source}`);
+  const g = git(src);
+  item.git = g;
+  if (g?.linked) warnings.push("this folder is a linked git worktree; its main repository will point at the old path until `git worktree repair` runs there");
+  if (g?.worktrees.length) warnings.push(`${g.worktrees.length} worktree${g.worktrees.length === 1 ? "" : "s"} of this repository point at its old path until \`git -C ${dest} worktree repair\` runs: ${g.worktrees.join(", ")}`);
+  if (g?.uncommitted) warnings.push(`${g.uncommitted} uncommitted change${g.uncommitted === 1 ? "" : "s"} move with it, unchanged`);
+  item.links = linksInto(src, [dirname(src), src, ...links]);
+  if (item.links.length) warnings.push(`${item.links.length} symbolic link${item.links.length === 1 ? "" : "s"} point into it and will break: ${item.links.map((x) => x.link).join(", ")}`);
+  item.busy = busy(src);
+  if (item.busy.length) warnings.push(`${item.busy.length} process${item.busy.length === 1 ? " is" : "es are"} working inside it (${[...new Set(item.busy.map((x) => x.command))].join(", ")}); apply refuses unless --even-if-busy`);
+  item.warnings = warnings;
+  return item;
 }
 
-/** Carries out a plan as the founder left it. Returns what was done. */
-export function apply(dir, p, agent = { kind: "person", via: "cli" }) {
-  const src = p.from;
-  for (const i of p.items.filter((x) => x.action === "port")) {
-    if (!existsSync(join(src, i.from)) || sha(join(src, i.from)) !== i.sha256) throw new Error(`${i.from} changed since the plan was written; write the plan again`);
-    if (existsSync(join(dir, i.to))) throw new Error(`${i.to} already exists in the venture; a port never overwrites`);
+/** Adds (or replaces) one folder's item in the venture's plan and writes it. */
+export function plan(folder, dir, opts = {}) {
+  const item = planOne(folder, dir, opts);
+  const p = readPlan(dir) ?? { venture: JSON.parse(readFileSync(join(dir, "venture.json"), "utf8")).id, items: [] };
+  const others = p.items.filter((i) => i.from !== item.from && i.action === "move" && !i.done);
+  if (others.some((i) => i.source === item.source)) Object.assign(item, { action: "leave", reason: `another planned move already uses the source id ${item.source}` });
+  if (others.some((i) => i.to === item.to)) Object.assign(item, { action: "leave", reason: `another planned move already goes to ${item.to}` });
+  p.items = [...p.items.filter((i) => i.from !== item.from || i.done), item];
+  p.at = new Date().toISOString();
+  mkdirSync(dirname(ventureFile(dir, PLAN)), { recursive: true });
+  writeFileSync(ventureFile(dir, PLAN), JSON.stringify(p, null, 2) + "\n");
+  return { plan: p, item };
+}
+
+/** Carries out the plan as the founder left it. Checks every item before moving any. */
+export function apply(dir, p, { agent = agentFromEnv("person", "cli"), evenIfBusy = false } = {}) {
+  const moves = p.items.filter((i) => i.action === "move" && !i.done);
+  const ids = new Set(readMap(dir).sources.map((s) => s.id));
+  for (const i of moves) {
+    if (!existsSync(i.from)) throw new Error(`${i.from} is gone; write the plan again`);
+    const s = statSync(i.from);
+    if (s.dev !== i.identity.dev || s.ino !== i.identity.ino) throw new Error(`${i.from} is not the folder the plan was written for; write the plan again`);
+    if (existsSync(i.to)) throw new Error(`${i.to} already exists; a port never overwrites`);
+    if (ids.has(i.source)) throw new Error(`sources.json already has a source ${i.source}`);
+    const b = busy(i.from);
+    if (b.length && !evenIfBusy) throw new Error(`${b.length} process${b.length === 1 ? " is" : "es are"} working inside ${i.from} (${b.map((x) => `${x.command} ${x.pid}`).join(", ")}); stop them or add --even-if-busy`);
   }
-  const done = { ported: [], pointed: [] };
-  for (const i of p.items.filter((x) => x.action === "port")) {
-    mkdirSync(dirname(join(dir, i.to)), { recursive: true });
-    copyFileSync(join(src, i.from), join(dir, i.to));
-    record(dir, { entity: i.to, activity: "port", agent, derived_from: [`file://${join(src, i.from)}`], note: `ported unchanged: ${i.reason}` });
-    done.ported.push(i.to);
-  }
-  const points = p.items.filter((x) => x.action === "point");
-  if (points.length) {
-    const f = join(dir, "knowledge/sources.json");
-    const map = existsSync(f) ? JSON.parse(readFileSync(f, "utf8")) : { sources: [], records: {} };
-    for (const i of points) {
-      if (map.sources.some((s) => s.id === i.source)) continue;
-      map.sources.push({ id: i.source, connector: "filesystem", writes: "none", root: join(src, i.from === "." ? "" : i.from), note: `ported as a pointer: ${i.reason}` });
-      done.pointed.push(i.source);
-    }
-    mkdirSync(dirname(f), { recursive: true });
-    writeFileSync(f, JSON.stringify(map, null, 2) + "\n");
-    if (done.pointed.length) record(dir, { entity: "knowledge/sources.json", activity: "port", agent, note: `pointers to ${done.pointed.join(", ")}` });
+  const done = [];
+  for (const i of moves) {
+    mkdirSync(dirname(i.to), { recursive: true });
+    renameSync(i.from, i.to);
+    const map = readMap(dir);
+    const root = inside(i.to, real(dir)) ? relative(real(dir), i.to) : i.to;
+    map.sources.push({ id: i.source, connector: "filesystem", writes: "none", root, note: `source of truth, moved here unchanged from ${i.from} by naive port` });
+    mkdirSync(dirname(ventureFile(dir, MAP)), { recursive: true });
+    writeFileSync(ventureFile(dir, MAP), JSON.stringify(map, null, 2) + "\n");
+    record(dir, { entity: root, activity: "port", agent, derived_from: [`file://${i.from}`], sha256: measure(i.to).manifest, note: `moved unchanged (${i.files} files); named in sources.json as source ${i.source}` });
+    i.done = new Date().toISOString();
+    done.push(i);
+    writeFileSync(ventureFile(dir, PLAN), JSON.stringify(p, null, 2) + "\n");
   }
   return done;
 }
 
+// One run as a trace for platform/integrations/langsmith.mjs: the run, and a child per item.
+function trace(dir, name, inputs, start, items, error) {
+  const end = new Date().toISOString();
+  const t = { name, run_type: "chain", start, end, inputs, outputs: { items: items.map(({ from, to, action, done }) => ({ from, to, action, done })) }, ...(error ? { error } : {}),
+    tags: ["naive", "port"], children: items.map((i) => ({ name: `${i.action} ${basename(i.from)}`, run_type: "tool", start, end, inputs: { from: i.from, to: i.to },
+      outputs: { action: i.action, reason: i.reason, files: i.files, bytes: i.bytes, warnings: i.warnings, done: i.done } })) };
+  try { mkdirSync(dirname(ventureFile(dir, TRACE)), { recursive: true }); writeFileSync(ventureFile(dir, TRACE), JSON.stringify(t, null, 2) + "\n"); } catch { return; }
+  // The harness's way (interface/harness/run.mjs): with a key set, the platform exporter ships the trace.
+  if (process.env.LANGSMITH_API_KEY) {
+    const p = spawnSync("node", [join(dirname(new URL(import.meta.url).pathname), "../platform/integrations/langsmith.mjs"), ventureFile(dir, TRACE), "--project", process.env.LANGSMITH_PROJECT ?? "naive-port"], { encoding: "utf8" });
+    console.log(p.status === 0 ? `LangSmith: ${p.stdout.trim()}` : `LangSmith upload failed: ${(p.stderr || p.stdout).trim()}`);
+  }
+}
+
+const mb = (b) => `${(b / 1024 / 1024).toFixed(1)} MB`;
+
 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 all = (k) => args.flatMap((a, i) => a === `--${k}` ? [args[i + 1]] : []);
+  const VALUED = new Set(["--venture", "--to", "--links", "--confirm", "--from"]);
+  const folder = opt("from") ?? args.find((a, i) => !a.startsWith("--") && !VALUED.has(args[i - 1]));
   const dir = opt("venture");
-  if (!dir) { console.error("usage: node schema/port-venture.mjs --from <project> --venture <dir> | --venture <dir> --apply --confirm port"); process.exit(2); }
-  try {
-    if (args.includes("--apply")) {
-      if (opt("confirm") !== "port") { console.error("type --confirm port to carry out the plan"); process.exit(1); }
-      if (!existsSync(join(dir, PLAN))) { console.error(`no plan at ${join(dir, PLAN)}: run with --from first`); process.exit(1); }
-      const d = apply(dir, JSON.parse(readFileSync(join(dir, PLAN), "utf8")));
-      console.log(`ported ${d.ported.length} files unchanged; pointed to ${d.pointed.length} source${d.pointed.length === 1 ? "" : "s"}`);
-    } else {
-      const from = opt("from");
-      if (!from) { console.error("--from <project> is needed to write a plan"); process.exit(2); }
-      const p = plan(from, dir);
-      mkdirSync(join(dir, ".release"), { recursive: true });
-      writeFileSync(join(dir, PLAN), JSON.stringify(p, null, 2) + "\n");
-      for (const i of p.items) console.log(`${i.action.padEnd(5)}  ${i.from}${i.to ? `  ->  ${i.to}` : i.source ? `  ->  source ${i.source}` : ""}   (${i.reason})`);
-      console.log(`\n${p.summary.port} to port, ${p.summary.point} to point to, ${p.summary.leave} left behind. Nothing has changed yet.`);
-      console.log(`Read ${relative(process.cwd(), join(dir, PLAN))}, set any item's action to port, point or leave, then run with --apply --confirm port.`);
-    }
-  } catch (e) { console.error(e.message); process.exit(1); }
+  if (!dir) { console.error("usage: node schema/port-venture.mjs <folder> --venture <dir> [--to <path>] | --venture <dir> --apply --confirm port"); process.exit(2); }
+  const start = new Date().toISOString();
+  if (args.includes("--apply")) {
+    if (opt("confirm") !== "port") { console.error("type --confirm port to carry out the plan"); process.exit(1); }
+    const p = readPlan(dir);
+    if (!p) { console.error(`no plan at ${ventureFile(dir, PLAN)}: run naive port <folder> first`); process.exit(1); }
+    try {
+      const d = apply(dir, p, { evenIfBusy: args.includes("--even-if-busy") });
+      trace(dir, "naive port apply", { venture: dir }, start, d);
+      for (const i of d) console.log(`moved  ${i.from}  ->  ${i.to}   (${i.files} files, unchanged; source ${i.source})`);
+      for (const i of d.filter((x) => x.git?.worktrees.length)) console.log(`\nrepair its worktrees: git -C ${i.to} worktree repair`);
+      console.log(`\nmoved ${d.length} folder${d.length === 1 ? "" : "s"}. Trace: ${relative(process.cwd(), ventureFile(dir, TRACE))}`);
+    } catch (e) { trace(dir, "naive port apply", { venture: dir }, start, p.items, e.message); console.error(e.message); process.exit(1); }
+  } else {
+    if (!folder) { console.error("name the folder to port: naive port <folder>"); process.exit(2); }
+    try {
+      const { plan: p, item } = plan(folder, dir, { to: opt("to"), links: all("links") });
+      trace(dir, "naive port plan", { folder, venture: dir, to: opt("to") }, start, [item]);
+      for (const i of p.items) {
+        console.log(`${(i.done ? "moved" : i.action).padEnd(5)}  ${i.from}  ->  ${i.to}   (${i.files} files, ${mb(i.bytes)}${i.reason ? `; ${i.reason}` : ""})`);
+        if (!i.done) for (const w of i.warnings ?? []) console.log(`       ! ${w}`);
+      }
+      const n = p.items.filter((i) => i.action === "move" && !i.done).length;
+      console.log(`\n${n} folder${n === 1 ? "" : "s"} to move, unchanged. Nothing has moved yet.`);
+      console.log(`Read ${relative(process.cwd(), ventureFile(dir, PLAN))}, set any item's action to leave, then run with --apply --confirm port.`);
+    } catch (e) { trace(dir, "naive port plan", { folder, venture: dir }, start, [], e.message); console.error(e.message); process.exit(1); }
+  }
 }

package/schema/release-read.mjs

@@ -16,6 +16,7 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { join, normalize } from "node:path";
+import { ventureFile } from "./venture-paths.mjs";
 
 export const RELEASE_DIR = ".release";
 export const MANIFEST = ".release/release.json";
@@ -24,7 +25,7 @@ export const RECORDS = ".release/records";
 
 /** The release manifest of a venture, or null when it has none. */
 export function readRelease(dir) {
-  const f = join(dir, MANIFEST);
+  const f = ventureFile(dir, MANIFEST);
   return existsSync(f) ? JSON.parse(readFileSync(f, "utf8")) : null;
 }
 
@@ -32,7 +33,7 @@ export function readRelease(dir) {
 export function frozenText(dir, file) {
   const rel = normalize(file);
   if (rel.startsWith("..") || rel.startsWith("/")) return null;
-  const f = join(dir, RECORDS, rel);
+  const f = join(ventureFile(dir, RECORDS), rel);
   return existsSync(f) ? readFileSync(f, "utf8") : null;
 }
 
@@ -94,10 +95,10 @@ export function answer(dir, method, path, { draw } = {}) {
   if (p.split("/").includes("..")) return json(400, { error: "no .. in a release path" });
   if (p === "/" || p === "") return json(200, index(m));
   if (p === "/release.json") return json(200, m);
-  if (p === "/card.json") return existsSync(join(dir, CARD)) ? json(200, JSON.parse(readFileSync(join(dir, CARD), "utf8"))) : json(404, { error: "this release has no card" });
+  if (p === "/card.json") return existsSync(ventureFile(dir, CARD)) ? json(200, JSON.parse(readFileSync(ventureFile(dir, CARD), "utf8"))) : json(404, { error: "this release has no card" });
   if (p === "/card.svg") {
     if (!draw) return json(404, { error: "no card drawing here" });
-    return { status: 200, type: "image/svg+xml; charset=utf-8", body: draw(JSON.parse(readFileSync(join(dir, CARD), "utf8"))) };
+    return { status: 200, type: "image/svg+xml; charset=utf-8", body: draw(JSON.parse(readFileSync(ventureFile(dir, CARD), "utf8"))) };
   }
   if (p.startsWith("/records/")) {
     const file = p.slice("/records/".length);

package/schema/releases.mjs

@@ -43,6 +43,7 @@ import { attributeSources, connect } from "../knowledge/connectors/index.mjs";
 import { FRAME, confirmedIn } from "./foundation.mjs";
 import { HOME, packages } from "./packages.mjs";
 import { CARD, MANIFEST, RECORDS, RELEASE_DIR, frozenText, readRelease } from "./release-read.mjs";
+import { ventureFile } from "./venture-paths.mjs";
 
 const repo = new URL("..", import.meta.url).pathname;
 const load = (p) => JSON.parse(readFileSync(p, "utf8"));
@@ -68,7 +69,7 @@ export function key() {
 
 /** The local cache for a key: { entries, hits, misses, fresh, get(k, f), save() }. A different key starts it fresh. */
 export function openCache(dir, k = key()) {
-  const f = join(dir, CACHE);
+  const f = ventureFile(dir, CACHE);
   const kh = sha(JSON.stringify(k)).slice(0, 16);
   let old = null;
   try { old = existsSync(f) ? load(f) : null; } catch { old = null; }
@@ -87,7 +88,7 @@ export function openCache(dir, k = key()) {
 
 /** Every file of a venture, relative: skips dot folders, nested ventures and _-folders other than _streams. */
 export function ventureFiles(dir, sub = "") {
-  return readdirSync(join(dir, sub), { withFileTypes: true }).flatMap((e) => {
+  return readdirSync(ventureFile(dir, sub), { withFileTypes: true }).flatMap((e) => {
     const rel = sub ? `${sub}/${e.name}` : e.name;
     if (e.name.startsWith(".") || e.name === "node_modules") return [];
     if (e.isDirectory()) return existsSync(join(dir, rel, "venture.json")) || (e.name.startsWith("_") && e.name !== "_streams") ? [] : ventureFiles(dir, rel);
@@ -121,7 +122,7 @@ export function confirmation(dir, file, type, log) {
   const es = log.filter((e) => e.entity === file);
   if (!es.length) return { ok: false, why: "no provenance entry: written outside the router", fix: "baseline" };
   const last = es.at(-1);
-  const now = sha(readFileSync(join(dir, file)));
+  const now = sha(readFileSync(ventureFile(dir, file)));
   if (last.sha256 && last.sha256 !== now) return { ok: false, why: "changed since its last provenance entry", fix: "rewrite" };
   const statements = FRAME.questions.flatMap((q) => q.statements).filter((s) => s.record === type && s.id);
   const ok = confirmedIn(dir, file, null) || (statements.length > 0 && statements.every((s) => confirmedIn(dir, file, s.id)));
@@ -195,7 +196,7 @@ export async function survey(dir, { cache } = {}) {
     const stream = file.match(/^(.*\/_streams\/[^/]+)\//);
     if (stream) { if (!streams.has(stream[1])) streams.set(stream[1], file); continue; }
     if (file.endsWith(".decision.json") && file.split("/").at(-2) === "decisions") {
-      const d = load(join(dir, file));
+      const d = load(ventureFile(dir, file));
       const ro = routeOf(file, ms);
       if (d.status === "decided") frozen.push({ file, record: "decision-record", route: ro?.route ?? `decisions/${d.id}`, route_template: ro?.template ?? "decisions/[id]", ...(ro?.id ? { id: ro.id } : {}),
         as_of: d.provenance?.approved_at ?? null, confirmed_by: d.provenance?.approved_by ?? d.decided_by ?? "a person" });
@@ -209,7 +210,7 @@ export async function survey(dir, { cache } = {}) {
     if (!type) { leftOut.push({ file, why: "not a record: notes and readmes never ship" }); continue; }
     if (NOT_SHIPPED[type]) { leftOut.push({ file, why: NOT_SHIPPED[type] }); continue; }
     if (LIVE[type]) { holes.push({ kind: type === "money-account" ? "money" : "stream", name: ro.id ?? file, file, record: type, route: ro.route, route_template: ro.template, why: LIVE[type], live: `${CLI} ${ro.route} read --venture ${v.id}`, to_freeze: "stays live by design: confirm a dated summary record to freeze a number" }); continue; }
-    const text = readFileSync(join(dir, file), "utf8");
+    const text = readFileSync(ventureFile(dir, file), "utf8");
     let parsed = null;
     if (file.endsWith(".json")) { try { parsed = JSON.parse(text); } catch { blockers.push({ file, route: ro.route, record: type, why: "not valid JSON", fix: `fix ${file}` }); continue; } }
     if (parsed?.private === true) { privateCount.records++; continue; }
@@ -251,9 +252,9 @@ export async function survey(dir, { cache } = {}) {
     const id = d.split("/").at(-1);
     holes.push({ kind: "stream", name: d, file: first, record: "data-stream", stream: id, route: d, route_template: null, why: "a stream is append-only activity; it is never frozen", live: `read ${d}/ in the venture`, to_freeze: "stays live by design" });
   }
-  if (existsSync(join(dir, "_private"))) privateCount.folder = ventureFilesAll(join(dir, "_private")).length;
+  if (existsSync(join(ventureFile(dir, "_private")))) privateCount.folder = ventureFilesAll(join(ventureFile(dir, "_private"))).length;
   // Drafts (P-31): never shipped. One with no confirmed record behind it blocks its package.
-  const drafts = existsSync(join(dir, "_drafts")) ? readdirSync(join(dir, "_drafts")).filter((f) => f.endsWith(".draft")) : [];
+  const drafts = existsSync(join(ventureFile(dir, "_drafts"))) ? readdirSync(join(ventureFile(dir, "_drafts"))).filter((f) => f.endsWith(".draft")) : [];
   for (const d of drafts) {
     const file = d.replace(/\.draft$/, "").replace(/__/g, "/");
     const ro = routeOf(file, ms);
@@ -293,7 +294,7 @@ async function frozenCommands(dir, v, frozen, plan, cache, log) {
   try {
     mkdirSync(shadow, { recursive: true });
     writeFileSync(join(shadow, "venture.json"), JSON.stringify(v, null, 2) + "\n");
-    for (const f of frozen) { mkdirSync(dirname(join(shadow, f.file)), { recursive: true }); writeFileSync(join(shadow, f.file), f.text ?? readFileSync(join(dir, f.file), "utf8")); }
+    for (const f of frozen) { mkdirSync(dirname(join(shadow, f.file)), { recursive: true }); writeFileSync(join(shadow, f.file), f.text ?? readFileSync(ventureFile(dir, f.file), "utf8")); }
     // The log, so confirmations hold in the copy; the release's own entries are left out of the key.
     const kept = log.filter((e) => !(e.activity === "release" && e.entity === MANIFEST));
     writeFileSync(join(shadow, "provenance.jsonl"), log.map((e) => JSON.stringify(e)).join("\n") + (log.length ? "\n" : ""));
@@ -369,19 +370,19 @@ function checks(dir) {
 }
 
 function writeRelease(dir, m, frozen) {
-  const stage = join(dir, RELEASE_DIR, `.stage-${process.pid}`);
+  const stage = join(ventureFile(dir, RELEASE_DIR), `.stage-${process.pid}`);
   rmSync(stage, { recursive: true, force: true });
   for (const f of frozen) {
     const dest = join(stage, "records", f.file);
     mkdirSync(dirname(dest), { recursive: true });
-    writeFileSync(dest, f.text ?? readFileSync(join(dir, f.file), "utf8"));
+    writeFileSync(dest, f.text ?? readFileSync(ventureFile(dir, f.file), "utf8"));
   }
   mkdirSync(join(stage, "records"), { recursive: true });
-  rmSync(join(dir, RECORDS), { recursive: true, force: true });
-  renameSync(join(stage, "records"), join(dir, RECORDS));
+  rmSync(ventureFile(dir, RECORDS), { recursive: true, force: true });
+  renameSync(join(stage, "records"), ventureFile(dir, RECORDS));
   rmSync(stage, { recursive: true, force: true });
-  writeFileSync(join(dir, MANIFEST), JSON.stringify(m, null, 2) + "\n");
-  writeFileSync(join(dir, CARD), JSON.stringify(cardOf(dir, m), null, 2) + "\n");
+  writeFileSync(ventureFile(dir, MANIFEST), JSON.stringify(m, null, 2) + "\n");
+  writeFileSync(ventureFile(dir, CARD), JSON.stringify(cardOf(dir, m), null, 2) + "\n");
 }
 
 const strip = ({ text, ...rest }) => ({ ...rest, sha256: sha(text ?? "") });
@@ -435,7 +436,7 @@ export async function add(dir, route, { now = new Date().toISOString(), actor =
   if (!r) return { ok: false, error: `${route} is not a collection item route (such as product/<id>)` };
   const id = route.slice(r.route.length - 4);
   if (m.records.some((x) => x.route === route)) return { ok: false, error: `${route} is already in release ${m.release}; a full build updates it` };
-  const file = r.files.map((g) => g.replace("*", id)).find((f) => existsSync(join(dir, f)));
+  const file = r.files.map((g) => g.replace("*", id)).find((f) => existsSync(ventureFile(dir, f)));
   if (!file) return { ok: false, error: `no ${r.record} ${id} in the venture` };
   const s = await survey(dir);
   const hit = s.frozen.find((f) => f.file === file);
@@ -451,10 +452,10 @@ export async function add(dir, route, { now = new Date().toISOString(), actor =
   for (const p of m.packages) if (HOME[r.record] === p.id) { p.frozen = [...p.frozen, file]; p.gaps = p.gaps.filter((g) => g !== r.record); const t = p.frozen.length + p.holes.length; p.shell = t ? Math.round((p.frozen.length / t) * 100) / 100 : null; }
   m.incremental = [...(m.incremental ?? []), { route, file, from: before, at: stamp(now) }];
   m.release = releaseId(m);
-  mkdirSync(dirname(join(dir, RECORDS, file)), { recursive: true });
-  writeFileSync(join(dir, RECORDS, file), hit.text);
-  writeFileSync(join(dir, MANIFEST), JSON.stringify(m, null, 2) + "\n");
-  writeFileSync(join(dir, CARD), JSON.stringify(cardOf(dir, m), null, 2) + "\n");
+  mkdirSync(dirname(join(ventureFile(dir, RECORDS), file)), { recursive: true });
+  writeFileSync(join(ventureFile(dir, RECORDS), file), hit.text);
+  writeFileSync(ventureFile(dir, MANIFEST), JSON.stringify(m, null, 2) + "\n");
+  writeFileSync(ventureFile(dir, CARD), JSON.stringify(cardOf(dir, m), null, 2) + "\n");
   prov(dir, { entity: MANIFEST, route: "system/release", activity: "release", agent: agentFromEnv(actor === "agent" ? "agent" : "person", "cli"), note: `release ${m.release}: added ${route} to ${before} without rebuilding the rest` });
   return { ok: true, manifest: m, added: { route, file, from: before } };
 }
@@ -476,7 +477,7 @@ export function exportRelease(dir, out) {
   if (!m) return { ok: false, error: `no release in ${dir}: build one first` };
   if (existsSync(out) && readdirSync(out).length) return { ok: false, error: `${out} exists and is not empty: an export never writes over files` };
   mkdirSync(out, { recursive: true });
-  const card = JSON.parse(readFileSync(join(dir, CARD), "utf8"));
+  const card = JSON.parse(readFileSync(ventureFile(dir, CARD), "utf8"));
   const lines = [`# ${m.name}`, "", `Phase: ${m.phase}. Release ${m.release}, built ${m.built_at} as of ${m.now}.`, "", "## Headline numbers", "", "| Number | Value | As of | Confirmed by |", "| --- | --- | --- | --- |",
     ...card.headline.filter((h) => h.label !== "Live holes").map((h) => `| ${h.label} | ${h.value}${h.unit ? ` ${h.unit}` : ""} | ${h.as_of ?? m.now} | ${h.confirmed_by.join(", ") || "none"} |`), "", "## Records", "", "| Record | As of | Confirmed by |", "| --- | --- | --- |"];
   for (const r of m.records) {

package/schema/run-handoff.mjs

@@ -12,6 +12,7 @@
 import { execSync, spawnSync } from "node:child_process";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
+import { ventureFile } from "./venture-paths.mjs";
 
 const [dir, id] = process.argv.slice(2);
 if (!dir || !id) { console.error("usage: node schema/run-handoff.mjs <venture dir> <handoff id> [--runner <id>]"); process.exit(2); }
@@ -19,7 +20,7 @@ const opt = (k) => process.argv.includes(k) ? process.argv[process.argv.indexOf(
 const runner = opt("--runner") ?? "local";
 const [reviewId, verdict] = (opt("--review") ?? "").split("=");
 const root = new URL("..", import.meta.url).pathname;
-const hPath = join(dir, "operations/handoffs", `${id}.json`);
+const hPath = join(ventureFile(dir, "operations/handoffs"), `${id}.json`);
 const h = JSON.parse(readFileSync(hPath, "utf8"));
 const dirty = execSync("git status --porcelain", { cwd: root, encoding: "utf8" }).trim() ? "+uncommitted" : "";
 const version = execSync("git rev-parse --short HEAD", { cwd: root, encoding: "utf8" }).trim() + dirty;
@@ -41,10 +42,10 @@ for (const c of h.done_criteria.filter((d) => d.kind !== "review")) {
 const at = new Date().toISOString().replace(/\.\d+Z$/, "Z");
 const eid = `${h.id}-${at.replace(/[-:TZ]/g, "").slice(0, 14)}`;
 const ev = { id: eid, subject: { kind: "handoff", id: h.id, version }, ran_at: at, runner, results, passed: results.every((r) => r.passed) };
-mkdirSync(join(dir, "evidence/results"), { recursive: true });
-const ePath = join(dir, "evidence/results", `${eid}.json`);
+mkdirSync(join(ventureFile(dir, "evidence/results")), { recursive: true });
+const ePath = join(ventureFile(dir, "evidence/results"), `${eid}.json`);
 writeFileSync(ePath, JSON.stringify(ev, null, 2) + "\n");
-h.evidence = [...(h.evidence ?? []), relative(join(dir, "operations/handoffs"), ePath)];
+h.evidence = [...(h.evidence ?? []), relative(join(ventureFile(dir, "operations/handoffs")), ePath)];
 writeFileSync(hPath, JSON.stringify(h, null, 2) + "\n");
 const pending = h.done_criteria.filter((d) => d.kind === "review" && d.id !== reviewId).map((d) => `${d.id} (${d.reviewer})`);
 console.log(`${ev.passed ? "every criterion run passed" : "some criteria failed"}${pending.length ? `; review still owed: ${pending.join(", ")}` : ""}: ${relative(process.cwd(), ePath)}`);