geneseed 3.1.0 → 3.1.2

package/docs/extending.md

@@ -1,6 +1,5 @@
 # Extending — what it costs to change this tool
 
-`docs/limits.md` is the standing answer to *"what does this tool not prove about itself?"*.
 This file is its companion: **"what does it cost to add one thing?"** — one invariant, one
 doctrine rule, one skill, one plugin, one hook verb, one doc page, one theme, one screen.
 
@@ -33,7 +32,7 @@ Three seams, and almost every question about "where do I edit?" resolves to one
 Two rules follow from the table and they cause most of the surprises:
 
 - **Nothing propagates by itself.** A bundle is a *render*. Editing `src/` changes nothing on any
-  machine until something re-emits (`js/emit.mjs:362` re-fingerprints, `js/status.mjs:80`
+  machine until something re-emits (`js/build/emit.mjs:362` re-fingerprints, `js/inspect/status.mjs:80`
   reports the drift).
 - **`docs/web/` is data, `web/src/` is code.** A new documentation page is one file and no
   rebuild. A new screen is a new hashed chunk and a mandatory `web/dist` commit.
@@ -47,14 +46,14 @@ three-tier split added — `{N_ONTOLOGY}` (the ontology's sections), `{N_PACKS}`
 packs). `{N_LAWS}` is the **invariant** count and nothing else; there is deliberately no token
 meaning "the whole constitution", because `proseMirrorProblems` holds README and `SHIPPED.md`
 prose to that same number and a token that quietly meant something wider would put the docs and
-the gate at odds with no way to re-bless either.
+the gate at odds.
 
 ⚠ **Only a `kind: "concept"` page is substituted.** A `markdown`-kind page renders `{N_PACKS}`
 literally, on the screen, as those nine characters.
 
 Typing a literal number into a `docs/web` page is caught by `proseMirrorProblems`. The README
 badges and prose, and the `N laws, N agents, N skills` line in `SHIPPED.md`, are the hand-written
-exceptions — and each has its own arm in `js/doctor.mjs` (`countTableProblems` walks the five
+exceptions — and each has its own arm in `js/inspect/doctor.mjs` (`countTableProblems` walks the five
 badge keys `agents`/`skills`/`laws`/`themes`/`plugins`; `proseMirrorProblems` holds the prose).
 
 ---
@@ -94,9 +93,10 @@ cd web && npm ci && npm run lint && npm run format:check && npm test && npm run
 
 Notes that matter:
 
-- The root `package.json` has **no `scripts` key**, and no pre-commit hook, Makefile or justfile
-  exists either. `npm test` at the root exits 1 with *Missing script: "test"*; the suite is run by
-  hand with the glob above.
+- The root `package.json` has exactly one script, `lint`, and no pre-commit hook, Makefile or
+  justfile exists. `npm test` at the root exits 1 with *Missing script: "test"*; the suite is run
+  by hand with the glob above. `npm ci` once per clone installs the devDependencies `lint` needs
+  — it pulls no runtime dependency, because there are none.
 - `--test-reporter=tap` is not decoration. Both workflows gate on the *count* (`# tests N ≥ 500`)
   because `node --test` over a glob that matches nothing prints `# tests 0` and **exits 0**. Node's
   default reporter changed between majors, which is how a green 1043-test suite once reported zero.
@@ -116,9 +116,9 @@ Notes that matter:
 
 ### The gates CI does not run
 
-- **The mutation matrix itself.** `tests/mutate.mjs` — 31 rows, each a one-string edit to a
+- **The mutation matrix itself.** `tests/mutate.mjs` — 33 rows, each a one-string edit to a
   product file with a written argument for which gate should catch it. The full run is **in no
-  workflow** and should not be: it mutates the product tree 31 times and runs a gate per edit.
+  workflow** and should not be: it mutates the product tree 33 times and runs a gate per edit.
   Run `node tests/mutate.mjs --all` (or `--only M7`) by hand when you change something a gate is
   supposed to be watching. ⚠ An interrupted run leaves the **product tree mutated** — check
   `git status` before doing anything else.
@@ -166,7 +166,7 @@ Five files, none of them a count. This is the slot most new material belongs in,
 on purpose so that the invariant slot stays scarce.
 
 1. `src/doctrines/<pack>.md` — **append** `### {{DOCTRINE}} <pack> <n> — {{DOC_<PACK>_<n>}}` plus
-   the body. Two gates in `constitutionProblems` (`js/doctor.mjs`) sit on this: the pack named in
+   the body. Two gates in `constitutionProblems` (`js/inspect/doctor.mjs`) sit on this: the pack named in
    the *heading* is what addresses the rule (not the filename, so a rule filed in the wrong file is
    reported rather than silently renamed), and ids must run **contiguously from 1**, so appending
    at the end is the only place `n` is free. Packs are numbered independently — nothing outside
@@ -179,7 +179,7 @@ on purpose so that the invariant slot stays scarce.
 3. Seed the fourteen themes:
 
    ```bash
-   node bin/geneseed.mjs --sync-themes
+   node bin/build-driver.mjs --sync-themes
    ```
 
    ⚠ Four spellings of this command are in circulation and two of them fail — `doctor`'s own tip
@@ -216,13 +216,10 @@ a defect.
 Steps 1 and 9 of §2c, plus `LAW_META` if the Principle line moved. Two cautions:
 
 - `--footprint` defaults to **lean**, and lean keeps only the heading plus the first sentence
-  (`terseBlocks` in `js/render.mjs`). A clause added to the second paragraph is invisible in the
+  (`terseBlocks` in `js/build/render.mjs`). A clause added to the second paragraph is invisible in the
   default build. Amend the first sentence, or the amendment does not exist for most installs. The
   same is true of a doctrine rule; it is **not** true of the ontology, which ships whole at both
   footprints.
-- ⚠ **Rule I is frozen.** `LEX_I` is one of seven theme keys recorded byte-for-byte in the
-  primitives corpus (§5.2). Retitling Rule I in any theme reddens a snapshot that cannot be
-  re-blessed.
 
 ### 2c — Adding an INVARIANT
 
@@ -231,7 +228,7 @@ the bar is in `DESIGN.md` Decision 7, and most candidates belong in a doctrine p
 
 1. `src/laws/universal.md` — **append** `### {{LAW}} <roman> — {{LEX_<roman>}}` plus the body.
    Never insert: the `{{LAW}}` cross-references counted above live all over `src/`, plus hardcoded
-   citations in `js/hooks.mjs` and two OpenCode plugins, and **nothing resolves a cross-reference
+   citations in `js/hosts/hooks.mjs` and two OpenCode plugins, and **nothing resolves a cross-reference
    against the canon**. Renumbering silently rewires every one of them.
 2. `themes/_TEMPLATE.json` — add `LEX_<roman>` in template order. Gated, as in §2a step 2:
    `constitutionProblems` holds `LEX_I..LEX_IX` as an **equality** across all fifteen files (the
@@ -239,7 +236,7 @@ the bar is in `DESIGN.md` Decision 7, and most candidates belong in a doctrine p
    arm exists because the renumber left `LEX_XXII`, `LEX_XXIII`, `LEX_XXIV` and `LEX_XXXVI` behind
    in every file and parity was silent — they were absent from nowhere.
 3. `--sync-themes`, then restyle all fourteen by hand (§2a step 3).
-4. `LAW_CLASS` in `js/inventory.mjs` — one of the six in `LAW_CLASSES` beside it.
+4. `LAW_CLASS` in `js/inspect/inventory.mjs` — one of the six in `LAW_CLASSES` beside it.
 5. `LAW_META` in `web/src/pages/Laws.jsx` — same class, plus the one-line Principle. Note the map
    is keyed by **arabic** number where `universal.md` heads with a Roman numeral. **This copy
    exists nowhere else**; a rule absent here renders with a blank description. It is why that one
@@ -271,13 +268,13 @@ Rare, and mechanical. On top of §2a for each rule the pack carries:
 1. `src/doctrines/<pack>.md`, opening with its lead line — `**{{PACK_<NAME>}}** — how … .` A pack
    file `PACK_ORDER` names but cannot read, or one carrying no `### {{DOCTRINE}} <pack> <n>`
    heading at all, is a refusal.
-2. `PACK_ORDER` in `js/checkout.mjs` — the registration, and the render order. It is **narrative,
+2. `PACK_ORDER` in `js/build/source.mjs` — the registration, and the render order. It is **narrative,
    not alphabetical** (craft → rigor → ops → process); discovery sorts alphabetically and the
    renderer refuses a `.md` under `src/doctrines/` that `PACK_ORDER` does not name, rather than
    skipping it.
 3. `PACK_<NAME>` in `themes/_TEMPLATE.json` and all fourteen voices. Unlike `DOC_*`, this family is
    held only by `themeParityProblems` — presence, across the voices, template excluded.
-4. `DOCTRINE_BLURBS` in `js/setup.mjs` — the one-line description an installer sees in the wizard,
+4. `DOCTRINE_BLURBS` in `js/maintain/setup.mjs` — the one-line description an installer sees in the wizard,
    and the only place a pack is ever explained to them. Missing entries fall back to the bare name.
 5. `harness.config.json` if the pack should be on by default; `constitutionProblems` refuses a
    `doctrines` array naming a pack this checkout does not ship.
@@ -286,7 +283,7 @@ Rare, and mechanical. On top of §2a for each rule the pack carries:
 
 ## 3 — Adding a SKILL or an AGENT
 
-**Order matters at the first two steps.** `missingReferencedSpecs` (in `js/emit.mjs`) *aborts the
+**Order matters at the first two steps.** `missingReferencedSpecs` (in `js/build/emit.mjs`) *aborts the
 build* when `AGENT.md.tmpl` names a spec with no file — so the file comes before the table row, or
 nothing builds at all. The refusal is clean: `tests/unit/emit_gates.test.mjs:265` proves a refused
 emit leaves the prior install intact.
@@ -299,20 +296,20 @@ emit leaves the prior install intact.
    Gated both ways: a row with no file, and a file with no row.
 3. `DESC_<NAME>` in **all fourteen** themes. Theme parity catches a missing one; nothing catches
    an unstyled placeholder.
-4. **Skills only** — `SKILL_CLASS` in `js/inventory.mjs`. Gated both ways, inside
+4. **Skills only** — `SKILL_CLASS` in `js/inspect/inventory.mjs`. Gated both ways, inside
    `countTableProblems`, which matters because the runtime fallback is silent: an unclassified
    skill renders as `build`.
 5. `registry.json` — a row keyed `skills/<name>` or `agents/<name>` with `status` ∈
    {`experimental`, `approved`, `deprecated`}, a semver `version`, a non-blank `owner`, an ISO
    `added`, and `last_verified: ""`. **This is the most forgettable step**: four hand-typed fields,
-   and the gate fires in both directions (`js/doctor.mjs:388-436`).
+   and the gate fires in both directions (`js/inspect/doctor.mjs:388-436`).
 6. `README.md` — the badge, the `**🤖 Agents** (N)` / `**🛠 Skills** (N)` count, and for a skill the
    `·`-separated name in the 🛠 row (that enumeration is gated two ways, unlike the laws' one).
 7. `SHIPPED.md` — the `N laws, N agents, N skills` triple.
 8. `doctor --all`, then the suite.
 
 **A vendored skill folder** (`src/skills/<name>/SKILL.md`) is a different shape: add it to
-`VENDORED_SKILL_DIRS` (`js/native.mjs:37` — the literal is frozen in
+`VENDORED_SKILL_DIRS` (`js/hosts/native.mjs:37` — the literal is frozen in
 `tests/unit/authoring_gates.test.mjs:312`), write a `VENDOR.md` carrying `**Upstream:**`,
 `**Commit:**` (a 40-hex commit, never a moving branch) and `**License:**`, add the registry row —
 and **skip steps 2, 4, 6, 7**: the flat-spec globs only see `*.md` at the top level.
@@ -320,14 +317,13 @@ and **skip steps 2, 4, 6, 7**: the flat-spec globs only see `*.md` at the top le
 Two traps worth knowing before you write the spec:
 
 - **The word "Read-only" anywhere in an agent spec locks its emit.** It is a bare substring test
-  (`js/native.mjs:148`). The escape hatch is an explicit `<!-- bash: allow -->` marker, which
+  (`js/hosts/native.mjs:148`). The escape hatch is an explicit `<!-- bash: allow -->` marker, which
   re-opens bash on all three hosts.
 - **The console has a fourth, ungated copy of the skill taxonomy.** `SKILL_CATS` in
   `web/src/pages/Skills.jsx:19` mirrors `SKILL_CLASS` with nothing comparing them (contrast
   `LAW_META`, which *is* cross-checked). Inventing a new *category* means editing that file —
   which drags in the `web/dist` rebuild — and an unknown category renders as Build with no warning.
 
-Adding a spec reddens no recording: none of the surviving snapshots contains a skill or agent name.
 
 ---
 
@@ -358,8 +354,8 @@ No `registry.json` row, no `package.json` edit — `files[]` ships `adapters/` w
 
 ⚠ **Read §5 first. A fifth hook verb has no green path today.**
 
-The mechanical part: implement `cmd<Verb>` in `js/hooks.mjs`; wire the command string in
-`claudeHookGroups` (`js/settings.mjs:434`, spelled `` `${run} <verb> …` `` — the gate scrapes that
+The mechanical part: implement `cmd<Verb>` in `js/hosts/hooks.mjs`; wire the command string in
+`claudeHookGroups` (`js/hosts/settings.mjs:434`, spelled `` `${run} <verb> …` `` — the gate scrapes that
 shape); add the entry to `bin/geneseed-hook.mjs:43` `VERBS` with **exactly two-space indent**; add
 a row to `js/cli-table.json` with a help string over 20 characters.
 
@@ -381,6 +377,55 @@ the page renders, wrong, with nothing red.
 
 ---
 
+## 4bis — Adding a RUNTIME DEPENDENCY
+
+**Short answer: you vendor it, or you do not add it.** A dependency arrives as tracked source under
+`js/vendor/<name>/`, imported by relative path, landing in the same `git merge --ff-only` as the
+code that imports it. It never comes from a registry at install time. `tests/unit/dependency_policy.test.mjs`
+gates this, and its header carries the long form.
+
+This is not conservatism. The npm route is *unbuildable* here, for three reasons that were measured
+rather than assumed:
+
+1. **Every fixture would die at module load.** `copyCheckout` lists the tree with
+   `git ls-files --cached --others --exclude-standard`, which honours `.gitignore`, and
+   `.gitignore` ignores `/node_modules/`. The copy is written outside the repository, under the OS
+   temp root, and the product is run out of it as a real child process — so Node's upward resolver
+   walk starts in temp and finds nothing. Eleven test files build such a copy. And this is not a
+   fixture defect to work around: a user's fresh `git clone` has no `node_modules` either. **The
+   fixture is that clone.** Giving the fixture something the real install lacks makes it stop
+   reproducing the failure it exists to catch.
+
+2. **The clone channel cannot install, and it is the only channel that would need to.** `geneseed
+   update` is `git pull` + rebuild. `npm ci` deletes `node_modules` before refetching, so a blocked
+   download leaves an install whose CLI cannot start — the one outcome the update must never
+   produce. `npm install` writes the tracked `package-lock.json`, so `preflight()`'s
+   `git status --porcelain` then reports a dirty tree and the *next* update refuses with "You have
+   local changes": a self-poisoning update. Meanwhile npm/npx installs already resolve
+   `dependencies` at install time and need nothing from us. There is no overlap between the channel
+   that would need a sync step and the channel where one could work.
+
+3. **The hook path pays per tool call.** `bin/geneseed-hook.mjs` loads on every tool call of every
+   agent session (~14 ms). A relative import costs no resolver walk; a bare one does.
+
+What vendoring costs, by contrast, is almost nothing: `files[]` already carries `js/` and the
+manifest partition already carries the `js/` prefix row, so a vendored subtree costs **zero**
+manifest lines and zero partition lines. The existing doctor gate already covers a bad drop, because
+`runDoctor` validates the pulled tree in a fresh interpreter before the rebuild.
+
+**The one exception, and it is not a loophole.** `adapters/` does not run in this tool's process — it
+ships into OpenCode's. A module the *host* provides is resolvable there and nowhere else, so
+reaching for one is legitimate. But it must be a **guarded dynamic import with a working degraded
+path**, never a static one: an older host that lacks it would otherwise fail the whole plugin at
+load instead of losing one capability. `geneseed-workflow.js`'s `@opencode-ai/plugin` is the shape
+to copy. The allow-list in the gate is two-sided — an entry nothing imports fails as loudly as an
+import nothing declares.
+
+**Before proposing one at all, price it.** At the time this was written there were 463 import
+specifiers under `js/`, `bin/` and `adapters/` and exactly one was bare — the host-provided
+exception above. The invariant already held; it had simply never been written down. A library that
+would delete fewer lines than its vendored source adds is not a saving.
+
 ## 5 — The four things that are genuinely hard
 
 These are not checklist items. They are structural, and each one should be settled *before* the
@@ -398,34 +443,24 @@ already exempted a named `NATIVE` list; the hook half exempted nothing — so a
 failed with **no green path**, since the recorder died on 2026-08-17 and the failure message
 correctly forbids deleting cells to pass.
 
-Both halves now filter through the same `NATIVE` list, and the reverse check refuses an
-exemption for a verb neither entry point carries. The argument is in `docs/declined.md` — the
-short version is that the reason those verbs have no cell (*the reference had nothing to compare
-against*) is the same reason a verb postdating the reference has none, so it is one exemption,
-not two. Nothing measurable was lost: the hook verb set is pinned twice more, from editable
-sources, twelve lines above.
-
-**To add a hook verb today:** implement `cmd<Verb>` in `js/hooks.mjs`, wire the string in
-`claudeHookGroups`, add the `VERBS` entry, add the `js/cli-table.json` row, then name the verb in
-`NATIVE` in **both** `tests/unit/hook_cli.test.mjs` and `tests/snapshot/cli_help.test.mjs` (they
-read each other's source, so one alone fails) and give it an absolute unit gate.
-
-### 5.2 ⚠ Seven theme keys are frozen byte-for-byte
+`NATIVE` in `tests/unit/hook_cli.test.mjs` names the verbs held to the structural rules rather
+than to a per-verb gate, and the reverse check refuses an exemption for a verb neither entry point
+carries — so a name that stops meaning anything fails rather than sitting there.
 
-`tests/__snapshots__/primitives/{posix,win32}.json` record `theme_preview` and `theme_flair`
-answers for all fourteen themes **and the template**. Those probes read the live `themes/*.json`
-at replay time, which pins:
+**To add a hook verb today:** implement `cmd<Verb>` in `js/hosts/hooks.mjs`, wire the string in
+`claudeHookGroups`, add the `VERBS` entry, add the `js/cli-table.json` row, then give it an
+absolute unit gate. `NATIVE` used to be duplicated across two files that read each other's source
+to stay in step; there is one copy now, so there is nothing to keep in step.
 
-| Probe | Frozen keys |
-|---|---|
-| `theme_preview` | `TAGLINE`, `LOADED_SIGIL`, `VOICE`, **`LEX_I`**, `BENEDICTION` |
-| `theme_flair` | `ACCENT`, `BANNER` |
+### 5.2 ✅ Theme text is free to edit — resolved 2026-08-23
 
-Editing any of those, in any theme, reddens a snapshot with **no re-bless path**. Adding a *new*
-law is safe (only `LEX_I` is recorded). Restyling an existing theme's tagline or banner is not.
+Seven keys (`TAGLINE`, `LOADED_SIGIL`, `VOICE`, `LEX_I`, `BENEDICTION`, `ACCENT`, `BANNER`) used to
+be pinned byte-for-byte by a recording with no re-bless path, so restyling a theme's tagline was a
+red gate. **That recording is gone.** Theme text is now held only by `doctor --all` — key presence,
+cross-theme parity, and no unresolved tokens — which is a claim about structure, not wording.
 
-This was proven, not inferred: prefixing `marvin.json`'s `TAGLINE` turned
-`tests/snapshot/pure_snapshot.test.mjs` red at `case 1275`.
+Restyle freely. What still bites is `LOADED_SIGIL` uniqueness (§6): it is load-bearing for theme
+detection and nothing checks it.
 
 ### 5.3 ⚠ The hook shim is machine-wide and last-writer-wins
 
@@ -434,7 +469,7 @@ anything owns **every** install's hooks. Emitting from a git worktree or a temp
 repoint the shim at that disposable path; removing the worktree then killed hooks for every
 install on the machine.
 
-**`hookPrefix` now refuses the claim** (`js/settings.mjs`, `ephemeralCheckout`): an emit whose
+**`hookPrefix` now refuses the claim** (`js/hosts/settings.mjs`, `ephemeralCheckout`): an emit whose
 checkout is under the OS temp root, or is a linked git worktree (`.git` is a *file*), leaves a
 shim that still resolves exactly as it is and wires the emitted hooks to it anyway. The bundle it
 writes is byte-identical to a normal emit — the install simply keeps running the durable
@@ -463,37 +498,30 @@ remains the cheapest thing to run.
 Related: a stray `console.log` on a hook path silently disables a gate. Hooks signal through
 stdout JSON and return 0 on every path — a printed byte is not a warning, it is a disabled gate.
 
-### 5.4 ⚠ A snapshot red is a finding, not a step
+### 5.4 ✅ Expected values are written out — resolved 2026-08-23
 
-Everything left under `tests/__snapshots__/` — the primitives, the 26 help texts, and the small
-pure-function recordings — was produced by an implementation that no longer exists. There is no
-`--record`. A change that moves a recorded byte leaves two honest options: revert it, or argue in
-writing (in `docs/declined.md`) that the recording was wrong. `docs/limits.md` carries the full
-argument and the measurement that licensed retiring the three larger corpora.
+This section used to say that a snapshot red was a finding rather than a step: the recordings under
+`tests/__snapshots__/` came from an implementation that no longer existed, there was no `--record`,
+and a change that moved a recorded byte left only two honest options — revert it, or argue in
+writing that the recording was wrong. The rule that fell out of it was *when a frozen recording
+blocks a change, move the logic to the nearest caller that is not frozen*.
 
-**A worked example, from the session that wrote this file.** Closing a real defect — three count
-gates that go green when you *delete* the sentence they check — turned the primitives corpus red
-at `case 371`: `proseMirrorProblems` is a recorded pure function, the recording holds a case that
-passes an empty `shipped` string and expects `[]`, and the new absence arm answered otherwise.
-Both obvious moves are wrong. Re-blessing is impossible. Abandoning the fix leaves a gate failing
-open. The third move is the one to reach for: **the presence check moved up one level, into
-`countTableProblems`, which is not recorded** — where it reads better anyway, beside the code that
-already knows whether the file could be opened. The rule that falls out: *when a frozen recording
-blocks a change, look for the nearest caller that is not frozen.* Check with
+**None of that applies any more.** The recordings are retired (tag `corpus-reference-v3.1.2` is the
+only way back to them), and every expected value now lives in the test file that asserts it, above
+a sentence saying which decision it pins. The rule is correspondingly ordinary:
 
-```bash
-node -e "const j=require('./tests/__snapshots__/primitives/win32.json');console.log([...new Set(j.cases.map(c=>c.fn))].join('\n'))"
-```
+> **Change the expectation and the sentence that explains it in the same commit, and say why in
+> the message.**
 
-The concrete consequence for evolution: **editing the help text or the flags of any of the 26
-recorded CLI verbs is a frozen surface.** New verbs have a path (`NATIVE`); changes to old ones
-do not. `docs/limits.md:311-316` names this cluster as the one open standing decision.
+A red test is a step again. What it costs is an argument, in prose, that the new answer is better —
+the cost that keeps the tables honest, and far cheaper than the one it replaced.
 
-The CLI surface is the most expensive thing in the repo to change, because four hand-written
-equalities converge on it: `js/cli-table.json`'s 29-command count (`tests/unit/cli_table.test.mjs:67`),
-the 5-entry hidden-argument list (`tests/snapshot/cli_help.test.mjs:219`), the 25-subparser count
-(`tests/unit/docs.test.mjs:193`), and the 26 unblessable help fixtures. Plus
-`tests/unit/docs.test.mjs:554`, which validates every fenced `geneseed <verb> <flags>` line in
+The CLI surface is no longer the most expensive thing in the repo to change. Editing a verb's help
+text or flags is now an ordinary edit: `js/cli-table.json` is the owned document, and
+`tests/unit/text_layout.test.mjs` renders every verb through `formatHelp` to check the layout
+holds. Three hand-written equalities still converge on it and are cheap to keep in step — the
+29-command count and the hidden-argument rule (`tests/unit/cli_table.test.mjs`), and
+`tests/unit/docs.test.mjs`, which validates every fenced `geneseed <verb> <flags>` line in
 `README.md`, `SETUP.md`, `QUICKSTART.md` and `SHIPPED.md` against the table.
 
 ---
@@ -511,12 +539,12 @@ only, at best, on its presence.
 | The README keyword enumerations | `README.md`, `docs/web/rules.md` | nothing |
 | The plugin capability enumeration | `docs/web/model.md` | nothing (the number substitutes; the list does not) |
 | Section labels and page subtitles | `web/src/lib/sections.js`, `web/src/pages/Docs/index.jsx` | nothing |
-| `THEME_BLURBS` (8 of 14), `ART` (8 of 14) | `js/setup.mjs`, `js/anim.mjs` | nothing — missing entries fall back silently |
+| `THEME_BLURBS` (8 of 14), `ART` (8 of 14) | `js/maintain/setup.mjs`, `js/ui/anim.mjs` | nothing — missing entries fall back silently |
 | `LOADED_SIGIL` uniqueness | `themes/*.json` | nothing, and it is load-bearing for theme detection |
 | `adapters/claude-code/settings.json` | — | nothing compares it to what the emitter writes; **it is already divergent** |
 | `NATIVE`, twice | two test files | they check each other, which is the gate that makes the duplication safe |
 | The emit-size `CEILING` | `tests/unit/emit_smoke.test.mjs:54` | a hand-transcribed measurement |
-| Stale docblock counts | `js/themes.mjs:62` ("137 values" → 140), `js/render.mjs:116` ("145 tokens" → 148) | nothing |
+| Stale docblock counts | `js/build/themes.mjs:62` ("137 values" → 140), `js/build/render.mjs:116` ("145 tokens" → 148) | nothing |
 
 ---
 
@@ -555,7 +583,7 @@ answer.
 5. **Numbers in docblocks that had drifted** — `_TEMPLATE.json`'s "137 values" (140), "the 145
    tokens" `src/` uses (148), and "sixteen `_*_problems` checks" (fifteen — the sixteenth was
    named as `cli`, which was removed).
-6. **A claim that was simply false.** `js/render.mjs` said `--theme` is validated against
+6. **A claim that was simply false.** `js/build/render.mjs` said `--theme` is validated against
    `choices` before anything renders, which is why its own refusal read as an unreachable nicety.
    It is not in `choicesFor`; that refusal is the only one there is, on every path.
 7. **Five dead cross-references** to `tests/snapshot/no_python_in_corpus.test.mjs`, retired with
@@ -563,7 +591,7 @@ answer.
    Plus a skip message naming a `record-corpus` CI job that no longer exists.
 8. **`CHANGELOG.md` said 2.0.0 was "not yet published"**, with "no tag, no release and no install
    URL"; `geneseed@2.0.0` has been on npm since 2026-08-17. And **`SETUP.md`** documented
-   `geneseed upgrade v1.0.0 # pin to a tag`, which `js/update.mjs` prints is IGNORED.
+   `geneseed upgrade v1.0.0 # pin to a tag`, which `js/maintain/update.mjs` prints is IGNORED.
 9. **`docs/web/agents.md`** enumerated 16 agents and omitted `developer`, where README says 17 —
    the doctor arm cannot fire, because the page spells `{N_AGENTS}` and that arm only ever catches
    a literal. **`docs/web/rules.md`** called each law "a short markdown file under `src/laws/`";
@@ -662,9 +690,9 @@ stop a change today, and all of them cost a contributor a wrong turn until they
    and today nothing warns you before the snapshot goes red.
 4. **Gate `AGENT_LESSON_PROMPT` like its sibling (§7.7), and either gate or delete
    `adapters/claude-code/settings.json` (§7.10).** Two silent failure modes, both cheap to close.
-5. **Consider a `scripts` block in the root `package.json`.** There is currently no single command
-   that runs what CI runs; every contributor reassembles the five by hand from this file. A
-   `verify` script is three lines and makes §1 executable rather than descriptive.
+5. **Finish the `scripts` block in the root `package.json`.** `lint` landed with the ESLint
+   config; the rest of what CI runs is still reassembled by hand from this file. A `verify` script
+   chaining lint + suite + doctor is three lines and makes §1 executable rather than descriptive.
 
 The list of hand-maintained satellites in §6 is the *design*, not a defect — this project
 deliberately keeps tables and prose hand-written and gates them from the source tree. The

package/docs/web/rules.md

@@ -21,6 +21,8 @@ Practices rather than principles: **craft** (how code is written), **rigor** (ho
 
 A pack you leave out **still ships in the bundle**: every pack file lands under `doctrines/` beside `AGENT.md` whether or not it was built in. So a rule that cites one in an inactive pack still resolves on disk, and you can read the alternatives before turning one on. What an inactive pack loses is bindingness, not availability.
 
+Rules toggle **individually** too — `geneseed-build --exclude-rules "process 7"`, or the switches on this page — so *keep all of process except one rule* is a state you can build. A pack whose every rule is excluded drops out of the active set on its own. What an install excluded is recorded beside the pack list, as `Excluded rules: process 7`, and every rebuild preserves it.
+
 ### Which outranks which
 
 Ontology and Invariants first, then your own `user-rules.md`, then the active Doctrines, then `PROFILE.md`. A rule you write in `user-rules.md` **outranks a doctrine rule** — a practice pack chosen at build time never overrides an instruction you wrote for your own repo — and nothing outranks an invariant: a user rule or a doctrine rule may tighten one, never repeal it.

package/docs/web/setup-choices.md

@@ -36,10 +36,22 @@ Which practice rules this install adopts, fixed at build time. Unlike the dials
 - **ops** — how the machine is driven: tool discovery, commands that return, complete teardowns.
 - **process** — how a session runs: planning, context economy, docs first, and the **consent gate on every commit and push**.
 
-Turning **process** off takes that consent gate with it, at the tool boundary as well as in the prose: the OpenCode permission block and the Claude/Bob `PreToolUse` hook that ask before a commit or a push are wired only when the pack is built in, because a boundary that keeps asking for a rule the install never adopted is a gate arguing with its own harness. The invariant-territory refusals — `rm -rf`, a force-push — stay in every build; they are the Rules' territory, not the pack's.
+Turning **process 5** off takes that consent gate with it, at the tool boundary as well as in the prose: the OpenCode permission block and the Claude/Bob `PreToolUse` hook that ask before a commit or a push are wired only when that rule is built in, because a boundary that keeps asking for a rule the install never adopted is a gate arguing with its own harness. The invariant-territory refusals — `rm -rf`, a force-push — stay in every build; they are the Rules' territory, not the pack's.
 
 A pack you leave out still ships in the bundle under `doctrines/`, so you can read it before turning it on, and a rule that cites it still resolves. Change the set with `geneseed-build --doctrines craft,rigor` (or `--doctrines none`), or in `harness.config.json`.
 
+### One rule at a time
+
+The pack is the coarse axis. `--exclude-rules` is the fine one, and it takes rule addresses — so *keep all of process, drop just `process 7`* is expressible:
+
+    geneseed-build --exclude-rules "process 7"
+    geneseed-build --exclude-rules "process 5,craft 2"
+    geneseed-build --exclude-rules none
+
+Either spelling of an address works, `process 7` or `process.7`. The two axes compose: a pack whose every rule is excluded leaves `Active packs:` entirely, so no pack header is ever rendered with nothing under it. An install records its exclusions in a second marker line — `Excluded rules: process 7` — written only when something *is* excluded, and every rebuild path reads it back and preserves it.
+
+The switches are on the **Constitution** page, one per rule, staged locally and applied in a single rebuild.
+
 ### Footprint — how much of the constitution loads inline
 
 How much of the constitution `AGENT.md` carries inline every turn. A token-cost dial, not a rules cut — whatever this install adopted always applies:

package/harness.config.json

@@ -2,5 +2,5 @@
   "_comment": "version is a human-readable release label only; the canonical identity of an installed harness is the source fingerprint stamped in .geneseed-version (see `harness version`), not this string.",
   "theme": "neutral",
   "product": "Geneseed",
-  "version": "3.1.0"
+  "version": "3.1.2"
 }