geneseed 3.12.0 → 3.13.0

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.

package/docs/concepts/loops.md

@@ -1,10 +1,14 @@
 ---
 group: concepts
-order: 11
-title: "Loops"
 kind: "concept"
-link: {"hash": "#/docs/reference/cli", "label": "geneseed loop --help →"}
+section: "Loops"
+order: 16
+title: "Loops"
+link: {"hash":"#/docs/loop-actions","label":"The geneseed loop actions →"}
+description: "What a loop is, the ring of bricks it runs, and how it differs from foreman mode."
 ---
+To run one, see [Run a loop](../guides/run-a-loop.md).
+
 A **loop** is a requirement worked as small, validated, committed iterations instead of one long
 turn. `geneseed loop` is the state machine: it decides every transition, ceiling, score and stop,
 and hands the agent one node at a time to run. The `loop` [skill](skills.md) is the only thing
@@ -22,10 +26,11 @@ report. One cycle through the graph back to its head is an **iteration**; the gr
 array names every cycle that is allowed to exist, each with a `max` number of times a node inside
 it may be re-entered. Picture it as rings: the outer ring is the iteration itself (plan, apply,
 test, review, back to plan), and inner rings sit inside it for retries (apply failed its test, try
-`apply` again without going all the way back around). The three shipped templates —
-`bugfix`, `feature`, `refactor` — all nest a short `apply`↔`test` retry ring inside the iteration
-ring, and `bugfix` and `feature` nest a second, wider `apply`↔`test`↔`review` ring
-(`review-fix`) around that.
+`apply` again without going all the way back around). The shipped templates that center on
+`apply` — `bugfix`, `feature`, `refactor`, `tdd`, `legacy-refactor`, `deps-upgrade` — all nest a
+short `apply`↔`test` retry ring inside the iteration ring, and most nest a second, wider
+`review-fix` ring around that. `legacy-tests` and `ci-repair` have no `apply` at all: the first
+only ever writes tests, the second repairs CI directly through `ci-fix`.
 
 Work closes into a commit whenever the graph re-enters the iteration loop's head — so any setup
 work before the loop starts (reproducing a bug, say) is its own unit, numbered iteration 0, kept
@@ -42,120 +47,23 @@ all gets exactly 1 — no re-entry — which is also why **every cycle inside an
 named inner loop** in the graph JSON: `geneseed loop check` (and `loop init`, which runs the same
 check) refuses a graph with an undeclared cycle inside an iteration, before a single node runs.
 
-## Bricks, templates, and the three origins
-
-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** (`bugfix`, `feature`, `refactor`, 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](https://github.com/geneseed-dev/geneseed/blob/main/src/bricks/README.md) in
-the repository.
-
-## Risk, trust, and the three validation 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 below.
-- **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.
-
-## `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 seven trailers, read straight off that state:
-
-```
-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>
-```
-
-## 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.
-
-## `geneseed loop` actions
-
-| action | what it does |
-|---|---|
-| `check` | lists templates and every brick (available, unavailable, overridden); validates one graph file (`--graph`) or one brick file (`--brick`) |
-| `init` | writes a fresh `LOOP.md` from a template or graph file, under a title, requirement and trust preset |
-| `next` | the only driver of the cycle — returns the next thing to do: run a node, score a card, answer an `awaiting`, or a terminal |
-| `score` | scores a declared card (`--declared`) before a mutate node runs, or the real diff (`--diff`, numstat piped on stdin) before a commit |
-| `record` | records a brick's reported outcome and advances the graph |
-| `decide` | answers an `awaiting` validation with a verdict and a note |
-
-Run `geneseed loop --help` for the full flag list.
-
 ## Limits
 
 - **No parallel nodes.** The graph runs one node at a time; there is no fan-out.
-- **A per-install skill exclusion is invisible to the CLI** (see above) — the `loop` skill is
+- **A per-install skill exclusion is invisible to the CLI** (see [Bricks and their origins](loop-bricks.md)) — the `loop` skill is
   responsible for skipping bricks it can't run, not the engine.
 
+## Read on
+
+- [Loop templates](loop-templates.md): the shipped graphs, and when to use each.
+- [Bricks and their origins](loop-bricks.md): what a brick is, and where your own override the shipped ones.
+- [Notes and rules](loop-notes.md): what survives an iteration, and what every brick must follow.
+- [Risk, trust and validation levels](loop-risk.md): how a change is scored, and when it stops for you.
+- [Human gates](loop-gates.md): the bricks that always wait for a person.
+- [Contracts and ignored deletions](loop-contracts.md): the globs that raise or ignore risk.
+- [LOOP.md, trailers and the loop branch](loop-branch.md): the state file, the commit trailers, and why merging always asks.
+- [Loop actions](../reference/loop-actions.md): the `geneseed loop` commands.
+
 ## Not foreman mode
 
 A loop and a [foreman-mode](foreman-mode.md) pipeline are both "hand work off and keep going," but

package/docs/concepts/lsp.md

@@ -3,6 +3,8 @@ group: concepts
 order: 13
 title: "Code intelligence (LSP, OpenCode)"
 kind: "concept"
+section: "Configuration"
+description: "Language servers on OpenCode, so the agent sees real diagnostics."
 ---
 OpenCode can run **language servers** — the same Language Server Protocol servers your editor uses — so the agent sees real diagnostics, type errors and definitions, not just text. Geneseed turns this on for every language OpenCode ships a server for.
 

package/docs/concepts/memory.md

@@ -1,7 +1,9 @@
 ---
 group: concepts
-order: 6
+order: 8
 title: "Memory"
 kind: "markdown"
+section: "Memory"
+description: "How durable facts are stored, indexed and loaded."
 source: "src/memory/README.md"
 ---

package/docs/concepts/notebook.md

@@ -1,7 +1,9 @@
 ---
 group: concepts
-order: 7
+order: 9
 title: "Notebook"
 kind: "markdown"
+section: "Memory"
+description: "The agent's own working space: plans, notes and the gate log."
 source: "src/notebook/README.md"
 ---

package/docs/concepts/rules.md

@@ -1,8 +1,10 @@
 ---
 group: concepts
-order: 2
+order: 3
 title: "Rules (the constitution)"
 kind: "concept"
+section: "Harness"
+description: "The constitution: the standing rules every session carries, in laws and doctrine packs."
 link: {"hash": "#/laws", "label": "Browse the constitution →"}
 ---
 The **constitution** is the set of standing rules the agent carries into every session. It is authored in `src/`, rendered into the instructions file your host reads (`AGENT.md`, `CLAUDE.md` or `AGENTS.md`), and comes in layers that differ in one thing: whether you can turn them off.
@@ -37,7 +39,7 @@ When two instructions disagree, the higher one wins.
 | **process** | how a session runs — planning, context economy, docs first, bounded loops, consent before every commit and push |
 | **comms** | how answers are presented — stable reference codes on tracked items, a diagram or table only where it earns its place |
 
-All of them are on by default. This install built in {N_PACKS_ACTIVE}, carrying {N_DOCTRINE_RULES} rules between them. You choose packs at build time with `--doctrines`, or drop single rules with `--exclude-rules`; the how-to is in [Choose your setup](../guides/choose-your-setup.md).
+All of them are on by default. This install built in {N_PACKS_ACTIVE}, carrying {N_DOCTRINE_RULES} rules between them. You choose packs at build time with `--doctrines`, or drop single rules with `--exclude-rules`; the how-to is in [Doctrine packs and single rules](../guides/setup-doctrines.md).
 
 A pack you leave out **still ships**: every pack file lands under `doctrines/` beside the instructions file whether or not it was built in. A rule that cites an inactive pack still resolves on disk, and you can read the alternatives before turning one on. An inactive pack loses its binding force, not its availability.
 

package/docs/concepts/skills.md

@@ -1,8 +1,10 @@
 ---
 group: concepts
-order: 4
+order: 5
 title: "Skills"
 kind: "concept"
+section: "Harness"
+description: "Written playbooks the agent follows for a repeatable task."
 link: {"hash": "#/section/skills", "label": "Browse the catalog →"}
 ---
 A **skill** is a repeatable workflow written as a markdown playbook: when it applies, the steps, and what "done" looks like. The agent reads the playbook before acting, so a task it has a skill for is done the same careful way every time instead of improvised.

package/docs/concepts/themes.md

@@ -1,8 +1,10 @@
 ---
 group: concepts
-order: 12
+order: 11
 title: "Themes"
 kind: "concept"
+section: "Configuration"
+description: "The agent's voice and the words the harness uses, never its structure."
 ---
 A **theme** changes the agent's *voice* and the words the harness uses for its own parts. It never changes structure: the same rules, in the same order, with the same files, folders and links, whatever theme you pick.