docs(AGENTS): write down the wave workflow

Most work here is done by waves of agents in worktrees, and every rule in
this section was learned by breaking it: the three orchestrator-only files
and why, that kb.pl additions must be batched because loadProgram replaces a
whole predicate, that tickets sharing a file belong to one agent, that a
worktree does not reliably branch from the orchestrator's HEAD, that direnv
status reports 0 for allowed, and that the code review's characteristic find
here is a test that passes while the thing it names is broken.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EoW5BB87ZZdm96SvBTWawH

AGENTS.md

@@ -53,6 +53,111 @@ cp -rf source dest          # NOT: cp -r source dest
 - `apt-get` - use `-y` flag
 - `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var
 
+## The Wave Workflow
+
+Most work here is done by **waves**: an orchestrator chunks the open backlog,
+fans several agents out into their own git worktrees, merges what comes back,
+reviews it, and pushes the wave as one PR. This section is what that costs to
+get right. Everything in it was learned by getting it wrong first.
+
+### Who owns what
+
+Three files are **orchestrator-only**, and the rule exists because they are
+guaranteed conflicts — every agent has a reason to touch them and they merge
+badly:
+
+| File | Why |
+|---|---|
+| `.beads/` (incl. `issues.jsonl`) | bd owns it. See "Never hand-edit" below. |
+| `prolog-sessions/kb.pl` | MCP-maintained, whole-predicate replacement. |
+| `context/repo-map.md` | Every agent wants to add a gotcha; every wave would conflict. |
+
+Wave agents **read** all three freely (`bd show`, `bd ready`, grep `kb.pl`) and
+**write** none of them. They report proposed repo-map lines and `kb.pl` facts as
+*text* in their hand-back, and the orchestrator applies them — batched, at the
+end of the wave, after the review. Batching matters for `kb.pl` specifically:
+`loadProgram` **replaces a whole predicate**, so every addition means re-sending
+every existing clause of `doctrine/2`, `decision/3`, etc. Doing that once per
+wave instead of once per fact is the difference between cheap and painful. It
+has already silently wiped 22 decisions and 19 doctrines once — count with
+`findall/length` before and after, and check the count before saving.
+
+`saveSession` re-adds the MCP's own `host_rpc` shims to `kb.pl` every time.
+Strip them after each save.
+
+### Partitioning a wave
+
+Partition by **crate or directory**, not by ticket count, and tell each agent
+explicitly which ground is *not* theirs. Two rules that fall out of the ones we
+broke:
+
+- **Tickets that share a file belong to one agent.** The four TUI widget
+  migrations all touch `src/draw.rs`; split across agents they are a guaranteed
+  conflict, so they go to one agent to do sequentially. Group first, then count.
+- **An agent that must stray says so rather than guessing.** Give the boundary
+  and ask for a report when it has to be crossed.
+
+Two agents each adding a workspace member will still collide in
+`Cargo.toml`/`Cargo.lock`. That one is expected; keep both sides.
+
+### Every wave agent's brief must include
+
+1. **Verify your base commit first.** Worktrees do **not** reliably branch from
+   the orchestrator's HEAD — one was created three merges behind and only
+   noticed because it was told to look. `git log --oneline -1` against a named
+   commit, reset onto `main` if behind. Name the expected commit in the brief.
+2. **The baseline test count**, so "1090 passing" is checkable rather than
+   asserted, and a drop is visible.
+3. **Do not push, do not merge to `main`.** The orchestrator merges.
+4. The commit-message trailers, spelled out.
+5. **What to report**: branch and commits, what changed per ticket, *what could
+   not be verified and why*, and proposed repo-map/`kb.pl` text. Ask explicitly
+   for the thing the agent learned that the ticket did not predict — that is
+   consistently the most valuable part of a hand-back, and agents omit it unless
+   asked.
+
+`bd` works in any worktree, but `.envrc` must be allowed there or you get a
+**version mismatch** rather than a clean failure — `direnv allow` in the
+worktree, or rely on the `[whitelist] prefix` in `~/.config/direnv/direnv.toml`.
+Note `direnv status` reports `Found RC allowed 0`, and `0` means **allowed**
+(the enum is 0=Allowed, 1=NotAllowed). It reads like the opposite.
+
+### Between waves
+
+Run the **code-review skill** on the merged range and iterate until its backlog
+is empty. This is not ceremony: in this repo the review's characteristic find is
+not a wrong line, it is **a test that passes while the thing it names is
+broken** — a vacuous fold test, a bit-witness that cannot see the bit, a
+one-category fixture, a helper that fabricates the `_Measure` items the code
+under test needs, a check-the-checker that injected malformed JSON and so proved
+nothing. A green suite is not evidence. Ask the reviewer to *inject the fault*
+and watch the check fail.
+
+### Shipping a wave
+
+One PR per wave, built by a **dedicated PR agent in its own worktree**, so waves
+pipeline against it: the next wave runs while the PR absorbs review fixes.
+
+Copilot review must be **re-requested after every fix push** (GraphQL
+`requestReviews`); it does not re-review on its own. Across three PRs it found
+five genuine bugs and zero false positives, so its findings are worth the loop.
+Merge only once it passes.
+
+### Never hand-edit `.beads/issues.jsonl`
+
+bd manipulates that file and auto-exports to it. Editing it — or even
+`git checkout`-ing it, which fires the post-checkout hook — breaks auto-export
+and desynchronises `export-state.json`. Use `bd` commands, let auto-export run,
+and commit whatever it leaves.
+
+### Before filing a ticket, search
+
+Agent-filed issues duplicate work that is already open, sometimes already
+in progress. Two duplicates were filed in this repo within minutes of the
+hand-backs that prompted them. `bd search` the core concept *and* scan
+in-progress issues first.
+
+
 <!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
 ## Beads Issue Tracker