geneseed 3.11.0 → 3.13.0

package/docs/concepts/footprint.md

@@ -1,8 +1,10 @@
 ---
 group: concepts
-order: 8
+order: 10
 title: "Footprint (lean vs full)"
 kind: "concept"
+section: "Configuration"
+description: "Lean or full: how much of the constitution rides inline every turn."
 link: {"hash": "#/settings", "label": "Toggle it in Settings →"}
 ---
 **Footprint** decides how much of the [constitution](rules.md) the agent carries *inline* in its instructions file on every turn. It has two settings, **lean** (the default) and **full**, chosen per install. It is a token-cost dial, not a rules dial: every rule the install adopted is in force at either setting.

package/docs/concepts/foreman-mode.md

@@ -1,15 +1,17 @@
 ---
 group: concepts
-order: 10
+order: 15
 title: "Foreman mode"
 kind: "concept"
+section: "Working together"
+description: "Direct or foreman: whether the session does the work or hands it to a crew."
 link: {"hash": "#/harness", "label": "Set the mode in Harness →"}
 ---
 **Mode** decides how work gets executed in a session. Two modes ship: **direct**, the default, where the agent does every task itself, and **foreman**, where the session hands substantial tasks to a crew of [agents](agents.md) and keeps talking to you while they work.
 
 > **You already know this:** a tech lead with a team. Quick questions get answered on the spot; a real feature becomes a ticket that someone builds on a branch, and the lead reviews the result before it is merged.
 
-Mode is chosen at build time, so it does not drift mid-session, and kept across every rebuild and re-theme. It is separate from [posture](collaboration.md) (the relationship register), the doctrine packs ([Rules](rules.md)) and [footprint](footprint.md).
+Mode is chosen at build time, so it does not drift mid-session, and kept across every rebuild and re-theme. It is separate from [posture](collaboration.md) (the relationship register), the doctrine packs ([Rules](rules.md)) and [footprint](footprint.md). It is also separate from a [loop](loops.md) — a pipeline is a one-shot, uncommitted crew for a single task; a loop is a long-running state machine that commits each validated iteration on its own branch.
 
 ### direct — the default
 

package/docs/concepts/hook-gates.md

@@ -0,0 +1,61 @@
+---
+group: concepts
+order: 7
+title: "Hook gates, settings and the shim"
+kind: "concept"
+section: "Harness"
+description: "Gates fail closed, the settings files hooks are written to, Bob and OpenClaude, and the hook shim."
+---
+How Geneseed's [hooks](hooks.md) behave when something goes wrong, where they are written on each host, and the one file they all run through.
+
+## Gates fail closed, and leave a trace
+
+If a gate cannot evaluate a call — an unreadable payload, a bug — it asks, with the error as its reason, rather than silently letting the call through. Every prompt a gate raises adds one line to `notebook/gates.jsonl` in the install: the rule and the time, never the command or content. `geneseed status` counts them by rule.
+
+```bash
+geneseed status
+```
+
+In an [excluded folder](exclusions.md), every hook of a global install exits silently. And a global install's `context` hook stands down when the repo has its own per-repo install of the same host, so nothing is injected twice.
+
+## Where they are written
+
+| Host | Global | Per repo |
+| --- | --- | --- |
+| Claude Code | `~/.claude/settings.json` | `.claude/settings.local.json` |
+| OpenClaude | `~/.openclaude/settings.json` | `.openclaude/settings.local.json` |
+| Bob | `~/.bob/settings/settings.json` | `.bob/settings.json` |
+
+Per repo, Claude Code and OpenClaude hooks go into the **local**, untracked settings file: the hook commands contain paths on your machine, and the team-shared `settings.json` would hand every teammate broken hooks.
+
+The merge is surgical. Every other key and every hook of your own survive, and the install manifest records exactly which hook groups are Geneseed's, so an upgrade replaces and an uninstall removes only those.
+
+## Bob and OpenClaude
+
+**OpenClaude** is a Claude Code fork: it gets the same hooks and the same prompts, unchanged.
+
+**Bob** has its own contract. It uses Claude's event names but ignores a hook's output before a tool call — the only way to refuse is exit code 2 — and it has no tool matcher, `SubagentStop` or `PreCompact`. So Bob gets three hooks:
+
+- `SessionStart` → `geneseed-hook context`.
+- `PreToolUse` → `geneseed-hook tool-gate`, the git gate and the rule gate fused into one command that decides from the shape of the call. It **blocks** (exit 2) only for the two Rules, secrets and destructive git. The commit/push and rule-or-memory checks become a warning line, because a hard block would leave Bob unable to commit at all.
+- `Stop` → `geneseed-hook learn`.
+
+Neither host has been verified live on the authoring machine. If a hook does not fire, the same rules still reach the agent through the instructions file.
+
+## The hook shim
+
+Hooks run with your project as the working directory, so each command needs an absolute path. Rather than write the Node path and the Geneseed checkout path into every settings file, every hook points at one stable file, the **hook shim**: `~/.geneseed/bin/geneseed-hook` (`geneseed-hook.cmd` on Windows). The shim holds those two paths; your settings hold none. Set `GENESEED_HOME` to keep it somewhere other than `~/.geneseed`.
+
+Every build rewrites the shim, so moving the checkout and running one build repairs every install at once.
+
+**A stale shim fails silently.** Hooks report through their output and exit 0 on every path — that is what keeps a broken hook from breaking your tool calls. The flip side: if the shim points at a checkout that no longer exists, every hook on the machine stops working and nothing tells you. The agent simply stops getting project context and the gates stop asking. `geneseed doctor` checks the shim; a build repairs it.
+
+```bash
+geneseed doctor
+```
+
+See [Hook, context and memory problems](../reference/troubleshoot-hooks.md).
+
+## Cost
+
+The hook program is small on purpose: it adds about 14 ms to each tool call.

package/docs/concepts/hooks.md

@@ -1,8 +1,10 @@
 ---
 group: concepts
-order: 5
+order: 6
 title: "Hooks (Claude Code, Bob, OpenClaude)"
 kind: "concept"
+section: "Harness"
+description: "The commands Claude Code, Bob and OpenClaude run at fixed moments, and what each gate does."
 ---
 A **hook** is a command your host runs at a fixed moment — when a session starts, before a tool call, when the agent finishes. On Claude Code, Bob and OpenClaude, hooks are how Geneseed does anything *in code* rather than in prose: load your project's docs, stop a risky command for your confirmation, save what was learned.
 
@@ -10,7 +12,7 @@ A **hook** is a command your host runs at a fixed moment — when a session star
 
 Geneseed writes its hooks into the host's settings file. Every hook calls one program, `geneseed-hook`, with a verb — not the `geneseed` CLI you type yourself. The instructions file (`CLAUDE.md`) needs no hook: the host loads it by location.
 
-### The hooks on Claude Code
+## The hooks on Claude Code
 
 | Event | When | Command | What it does | Conditional? |
 | --- | --- | --- | --- | --- |
@@ -22,7 +24,7 @@ Geneseed writes its hooks into the host's settings file. Every hook calls one pr
 | `SubagentStop` | a subagent finishes | `geneseed-hook learn` | records a lesson for that agent in `memory/agents/<name>.md` | needs `GENESEED_LLM` |
 | `PreCompact` | before auto-compaction | `geneseed-hook learn` | captures memory before the transcript is summarised | needs `GENESEED_LLM` |
 
-### What each one does, and what you see
+## What each one does, and what you see
 
 **context.** Before your first message, the agent receives your own harness files — `user-rules.md`, `PROFILE.md`, the memory index, the notebook index, your wiki declaration — skipping any still untouched since install, then the repo's docs, discovered by convention or listed in a `context.json`. Each file is capped at 16 KB and the whole injection at 48 KB; what does not fit is listed for the agent to read on demand. You see nothing, except that the agent already knows your project. See [Project context](../guides/project-context.md).
 
@@ -44,58 +46,8 @@ export GENESEED_LLM="claude -p"
 
 Unset, `learn` does nothing useful — it prints the prompt it would have sent. Geneseed never stores or embeds an API key. See [Memory](memory.md).
 
-### Gates fail closed, and leave a trace
-
-If a gate cannot evaluate a call — an unreadable payload, a bug — it asks, with the error as its reason, rather than silently letting the call through. Every prompt a gate raises adds one line to `notebook/gates.jsonl` in the install: the rule and the time, never the command or content. `geneseed status` counts them by rule.
-
-```bash
-geneseed status
-```
-
-In an [excluded folder](exclusions.md), every hook of a global install exits silently. And a global install's `context` hook stands down when the repo has its own per-repo install of the same host, so nothing is injected twice.
-
-### Where they are written
-
-| Host | Global | Per repo |
-| --- | --- | --- |
-| Claude Code | `~/.claude/settings.json` | `.claude/settings.local.json` |
-| OpenClaude | `~/.openclaude/settings.json` | `.openclaude/settings.local.json` |
-| Bob | `~/.bob/settings/settings.json` | `.bob/settings.json` |
-
-Per repo, Claude Code and OpenClaude hooks go into the **local**, untracked settings file: the hook commands contain paths on your machine, and the team-shared `settings.json` would hand every teammate broken hooks.
-
-The merge is surgical. Every other key and every hook of your own survive, and the install manifest records exactly which hook groups are Geneseed's, so an upgrade replaces and an uninstall removes only those.
-
-### Bob and OpenClaude
-
-**OpenClaude** is a Claude Code fork: it gets the same hooks and the same prompts, unchanged.
-
-**Bob** has its own contract. It uses Claude's event names but ignores a hook's output before a tool call — the only way to refuse is exit code 2 — and it has no tool matcher, `SubagentStop` or `PreCompact`. So Bob gets three hooks:
-
-- `SessionStart` → `geneseed-hook context`.
-- `PreToolUse` → `geneseed-hook tool-gate`, the git gate and the rule gate fused into one command that decides from the shape of the call. It **blocks** (exit 2) only for the two Rules, secrets and destructive git. The commit/push and rule-or-memory checks become a warning line, because a hard block would leave Bob unable to commit at all.
-- `Stop` → `geneseed-hook learn`.
-
-Neither host has been verified live on the authoring machine. If a hook does not fire, the same rules still reach the agent through the instructions file.
-
-### The hook shim
-
-Hooks run with your project as the working directory, so each command needs an absolute path. Rather than write the Node path and the Geneseed checkout path into every settings file, every hook points at one stable file, the **hook shim**: `~/.geneseed/bin/geneseed-hook` (`geneseed-hook.cmd` on Windows). The shim holds those two paths; your settings hold none. Set `GENESEED_HOME` to keep it somewhere other than `~/.geneseed`.
-
-Every build rewrites the shim, so moving the checkout and running one build repairs every install at once.
-
-**A stale shim fails silently.** Hooks report through their output and exit 0 on every path — that is what keeps a broken hook from breaking your tool calls. The flip side: if the shim points at a checkout that no longer exists, every hook on the machine stops working and nothing tells you. The agent simply stops getting project context and the gates stop asking. `geneseed doctor` checks the shim; a build repairs it.
-
-```bash
-geneseed doctor
-```
-
-See [Troubleshooting](../reference/troubleshooting.md).
-
-### Cost
-
-The hook program is small on purpose: it adds about 14 ms to each tool call.
-
-### Verify
+## Verify
 
 Open a session in a repo and ask the agent what it knows about the project — it should answer from the repo's docs without reading them first. Ask it to commit something: you should get a prompt before the commit runs.
+
+What happens when a gate cannot decide, where the hooks are written, and the one file they all run through: [Hook gates, settings and the shim](hook-gates.md).

package/docs/concepts/host-matrix.md

@@ -0,0 +1,38 @@
+---
+group: concepts
+order: 2
+title: "What each host automates"
+kind: "concept"
+section: "Harness"
+description: "Row by row, which checks each host runs in code and which stay prose."
+---
+Every [host](hosts.md) gets the same content. This table is what each one lets Geneseed **automate** (check in code before an action) rather than only **ask** of the model.
+
+| Capability | OpenCode | Claude Code | Bob | OpenClaude |
+| --- | :---: | :---: | :---: | :---: |
+| Instructions file | `AGENT.md` via `opencode.json` | `CLAUDE.md` | `AGENTS.md` + `rules/geneseed.md` | `CLAUDE.md` (`.openclaude/` per repo) |
+| Agents · Skills · Memory · Notebook | ✅ | ✅ | ✅ | ✅ |
+| Project context loaded at session start | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook² |
+| Memory written back at session end (learn) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook² |
+| Destructive git (force-push, `reset --hard`…) | 🔒 permission ask | 🪝 ask | 🪝 block¹ | 🪝 ask² |
+| Secrets kept out of files | ⚙️ block⁴ | 🪝 ask | 🪝 block¹ | 🪝 ask² |
+| Consent before every commit and push | 🔒 permission ask | 🪝 ask | 🪝 warning¹ | 🪝 ask² |
+| Rule-or-memory write needs your call | ⚙️ speed bump³ | 🪝 ask | 🪝 warning¹ | 🪝 ask² |
+| Sovereign-repo exclusions | ⚙️ plugins stand down | ✅ `claudeMdExcludes` | ✅ rules shadow stub | ✅ `claudeMdExcludes` |
+| MCP server wiring | ✅ `mcp` | ✅ `mcpServers` | ✅ `mcp.json` | ✅ `mcpServers` |
+| Colour themes · LSP · workflow runner · primary agent · `/`-commands | ✅ | ➖ | ➖ | ➖ |
+
+✅ native · ⚙️ OpenCode plugin · 🔒 `permission.bash` entry in `opencode.json` · 🪝 `settings.json` hook · ➖ no host mechanism (the rule still applies as prose).
+
+¹ **Bob** has its own hook contract: Claude's event names, but it ignores a hook's output on `PreToolUse`, so the only way to refuse is exit code 2. Geneseed therefore blocks only the two always-on rules (secrets, destructive git) and turns the two consent checks into a logged warning. It has no `SubagentStop` or `PreCompact` event, so learn runs on `Stop` only. **Unverified live** — there is no Bob install on the authoring machine; the rules preamble still holds if a hook does not fire.
+² **OpenClaude** is a Claude Code fork and gets Claude's hooks and verdicts verbatim, in `~/.openclaude/settings.json` (global) or `.openclaude/settings.local.json` (per repo). **Unverified live** for the same reason.
+³ OpenCode's plugin hook can only allow or throw — there is no "ask the user" — so this check stops the first such write once rather than prompting.
+⁴ The checks differ in shape: OpenCode's guard plugin blocks writes *to* private-key and credential files by path; the Claude-shaped hook looks at the *content* being written for credential-shaped strings (cloud keys, tokens, private-key blocks) and asks. A `.env` file is exempt on the hook side — that is where a secret is allowed to live.
+
+## The one conditional row
+
+The **consent before commit and push** row depends on a choice you make at build time. It enforces the rule *Consent Before Push*, which belongs to the **process** doctrine pack ([Rules](rules.md)). Build without that pack, or exclude that one rule, and the commit/push question goes away — but the gate itself stays: on Claude Code and OpenClaude the `git-gate` hook is still wired (with `--no-consent`), so destructive git is still caught. Everything else in the table is always on.
+
+One OpenCode asymmetry: Geneseed shares `opencode.json` with you and cannot tell its own `git commit*` permission entry from one you typed, so a rebuild without the process pack leaves an existing entry in place and says so instead of deleting it.
+
+In plain terms: [Enforced vs. asked](../understand/enforced-vs-asked.md).

package/docs/concepts/hosts.md

@@ -3,53 +3,27 @@ group: concepts
 order: 1
 title: "Hosts"
 kind: "concept"
+section: "Harness"
+description: "The AI coding tools Geneseed installs into, and what each one can enforce."
 ---
 A **host** is the AI coding tool Geneseed installs into — OpenCode, Claude Code, Bob or OpenClaude. Geneseed does not run the model; the host does. Geneseed writes the files the host reads (the instructions file, agents, skills) and, where the host allows it, wires small programs that run around the agent's actions. The *content* is the same on every host. What differs is how much of it the host lets Geneseed **automate** — check in code before an action — rather than only **ask** of the model in prose.
 
 > **You already know this:** one codebase, several CI providers. The pipeline does the same job everywhere, but each provider exposes different hooks, so some checks run natively on one and are a manual step on another.
 
-### What is the same everywhere
+## What is the same everywhere
 
 One build renders the same text for every host: the constitution ([rules](rules.md)), the {N_AGENTS} [agents](agents.md), the {N_SKILLS} [skills](skills.md), the [memory](memory.md) and [notebook](notebook.md) conventions, and the theme's voice. No host drops an agent, a skill or the memory convention.
 
 Each host has a **global** install (in its config directory, active in every repo) and a **per-repo** install (inside one project). There is also a portable `files` bundle — a plain `Harness/` folder with an `AGENT.md` that any tool reading an instructions file can use, with no automation at all.
 
-### Two engines
+## Two engines
 
 - **OpenCode** runs its own engine: Geneseed installs JavaScript **plugins** that OpenCode loads, plus permission entries in `opencode.json`. It also gets OpenCode-only extras: colour themes, [language servers](lsp.md), a workflow runner, a primary agent and `/`-commands.
 - **Claude Code**, **Bob** and **OpenClaude** share one Claude-shaped engine: Geneseed wires **hooks** into the host's `settings.json`, each calling `geneseed-hook <verb>`. See [Hooks](hooks.md).
 
-### What each host automates
-
-| Capability | OpenCode | Claude Code | Bob | OpenClaude |
-| --- | :---: | :---: | :---: | :---: |
-| Instructions file | `AGENT.md` via `opencode.json` | `CLAUDE.md` | `AGENTS.md` + `rules/geneseed.md` | `CLAUDE.md` (`.openclaude/` per repo) |
-| Agents · Skills · Memory · Notebook | ✅ | ✅ | ✅ | ✅ |
-| Project context loaded at session start | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook² |
-| Memory written back at session end (learn) | ⚙️ plugin | 🪝 hook | 🪝 hook¹ | 🪝 hook² |
-| Destructive git (force-push, `reset --hard`…) | 🔒 permission ask | 🪝 ask | 🪝 block¹ | 🪝 ask² |
-| Secrets kept out of files | ⚙️ block⁴ | 🪝 ask | 🪝 block¹ | 🪝 ask² |
-| Consent before every commit and push | 🔒 permission ask | 🪝 ask | 🪝 warning¹ | 🪝 ask² |
-| Rule-or-memory write needs your call | ⚙️ speed bump³ | 🪝 ask | 🪝 warning¹ | 🪝 ask² |
-| Sovereign-repo exclusions | ⚙️ plugins stand down | ✅ `claudeMdExcludes` | ✅ rules shadow stub | ✅ `claudeMdExcludes` |
-| MCP server wiring | ✅ `mcp` | ✅ `mcpServers` | ✅ `mcp.json` | ✅ `mcpServers` |
-| Colour themes · LSP · workflow runner · primary agent · `/`-commands | ✅ | ➖ | ➖ | ➖ |
-
-✅ native · ⚙️ OpenCode plugin · 🔒 `permission.bash` entry in `opencode.json` · 🪝 `settings.json` hook · ➖ no host mechanism (the rule still applies as prose).
-
-¹ **Bob** has its own hook contract: Claude's event names, but it ignores a hook's output on `PreToolUse`, so the only way to refuse is exit code 2. Geneseed therefore blocks only the two always-on rules (secrets, destructive git) and turns the two consent checks into a logged warning. It has no `SubagentStop` or `PreCompact` event, so learn runs on `Stop` only. **Unverified live** — there is no Bob install on the authoring machine; the rules preamble still holds if a hook does not fire.
-² **OpenClaude** is a Claude Code fork and gets Claude's hooks and verdicts verbatim, in `~/.openclaude/settings.json` (global) or `.openclaude/settings.local.json` (per repo). **Unverified live** for the same reason.
-³ OpenCode's plugin hook can only allow or throw — there is no "ask the user" — so this check stops the first such write once rather than prompting.
-⁴ The checks differ in shape: OpenCode's guard plugin blocks writes *to* private-key and credential files by path; the Claude-shaped hook looks at the *content* being written for credential-shaped strings (cloud keys, tokens, private-key blocks) and asks. A `.env` file is exempt on the hook side — that is where a secret is allowed to live.
-
-### The one conditional row
-
-The **consent before commit and push** row depends on a choice you make at build time. It enforces the rule *Consent Before Push*, which belongs to the **process** doctrine pack ([Rules](rules.md)). Build without that pack, or exclude that one rule, and the commit/push question goes away — but the gate itself stays: on Claude Code and OpenClaude the `git-gate` hook is still wired (with `--no-consent`), so destructive git is still caught. Everything else in the table is always on.
-
-One OpenCode asymmetry: Geneseed shares `opencode.json` with you and cannot tell its own `git commit*` permission entry from one you typed, so a rebuild without the process pack leaves an existing entry in place and says so instead of deleting it.
-
-### Where to go next
+## Where to go next
 
+- Which checks each host runs in code, row by row: [What each host automates](host-matrix.md).
 - What exactly each host writes to disk: [What lands on your machine](../understand/on-your-machine.md).
 - Code-enforced versus asked-of-the-model, in plain terms: [Enforced vs. asked](../understand/enforced-vs-asked.md).
 - Per-host detail for maintainers: [OpenCode](../../adapters/opencode/README.md) · [Claude Code](../../adapters/claude-code/README.md) · [Bob](../../adapters/bob/README.md) · [OpenClaude](../../adapters/openclaude/README.md).

package/docs/concepts/loop-branch.md

@@ -0,0 +1,66 @@
+---
+group: concepts
+kind: "concept"
+section: "Loops"
+order: 23
+title: "LOOP.md, trailers and the loop branch"
+description: "The loop's state file, the trailers on every commit, the loop/* branch exemption, and the console's view."
+---
+## `LOOP.md` and its trailers
+
+`LOOP.md`, at the worktree root, is both the human-readable record (title, requirement, and the
+rule that you may edit `preset` or `contracts` there) and the engine's own JSON state block. Every
+closing commit carries a fixed set of trailers, read straight off that state — `Loop-Gates` only
+when the unit passed at least one human gate:
+
+```
+Loop-Iteration: <n>
+Loop-Bricks: <every brick name visited this unit, deduplicated>
+Loop-Risk-Declared: <score>
+Loop-Risk-Actual: <score>
+Loop-Threshold: <preset> <silent>/<soft>
+Loop-Decision: silent | soft | blocking[ (amended)]
+Loop-Tests: <what the loop was told about test state>
+Loop-Gates: <every node whose gate passed this unit, deduplicated>
+```
+
+## The `loop/*` branch, and why merge always asks
+
+A loop runs in its own worktree, on a branch named `loop/<slug>` — the `loop` skill creates both
+with `git worktree add -b loop/<slug>` before `geneseed loop init` writes `LOOP.md` there.
+While that branch is checked out and `LOOP.md` carries the engine's state marker, the git gate lets
+exactly one commit/push form through without asking:
+
+```
+git add -A && git commit -F <message_file> && git push [-u] <remote> HEAD:<loop branch>
+```
+
+Nothing else is exempt — not `git commit -m`, not a quoted refspec, not a plain `git push` with no
+explicit `HEAD:<ref>` — any other shape still asks. The exemption only ever covers a `loop/*`
+branch, and never a shared one (`main`, `master`, `develop`, `development`, `release/*`,
+`hotfix/*`). The **final** commit of a run — the one that removes `LOOP.md` on `$close` — is
+outside the exemption too, because the loop is no longer running when it lands; that ask is your
+consent to close it. **Merging a loop branch into anything else always asks, with no exception.**
+The loop reports the branch to merge and the iterations that landed in "to review" — it never
+merges for you.
+
+## Watching a loop
+
+Every `geneseed loop init` upserts an identity row — root, branch, title, started — into a
+**loop registry** at `$XDG_CONFIG_HOME/geneseed/loops.json` (default `~/.config/geneseed/loops.json`).
+`LOOP.md` stays the only source of loop *state*; the registry just lets the console find a loop
+without scanning every worktree on the machine. Only loops launched by this version or later are
+registered, so a loop started before the registry existed won't appear until re-initialised.
+
+The console's **Loops › Active** tab (`GET /api/loops/active`, polled every few seconds) reads that
+registry and shows one card per loop: branch, status (`running`, `awaiting`, `done`, `stopped`,
+`finished`, or `unreadable` if `LOOP.md` fails to parse), `iteration N / max`, and its current
+node. A loop `awaiting` a decision is highlighted with what it's waiting on — the launch, the
+declared score, the actual score, or a human gate (with its node) — but **the answer is given in the agent's session**, with
+`geneseed loop decide`, never from the page. A finished loop (`LOOP.md` removed) is kept, muted,
+for 7 days after first being seen finished, then dropped. Selecting a card draws its ring with the
+current node filled, with the iteration history (declared, actual, decision, tests) underneath.
+
+Each live card also carries a **preset picker** (`POST /api/loops/preset`) that rewrites
+`LOOP.md`'s `preset` field — the same edit you could make by hand — applying from the next score
+on, not retroactively. It's the tab's only write; there is no relaunch button.

package/docs/concepts/loop-bricks.md

@@ -0,0 +1,48 @@
+---
+group: concepts
+kind: "concept"
+section: "Loops"
+order: 18
+title: "Bricks and their origins"
+description: "What a brick is, how templates wire bricks, and how project and global bricks override shipped ones."
+---
+A **brick** is a markdown file: YAML-ish frontmatter (`name`, `description`, `effect` — `read` or
+`mutate` — exactly one of `agent` or `skill`, and `outcomes`) plus a 4-10 line prose body. The
+model never sees the file; `geneseed loop next` hands it the body as the prompt. A **loop
+template** — a shipped template (see [Loop templates](loop-templates.md)) or one composed by hand — is the graph JSON
+that wires bricks together.
+
+Both are looked up across three origins, each able to override the one before it **by name**:
+
+| origin | path | who writes it |
+|---|---|---|
+| shipped | `src/bricks/`, `src/loops/` | Geneseed itself — read by the CLI from its own source, never emitted into an install |
+| global | `$XDG_CONFIG_HOME/geneseed/{bricks,loops}` (default `~/.config/geneseed/…`) | the user, for every project on this machine |
+| project | `<repo>/.geneseed/{bricks,loops}` | a team, committed and shared |
+
+Precedence is project > global > shipped. A project or global brick named `apply` replaces the
+shipped `apply` everywhere a template references it, without the template changing.
+`geneseed loop check` lists every override it finds, never silently.
+
+A per-install skill exclusion is invisible to the CLI — it has no way to know which skills your
+install carries. The `loop` skill covers the gap itself: when composing a graph it skips a brick
+whose `skill` it doesn't have.
+
+To add or adapt a brick, use the `brick-forge` skill — ask it, or see
+[the bricks README](../../src/bricks/README.md) in
+the repository.
+
+## Java notes for the newer bricks
+
+- **`mutation-check`** (`legacy-tests`) prefers PIT on a Maven build: `mvn test-compile
+  org.pitest:pitest-maven:mutationCoverage -DtargetClasses=<fq.Class*>
+  -DreportsDirectory=<OS temp dir> -DtimestampedReports=false`, and needs `pitest-junit5-plugin`
+  on the classpath under JUnit 5; on Gradle, the `info.solidsoft.pitest` plugin's `pitest` task.
+  With neither configured it reports `unavailable` rather than adding the plugin itself or a
+  silent `pass`.
+- **`fitness-define`** (`enforce-architecture-rule`) reaches for ArchUnit first on Java — a
+  `FreezingArchRule`, whose violation store doubles as the allowlist of today's violations —
+  before dependency-cruiser, import-linter, eslint-plugin-boundaries or size-limit elsewhere.
+- **`migration-plan`** (`update-contract`) treats Pact or Spring Cloud Contract, where the repo
+  already records consumer contracts, as the check `compat-check` runs against each step rather
+  than only the consumers' own test suites.

package/docs/concepts/loop-contracts.md

@@ -0,0 +1,33 @@
+---
+group: concepts
+kind: "concept"
+section: "Loops"
+order: 22
+title: "Contracts and ignored deletions"
+description: "The contract globs that always raise risk, the deletions a template ignores, and the glob dialect."
+---
+A template may declare `contracts`: globs for the interface or schema files whose *shape* a
+change can break, not just the implementation behind it — `update-contract` and
+`api-endpoint` ship defaults (OpenAPI/Swagger/AsyncAPI specs, `.proto`, `.avsc`, GraphQL schemas,
+Flyway/Liquibase migrations). They're copied into `LOOP.md`'s own `contracts` at `loop init`;
+`loop init --contracts <globs>` appends more, and the list is editable by hand in `LOOP.md`
+afterward, applying from the next score on. Touching a file any of these globs match raises the
+*actual* score to at least the **api** weight (0.8) regardless of the declared card — a contract
+edit is never silent.
+
+A template may also declare `ignoreDeletions`: globs excluded from the ">20 deleted lines"
+escalation rule only. `deps-upgrade` lists lockfiles this way (`**/package-lock.json`,
+`**/yarn.lock`, `**/pnpm-lock.yaml`, `**/*.lock`, `**/gradle.lockfile`) because a lockfile
+regenerating under a bump deletes and re-adds hundreds of lines with no risk in them;
+`remove-dead-code` ignores generated output (`**/generated/**`, `**/generated-sources/**`,
+`**/target/**`, `**/build/generated/**`) for the same reason. A file matched by `ignoreDeletions`
+is still subject to the write-set check — it must still be declared or match a write-set glob, it
+just doesn't count toward the deletion total.
+
+Both lists, and the write set, share one hand-rolled glob dialect (no dependency — this module
+imports only node builtins): `*` and `?` stay inside one path segment, `**` crosses segments and
+`**/` may match zero directories (so `**/yarn.lock` also covers the root one); there is no brace
+expansion (`{a,b}`). A write-set entry is matched as a glob too, but only when it has at least one
+literal (non-`*`/`?`) path segment — a wildcard-only entry like `**` or `**/*.java` would
+otherwise declare the whole repo as writable, so it's left to match nothing instead and the
+check fails closed.

package/docs/concepts/loop-gates.md

@@ -0,0 +1,30 @@
+---
+group: concepts
+kind: "concept"
+section: "Loops"
+order: 21
+title: "Human gates"
+description: "Bricks that hold for a person whatever the score, and how ok, no and amend answer them."
+---
+A brick can hold for a person regardless of preset or score, independent of the [risk machinery](loop-risk.md): its frontmatter carries `gate: human`, optionally narrowed with `gateOn: <outcomes>` (no
+`gateOn` holds on every outcome the brick can report). `adr-challenge` (holds on `pass` — a
+drafted ADR that survived its skeptic), `fitness-define`, `migration-plan` and `spec` all gate
+this way: the loop reports `{awaiting}` with `kind: "gate"` before the edge that outcome would
+normally follow is taken at all — **the gate holds the whole transition**, so nothing is scored,
+committed or counted against a ring budget while it waits.
+
+`geneseed loop decide --verdict ok|no|amend` answers it:
+
+- **`ok`** follows the edge the brick's reported outcome actually points to. On a brick gated on
+  more than one outcome, a held `fail` still routes through its own edge on `ok` — which is
+  usually `$stop` — so `ok` on a held failure stops the loop, it doesn't wave it through.
+- **`no`** stops the loop at that node.
+- **`amend`** re-runs the same brick with your note appended to `LOOP.md`'s notes, so the next
+  run of that brick sees it; the node's re-entry (ring) budget restarts, since the amendment
+  changes what the unit does. A node can be amended at most 3 times per iteration — the 4th
+  amend stops the loop instead: three rounds that didn't converge are a conversation, not a loop.
+
+Every closing commit that passed a gate names it under `Loop-Gates` (see [LOOP.md, trailers and the loop branch](loop-branch.md)). The console's
+**Active** tab shows a gated loop as `Awaiting gate at <node>`, the same way it shows a score
+`awaiting`. A gate passed in a read-only setup unit leaves its approval as a note in `LOOP.md`,
+not a trailer — that unit closes without a commit.

package/docs/concepts/loop-notes.md

@@ -0,0 +1,43 @@
+---
+group: concepts
+kind: "concept"
+section: "Loops"
+order: 19
+title: "Notes and rules"
+description: "What survives an iteration in LOOP.md's notes, and the rules a template hands every brick."
+---
+Two ways words travel through a loop: the notes a brick leaves in `LOOP.md`, and the rules a template hands every brick.
+
+## Notes: what survives an iteration
+
+A `read` brick can find something worth keeping — a plan, a review finding, a mutation gap, a
+classified CI failure — that the next brick needs but the outcome string alone can't carry.
+`geneseed loop record --note "<text>"` (or `--note-file <path>` for anything multi-line or that
+mentions `git commit`/`push`, which a shell argument can't carry safely) appends it to `LOOP.md`'s
+notes, so it survives into the next node and the next iteration instead of evaporating with the
+brick's own context. The brick never records a note itself — a brick only ever reports its
+outcome, plus the path to a file it wrote; the loop skill records it with `--note-file` on the
+brick's behalf. This applies to `plan` and `review` as much as to the newer bricks: any `read`
+brick whose finding the next brick needs writes it to a file in the OS temp directory and reports
+that file's path with the outcome.
+
+## `description` and `rules`: what a template is for, and what every brick must do
+
+A template's JSON carries two prose fields, and they are never confused:
+
+- **`description`** — the catalogue blurb: what the template is for and when to pick it. The
+  `loop` skill and the console read it to choose a template; no brick ever receives it.
+- **`rules`** — optional, a list of one-line instructions every brick of this loop must follow
+  (`["Each card's intent cites the proof it is unused: …", "Generated sources do not count as
+  unused."]`). `geneseed loop check` refuses anything but a list of non-empty strings.
+
+`geneseed loop next` hands the template's `rules` to every node — not only the iteration head that
+reads `LOOP.md` — so a template-wide proviso (cite your deletion proof, a flaky test is never fixed
+with a retry, contract edits stop for a human by design) is visible to whichever brick runs,
+including `review`, which checks the diff against it. A graph with no `rules`, or an empty list,
+omits the field; there is no fallback to `description`.
+
+A template may also carry a **`category`** — one of `architecture`, `tests`, `development`,
+`refactoring`, `day-to-day` — the shelf the console's Loops page files it under, in that order.
+It is optional (a template without one is listed under *Other*); `geneseed loop check` refuses
+any other value.

package/docs/concepts/loop-risk.md

@@ -0,0 +1,36 @@
+---
+group: concepts
+kind: "concept"
+section: "Loops"
+order: 20
+title: "Risk, trust and validation levels"
+description: "How a loop scores a change, the trust presets, and the silent, soft and blocking levels."
+---
+Before a `mutate` brick runs, the loop scores the card the brick's setup declared: one risk weight
+per action kind it named, and the score is the **max**, not a sum — one contract change outweighs
+ten trivial renames, and ten trivial renames never add up to one. After the brick runs, the loop
+re-scores against the real diff, and the diff can only raise the score, never lower it:
+
+- a file touched outside the declared write set raises the score to at least **api** (`0.8`);
+- more than 20 deleted lines raises it to at least the **delete** weight;
+- touching a file listed in the loop's `contracts` raises it to at least the **api** weight.
+
+`LOOP.md` itself is excluded from every score and every diff check — it's the engine's own
+bookkeeping, rewritten on every action, never part of the work being judged.
+
+The score is checked against a **trust preset** — `--preset` on `geneseed loop init`, editable
+afterward in `LOOP.md`'s `preset` field, applying from the next score on:
+
+| preset | silent ≤ | soft ≤ | above soft |
+|---|---|---|---|
+| prudent | 0.1 | 0.3 | blocking |
+| balanced (default) | 0.2 | 0.6 | blocking |
+| aggressive | 0.4 | 0.8 | blocking |
+
+Three levels follow from where the score lands:
+
+- **silent** — nothing more than the commit trailers (see [LOOP.md, trailers and the loop branch](loop-branch.md)).
+- **soft** — listed under "to review" in the run's final summary; no notification during the run.
+- **blocking** — the run ends. `LOOP.md` is written with `status: awaiting`, and a person has to
+  answer with `geneseed loop decide --verdict ok|no|amend`. Amending a verdict marks the decision
+  `blocking (amended)` in the trailers rather than silently rewriting it to something else.

package/docs/concepts/loop-templates.md

@@ -0,0 +1,50 @@
+---
+group: concepts
+kind: "concept"
+section: "Loops"
+order: 17
+title: "Loop templates"
+description: "Every shipped loop template, what it is for, and the notes that matter when you pick one."
+---
+The loop templates Geneseed ships. Each is a graph of [bricks](loop-bricks.md) wired for one kind of work; [Run a loop](../guides/run-a-loop.md) picks one by what you want to do.
+
+| template | purpose | when to use |
+|---|---|---|
+| `bugfix` | reproduce, fix, test, review a defect | a reported bug with a reproduction step |
+| `feature` | plan, then build and review in small iterations | new behaviour with no existing test pinning it |
+| `refactor` | restructure behind the existing tests, no behaviour change | the tests already cover the code you're moving |
+| `tdd` | plan, then write each failing test before the code that passes it | you want the test written first, every iteration |
+| `legacy-tests` | pin undocumented behaviour with characterization tests, mutation-checked, production code untouched | code with no tests and no spec, before anyone risks changing it |
+| `legacy-refactor` | pin current behaviour once with characterization tests, then refactor behind that net | the refactor target has no tests yet but will get changed |
+| `deps-upgrade` | upgrade one package or group per iteration: read breaking changes, bump, adapt, audit | a dependency bump that needs to land as reviewable steps, not one big diff |
+| `ci-repair` | triage failing CI checks for the current commit and fix one code failure per iteration | a red CI run on a `loop/*` branch that needs to go green |
+| `architecture-decision` | draft one ADR per decision the requirement names, challenged by a skeptic brick, reviewed by the user | a design choice worth recording before (or instead of) any code changes |
+| `enforce-architecture-rule` | encode an architecture rule as a test with an allowlist of today's violations, then fix one violation per iteration | a rule the codebase should hold everywhere but doesn't yet |
+| `update-contract` | change an interface with live consumers as expand, migrate one consumer per iteration, contract | an API, schema or event change that can't break existing callers in one step |
+| `spec-first-feature` | write the feature's spec (EARS criteria, ordered tasks) for review, then build one task per iteration | a feature whose acceptance criteria are worth pinning down before any code |
+| `api-endpoint` | plan, build, test, write a Bruno request and security-review one endpoint change per iteration | an HTTP API feature where each endpoint needs its own exercised request and a security pass |
+| `remove-dead-code` | confirm the suite is green, then delete one coherent group of unused code per iteration, test, review | code a tool (knip, ts-prune, vulture, PMD…) and a reference search say is unused |
+| `fix-flaky-tests` | confirm flakiness by repeated runs, then fix one test's root cause per iteration — never a retry or a sleep | a test that fails only sometimes, not every run |
+
+`feature` and `spec-first-feature` both end with an independent `done-check`: before `$close`, it
+maps every acceptance criterion to a passing test (or a stated manual check) and reports `fail`
+with what's missing rather than trusting the iterations that already ran.
+
+`legacy-tests` and `legacy-refactor` both open on `baseline-green` — the suite must already be
+green before either template pins anything, and `baseline-green` reporting `fail` stops the loop
+rather than characterizing a change no one can tell from existing breakage.
+
+`mutation-check`, inside `legacy-tests`, needs a mutation tool on the stack (Stryker, PIT, mutmut,
+cargo-mutants) to prove the new characterization tests actually bite. With none configured it
+reports `unavailable` rather than a silent `pass` — and still writes a note saying what it checked,
+so the gap is visible in `LOOP.md` rather than just absent from it.
+
+`ci-repair` needs CI to actually run on `loop/*` branches; `ci-triage` keys off the HEAD commit's
+checks (`gh run list --commit`), and with no run for that commit it reports `done` with a note
+rather than treating a branch CI never touched as green.
+
+`deps-upgrade` lists lockfiles under `ignoreDeletions` (`**/package-lock.json`, `**/yarn.lock`,
+`**/pnpm-lock.yaml`, `**/*.lock`, `**/gradle.lockfile`): a lockfile regenerating under a bump deletes
+and re-adds hundreds of lines with no risk in them, so those lines stay out of the deleted-lines
+count. Everything else keeps the default `delete` weight, and a lockfile outside the iteration's
+write set still escalates like any other file.