geneseed 3.4.0 → 3.5.0

package/SETUP.md

@@ -35,11 +35,11 @@ that matches your tool, then configure and verify. For the conceptual overview s
 Nothing in this guide needs a second interpreter. Three things are worth stating plainly,
 because each is a live constraint rather than a footnote:
 
-- **0 commands have no Node twin**: every command in this guide answers from the Node
-  entry points. There is no full-screen browse panel: `geneseed tui` and `geneseed menu`
-  are verbs that say the panel is not here and print the command list instead, and off a
-  terminal (which is how scripts and CI run them) the bytes and the exit code are the
-  recorded ones. `home` opens the web console, which is the visual front end.
+- **Every command runs on Node.** There is no full-screen browse panel: `geneseed tui`
+  and `geneseed menu` are verbs that say the panel is not here and print the command list
+  instead. Bare `geneseed` — from the launchers and from an npm install alike — runs
+  `home`, which opens the web console when it can and otherwise prints the command list;
+  `geneseed --help` lists every command.
 - **Nothing you install needs an interpreter.** The `token-report` skill is a script
   rather than prose, and it ships as `scripts/token_report.mjs`, run with `node`;
   `daydream` and `herdr` hand their inline code to `node -e`.
@@ -79,7 +79,7 @@ tagline, loaded-sigil, and voice — so you hear the flavour before you choose;
 you pick, it speaks in that theme's accent through confirm and build, and the
 install ends on the theme's own **banner and benediction**.
 
-**Already installed?** Bare **`./geneseed`** (Windows: `.\geneseed.cmd`) opens the
+**Already installed?** Bare **`geneseed`** (a checkout: `./geneseed`, Windows: `.\geneseed.cmd`) opens the
 **web console**, which is where browsing, local edits, rebuilds, memory, status, MCP
 servers and uninstall all live — see [The web console](docs/web-ui.md). `GENESEED_NO_WEB=1`
 suppresses that and prints the command list instead. Uninstall from the CLI is
@@ -103,8 +103,8 @@ hand? Pick a path below.
 > `node bin/build-driver.mjs` with the same flags. Every commit re-emits with it across every
 > theme × host × footprint combination and checks the result with `doctor --all`, on Linux
 > and Windows both. Until 2026-08-17 that output was also compared byte for byte against
-> recordings taken from the Python implementation; those were retired, and `docs/limits.md`
-> says why and what it cost.
+> recordings taken from the Python implementation; those were retired (see the 2.0.0 entry
+> in [CHANGELOG.md](CHANGELOG.md)).
 
 ---
 
@@ -238,16 +238,13 @@ the preamble rides a file Copilot auto-loads: the repo-root `AGENTS.md` (CLI, co
 agent, and VS Code agent mode) or the personal `~/.copilot/copilot-instructions.md`
 (CLI). Two differences from the Claude paths:
 
-- **Hooks at global scope only, block-or-warn.** The global emit wires two hooks
-  into `~/.copilot/settings.json`: `sessionStart` (eager project-context injection,
-  as on Claude Code) and `toolCall` (both gates behind one command, because Copilot
-  takes one command per event). Copilot's `toolCall` has no "ask the user" tier, so
-  Laws I and IV **block** and the two consent rules (process 1, process 5) **warn**
-  on stderr instead of prompting. No `learn` hook — Copilot's `sessionEnd`/`agentStop`
-  payloads carry no transcript — so the memory convention rides the preamble's
-  instructions. The per-repo emit wires nothing: Copilot reads hooks from the
-  personal settings file only, and a machine-absolute command in a shared
-  `.github/` would fail on every teammate's machine.
+- **Hooks at global scope only.** The global emit adds entries to four events in
+  `~/.copilot/settings.json`: `sessionStart` (eager project-context injection),
+  `preToolUse` (both gates behind one command, since entries carry no matcher —
+  every rule **asks**, as on Claude Code), and `agentStop` + `preCompact` (`learn`,
+  from the payload's `transcriptPath`). The per-repo emit wires nothing: a
+  machine-absolute command in a shared `.github/` would fail on every teammate's
+  machine.
 - **The per-repo layer lives in the shared `.github/`** (Copilot's repo config
   surface). Safe by construction: the ownership manifest + claim-on-create never
   touch files Geneseed didn't write — your workflows and same-named agents/skills
@@ -406,19 +403,19 @@ the agent reads — which is why the wizard's blurb for it says so.
 **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:
 
-- **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
+- **lean** (default) — Sections 1–2 carry the heading and the authored short form 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.
+**Nothing at lean is truncated — it is written.** Every tier carries a hand-authored short form
+beside its full text: the Ontology (whose four flowing sections would have read as four orphan
+sentences if cut), each Rule, and each doctrine rule. What lean ships is decided by an author
+rather than by where a sentence happens to end — so a short form is judged on whether an agent
+can act on it, which is something a reviewer can see.
 
 **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
@@ -917,7 +914,8 @@ not connected, walk these in order:
 | `GENESEED_NO_ANIM` | install animation | disable the themed install animation |
 | `GENESEED_LOG` | `geneseed upgrade` | override the install/upgrade log path |
 | `GENESEED_NET_TIMEOUT` | `upgrade` | seconds before download attempts give up (default 20, floor 5) |
-| `GENESEED_NO_WEB` | launcher / menu | `1` disables the web-first default of bare `./geneseed` — falls back to the terminal menu |
+| `GENESEED_NO_WEB` | `home` | `1` disables the web-first default of bare `geneseed` — it prints the command list instead |
+| `GENESEED_STACK_GLOBAL` | context hook | `1` disables project-bypasses-global: a project install of the same host no longer makes the global install's hook stand down, so both inject |
 | `OPENCODE_CONFIG_DIR` / `XDG_CONFIG_HOME` | global emit | where the global install is written |
 | `OPENCODE_DISABLE_LSP_DOWNLOAD` | OpenCode (LSP) | `true` stops OpenCode auto-downloading built-in language servers (typescript, pyright, jdtls) — set it on air-gapped machines and pre-install each server yourself |
 
@@ -965,7 +963,7 @@ harness no matter where the shim itself lives — the same shape the Windows arm
 always used. Once it's on `PATH`, drop the `./`:
 
 ```
-geneseed            # the interactive main menu, from any directory
+geneseed            # the web console (else the command list), from any directory
 geneseed build      # …and every subcommand
 ```
 

package/SHIPPED.md

@@ -14,54 +14,48 @@ This page answers "what is actually in the harness, and where is its rationale?"
 The dated `docs/specs/*` files were the *design record* — the problem and the
 decisions behind each feature; this is the *index* over them, marking what has
 landed in the source tree. Specs are working documents: they live git-ignored on
-the authoring machine and are dropped once shipped, so the spec links below are
-historical pointers, not files distributed with the repo.
+the authoring machine and are dropped once shipped, so the spec names below are
+historical references, not files distributed with the repo.
 
 > **On version numbers.** [`harness.config.json`](harness.config.json)'s `version` is a
 > human-readable label only. The canonical identity of an installed harness is the
 > **source fingerprint** stamped in `.geneseed-version` (see `geneseed version`), not the
-> string. Current label: **3.4.0**.
-
-> **Spec status audit (2026-06-15).** Every dated spec authored before today was
-> verified against the source tree and confirmed implemented (code + tests + docs);
-> their `**Status:**` headers were flipped from `approved`/`implementing`/`Accepted`/`spec`
-> to `implemented`. The only open spec is the same-day
-> [shell-completion](docs/specs/2026-06-15-shell-completion.md) draft.
+> string. Current label: **3.5.0**.
 
 ## Capabilities
 
-Every row below is present in the tree today; "Spec" links the design record.
+Every row below is present in the tree today; "Spec" names the design record.
 
 | Capability | What it is | Spec |
 | --- | --- | --- |
 | **Themed generator** | One neutral `src/` → 14 themed bundles via `geneseed-build` (zero dependencies); structure stays theme-independent | [DESIGN.md](DESIGN.md) |
-| **Laws / Agents / Skills / Memory / Notebook** | 11 laws, 18 agents, 49 skills, the memory convention, and the agent's sovereign notebook | [notebook](docs/specs/2026-06-11-notebook-sovereign-space.md) · [agent-own-space](docs/specs/2026-06-10-notebook-agent-own-space.md) |
-| **Three-tier constitution** | The governance surface splits into an always-on **Ontology** (Telos, Evidence, Decisions, Conduct — the Pact absorbed into Telos), the eleven always-on **Invariants** (IX and XI retired in place — folded into rigor 5 and Law III, numbers kept), and four toggleable **Doctrine** packs (craft, rigor, ops, process) addressed `<pack> <n>`. Packs are chosen at build time with `--doctrines` or the setup wizard; the whole catalogue ships on disk either way, so a citation into an inactive pack still resolves. Precedence, in order: Ontology + Invariants, then the user's `user-rules.md`, then the active Doctrines, then `PROFILE.md`. `doctor`'s `constitutionProblems` gates pack numbering, the per-rule Principle column, every `{{DOCTRINE}}` citation in `src/`, and the rule that an always-on tier may never cite a toggleable one | [three-tier-constitution](docs/specs/2026-08-19-three-tier-constitution-design.md) |
-| **`doctor`** | One check: unresolved tokens, dead/non-hermetic links, theme-key parity, authoring gates, rendered-bundle drift | [theme-aware doctor/diff](docs/specs/2026-06-07-theme-aware-doctor-diff.md) |
-| **`diff` + improvements export** | Deployed-vs-source drift report; export an `improvements.md` back-port | [improvements-export](docs/specs/2026-06-12-improvements-export.md) |
-| **`status` / `version`** | Headless dashboard + fingerprint verdict (no TUI needed) | [status-command](docs/specs/2026-06-07-status-command.md) · [version-and-uninstall](docs/specs/2026-06-07-version-and-uninstall.md) |
-| **Terminal rendering** | There is no full-screen control panel: `tui` and `menu` are verbs that say so and print the command list. The display-width and glyph layer ships on, behind `status` and the install animation | [refactor-polish](docs/specs/2026-06-07-tui-refactor-polish.md) · [modern-refresh](docs/specs/2026-06-08-tui-modern-refresh.md) · [windows-tui](docs/specs/2026-06-11-windows-tui.md) |
-| **Web console** | Local browser UI (Dashboard, Library, Graph, Docs, Specs, Changes, Doctor, Themes, Settings), auto-build, in-app docs menu | [web-ui-v2](docs/specs/2026-06-12-web-ui-v2.md) · [web-auto-build](docs/specs/2026-06-12-web-auto-build.md) · [docs-menu](docs/specs/2026-06-13-docs-menu.md) |
-| **OpenCode adapter** | Native agents/skills mapping + plugins (context, learn, guard, workflow, notify, ponytail, activity); global-emit link integrity; JSONC config target | [adapter-features](docs/specs/2026-06-07-opencode-adapter-features.md) · [global-emit](docs/specs/2026-06-07-global-emit-link-integrity.md) · [jsonc-target](docs/specs/2026-06-12-opencode-jsonc-target.md) · [ponytail](docs/specs/2026-06-16-ponytail-minimal-code-mode.md) |
-| **Host hooks, per dialect** | Every host gets the hook surface its runtime offers, spoken in that runtime's own verdict dialect via `--host`: Claude Code asks (`permissionDecision`), Copilot blocks (`{"block":true}`, `sessionStart` + `toolCall` in `~/.copilot/settings.json`), Bob refuses by exit code 2 (five Claude-named events, nested `~/.bob/settings/settings.json`, no subagent event), OpenCode's guard throws. Laws I/IV are the hard tier everywhere; the consent rules ask where a host can ask and warn where it cannot. `tool-gate` fuses the two gates for hosts that run one command per event; `PreCompact` runs `learn` before Claude compacts; every block or ask lands in `notebook/gates.jsonl` on every host | [copilot](adapters/copilot/README.md) · [bob](adapters/bob/README.md) · [claude-code](adapters/claude-code/README.md) · [candidate hosts](docs/candidate-hosts.md) |
-| **Workflow primitive** | Saved, code-driven subagent orchestration (`workflow` tool + runtime); shipped scripts include `dispatch` — decompose a goal, route each subtask to its owning agent, converge | [workflow-primitive](docs/specs/2026-06-09-opencode-workflow-primitive.md) |
-| **Per-agent memory** | Each capability agent keeps durable lessons in `memory/agents/<name>.md`: read at dispatch, written back mechanically by `learn` on session/subagent end (OpenCode plugin + Claude `SubagentStop`; Bob has no subagent event); `learn --consolidate` rebuilds the index | [orchestration-memory-upgrade](docs/specs/2026-07-04-orchestration-memory-upgrade.md) |
-| **Wiki integration** | Machine-wide knowledge base (`wiki.jsonc`): eager/lazy loading, conventions, protected folders enforced at the tool boundary | [wiki-knowledge-base](docs/specs/2026-06-11-wiki-knowledge-base.md) |
-| **Collaboration layer** | Negotiated postures (peer/mentor/expert/assistant/artisan, chosen at setup, inlined in AGENT.md), the bidirectional Pact, epistemically-typed memory (`force:` + Bridge rule), and a seed-once `PROFILE.md` identity with a web editor tab and a `profile` skill that interviews the user to draft it | [collaboration-layer](docs/specs/2026-07-12-collaboration-layer.md) |
-| **Rule front door** | Both durable stores enter through the `rule` skill's fork (*standing rule, or fact to remember?* — always asked, never inferred): the memory branch elicits the binding `force` and shows the file before writing, the rule branch pressure-tests by reformulation and a mandatory counter-example. Doctrine process 1 carries the norm on every host; a `rule-gate` PreToolUse hook (Claude, Bob) and a `geneseed-guard` speed bump (OpenCode) hold it at the tool boundary | [rule-front-door](docs/specs/2026-07-30-rule-front-door.md) |
-| **Entity registry** | `registry.json` records a lifecycle status, version, owner and add-date for every agent and skill in the tree (maintainer-side — never rendered into a bundle, so it costs no session context). `doctor` gates it against `src/` in both directions, sweeps everything that ships for credentials, and holds each vendored skill folder to an immutable upstream commit. The status surfaces as a badge in the web catalog, shown only where it deviates from `approved` | [entity-registry](docs/specs/2026-07-31-entity-registry.md) |
-| **Node runtime + npm package** | The whole harness runs from Node: every command `js/cli-table.json` declares, all five hook verbs, every web-console endpoint (the OS-native folder picker excepted, and declined on purpose) and both generators. Every commit runs the unit suite, `doctor --all` across every theme × host × footprint, and the generator's two self-comparisons, on Linux and Windows both; the frozen emit/cli/web recordings that also gated it retired on 2026-08-17 (`docs/limits.md`). It ships as the zero-dependency `geneseed` package (`geneseed`, `geneseed-hook`, `geneseed-build`), so `npx geneseed setup` needs no clone and nothing else installed; `geneseed migrate` moves an existing checkout install across. Node is the only runtime it asks for: the `token-report` skill's own script is `token_report.mjs`, gated over seeded transcripts for all four hosts, and `daydream` and `herdr` call `node -e` | [npx-distribution](docs/specs/2026-08-06-npx-distribution.md) |
-| **Runtime awareness** | MCP discovery, web research, tool-call batching, review discipline — carried by the doctrine packs (`ops 1` tool discovery, `process 4` read the docs first, `rigor 2`/`rigor 3` honest tests and cover-and-verify), not by the invariants | [runtime-awareness](docs/specs/2026-06-07-runtime-awareness-and-review-discipline.md) |
-| **Run from anywhere / uninstall** | `link`/`unlink` onto PATH; global uninstall that keeps the memory store | [version-and-uninstall](docs/specs/2026-06-07-version-and-uninstall.md) |
+| **Laws / Agents / Skills / Memory / Notebook** | 11 laws, 18 agents, 52 skills, the memory convention, and the agent's sovereign notebook | `2026-06-11-notebook-sovereign-space` · `2026-06-10-notebook-agent-own-space` |
+| **Three-tier constitution** | The governance surface splits into an always-on **Ontology** (Telos, Evidence, Decisions, Conduct — the Pact absorbed into Telos), the eleven always-on **Invariants** (IX and XI retired in place — folded into rigor 5 and Law III, numbers kept), and four toggleable **Doctrine** packs (craft, rigor, ops, process) addressed `<pack> <n>`. Packs are chosen at build time with `--doctrines` or the setup wizard; the whole catalogue ships on disk either way, so a citation into an inactive pack still resolves. Precedence, in order: Ontology + Invariants, then the user's `user-rules.md`, then the active Doctrines, then `PROFILE.md`. `doctor`'s `constitutionProblems` gates pack numbering, the per-rule Principle column, every `{{DOCTRINE}}` citation in `src/`, and the rule that an always-on tier may never cite a toggleable one | `2026-08-19-three-tier-constitution-design` |
+| **`doctor`** | One check: unresolved tokens, dead/non-hermetic links, theme-key parity, authoring gates, rendered-bundle drift | `2026-06-07-theme-aware-doctor-diff` |
+| **`diff` + improvements export** | Deployed-vs-source drift report; export an `improvements.md` back-port | `2026-06-12-improvements-export` |
+| **`status` / `version`** | Headless dashboard + fingerprint verdict (no TUI needed) | `2026-06-07-status-command` · `2026-06-07-version-and-uninstall` |
+| **Terminal rendering** | There is no full-screen control panel: `tui` and `menu` are verbs that say so and print the command list. The display-width and glyph layer ships on, behind `status` and the install animation | `2026-06-07-tui-refactor-polish` · `2026-06-08-tui-modern-refresh` · `2026-06-11-windows-tui` |
+| **Web console** | Local browser UI (Dashboard; Codex: Constitution, Rules, Profile, Skills, Agents, Library, Docs; Care: Activity, Changes, Doctor; Setup: Harness, Settings), auto-build, in-app docs menu | `2026-06-12-web-ui-v2` · `2026-06-12-web-auto-build` · `2026-06-13-docs-menu` |
+| **OpenCode adapter** | Native agents/skills mapping + plugins (context, learn, guard, workflow, notify, ponytail, activity); global-emit link integrity; JSONC config target | `2026-06-07-opencode-adapter-features` · `2026-06-07-global-emit-link-integrity` · `2026-06-12-opencode-jsonc-target` · `2026-06-16-ponytail-minimal-code-mode` |
+| **Host hooks, per dialect** | Every host gets the hook surface its runtime offers, spoken in that runtime's own verdict dialect via `--host`: Claude Code asks (`permissionDecision`), Copilot asks as Claude does (`sessionStart`, `preToolUse`, `agentStop`, `preCompact` in `~/.copilot/settings.json`, global scope only), Bob refuses by exit code 2 (five Claude-named events, nested `~/.bob/settings/settings.json`, no subagent event), OpenCode's guard throws. Laws I/IV are the hard tier everywhere; the consent rules ask where a host can ask and warn where it cannot. `tool-gate` fuses the two gates for hosts that run one command per event; `PreCompact` runs `learn` before Claude compacts; every block or ask lands in `notebook/gates.jsonl` on every host | [copilot](adapters/copilot/README.md) · [bob](adapters/bob/README.md) · [claude-code](adapters/claude-code/README.md) · [candidate hosts](docs/candidate-hosts.md) |
+| **Workflow primitive** | Saved, code-driven subagent orchestration (`workflow` tool + runtime); shipped scripts include `dispatch` — decompose a goal, route each subtask to its owning agent, converge | `2026-06-09-opencode-workflow-primitive` |
+| **Per-agent memory** | Each capability agent keeps durable lessons in `memory/agents/<name>.md`: read at dispatch, written back mechanically by `learn` on session/subagent end (OpenCode plugin + Claude `SubagentStop`; Bob has no subagent event); `learn --consolidate` rebuilds the index | `2026-07-04-orchestration-memory-upgrade` |
+| **Wiki integration** | Machine-wide knowledge base (`wiki.jsonc`): eager/lazy loading, conventions, protected folders enforced at the tool boundary | `2026-06-11-wiki-knowledge-base` |
+| **Collaboration layer** | Negotiated postures (peer/mentor/expert/assistant/artisan, chosen at setup, inlined in AGENT.md), the bidirectional Pact, epistemically-typed memory (`force:` + Bridge rule), and a seed-once `PROFILE.md` identity with a web editor tab and a `profile` skill that interviews the user to draft it | `2026-07-12-collaboration-layer` |
+| **Rule front door** | Both durable stores enter through the `rule` skill's fork (*standing rule, or fact to remember?* — always asked, never inferred): the memory branch elicits the binding `force` and shows the file before writing, the rule branch pressure-tests by reformulation and a mandatory counter-example. Doctrine process 1 carries the norm on every host; a `rule-gate` PreToolUse hook (Claude, Bob) and a `geneseed-guard` speed bump (OpenCode) hold it at the tool boundary | `2026-07-30-rule-front-door` |
+| **Entity registry** | `registry.json` records a lifecycle status, version, owner and add-date for every agent and skill in the tree (maintainer-side — never rendered into a bundle, so it costs no session context). `doctor` gates it against `src/` in both directions, sweeps everything that ships for credentials, and holds each vendored skill folder to an immutable upstream commit. The status surfaces as a badge in the web catalog, shown only where it deviates from `approved` | `2026-07-31-entity-registry` |
+| **Node runtime + npm package** | The whole harness runs from Node: every command `js/cli-table.json` declares, all five hook verbs, every web-console endpoint (the OS-native folder picker excepted, and declined on purpose) and both generators. Every commit runs the unit suite, `doctor --all` across every theme × host × footprint, and the generator's two self-comparisons, on Linux and Windows both; the frozen emit/cli/web recordings that also gated it retired on 2026-08-17 (see the 2.0.0 entry in [CHANGELOG.md](CHANGELOG.md)). It ships as the zero-dependency `geneseed` package (`geneseed`, `geneseed-hook`, `geneseed-build`), so `npx geneseed setup` needs no clone and nothing else installed; `geneseed migrate` moves an existing checkout install across. Node is the only runtime it asks for: the `token-report` skill's own script is `token_report.mjs`, gated over seeded transcripts for all four hosts, and `daydream` and `herdr` call `node -e` | `2026-08-06-npx-distribution` |
+| **Runtime awareness** | MCP discovery, web research, tool-call batching, review discipline — carried by the doctrine packs (`ops 1` tool discovery, `process 4` read the docs first, `rigor 2`/`rigor 3` honest tests and cover-and-verify), not by the invariants | `2026-06-07-runtime-awareness-and-review-discipline` |
+| **Run from anywhere / uninstall** | `link`/`unlink` onto PATH; global uninstall that keeps the memory store | `2026-06-07-version-and-uninstall` |
 
 ## Workplans (not features)
 
-A few `docs/specs/` entries are multi-agent *workplans / audits*, not single features —
+A few specs were multi-agent *workplans / audits*, not single features —
 they record direction, and their individual items landed across the capabilities above:
 
-- [2026-06-08-harness-perfection-workplan](docs/specs/2026-06-08-harness-perfection-workplan.md)
-- [2026-06-08-opencode-feature-coverage](docs/specs/2026-06-08-opencode-feature-coverage.md)
-- [2026-06-08-tui-professional-workplan](docs/specs/2026-06-08-tui-professional-workplan.md)
+- `2026-06-08-harness-perfection-workplan`
+- `2026-06-08-opencode-feature-coverage`
+- `2026-06-08-tui-professional-workplan`
 
 ## Exploratory archive
 

package/adapters/bob/README.md

@@ -4,7 +4,7 @@
 
 [IBM Bob](https://bob.ibm.com) is **Claude-Code-shaped**: a project `.bob/`
 layer, an `AGENTS.md` instructions file, `SKILL.md` skills, subagents, and a
-`settings.json` that also carries `mcpServers`. So the Bob emit **reuses the
+`settings.json` for hooks. So the Bob emit **reuses the
 Claude engine** verbatim — only the marker dir (`.bob`) and the instructions
 filename (`AGENTS.md`) change. There is nothing to install by hand: `geneseed
 setup` (or `geneseed build --emit bob` / `--emit bob-global`) writes everything.
@@ -25,7 +25,9 @@ limitation to be aware of on a shared repo.
   - `skills/<name>/SKILL.md` — **byte-identical** to every other host; skills
     are model-invoked via the `skill` tool.
   - `rules/geneseed.md` — a **slim shadow stub** (see *Bob-ism 1* below).
-  - `settings.json` — Geneseed's lifecycle hooks + any `mcpServers` you wire.
+  - `settings.json` — Geneseed's lifecycle hooks (gitignored by the emit's
+    `.bob/.gitignore`, see the caveat below).
+  - `mcp.json` — any MCP servers you wire with `geneseed mcp` / the web console.
   - `memory/`, `notebook/` stores + their indices.
 
 ### Global (`--emit bob-global` → `~/.bob`, or `$BOB_CONFIG_DIR`)
@@ -94,7 +96,7 @@ Bob's hooks: the one group only ever exits 2 for Laws I and IV, which every buil
 
 **Migration.** A re-emit over an older install unwires Geneseed's groups from the flat
 `~/.bob/settings.json` (your own keys there are kept) and writes the new set to the
-nested file. `geneseed mcp` targets the nested file too.
+nested file.
 
 **Unverified live.** There is no Bob install on the authoring machine; this is Bob's
 documented contract, with the payload field names assumed to be Claude's. If a field
@@ -111,15 +113,16 @@ out of shared git). Those hook commands name the **per-user hook shim**
 (`~/.geneseed/bin/geneseed-hook`) — no longer this machine's interpreter and
 checkout, but still a path under *your* home, and now also OS-specific (`.cmd` on
 Windows, extensionless elsewhere). If you commit `.bob/settings.json`, a teammate
-still inherits hooks pointing at a path they do not have. **Add
-`.bob/settings.json` to `.gitignore`** on a team repo, or keep the Bob install
-personal/global.
+still inherits hooks pointing at a path they do not have. A fresh emit writes
+`.bob/.gitignore` listing `settings.json`; if you already had a `.bob/.gitignore`,
+add the line yourself.
 
 ## MCP
 
-MCP servers are wired at runtime by `geneseed mcp` into the `mcpServers` key of
-the relevant `settings.json` (`.bob/settings.json` per-repo, `~/.bob/settings.json`
-global) — see [`geneseed mcp`](../../README.md) and `rituals/_harness_mcp.py`.
+MCP servers are wired at runtime (web console, listed by `geneseed mcp`) into the
+`mcpServers` key of Bob's own MCP file — `.bob/mcp.json` per-repo,
+`~/.bob/settings/mcp.json` global — never `settings.json`, which Bob does not read
+servers from ([Bob docs](https://bob.ibm.com/docs/ide/configuration/mcp/mcp-in-bob)).
 
 ## What Bob does not get
 

package/adapters/copilot/README.md

@@ -9,8 +9,9 @@ Agent Skills), custom agents are markdown-with-frontmatter, and the repo-root
 a `host="copilot"` flag. Nothing to install by hand: `geneseed setup` (or
 `geneseed build --emit copilot` / `--emit copilot-global`) writes everything.
 
-Copilot is a **reduced host**: it has lifecycle hooks, but one command per event and
-no "ask the user" tier, so this page is mostly about what those hooks *can* and
+Copilot is a **reduced host** at project scope (no hooks there) and close to Claude
+Code at global scope: its lifecycle hooks have an "ask the user" tier, so the gates
+prompt as they do on Claude. This page is mostly about what those hooks *can* and
 *cannot* automate and why the harness still holds where they cannot.
 
 ## What the emit writes
@@ -39,42 +40,42 @@ no "ask the user" tier, so this page is mostly about what those hooks *can* and
   the preamble rides it as a managed block. (Unlike Bob, Copilot *has* a real
   personal instructions carrier, so no rules-folder workaround is needed.)
 - `agents/<name>.agent.md` + `skills/` under `~/.copilot`.
-- **`settings.json` hooks** — two entries under `hooks`, see below.
+- **`settings.json` hooks** — four entries under `hooks`, see below.
 
-## Hooks — one command per event, block or warn
+## Hooks — ask, as on Claude Code
 
 The Copilot CLI reads lifecycle hooks from **`~/.copilot/settings.json`** as a map of
-event → one `{command}` object (no matcher groups, no list). The global emit wires
-two of them, each calling the machine-wide `geneseed-hook` shim with `--host copilot`
-so the verdict is spoken in Copilot's dialect:
+event → **array** of `{type: "command", command}` entries
+([reference](https://docs.github.com/en/copilot/reference/hooks-configuration)). The
+global emit adds one entry to each of four events, each calling the machine-wide
+`geneseed-hook` shim:
 
 | event | verb | what it does |
 | --- | --- | --- |
 | `sessionStart` | `context` | eager project-context injection, as on Claude Code, returned as `{"additionalContext": …}` |
-| `toolCall` | `tool-gate` | the git gate and the rule gate **fused** — one command is all the event allows — dispatched on the payload: a `command` gets the git checks, a path gets the rule checks; the `after` phase is ignored |
+| `preToolUse` | `tool-gate --host copilot` | the git gate and the rule gate **fused** — entries carry no matcher — dispatched on the payload: a `command` gets the git checks, a path gets the rule checks |
+| `agentStop` | `learn` | distils the session transcript (`transcriptPath`) into memory, as Claude's `Stop` |
+| `preCompact` | `learn` | the same, once more before compaction summarises the window away |
 
-Copilot's `toolCall` has **no "ask the user" tier** — its stdout contract is
-`{"block": true|false}` — so the verdict tiers are:
+`preToolUse` has an ask tier, so every rule **asks** exactly where it asks on Claude
+Code — Laws I and IV, process 1 and process 5 — answered top-level as
+`{"permissionDecision": "ask", "permissionDecisionReason": …}`. A gate error asks
+too (fail closed). `toolArgs` is read whether Copilot sends it as an object or as a
+JSON string.
 
-- **Laws I and IV block.** A credential-shaped string headed for a tracked file, or
-  a history-discarding git act (`reset --hard`, `clean -f`, `branch -D`,
-  `checkout --`, `push --force`), is refused outright with the reason. Same stance
-  as the OpenCode guard plugin, whose `tool.execute.before` can only allow or throw.
-- **Process 1 and process 5 warn.** The two consent rules are the *user's* calls; a
-  hard block would make Copilot unable to commit at all. They log a `[geneseed] …`
-  line on stderr (which Copilot records) and allow. A gate error warns the same way
-  rather than locking every tool call behind a block nobody can clear.
+**Your own hooks on those events stay**: Geneseed's entry goes beside them in the
+array, and uninstall removes exactly the entries it claimed. Comments in the file
+mean it is never rewritten.
 
-**A hook you already set on one of those events is left alone**, and that event is
-not claimed — one slot per event means Geneseed could only displace it. Uninstall
-removes exactly the hooks it claimed. Comments in the file mean it is never
-rewritten.
+**Migration.** Before this, the emit wired a single-object `toolCall` hook — an event
+Copilot no longer fires, so the gates never ran. A re-emit removes those recorded
+entries (your own keys stay) and writes the array shape.
+
+**Unverified live.** No Copilot CLI on the authoring machine; this is the documented
+contract.
 
 **What is not wired, and why:**
 
-- **no `learn`** — Copilot's `sessionEnd` and `agentStop` payloads carry no
-  `transcript_path`, so a distiller would have nothing to read. The memory
-  convention rides the preamble's instructions (the agent writes its own memories);
 - **no hooks at project scope** — the CLI documents hooks in the personal settings
   file only, and a machine-absolute command committed into a shared `.github/`
   would fail on every teammate's machine;

package/adapters/opencode/GLOBAL-HARNESS-SPEC.md

@@ -185,7 +185,7 @@ repo's layout defeats the convention.
 
 ### 3.5 Injection block format (mirror `harness.py cmd_context`)
 
-Byte-identical structure to [harness.py:237-263](../../rituals/harness.py) so both
+Byte-identical structure to the retired Python `harness.py` (lines 237-263) so both
 enforcement paths read the same. Adds a machine marker (first line) for §4.
 
 ```

package/adapters/opencode/README.md

@@ -380,8 +380,8 @@ behaviour** — nothing changes the machine's current agent/model unless you opt
   `tokyonight`, `rosepine`, `gruvbox`, `nord`, `everforest`, `kanagawa`, `dracula` — each
   in a **solid** (opaque) and a **transparent** (terminal-background-through) flavour.
   These are decoupled from the voice theme: any voice theme can run any colour theme.
-  Authored under `themes/opencode/` (see its README and
-  [the spec](../../docs/specs/2026-06-17-opencode-color-themes.md)).
+  Authored under `themes/opencode/` (see its README; the design record was the
+  `2026-06-17-opencode-color-themes` spec).
 - **Runtime guard plugin** (`geneseed-guard.js`, installed with the others). Enforces
   the safety Laws at the tool boundary: **blocks** writes to private-key/credential
   files (Law I), catastrophic shell like `rm -rf /` (Law IV), and any mutation under

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

@@ -138,10 +138,12 @@ let fallbackVisible = false
 function log(msg) { if (DEBUG) console.error(`[geneseed-context] ${msg}`) }
 
 // ---- convention --------------------------------------------------------------
-// Root-level files injected in full. Agent-directed rules + canonical entry docs.
+// Root-level files injected in full. Canonical entry docs + agent-directed rules OpenCode
+// does not read by itself. AGENT.md (opencode.json `instructions`), AGENTS.md and CLAUDE.md
+// (OpenCode's own native roots) are deliberately absent: OpenCode already has them, and
+// injecting them again re-sent the whole harness on every request until 2026-09.
 const EAGER_ROOT = new Set([
-  "AGENTS.md", "AGENT.md", "CLAUDE.md", ".cursorrules",
-  "README.md", "CONTRIBUTING.md", "user-rules.md", "PROFILE.md",
+  ".cursorrules", "README.md", "CONTRIBUTING.md", "user-rules.md", "PROFILE.md",
 ])
 // Doc trees walked recursively; everything found is lazy (listed, not injected).
 const LAZY_DIRS = ["docs", "doc", "documentation", "architecture", "adr", "ADR"]

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

@@ -17,6 +17,7 @@
 // Quiet by default; GENESEED_DEBUG=1 logs to stderr. GENESEED_WORKFLOWS_DIR overrides
 // where saved workflows are loaded from.
 
+import { execFile } from "node:child_process"
 import { promises as fs } from "node:fs"
 import * as path from "node:path"
 import { fileURLToPath, pathToFileURL } from "node:url"
@@ -63,6 +64,17 @@ function nowStamp() {
   return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`
 }
 
+// The runtime's git executor, for `isolation: "worktree"`. argv only, never a shell string:
+// branch and directory names derive from agent labels a script author wrote.
+function git(argv, cwd) {
+  return new Promise((resolve, reject) => {
+    execFile("git", argv, { cwd, windowsHide: true, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) reject(new Error(`git ${argv[0]}: ${String(stderr || err.message).trim()}`))
+      else resolve(String(stdout))
+    })
+  })
+}
+
 function safeJson(v) {
   try { return JSON.stringify(v, null, 2) } catch { return String(v) }
 }
@@ -73,7 +85,22 @@ function summarize(name, result, stats, tracePath) {
     (stats.phases.length ? `, phases: ${stats.phases.join(" → ")}` : "")
   let body = safeJson(result)
   if (body.length > 2000) body = body.slice(0, 2000) + `\n… (truncated — full result in ${tracePath})`
-  return `${head}\n\nResult:\n${body}\n\nTrace: ${tracePath}`
+  return `${head}\n\nResult:\n${body}${isolationReport(stats)}\n\nTrace: ${tracePath}`
+}
+
+// Kept worktrees are work awaiting review, and an overlap is a conflict awaiting ONE
+// merger (process 8) — both are said out loud, never left for the trace to hold.
+function isolationReport(stats) {
+  const kept = stats.worktrees || []
+  if (!kept.length) return ""
+  const lines = ["", "", `Worktrees kept (${kept.length}) — review and merge them yourself; nothing was merged:`]
+  for (const w of kept) lines.push(`- ${w.label}: ${w.branch} at ${w.dir} — ${w.files.length} file(s)`)
+  const over = stats.overlaps || []
+  if (over.length) {
+    lines.push(`CONFLICTS — ${over.length} file(s) changed by more than one agent; merge these by hand or through one merge agent:`)
+    for (const o of over) lines.push(`- ${o.file}: ${o.labels.join(", ")}`)
+  }
+  return lines.join("\n")
 }
 
 async function writeTrace(rootDir, runId, lines) {
@@ -142,7 +169,7 @@ export const GeneseedWorkflow = async (ctx) => {
     try { ({ createRuntime } = await import(pathToFileURL(path.join(WORKFLOWS_DIR, "_runtime.js")).href + "?t=" + Date.now())) }
     catch (e) { return `Workflow runtime unavailable: ${e?.message || e}` }
 
-    const rt = createRuntime({ client, directory, worktree, args: normalizeArgs(argv?.args), log: sink })
+    const rt = createRuntime({ client, directory, worktree, git, runId, args: normalizeArgs(argv?.args), log: sink })
     let result, failed = null
     try { result = await wf.run(rt) }
     catch (e) { failed = e; sink(`✗ workflow error: ${e?.stack || e?.message || e}`) }
@@ -152,7 +179,7 @@ export const GeneseedWorkflow = async (ctx) => {
     if (!failed) sink(`# result:\n${safeJson(result)}`)
     const tracePath = await writeTrace(rootDir, runId, lines)
 
-    if (failed) return `Workflow "${name}" failed: ${failed?.message || failed}\nTrace: ${tracePath}`
+    if (failed) return `Workflow "${name}" failed: ${failed?.message || failed}${isolationReport(stats)}\nTrace: ${tracePath}`
     return summarize(name, result, stats, tracePath)
   }
 

package/adapters/opencode/workflows/_runtime.js

@@ -17,6 +17,7 @@
 // hard sandbox guard. See docs/specs/2026-06-09-opencode-workflow-primitive.md.
 
 import * as os from "node:os"
+import * as path from "node:path"
 
 const DEBUG = !!process.env.GENESEED_DEBUG
 function dlog(m) { if (DEBUG) console.error(`[geneseed-workflow] ${m}`) }
@@ -150,13 +151,17 @@ function usageFrom(res) {
   return { input: Number(tok?.input ?? 0) || 0, output: Number(tok?.output ?? 0) || 0 }
 }
 
-async function runChildSession(client, { prompt, agent, model, title }) {
+async function runChildSession(client, { prompt, agent, model, title, directory }) {
   if (!client?.session?.create || !client?.session?.prompt) {
     throw new Error("OpenCode SDK session API unavailable")
   }
   let created
-  try { created = await client.session.create({ body: { title: title || "geneseed-workflow" } }) }
-  catch { created = await client.session.create() }
+  // `query.directory` routes the request to that directory's instance, and the session keeps
+  // it — so an isolated child runs in its worktree. Never retried without it: a child that
+  // asked for a worktree and silently ran in the shared tree is the failure isolation exists for.
+  const q = directory ? { query: { directory } } : {}
+  try { created = await client.session.create({ body: { title: title || "geneseed-workflow" }, ...q }) }
+  catch (e) { if (directory) throw e; created = await client.session.create() }
   const sid = sessionId(created)
   if (!sid) throw new Error("could not create child session")
   try {
@@ -164,7 +169,7 @@ async function runChildSession(client, { prompt, agent, model, title }) {
     if (agent) body.agent = agent
     if (model) body.model = model
     let res = null
-    try { res = await client.session.prompt({ path: { id: sid }, body }) }
+    try { res = await client.session.prompt({ path: { id: sid }, body, ...q }) }
     catch (e) { dlog(`prompt failed: ${e?.message || e}`) }
     const r = unwrap(res)
     let text = partsText(r?.parts ?? r?.info?.parts ?? [])
@@ -175,9 +180,52 @@ async function runChildSession(client, { prompt, agent, model, title }) {
   }
 }
 
+// ---- 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 8, 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
+// plugin so this file stays pure and testable. The worktree has no untracked files from
+// the root (no node_modules, no .env): an agent that must run the project installs first.
+const slug = (t) => String(t).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 32) || "agent"
+
+export async function isolate(git, root, name) {
+  if (typeof git !== "function") throw new Error("worktree isolation unavailable — no git executor")
+  if (!root) throw new Error("worktree isolation unavailable — unknown working dir")
+  const base = (await git(["rev-parse", "HEAD"], root)).trim()
+  const branch = `geneseed-wf/${name}`
+  const dir = path.join(os.tmpdir(), "geneseed-wf", name)
+  await git(["worktree", "add", "-b", branch, dir, base], root)
+  return { dir, branch, base }
+}
+
+export async function changedFiles(git, w) {
+  const lines = (out) => String(out).split("\n").map((l) => l.trim()).filter(Boolean)
+  const tracked = lines(await git(["diff", "--name-only", w.base], w.dir))
+  const untracked = lines(await git(["ls-files", "--others", "--exclude-standard"], w.dir))
+  return [...new Set([...tracked, ...untracked])].sort()
+}
+
+// Files more than one isolated agent changed — the conflicts a merge would otherwise
+// settle by whoever landed last. [{ file, labels }], sorted by file.
+export function overlaps(worktrees) {
+  const by = new Map()
+  for (const w of worktrees || []) for (const f of w.files || []) {
+    if (!by.has(f)) by.set(f, [])
+    by.get(f).push(w.label)
+  }
+  return [...by].filter(([, l]) => l.length > 1).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([file, labels]) => ({ file, labels }))
+}
+
 // ---- the runtime ------------------------------------------------------------
 export function createRuntime(ctx) {
-  const { client, directory, worktree, log: sink } = ctx
+  const { client, directory, worktree, log: sink, git } = ctx
+  const root = worktree || directory
+  const runTag = slug(ctx.runId || "run")
+  const worktrees = []
   const args = ctx.args || {}
   const cap = ctx.concurrency || concurrencyCap()
   const limit = createLimiter(cap)
@@ -202,9 +250,32 @@ export function createRuntime(ctx) {
   async function spawn(prompt, opts) {
     return limit(() => runChildSession(client, {
       prompt, agent: opts.agent, model: opts.model, title: `geneseed-wf:${opts.label}`,
+      directory: opts.directory,
     }))
   }
 
+  // Git calls are serialised: concurrent `worktree add -b` calls contend for the same ref
+  // and worktree locks, and a lost lock fails an agent that did nothing wrong.
+  const gitQ = createLimiter(1)
+  const g = typeof git === "function" ? (argv, cwd) => gitQ(() => git(argv, cwd)) : undefined
+
+  // An isolated agent that changed nothing has its worktree and branch released; one that
+  // changed files is KEPT and recorded. A failed release is logged, never thrown.
+  async function settle(w, label) {
+    let files
+    try { files = await changedFiles(g, w) }
+    catch (e) { emit(`  ⚠ ${label}: could not list changes — worktree kept at ${w.dir}: ${e?.message || e}`); return }
+    if (files.length) {
+      worktrees.push({ label, dir: w.dir, branch: w.branch, base: w.base, files })
+      emit(`  ⎇ ${label}: ${files.length} file(s) changed — kept at ${w.dir} (branch ${w.branch})`)
+      return
+    }
+    try {
+      await g(["worktree", "remove", w.dir], root)
+      await g(["branch", "-D", w.branch], root)
+    } catch (e) { emit(`  ⚠ ${label}: could not release unchanged worktree — ${e?.message || e}`) }
+  }
+
   async function agent(prompt, opts = {}) {
     if (agentCount >= MAX_AGENTS) throw new Error(`workflow agent cap (${MAX_AGENTS}) exceeded`)
     if (budgetTotal != null && spent >= budgetTotal) {
@@ -213,8 +284,21 @@ export function createRuntime(ctx) {
     agentCount++
     const label = opts.label || String(prompt).slice(0, 40)
     emit(`· agent: ${label}`)
+    if (opts.isolation !== "worktree") return runAgent(prompt, { ...opts, label })
+    // The worktree wraps EVERY attempt, schema retries included — a retry that ran in the
+    // shared tree would undo the isolation it was asked for.
+    let w
+    try { w = await isolate(g, root, `${runTag}-${agentCount}-${slug(label)}`) }
+    catch (e) { emit(`✗ agent failed: ${label} — ${e?.message || e}`); return null }
+    emit(`  ⎇ ${label}: worktree ${w.dir}`)
+    try { return await runAgent(prompt, { ...opts, label, directory: w.dir }) }
+    finally { await settle(w, label) }
+  }
+
+  async function runAgent(prompt, opts) {
+    const { label } = opts
     let out
-    try { out = await spawn(prompt, { ...opts, label }) }
+    try { out = await spawn(prompt, opts) }
     catch (e) { emit(`✗ agent failed: ${label} — ${e?.message || e}`); return null }
     spent += out.usage?.output || 0
     if (!opts.schema) return out.text
@@ -270,7 +354,13 @@ export function createRuntime(ctx) {
 
   return {
     agent, parallel, pipeline, phase, log, budget, args, directory, worktree,
-    _stats: () => ({ agentCount, spent, cap, phases: [...phases], trace: [...trace] }),
+    // Isolated agents that changed something, and the files two or more of them touched.
+    worktrees: () => worktrees.map((w) => ({ ...w, files: [...w.files] })),
+    overlaps: () => overlaps(worktrees),
+    _stats: () => ({
+      agentCount, spent, cap, phases: [...phases], trace: [...trace],
+      worktrees: worktrees.map((w) => ({ ...w, files: [...w.files] })), overlaps: overlaps(worktrees),
+    }),
   }
 }