wanderbooks/docs/runbooks/re-audit.md

The re-audit, through the MCP alone

The owner's acceptance of the whole programme (plan/served.md, P10). An agent audits a company's books using only the books tools, the books' own filed documents and the viewer's Export menu. Nothing here reads the data root, a database file or the journal file. The engineering mirror of this runbook is crates/ledger-cli/tests/defects.rs (every tool named below exists; every defect has a named regression test); the run itself is the owner's, on the owner's books.

Money is a decimal string everywhere. Every tool named is a tool in books.start's list; if one is missing, stop: the runbook is stale, not the books.

Before you start

• Two roles. The auditor runs books.audit, reads, and proposes fixes. The verifiers (at least two agents, not the auditor, not whoever made the entry) attest. The human confirms every correction.
• The bar is policy.attestation_bar (default effort=high verifiers=2 adversarial=true, D-9). Read it with books.settings. A verifier's method is its own claim, said truthfully: { model, reasoning_effort, adversarial, verifier_agents }. A reading that differs from the entry is recorded with disagrees: true and never counts; never bend a reading to fit.
• Context discipline. A receipt is read as text first (books.get_receipt, the default meta view is under 8 KiB, view: "text" gives the whole text), as one page picture (view: "page_image", page, max_px) only when the text is empty or looks wrong, and never as bytes. Record each verifier's own token count for receipts; the exit bar is under 100K tokens per verifier.
• Start with books.start (rules, conventions, open items, its next_steps) and books.handbook section attestations-and-audit. The audit prompt (scope: month, annual, cpa_handoff or full) is the same procedure for a client that offers prompts.
• Audits and attestations need the books' audits feature (the owner's format upgrade). Without it the tools refuse with format_upgrade_pending: do the upgrade first, as its own step, with the owner.

The two cases

• T1, desktop only. Claude Code and Codex on the owner's machine, through wanderbooks connect. Separation between the agent and the data root is advisory. The evidence that it held is the access log (books.access_log, books:admin) and the agents' transcripts, which never name the data root or a path into it.
• T2, a self-host machine running (D-30, D-31; deploy/README.md). The same steps, plus claude.ai through the tunnel once P9b exists. Separation is enforced by the machine's account split. Until P9b, T2 is T1 with the server on its own machine.

The steps are identical; only the evidence in step 8 differs.

Step 1. The first audit and its fixes

1. books.audit { scope: "full", through: <the last month end> } without confirmed: it lists the checks and changes nothing. Show the human. Then run it with confirmed: true and the preview digest. Do the same for { scope: "cpa_handoff", through: <the fiscal year end> }.
2. books.workpaper { id } for each run: the findings and the PDF as filed.
3. Fix every finding through journaled corrections, never an edit:
   • a wrong posted entry: books.reverse_entry { entry_id, date, description }, previewed, then confirmed: true; then the right entry through books.draft_entry, books.add_line, books.post_entry (preview, then confirmed);
   • a reversal with no receipt of its own (an old one, legacy_reversal_exempt): its evidence is its original's (D-12, D-47). Link the original's receipt to the reversal with books.link_attachment { attachment_id, subject }; books.list_receipts { entry_id } finds the receipt;
   • a duplicate file: books.consolidate_duplicates (preview, then confirmed); books.find_attachment to look one up by hash or number;
   • a receipt's facts: books.annotate_attachment;
   • an open draft: post it, or books.discard_draft { reason };
   • an undecided 1099 vendor: books.set_vendor_1099;
   • a missing tax category: books.set_tax_category;
   • a judgment the books should remember: books.record_decision. Nothing is fixed without the human's confirmation.
4. Audit again at the new head. An audit is idempotent on the same books (already_run), so a new run means the books changed. Repeat until the full and cpa_handoff runs have no error findings; keep the final two run ids. Each journaled fix can be traced with books.journal_history { subject }.

Step 2. Every receipt attested

For every receipt on a posted entry (books.list_receipts, entry by entry, or books.search_entries then books.get_entry):

1. Verifier A reads books.get_receipt (text; a page image only if needed) and calls books.attest_receipt { attachment_id, entry_id, amount, date, method, note? } with the total and the date as read off the receipt.
2. Verifier B does the same independently, without seeing A's reading.
3. books.attestations { kind: "receipt" } shows each claim with counted. A claim below the bar, or with disagrees: true, does not count; the disagreement is a finding: reopen step 1 for that entry.

Step 3. Every entry reviewed, every period attested

1. books.review_entry { entry_id, method } for every posted entry, by a verifier that did not make it.
2. books.attest_period { period, method } for each month since the company's formation (books.list_periods), each against a standing audit at the current head (scope: "month" or "full"), then once for the fiscal year against the cpa_handoff run. A period attestation is refused when the books changed since the audit: audit again, then attest.
3. books.attestations with no filter: every row has counted: true and none has disagrees.

Step 4. The defect regressions

The 2026-10-16 audit found 20 defects; P0 found two more (21, 22) and P3 two (23, 24). Each has a named regression test in the workspace; crates/ledger-cli/tests/defects.rs holds the list (defect, test, file) and proves each name exists. Show them green, from a checkout of the build under audit:

cargo test -p ledger-cli --test defects

then each test named in that list, by name, for example cargo test -p ledger-core --test spec_cash_flow defect1_two_member_llc_first_year_regression. Two defects have no code fix to test: defect 2 (reversals without their own evidence) is closed by D-12 and D-47 (its test shows the rule now) and defect 20 (the migration scripts) was retired at the cutover (no tool exists; the test checks none came back). Record the test run's output in the sign-off decision (step 7).

Step 5. The Sheet comparison

The old Google Sheet and the books were frozen as of 2026-10-11 and compared a final time before the cutover (P2, verify-sheet); that run is filed as a document. There is no comparison tool and this runbook builds none.

1. books.find_attachment { text: "verify-sheet" } finds the filed run (its extracted text names the tool); books.get_receipt { attachment_id } reads it (text view; its links and sha256 identify it). Cite it by attachment id and sha256. If it is not found, stop: the comparison was not filed at the cutover and the owner decides what stands in for it.
2. books.record_decision { subject: "Sheet comparison as of 2026-10-11", decision_md, decided_by: [<the owner>], decided_on, evidence_attachment: <that workpaper's id> } stating that the frozen Sheet and the books agreed then, and nothing newer is claimed.

Step 6. The CPA package from both doors

1. The agent's door: books.export_cpa_package { as_of: <the year end>, include_tins: true } (TINs are included by default, D-29). Without a counted audit it is refused (audit_required); never use without_audit_reason for the re-audit, the point is that it is not needed. Save the zip with the download command in its file.
2. The viewer's door: wanderbooks gui <book>, the Export menu, the CPA package as of the same day. It lands in the Downloads folder.
3. Compare the two zips file by file: byte-identical except for timestamps (the README's generated-at line and the zip entries' times). A difference in any figure is a defect: stop and report it.

Step 7. Verify, back up, sign off

1. books.verify { blobs: true }: status: "ok" (not healed: a healed result means a torn tail was set aside; note it and look at books.journal_history's tail_repairs).
2. books.backup: every target not stale, last_error empty, and last_drill_at set with no drill_error. If not, books.back_up_now (an admin action) and read it again. The drill is the restore test; a backup that was never restored is not a backup.
3. The owner's sign-off: books.record_decision { subject: "Re-audit sign-off", decision_md, decided_by: [<the owner>], decided_on } naming the final cpa_handoff and full run ids, the journal head (books.verify's head), the defects run, and the CPA package's sha256.

Step 8. The exit evidence

The re-audit passes only when all of these are true. The owner checks them; the agent presents the proof for each.

Exit bar	Proof
Zero failing workpaper checks	the final full and cpa_handoff workpapers (books.workpaper)
Cash flow difference 0.00	books.cash_flow for the year; no cash_flow_unfooted finding
Every receipt and posted entry has a counted attestation, none disagrees	books.attestations (step 3.3)
Every action under the right principal	books.access_log: the auditor's token and each verifier's token appear on their own calls; no action by an admin token that an agent token did
No transcript names the data root	grep each agent's transcript for the root path before sign-off (T1); T2: the tenant root is not readable by the agent's account
No result carried a full TIN to a client that should not see one	books.access_log shows include_tins only on books.export_cpa_package and books.get_w9/books.vendor_1099 calls by the owner's agent; the agents' exports may carry them (D-29), nothing else
Receipt reading stayed under 100K tokens per verifier	each verifier's own token count for its receipt calls (the harness's count, written into the attestation note)
The sign-off is journaled	books.decisions shows it

When all are true the books are re-audited through the MCP alone.