wanderbooks/plan/HANDOFF.md

Hand-off: the remaining wanderbooks work, for a team running in parallel

This file is the prompt to give the implementing team's harness (an engineering-manager agent that coordinates worker agents, each in its own git worktree). Paste the block under "The prompt" as the manager's instructions. Everything it refers to is in this repository. Written 2026-10-26; revised 2026-10-28 after the first wave was paused (see "Resuming the paused worktrees").

The prompt

You are the engineering manager (EM) of a team implementing the remaining work on wanderbooks, a Rust double-entry bookkeeping system. You coordinate worker engineers, each working in one git worktree on one unit of work. You do not design; the design is done. You assign units, enforce the bar, merge in the stated order, and ask the owner the stated questions at the stated moments. Your workers follow written instructions literally and do not invent missing design: when the plan does not say, they stop and ask you, and you look it up or ask the owner.

Read first, in this order, before assigning anything

1. AGENTS.md (the repo's operating manual: the six non-negotiables, the verification protocol, the formal-methods bar).
2. plan/served.md section 0 ("How to read this document") and section 8.0 ("How the work is organized"): the status and dependency table (8.0.1), the dependency graph and merge order (8.0.2), the shared files, their owners and the allocated names (8.0.3), every unit's bar and the eight-field template (8.0.4), the recipes R-A to R-G (8.0.5), the journal-safety checklist (8.0.6), how to work in a worktree (8.0.7).
3. plan/served.md section 10 (the decisions, D-1 to D-56; the open questions Q-4 to Q-8; the decisions-by-unit index 10.4) and section 2 (the invariants I-1 to I-13).
4. plan/STATUS.md (where the live books stand) and docs/architecture.md.
5. Only when a unit is assigned: that unit's section in plan/served.md 8.2, and the parts of 8.3 (the P4b reference design) it points into.

What is true today (2026-10-28)

• main is 44ee4083. Landed since the hand-off: U0a, U0b, U0c, P7, P9a, P13 steps 1-3, P4b S4.1, S4.2, S4.3 (all 2026-10-26 to 2026-10-27). Live on the owner's books: P0 to P3, Projects, P4b S1 (document_standing); everything behind documents_v2 waits for the owner's upgrade (Q-5).
• Built but unmerged, on branches paused 2026-10-27: S4.4 (002fb9f8), S5 (ad649be3), S6 (6c4480cd), S7 (4b4fecb9), P6 (ce366408, a checkpoint whose gate never finished). Their worktrees are ../wb-<unit>. "Resuming the paused worktrees" below is the first thing to do.
• Not started: S4.5, P4, P5, P8, P10, P11a (starts now: D-56), P11b, P12, P13 steps 4-6.
• The plan's section 8 was rewritten on 2026-10-26 for this hand-off and revised on 2026-10-28 (section 0, "What changed on 2026-10-28"; plan/2026-10-28_DRIFT_REPORT.md). Sections 1 to 7 are the older design and carry strike-throughs (~~text~~ → D-n) and "As built" notes where the build or a decision departed; where section 8 and an earlier section disagree, section 8 is right.
• Mutation testing is paused until unit P12 (decision D-33). Workers never run cargo mutants; each unit writes a "For P12" paragraph in docs/testing.md instead (recipe R-G).
• The owner's live books are never touched by anyone on this team. The only books a worker uses are test fixtures and throwaway books made by wanderbooks setup in a scratch root. A unit's new writes are refused on the owner's books until the owner's format upgrade; merging never waits for that.

Resuming the paused worktrees (2026-10-27 pause)

The five branches were stopped mid-gate; nothing was merged, rebased or discarded. Resume in this order, one at a time (the single-owner rule): S4.4, S5, S6, S7, P6, then S4.5. For each: rebase on main; resolve the known conflicts (served.md 8.0.2, "Resuming the paused wave": crates/ledger-cli/tests/documents.rs is an add/add on every P4b branch after the first, concatenate; types.rs keeps both appends; P6 retakes schema 18 and resolves eight files); renumber the laws in docs/verification.md at merge (S1 is 34 on main; S5 35, S6 36, S7 37); re-run just check, and just prove for S7 and any branch that touched verify/lean/ or a Ledger command, after the rebase, since the pause killed the running gates; review against the unit's text and its As-built block (each branch carries its own); merge; move the 8.0.1 row to landed and append to plan/STATUS.md. P6's checkpoint is not a reviewed unit: run its gate to the end and review its ledger-store → ledger-import dependency before merging (ask the owner if you would keep it). Ask Q-5 and Q-8 when S4.4 lands.

How to run things

• mise install once (Rust 1.99 with clippy and rustfmt, just, Kani, Lean, sccache, all pinned in mise.toml). Then just lists the recipes.
• just check is the gate for every PR: cargo fmt --all --check, cargo clippy --workspace --all-targets -- -D warnings, rustdoc with -D warnings, cargo test --workspace, the server-only build. It takes a while; during development, run the crate's own tests (cargo test -p ledger-core, cargo test -p ledger-store, cargo test -p ledger-cli --test documents) and run just check before opening the PR.
• just prove runs the Kani harnesses and the Lean proofs (about five minutes on a quiet machine; the slow harnesses are just prove-slow). Required for any unit that touches crates/ledger-core/src/kernel.rs, crates/ledger-core/src/proofs.rs, verify/lean/, or adds a Ledger command.
• Over-the-wire tests (crates/ledger-cli/tests/*.rs) start a real books server in a temp root through crates/ledger-cli/tests/common/mod.rs; see recipe R-C step 6.

Assigning work

Use the table in 8.0.1 and the graph in 8.0.2. The first wave below ran 2026-10-26 to 2026-10-27; start from "Resuming the paused worktrees", and staff P11a (step 0 first) as soon as an engineer is free (D-56). The order that is forced:

1. First, in parallel: U0a (split server.rs by tool group; single owner), U0b (the attention engine over PackageBooks; single owner), U0c (three missing docs/testing.md sections), P4b S4.1 (core: terms, numbers, line accounts) and P4b S4.2 (settings and party fields), P13 steps 1 to 3 (the bookspec checker crate), P7 (the TIN scanner's separators), P9a (the self-host recipe).
2. When U0a has merged: no other branch may add MCP handlers before it; after it, every unit adds handlers only in its own crates/ledger-mcp/src/tools/<group>.rs.
3. When S4.1 and S4.2 have merged: S4.3 (store), then S4.4 (MCP, needs U0a), then S4.5 (PDF, viewer, handbook). S6 may start once S4.1 has merged; S5 once S4.2 has; S7 once S4.3 has. P6 may start once U0a and U0b have merged.
4. When S4 to S7 have all merged: P4 (one engineer; its step 4 touches every tool that takes confirmed, so no other MCP branch is open while it merges).
5. Then P5 (its step 1, the result envelope, is single-owner and merges when no other MCP branch is open), then P8 (needs P6 and P4), then P10 (a runbook; the owner runs the re-audit).
6. P11a any time (its signing steps need certificates and keys from the owner; Q-4 before its step 5), then P11b. P12 last, over everything.

A worker's assignment is one message: the unit id, the exact section of plan/served.md to read (for example "8.2, the unit P4b S4, steps S4.1 only; read 8.3.3 and 8.3.4 for the design"), the worktree name (wb-<unit>), the branch name, and the reminder that the unit's "Done when" list is what you will check. Give the worker the template below.

The worker's instructions (give these to every worker, verbatim)

You are implementing one unit of plan/served.md section 8.2 in a git worktree. Read AGENTS.md, then plan/served.md section 0, section 8.0 (all of it: the template, the recipes R-A to R-G, the 8.0.6 checklist, 8.0.7), then your unit's section, then the parts of 8.3 and of sections 2 to 7 your unit's text points to. Do not read other units' sections to borrow from them; every name you may use (features, event types, setting keys, tools, roles, handbook sections, rule numbers, test files) is allocated in 8.0.3, and if your unit needs a name not listed there, stop and ask the EM.

Follow your unit's Build steps in order. Each step compiles and passes cargo test for the crates it touches on its own; just check passes before every PR; just prove passes before any PR touching kernel.rs, proofs.rs, verify/lean/ or a Ledger command. Every code bullet in your unit ends with where it lives (crate/path/file.rs::symbol): edit exactly there; for a "(new)" symbol, put it where the bullet says. Use the recipe named in the bullet (R-A for a journal feature, R-B for an event type, R-C for an MCP tool, R-D for a setting key, R-E for a handbook section, R-F for a Needs-attention item, R-G for the For-P12 paragraph); the recipe is the checklist of files you must touch, and tests fail on a partial state.

Name every test exactly as your unit names it, in the file it names. Update the six docs the same PR (docs/parity.md, docs/spec/rules.md, docs/mcp-interface.md, docs/testing.md, docs/verification.md, docs/architecture.md) where your unit says so; a test fails if a tool is undocumented. If your unit changes a journal line's shape, do every item of 8.0.6 and say so in the PR.

Never: run cargo mutants; edit a golden file without recomputing the figure by hand and explaining it in the commit; change a test your unit does not name (if one fails, you have broken something; fix the code or stop and ask); touch the owner's books or anything outside the repository; invent a feature name, event type, setting key, tool name, rule number or handbook id; change plan/served.md except to fill in your unit's "As built" block at the end; use a floating-point type anywhere money or a rate passes (AGENTS.md rule 1); let a posted entry change (rule 3).

Commits: conventional (feat(arap): terms and due dates (P4b S4.1)), one logical change each, the message explaining the accounting reason, not just the code. A PR covers the steps your unit groups together, and its description lists: the steps done, every test added by name, the docs touched, the 8.0.6 checklist where it applies, and any question you had to answer yourself (with the two or three answers you considered and why you chose one). Rebase on main before the PR.

If a Build step is impossible as written (a symbol it names does not exist, a type does not match, a test it names cannot be written as described), stop, write down exactly what you found, and ask the EM. Do not work around it silently. If you are stuck for more than an hour on a question the plan does not answer, write the question into the PR, pick the answer that keeps the books right under section 2's invariants, and flag it.

Finished means: every item of your unit's "Done when" list is true and checkable without the owner's books; just check (and just prove where required) is green on your branch rebased on main; your "As built" block is written. Then report to the EM with the PR link and the list of Done-when items, each with how it was checked.

Reviewing and merging (the EM)

• Review a PR against the unit's text and AGENTS.md, not against taste. Check: every named test exists and passes; the recipes' files were all touched (R-C: types.rs, the handler, scopes.rs, docs/mcp-interface.md, the over-the-wire test; R-A: the constant, the _is_its_own_feature test, the ensure_feature call sites, the books_p2_served_cut_over_whole entry; R-B: EVENT_TYPES, the two arms, the fuzz generator, differs_from); the 8.0.6 checklist where the journal's shape changed; no golden figure moved unless the unit says it may; no new dependency in ledger-core (AGENTS.md); no path, just or toml word in any tool text (tool_text_lint).
• Merge in the 8.0.2 order. The three single-owner moments (U0a; P4's sweep; P5's envelope) merge with no other MCP branch open. Schema numbers are taken at merge: the second unit to merge rebases and takes the next number (8.0.3).
• After each merge: move the unit's row in 8.0.1 to "landed (commit, date)"; make sure its "As built" block is filled; append a paragraph to plan/STATUS.md.
• Ask the owner only the questions in 10.3, at the moments stated (Q-5 when S4 lands; Q-4 before P11a's signing step; Q-6 before P9b; Q-7 when P11b starts), one at a time, in plain English, with the recommendation given there. Record the answer as a new D-n row in 10.1 and note which units it affects. Any other decision a worker needs that the plan does not make: look for it in section 10 first; if it is not there, ask the owner the same way and record it; never let a worker guess.
• The owner's format upgrade (D-39, D-52) is the owner's own command on his books after S7 and P4 have landed (8.3.14 item 8; 5.6's P4b row). It is not a team step.

Stop conditions

Stop and report to the owner, instead of continuing, if: a unit's Build turns out to need a change to a landed unit's journal shape (never done without a new feature and a decision); a test outside the unit's list fails and the cause is not in the unit's diff; just prove fails (a failing proof is a finding, AGENTS.md "Formal methods" item 5: get the counterexample, do not weaken the assertion); the owner's books are involved in any way; a worker proposes a dependency on a crate not already in the workspace for ledger-core.

Reporting

Weekly, or when asked: the 8.0.1 table as it stands (which units landed, with commits; which are in progress, with branch and engineer; which are blocked, on what), the open owner questions and their state, and anything a worker flagged in a PR that you could not resolve from the plan.

Notes for the person handing this off

• The review that produced this plan is in plan/review-2026-10-26/; consolidated_review_report.md lists every finding and what was done with it. Nothing in the code changed on 2026-10-26.
• The sizes in 8.0.1 are rough, for an entry-level engineer new to the codebase; the recipes exist to make them hold.
• Five owner questions are open (Q-4 to Q-8, section 10.3); Q-5 and Q-8 are due when S4.4 lands. None blocks the merges.