geneseed 3.1.1 → 3.1.3

package/js/build/emit-claude.mjs

@@ -0,0 +1,287 @@
+/**
+ * The Claude and Bob emits — one renderer, and the settings merge that wires it in.
+ *
+ * Split out of `emit.mjs` beside `emit-opencode.mjs`, over the shared writers in
+ * `emit-common.mjs`. `claudeWire` is the half that touches a file the USER also edits, and
+ * its prior-claim pruning is the reason `deepEquals` exists — read it before changing anything here.
+ */
+import path from 'node:path';
+import { VERSION_MARKER } from '../hosts/hosts.mjs';
+import { loadAgentOverrides, writeNativeLayer } from '../hosts/native.mjs';
+import { ensureAgentOverridesStub } from '../hosts/opencode.mjs';
+import {
+  managedBlockRemove, managedBlockWrite, mergeClaudeSettings, unwireClaudeExcludes,
+  unwireClaudeSettings, wireClaudeExcludes,
+} from '../hosts/settings.mjs';
+import { writeText } from '../lib/fs.mjs';
+import { isTruthy } from '../lib/json.mjs';
+import { assertSourceComplete, phaseLog } from './bundle.mjs';
+import {
+  get, globalMemory, globalNotebook, isDict, relPosix, shipLeanLaws, stripCapabilityLinks,
+} from './emit-common.mjs';
+import { renderAll, renderFile } from './render.mjs';
+import {
+  BOB_RULES_STUB, ensureExcludesStub, ensureMemoryIndex, ensureNotebookIndex, ensureProfileStub,
+  ensureRulesStub, ensureWikiStub,
+} from './stubs.mjs';
+import { writeVersion } from './version.mjs';
+import { existsSync, mkdirSync } from 'node:fs';
+
+// ---------------------------------------------------------------------------
+// _emit_claude_core — both halves
+// ---------------------------------------------------------------------------
+
+/**
+ * RENDER and WIRE for `_build_global._emit_claude_core`: this renders wholesale, then calls
+ * `claudeWire` below for the CLAUDE.md managed-block merge and the settings file. PRUNE,
+ * MANIFEST and VERIFY are the driver's, in `bin/build-driver.mjs`.
+ *
+ * Six emits route through here — claude, bob and copilot at both scopes — so this one
+ * job is what puts two thirds of the matrix on the seam.
+ *
+ * `claudeMdText` is the payload's one item that is not a file this process wrote. WIRE
+ * needs the managed block's text, and that text is a RENDER (`prefixedAgentText`
+ * re-renders AGENT.md with every store dir prefixed), so it is computed here and merged
+ * there. `emitOpencodeRender` needed nothing of the kind — its wired file is derived from
+ * a path, not from a render.
+ */
+export function emitClaudeRender(cfg, job) {
+  phaseLog('RENDER');
+  const {
+    theme: themeName, cfgDir, claudeMd, scope, out, footprint, host, nativeCatalog,
+    oldOwned,
+  } = job;
+
+  // `os.path.relpath(cfg, claude_md.parent)` — note the reversed argument order, and
+  // that Python answers '.' for an identical pair where `path.relative` answers ''.
+  const relCfg = path.relative(path.dirname(claudeMd), cfgDir).split(path.sep).join('/')
+    || '.';
+  const lawsPrefix = relCfg === '.' ? '' : `${relCfg}/`;
+  const { theme, items } = renderAll(cfg, themeName, { footprint, lawsPrefix, nativeCatalog });
+  assertSourceComplete(cfg, `claude-${scope}`);
+  mkdirSync(cfgDir, { recursive: true });
+
+  /** `_emit_claude_core._prefixed_agent_text`. */
+  const prefixedAgentText = (prefix) => {
+    const tmplItem = items.find((i) => i.rel === 'AGENT.md');
+    if (tmplItem === undefined) return null;
+    // Deliberately NOT the same lookup as `agentText` below: that one skips an
+    // AGENT.md whose text is null, this one does not. Unreachable today (`.md` is a
+    // text suffix, so the render is never null) and reproduced anyway, because the two
+    // spellings sit four lines apart in the Python and only one of them filters.
+    //
+    // The fast path itself is byte-inert, measured: removing it re-renders with a theme
+    // whose DIR_* tokens gained an EMPTY prefix and with the same lawsPrefix, so it
+    // produces exactly the item's own text. The mutation stays green, and that is
+    // "nothing to detect" rather than "the gate cannot see it" — recorded the way
+    // `themed_rel` and `lstripNewlines` are, so the two verdicts stay distinguishable.
+    if (!prefix) return tmplItem.text;
+    const ptheme = { ...theme };
+    for (const tok of ['DIR_LAWS', 'DIR_AGENTS', 'DIR_SKILLS', 'DIR_MEMORY', 'DIR_NOTEBOOK']) {
+      ptheme[tok] = prefix + (ptheme[tok] ?? tok.split('_').slice(1).join('_').toLowerCase());
+    }
+    // Same catalogue decision as the renderAll above — a re-render that forgot it would
+    // quietly put the stripped tables back.
+    return renderFile(cfg, tmplItem.src, ptheme, footprint, '', new Set(), nativeCatalog);
+  };
+
+  const owned = [];
+  const agentText = items.find((i) => i.rel === 'AGENT.md' && i.text !== null)?.text ?? null;
+  const isBob = host === 'bob';
+  const isCopilot = host === 'copilot';
+
+  // Bob's always-injected channel is the rules folder. At GLOBAL scope rules/geneseed.md
+  // IS the preamble (a global ~/.bob/AGENTS.md is not auto-loaded), and its pointers need
+  // a `../` prefix because it sits one level below the stores; at PROJECT scope it is the
+  // slim shadow stub whose only job is to have the same filename.
+  if (isBob && agentText !== null) {
+    const rulesMd = path.join(cfgDir, 'rules', 'geneseed.md');
+    mkdirSync(path.dirname(rulesMd), { recursive: true });
+    writeText(rulesMd, scope === 'project' ? BOB_RULES_STUB
+      : stripCapabilityLinks(cfg, prefixedAgentText('../') || agentText));
+    owned.push('rules/geneseed.md');
+  }
+
+  ensureAgentOverridesStub(cfg, cfgDir);
+  // Bob's agents/skills use the Claude dialect verbatim; Copilot has its own frontmatter.
+  // `manifestExisted` is deliberately not passed: the Python does not pass it either, so
+  // the pre-manifest header line is unreachable from this emit on both sides.
+  const { nAgents, nSkills, written } = writeNativeLayer(
+    items, path.join(cfgDir, 'agents'), path.join(cfgDir, 'skills'),
+    loadAgentOverrides(cfgDir),
+    { host: isCopilot ? 'copilot' : 'claude', oldOwned, cfg: cfgDir, src: cfg.src });
+  for (const p of written) owned.push(relPosix(cfgDir, p));
+
+  const memStatus = globalMemory(cfgDir, items, out, cfg.src);
+  ensureMemoryIndex(path.join(cfgDir, 'memory'));
+  const nbStatus = globalNotebook(cfgDir, items, out, cfg.src);
+  ensureNotebookIndex(path.join(cfgDir, 'notebook'));
+  ensureWikiStub(cfgDir);
+  ensureRulesStub(cfgDir);
+  ensureProfileStub(cfgDir);
+  ensureExcludesStub(cfgDir);
+
+  // Project hygiene, claim-on-create: an existing (possibly user-authored) .gitignore is
+  // never rewritten, but one we created stays owned across re-emits.
+  if (scope === 'project') {
+    const gi = path.join(cfgDir, '.gitignore');
+    const giLines = (host === 'claude' ? ['settings.local.json'] : [])
+      .concat(['wiki.jsonc', 'agent-overrides.json']);
+    if (!existsSync(gi)) {
+      writeText(gi, `${giLines.join('\n')}\n`);
+      owned.push('.gitignore');
+    } else if (oldOwned.includes('.gitignore')) {
+      owned.push('.gitignore');
+    }
+  }
+
+  writeVersion(cfg, cfgDir);
+  owned.push(VERSION_MARKER);
+
+  shipLeanLaws(items, theme, cfgDir, owned, footprint);
+
+  // The last render of the emit, and the only one whose product is not written here.
+  // Bob at GLOBAL scope gets no managed block at all, so nothing is rendered for it —
+  // the condition is the merge's, kept here so RENDER produces exactly what WIRE
+  // consumes and no more.
+  let claudeMdText = null;
+  if (agentText !== null && !(isBob && scope === 'global')) {
+    claudeMdText = stripCapabilityLinks(cfg, prefixedAgentText(lawsPrefix) || agentText);
+  }
+
+  // WIRE — see `claudeWire` below. One child per emit, so the two halves are two
+  // functions rather than two spawns; the seam between them is a call, not a process.
+  const managed = claudeWire(job, claudeMdText, agentText !== null, cfg.doctrines,
+    cfg.excludeRules);
+
+  return {
+    owned,
+    stats: { nAgents, nSkills },
+    memStatus,
+    nbStatus,
+    hasAgentText: agentText !== null,
+    claudeMdText,
+    managed,
+  };
+}
+
+/**
+ * `_build_global._claude_wire_py` — the files the Claude-shaped emits do NOT own: the
+ * CLAUDE.md/AGENTS.md managed block and settings(.local).json.
+ *
+ * Everything the render half wrote, it wrote wholesale. Everything here reconciles
+ * Geneseed's claim with content it did not write. The return value is `managed`, the claim
+ * set `bin/build-driver.mjs` records in the manifest so every teardown path unwires what was wired
+ * — which is why WIRE must precede MANIFEST, and why `managed` travels back rather than
+ * being recomputed.
+ *
+ * `preambleExclude` arrives decided and is NOT derived here. `bin/build-driver.mjs` computes
+ * it from the Claude config dir it resolved, and the suite redirects that at a sandbox.
+ * Resolving `~/.claude` on this side would write the developer's REAL CLAUDE.md path into a
+ * test's exclude list and suppress it. Third phase running that a name had to travel rather than be re-derived
+ * (`STRUCTURE` at P2d, `capabilityLinkRe` at P2e); this one edits a file the user co-owns.
+ *
+ * `GENESEED_STACK_GLOBAL` is read from the environment on BOTH sides — the child inherits
+ * `process.env`, so the opt-out reaches here without travelling in the job. `isTruthy` is
+ * not needed for it: Python tests `os.environ.get(...)` for truthiness and an env var is
+ * always a string, so `''` is the only falsy value either language sees.
+ */
+function claudeWire(job, claudeMdText, hasAgentText, doctrines = null, excludeRules = []) {
+  phaseLog('WIRE');
+  const { cfgDir, claudeMd, scope, host, oldManaged, preambleExclude, hookOpts } = job;
+  const old = oldManaged && typeof oldManaged === 'object' && !Array.isArray(oldManaged)
+    ? oldManaged : {};
+  const isBob = host === 'bob';
+  const isCopilot = host === 'copilot';
+  const managed = {};
+
+  // CLAUDE.md — Claude auto-loads it by location; merge as a delimited block so any user
+  // prose around it survives. `claudeMdText` is the render half's product; it is null
+  // exactly when no block is to be written.
+  // Exception — Bob GLOBAL: Bob never auto-loads a global ~/.bob/AGENTS.md, so a global
+  // copy is pure disk weight; none is written, and a re-emit self-heals the one an older
+  // install carries.
+  if (claudeMdText !== null) {
+    managedBlockWrite(claudeMd, claudeMdText);
+    // No sticky "whole" flag: teardown always excises the block and deletes the file only
+    // when nothing else remains — a whole-file delete would eat prose the user added AFTER
+    // Geneseed created the file.
+    //
+    // `os.path.relpath(claude_md, cfg).replace(os.sep, '/')`. Python answers '.' where
+    // `path.relative` answers '' for an identical pair, the same guard `lawsPrefix` needs
+    // above — unreachable here (CLAUDE.md is a file, cfgDir a directory, so the pair is
+    // never identical) and spelled anyway, because the two call sites are 400 lines apart
+    // and only one of them is obviously safe.
+    const rel = path.relative(cfgDir, claudeMd).split(path.sep).join('/') || '.';
+    managed.claude_md = { rel };
+  } else if (isBob && scope === 'global' && isTruthy(get(old, 'claude_md'))) {
+    const oldCm = isDict(get(old, 'claude_md')) ? get(old, 'claude_md') : {};
+    // `.resolve()` on the Python side; `path.resolve` is its counterpart and both are
+    // applied to a path already built from an absolute cfgDir.
+    const victim = path.resolve(cfgDir, get(oldCm, 'rel') || path.basename(claudeMd));
+    managedBlockRemove(victim);
+  }
+
+  // Hooks embed machine-absolute paths. At PROJECT scope for Claude they go into
+  // settings.local.json — the personal, untracked file — never the team-shared
+  // settings.json, which would hand every teammate failing hooks pointing at this machine's
+  // node and this machine's checkout. (Bob documents no local variant, so it keeps
+  // settings.json.) Copilot has NO
+  // settings.json and no hook mechanism at all, so the whole stage is skipped: nothing
+  // written, no settings_* keys recorded for the lifecycle to unwire.
+  if (!isCopilot) {
+    const settingsName = scope === 'project' && !isBob ? 'settings.local.json' : 'settings.json';
+    const settingsPath = path.join(cfgDir, settingsName);
+    managed.settings_file = settingsName;
+    // Migration: an older install wired hooks/excludes into a different file — unwire the
+    // recorded claims there, or they linger (and run) forever.
+    const oldSf = get(old, 'settings_file') || 'settings.json';
+    if (oldSf !== settingsName) {
+      unwireClaudeSettings(path.join(cfgDir, oldSf), get(old, 'settings_hooks') || []);
+      unwireClaudeExcludes(path.join(cfgDir, oldSf), get(old, 'settings_excludes') || []);
+    }
+    // The merge prunes recorded groups that are no longer canonical and returns the
+    // COMPLETE current claim set — store it as-is; unioning with prior would resurrect the
+    // stale claims.
+    // `doctrines` decides whether the git-gate group is part of the canonical claim set. It
+    // travels from `cfg` rather than being re-read off the deployment: this is the emit that
+    // DECIDES the install's packs, so the marker on disk is still the previous build's.
+    const [, managedHooks] = mergeClaudeSettings(
+      settingsPath, scope, oldSf === settingsName ? get(old, 'settings_hooks') : null, hookOpts,
+      doctrines, excludeRules,
+    );
+    managed.settings_hooks = managedHooks;
+
+    // Project-bypasses-global (Claude only): a PROJECT install suppresses the GLOBAL
+    // ~/.claude/CLAUDE.md while cwd is this repo, via Claude's native claudeMdExcludes.
+    // Written only when this run actually emitted the project's own preamble (never
+    // suppress with no replacement); GENESEED_STACK_GLOBAL=1 opts out, and a re-emit with
+    // it set strips a prior exclude. Bob never gets one: its bypass is the same-named
+    // workspace rules file.
+    const priorRaw = get(old, 'settings_excludes');
+    const priorExcl = Array.isArray(priorRaw) ? priorRaw : [];
+    if (scope === 'project' && hasAgentText && preambleExclude) {
+      const wantExcl = [preambleExclude];
+      if (process.env.GENESEED_STACK_GLOBAL) {
+        unwireClaudeExcludes(settingsPath, wantExcl);
+        managed.settings_excludes = [];
+      } else {
+        const addedExcl = wireClaudeExcludes(settingsPath, wantExcl);
+        // Claim only what Geneseed itself wired (prior + newly added) — folding `wantExcl`
+        // in unconditionally would claim a user's own pre-existing exclude, and uninstall
+        // would then strip it. `sorted(set(a) | set(b))` — Python sorts strings by code
+        // point and so does the default `Array.sort`, which is why no comparator is passed.
+        managed.settings_excludes = [...new Set([...priorExcl, ...addedExcl])].sort();
+      }
+    } else if (priorExcl.length && isBob) {
+      // Self-heal older Bob installs: earlier versions wrote the global AGENTS.md into
+      // claudeMdExcludes here. The key is Claude-only and its Bob semantics are unknown, so
+      // a re-emit removes it instead of carrying it forward.
+      unwireClaudeExcludes(settingsPath, priorExcl);
+    } else if (priorExcl.length) {
+      managed.settings_excludes = priorExcl;
+    }
+  }
+  return managed;
+}
+

package/js/build/emit-common.mjs

@@ -0,0 +1,255 @@
+/**
+ * What every emit shares — the constants that name what this tool owns, the small readers it
+ * walks a tree with, and the three writers both GLOBAL emits call.
+ *
+ * Split out of `emit.mjs` because each of `globalMemory`, `globalNotebook`, `shipLeanLaws`
+ * and `stripCapabilityLinks` has two callers in two different host emits. A helper with two
+ * hosts belongs to neither, and putting it in one of them is how a file grows to 1400 lines.
+ *
+ * Nothing here decides WHICH host is being emitted. `emit-opencode.mjs` and
+ * `emit-claude.mjs` do that; `emit.mjs` renders the bundle they read from.
+ */
+import path from 'node:path';
+import { copyFile, writeText } from '../lib/fs.mjs';
+import { SRC_DIR_TOKENS, destRel } from './render.mjs';
+import { mkdirSync, readdirSync, statSync } from 'node:fs';
+
+/** `_build_render.SRC_DIRS_MARKER`. */
+export const SRC_DIRS_MARKER = '.geneseed-srcdirs.json';
+/**
+ * `_build_render.OWNED_SRC_DIRS` — wiped and regenerated each run.
+ *
+ * `ontology` and `doctrines` are appended, not inserted: this array's iteration order is the
+ * key order of the `.geneseed-srcdirs.json` marker it fills, and appending keeps the three
+ * original keys where an existing install's marker already has them.
+ *
+ * They belong here for the same reason `laws` does — they are GENERATED, so an install must
+ * not keep a copy the source no longer produces. Without them a build writes the dirs on
+ * every run and never wipes them, which turns the doctrines toggle into a one-way switch:
+ * disable a pack, rebuild, and its rendered file sits in the install forever, contradicting
+ * the `Active packs:` line in the AGENT.md right beside it.
+ */
+export const OWNED_SRC_DIRS = ['laws', 'agents', 'skills', 'ontology', 'doctrines'];
+
+/**
+ * The constitution dirs a LEAN emit re-ships in full text — see `shipLeanLaws`.
+ *
+ * Not all of `OWNED_SRC_DIRS`: `agents` and `skills` are already written as whole files by
+ * the native layer, and only the three constitution dirs are inlined into AGENT.md in a
+ * form (terse, or pack-filtered) that loses text the reader may still need.
+ */
+const LEAN_FULL_TEXT_DIRS = ['laws', 'ontology', 'doctrines'];
+
+/**
+ * `_build_core.CAPABILITY_LINK_RE` — the DEFAULT only.
+ *
+ * `cfg.capabilityLinkRe` overrides it and the driver always supplies one, for the same
+ * reason `cfg.structure` exists: the constant is in `_OWNED` because a doctor test
+ * redirects it to the pre-fix form and asserts the emit then renders dead links, and a
+ * redirect that stops at the process boundary half-works silently. The literal stays as
+ * the fallback for the parity harnesses, which drive this module in-process.
+ */
+const CAPABILITY_LINK_RE =
+  /\[([^\]]+)\]\((?:(?!https?:\/\/|\/)[A-Za-z0-9_.-]+\/)*(?:agents|skills)\/[A-Za-z0-9_-]+\.md\)/g;
+
+/** `_build_render._TMPL_SPEC_RE`. */
+export const TMPL_SPEC_RE = /\{\{DIR_(AGENTS|SKILLS)\}\}\/([A-Za-z0-9_-]+)\.md/g;
+
+// ---------------------------------------------------------------------------
+// Small filesystem predicates. Python spells these `Path.is_file()` / `is_dir()`, both
+// of which answer False for a missing path rather than raising; `statSync` throws.
+// ---------------------------------------------------------------------------
+
+export function isFile(p) {
+  try { return statSync(p).isFile(); } catch { return false; }
+}
+
+export function isDir(p) {
+  try { return statSync(p).isDirectory(); } catch { return false; }
+}
+
+/** `dict.get(key)` with Python's semantics — OWN properties only.
+ *
+ * The same hazard `js/hosts/settings.mjs` and `js/hosts/native.mjs` both spell out: the keys here come
+ * out of a manifest the user can edit, and `old['constructor']` hands back
+ * `Object.prototype`'s member where Python's `.get` returns None. */
+export function get(obj, key) {
+  return Object.prototype.hasOwnProperty.call(obj, key) ? obj[key] : undefined;
+}
+
+export function isDict(v) {
+  return Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+}
+
+/** `Path.rglob("*")` restricted to files, skipping `__pycache__` as Python's callers do. */
+export function rglobFiles(root, out = []) {
+  for (const name of readdirSync(root)) {
+    if (name === '__pycache__') continue;
+    const full = path.join(root, name);
+    if (isDir(full)) rglobFiles(full, out);
+    else out.push(full);
+  }
+  return out;
+}
+
+/**
+ * `Path.rglob("*")` restricted to files, keeping EVERYTHING — including `__pycache__`.
+ *
+ * Not a duplicate of `rglobFiles` by accident: `source_fingerprint`'s Python filters
+ * `__pycache__` and the legacy-store migration in `_global_memory` does not, so a single
+ * walk would be wrong for one caller either way. A user's legacy bundle really can carry
+ * one (the harness ships `.py` skill scripts), and copying it or not is a byte difference
+ * the two runtimes would disagree on silently.
+ */
+function rglobAllFiles(root, out = []) {
+  for (const name of readdirSync(root)) {
+    const full = path.join(root, name);
+    if (isDir(full)) rglobAllFiles(full, out);
+    else out.push(full);
+  }
+  return out;
+}
+
+/** `p.relative_to(base).as_posix()`. */
+export function relPosix(base, p) {
+  return path.relative(base, p).split(path.sep).join('/');
+}
+
+/**
+ * `_build_emit._strip_capability_links` — `re.sub(r"\1")`, so the pattern needs `g`.
+ *
+ * Exported for `js/inspect/checks-build.mjs`: `_rendered_problems` applies the same de-linking before
+ * comparing an OpenCode bundle's AGENT.md against a fresh render, because the emit puts
+ * that difference back by design and a check that did not would report the file stale on
+ * every run forever.
+ */
+export function stripCapabilityLinks(cfg, text) {
+  const re = cfg.capabilityLinkRe
+    ? new RegExp(cfg.capabilityLinkRe, 'g')
+    : CAPABILITY_LINK_RE;
+  return text.replace(re, '$1');
+}
+
+// ---------------------------------------------------------------------------
+// The global-store helpers, shared by the `opencode-global` and `claude` jobs
+// ---------------------------------------------------------------------------
+
+/**
+ * `_build_global._global_memory` — ensure `<cfg>/memory` exists, without ever touching a
+ * store that already holds something.
+ *
+ * The three outcomes are the returned status string, which the emit prints, so they are
+ * compared through stdout as well as through the tree. Python's `theme` parameter is
+ * dropped: the store dir is ALWAYS the classic English `memory/`, never themed (the
+ * OpenCode config dir uses fixed names), so the argument was never read.
+ *
+ * The migration branch copies arbitrary USER files out of a legacy bundle, which is the
+ * reason this is not a plain translation: everything it touches is the user's, and the
+ * only thing keeping it safe is that it runs at all only when the destination is empty.
+ */
+export function globalMemory(cfgDir, items, legacy, srcRoot) {
+  const memName = 'memory';
+  const memDir = path.join(cfgDir, memName);
+  if (isDir(memDir) && readdirSync(memDir).length) return `kept ${memName}/`;
+  mkdirSync(memDir, { recursive: true });
+  if (legacy) {
+    // `dict.fromkeys([mem_name, "memory", "anamnesis"])` — de-duplicated, order kept.
+    // `mem_name` is the literal 'memory' and the Python docstring beside it says the
+    // store name is NEVER themed, so the first two entries always collapse and
+    // `anamnesis` — an older themed install's name — is the only live alias. The dedupe
+    // is what keeps the duplicate harmless rather than copying the same dir twice.
+    for (const nm of [...new Set([memName, 'memory', 'anamnesis'])]) {
+      const src = path.join(legacy, nm);
+      if (isDir(src) && readdirSync(src).length) {
+        for (const f of rglobAllFiles(src)) {
+          const dest = path.join(memDir, path.relative(src, f));
+          mkdirSync(path.dirname(dest), { recursive: true });
+          copyFile(f, dest);
+        }
+        return `migrated ${nm}/ -> ${memName}/`;
+      }
+    }
+  }
+  for (const { text, src } of items) {
+    const sp = relPosix(srcRoot, src).split('/');
+    if (sp[0] === 'memory' && sp.length > 1) {
+      // `destRel`, because this seeds from the SOURCE path and not from the item's `rel`
+      // (which is themed, and `memory/` never is). Without it the store would be seeded
+      // with the on-disk name `gitignore` — see `js/build/render.mjs`'s `destRel`.
+      const dest = path.join(memDir, destRel(path.join(...sp.slice(1))));
+      mkdirSync(path.dirname(dest), { recursive: true });
+      if (text !== null) writeText(dest, text);
+      else copyFile(src, dest);
+    }
+  }
+  return `seeded ${memName}/`;
+}
+
+/** `_build_global._global_notebook` — the same shape, with no `anamnesis` alias. */
+export function globalNotebook(cfgDir, items, legacy, srcRoot) {
+  const nbName = 'notebook';
+  const nbDir = path.join(cfgDir, nbName);
+  if (isDir(nbDir) && readdirSync(nbDir).length) return `kept ${nbName}/`;
+  mkdirSync(nbDir, { recursive: true });
+  if (legacy) {
+    const src = path.join(legacy, nbName);
+    if (isDir(src) && readdirSync(src).length) {
+      for (const f of rglobAllFiles(src)) {
+        const dest = path.join(nbDir, path.relative(src, f));
+        mkdirSync(path.dirname(dest), { recursive: true });
+        copyFile(f, dest);
+      }
+      return `migrated ${nbName}/`;
+    }
+  }
+  for (const { text, src } of items) {
+    const sp = relPosix(srcRoot, src).split('/');
+    if (sp[0] === nbName && sp.length > 1) {
+      // `destRel` — same reason as `globalMemory` above.
+      const dest = path.join(nbDir, destRel(path.join(...sp.slice(1))));
+      mkdirSync(path.dirname(dest), { recursive: true });
+      if (text !== null) writeText(dest, text);
+      else copyFile(src, dest);
+    }
+  }
+  return `seeded ${nbName}/`;
+}
+
+/**
+ * `_build_global._ship_lean_laws`.
+ *
+ * Historically the one RENDER that ran AFTER a WIRE, which is why the phase-order
+ * normalisation had to move it before the seam could be cut. Re-derived rather than
+ * trusted: its inputs are `items` and `theme` (both from `render_all`) and its only
+ * output besides the files is what it APPENDS to `owned` — which travels back in the
+ * payload for the manifest and the prune. It reads nothing any wiring stage writes, so
+ * its new position is not merely legal, it has no dependency on the old one.
+ *
+ * NO LONGER LEAN-ONLY, and the name is kept because the lean case is still the whole reason
+ * it exists. `doctrines` ships at BOTH footprints, because the two footprints lose different
+ * things: lean loses text (every rule is truncated to its first sentence, so the full text has
+ * to be on disk), while FULL loses whole packs (only the active ones are inlined, so the
+ * inactive ones have to be on disk). AGENT.md tells the agent it may read a rule in a pack
+ * that is not active, and `src/doctrines/README.md` rests cross-pack citations on exactly
+ * that — a claim the emit has to make true, not merely the `files` bundle.
+ */
+export function shipLeanLaws(items, theme, cfgDir, owned, footprint) {
+  // Themed names, resolved through the same token table `build`'s wipe resolves, so the dir
+  // a lean emit re-ships and the dir it prunes can never be two different spellings.
+  const wanted = footprint === 'lean' ? LEAN_FULL_TEXT_DIRS : ['doctrines'];
+  const dirs = new Set(wanted.map((d) => theme[SRC_DIR_TOKENS[d]] ?? d));
+  for (const { rel, text } of items) {
+    const parts = rel.split('/');
+    // `parts.length` mirrors Python's `parts and parts[0]`, where `Path("").parts` really
+    // is empty. `String.split` never returns an empty array, so this half can never be
+    // false here — kept for the mirror, and its mutation stays green because there is
+    // nothing to detect, not because the gate cannot see it.
+    if (text !== null && parts.length && dirs.has(parts[0])) {
+      const dest = path.join(cfgDir, ...parts);
+      mkdirSync(path.dirname(dest), { recursive: true });
+      writeText(dest, text);
+      owned.push(rel);
+    }
+  }
+}
+