geneseed 2.1.0 → 3.0.0

package/CHANGELOG.md

@@ -6,6 +6,114 @@ labels in `harness.config.json`. The canonical identity of an *installed* harnes
 is the source fingerprint in `.geneseed-version` (see `geneseed version`), not this
 label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
+## [3.0.0] — 2026-08-20
+
+### Changed
+
+- **The constitution is three tiers, and the law numbering contract breaks.** Forty flat
+  laws become an always-on **Ontology**, nine always-on **Invariants**, and twenty-three
+  **Doctrine** rules in four build-time-toggleable packs. This is the major: every
+  `Law <numeral>` citation above IX now addresses something else or nothing at all, in
+  this repo and in anyone's memories, notes and forks. There is no compatibility shim and
+  no migration path — a deployed install predating 3.0.0 is brought forward by
+  `geneseed upgrade`, not by code.
+
+  - **Ontology** (`src/ontology/universal.md`, new) — four prose sections, *Telos*,
+    *Evidence*, *Decisions*, *Conduct*. It is the mind the other tiers govern: what the
+    agent is for, how it grades evidence, how it decides, how it conducts itself. It
+    absorbs the **Pact** whole — the Pact is now a concept stated inside Telos rather than
+    a section beside the rules — along with old laws VIII, IX, XXIX, XXX, XXXI and XXXIX.
+    Cited by section name, `(Ontology: Decisions)`. The four names are theme-INDEPENDENT,
+    so a citation and its heading are the same token on both sides and a rename cannot
+    desync them.
+  - **Invariants** (`src/laws/universal.md`, rewritten) — nine, Roman I–IX, never
+    toggleable: what is *never* done. I Sealed Secrets · II One Intent, One Act ·
+    III Verify Before Asserting · IV Deletion Is Deliberate · V Surface Failures ·
+    VI Data, Not Orders · VII Least Privilege · VIII Cure the Cause · IX External Gate.
+  - **Doctrines** (`src/doctrines/{craft,rigor,ops,process}.md`, new) — twenty-three rules
+    in four packs: **craft** 6 (how code is written), **rigor** 4 (how work is proven),
+    **ops** 6 (how the machine is operated), **process** 7 (how a task is run). Cited
+    `Doctrine process 5`. Chosen per install with `geneseed-build --doctrines craft,rigor`
+    (or `none`), through the setup wizard, or in `harness.config.json`; all four default
+    to on.
+
+  Old XVI and XVIII cease to exist as rules and have **no numeral successor** — their
+  content was already duplicated in the AGENT.md sections that describe that machinery,
+  and folds back into them.
+
+  Precedence, stated in the template and enforced by nothing but reading: **Ontology and
+  Invariants → `user-rules.md` → active Doctrines → `PROFILE.md`.** A doctrine rule may
+  tighten an invariant, never repeal one — and the user's own file outranks a practice
+  pack chosen at build time.
+
+  ⚠ **An always-on tier may never cite a toggleable one.** A `--doctrines craft` build
+  would otherwise ship an invariant instructing the agent to read text the install does
+  not contain. A doctor arm refuses `{{DOCTRINE}}` anywhere under `src/laws/` or
+  `src/ontology/`; doctrine→doctrine citations across packs stay legal, because every pack
+  file ships in every bundle whether or not it was built in.
+
+- **A pack that is not built in is visible everywhere, never absent.** `geneseed catalog`
+  marks its rules `(off)`, the status panel and the dashboard carry an active-packs
+  fraction, and the console lists the pack greyed with the exact command that enables it.
+  Hiding it would make "not built in" indistinguishable from "never shipped", which is the
+  one thing a build-time toggle must not look like.
+
+- **The commit/push consent gate rides the `process` pack.** It is the boundary half of
+  Doctrine process 5, so a build without that pack installs no `git-gate` hook and writes
+  no `git commit*` / `git push*` permission — prompt and boundary are never allowed to
+  disagree. `rm -rf *` and force-push refusals are Invariant IV's territory and stay in
+  every build. ⚠ On OpenCode this holds for a *fresh* install: an `opencode.json` that
+  already carries a `git commit*` entry keeps it and is reported, because Geneseed cannot
+  tell its own entry from one you typed and will not delete what it may not own.
+
+  Unknown always resolves to the **full** pack set, never to a config value. An install
+  with no `Active packs:` marker — every install predating this release — keeps its
+  consent gate on upgrade.
+
+- **The console's Laws page is the Constitution page.** One nav entry, three bands, read
+  top to bottom. Deep links address all three tiers: `#/item/law/ont:telos`,
+  `#/item/law/IV`, `#/item/law/process.5`. The route, the section id and the filename stay
+  `laws`.
+
+- **The lean footprint grew ~17%, deliberately.** Measured on `neutral`, `AGENT.md` goes
+  from 31,457 to 36,882 bytes at `lean` and 53,378 to 54,810 at `full`. Lean truncates
+  each invariant and each doctrine rule to its first line, but ships the **ontology
+  whole** — four flowing prose sections reduced to four orphan sentences would have been a
+  worldview nobody could read. `--doctrines` is now the larger lever on that cost.
+
+### Added
+
+- `--doctrines` on the generator, a doctrine-packs question in the setup wizard that
+  pre-selects what the install already carries, and an `Active packs:` marker in every
+  carrier so an install remembers its selection across upgrades.
+- Doctor gates for the whole constitution: dangling `{{DOCTRINE}}` citations, per-pack
+  rule contiguity, `DOC_*` theme coverage in both directions, an exact `LEX_I..LEX_IX`
+  equality (a presence check had already missed four keys the renumber orphaned), a
+  single-word tier noun in every voice — both heading parsers match it with `\S+`, so a
+  two-word value makes a whole tier parse to nothing in silence — and a `DOCTRINE_META`
+  parity check whose class arm is an equality against the rule's own pack.
+- A `[note]` channel in `doctor`: printed, never counted. Its one producer reports which
+  body citations point into packs a narrowed build did not render. That state must be
+  visible, but failing the doctor over a configuration its owner chose would be wrong.
+- Count tokens `{N_ONTOLOGY}`, `{N_PACKS}`, `{N_PACKS_ACTIVE}` and `{N_DOCTRINE_RULES}`
+  for the in-app docs. `{N_LAWS}` stays the **invariant** count — the rail badge, the
+  README prose and SHIPPED.md's triple are all held to that one number by a frozen gate.
+
+### Fixed
+
+- **Four `§N` cross-references that render into every bundle** pointed at the section that
+  used to be there: inserting `## 2. Doctrines` pushed every later AGENT.md section down
+  one and the sweep stopped at the template. `src/skills/wiki.md`,
+  `src/skills/daydream/SKILL.md`, `src/skills/handoff.md`, `src/agents/_template.md`, plus
+  six in the two OpenCode plugins — one of them a live deny message a user reads. A doctor
+  arm now refuses a `§N` the template declares no section for; the half it cannot catch (a
+  pointer that still resolves and now means something else) is recorded as a manual sweep
+  in `docs/extending.md`.
+- An `opencode.json` whose `permission` Geneseed cannot see inside — a blanket
+  `"bash": "allow"` — made the reconcile a no-op and the merge then returned before any of
+  its warnings. A rule stated in AGENT.md with nothing behind it at the boundary, in
+  silence. Now reported, naming the shape and the gates left unwired.
+
 ## [2.1.0] — 2026-08-19
 
 ### Added

package/DESIGN.md

@@ -31,22 +31,32 @@ vault or a specific tool's hooks.
 3. **Theme is voice + vocabulary; the scaffolding is theme-independent.** A single
    neutral source renders to any theme via token substitution, split into two classes:
    - **Structure** (always plain English, every theme, every emit) — the section
-     *layout*, the harness name (`HARNESS`), the law *numbers*, a few rare technical
-     nouns (`Context`, `Scripts`, `Charter`), and the folder names (`laws/`, `agents/`,
-     `skills/`, `memory/` via `DIR_*`). These live in the `STRUCTURE` map in `js/render.mjs`
-     and are laid on top of every render, so a theme can never move a path, a link, or
-     a heading number. Tooling stays stable.
+     *layout*, the harness name (`HARNESS`), the law *numbers*, the four ontology section
+     names (`ONT_TELOS`, `ONT_EVIDENCE`, `ONT_DECISIONS`, `ONT_CONDUCT`), a few rare
+     technical nouns (`Context`, `Scripts`, `Charter`), and the folder names (`laws/`,
+     `ontology/`, `doctrines/`, `agents/`, `skills/`, `memory/`, `notebook/` via `DIR_*`).
+     These live in the `STRUCTURE` map in `js/render.mjs` and are laid on top of every
+     render, so a theme can never move a path, a link, or a heading number. No theme file
+     defines a `DIR_*` or an `ONT_*` key, and none may: an ontology citation spells the
+     section on both sides (`{{ONTOLOGY}}: {{ONT_TELOS}}`), so heading and reference move
+     together or not at all. Tooling stays stable.
    - **Voice + vocabulary** (themed) — how the AI *responds* (`VOICE`), a top `BANNER`,
-     and the prose words the docs use: the core nouns `LAW(S)`/`AGENT(S)`/`SKILL(S)`/
-     `MEMORY`/`NOTEBOOK`/`VAULT`/`WIKI`, plus `TAGLINE`, `LOADED_SIGIL`, `EPI_*`, `BENEDICTION`, `DESC_*`,
-     `ROAST_PERSONA`, the law titles `LEX_*`, and the section intros `INTRO_*`. Each
-     theme defines its own nouns; **neutral keeps the plain words** (Rule, Agent, Skill,
-     Memory, Workspace), so neutral output is unchanged.
+     and the prose words the docs use: the core nouns `LAW(S)`/`DOCTRINE(S)`/`ONTOLOGY`/
+     `AGENT(S)`/`SKILL(S)`/`MEMORY`/`NOTEBOOK`/`VAULT`/`WIKI`, plus `TAGLINE`,
+     `LOADED_SIGIL`, `EPI_*`, `BENEDICTION`, `DESC_*`, `ROAST_PERSONA`, the invariant
+     titles `LEX_I`..`LEX_IX`, the 23 doctrine-rule titles `DOC_<PACK>_<n>`, the four pack
+     names `PACK_CRAFT`/`PACK_RIGOR`/`PACK_OPS`/`PACK_PROCESS`, and the section intros
+     `INTRO_*`. Each theme defines its own nouns; **neutral keeps the plain words** (Rule,
+     Doctrine, Agent, Skill, Memory, Workspace), so neutral output is unchanged.
+     `{{LAW}}` and `{{DOCTRINE}}` must each be a **single word** — both heading parsers
+     match the tier noun with `\S+`, so a two-word value makes the whole tier parse to
+     nothing in silence. `constitutionProblems` refuses one.
 
    So `imperial` flavours the agent's tone *and* the page — the banner, the readiness
-   sigil, the epigraphs, and the words themselves (the laws read as *Dictates*, agents
-   as *Adepts*, skills as *Rites*) — while every folder is still `agents/`/`skills/`,
-   law numbers stay `XVIII`, and links resolve identically across themes. The source
+   sigil, the epigraphs, and the words themselves (the invariants read as *Dictates*,
+   doctrine rules as *Doctrinae*, agents as *Adepts*) — while every folder is still
+   `agents/`/`skills/`, an invariant is still numbered `IV` and a doctrine rule is still
+   addressed `process 5`, and links resolve identically across themes. The source
    tree under `src/` stays neutral for sane authoring. Toggle = one flag.
 
    The OpenCode emits add only: native skills at `skills/<name>/SKILL.md` (not slash
@@ -76,61 +86,102 @@ vault or a specific tool's hooks.
    documentation* maintained elsewhere. It also subsumes what a baked-in project
    rules file used to do: point at the project's own conventions instead.
 
-7. **Lean governance — every line must change behaviour.** The Laws, agent specs,
-   and skills are the product, and a bloated instruction surface is ignored at
-   runtime, not obeyed: an over-long rule set dilutes the rules that matter. So the
-   bar for a new Law is high — it must be universal (it binds *every* task, in
-   *every* repository), agent-behavioural (something the model does, not infra it
+7. **Lean governance — three tiers, and every line must change behaviour.** The
+   constitution, the agent specs, and the skills are the product, and a bloated
+   instruction surface is ignored at runtime, not obeyed: an over-long rule set dilutes
+   the rules that matter. The governance surface is split into three tiers, each answering
+   a different question:
+
+   - **Ontology** (`src/ontology/universal.md`) — *who is deciding*. Four sections of
+     flowing prose: **Telos** (what the agent is for, and the Pact it works under),
+     **Evidence** (how a claim is graded by how it was obtained), **Decisions** (classify
+     and tier by reversibility; show the real forks), **Conduct** (answer what was asked,
+     once). It absorbed the Pact, which is now stated *inside* Telos rather than standing
+     as a peer of the rules.
+   - **Invariants** (`src/laws/universal.md`) — *what is never traded*. Nine numbered
+     Rules, `I`..`IX`, headed `### {{LAW}} <roman> — {{LEX_<roman>}}`.
+   - **Doctrines** (`src/doctrines/{craft,rigor,ops,process}.md`) — *how work is done
+     here*. Practice rules addressed by pack and number, cited as `Doctrine process 5`.
+     `PACK_ORDER` (`js/checkout.mjs`) fixes the order craft → rigor → ops → process, which
+     is narrative and deliberately not alphabetical.
+
+   **The Ontology and the Invariants are never toggleable** — every build carries both,
+   whole. The Doctrine packs are the only tier a repository may narrow, chosen once at
+   build time (`--doctrines craft,rigor`, `--doctrines none`, or the setup wizard) and
+   defaulting to all four on. There is no runtime toggle. Every pack file ships on disk at
+   both footprints whether or not it was built in, which is what lets a citation into an
+   inactive pack still resolve.
+
+   **Conflict order, exactly:** Ontology + Invariants → the user's own `user-rules.md` →
+   the active Doctrines → `PROFILE.md`. A doctrine rule may *tighten* an invariant, never
+   repeal one; a user rule outranks a doctrine rule outright; nothing outranks an
+   invariant. And an always-on tier may never cite a toggleable one — a `--doctrines craft`
+   build would otherwise ship an invariant pointing at text its `AGENT.md` does not
+   contain — so `constitutionProblems` (`js/doctor.mjs`) refuses a `{{DOCTRINE}}` token
+   anywhere under `src/ontology/` or `src/laws/`.
+
+   The bar for a **new invariant** is the highest in the tree: universal (it binds *every*
+   task, in *every* repository), agent-behavioural (something the model does, not infra it
    cannot instantiate), and not already covered. A principle that is app-code craft,
-   host-specific infrastructure, or single-domain belongs in an agent, a skill, or
-   `context.json`, not in the universal Laws; a rule that overlaps an existing Law is
-   folded in as a clause, not minted as a new number. This is the authoring-time
-   counterpart to Law XV's runtime context economy: keep the instruction surface
-   high-signal and pruned so it stays read and heeded.
-
-   A Law that clears that bar is not one edit but six, because its *satellites* —
-   themed title, class, display copy, counts — live outside `universal.md`:
-
-   1. the rule body in `src/laws/universal.md`, headed `### {{LAW}} <roman> — {{LEX_<roman>}}`;
-   2. `LEX_<roman>` in `themes/_TEMPLATE.json`, then `geneseed-build --sync-themes`
-      to seed every theme, then restyle each one in its own voice. The flag is the
-      *generator's*, not the CLI's: `geneseed build` forwards `--theme` and nothing else,
-      so `geneseed build --sync-themes` is an error, not a synonym;
-   3. `LAW_CLASS` in `js/inventory.mjs` — the governance class, one of the six
-      in `LAW_CLASSES`;
-   4. `LAW_META` in `web/src/pages/Laws.jsx` — the class fallback *and* the one-line
-      Principle shown in the web ledger. This copy exists nowhere else; a law absent
-      here renders with a blank description;
-   5. the counts — README badge and prose, `SHIPPED.md`, the web onboarding copy;
-   6. `CHANGELOG.md`.
-
-   Five of the six are gated by `doctor`, in three different checks — theme-key parity
-   for step 2, the authoring sweep for step 3, and the count and prose mirrors for step 5
-   (`themeParityProblems`, `authoringProblems`, `countTableProblems` / `proseMirrorProblems`,
-   all in `js/doctor.mjs`) — so `geneseed doctor --all` is the check, not the checklist
-   above; the list just says what it will ask for. Step 6 has no gate and never has. Steps 3
-   and 4 both earned their gate the same way: a law shipped without them, and the
-   only symptom was a wrong chip or an empty cell in a UI nobody re-read.
-
-   Two things the checklist cannot tell you, and `docs/extending.md` can: the default
-   footprint is **lean**, which keeps a law's heading and its *first sentence* only — so an
-   amendment written into the second paragraph does not exist for most installs — and
-   `LEX_I` is one of seven theme keys frozen byte-for-byte in a recording nothing can
-   re-make, so Law I's themed titles are the one part of this list that cannot be edited.
+   host-specific infrastructure, or single-domain now has a home one tier down — a doctrine
+   pack — or in an agent, a skill, or `context.json`. A rule that overlaps an existing
+   invariant is folded in as a clause, not minted as a new number. This is the
+   authoring-time counterpart to Doctrine `process 3`'s runtime context economy.
+
+   **The satellites differ per tier, and that difference is the design** — a doctrine rule
+   is cheap on purpose, so the expensive slot stays scarce:
+
+   | Satellite | A new invariant | A new doctrine rule | A whole new pack |
+   |---|---|---|---|
+   | body | append to `src/laws/universal.md` — never insert; nothing resolves a cross-reference against the canon | append to `src/doctrines/<pack>.md`, `### {{DOCTRINE}} <pack> <n> — {{DOC_<PACK>_<n>}}`; ids must run contiguously from 1 | a new `src/doctrines/<pack>.md` with its `**Name** — lead line` |
+   | themed title | `LEX_<roman>` in all 15 theme files | `DOC_<PACK>_<n>` in all 15 theme files | `PACK_<NAME>` in all 15, plus each rule's `DOC_*` |
+   | class | `LAW_CLASS` in `js/inventory.mjs`, one of the six in `LAW_CLASSES` | **none** — a doctrine rule's class *is* its pack, and there is no second taxonomy over it | — |
+   | console copy | a `LAW_META` row in `web/src/pages/Laws.jsx` (keyed by arabic number) | a `DOCTRINE_META` row in the same file (keyed `<pack>.<n>`) | one `DOCTRINE_META` row per rule |
+   | registration | the numeral is the registration | the number is the registration | the pack name in `PACK_ORDER`, `js/checkout.mjs` |
+   | renumber risk | high — appending is the only safe move | none — packs are numbered independently | none |
+   | counts | README badge + the `N universal laws` prose, `SHIPPED.md`'s triple, the web onboarding copy | **none** — the console spends the `N_PACKS` / `N_PACKS_ACTIVE` / `N_DOCTRINE_RULES` count tokens, all computed at request time | none, same reason |
+   | changelog | `CHANGELOG.md` | `CHANGELOG.md` | `CHANGELOG.md` |
+
+   "All 15 theme files" is the 14 voices **and** `themes/_TEMPLATE.json`: theme parity
+   skips underscore-prefixed names, but `constitutionProblems` reads the template too,
+   because it is what `geneseed-build --sync-themes` seeds a new voice from. That flag is
+   the *generator's*, not the CLI's — `geneseed build --sync-themes` is an error, not a
+   synonym. `--sync-themes` writes the template's placeholder and only *prints* which keys
+   to restyle; a shipped placeholder passes every gate.
+
+   Almost all of it is gated, across six named checks in `js/doctor.mjs` —
+   `themeParityProblems` (key parity across the voices), `lawMetaProblems` and
+   `doctrineMetaProblems` (the console's Principle column, in both directions),
+   `constitutionProblems` (pack numbering and filing, `LEX_I..LEX_IX` as an *equality*, the
+   `DOC_*` vocabulary, and every `{{DOCTRINE}}` citation in `src/`), and
+   `countTableProblems` / `proseMirrorProblems` (badges and prose). So `geneseed doctor
+   --all` is the check; the table above only says what it will ask for. `CHANGELOG.md` has
+   no gate and never has.
+
+   Two things the table cannot tell you, and `docs/extending.md` can: the default footprint
+   is **lean**, which keeps an invariant's or a doctrine rule's heading and its *first
+   sentence* only — so an amendment written into the second paragraph does not exist for
+   most installs — and `LEX_I` is one of seven theme keys frozen byte-for-byte in a
+   recording nothing can re-make, so Rule I's themed titles are the one part of this list
+   that cannot be edited. The Ontology is exempt from the truncation: it ships whole at
+   both footprints, because four flowing sections cut to their first sentences would read
+   as four orphan sentences.
 
 ## 🧩 Components
 
-The `Harness/` output column shows the **neutral** folder name; the imperial theme
-renders it as the name in parentheses.
+Every folder name in the `Harness/` output column is theme-independent (Decision 3): no
+theme file defines a `DIR_*` key, so `laws/` is `laws/` in all fourteen voices.
 
 | Component | Source | `Harness/` output | Purpose |
 | --- | --- | --- | --- |
-| Entrypoint | `src/AGENT.md.tmpl` | `AGENT.md` | what the tool reads; inlines the rules, links the rest |
-| Governance | `src/laws/` | `laws/` (`leges/`) | universal rules |
-| Delegation | `src/agents/` | `agents/` (`legati/`) | capability specialists with output contracts |
-| Workflows | `src/skills/` | `skills/` (`rites/`) | repeatable procedures |
-| Memory | `src/memory/` | `memory/` (`anamnesis/`) | one-fact-per-file convention + index |
-| Notebook | `src/notebook/` | `notebook/` (`scriptorium/`) | the agent's sovereign space — any medium, seed-once charter the agent may rewrite; only `.gitignore` re-asserted |
+| Entrypoint | `src/AGENT.md.tmpl` | `AGENT.md` | what the tool reads; inlines the constitution, links the rest |
+| Ontology | `src/ontology/` | `ontology/` | the mind the rules govern — Telos, Evidence, Decisions, Conduct; always on, never toggleable |
+| Governance | `src/laws/` | `laws/` | the nine universal invariants; always on, never toggleable |
+| Doctrines | `src/doctrines/` | `doctrines/` | the four practice packs — the one build-time axis that changes *which rules ship*; the whole catalogue is written to disk either way |
+| Delegation | `src/agents/` | `agents/` | capability specialists with output contracts |
+| Workflows | `src/skills/` | `skills/` | repeatable procedures |
+| Memory | `src/memory/` | `memory/` | one-fact-per-file convention + index |
+| Notebook | `src/notebook/` | `notebook/` | the agent's sovereign space — any medium, seed-once charter the agent may rewrite; only `.gitignore` re-asserted |
 | Posture | `src/postures/` | inlined into `AGENT.md` | how much ceremony the agent brings to a task |
 | Mode | `src/modes/` | inlined into `AGENT.md` | the working axis (solo, foreman, …) — orthogonal to posture |
 | Context | `js/emit.mjs` | `context.json` | empty per-repo manifest, written once and never overwritten; git-ignore it |

package/QUICKSTART.md

@@ -10,7 +10,7 @@ repo inherits it, nothing committed into your projects. The only prerequisite is
 
 Same command on macOS, Linux and Windows (cmd, PowerShell, or any POSIX shell).
 
-Pick a **theme**, pick **OpenCode global** when asked for the install mode, confirm.
+Pick a **theme**, then accept the defaults for posture, mode, doctrine packs and footprint (or pick deliberately — see [setup choices](docs/web/setup-choices.md)), pick **OpenCode global** when asked for the install mode, confirm.
 The wizard builds the harness and offers a health check.
 
 Want the command to stay? `npm install -g geneseed`, then plain `geneseed …` from

package/README.md

@@ -12,7 +12,7 @@
 [![Themes](https://img.shields.io/badge/themes-14-9cf)](themes/)
 [![Skills](https://img.shields.io/badge/skills-47-blueviolet)](src/skills/)
 [![Agents](https://img.shields.io/badge/agents-17-orange)](src/agents/)
-[![Laws](https://img.shields.io/badge/laws-40-critical)](src/laws/universal.md)
+[![Laws](https://img.shields.io/badge/laws-9-critical)](src/laws/universal.md)
 [![Plugins](https://img.shields.io/badge/plugins-7-teal)](adapters/opencode/plugins/)
 [![OpenCode · Claude Code · Bob · Copilot · AGENT.md](https://img.shields.io/badge/works%20with-OpenCode%20·%20Claude%20Code%20·%20Bob%20·%20Copilot%20·%20AGENT.md-1f6feb)](#-supported-harnesses)
 
@@ -38,7 +38,7 @@ The lineage is also why an **imperial** theme ships alongside the neutral one: i
 
 ### How it works
 
-One canonical source in `src/` renders, via a tiny zero-dependency generator (`geneseed-build`), into a ready-to-use bundle. **A theme controls only *voice*** — how the AI responds and how the prose inside the docs reads (tagline, greeting, descriptions). **Structure is theme-independent**: section names (Rules, Agents, Skills, Memory…) and folder names (`laws/`, `agents/`, `skills/`, `memory/`, `notebook/`) are always plain English, so the scaffolding stays tool-friendly while the flavour lives in the words.
+One canonical source in `src/` renders, via a tiny zero-dependency generator (`geneseed-build`), into a ready-to-use bundle. **A theme controls only *voice*** — how the AI responds and how the prose inside the docs reads (tagline, greeting, descriptions). **Structure is theme-independent**: section names (Rules, Agents, Skills, Memory…), folder names (`laws/`, `ontology/`, `doctrines/`, `agents/`, `skills/`, `memory/`, `notebook/`) and the four ontology section headings (Telos, Evidence, Decisions, Conduct) are always plain English, so the scaffolding stays tool-friendly while the flavour lives in the words.
 
 ```bash
 geneseed-build                   # default theme (neutral)
@@ -148,11 +148,13 @@ No browser? Every action the console offers is also a verb: `build`, `doctor`, `
 
 ## 📦 4 · What you get
 
-The harness ships as a small set of layers, mirrored one-for-one in the web console's **Library** rail (Laws · Agents · Skills · Memory · Notebook):
+The harness ships as a small set of layers, and the web console's rail is the same shape — Constitution, Skills and Agents each have their own entry; Memory, Notebook and the wiki sit under Library:
 
 | Layer | What it is |
 | --- | --- |
-| **🛡️ Rules** (`laws/`) | 40 universal laws the agent obeys — secrets, scope, verify-before-assert, surface-failures, context economy, load-the-docs, tool-discovery, non-interactive-shell, untrusted-content, least-privilege, external-gate, root-cause, idempotency, calibrated-honesty, source-over-surface, restart-is-not-reload, total-teardown, cover-and-verify, prove-the-gate, answer-shape, stable-reference-codes… |
+| **🧭 Ontology** (`ontology/`) | the mind the rules govern, in four prose sections — **Telos** (the Pact: protect the user, the truth, the agent), **Evidence** (every claim graded by how it was obtained), **Decisions** (classify and tier by reversibility, show the real forks), **Conduct** (answer what was asked, once). Always in force, never toggleable |
+| **🛡️ Rules** (`laws/`) | 9 universal laws the agent obeys — always in force, never toggleable: sealed-secrets, one-intent-one-act, verify-before-assert, deletion-is-deliberate, surface-failures, data-not-orders, least-privilege, root-cause, external-gate |
+| **📐 Doctrines** (`doctrines/`) | practice packs, chosen per install at build time: **craft** (how code is written), **rigor** (how work is proven), **ops** (how the machine is operated), **process** (how a task is run). A doctrine rule may tighten a Rule, never repeal one, and the user's own `user-rules.md` outranks it. Pick with `geneseed-build --doctrines craft,rigor` (or `none`), or in the setup wizard; all four pack files ship on disk either way, so a citation into a pack you left out still resolves |
 | **🤖 Agents** (17) | capability specialists: `reviewer`, `tester`, `architect`, `docs`, `security`, `explorer`, `developer` — plus a debate **council** the `council` skill convenes: `advocate`, `skeptic`, `pragmatist`, `steward`, `visionary`, `user-advocate`, `framer`, `empiricist`, `operator`, `historian` |
 | **🛠 Skills** (47) | repeatable workflows: brainstorm · **clarify** · plan · **codebase-design** · **domain-modeling** · **wayfinder** · **tickets** · tdd · **develop** · debug · **prototype** · refactor · **ponytail** · **forge-mcp** · geneseed-code-review · **fresh-eyes** · **review-response** · commit · **ship** · **release** · **migrate** · **git-archaeology** · **git-rescue** · repo-map · document-project · **frontend-design** · **prose** · **ingest** · **research** · **learning-path** · **gap-detector** · **feynman** · **crash-course** · **drill** · **decode** · handoff · roast-me · **council** · parallel-agents · **workflow** · **wiki** · **geneseed** · **rule** · **profile** · **opencode-theme** · **herdr** · **pipeline** |
 | **🔌 Plugins** (OpenCode) | `geneseed-context` injects project docs *and your machine wiki* every session (and across compaction); `geneseed-learn` distils memory at session end; `geneseed-guard` enforces the safety Laws and protected wiki folders at the tool boundary; `geneseed-workflow` registers the `workflow` tool that runs saved orchestration scripts; `geneseed-notify` sends a native OS notification when a long run finishes; `geneseed-ponytail` holds a minimal-code mode (`/ponytail lite\|full\|ultra\|off`), opt-in, injecting the laziest-that-works ruleset every turn so it doesn't drift; `geneseed-activity` streams what each session is doing to the web console's Activity view |
@@ -181,16 +183,20 @@ Pick with `--theme NAME` or via the setup wizard. The theme is remembered in a `
 
 ### 🪶 Footprint (lean vs full)
 
-A second per-install dial, **footprint**, sets how much of the Rules `AGENT.md` carries *inline* every turn — a token-cost knob, not a change to which Rules apply (every Rule is always in force).
+A second per-install dial, **footprint**, sets how much of the constitution `AGENT.md` carries *inline* every turn — a token-cost knob, not a change to which Rules apply (every Rule is always in force, and so is the whole of the Ontology).
 
-| Footprint | Section 1 of `AGENT.md` | Trade-off |
+| Footprint | The Ontology + Sections 1–2 of `AGENT.md` | Trade-off |
 | --- | --- | --- |
-| **lean** *(default)* | each Rule's heading + the rule line, then a pointer to the full law file | ~40% smaller; rationale is one on-demand read away |
-| **full** | every Rule's complete text **and** rationale, inlined | maximum guidance density; largest per-turn token cost |
+| **lean** *(default)* | the Ontology **whole**; each Rule and each active doctrine rule as its heading + the rule line, then a pointer to the full text | lighter every turn; rationale is one on-demand read away |
+| **full** | the Ontology, every Rule and every active doctrine rule at complete text **and** rationale, inlined | maximum guidance density; largest per-turn token cost |
 
-Lean still ships the complete `laws/universal.md` beside `AGENT.md` and points the agent there before acting on secrets, deletion, git history, scope, or untrusted content — so it's a context/token optimization, **not** a rules cut. Lean is the default: the rationale is one read away and the context it frees is paid back on every turn. Switch to **full** when token cost is a non-issue or you run a smaller model, which leans harder on always-present rationale. Set it with `--footprint lean|full`, the Settings toggle, the per-harness dropdown in the Harnesses tab, or the setup wizard. It's remembered in a `.geneseed-footprint` marker and preserved across rebuilds, on every host (OpenCode, Claude Code, Bob, Copilot).
+**The Ontology is never truncated.** Lean keeps only the first sentence of each `### ` block, and the four ontology sections are flowing prose rather than numbered rules — truncating them would leave four orphan sentences, so they ship whole at both footprints. The invariants and the doctrine rules *are* truncated at lean, each to its heading plus its first sentence.
 
-Either way the harness is otherwise identical — same files, Rules, capabilities, and guards; lean only relocates each Rule's *reasoning* to on-demand (and adds the standalone laws file to global/Claude/Bob installs). The one behavioural edge: with the rationale always in context, **full** applies a rule's nuance more reliably on subtle edge cases — or with a weaker model that may not reach for the pointer — which is why it stays the default.
+Both footprints put the full text on disk beside `AGENT.md`: `laws/`, `ontology/` and `doctrines/` all ship in the bundle, and **all four pack files ship whether or not the pack was built in** — which is what lets a citation into an inactive pack resolve. So lean is a context/token optimization, **not** a rules cut. Measured on `neutral`, adding the ontology and doctrine tiers moved the always-loaded `AGENT.md` from 31,457 to 36,882 bytes at lean (+17.2%) and from 53,378 to 54,810 at full (+2.7%) — the lean growth is the price of shipping the ontology whole, and it was taken deliberately.
+
+Lean is the default: the rationale is one read away and the context it frees is paid back on every turn. Switch to **full** when token cost is a non-issue or you run a smaller model, which leans harder on always-present rationale. Set it with `--footprint lean|full`, the Settings toggle, the per-harness dropdown in the Harnesses tab, or the setup wizard. It's remembered in a `.geneseed-footprint` marker and preserved across rebuilds, on every host (OpenCode, Claude Code, Bob, Copilot).
+
+Either way the harness is otherwise identical — same files, Rules, capabilities, and guards; lean only relocates the *reasoning* to on-demand (and adds the standalone law, ontology and doctrine files to global/Claude/Bob installs). The one behavioural edge: with the rationale always in context, **full** applies a rule's nuance more reliably on subtle edge cases — or with a weaker model that may not reach for the pointer.
 
 Want to check a build before it touches anything real? `geneseed-build --validate-only --theme NAME --emit MODE --out TARGET` renders and validates into a throwaway sandbox — nothing under `--out`/`--root` is written — and exits non-zero on any problem. Details: [SETUP.md](SETUP.md#dry-run-a-build-validate).
 
@@ -214,10 +220,10 @@ is **identical on every host**. What differs is how much of it the host can
 | **Agents** (capability specialists) | ✅ native | ✅ | ✅ | ✅ `.agent.md` |
 | **Skills** (byte-identical) | ✅ | ✅ | ✅ | ✅ |
 | **Memory & Notebook** | ✅ | ✅ | ✅ | ✅ |
-| **Context injection** (Rule XVIII) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 📄 preamble |
+| **Context injection** | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 📄 preamble |
 | **Memory write-back** (learn) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 📄 preamble |
-| **Git-gate consent** (Rule XX) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 📄 preamble |
-| **Rule-gate consent** (Rule VI) | ⚙️ plugin² | 🪝 hook | 🪝 hook¹ | 📄 preamble |
+| **Git-gate consent** (process 5) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 📄 preamble |
+| **Rule-gate consent** (process 1) | ⚙️ plugin² | 🪝 hook | 🪝 hook¹ | 📄 preamble |
 | **Sovereign-repo excludes** | ⚙️ plugin | ✅ `claudeMdExcludes` | ✅ rules-shadow | ➖ none |
 | **MCP server wiring** | ✅ `mcp` | ✅ `mcpServers` | ✅ `mcpServers` | ✅ `mcp-config.json` |
 | **Colour themes** | ✅ full palette | ➖ | ➖ | ➖ |
@@ -253,7 +259,11 @@ Geneseed/
 ├── harness.config.json   default theme + metadata (the one owner of the version)
 ├── src/                  canonical source — edit here
 │   ├── AGENT.md.tmpl     the entrypoint, rendered to AGENT.md
-│   ├── laws/             governance rules
+│   ├── ontology/         how the agent thinks — Telos, Evidence, Decisions, Conduct
+│   ├── laws/             the universal invariants
+│   ├── doctrines/        the four practice packs (craft, rigor, ops, process)
+│   ├── postures/         the relationship register, inlined into AGENT.md
+│   ├── modes/            the operating register, inlined into AGENT.md
 │   ├── agents/           capability specialists
 │   ├── skills/           repeatable workflows
 │   ├── memory/           memory convention + index

package/SETUP.md

@@ -165,9 +165,11 @@ your repo's `.claude/settings.json` (paths assume the bundle is at the repo root
 It wires:
 
 - **PreToolUse** (matcher `Bash`) — runs `harness git-gate`, a tool-boundary backstop
-  for Law XX. The hook inspects the command and forces an `ask` on every `git commit`
-  or `git push` (even chained or `-C`-flagged), un-suppressible by a one-time "don't
-  ask again". Every other Bash command is deferred to the normal permission flow.
+  for Doctrine `process 5`. The hook inspects the command and forces an `ask` on every
+  `git commit` or `git push` (even chained or `-C`-flagged), un-suppressible by a
+  one-time "don't ask again". Every other Bash command is deferred to the normal
+  permission flow. It is wired only when the **process** pack is active — build with
+  `--doctrines` leaving `process` out and this hook is not installed at all.
 - **SessionStart** (`startup`/`clear`) — prints `AGENT.md` and injects the project
   context (`harness context`, which auto-discovers the repo's docs);
 - **SessionStart** (`resume`) — refreshes the project context only, without re-printing
@@ -286,17 +288,79 @@ doubles as a CI drift check: `1` when it had to change files, `0` when every the
 already in sync, and `2` when `_TEMPLATE.json` itself is missing or unreadable — the one
 case where a `0` would have meant "in sync" without having checked anything.
 
+### Doctrine packs
+
+The constitution is three tiers, and only one of them is a choice. The **Ontology** (how the
+agent thinks — Telos, Evidence, Decisions, Conduct) and the nine **Rules** (what it never
+trades away) are always on and cannot be switched off. The **Doctrines** are practices rather
+than principles, and they ship as four packs:
+
+| Pack | What it governs |
+| --- | --- |
+| **craft** | how code is written — reuse first, house conventions, docs in the same change, the smallest diff |
+| **rigor** | how work is proven — idempotence, honest tests, cover-and-verify, gates that can actually fail |
+| **ops** | how the machine is driven — tool discovery, commands that return, complete teardowns, restart is not reload |
+| **process** | how a session runs — planning, context economy, docs first, bounded loops, and the consent gate on every commit and push |
+
+They are picked **at build time**, once, on the generator — there is no runtime toggle — and
+the default is all four:
+
+    geneseed-build --doctrines craft,rigor   # two packs
+    geneseed-build --doctrines none          # ontology and the nine Rules only
+    geneseed-build                           # all four (the default)
+
+`harness.config.json`'s `doctrines` array sets this checkout's own default, and `doctor`
+refuses one that names a pack the checkout does not ship. Order is fixed by the harness
+(craft → rigor → ops → process) regardless of the order you type.
+
+The setup wizard asks too — one *all* / *choose* gate, then a yes/no per pack with its
+one-line description — and it **pre-selects what the install already carries**, read off the
+`Active packs:` marker line in the deployed `AGENT.md`. So re-running the wizard and holding
+Enter cannot silently widen a set you deliberately narrowed.
+
+**The whole catalogue always ships.** Every pack file lands under `doctrines/` beside
+`AGENT.md` at both footprints whether or not it was built in, so a rule that cites a pack you
+left out is still readable on disk — only the rendered `AGENT.md` is narrower. `doctor` reports
+such citations as a `[note]`, printed and not counted, because a narrowed build is a
+configuration you chose rather than a defect.
+
+⚠ **Turning `process` off also removes the commit/push consent gate.** Doctrine `process 5`
+(*Consent Before Push*) is enforced twice: as prose in `AGENT.md`, and at the tool boundary —
+the `git-gate` PreToolUse hook on Claude Code and Bob, and the `git commit*` / `git push*`
+permission entries on OpenCode. A build without the `process` pack wires neither, and
+rebuilding an install that had them takes the Claude hook back out of `settings.json`. That is
+deliberate and it is the rule the tiering rests on: **prompt and boundary must never
+disagree.** A gate that stops every command to ask consent for a rule the install did not adopt
+is a gate the agent cannot explain and you did not ask for. Two details worth knowing:
+
+- **What stays in every build regardless:** `rm -rf *`, `git push --force*` and `git push -f*`.
+  Those are Rule IV's territory — an always-on invariant — not the process pack's.
+- **On OpenCode, an existing `opencode.json` is not stripped.** That file is co-owned, nothing
+  on disk records who wrote a given permission entry, and Geneseed will not delete a line you
+  might have typed yourself. A pack-off rebuild leaves an already-written `git commit*` in
+  place and *reports* it instead. A fresh install has no git gate at all.
+
+`process` is the only pack whose removal changes what the machine does rather than only what
+the agent reads — which is why the wizard's blurb for it says so.
+
 ### Footprint (lean vs full)
 
-**Footprint** sets how much of the Rules `AGENT.md` carries *inline* on every turn — a
+**Footprint** sets how much of the constitution `AGENT.md` carries *inline* on every turn — a
 token-cost dial, not a change to which Rules apply. Both states keep all Rules in force:
 
-- **full** (default) — Section 1 inlines every Rule's complete text *and* rationale.
-  Maximum guidance density; the largest always-loaded block in the harness.
-- **lean** — Section 1 carries each Rule's heading + the rule line, then a pointer to the
-  full law file. ~40% smaller; the complete `laws/universal.md` still ships beside
-  `AGENT.md` and the agent reads it on demand (and is told to before acting on secrets,
-  deletion, git history, scope, or untrusted content).
+- **lean** (default) — Sections 1–2 carry the heading and rule line of each Rule and each
+  active doctrine rule, then a pointer to the full text. Lighter every turn; the complete
+  `laws/universal.md`, `ontology/` and `doctrines/` still ship beside `AGENT.md` and the agent
+  reads them on demand (and is told to before acting on secrets, deletion, git history, scope,
+  or untrusted content).
+- **full** — Sections 1–2 inline every Rule's and every active doctrine rule's complete text
+  *and* rationale. Maximum guidance density; the largest always-loaded block in the harness.
+
+**The Ontology is never truncated.** Lean keeps only the first sentence of each `### ` block,
+and the four ontology sections are flowing prose rather than numbered rules — cutting them
+would leave four orphan sentences, so they ship whole at both footprints. That is why adding
+the ontology tier grew the lean carrier proportionally more than the full one; it was taken as
+a deliberate cost.
 
 **Why:** context is scarce and metered. Lean reclaims that budget — and the tokens you
 pay for it — for the task, moving the *rationale* one read away while keeping the rules
@@ -310,10 +374,11 @@ you run a smaller model.
 can *do*: lean and full emit identical files (same agents, skills, plugins, commands, memory,
 notebook, hooks) and every Rule is present and binding. The only structural difference is
 that a lean install on a global / Claude / Bob / Copilot target also ships the standalone
-`laws/universal.md` (project bundles already carry it); the only behavioural difference is
-that each Rule's reasoning loads on demand instead of every turn. Lean is the default;
-full, with the rationale always in front of the model, applies a rule's nuance more
-reliably on subtle edge cases or with a weaker model, and is one flag away.
+`laws/universal.md` and `ontology/` (project bundles already carry them, and `doctrines/`
+ships at both footprints on every target); the only behavioural difference is that the
+reasoning loads on demand instead of every turn. Lean is the default; full, with the rationale
+always in front of the model, applies a rule's nuance more reliably on subtle edge cases or
+with a weaker model, and is one flag away.
 
 Set it with `--footprint lean|full` (alongside any `--emit`), the **Footprint** toggle in
 the web Settings, the per-harness dropdown in the Harnesses tab, or the setup wizard. It is
@@ -418,7 +483,7 @@ opt-in, now simply matches the default. To drop injection entirely, set
 If you keep a personal knowledge base on this machine — an Obsidian vault, or any
 folder of interlinked markdown — declare it once in **`wiki.jsonc`** and the agent
 becomes a citizen of it: entry notes load each session (eager) or on demand (lazy),
-and it reads *and writes* notes under your vault's own conventions (AGENT.md §7,
+and it reads *and writes* notes under your vault's own conventions (AGENT.md §8,
 the `wiki` skill). Unlike `context.json` this is **per machine, not per repo**.
 
 The build seeds `wiki.jsonc` beside `AGENT.md` (for a global install:
@@ -462,7 +527,7 @@ list keeps the feature off. The file may hold private paths — it is host-speci
 covered by the bundle `.gitignore`, and never committed.
 
 On tools without the plugins (plain `AGENT.md`, Claude Code), the same contract
-holds through prose: AGENT.md §7 instructs the agent to read `wiki.jsonc` at session
+holds through prose: AGENT.md §8 instructs the agent to read `wiki.jsonc` at session
 start and honour it.
 
 ### Memory
@@ -963,7 +1028,8 @@ capability agent. Notes:
 
 - **Permissions still gate.** The consent-before-commit/push / `rm -rf` `ask` rules
   will *block* in a non-interactive run (nothing to answer the prompt). Both
-  `git commit` and `git push` are gated now (Law XX, every branch), so a CI job that
+  `git commit` and `git push` are gated on every branch whenever the **process** pack
+  is active (Doctrine `process 5`; a build without it wires neither), so a CI job that
   commits must opt those commands back to `"allow"` in its own `permission.bash` map,
   or scope the run to read-only work — don't blanket-disable the guards.
 - **`--pure`** runs OpenCode ignoring local/global config — handy to reproduce a bug