geneseed 3.1.0 → 3.1.2

package/js/build/emit-opencode.mjs

@@ -0,0 +1,214 @@
+/**
+ * The OpenCode emits — a project's `.opencode/` and the global config directory.
+ *
+ * Split out of `emit.mjs` beside `emit-claude.mjs`, over the shared writers in
+ * `emit-common.mjs`. The two are siblings on purpose: an emit that is right for one host and
+ * wrong for the other is the defect these have historically carried, and it reads far more
+ * plainly as two files with the same shape than as two sections of one.
+ */
+import path from 'node:path';
+import { VERSION_MARKER } from '../hosts/hosts.mjs';
+import { loadAgentOverrides, writeNativeLayer } from '../hosts/native.mjs';
+import {
+  copyPlugins, copyWorkflows, ensureAgentOverridesStub, writeColorThemes, writeCommandLayer,
+  writePonytailCommand, writePrimaryAgent, writeTheme,
+} from '../hosts/opencode.mjs';
+import { mergeOpencodeJson } from '../hosts/settings.mjs';
+import { readText, writeText } from '../lib/fs.mjs';
+import { assertSourceComplete, build, phaseLog } from './bundle.mjs';
+import {
+  globalMemory, globalNotebook, isFile, relPosix, shipLeanLaws, stripCapabilityLinks,
+} from './emit-common.mjs';
+import { renderAll } from './render.mjs';
+import {
+  ensureExcludesStub, ensureMemoryIndex, ensureNotebookIndex, ensureProfileStub, ensureRulesStub,
+  ensureWikiStub,
+} from './stubs.mjs';
+import { writeVersion } from './version.mjs';
+import { mkdirSync } from 'node:fs';
+
+// ---------------------------------------------------------------------------
+// emit_opencode — the RENDER stage only
+// ---------------------------------------------------------------------------
+
+/**
+ * RENDER and WIRE for `_build_emit.emit_opencode` — everything through the
+ * `mergeOpencodeJson` call at the bottom. PRUNE and MANIFEST are the driver's, in
+ * `bin/build-driver.mjs`.
+ *
+ * `oldOwned` and `manifestExisted` arrive in the job rather than being read here. The
+ * manifest is the DRIVER's stage: it reads the file, hands the prior claim in, and prunes
+ * and rewrites it after this returns. One owner of the file, and this function is not it.
+ *
+ * `nativeCatalog` likewise arrives decided. It is `HOSTS['opencode']['native_catalog']` from
+ * `js/hosts/hosts.mjs`, resolved by the driver before the call; passing the decision rather
+ * than re-reading the registry keeps one owner of it.
+ */
+export function emitOpencodeRender(cfg, job) {
+  phaseLog('RENDER');
+  const {
+    theme: _theme, out, root, footprint, nativeCatalog, oldOwned, manifestExisted, agentPath,
+  } = job;
+  const oc = path.join(root, '.opencode');
+
+  build(cfg, _theme, out, { footprint, nativeCatalog });
+
+  // OpenCode loads agents/skills natively, so strip AGENT.md's per-row spec links to
+  // plain names (the portable build keeps them). A deliberate de-link, not a fix.
+  const agentMd = path.join(out, 'AGENT.md');
+  if (isFile(agentMd)) writeText(agentMd, stripCapabilityLinks(cfg, readText(agentMd)));
+
+  const owned = [];
+  const { theme, items } = renderAll(cfg, _theme);
+
+  ensureAgentOverridesStub(cfg, out);
+  const overrides = loadAgentOverrides(out);
+
+  const { nAgents, nSkills, written } = writeNativeLayer(
+    items, path.join(oc, 'agents'), path.join(oc, 'skills'), overrides,
+    { host: 'opencode', oldOwned, cfg: oc, manifestExisted, theme, src: cfg.src });
+  for (const p of written) owned.push(relPosix(oc, p));
+
+  const primary = writePrimaryAgent(cfg, path.join(oc, 'agents'), overrides);
+  if (primary) owned.push(relPosix(oc, primary));
+
+  const commands = writeCommandLayer(cfg, items, path.join(oc, 'command'));
+  commands.push(writePonytailCommand(path.join(oc, 'command')));   // always-on /ponytail
+  for (const p of commands) owned.push(relPosix(oc, p));
+
+  owned.push(relPosix(oc, writeTheme(path.join(oc, 'themes'), _theme, theme)));
+  for (const p of writeColorThemes(cfg, path.join(oc, 'themes'))) owned.push(relPosix(oc, p));
+
+  const nPlugins = copyPlugins(cfg, path.join(oc, 'plugins'), owned);
+  const nWorkflows = copyWorkflows(cfg, path.join(oc, 'workflows'), owned);
+
+  // WIRE — the one file of this emit the user co-owns. `agentPath` arrives decided
+  // (`_rel_under` is the Python side by design), and only the BASENAME is consumed
+  // downstream: `opencode.json`, or the `.jsonc` sibling when that is what is on disk.
+  phaseLog('WIRE');
+  const cfgName = path.basename(mergeOpencodeJson(path.join(root, 'opencode.json'), agentPath,
+    cfg.doctrines, cfg.excludeRules));
+
+  return {
+    owned,
+    stats: {
+      nAgents, nSkills, nPlugins, nWorkflows, nCommands: commands.length, primary: !!primary,
+    },
+    cfgName,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// emit_opencode_global — the ninth, and the last emit to cross
+// ---------------------------------------------------------------------------
+
+/**
+ * BOTH halves of `_build_global.emit_opencode_global`, the "everything global, zero
+ * per-repo" OpenCode deployment. PRUNE and MANIFEST are the driver's; there is no VERIFY,
+ * because this emit writes no settings file.
+ *
+ * ASSEMBLY, NOT TRANSLATION. Every unit it needs was already here — 58 of the 65 functions
+ * in its Python closure, counted with `ast` rather than by name-mapping, which is how the
+ * scout that produced this list first reported `_posture_body` and `_mode_body` as missing
+ * when both are `registerBody` in `js/build/render.mjs`. What is new is the assembly and the
+ * three values that had to be decided on the Python side.
+ *
+ * `cfgDir` IS THE FIRST OF THEM AND THE REASON THE OTHERS WERE ASKED ABOUT.
+ * `_build_core._opencode_config_dir` is an `_OWNED` name — the suite and `harness diff`
+ * both redirect it at a sandbox — so resolving it here would render 135 files into the
+ * developer's real `~/.config/opencode`. Python's entry point resolves it once, before
+ * anything else, and sends the answer. Fourth phase running (`STRUCTURE` at P2d,
+ * `capabilityLinkRe` at P2e, `_PREAMBLE_CONFIG_DIR` at P3b): send the decision, never the
+ * resolver.
+ *
+ * `out` IS NOT THE TARGET, and with the default nobody can tell. `emit_opencode_global`
+ * writes into `<cfg>` and takes `out` ONLY as the legacy bundle to migrate a memory or
+ * notebook store from; the CLI's `--out` defaults to a directory this emit never writes a
+ * byte into. A port that derived the legacy source from `<cfg>` would pass every cell that
+ * leaves them coincident — the `claude/bundle-in-subfolder` finding at a third call site.
+ *
+ * `agentPath` travels for the same reason `emitOpencodeRender`'s does: it is WIRE's one
+ * input, and `Path.as_posix()` is the Python side's spelling of it.
+ */
+export function emitOpencodeGlobalRender(cfg, job) {
+  phaseLog('RENDER');
+  const {
+    theme: themeName, cfgDir, out, footprint, nativeCatalog, oldOwned, agentPath,
+  } = job;
+
+  // No `lawsPrefix`: the standalone laws dir sits beside AGENT.md in <cfg>, so the lean
+  // pointer's relative `laws/universal.md` resolves with no prefix.
+  const { theme, items } = renderAll(cfg, themeName, { footprint, nativeCatalog });
+  assertSourceComplete(cfg, 'opencode-global');
+  mkdirSync(cfgDir, { recursive: true });
+
+  const owned = [];
+  const agentText = items.find((i) => i.rel === 'AGENT.md' && i.text !== null)?.text ?? null;
+  if (agentText !== null) {
+    // OpenCode loads agents/skills natively, so drop AGENT.md's per-row spec links to
+    // plain names. Memory links stay RELATIVE: in the global layout AGENT.md and the
+    // store are siblings, so `memory/` resolves from AGENT.md's own location and stays
+    // hermetic — no absolute path a doctor check would flag as an escape.
+    writeText(path.join(cfgDir, 'AGENT.md'), stripCapabilityLinks(cfg, agentText));
+    owned.push('AGENT.md');
+  }
+
+  ensureAgentOverridesStub(cfg, cfgDir);
+  const overrides = loadAgentOverrides(cfgDir);
+
+  // `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'), overrides,
+    { host: 'opencode', oldOwned, cfg: cfgDir, theme, src: cfg.src });
+  for (const p of written) owned.push(relPosix(cfgDir, p));
+
+  const primary = writePrimaryAgent(cfg, path.join(cfgDir, 'agents'), overrides);
+  if (primary) owned.push(relPosix(cfgDir, primary));
+
+  const commands = writeCommandLayer(cfg, items, path.join(cfgDir, 'command'));
+  commands.push(writePonytailCommand(path.join(cfgDir, 'command')));   // always-on /ponytail
+  for (const p of commands) owned.push(relPosix(cfgDir, p));
+
+  owned.push(relPosix(cfgDir, writeTheme(path.join(cfgDir, 'themes'), themeName, theme)));
+  for (const p of writeColorThemes(cfg, path.join(cfgDir, 'themes'))) {
+    owned.push(relPosix(cfgDir, p));
+  }
+
+  const nPlugins = copyPlugins(cfg, path.join(cfgDir, 'plugins'), owned);
+  const nWorkflows = copyWorkflows(cfg, path.join(cfgDir, 'workflows'), owned);
+
+  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);
+
+  writeVersion(cfg, cfgDir);
+  owned.push(VERSION_MARKER);
+
+  shipLeanLaws(items, theme, cfgDir, owned, footprint);
+
+  // WIRE — the one file of this emit the user co-owns, and the last render is now behind
+  // us. Inlined the way `emitOpencodeRender`'s is (one call, the same merge, the same file
+  // name). Nothing walks the SOURCE for that split now: `tests/unit/emit_phase_order.test.mjs`
+  // reads the runtime `GENESEED_PHASE_LOG` trace instead, so the `phaseLog('WIRE')` below is
+  // what the gate sees — and deleting it is mutation M30.
+  phaseLog('WIRE');
+  const cfgName = path.basename(mergeOpencodeJson(path.join(cfgDir, 'opencode.json'),
+    agentPath, cfg.doctrines, cfg.excludeRules));
+
+  return {
+    owned,
+    stats: {
+      nAgents, nSkills, nPlugins, nWorkflows, nCommands: commands.length, primary: !!primary,
+    },
+    memStatus,
+    nbStatus,
+    cfgName,
+  };
+}
+

package/js/{generate.mjs → build/generate.mjs}

@@ -1,19 +1,19 @@
 /**
- * `rituals/_harness_build.py`'s three cheap verbs — `build`, `prompt` and `theme`.
+ * The three cheap generator verbs — `build`, `prompt` and `theme`.
  *
  * These are the harness's GENERATOR FACE: the subcommands whose whole job is to drive the
- * thing `bin/geneseed.mjs` already is. That is why they are the cheapest slice left and why
+ * thing `bin/build-driver.mjs` already is. That is why they are the cheapest slice left and why
  * they are the last one that can be measured by a closure walk alone — `cmd_build`'s body is
  * three lines because the work is a `subprocess`, and a name walk cannot see through one.
  *
  * WHY `build` IMPORTS THE DRIVER RATHER THAN SPAWNING IT. The Python is
  * `run([sys.executable, BUILD, *extra]).returncode` — a passthrough to a second process.
- * Reproducing that shape here would mean spawning `node bin/geneseed.mjs`, and
+ * Reproducing that shape here would mean spawning `node bin/build-driver.mjs`, and
  * `test_the_cli_reaches_no_child_process_module` forbids it: the ban is transitive over this
  * entry's imports, and P5c's argument for keeping it is that `web`, `upgrade` and `setup`
  * will genuinely need to spawn, so the ban should outlive them rather than be dismantled by
  * a verb that does not. It is also the wrong shape on its own terms. Python needs a second
- * process because `build.py` is a different PROGRAM; `bin/geneseed.mjs` is a module in this
+ * process because `build.py` is a different PROGRAM; `bin/build-driver.mjs` is a module in this
  * one, and a Node CLI spawning a Node driver to do work it could do in-process is exactly
  * the passthrough the whole port has been removing. So the driver's `main` is exported and
  * called directly, and the observable contract — the tree, the streams, the exit code — is
@@ -32,18 +32,18 @@
 import { existsSync, mkdirSync, statSync } from 'node:fs';
 import path from 'node:path';
 
-import { main as driverMain } from '../bin/geneseed.mjs';
-import { makeCfg, PACK_ORDER } from './checkout.mjs';
-import { opencodeConfigDir, pyResolve } from './hosts.mjs';
+import { main as driverMain } from '../../bin/build-driver.mjs';
+import { makeCfg, PACK_ORDER } from './source.mjs';
+import { opencodeConfigDir, resolvePath } from '../hosts/hosts.mjs';
 import {
   EMIT_HOST_SCOPE, defaultMode, defaultPosture, defaultTheme, doctrinesForBuild,
-  footprintOfDir, installState, installTargets, modeOfDir, postureOfDir, readMaybe, themeOfDir,
-} from './installs.mjs';
-import { colorThemeFiles, colorThemeJson, PALETTE_ROLES } from './opencode.mjs';
+  excludedRulesOfDir, footprintOfDir, installState, installTargets, modeOfDir, postureOfDir,
+  readMaybe, themeOfDir,
+} from '../hosts/installs.mjs';
+import { colorThemeFiles, colorThemeJson, PALETTE_ROLES } from '../hosts/opencode.mjs';
 import { renderAll } from './render.mjs';
-import {
-  jsonDumpsIndent, parseJson, pyPrint, pyPrintErr, pyRepr, readText, writeText,
-} from './lib/fs.mjs';
+import { printOut, printErr, readText, writeText } from '../lib/fs.mjs';
+import { jsonDumpsIndent, parseJson, formatRepr } from '../lib/json.mjs';
 
 /** `_harness_build._HEX_RE`. Anchored at BOTH ends — `#123` and `#1122334` both fail. */
 const HEX_RE = /^#[0-9a-fA-F]{6}$/;
@@ -51,18 +51,18 @@ const HEX_RE = /^#[0-9a-fA-F]{6}$/;
 /**
  * `raise SystemExit(msg)` — the message on stderr, exit 1.
  *
- * The convention `js/emit.mjs`'s `assertSourceComplete` set and `bin/geneseed-cli.mjs`
+ * The convention `js/build/bundle.mjs`'s `assertSourceComplete` set and `bin/geneseed-cli.mjs`
  * honours: write at the raise site, mark the throw as a DELIBERATE refusal with `exitCode`,
  * and let anything unmarked keep its stack. Python prints a traceback for an unhandled
  * exception, so dressing a crash as a one-liner would hide a bug.
  */
 function sysExit(msg) {
-  // `pyPrintErr`, NOT a local newline translation. The first draft inlined the `\n` ->
+  // `printErr`, NOT a local newline translation. The first draft inlined the `\n` ->
   // `\r\n` rule here and every cell passed, because `harness_golden` reads stderr through
   // `subprocess`'s universal-newline decode and cannot see the difference — the same
   // transport hole P5b measured. A second copy of a translation is exactly what P5d's
-  // `pyStrPath`/`pyPathStr` split was, and it is ungated in precisely the same way.
-  pyPrintErr(`${msg}\n`);
+  // `pyStrPath`/`toPlatformPath` split was, and it is ungated in precisely the same way.
+  printErr(`${msg}\n`);
   const e = new Error(msg);
   e.exitCode = 1;
   throw e;
@@ -122,7 +122,8 @@ export function cmdBuild(args) {
  * accepts (an empty `--doctrines ` is a usage error there, so it can never be produced here).
  */
 export function setupBuildArgs(theme, emit, out = null, root = null, footprint = 'lean',
-  posture = 'peer', mode = 'direct', doctrines = null, allPacks = PACK_ORDER) {
+  posture = 'peer', mode = 'direct', doctrines = null, allPacks = PACK_ORDER,
+  excludeRules = null) {
   const argv = ['--theme', theme, '--emit', emit];
   if (!['opencode-global', 'claude-global', 'bob-global', 'copilot-global'].includes(emit)) {
     if (out) argv.push('--out', out);
@@ -138,6 +139,13 @@ export function setupBuildArgs(theme, emit, out = null, root = null, footprint =
     const picked = allPacks.filter((p) => doctrines.includes(p));
     argv.push('--doctrines', picked.length ? picked.join(',') : 'none');
   }
+  // The second axis, emitted the same way and for the same reason — but ALWAYS when the
+  // caller passed a list, empty included. An omitted flag reads as "no opinion" and the
+  // driver's config fallback fills it in; `none` is the caller saying "exclude nothing",
+  // which is exactly what a rebuild that just re-enabled the last rule has to say.
+  if (Array.isArray(excludeRules)) {
+    argv.push('--exclude-rules', excludeRules.length ? excludeRules.join(',') : 'none');
+  }
   return argv;
 }
 
@@ -179,7 +187,7 @@ export const DEFAULT_EMIT = new Map([
 export function cmdRebuildAll() {
   const targets = installTargets().filter(([h, s, r]) => installState(r, h, s) === 'active');
   if (!targets.length) {
-    pyPrint('[rebuild-all] no active installs detected.\n');
+    printOut('[rebuild-all] no active installs detected.\n');
     return 0;
   }
   const failures = [];
@@ -201,22 +209,28 @@ export function cmdRebuildAll() {
     // resolving that silence out of a machine-wide config narrows every such install on its
     // first upgrade. `doctrinesForBuild` resolves unknown to ALL packs — see its docblock.
     const doctrines = doctrinesForBuild(root);
-    const argv = setupBuildArgs(theme, emit, out, out, footprint, posture, mode, doctrines);
+    // SEVEN. The per-rule axis is preserved for the same reason and with sharper teeth: an
+    // upgrade that dropped it would quietly hand back every rule its owner switched off, and
+    // `process 5` is one of them — the consent gate would return to a harness that had been
+    // built without it. No `doctrinesForBuild` rescue is needed here; see `apiInstallCmd`.
+    const excludeRules = excludedRulesOfDir(root);
+    const argv = setupBuildArgs(theme, emit, out, out, footprint, posture, mode, doctrines,
+      PACK_ORDER, excludeRules);
     const label = `${host}:${scope} (${root})`;
-    pyPrint(`[rebuild-all] ${label}: theme=${theme} emit=${emit} footprint=${footprint} `
+    printOut(`[rebuild-all] ${label}: theme=${theme} emit=${emit} footprint=${footprint} `
       + `posture=${posture} mode=${mode}\n`);
     const rc = driverMain(argv);
     if (rc !== 0) {
       failures.push(label);
-      pyPrintErr(`[rebuild-all] FAILED ${label} (exit ${rc})\n`);
+      printErr(`[rebuild-all] FAILED ${label} (exit ${rc})\n`);
     }
   }
   if (failures.length) {
-    pyPrintErr(`[rebuild-all] ${failures.length}/${targets.length} install(s) failed: `
+    printErr(`[rebuild-all] ${failures.length}/${targets.length} install(s) failed: `
       + `${failures.join(', ')}\n`);
     return 1;
   }
-  pyPrint(`[rebuild-all] rebuilt ${targets.length} install(s).\n`);
+  printOut(`[rebuild-all] rebuilt ${targets.length} install(s).\n`);
   return 0;
 }
 
@@ -296,9 +310,9 @@ export function cmdPrompt(args) {
     if (dest) mkdirSync(dest, { recursive: true });
     writeText(args.out, text);
     // The RAW argument, not the resolved path — `f"[prompt] wrote {args.out}"`.
-    pyPrint(`[prompt] wrote ${args.out} (${themeName})\n`);
+    printOut(`[prompt] wrote ${args.out} (${themeName})\n`);
   } else {
-    pyPrint(text);
+    printOut(text);
   }
   return 0;
 }
@@ -309,8 +323,8 @@ export function cmdPrompt(args) {
 
 /** `_harness_build._resolve_themes_dir` — explicit `--dir`, else a repo `.opencode/`, else global. */
 export function resolveThemesDir(args) {
-  // `Path(args.dir).expanduser().resolve()` — `pyResolve` already expands a leading `~`.
-  if (args.dir) return pyResolve(args.dir);
+  // `Path(args.dir).expanduser().resolve()` — `resolvePath` already expands a leading `~`.
+  if (args.dir) return resolvePath(args.dir);
   const repo = path.join(process.cwd(), '.opencode');
   if (!args.globalDir && isDir(repo)) return path.join(repo, 'themes');
   return path.join(opencodeConfigDir(), 'themes');
@@ -368,7 +382,7 @@ export function loadUserPalette(args, cfg) {
   }
   // `f"{r}={pal[r]!r}"` — Python's repr, so a string is single-quoted and an int is bare.
   const bad = [...pal].filter(([, v]) => !(typeof v === 'string' && HEX_RE.test(v)))
-    .map(([r, v]) => `${r}=${pyRepr(v)}`);
+    .map(([r, v]) => `${r}=${formatRepr(v)}`);
   if (bad.length) sysExit(`[theme] non-#rrggbb value(s): ${bad.join(', ')}`);
   return pal;
 }
@@ -406,8 +420,8 @@ export function cmdTheme(args) {
     writeText(dest, `${jsonDumpsIndent(colorThemeJson(Object.fromEntries(pal), transparent))}\n`);
     written.push(dest);
   }
-  pyPrint(`[theme] wrote ${written.map((p) => path.basename(p)).join(', ')} to ${destDir}\n`);
-  pyPrint(`[theme] select in OpenCode with: /theme ${full}`
+  printOut(`[theme] wrote ${written.map((p) => path.basename(p)).join(', ')} to ${destDir}\n`);
+  printOut(`[theme] select in OpenCode with: /theme ${full}`
     + (args.solidOnly ? '' : `  (or /theme ${full}-transparent)`) + '\n');
   return 0;
 }

package/js/{render.mjs → build/render.mjs}

@@ -10,11 +10,13 @@
  * RENDER* -> WIRE* -> PRUNE -> MANIFEST -> VERIFY (see `_build_global._emit_claude_core`
  * and tests/test_emit_phase_order.py). RENDER produces files Geneseed owns wholesale;
  * WIRE reconciles files the user co-owns (settings.json, opencode.json, the CLAUDE.md
- * managed block) and stays in Python for now, in `_build_settings.py`. Node takes RENDER
+ * managed block) and lives in `js/hosts/settings.mjs`, driven from the two emit modules.
+ * THIS module is only RENDER
  * because it is the only stage whose output is a pure function of the source tree.
  *
  * PARITY IS THE CONTRACT, NOT THE INTENT. Every function here has a named Python
- * counterpart and must produce byte-identical output for it; tests/test_render_parity.py
+ * counterpart and had to produce byte-identical output for it. The reference is gone, so
+ * what holds the line is `tests/golden.mjs --against`, replaying recorded emit cells;
  * drives both over every theme x footprint x posture x mode and byte-compares the
  * written trees. Where Python and JS semantics differ silently — path sort order,
  * `.suffix`, `splitlines`, universal newlines — the difference is spelled out at the
@@ -28,9 +30,11 @@
  */
 import { readdirSync, statSync, existsSync } from 'node:fs';
 import path from 'node:path';
-import { readText, parseJson, normcase, comparePaths } from './lib/fs.mjs';
-// `js/checkout.mjs` imports nothing but node builtins, so this direction cannot cycle.
-import { PACK_ORDER } from './checkout.mjs';
+import { readText } from '../lib/fs.mjs';
+import { parseJson } from '../lib/json.mjs';
+import { normcase, comparePaths } from '../lib/paths.mjs';
+// `js/build/source.mjs` imports nothing but node builtins, so this direction cannot cycle.
+import { PACK_ORDER } from './source.mjs';
 
 /** Document STRUCTURE is theme-INDEPENDENT — mirrors `_build_render.STRUCTURE`. */
 export const STRUCTURE = {
@@ -47,7 +51,7 @@ export const STRUCTURE = {
 
 /**
  * Source top-level dirs whose OUTPUT name is themed. Mirrors `SRC_DIR_TOKENS`.
- * Exported because `js/emit.mjs`'s `build` resolves the same tokens to decide which
+ * Exported because `js/build/bundle.mjs`'s `build` resolves the same tokens to decide which
  * dirs it owns and wipes — one owner, so the two cannot disagree about a folder name.
  */
 export const SRC_DIR_TOKENS = {
@@ -101,7 +105,7 @@ export function loadTheme(cfg, name) {
     // `sys.exit(<str>)` — the message on stderr, exit 1 — spelled the way
     // `assertSourceComplete` spells it: written at the raise site, and the throw carries
     // only the marker. ⚠ It was once described as an unreachable nicety under
-    // `bin/geneseed.mjs`, on the grounds that `--theme` is validated against `choices` before
+    // `bin/build-driver.mjs`, on the grounds that `--theme` is validated against `choices` before
     // anything renders — it is not: `--theme` takes a value and has no `choices` entry, so THIS
     // is the refusal, on every path. It is also reachable from `geneseed status`, which takes
     // its theme from a `.geneseed-theme`
@@ -253,7 +257,7 @@ function registerBody(cfg, theme, dir, selected, fallback) {
  * entry point and an emit that quietly dropped a pack the user asked for is exactly the
  * failure the `Active packs:` marker would then attest to.
  *
- * Both throw with `exitCode`, the marker `bin/geneseed.mjs`'s `main` turns into a status.
+ * Both throw with `exitCode`, the marker `bin/build-driver.mjs`'s `main` turns into a status.
  */
 function activeDoctrines(cfg) {
   const dir = path.join(cfg.src, 'doctrines');
@@ -265,7 +269,7 @@ function activeDoctrines(cfg) {
   const stray = onDisk.filter((n) => !PACK_ORDER.includes(n));
   if (stray.length) {
     const e = new Error(`doctrine pack file(s) ${stray.join(', ')} exist under src/doctrines/ `
-      + 'but are missing from PACK_ORDER (js/checkout.mjs) — add them there, or they render '
+      + 'but are missing from PACK_ORDER (js/build/source.mjs) — add them there, or they render '
       + 'into no install at all');
     e.exitCode = 1;
     throw e;
@@ -279,7 +283,20 @@ function activeDoctrines(cfg) {
       throw e;
     }
   }
-  return PACK_ORDER.filter((p) => wanted.includes(p));
+  // ⚠ A PACK WHOSE EVERY RULE IS EXCLUDED IS NOT A PACK, it is a heading over nothing. The
+  // console only ever offers per-RULE switches, so "turn this whole pack off" arrives here as
+  // seven exclusions rather than as a missing pack name — and rendering `**Observance** — how
+  // a task is run.` with no rules under it would be the one shape the reader cannot
+  // interpret. Dropped here rather than in `doctrinesBody` so `DOCTRINES_LIST` — the
+  // `Active packs:` marker a later reader parses back — agrees with what was rendered.
+  const excluded = new Set(cfg.excludeRules ?? []);
+  const survives = (pack) => {
+    const ids = [...readText(path.join(dir, `${pack}.md`))
+      .matchAll(/^### \{\{DOCTRINE\}\} ([a-z]+) (\d+)\b/gm)]
+      .map((m) => `${m[1]}.${Number(m[2])}`);
+    return ids.some((id) => !excluded.has(id));
+  };
+  return PACK_ORDER.filter((p) => wanted.includes(p)).filter(survives);
 }
 
 /**
@@ -292,10 +309,40 @@ function activeDoctrines(cfg) {
  * pack — closes with one pointer at the full catalogue, which ships in every bundle whether
  * or not a pack is active.
  */
+/** `### {{DOCTRINE}} <pack> <n> —` in the UNRENDERED source, which is where the address is. */
+const SRC_RULE_HEADING_RE = /^### \{\{DOCTRINE\}\} ([a-z]+) (\d+)\b/;
+
+/**
+ * Drop the individual rules an install excluded, leaving the pack's lead line and the rest.
+ *
+ * ⚠ FILTERED BEFORE SUBSTITUTION, ON THE SOURCE. The rendered heading spells the tier noun in
+ * the theme's own voice — `Doctrina process 7` on imperial, `Custom process 7` on pirate — so
+ * matching after substitution means matching fourteen spellings, and a theme whose noun
+ * happened not to match would silently exclude nothing at all. The source spelling is one
+ * literal and is the same in every voice.
+ *
+ * The pack's lead line (`**{{PACK_CRAFT}}** — how code is written.`) sits before the first
+ * heading and always survives: `splitAtLawHeadings` returns it as the leading chunk, and a
+ * pack whose every rule is excluded is not rendered at all — `activeDoctrines` drops it from
+ * the selection, so a header with nothing under it cannot occur.
+ */
+function dropExcludedRules(text, pack, excluded) {
+  if (!excluded.size) return text;
+  return splitAtLawHeadings(text)
+    .filter((block) => {
+      const m = SRC_RULE_HEADING_RE.exec(block);
+      return !m || !excluded.has(`${m[1]}.${Number(m[2])}`);
+    })
+    .join('');
+}
+
 function doctrinesBody(cfg, theme, active, footprint, lawsPrefix) {
   if (!active.length) return '';
+  const excluded = new Set(cfg.excludeRules ?? []);
   const parts = active.map((name) => {
-    const body = substitute(readText(path.join(cfg.src, 'doctrines', `${name}.md`)), theme).trim();
+    const raw = dropExcludedRules(readText(path.join(cfg.src, 'doctrines', `${name}.md`)),
+      name, excluded);
+    const body = substitute(raw, theme).trim();
     return footprint === 'lean' ? terseBlocks(body) : body;
   });
   if (footprint === 'lean') {
@@ -330,6 +377,20 @@ export function effectiveTheme(cfg, themeName, { footprint = 'full', lawsPrefix
   const active = activeDoctrines(cfg);
   theme.DOCTRINES_BODY = doctrinesBody(cfg, theme, active, footprint, lawsPrefix);
   theme.DOCTRINES_LIST = active.length ? active.join(', ') : 'none';
+  // ⚠ EMITTED ONLY WHEN SOMETHING IS EXCLUDED, and that is not cosmetic. An unconditional
+  // second marker line would put a new line into EVERY carrier — 261 golden cells, both
+  // footprints, nine emit modes — to say "nothing was excluded", which is what the line's
+  // absence already says. Keeping the default build byte-identical is what lets this ship
+  // without re-blessing anything, and it is why `excludedRulesOfDir` reads a MISSING line as
+  // `[]` rather than as unknown: absence is a real answer here, unlike the pack list.
+  //
+  // Rendered `process 7`, not `process.7`: the dotted form is the console's address, the
+  // spaced form is how every citation in the corpus already spells a rule, and this line is
+  // read by people first and by `excludedRulesOfDir` second.
+  const dropped = [...(cfg.excludeRules ?? [])].sort();
+  theme.EXCLUDED_RULES_LINE = dropped.length
+    ? `\nExcluded rules: ${dropped.map((id) => id.replace('.', ' ')).join(', ')}`
+    : '';
   return theme;
 }