geneseed 3.8.0 → 3.10.0

package/adapters/opencode/plugins/geneseed-context.js

@@ -56,6 +56,7 @@ import { promises as fs } from "node:fs"
 import * as path from "node:path"
 import { fileURLToPath } from "node:url"
 import { homedir } from "node:os"
+import { createHash } from "node:crypto"
 
 const MARKER = "<!-- geneseed-context:v2 -->"
 const PLUGIN_DIR = path.dirname(fileURLToPath(import.meta.url))
@@ -156,6 +157,49 @@ const EXCLUDE_DIRS = new Set([
 async function isFile(p) { try { return (await fs.stat(p)).isFile() } catch { return false } }
 async function isDir(p) { try { return (await fs.stat(p)).isDirectory() } catch { return false } }
 
+// ---- session files (the harness's own) --------------------------------------
+// The files AGENT.md names for session start, relative to the HARNESS dir — the dir that
+// holds the installed AGENT.md: the repo root for a project install, the config dir for a
+// global one. Same list and seed hashes as SESSION_FILES/SEED_SHA256 in js/hosts/hooks.mjs;
+// tests/unit/claude.test.mjs gates both copies against SESSION_SEEDS in js/build/stubs.mjs.
+// context.json is not here: it is a manifest, honoured by resolveSource. wiki.jsonc is not
+// here either: the MACHINE WIKI block below already renders it in full.
+const SESSION_FILES = ["user-rules.md", "PROFILE.md", "memory/MEMORY.md", "anamnesis/MEMORY.md",
+  "notebook/NOTEBOOK.md"]
+const SEED_SHA256 = new Set([
+  "5c2e92fb1acde041e02d9ebf158460d8ff7a07cbc2b447859631604610130721", // user-rules.md
+  "29e012c3c4349ea62a9082cbd04bb25599a0ec280d62c33f6e10742809471816", // PROFILE.md
+  "cccc917c34e6b990e821620bdb4739090151885ab71b6e85046f30a3b71fa5e8", // wiki.jsonc
+  "99c786049c260f6baf7aec68a5c0f59907861afe9b867da009440613bdddb907", // MEMORY.md
+  "9acb5c9d9cb5dac572104480f05b48cc144e676869bd60e86d8a15b1f6308184", // NOTEBOOK.md
+])
+
+// $GENESEED_HARNESS when set, else the first of <plugin dir>/.. (global: the config dir) and
+// <plugin dir>/../.. (project: .opencode/plugins -> the repo root) that holds AGENT.md.
+async function harnessDir() {
+  if (process.env.GENESEED_HARNESS && (await isDir(process.env.GENESEED_HARNESS))) {
+    return process.env.GENESEED_HARNESS
+  }
+  for (const d of [path.resolve(PLUGIN_DIR, ".."), path.resolve(PLUGIN_DIR, "..", "..")]) {
+    if (await isFile(path.join(d, "AGENT.md"))) return d
+  }
+  return null
+}
+
+// Session files present under the harness dir and changed from their seed: [{ rel, abs, text }].
+async function sessionFiles(dir) {
+  const found = []
+  if (!dir) return found
+  for (const rel of SESSION_FILES) {
+    const abs = path.join(dir, rel)
+    let text
+    try { text = (await fs.readFile(abs, "utf8")).replace(/\r\n/g, "\n") } catch { continue }
+    if (SEED_SHA256.has(createHash("sha256").update(text).digest("hex"))) continue
+    found.push({ rel, abs, text: text.replace(/\n+$/, "") })
+  }
+  return found
+}
+
 async function readJson(p) {
   try { return JSON.parse(await fs.readFile(p, "utf8")) } catch { return null }
 }
@@ -474,11 +518,13 @@ async function fromManifest(manifestFile, root) {
   return { eager: eager.sort(byRel), lazy: lazy.sort(byRel) }
 }
 
-async function resolveSource(root) {
+async function resolveSource(root, harness = null) {
   const explicit = process.env.GENESEED_CONTEXT
   if (explicit && (await isFile(explicit))) return { mode: "manifest", file: explicit }
-  for (const rel of [path.join(".harness", "context.json"), "context.json"]) {
-    const p = path.join(root, rel)
+  // The harness dir last: a repo's own manifest outranks the one seeded beside the install.
+  const cands = [path.join(root, ".harness", "context.json"), path.join(root, "context.json")]
+  if (harness) cands.push(path.join(harness, "context.json"))
+  for (const p of cands) {
     if (await isFile(p)) return { mode: "manifest", file: p }
   }
   return { mode: "discover" }
@@ -494,8 +540,12 @@ async function resolveSource(root) {
 async function resolveWikiFile() {
   const explicit = process.env.GENESEED_WIKI
   if (explicit && (await isFile(explicit))) return explicit
+  // The harness dir (which honours $GENESEED_HARNESS) first: on a PROJECT install the plugin
+  // sits in .opencode/plugins, so <plugin dir>/.. is .opencode, not the dir the seed landed in.
+  // <plugin dir>/.. stays as the fallback for an install without an AGENT.md.
   const bases = []
-  if (process.env.GENESEED_HARNESS) bases.push(process.env.GENESEED_HARNESS)
+  const harness = await harnessDir()
+  if (harness) bases.push(harness)
   bases.push(path.resolve(PLUGIN_DIR, ".."))
   for (const base of bases) {
     // wiki.json is the legacy name from earlier seeds — still honoured.
@@ -652,9 +702,27 @@ async function renderSet(out, { eager, lazy }, state) {
   state.lazy += lazyLines.length
 }
 
-async function buildBlock(sets, wikis = [], commands = []) {
+async function buildBlock(sets, wikis = [], commands = [], session = []) {
   const state = { spent: 0, injected: 0, lazy: 0, headingsRead: 0 }
 
+  // A session file discovery also found (user-rules.md at the root of a project install,
+  // whose harness dir IS the repo root) is injected once, in the session block.
+  const seen = new Set(session.map((s) => path.resolve(s.abs)))
+  const fresh = (x) => !seen.has(path.resolve(x.abs))
+  sets = { eager: sets.eager.filter(fresh), lazy: sets.lazy.filter(fresh) }
+  const ses = []
+  for (const s of session) {
+    const size = Buffer.byteLength(s.text, "utf8")
+    ses.push(`----- ${s.rel} -----`)
+    if (size > EAGER_FILE_KB * 1024) {
+      ses.push(`[demoted: ${s.rel} exceeded ${EAGER_FILE_KB} KB — read ${s.abs} on demand]`, "")
+      continue
+    }
+    ses.push(s.text, "")
+    state.spent += size
+    state.injected++
+  }
+
   const proj = []
   await renderSet(proj, sets, state)
 
@@ -675,8 +743,9 @@ async function buildBlock(sets, wikis = [], commands = []) {
     if (w.truncated) wik.push(`  [+${w.truncated} more notes in this wiki — explore its folders on demand]`, "")
   }
 
-  if (!proj.length && !wik.length) return null
+  if (!ses.length && !proj.length && !wik.length) return null
   const out = [MARKER]
+  if (ses.length) out.push("=== SESSION FILES — your harness files, injected at session start (untouched seeds skipped) ===", "", ...ses)
   if (proj.length) out.push("=== PROJECT CONTEXT — binding for this repo ===", "", ...proj)
   if (wik.length) out.push("=== MACHINE WIKI — the user's knowledge base, binding per AGENT.md §8 ===", "", ...wik)
   return { text: out.join("\n"), injected: state.injected, lazy: state.lazy, kb: kb(state.spent) }
@@ -686,13 +755,14 @@ async function buildBlock(sets, wikis = [], commands = []) {
 // and render the injection block — shared by the session.created injection and the
 // compaction hook (the transform path reuses it via cachedBlockText).
 async function resolveBlock(root) {
-  const src = await resolveSource(root)
+  const harness = await harnessDir()
+  const src = await resolveSource(root, harness)
   const sets = src.mode === "manifest"
     ? await fromManifest(src.file, root)
     : await discover(root)
   const wikis = await wikiSets()
   const commands = await discoverCommands(root)
-  return { block: await buildBlock(sets, wikis, commands), src }
+  return { block: await buildBlock(sets, wikis, commands, await sessionFiles(harness)), src }
 }
 
 // Per-process cache of the rendered block text for the transform path (root is fixed

package/adapters/opencode/plugins/geneseed-guard.js

@@ -2,9 +2,9 @@
 //
 // Enforces the safety Laws at the tool boundary (`tool.execute.before`), the same
 // "enforce by injection, don't just instruct" stance as the context plugin:
-//   - Law I  (Sealed Secrets):  block writes to private-key / credential files.
-//   - Law IV (Deletion Is Deliberate):  block catastrophic shell commands.
-//   - Doctrine process 1 (rule vs memory):  speed-bump the first write to user-rules.md
+//   - Sealed Secrets:  block writes to private-key / credential files.
+//   - Deletion Is Deliberate:  block catastrophic shell commands.
+//   - Persist Insight (rule vs memory):  speed-bump the first write to user-rules.md
 //     memory file — that choice belongs to the user, via the rule skill.
 //   - Wiki (AGENT.md §8):  block mutations under a declared wiki's `protected`
 //     folders — the user's knowledge base sets its own no-go zones in wiki.jsonc.
@@ -238,7 +238,7 @@ async function protectedPrefixes() {
   return prefixes
 }
 
-// ---- the rule / memory stores (Doctrine process 1) -----------------------------
+// ---- the rule / memory stores (Persist Insight) --------------------------------
 // Whether something the user wants kept is a standing rule or a durable fact is THEIR
 // call, settled through the rule skill. `tool.execute.before` can only allow or throw —
 // it has no "ask the user" tier like the Claude/Bob rule-gate hook —
@@ -285,13 +285,13 @@ export const GeneseedGuard = async () => {
       try {
         if (hasAny(tool, WRITE_TOOLS)) {
           const p = pickPath(args)
-          if (p && SECRET_RE.some((re) => re.test(p))) { await deny(`write to secret/key file ${p} (Law I)`, "law-1"); return }
-          if (p && SECRET_WARN_RE.some((re) => re.test(p))) log(`WARN: writing ${p} — keep secrets out of tracked files (Law I)`)
+          if (p && SECRET_RE.some((re) => re.test(p))) { await deny(`write to secret/key file ${p} (Sealed Secrets)`, "law-1"); return }
+          if (p && SECRET_WARN_RE.some((re) => re.test(p))) log(`WARN: writing ${p} — keep secrets out of tracked files (Sealed Secrets)`)
           const store = p && ruleStoreTarget(p)
           if (store && !RULE_STORE_BUMPED.has(p)) {
             RULE_STORE_BUMPED.add(p)
             await deny(`writing to ${store} — a standing rule, or a fact to remember? That ` +
-                 `choice is the user's (Doctrine process 1). Settle it through the rule skill, ` +
+                 `choice is the user's (Persist Insight). Settle it through the rule skill, ` +
                  `then re-issue this write`, "process-1")
             return
           }
@@ -309,8 +309,8 @@ export const GeneseedGuard = async () => {
         // classes, and the shell check must still run after the write check.
         if (hasAny(tool, SHELL_TOOLS)) {
           const c = pickCommand(args)
-          if (c && SHELL_BLOCK_RE.some((re) => re.test(c))) { await deny(`catastrophic command (Law IV): ${c.slice(0, 80)}`, "law-4"); return }
-          if (c && SHELL_WARN_RE.some((re) => re.test(c))) log(`WARN: irreversible op — confirm intent (Law IV): ${c.slice(0, 80)}`)
+          if (c && SHELL_BLOCK_RE.some((re) => re.test(c))) { await deny(`catastrophic command (Deletion Is Deliberate): ${c.slice(0, 80)}`, "law-4"); return }
+          if (c && SHELL_WARN_RE.some((re) => re.test(c))) log(`WARN: irreversible op — confirm intent (Deletion Is Deliberate): ${c.slice(0, 80)}`)
         }
       } catch (err) {
         // Our own deny must propagate; any inspection error must never break a tool call.

package/adapters/opencode/plugins/geneseed-workflow.js

@@ -89,7 +89,7 @@ function summarize(name, result, stats, tracePath) {
 }
 
 // Kept worktrees are work awaiting review, and an overlap is a conflict awaiting ONE
-// merger (process 7) — both are said out loud, never left for the trace to hold.
+// merger (One Writer Per File) — both are said out loud, never left for the trace to hold.
 function isolationReport(stats) {
   const kept = stats.worktrees || []
   if (!kept.length) return ""

package/adapters/opencode/workflows/_runtime.js

@@ -182,8 +182,8 @@ async function runChildSession(client, { prompt, agent, model, title, directory
 
 // ---- worktree isolation ------------------------------------------------------
 // `agent(prompt, { isolation: "worktree" })` — the same option Claude Code's Workflow
-// takes. Parallel editors in one tree lose each other's writes (process 7, one writer per
-// file), so each isolated agent gets its own branch + worktree off the root's HEAD, and
+// takes. Parallel editors in one tree lose each other's writes (One Writer Per File),
+// so each isolated agent gets its own branch + worktree off the root's HEAD, and
 // the files it changed are recorded for `overlaps()`. A worktree with no change is
 // removed with its branch; one with changes is KEPT for the parent to review and merge —
 // the runtime never merges, commits, or deletes work. `git(argv, cwd)` is injected by the

package/adapters/opencode/workflows/dispatch.js

@@ -3,7 +3,7 @@
 //
 // The model-driven fallback is the parallel-agents skill; this runs the same
 // shape on rails: the script, not the model, enforces routing and the handoff
-// envelope (context in, output contract back, no commits — Doctrine process 5 stays with
+// envelope (context in, output contract back, no commits — Consent Before Push stays with
 // the caller).
 //
 // args: { goal: string, context?: string, agents?: string[] }

package/bin/geneseed-hook.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * The hook entry point — a Node twin of `rituals/harness.py` for the verbs the emitted
- * `settings.json` actually invokes (four from the reference, plus `tool-gate` for Copilot).
+ * `settings.json` actually invokes (four from the reference, plus `tool-gate` for Bob).
  *
  * WHY IT IS A SECOND BINARY AND NOT A SUBCOMMAND OF `bin/build-driver.mjs`. Three reasons,
  * and each alone would be enough:

package/docs/candidate-hosts.md

@@ -38,8 +38,7 @@ current host gets. Skills are the largest surface by file count and they cost no
   Claude's, and `permissionDecision: "ask"` exists. The Claude engine with `host: "codex"`
   covers instructions (`AGENTS.md`), skills (`.agents/skills`) and the hook verbs
   unchanged; the only new code is the carrier writer (a `hooks.json` merge or a TOML
-  table) and the config-dir resolver (`~/.codex`, `$CODEX_HOME`). Roughly the Copilot
-  port minus the dialect work.
+  table) and the config-dir resolver (`~/.codex`, `$CODEX_HOME`).
 
 - **Gemini CLI — Claude's groups, Gemini's names.** The hook groups are Claude's
   `event → [{matcher, hooks}]` and the payload fields are Claude's, but the events are
@@ -54,7 +53,7 @@ current host gets. Skills are the largest surface by file count and they cost no
 - **Cursor — a third verdict dialect.** `AGENTS.md` and `.agents/skills` are free; hooks
   are `hooks.json` with a `{command}` list per event and a `permission: allow|deny`
   verdict, `additional_context` in snake_case for `sessionStart`. Same block-or-warn stance
-  as Copilot, one more output spelling in `js/hosts/hooks.mjs`, one more carrier writer.
+  as Bob, one more output spelling in `js/hosts/hooks.mjs`, one more carrier writer.
   Cursor also reads `.claude/skills/`, so a Claude project install already gives a Cursor
   user the skills.
 
@@ -64,8 +63,16 @@ If a fifth host is wanted, Codex first: it reuses the most and it is the only ca
 where the gates can *ask* rather than block. Before any of them, a `--emit agents` for
 the shared `.agents/skills/` folder would give Codex, Cursor and Gemini users the whole
 skill catalogue for the price of one directory name, with no host-specific code at all.
-A Gemini host would be the fourth verdict spelling in `js/hosts/hooks.mjs` (after Claude's
-ask, Copilot's block, Bob's exit code 2), plus a resolver and a carrier.
+A Gemini host would be the third verdict spelling in `js/hosts/hooks.mjs` (after Claude's
+ask and Bob's exit code 2), plus a resolver and a carrier.
+
+## Evaluated, dropped
+
+- **GitHub Copilot** — shipped as a host through 3.9.0, removed in 3.10.0. Dropped for lack
+  of support: its hooks were never verified live, its `postToolUse` output does not reach
+  the model, and it shared no cross-tool surface with the other hosts (camelCase payloads,
+  matcherless hook entries, its own agent dialect and carrier), so every feature needed a
+  Copilot-only decision.
 
 ## Not verified
 

package/docs/extending.md

@@ -155,36 +155,43 @@ Notes that matter:
 
 ## 2 — Changing the constitution
 
-Three tiers, four different costs. The addresses are `{{LAW}} <roman>` for an invariant and
-`{{DOCTRINE}} <pack> <n>` for a doctrine rule; the ontology is cited by section name and adding a
-section to it is not a checklist, it is a design change.
+Three tiers, four different costs. Every law and doctrine rule has a **permanent id** — kebab-case,
+derived from its English principle when it is created (`verify-before-asserting`,
+`consent-before-push`) — declared by its heading, `### {{LAW:<id>}} <Principle Name>` or
+`### {{DOCTRINE:<id>}} <Principle Name>`, and cited by it: `{{LAW:<id>}}`, `{{DOCTRINE:<id>}}`.
+**The number is not stored anywhere.** `ruleCanon` in `js/build/source.mjs` computes it from the
+rule's position (Roman in `laws/universal.md`, Arabic within its pack) at render time; the heading
+renders `Rule III — <themed title>` and a citation renders as the principle's name, in italics,
+identical in every voice — the same string an agent is told to write into its memory. So adding,
+removing or reordering a rule rewires nothing. `constitutionProblems` refuses a citation by number,
+an unknown id, a duplicate id, a heading with no id, and a retired id declared again. The ontology is
+cited by section name, and adding a section to it is not a checklist, it is a design change.
 
 To count the cross-references either tier already carries, from the repo root:
 
 ```bash
-grep -rhoE "\{\{LAW\}\} [IVXL]+" src/ | wc -l
-grep -rhoE "\{\{DOCTRINE\}\} [a-z]+ [0-9]+" src/ | wc -l
+grep -rhoE "\{\{LAW:[a-z0-9-]+\}\}" src/ | wc -l
+grep -rhoE "\{\{DOCTRINE:[a-z0-9-]+\}\}" src/ | wc -l
 ```
 
-On this checkout that reports 153 and 209. Both numbers move on every wave of editing, which is
-why the commands are here and the answers are not load-bearing.
+Both numbers move on every wave of editing, which is why the commands are here and the answers are
+not.
 
 ### 2a — Adding a DOCTRINE RULE (the common case)
 
 Five files, plus the written-out rule totals in four test files. This is the slot most new
 material belongs in, and it is cheap on purpose so that the invariant slot stays scarce.
 
-1. `src/doctrines/<pack>.md` — **append** `### {{DOCTRINE}} <pack> <n> — {{DOC_<PACK>_<n>}}` plus
-   the body, wrapped in a `LEAN` block with **both halves authored** — the heading stays outside the
-   block, the full text goes in `LEAN:begin`, and the lean half is the rule *and its mechanism*, no
-   maxims (the style rule is in `src/doctrines/README.md`, and `leanBlockProblems` refuses a rule
-   with no block or an empty half). Two gates in `constitutionProblems`
-   (`js/inspect/checks-authoring.mjs`) sit on this too: 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
-   this file renumbers.
-2. `themes/_TEMPLATE.json` — add `DOC_<PACK>_<n>`. ⚠ **This file *is* gated for this key family.**
+1. `src/doctrines/<pack>.md` — add `### {{DOCTRINE:<new-id>}} <Principle Name>` plus the body,
+   wrapped in a `LEAN` block with **both halves authored** — the heading stays outside the block,
+   the full text goes in `LEAN:begin`, and the lean half is the rule *and its mechanism*, no maxims
+   (the style rule is in `src/doctrines/README.md`, and `leanBlockProblems` refuses a rule with no
+   block or an empty half). The id is kebab-case, unique across laws **and** doctrines, and never
+   one listed in `RETIRED_RULE_IDS` (`js/build/source.mjs`). Where it goes in the file decides its
+   number; appending is still the kind move, because `excludeRules`, `DOCTRINE_META` and the
+   hook-gated addresses are keyed `<pack>.<n>` (see §2e).
+2. `themes/_TEMPLATE.json` — add `DOC_<ID>` (`consent-before-push` → `DOC_CONSENT_BEFORE_PUSH`).
+   ⚠ **This file *is* gated for this key family.**
    `themeFiles()` filters `_`-prefixed names and theme parity never sees the template, but
    `constitutionProblems` reads it alongside the fourteen voices for `DOC_*` and `LEX_*`
    specifically — because it is what `--sync-themes` seeds the *next* voice from. Every other key
@@ -199,7 +206,9 @@ material belongs in, and it is cheap on purpose so that the invariant slot stays
    is one of the two. See §7.2 before you copy a command from anywhere else. Then restyle all
    fourteen by hand: `--sync-themes` writes the template's placeholder and only *prints*
    `RESTYLE these`; a shipped placeholder passes every gate.
-4. `web/src/pages/Laws.jsx` — a `DOCTRINE_META` row keyed `'<pack>.<n>'`. Its first field is the
+4. `web/src/pages/Laws.jsx` — a `DOCTRINE_META` row keyed `'<pack>.<n>'`, whose third field is the
+   rule's id — `doctrineMetaProblems` holds that pin to the canon, so a row left behind by a
+   renumber is a failure rather than a description of the neighbour. Its first field is the
    **pack**, not one of `LAW_CLASSES`' six; `doctrineMetaProblems` requires an *equality* between
    that field and the key's own pack, which catches the copy error a six-way vocabulary cannot — a
    row pasted from the pack above it, keeping the wrong pack. Its second field is the one-line
@@ -213,19 +222,18 @@ material belongs in, and it is cheap on purpose so that the invariant slot stays
   there is no second taxonomy over it.
 - **No count in the product.** No badge, no `SHIPPED.md` triple, no prose mirror. The console spends
   `{N_PACKS}` / `{N_PACKS_ACTIVE}` / `{N_DOCTRINE_RULES}`, all computed at request time.
-- **No renumber risk.** But there *are* written-out rule totals to bump — expected values are
+- **No citation to rewire.** But there *are* written-out rule totals to bump — expected values are
   written out, never recorded — in `tests/unit/emit_smoke.test.mjs`, `harness.test.mjs`,
   `setup.test.mjs` and `web_api.test.mjs`. Each fails loudly with the new count; change the
   number *and* the comment that explains it. A rule in **craft** moves more: `setup` and
   `web_api` also pin the craft-only narrowed counts, `generate.test.mjs` excludes every craft
-  rule by address to empty the pack, and `harness.test.mjs`'s contiguity fixture plants a rule at
-  the first free craft id — the doctrine twin of §2c step 8. Grep `tests/` for the previous
+  rule by address to empty the pack. Grep `tests/` for the previous
   rule's address before trusting this list. A rule long enough to matter can also breach the
   `full` carrier ceiling in `emit_smoke` — raise it with a dated note there, as every earlier
   move did.
 
 ⚠ **Cite only downward.** An always-on tier may never reference a toggleable one:
-`constitutionProblems` refuses a `{{DOCTRINE}}` token anywhere under `src/ontology/` or
+`constitutionProblems` refuses a `{{DOCTRINE:…}}` token anywhere under `src/ontology/` or
 `src/laws/`, because a `--doctrines craft` build would then ship an invariant pointing at text its
 `AGENT.md` does not contain. Doctrine→doctrine citations are fine and stay — every pack file ships
 on disk whether or not it was built in. If the build's own default is narrowed,
@@ -248,26 +256,25 @@ Steps 1 and 9 of §2c, plus `LAW_META` if the Principle line moved. Two cautions
 Nine steps, and only the first is the rule itself. This is the expensive one, and it should be:
 the bar is in `DESIGN.md` Decision 7, and most candidates belong in a doctrine pack instead.
 
-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/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_XI` as an **equality** across all fifteen files (the
-   fourteen voices and the template), so both a missing key *and* a leftover one are reported. That
-   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.
+1. `src/laws/universal.md` — add `### {{LAW:<new-id>}} <Principle Name>` plus the body. Citations
+   are by id and resolve against the canon, so position is safe to choose — but append unless the
+   order is the point: `LAW_CLASS` and `LAW_META` are keyed by the rendered number (see §2e).
+2. `themes/_TEMPLATE.json` — add `LEX_<ID>` in template order. Gated, as in §2a step 2:
+   `constitutionProblems` holds the `LEX_*` keys as an **equality** with the declared law ids across
+   all fifteen files (the fourteen voices and the template), so both a missing key *and* a leftover
+   one are reported. That arm exists because an old renumber left `LEX_XXII`, `LEX_XXIII`,
+   `LEX_XXIV` and `LEX_XXXVI` behind in every file and parity was silent.
 3. `--sync-themes`, then restyle all fourteen by hand (§2a step 3).
 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
+5. `LAW_META` in `web/src/pages/Laws.jsx` — same class, the one-line Principle, and the rule's id
+   as the pin. Note the map is keyed by **arabic** number where the heading renders a Roman numeral. **This copy
    exists nowhere else**; a rule absent here renders with a blank description. It is why that one
    React file ships alone out of `web/src` in `package.json` — `doctor` regex-parses its literal.
 6. `README.md` — badge `badge/laws-N` and the `N universal laws` sentence.
 7. `SHIPPED.md` — the `N laws, N agents, N skills` triple.
-8. `tests/unit/harness.test.mjs` — the negative fixture for the `LAW_CLASS` gate plants a rule at
-   the *first free numeral*, which is `XII` now that the invariants are I..XI. Bump it, or it stops
-   being a fixture and starts being a duplicate.
+8. `tests/unit/harness.test.mjs` — the negative fixture for the `LAW_CLASS` gate appends a law and
+   expects the next numeral (`X` while there are nine), and `ROMANS` there and in `emit_smoke`
+   lists the numerals written out. Bump both.
 9. `CHANGELOG.md`, then rebuild and commit `web/dist` (step 5 touched `web/src`).
 
 ⚠ While restyling, `{{LAW}}` must stay a **single word** in every theme (and so must
@@ -288,8 +295,8 @@ the only configuration it can speak for.
 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.
+   file `PACK_ORDER` names but cannot read, or one declaring no `### {{DOCTRINE:<id>}}` rule at
+   all, is a refusal.
 2. `PACK_ORDER` in `js/build/source.mjs` — the registration, and the render order. It is **narrative,
    not alphabetical** (craft → rigor → ops → process → comms); discovery sorts alphabetically and the
    renderer refuses a `.md` under `src/doctrines/` that `PACK_ORDER` does not name, rather than
@@ -315,6 +322,31 @@ Rare, and mechanical. On top of §2a for each rule the pack carries:
 
 ---
 
+### 2e — Removing, retiring or reordering a rule
+
+Delete the rule's heading and both LEAN halves, and every rule after it renumbers on the next
+render — no citation moves, because none names a number. Then:
+
+1. `RETIRED_RULE_IDS` in `js/build/source.mjs` — add the id with what it was and where its text
+   went. `constitutionProblems` refuses a retired id declared again, so an id that meant one rule in
+   someone's notes can never come back meaning another. `liveAs` names the one tier that may still
+   declare it (Law IX's `external-gate` lives on as a rigor rule).
+2. Every citation of the removed id — the doctor names each one; point it at the rule that now
+   carries the text.
+3. Its `LEX_<ID>`/`DOC_<ID>` key in all fifteen theme files (the equality arm names each).
+4. The number-keyed tables, which the doctor checks against the canon: `LAW_CLASS`
+   (`js/inspect/inventory.mjs`), `LAW_META`/`DOCTRINE_META` (their id pins fail on every shifted
+   row), and — only if a hook-gated rule moved — `HOOK_PINNED` in `checks-authoring.mjs` names the
+   ledger keys, `CONSENT_RULE` and `HOOK_GATED` to move with it. `--exclude-rules` addresses are
+   `<pack>.<n>` too, and an install that excluded a shifted doctrine rule excludes its neighbour
+   after a re-emit: prefer appending in a pack, and say so in the CHANGELOG when you cannot.
+5. The count mirrors: README badge and prose, `SHIPPED.md`, and the written-out totals in tests.
+
+Laws IX (External Gate) and XI (Absence Is a Claim) were removed this way on 2026-09-30; Echo the
+Intent became IX.
+
+---
+
 ## 3 — Adding a SKILL or an AGENT
 
 **Order matters at the first two steps.** `missingReferencedSpecs` (in `js/build/bundle.mjs`) *aborts the
@@ -574,7 +606,7 @@ only, at best, on its presence.
 |---|---|---|
 | `§N` cross-references into `AGENT.md`'s anatomy | `src/skills/*`, `src/agents/*`, `adapters/**` | **range only.** `constitutionProblems` refuses a `§N` the template declares no section for — which catches a pointer past the end, the shape *removing* a section leaves. It cannot catch one that still resolves and now means something else, which is the shape *inserting* a section leaves, and is what actually happened when `## 2. Doctrines` pushed every later section down one. **Renumbering the anatomy means `grep -rn '§' src/ adapters/` and reading every hit.** Four satellites and a live OpenCode deny message shipped stale because the sweep stopped at `AGENT.md.tmpl` |
 | Per-law Principle lines | `web/src/pages/Laws.jsx` | presence and class only, never accuracy |
-| 588 themed constitution titles (42 keys × 14 voices) — `LEX_I..LEX_XI` (11), `DOC_<PACK>_<n>` (27), `PACK_<NAME>` (4) | `themes/*.json` | key presence only — a shipped placeholder is green. `LEX_*` and `DOC_*` are held across the template too, and in both directions; `PACK_*` only across the voices |
+| 588 themed constitution titles (42 keys × 14 voices) — `LEX_<ID>` (one per law), `DOC_<ID>` (one per doctrine rule), `PACK_<NAME>` | `themes/*.json` | key presence only — a shipped placeholder is green. `LEX_*` and `DOC_*` are held across the template too, and in both directions; `PACK_*` only across the voices |
 | 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 |

package/docs/token-footprint.md

@@ -15,33 +15,33 @@ heavier on the root file.
 
 The context every host injects at session start, before you type anything:
 
-| Component | Claude Code | OpenCode | Bob | Copilot |
-|---|---|---|---|---|
-| Root instruction file | ~7.3k (`CLAUDE.md`) | ~7.3k (`AGENT.md`) | ~7.7k (`AGENTS.md`, §3 table inline) | ~9.0k (`AGENTS.md`, §3+§4 tables inline) |
-| Skill metadata (name + description) | ~4.1k | ~4.1k | ~4.1k (native) | — (§4 table; native catalogue unverified) |
-| Agent metadata | ~0.5k | ~0.5k | — (no agents directory) | — (§3 table) |
-| Eager memory/notebook injection | ~1.2k (SessionStart hook) | ~1.2k (context plugin) | ~1.2k (SessionStart hook) | ~1.2k (sessionStart hook) |
-| **Total** | **~13k** | **~13k** | **~13k** | **~10k** |
+| Component | Claude Code | OpenCode | Bob |
+|---|---|---|---|
+| Root instruction file | ~7.2k (`CLAUDE.md`) | ~7.2k (`AGENT.md`) | ~7.5k (`AGENTS.md`, §3 table inline) |
+| Skill metadata (name + description) | ~4.1k | ~4.1k | ~4.1k (native) |
+| Agent metadata | ~0.5k | ~0.5k | — (no agents directory) |
+| Session files (rules, profile, Memory/Notebook indexes, wiki) | 0 fresh, grows with use (SessionStart hook) | 0 fresh, grows with use (context plugin) | 0 fresh, grows with use (SessionStart hook) |
+| **Total** | **~12k** | **~12k** | **~12k** |
 
-The emits are at parity by design: ~10–13k tokens, about 6% of a 200k
+The emits are at parity by design: ~12k tokens, about 6% of a 200k
 window. Bob catalogues skills natively but has no agents directory, so its
 root keeps the §3 Agents table and drops the §4 Skills table — the catalogue
 flag is per kind (`hostCatalogsNatively`), not one boolean. Before the 2026-09 footprint pass every hooked host paid roughly double
 this: the context hook re-injected the root file the host had already loaded
 natively, and skill descriptions ran to 900 characters each — see the
-"Where the tokens go" list below for what changed. Bob and Copilot carry the §3/§4 catalogue tables inline because their
-hosts expose no native skill/agent inventory; Claude Code and OpenCode ship a
-pointer to the host's own inventory instead, ~1.9k tokens lighter. Copilot's
-eager injection rides its `sessionStart` hook, which the **global** emit wires;
-a project-scope Copilot install has no hooks, so there the memory/notebook
-indexes load when the agent reads them, not eagerly. The
+"Where the tokens go" list below for what changed. Bob carries the §3/§4 catalogue tables inline because its host exposes
+no native skill/agent inventory; Claude Code and OpenCode ship a
+pointer to the host's own inventory instead, ~1.9k tokens lighter. A session file still
+byte-identical to its seed is skipped — it says nothing — so a fresh install injects none
+of them; until 2026-10 the hook read them from the repo root, where a Claude-shaped install
+never puts them, and none reached the session at all. The
 eager-injection path is budget-capped identically everywhere — 16 KB per file
 (cut at a line break, with a marker saying so) and 48 KB per session (files past
 the budget are listed lazy with the reason) — so a 40k-character README no
 longer leaves whole every session, and growing Memory degrades every host the
 same way instead of one silently falling behind. The hook also **never injects
 the root file the host loads by itself** (`CLAUDE.md` on Claude Code,
-`AGENTS.md` on Bob and Copilot, `AGENT.md`/`AGENTS.md`/`CLAUDE.md` on OpenCode):
+`AGENTS.md` on Bob, `AGENT.md`/`AGENTS.md`/`CLAUDE.md` on OpenCode):
 until 2026-09 it did, and the whole harness was paid twice per session.
 
 ## Where the tokens go
@@ -72,10 +72,17 @@ until 2026-09 it did, and the whole harness was paid twice per session.
   capped at 320 characters (`skillDescription` in `js/hosts/native.mjs`); at
   the earlier 900-character cap the catalogue weighed ~5.6k tokens. The later
   trigger sentences still live in the body, read as soon as the skill is chosen.
-- **§5–§10 carry authored lean halves too** (Memory, Notebook, Workspace, Wiki,
-  Context, Scripts): each keeps its obligations — read `MEMORY.md`, read
+- **§5–§9 carry authored lean halves too** (Memory, Notebook, Workspace, Wiki,
+  Context): each keeps its obligations — read `MEMORY.md`, read
   `context.json` before the first reply, the git-ignored folders — and points at
-  the on-disk README or config file for the rest.
+  the on-disk README or config file for the rest. §10 (Scripts) is full-only: it
+  describes the CLI to a reader, not an obligation to the agent.
+- **Restated prose is full-only** (2026-10): the laws and Ethos intros, the §2
+  pack intro, the posture/mode intros, §3's dispatch envelope and council roster
+  (they live in the parallel-agents and council Skills; the lean root keeps
+  "dispatched agents never commit or push"), and the folder-Skill list, which
+  now sits in the §4 catalogue half and so drops wherever the host catalogues
+  Skills natively.
 - **Skill bodies (~53k) and agent bodies (~10k) are lazy** on every host —
   loaded only when invoked. A typical skill costs ≤3k per invocation; the
   heaviest (`react-view-transitions`, ~17.5k with its reference files) loads
@@ -97,9 +104,7 @@ token counter also includes, none of which Geneseed controls:
    definitions. On OpenCode this is typically 5–10k tokens before any
    harness content loads.
 2. **Your repo's docs, injected eagerly** — the context delivery
-   (plugin on OpenCode, SessionStart hook on Claude Code / Bob, `sessionStart`
-   hook on a global Copilot install; a project-scope Copilot install has no
-   hooks, so it reads docs on demand instead) discovers and
+   (plugin on OpenCode, SessionStart hook on Claude Code / Bob / OpenClaude) discovers and
    injects `README.md`, `CONTRIBUTING.md`, and files under `docs/`, up to the
    48 KB budget (≈12k tokens). A doc-heavy repo fills it.
 3. **Wiki eager entries** plus the lazy listing of the rest, if a wiki is

package/docs/web/claude-hooks.md

@@ -11,7 +11,7 @@ Claude Code has no `instructions` array and no JS plugin dir — the harness rea
 - **Context injection** — `SessionStart` (startup, clear, resume) runs `geneseed-hook context`: auto-discovers the repo's docs by convention and injects them before your first turn, plus your machine wiki. It honours the same `GENESEED_CONTEXT` manifest as the OpenCode context plugin.
 - **Git gate** — `PreToolUse` on Bash runs `geneseed-hook git-gate`: a `git commit` or `git push` anywhere in the command line — a compound one-liner and a `-C <path>` form included — asks first, at the tool boundary and before the shell runs it (**Doctrine process 5**). It is the one hook that rides a doctrine pack: an install built without **process** never gets this group, because a boundary that keeps asking for a rule the install did not adopt is a gate arguing with its own harness.
 - **Rule gate** — `PreToolUse` on the write tools runs `geneseed-hook rule-gate`: a write to `user-rules.md` or to a memory file asks first, because whether something you want kept is a standing rule or a durable fact is *your* call, settled through the [rule skill](#/docs/skills) (**Doctrine process 1**). Ordinary edits are untouched.
-- **Tool gate** — `geneseed-hook tool-gate` is the git gate and the rule gate fused behind one command, for hosts whose hook config has no per-tool matcher (Copilot, Bob). Claude Code matches per tool, so its `settings.json` wires the two gates above instead.
+- **Tool gate** — `geneseed-hook tool-gate` is the git gate and the rule gate fused behind one command, for hosts whose hook config has no per-tool matcher (Bob). Claude Code matches per tool, so its `settings.json` wires the two gates above instead.
 - **Learn** — `Stop` and `SubagentStop` run `geneseed-hook learn`: distils durable memories into the install's `memory/` store at session end; a subagent's stop routes to the per-agent lesson path (`memory/agents/<name>.md`).
 
 ### Where they live

package/docs/web/collaboration.md

@@ -4,7 +4,7 @@ order: 11
 title: "The collaboration layer"
 kind: "concept"
 ---
-Beside the [constitution](#/docs/rules), a handful of mechanisms shape *how* the agent works with you — the two registers, the mutual contract, how memory binds, and who you are. All of them are plain content in `AGENT.md` and its neighbours, so they ride to every host (OpenCode, Claude, Bob, Copilot) unchanged.
+Beside the [constitution](#/docs/rules), a handful of mechanisms shape *how* the agent works with you — the two registers, the mutual contract, how memory binds, and who you are. All of them are plain content in `AGENT.md` and its neighbours, so they ride to every host (OpenCode, Claude, Bob, OpenClaude) unchanged.
 
 ### Postures — the register
 

package/docs/web/exclusions.md

@@ -17,7 +17,6 @@ Exclusion is all-or-nothing per folder — it doesn't trim which Rules apply or
 - **OpenClaude** — the same `claudeMdExcludes`, in the repo's `.openclaude/settings.local.json`.
 - **Bob** — a shadow `rules/geneseed.md` stub that shadows the global one (never overwrites a hand-written stub already there).
 - **OpenCode** — the hook entry's sovereign-bypass guard and its twin in the plugins short-circuit at session start.
-- **Copilot — documented limitation.** GitHub Copilot has no native per-repo suppression hook: the global `copilot-instructions.md` still loads even inside an excluded folder.
 
 ### Manage it
 

package/docs/web/footprint.md

@@ -26,7 +26,7 @@ Neither setting hides text from the agent; they hide it from *every turn*.
 
 ### How to set it
 
-It's set-and-forget — stored in the `.geneseed-footprint` marker, preserved across every rebuild, identical on every host (OpenCode, Claude Code, Bob, Copilot, OpenClaude). Changing it re-emits the install.
+It's set-and-forget — stored in the `.geneseed-footprint` marker, preserved across every rebuild, identical on every host (OpenCode, Claude Code, Bob, OpenClaude). Changing it re-emits the install.
 
 - **Settings** — the **Footprint** toggle flips the current install (full ⇄ lean) and rebuilds it in place.
 - **Harness tab** — on an active install, a per-harness dropdown sets it for that install independently, then **Apply**. On a host that is not installed yet, it is step 2 of **Install…**.