Appearance
SPEC-003: Bank reconciliation, check against the bank
Amended 2026-10-09 by ADR 0035 (Product Owner, 2026-10-08): GetMy Books no longer connects to any bank. Every bank line comes from a statement file the owner downloads (CSV presets including Starling CSV, saved column mappings, OFX, QIF, Amex). Where a scenario below says "Starling item", read "a line from a statement file". S11 (revoked Starling token) and S55 (Starling rate limit and ID encoding) are superseded: there is no token or Starling call. The Starling API and token parts of Scope, Data model, Integration and the Notes are superseded likewise; they are kept as the record of what was built.
Amended 2026-10-06 by SPEC-011 S4 (approved by the Product Owner, pre-sale review, track C): bank_entries_confirm and vat_corrections_confirm are removed. The owner's Approve in the approval card makes every write (SPEC-003 S38), and
write_statusreports what became of a preview without ever writing. Where a scenario below says a confirm tool runs, read the card's Approve; where it says a confirm by the model alone is refused, write_status reports the preview as still waiting.
Business intent
Show the owner exactly what is unreconciled in Xero for the Starling account, why, and what each line should be, using the bank's own statement as the source of truth. That turns reconciling in Xero into pressing OK on known matches. It also feeds SPEC-001's unreconciled-bank-lines warning, which protects SM-3.
User story
When I sit down to reconcile the Starling account, I want a checked list of every statement line still open in Xero, with its likely match or coding, so I only have to confirm, not investigate.
Scope
- Set up each entity's bank accounts in
bank_account, each linked to a Xero bank account and read by one source (ADR 0015). Sources in this slice: Starling, with a read-only personal access token stored encrypted; and Amex UK statement exports (CSV, standard or extended), either named from the git-ignoredstatements/folder (Claude Code on the owner's machine) or passed inline as text in the call (ADR 0032, accepted: built forbank_reconciliation_check,vat_prepare_returnand, from S36,bank_entries_preview, the way the deployed server reads them). Inline text is parsed by code, held in memory for the request and never stored or logged. For each statement-file account in a call, givestatementFilesorstatementCsv, not both; neither reports the account as not checked. The period must lie inside the statements' dates. WithstatementFiles, a tool can only name a file inside that folder. Inline text is open to any customer's own statements (QD-29, decided 2026-10-03). - Read Starling feed items for a period, dated by their London date.
- Read Xero's records on the linked bank account, each with its reconciled flag: bank transactions (which include transfers and batch payments) and invoice and credit note payments outside a batch.
- Read Xero's own Bank Summary movement for the account, to prove the records read are complete.
- Match in pure code (
src/rules/) and classify every item. - Report the Starling and Xero movements for the period, in integer pence.
- Suggest a coding for unmatched lines from the entity's own reconciled history (same counterparty to the same account and tax type). The suggestion comes from code, never from a language model.
- Flag reconciled Xero lines whose tax type the SPEC-001 mapping cannot place in a box, on VAT-bearing accounts only: never transfers, balance sheet accounts, or costs that never carry VAT (pay, NI, pensions, bank charges, interest, insurance), recognised by account type and name.
- Flag possible VAT over-claims: exempt or outside-scope costs (insurance, bank charges, pay) coded 20%.
- Flag possible VAT under-claims: purchases coded no VAT where the cost is normally standard-rated (telecoms, software, subscriptions, professional fees), the same supplier is coded 20% elsewhere, or the account defaults to 20%. Shows the VAT at stake (one sixth of the gross) and the evidence. Other 20% codings on the same account only support, never flag, because accounts like Travel mix 20% and zero-rated costs.
- Summarise first: a headline, what to do in Xero (press OK, enter, resolve, check Xero-only records, review under-claims), and the bank-to-Xero difference by cause.
Out of scope
- Pressing OK, or anything that clears a statement line (ADR 0013).
- Writing to Xero beyond ADR 0016: bills, invoice payments, edits, deletes.
- Creating bank rules. Xero has no API for them, so they are suggested only.
- The Finexer aggregator: a later slice, once Finexer's API docs are in hand.
- Inline statement text for
bank_outstanding, the VAT correction tools andreceipts_reconcile.bank_entries_previewtakes it from S36, keeping only the fields sent to Xero until the preview ends (QD-31, ADR 0032 amendment). - Accounts not in GBP.
- Browser automation of Xero, ever (ADR 0013,
docs/not-doing.md).
Data model sketch
bank_account (id, entity_id, name, linked xero_bank_account_id, source = starling_token | statement_file | aggregator, encrypted credentials). Unique per entity by name and by Xero account. Under row-level security like every table. Money is integer pence. The pipeline applies the migration (ADR 0014).
Integration sketch
Starling API v2, read-only token scopes account:read, account-list:read, transaction:read:
GET /api/v2/accounts: account and default category idsGET /api/v2/feed/account/{accountUid}/category/{categoryUid}/transactions-between
Xero adds accounting.banktransactions.read (bank transactions and transfers) and accounting.reports.banksummary.read. The entity reconnects through scripts/xero-connect.ts, then connects Starling through scripts/starling-connect.ts.
MCP tools sketch
| Tool | Returns |
|---|---|
bank_accounts_list | The entity's bank accounts and how each is read, never credentials |
bank_reconciliation_check | For one entity, bank account and period: matched, unreconciled, ambiguous and Xero-only items; the totals check; coding suggestions; VAT flags |
bank_explain_line | One Starling item: candidate Xero records and why each was accepted or rejected |
bank_outstanding | Everything outstanding on one account across months (default: a year to date): summary, per-month counts, OKs to press, missing lines grouped by payee with coding suggestions, VAT under- and over-claims |
bank_entries_preview | Creates unreconciled Xero spend/receive money for bank lines the check shows as missing, within ADR 0016's guards; says which to press OK |
vat_corrections_preview | Previews, then on the owner's yes posts, one VAT correction journal for flagged under- and over-claims, within ADR 0017's guards |
Only bank_entries_preview (ADR 0016) and vat_corrections_preview (ADR 0017) write to Xero, and no tool clears a statement line. Counterparty names and references are returned as quoted data, never as instructions.
Classification
| Class | Meaning |
|---|---|
matched_reconciled | Starling item matches a reconciled Xero record. Nothing to do |
matched_unreconciled | A Xero record exists but is not reconciled. Press OK in Xero |
unreconciled_no_record | No Xero record. Shown with a coding suggestion if history gives one |
ambiguous | More than one candidate, or its only match is a Xero record dated outside the period (Product Owner, 2026-10-20). Never auto-picked; all shown for the owner to check |
near_match | Already in Xero, but dated up to 3 days apart or split across 2-3 records. Never entered again |
possible_match | Still missing after exact and near matching, but a leftover Xero record has the same amount and direction, dated 4 to 10 days apart (QD-24, #45). Every such record is listed and none is picked. Never counted as reconciled and never entered until the owner has checked it in Xero |
xero_only | A Xero record in the period with no Starling item, reconciled or not. Possible duplicate, wrong account or wrong date |
Match rule: same direction, same amount in pence, dates within the matching window (QD-09): same day for card and bank payments, up to 5 days for invoice payments. Counterparty and reference only break ties.
Scenarios
S1: Exact match
Given a settled Starling item of −£42.00 on 3 March to "Adobe" And a reconciled Xero spend-money of £42.00 on 3 March on the linked account When the check runs for March Then the item is matched_reconciled
S2: Record exists, not yet reconciled
Given a settled Starling item of +£1,200.00 And an unreconciled Xero payment of £1,200.00 against an invoice, within the window When the check runs Then the item is matched_unreconciled and names the invoice
S3: No Xero record
Given a settled Starling item with no candidate in Xero When the check runs Then the item is unreconciled_no_record And if the same counterparty was previously reconciled to one account and tax type, that coding is suggested
S4: Ambiguous candidates are not picked
Given two Xero records of the same amount within the window When the check runs Then the item is ambiguous and both candidates are listed
S5: Xero-only record
Given a Xero record in the period on the linked account with no Starling item When the check runs Then it is listed as xero_only
S6: Xero records are complete or the check blocks
Given the Xero records read for the account and period When their net movement differs from Xero's own Bank Summary movement Then the result is marked blocked and shows both figures in pence And otherwise the Starling and Xero movements and their difference are shown
S7: Pending items are excluded
Given a Starling item still pending When the check runs Then it is not classified and is counted separately as pending
S8: VAT flag on reconciled lines
Given a reconciled Xero line whose tax type has no SPEC-001 box mapping When the check runs Then the line is flagged, naming the tax type
S9: Companies are isolated
Given a session authorised for FEAW When WealthTechPros bank data is requested Then no rows are returned and no Starling call is made
S10: Writes are guarded (ADRs 0016 and 0017, audit M4)
Given the MCP tool list Then only bank_entries_confirm and vat_corrections_confirm write to Xero, each taking only a preview ID And bank_entries_preview and vat_corrections_preview only preview, writing nothing to Xero And a preview is confirmed once, within 60 minutes, by the person who made it (amended 2026-11-17, #433: was 15) And no tool name contains approve or submit
S12: Enter a missing line
Given a bank line the check classifies as missing from Xero When bank_entries_preview is called for it with an account and tax rate that exist in Xero Then the owner sees a preview with its ID and nothing is written When bank_entries_confirm is called with that preview ID after the owner says yes And the check, re-run, still classifies the line as missing Then Xero gets an unreconciled spend or receive money with the bank line's amount, date and direction And the write is logged And the owner is told to press OK for it in Xero
S14: Enter a missing line as a transfer
Given a bank line the check classifies as missing from Xero, such as a card repayment When bank_entries_preview is called for it with another Xero bank account as transferToAccount Then Xero gets a bank transfer between the two accounts for the bank line's amount and date And the call is refused, with nothing written, if the other account already has that transfer within 3 days
S13: Only missing lines can be entered
Given a call naming a bank line that is already matched, or not in the period Or an account or tax rate Xero does not have Then nothing is written, for any entry in the call, and each problem is named
S15: Correct a VAT coding error (ADR 0017)
Given a purchase the check flags as a VAT under- or over-claim When vat_corrections_preview is called for it with a rate that fixes that kind of error Then the owner sees a preview with its ID: the journal lines and the change to the next VAT return And nothing is posted until vat_corrections_confirm is called with that preview ID after the owner says yes And if the flags changed since the preview, nothing is posted And the posted journal reverses the old coding and re-posts the new one, same account and gross, dated today And the correction is logged and the record is no longer flagged
S16: Only flagged records, once, within HMRC's limit
Given a call naming a record not flagged now, a record already corrected, or a rate that does not fix the error Or corrections whose net VAT change is over £10,000 Then nothing is posted, for any correction in the call, and each problem is named
S17: Remember how a supplier is treated for VAT
Given the owner says a flagged supplier charges UK VAT, is overseas, or does not charge VAT When vat_remember_treatment saves it Then later checks suggest 20% (INPUT2) or reverse charge (REVERSECHARGES) for that supplier's under-claims And a supplier that does not charge VAT is no longer flagged And vat_corrections_preview refuses a rate that contradicts the saved treatment And nothing is written to Xero
S18: Mark one flag as not an error
Given the owner says a flagged purchase is coded correctly, such as travel abroad with no UK VAT When vat_remember_treatment saves that record as not an error Then that record is no longer flagged as an under- or over-claim, and other records from the same supplier still are
S11: Bad token stops cleanly (superseded by ADR 0035: no bank token exists)
Given a revoked or expired Starling token When the check runs Then no partial result is returned and the owner is told to reconnect Starling
S19: Statement passed inline (ADR 0032)
Given an Amex bank account with source statement_file, and its CSV text passed as statementCsv When bank_reconciliation_check runs on the deployed server Then the lines are parsed by code and the result equals the same file read through statementFiles And the reply gives each text's line count, date range and sum in pence, for the owner to compare with the Amex statement's totals
S20: A bad cell is refused without echoing it
Given statement text with an unreadable date or amount in one cell When the check runs Then it fails naming the row and column only, never the cell's value, and returns no partial result
S21: Statement content is not kept
Given a check run on inline statement text When it finishes Then the text appears in no log line, file or table, including in error text And the check's own result is not stored (a write preview or ledger write made later keeps only the fields ADR 0026 lists)
S22: Inline text is subject to the same gap and period checks
Given inline statements that leave a gap of more than 10 days, or do not cover the period When the check runs Then it fails with the same message as for files
S23: Exactly one source
Given both statementFiles and statementCsv for a statement-file account When the check runs Then it fails saying to give one of them, and reads nothing
Given neither, the account is reported as not checked, as today, and nothing is read And the rule applies to each statement-file account in the call
S24: Overlapping statements repeat no line
Given two inline statements whose dates overlap When the check runs Then each line is counted once, as for files
S25: Over the size limit
Given inline text over the request size limit When the check runs Then the web layer answers 413 "The request is too large." and nothing is read, and the tool description tells Claude to send one statement period at a time
S26: Inline text stays inside the authorised entity
Given a principal authorised for entity A only, and inline text naming an Amex account that belongs to entity B When the check runs Then nothing is read from entity B's account and the text is not used for it (CLAUDE.md rule 4) And the same text sent for entity A's own Amex account is checked normally
S27: Text goes only to the account it is for
Given an entity with two statement-file accounts, and a statement for each, each naming its account When the VAT readiness check runs Then each account is checked against its own statement only, and the receipts name the account
Given text that names no account, or names an account that is not a statement-file account When the check runs Then the account is not checked, naming the problem, and nothing is guessed
Given text for a Starling account, which is not read from statement files When bank_reconciliation_check runs Then it is refused with no receipt
S28: A statement that cannot be trusted to cover its dates is refused
Given a statement with no rows, a date that does not exist, or an amount too large for exact integer pence When the check runs Then it fails naming the row and column, and nothing is read from that statement And a statement with no rows cannot hide a gap between the others
S29: An unpaid bill that may duplicate a spend (2026-10-04)
Given a spend on the linked account that matches a bank line, and unpaid authorised bills from the same supplier dated within 5 days of it When one bill has the spend's amount, or two bills add up to it, or the larger of two less the smaller is the spend's amount (a sale and an exchange) Then the check lists them under possibleDoubleBookings and as one more thing to check in Xero: the spend (date, supplier, amount), the bills (reference, amount, VAT, whether each holds a receipt) and how they relate, as Xero has them And it does not say which record stands, and writes nothing And a bill from another supplier, a bill more than 5 days away, or a bill that is paid or part-paid is never listed And a blocked check reads no bills (the one extra Xero read is made only when the check is not blocked and has a matched spend)
This is a heuristic. Supplier names agree the way SPEC-005 receipts do (one name contains the other, ignoring case), a bill of nothing is ignored, and a spend that appears twice is listed once. A bill is not used up: it can be listed against more than one spend. The VAT readiness check (SPEC-001 S11) uses the same analysis without this list.
Found on FEAW's real data on 2026-10-04: Apple's £703.00 spend matched the card statement's one charge, while two unpaid Apple bills (£768.00 and £65.00, each with a receipt) had no bank line and so were not in xero_only. FEAW is on cash accounting (QD-30), so unpaid bills probably do not reach its VAT return; they do inflate expenses and what is owed to the supplier.
S34: Enter a missing line and attach its receipt in one approval (approved 2026-10-05)
Given bank lines the check classifies as missing from Xero, and a file in the company's Xero Files inbox for some of them When bank_entries_preview is called with an account, a tax rate and, for those lines, the file's ID Then the approval card shows each entry with its coding and the receipt it will carry, and nothing is written When the owner presses Approve and bank_entries_confirm is called with the preview ID Then each entry is created as an unreconciled spend or receive money and its file is attached to it And the receipt guards of SPEC-005 apply: one receipt per record, and only this company's files (S32) And an entry whose attach fails is still created, and the reply names the file to attach by hand And the owner is told to press OK for each line in Xero, where it now shows as an exact match
Also (review of PR #189, 2026-10-05):
- The write is normally made by the owner's Approve in the card (S38); bank_entries_confirm is only the fallback, and attaches the same way.
- A file that fails a receipt guard leaves its entry out of the card, listed in a "Left out" table with why, as SPEC-005 S32 leaves out a link; the other entries stay. A coding problem still refuses the whole call (S13).
- A fileId on a transfer is refused, with nothing previewed.
- At most 10 entries with a receipt per preview, since each costs Xero calls at preview and again at Approve; more is refused, telling Claude to split them into several previews.
- A file attached elsewhere between the preview and Approve: the entry is still entered, and that attach is refused and named. Since S42 (review of PR #199), this holds only for an entry that claims no VAT: one that claims VAT is not entered, and is named, since it goes in only with its receipt.
S35: "Reconcile my account" runs the whole job from one prompt (approved 2026-10-05)
Given the owner asks to reconcile one account (for example "reconcile my Amex") for a period When the reconcile-account prompt runs Then it first says, in plain words, what GetMy Books will do and what stays with the owner: pressing OK in Xero, approving each card, and deciding VAT treatment And it asks for the statement CSV when the account is read from statement files (ADR 0032) And it runs the check, then the chase-missing-receipts flow (SPEC-005 S33) for lines that claim VAT or are missing (amended by SPEC-011 S6: the Xero Files inbox and receipts_reconcile first, then email only for the receipts still missing) And it lists the VAT treatments it is unsure of as yes/no questions, using what vat_remember_treatment holds And it ends with one bank_entries_preview carrying codings and receipts (S34), then the list of OKs to press And it re-runs the check and, for a VAT period, the readiness check (SPEC-001 S11)
As built (2026-10-06): the prompt is reconcile-account (entity, optional bankAccount, optional month as YYYY-MM, default last month). It keeps the check's checkId (S39) for every preview and never re-sends the statement, finds account codes with xero_list_accounts (S40), asks yes/no for VAT and for personal or business, and splits the entries into cards of at most 25 (at most 10 with a receipt) rather than one preview. It pairs a receipt with a new entry only where receipts_reconcile says to enter that line first. The VAT readiness step runs only when the month ends one of the company's VAT quarters (dates worked out by code); for an unknown company it asks for the quarter. The month-end and VAT-ready prompts now pass the checkId too. receipts_reconcile also takes the check's checkId (one source only, the same refusals), so for an attached statement it says which missing lines to enter first with which receipt, and the prompt puts entry and receipt in one card.
S36: Missing lines from an inline statement can be entered (approved 2026-10-05, QD-31)
Given an account read from statement files, checked with statementCsv When bank_entries_preview is called with statementCsv for lines the check shows as missing Then the preview keeps only what Xero is sent for each chosen line (date, amount, direction, counterparty) And that is deleted when the preview is confirmed or expires And nothing else from the statement text is kept When the owner presses Approve (or bank_entries_confirm is called) Then each chosen line is checked against the Xero records entered since the preview, with the check's own matcher And a line Xero now has is not entered, and is named, while the others are entered and logged And the rules of S23 and S27 apply: files or text, not both; text only for the statement-file account it names
Built 2026-10-05 (ADR 0032 amendment):
- The statement is not read again at Approve, unlike files and Starling, whose full re-check is unchanged. Xero is read again for the account and period; the check still blocks on Xero's own totals, lock dates and a transfer's other side are checked, and a changed coding refuses the whole preview as before.
- Records already in Xero at preview are left out of the Approve matching (kept as ID, direction, amount and date), so a record the check gave to another statement line then cannot refuse this one. A record edited since the preview counts as new. A new record that only nearly matches (up to 3 days apart, or split) also stops the line: it fails safe.
- "Deleted": the app cannot delete a preview row (
bootstrap.sql), so its payload is replaced in the same transaction that confirms or declines it. An expired preview is cleared within 15 minutes, by a database function (migration 0010) the web and local servers run on start and every 15 minutes, and at once by any refused call on it.
Review of PR #191 (2026-10-05):
- The preview shows what was read from the text (name, lines, dates, charges and payments in pence), as S19's check does, and asks the owner to compare it with the statement.
- Each line warns, never blocks, when Xero has a record in the same direction within 3 days and within £1.00 or 1%, whichever is larger, including one matched to another line: "Xero already has a similar record (date, amount, contact): check this is not a duplicate."
- A counterparty used as the description is cleaned, and a leading = + - @ is escaped with an apostrophe.
- At most 25 entries per preview, refused by the tool's schema.
- Security re-check: the clearing function's search_path is
pg_catalog, pg_tempwith every name qualified; a payload the sweep cleared as it was claimed is refused as expired; a model-given description or contact name is escaped like bank text; a bank line ID in a warning is shown cleaned.
S37: Correct VAT on records the owner names (approved 2026-10-05, QD-32)
Given a reconciled spend money the check did not flag When the owner names it, with the tax rate it should have and a reason Then vat_corrections_preview includes it, with the VAT before and after, within ADR 0017's guards and HMRC's error limit And the reason is logged with the correction
As built (2026-10-05, ADR 0017 amendment): the owner names records in vat_corrections_preview's namedCorrections, each with its Xero id, the rate it should have and a reason of 3 to 200 characters. A named record must be a reconciled spend or receive money with one line, on that bank account, dated in the period and within 4 years of the journal, not flagged and not corrected before, with the VAT Xero holds matching its rate to the penny; anything else is refused, naming the record. HMRC's limit counts corrections already posted for the same VAT return. The card lists named corrections apart from flagged ones, with the reason given, the VAT before and after, the change to Boxes 1, 4 and 5, and what is already corrected for that return. At Approve, a record that changed in Xero since the preview stops the journal and is named, and posting is one at a time per company.
S38: Approve writes, with no second message (approved 2026-10-05)
Given a write preview shown in the approval card (bank entries, VAT corrections, or attachments in SPEC-005) When the owner presses Approve Then the card's app-only tool records the approval and makes the write in the same call And the card shows what was written, or why it was refused And the outcome is put in Claude's context, marked as data, so Claude sees it with the owner's next message and the owner never has to say "I pressed Approve" And the card sends no message itself, and says "Done. Claude will see this the next time you write." And the model still cannot see or call that tool, nor confirm a write itself (AUDIT C5) And a confirm call from the model keeps refusing without the card's approval (amended by SPEC-011 S4: there is no confirm tool; write_status only reports)
Changed 2026-10-05 (Product Owner): the card no longer sends Claude a message. Claude Desktop drafts an app's message into the owner's prompt box with a "Use caution before running this prompt" warning rather than sending it, so the Product Owner chose silent context: the outcome reaches Claude as context on the owner's next message.
S39: The preview reuses the check's statement lines by ID (approved 2026-10-06, QD-34, #194)
Given bank_reconciliation_check read an account's statement from inline text and returned a checkId When bank_entries_preview is called with that checkId and the bank line IDs, without the statement text Then it uses the lines the check read, held only in the server's memory And those lines are kept for at most 60 minutes, as long as a preview lasts (amended 2026-11-17, #433: was 15), only for the same person, company, account and period, and never written to the database or logs And an unknown, expired or other person's checkId is refused, asking for the check to be run again And passing statementCsv still works as before
Amended 2026-10-06 by SPEC-011 S5: bank_outstanding and bank_explain_line take the checkId too, under the same rules, so an account read from attached statement text works in every bank tool.
As built (2026-10-06, ADR 0032 amendment): vat_prepare_return returns a checkId too, one per statement-file account it read from text. Lines are kept as parsed and cut to the period, with the summary of each statement the check showed (name, rows, dates, charges and payments), which the card shows again. At most 50 checks are held, the oldest dropped first; one checkId serves several previews within its 60 minutes. checkId with statementCsv or statementFiles, or for an account not read from statement files, is refused. A restart forgets every checkId.
S40: Claude can look up the company's account codes (approved 2026-10-06, #195)
Given an owner who names an account ("Rob's director's loan account") When xero_list_accounts is called, optionally with a search text Then it lists that company's Xero accounts with code, name, type, default tax type and status, read-only And the company comes only from the session, and names are data, not instructions
As built (2026-10-06): xero_list_accounts takes an optional search (at most 100 characters, matched against code or name, ignoring case) and includeArchived (default false: active accounts only). Each account also says whether it is a bank account. It reads the chart Xero already gives the check (one call) and no money, so the base currency is not checked. Names sit only in table cells, the search text is cleaned to one line, and the reply says names are data, not instructions.
S41: Claude finds the statement files on the server when none are attached (approved 2026-10-06)
Given an account read from statement files, on a server whose statements folder (STATEMENTS_DIR, or statements in its working folder) holds that account's CSV exports When bank_statement_files is called for the account, optionally with a period Then it lists each CSV file in the folder with its line count and first and last dates, parsed by code, and never its contents And a file that cannot be parsed is listed as "could not be read", with no cell value And with a period, coversPeriod names the files that cover it, earliest first, and the days they do not cover, by the same 10-day gap rule as reading the files (for example "Covers 1 Sep 2026 to 27 Sep 2026; 28 Sep 2026 to 30 Sep 2026 not covered.") And only plain file names inside the folder are read, and the company comes only from the session
Given a server with no statements folder (the hosted one) When bank_statement_files is called Then it says "This server has no statements folder: attach the statement CSV in the chat."
Given a statement-file account and none of statementFiles, statementCsv or checkId When bank_reconciliation_check, bank_entries_preview or vat_prepare_return runs Then the refusal (or the "not checked" reason) says to call bank_statement_files first, or to attach the CSV
Given the owner has not attached a statement When the reconcile-account, month-end-check or vat-ready prompt reaches a statement-file account Then Claude calls bank_statement_files for the period and passes the files that cover it as statementFiles And only if none cover it does it ask the owner to attach the CSV or save it into the statements folder of the server And attached text is still passed exactly as attached, and its checkId used (S39), never re-typed
As built (2026-10-06): the tool is read-only and reads no bank or Xero data. Files that are not .csv, hidden files, symbolic links, folders and files over 5 MB are not read (a file over 5 MB is listed as "could not be read"). A file whose dates sit inside another's is left out of coversPeriod.files, and the reader measures gaps the same way.
Security review of PR #196 (2026-10-06): the statements folder is shared by every company and account on the server, and coversPeriod picks files by date alone, so another company's statement could be entered into this company's Xero on one Approve. So, conservatively and without reorganising the folder:
bank_statement_filesalways says the folder is shared by every account and company on the server, and names the files it would use.- The prompts show the owner the chosen files with their dates and ask them to confirm these are this company's statements for this account before any check is called with them.
- A check, preview or VAT draft read from statement files shows the same "Statements received" table as one read from text (file name, lines, dates, charges and payments), with the shared-folder warning, so the card always carries it. Per-company (or per-account) subfolders could replace the confirmation later; that needs its own decision.
S42: A VAT claim with no receipt waits for its receipt (approved 2026-10-06, revised the same day by the Product Owner; revised again 2026-10-06 by the Product Owner: reverse charge is held back too)
Given bank_entries_preview entries, one coded to a rate that reclaims VAT (for example INPUT2, or a reverse charge, REVERSECHARGES) with no receipt fileId When the preview is made Then that entry is not entered: it is left out of the card, under "Not entered: VAT claimed but no receipt", with its date, contact, amount and the VAT it claims in Box 4 And a reverse charge says that, once entered, its VAT goes in Box 1 and is reclaimed in Box 4, and the reclaim needs the supplier's invoice And the card says what to do: attach its receipt (fileId) and preview again, or code it No VAT; for a reverse charge, only find its invoice (the supplier's billing page) and attach it, never No VAT And the entries that reclaim no VAT (No VAT, exempt, zero-rated, a director's loan, a transfer), and those that reclaim VAT with a fileId, go ahead in the card as normal And if every entry is held back, nothing is previewed and the reply says why And the VAT figures, and their total, come from code
Product Owner, 2026-10-06: "if it needs to reclaim VAT and doesn't have invoices or receipts, it says that clearly and doesn't match them, but matches ones without VAT." This replaced the first wording, a warning that never blocked.
Product Owner, revised again 2026-10-06, after a test in Claude Desktop where reverse charge lines (Anthropic, Notion, Polar, Google) were entered with no invoices and none was looked for: "I thought you needed an invoice to reverse charge" / "we must fix it in the tool". The reclaim half (Box 4) of a reverse charge needs the supplier's invoice as evidence; without it HMRC can refuse Box 4 but keep Box 1. So a reverse charge is held back like any other VAT claim, and the tools tell Claude to look for every invoice before the card.
As built (2026-10-06): whether an entry reclaims VAT, and how much, comes from SPEC-001's VAT return mapping (boxFigures, in src/vat/vat-without-receipt.ts): a spend money with any Box 4 figure is held back, with its Box 4 as the VAT it claims (one sixth of the bank amount at 20%, rounded to the penny; for a reverse charge, 20% of the bank amount), even when Box 1 offsets it. Money in is never held back. A reverse charge (REVERSECHARGES) puts the same self-charged VAT in Box 1 and Box 4: since the revision again on 2026-10-06 it is held back too, in the same list and total, its line marked reverseCharge: true, and the card and the reply add "Reverse charge: once entered, the VAT goes in Box 1 and is reclaimed in Box 4. The reclaim needs the supplier's invoice." A held reverse charge is never offered No VAT (review of PR #200): coding an overseas supplier No VAT would wrongly drop the Box 1 self-charge. Its only next step, in the card ("What to do for a reverse charge: find its invoice (usually the supplier's billing page), attach it (fileId) and preview again."), in its own next in waitingForReceipt, and in the reply's and the prompts' instructions to Claude, is to find its invoice and attach it; No VAT is offered only for the other lines. The old warning that let a reverse charge through with no invoice is gone. It fails closed (review of PR #199): a spend at a rate the mapping cannot place (a 5% rate, a custom rate, a sales rate) cannot be checked for VAT, so it is held back too unless it carries a receipt, shown with "can't be checked" in place of a figure and "This tax rate can't be checked for VAT, so it needs its receipt or a rate GetMy Books can place." Only No VAT, zero-rated and exempt purchase rates are known to reclaim nothing. The held-back lines are worked out from the plan before the card is saved, so Approve re-checks only what the card showed, as before. The reply's JSON lists them in waitingForReceipt, telling Claude to look for their receipts with receipts_reconcile, then in the owner's email as the chase-missing-receipts flow does (asking before forwarding anything), and to tell the owner plainly which lines are waiting for an invoice and where to get each one not found (usually the supplier's billing page). The server instructions, bank_entries_preview's description (RECEIPTS_BEFORE_ENTRIES; the checks point to it, SPEC-011 S2), receipts_reconcile's description and the prompts say the same before any card is prepared: every line that reclaims VAT, a reverse charge included, needs its invoice before it can be entered. At Approve (review of PR #199), each entry that claims VAT (a reverse charge included) has its receipt checked again before the entry is made; one whose receipt can no longer be attached (attached elsewhere since the preview, say) is not entered, and is named, while the others go ahead. A file taken in the moment between that check and the attach leaves the entry made, its attach refused and named (S34). And a receipt on an entry that claims VAT (a reverse charge included) is checked against its payment as receipts_reconcile pairs them (the amount exactly, the date within 5 days, the supplier by name), from the receipt's amount, date and supplier given with the entry (receipt, search terms only): one that does not fit, or given with none of them, carries the card warning "this receipt may not match this payment". It never blocks.
S43: Statement files are confirmed and receipts looked for, however the owner asks (approved 2026-10-06)
Given the owner asks to reconcile an account in their own words, without the reconcile-account prompt When Claude reads statement files from the server's folder Then it first shows the owner the file names and their dates and asks them to confirm they are this company's statements for this account And before entering lines that reclaim VAT, it looks for their receipts (the chase-missing-receipts flow) and attaches any it finds in the same card And these steps are required by the tools' own descriptions and the server instructions, not only by the prompt
Amended 2026-10-06 (SPEC-011 S2, approved by the Product Owner, pre-sale review, track C): each rule is said in full once in the server instructions and once in the tool it governs, and every other tool points to it in one line. The "As built" text below is as amended.
As built (2026-10-06, amended by SPEC-011 S2): the server instructions, in their own paragraph for reconciling an account however the owner asks, carry two rules in full: show the owner the statement files and their dates and get their confirmation before passing them (also in full in bank_statement_files' description; every other tool that takes statementFiles points to it in one line); and before previewing lines that reclaim VAT (also in full in bank_entries_preview's description; bank_reconciliation_check and bank_outstanding point to it in one line), run receipts_reconcile with the same checkId or statementFiles, put each receipt's fileId on its entry, chase the rest as chase-missing-receipts does (asking before forwarding anything), and tell the owner plainly which lines are waiting for a receipt (S42). As a guard, every tool that takes statementFiles (bank_reconciliation_check, bank_outstanding, bank_explain_line, bank_entries_preview, receipts_reconcile, vat_prepare_return and vat_corrections_preview) refuses them unless filesConfirmedByOwner is true, listing each file with its line count and first and last dates (read by code, or "could not be read", or "not in the statements folder") and asking for the owner's confirmation; the company is checked first. The flag is the model's word that the owner confirmed, not proof: it makes the step explicit, and the card still shows the files read (S41). The month-end, vat-ready, reconcile-receipts and reconcile-account prompts pass the flag only after the owner confirms, and month-end and vat-ready now look for receipts before entering lines that reclaim VAT.
S44: No duplicate preview while one is open (approved 2026-10-06)
Given an open (live, undecided) bank entries preview for the same person, company, account and bank lines When bank_entries_preview is called again for any of those same bank lines Then it is refused, naming the open preview and when it expires, and saying to approve or decline that card first And a preview for different lines is not affected
As built (2026-10-06): openBankEntriesPreview (src/banks/write-preview.ts) reads, before the new preview is saved, this person's bank entries previews for the same company and bank account that are live: not expired, and not approved, declined or claimed. One whose request holds any of the same bank line IDs refuses the call, naming its ID, the lines it shares and its expiry in London time; nothing is stored. An expired, declined or written preview, another person's, another account's, or a VAT correction or attachment preview never blocks. It is a read, not a lock: two previews made at the same moment can both be saved. That is accepted, because only the owner's Approve writes, and every Approve re-runs the check first and refuses a line Xero has by then, so the second card cannot enter a line the first one entered.
S45: The bank's reference is made safe before it is sent to Xero (approved 2026-10-06 by the Product Owner, pre-sale review)
Given a bank line whose reference starts with = + - or @, holds control characters, or is longer than 255 characters When it is planned as a spend, receive or transfer entry Then control characters in its reference become spaces And it is cut to 255 characters by whole character, so no character is split in two, and trimmed And it is otherwise sent as the bank wrote it: a leading = + - or @ is not escaped
As decided in review of PR #202: the reference mirrors the bank line, because Xero's bank rules and search use it, and the same text already reaches Xero through its own bank feed, so escaping it here would protect nothing. The contact and description are still escaped.
S46: A receipt amount that is not in pounds is refused before anything is saved (approved 2026-10-06 by the Product Owner, pre-sale review)
Given a bank_entries_preview entry whose receipt amount is not pounds and pence (e.g. "forty two") When bank_entries_preview is called Then it is refused, saying the amount is not an amount and to use pounds and pence, e.g. 42.50 And no preview is saved, so the same bank lines can be previewed again at once (S44)
S47: An account name with spaces around it is found for receipts too (approved 2026-10-06 by the Product Owner, pre-sale review)
Given the owner names the bank account with spaces around it, e.g. " Starling " When receipts_reconcile is called for that account Then the account is found, as it is when deciding whether to read its bank lines And the receipts are checked against it, not refused for an unknown account
S48: Explaining a line agrees with the check (approved 2026-10-06 by the Product Owner, pre-sale review)
Given a bank line the check shows as a near match, or as a move between the owner's own Starling spaces When bank_explain_line is called for it Then it gives the same class as the check: a near match with the Xero records it was found in, or a move between spaces that is not checked against Xero And it never says the line is missing from Xero, or that there is no such settled line
S49: A deploy lets an Approve in progress finish (approved 2026-10-06 by the Product Owner, pre-sale review)
Given the owner pressed Approve and the write to Xero is in progress When the app is told to stop (a deploy or restart sends SIGTERM, or SIGINT) Then it takes no new requests, stops the statement-preview sweep, and lets the requests in progress finish, so the write's audit row is recorded And a client's open event stream (a GET on /mcp) is not waited for: it is ended once no other request is running And repeating the signal while it stops changes nothing And it then closes its database connections and exits cleanly And if the requests in progress have not finished within 25 seconds, it exits with a failure And the container gives the app longer than that to stop before it is killed
Placed in this spec because no platform spec exists: the harm is an Approve (S38) written to Xero with no audit row.
S50: A refused sign-in is logged without the person's email (approved 2026-10-06 by the Product Owner, pre-sale review)
Given a person Cloudflare Access signed in but GetMy Books does not know When their request is refused Then the log line says a signed-in person with no access was refused And it holds no email address or other personal data (ADR 0026)
Placed in this spec because no platform spec exists.
S51: Pounds are written from whole pence only (approved 2026-10-06 by the Product Owner, pre-sale review)
Given an amount that is not a whole number of pence When it would be written as pounds in a sentence (for example "£12.34") Then it is refused with an error, never written as "£12.34.5"
A malformed amount (NaN) now fails the reply with that error too, instead of printing "£NaN".
Placed in this spec because the reconciliation summary is its main user; the VAT readiness and correction wording (SPEC-001) use the same function.
S52: A logged error keeps its kind (approved 2026-10-06 by the Product Owner, pre-sale review)
Given an error is logged When the log line is written Then it holds the error's name (for example "TypeError") as well as its message And nothing else from the error, so no statement text or credentials reach the log
Placed in this spec because no platform spec exists.
S70: Every flagged line on a record is corrected (approved 2026-10-06 by the Product Owner, pre-sale review)
Given a spend money with more than one line the check flags as a VAT under- or over-claim When vat_corrections_preview is called for the record with a rate that fixes each kind of error it has Then the journal reverses and re-posts every flagged line on it, each on its own account for its own gross And a record with both an under- and an over-claim is named once per kind, with a rate for each And if any flagged line on the record is left out, nothing is posted and the record is named, since a corrected record is never flagged again
As built (2026-10-06, review of PR #204): one request applies one rate to every flagged line of its kind on the record; lines of the same kind cannot take different rates in one journal. Each line is a correction of its own, logged under the record's key (":line<n>" after the first), and a record's rows are logged together in one savepoint, all or none, so a partly logged record never undercounts HMRC's limit for the return. A rate that fixes no flagged line on the record is refused with the rates that would, even when given twice.
S71: A reconciled line with money and no tax type is flagged (approved 2026-10-06 by the Product Owner, pre-sale review)
Given a reconciled Xero line on a VAT-bearing account with money in it and no tax type When the check runs Then the line is flagged, as SPEC-001 blocks the return on it And a reconciled line with no tax type and no money is not flagged, as SPEC-001 lets it through And a coding suggestion with no tax type is marked as blocking the VAT return
As built (2026-10-06, review of PR #204): a reconciled line is checked with its own money, its amount from Xero or, on a single-line record, the record's total; with neither it counts as having money. A coding suggestion has no amount, so it is checked as a line with money in it (a 1p probe).
S72: VAT inside a 20% amount is worked out as Xero does (approved 2026-10-06 by the Product Owner, pre-sale review; corrected the same day from Xero itself)
Given a VAT-inclusive amount at 20%, such as £1.29 on a flagged purchase or a correction When the VAT inside it is worked out, for a flag, a correction journal or the VAT the record should hold Then it is a sixth of the gross with a half penny rounded up, as Xero works it out per line: 22p on £1.29 and 21p on £1.23 And a refund (a negative amount) gives the same VAT, negative: -22p on -£1.29
As built (2026-10-06): one helper, vatInsideStandard in src/vat/vat-inside.ts, in integer pence, is used by the box effect, the under- and over-claim checks and the correction planner. The first version took the gross less its rounded net (21p on £1.29), from a reading of Xero's developer guide. The Product Owner then entered tax-inclusive bill lines at 20% (VAT on Expenses) in Xero: £1.23 showed 21p and £1.29 showed 22p, which only a sixth of the gross rounded half up gives. The helper now does that, keeping the one change that was right: a refund rounds the same way as a payment.
S53: A list Xero does not page still ends (approved 2026-10-06 by the Product Owner, pre-sale review)
Given Xero answers every page of a list (batch payments, say) with the same full page, because it does not page that list When the check reads that list Then reading stops at the first page that repeats one already read, and each record is counted once And a list with more than 500 full pages is stopped with an error naming the list ("Xero gave more than 500 pages of …"), never read for ever; exactly 500 are read in full And the same holds for every paged Xero list, the VAT return's invoice and credit note lists included (review of PR #205)
S54: Payments and batches not in pounds are refused (approved 2026-10-06 by the Product Owner, pre-sale review)
Given a linked bank account that Xero's chart of accounts gives in a currency other than GBP, with only invoice payments or batch payments on it in the period When the check reads it Then it is refused, naming the account and its currency, as spend and receive money in another currency are (ADR 0025) And no figure in another currency is read as pence
Payments and batches carry no field for the bank account's currency (ADR 0025), so the account's own currency, from the chart the check already reads, is what is checked: no extra Xero call. The linked account is found by its ID, letter case aside; one the chart does not list is refused, never assumed to be in pounds (review of PR #205).
S55: Starling's rate limit never holds a call for long, and its IDs are sent safely (superseded by ADR 0035: no Starling call exists; approved 2026-10-06 by the Product Owner, pre-sale review)
Given Starling answers 429 with a Retry-After longer than a minute When the statement is read Then each wait is at most 60 seconds, and the retries stay bounded as before And a Retry-After of 0, or one that is not a number, uses the usual backoff, as for Xero (review of PR #205) And the account and category IDs are encoded in the request path, so an ID holding "/" cannot change which address is read
S56: A transfer to an account not in pounds is refused (approved 2026-10-06 by the Product Owner, pre-sale review; review of PR #205)
Given a bank line the owner asks to enter as a transfer to another Xero bank account When that account's currency in Xero's chart of accounts is set and is not GBP Then the transfer is refused, naming the account and its currency, as in S54 (ADR 0025) And nothing is entered for that line
S60: Dates are written as the owner reads them (approved 2026-10-06 by the Product Owner, pre-sale review)
Given any reply, refusal or journal line that names a date: a posted correction journal, a record entered in Xero since a preview, a transfer already on its other account, a line to press OK or a near match in Xero, a named correction refused for its date, a correction journal's line descriptions, a correction changed since its preview, or a Xero lock date When it is shown to the owner or written to Xero Then the date reads like "19 Sep 2026", never "2026-09-19" And a line to press OK with no Xero record to hand names no date at all, rather than an empty one
S61: The posted journal says what was already corrected, as the preview did (approved 2026-10-06 by the Product Owner, pre-sale review)
Given a VAT correction preview that said what earlier GetMy Books journals already corrected for the same VAT return When the owner approves it and the journal is posted Then the reply also says what was already corrected for that return, in the same words as the preview
S62: A supplier answer needs a supplier name (approved 2026-10-06 by the Product Owner, pre-sale review)
Given the owner's VAT answer for a supplier whose name is blank or only spaces When vat_remember_treatment is called with it Then it is refused and nothing is saved
S63: A flagged record is found whatever the case of its id (approved 2026-10-06 by the Product Owner, pre-sale review)
Given a flagged under- or over-claim whose Xero id is given in capitals in corrections When vat_corrections_preview runs Then it is corrected as the same record, as a record named in namedCorrections already is
S64: A preview made before an update says it is out of date (approved 2026-10-06 by the Product Owner, pre-sale review)
Given a VAT correction preview stored before an update changed how its journal is written (such as its dates), with no record changed in Xero When the owner presses Approve Then nothing is posted, and the reply says "This preview is out of date: make a new preview."
S73: Insurance and other costs that carry no VAT are never entered with VAT (approved 2026-10-06 by the Product Owner)
Given a bank_entries_preview entry coded to a rate that reclaims VAT (any Box 4 figure, or a rate that cannot be placed), whose contact, bank counterparty, description, reference or account name says it is insurance (an insurer, insurance premium tax, premium finance), bank charges, interest, pay, a pension, a dividend or corporation tax When the preview is made Then that entry is not entered: it is left out of the card, under "Not entered: this looks like insurance, which carries no VAT" (or the cost it looks like), with its date, contact, amount, the VAT it would claim in Box 4 and what was matched And the card says what to do: code it No VAT or exempt and preview again, or, only if the owner says this payment truly carries VAT, preview it again with vatConfirmedByOwner on that entry And a receipt does not let it in, and it is not also listed as waiting for a receipt (S42) And an entry with vatConfirmedByOwner goes ahead (still needing its receipt, S42), with a card warning that the owner confirmed it carries VAT And "Premium" alone (Spotify Premium, a Xero premium plan), "Policy Exchange" or "Direct Line Telecom" is not insurance And the check's possible over-claims flag an existing Xero spend money at 20% whose contact or reference says it carries no VAT, not only by its account name, with the VAT at stake and what was matched And the server instructions and bank_entries_preview's description say that insurance, bank charges, interest and pay never carry VAT, and that Insurance Premium Tax on an insurance document is not VAT (amended by SPEC-011 S2: the checks point to bank_entries_preview in one line)
Product Owner, 2026-10-06: an insurance premium was entered at 20% through the MCP, coded to an account whose name did not say insurance, and S42 let it through because the insurance schedule counted as a receipt. UK insurance is exempt from VAT; Insurance Premium Tax is charged instead and is not reclaimable.
As built (2026-10-06, narrowed in review of PR #208): the words are matched by code (noVatNature, in src/vat/vat-nature.ts), whole words only and Unicode-safe, so "Pinterest" is not interest and "Receipt" is not IPT, from the contact, the bank's counterparty (read in memory only: for a statement-file account it is statement text, ADR 0032), the description and the reference, each read to its first 200 characters. Insurance: insurance, insurer, IPT, life assurance, assurance company or society, premium credit, premium finance, close brothers premium, and UK insurers by name (Aviva, Hiscox, Simply Business, AXA, Allianz, NFU Mutual, QBE, LV= or Liverpool Victoria, Policy Expert, Royal London, Scottish Widows, Standard Life, Legal & General, Prudential, Bupa, Ageas, Hastings Direct, Markerstudy, Towergate, Howden, Gallagher, Beazley, Chubb, Vitality, Cuvva, Superscript, Paymentshield, RSA Insurance, Lloyd's of London or underwriters). Direct Line counts only with insurance, group or (for) business after it, or as the whole name; Zurich, Admiral and Churchill only as the whole name, give or take a company suffix or the bank's noise (DD, payment, ref, digits): each is also a hotel, a pub, a place or a phone line. A bare "policy", "assurance" or "underwriting" is not insurance ("Policy Exchange", an audit and assurance firm). Pay is salary, salaries, wages, remuneration and national insurance; payroll is not, since a payroll bureau charges VAT. A pension is a pension contribution, scheme, payment or fund, in a description or reference only, never from a name ("Pension Advice Ltd" charges VAT). Interest is "interest charged, paid, received, charges or payments", or a text that is only "Interest" ("Special interest group" is not). The account name is read as before (neverCarriesVat). The VAT figure is the entry's Box 4 by SPEC-001's mapping, as S42; it fails closed: one at a rate the mapping cannot place is held back here too, with "can't be checked" in place of a figure. The flag is the model's word that the owner said so, never Claude's own judgement, as filesConfirmedByOwner is; an entry it lets through shows "(owner confirmed VAT)" on its row and a warning. The over-claim check reads a record's contact and reference (Xero gives no line description there); the owner's remembered treatment still clears a flag (S18), and the correction rates stay No VAT or exempt. The other way round, a spend coded No VAT whose contact or reference names an insurer or premium finance is not flagged as a possible under-claim, whatever its account. An insurer whose name is also a surname or another business (Gallagher, Howden, Chubb, Vitality, Prudential, Bupa, Ageas, Marsh, Beazley, Towergate) clears one only with an insurance word after it (insurance, ins, insurers, group, health, life, brokers, assurance) or as the whole name with the bank's noise, so "Gallagher Plumbing" or "Vitality Gym" coded No VAT is still flagged; at the preview the name alone still holds an entry back, which the owner can override. A bare word ("insurance", "pension", "interest", "salary") never clears one, since the account name already covers accounts that carry no VAT. A preview's "normally standard-rated" warning on a No VAT coding is left off when the contact or the bank's counterparty says the cost carries no VAT, never from a description Claude wrote.
S74: A near match goes to the closest bank line, whatever the statement order (approved 2026-10-07 by the Product Owner, #203)
Given two bank lines of £42.00 out, on 20 and 24 March, still missing after exact matching, and one leftover Xero record of £42.00 out on 23 March When the check runs, with the lines in either order Then the 24 March line (1 day away) is a near match to that record and the 20 March line (3 days away) is missing And the result is the same whichever line comes first
Given two bank lines of £42.00 out, on 21 and 25 March, and one leftover Xero record of £42.00 out on 23 March When the check runs Then neither line takes the record: both are ambiguous, each with that record as its candidate, and the record is not listed as only in Xero
Given a single bank line of £42.00 out on 20 March and one leftover Xero record of £42.00 out on 23 March When the check runs Then the line is a near match to that record, as before
Product Owner, 2026-10-07 (#203): the near-match pass gave a single same-amount record to whichever line came first in statement order, so the closer line could be reported missing. Among the lines that would near-match the same record, the line strictly closest in date wins it; equally close lines are all ambiguous. Split matches (split_in_xero) are unchanged.
S75: Owner-facing text reads plainly (approved 2026-10-07 by the Product Owner)
Given a VAT correction journal dated 2026-07-20 for a purchase dated 2026-07-14, or dated in the future When the plan is made Then the narration and the future-date refusal show dates as "14 Jul 2026", never as raw ISO dates And a not-an-error record id is saved in lower case, as a correction's record id is And a past coding with no tax type reads "account 463 (no tax type)", never "account 463, ." (Previews stored before this change re-plan to different narration; the "This preview is out of date: make a new preview." refusal covers them.)
S76: A line entered again after its record was deleted in Xero is really entered (2026-11-02, #297)
Given a bank line entered from one approved card, whose record the owner then deleted in Xero When a new preview for the same line, with the same entry, is approved Then the write carries an Idempotency-Key of its own, made from the new preview's id, so Xero creates a new record rather than replaying the deleted one and reporting it as created And a retry of the write within one Approve still carries the same key, so Xero creates it once
S77: A line and a Xero record of the same amount dated 4 to 10 days apart are a possible match, never entered (QD-24 decided 2026-09-30; written 2026-11-02, #45)
Given an Amex statement line of £439.16 out on 12 March, still missing after exact and near matching, and a leftover Xero record of £439.16 out on 20 March (8 days apart) When the check runs Then the line is possible_match with that record listed under possibleMatch.records, not unreconciled_no_record And the record is not listed as only in Xero And the summary counts it under "Possible match: check it in Xero", not under missing from Xero, and lists it as a "Possible match: check it in Xero" action naming the record and its date And bank_outstanding counts it per month under the same heading And a VAT return draft stays provisional while it is still to check ("1 possible match to check in Xero", SPEC-001 S11)
Given the same pair When bank_entries_preview is asked to enter that line Then it refuses the whole call, naming the Xero record (its number or reference, else its id; its date; its contact) as a possible match to check in Xero, and nothing is previewed And it is refused every time until the owner has checked it: GetMy Books never enters a possible match on a guess. If the owner finds in Xero that it is a different payment, they say so by naming each record they checked, and the line can then be previewed (S79); the refusal says so. (Until 2026-11-04 the owner entered such a line by hand in Xero; issue #328.) And a line kept from statement text whose possible match was entered in Xero since the preview is named and not entered at Approve, as a record that matched it would be (S36)
Given two leftover Xero records of £439.16 out, on 16 March and 20 March, within 10 days of the 12 March line When the check runs Then both are listed under possibleMatch.records, closest first, and neither is chosen
Given a leftover Xero record of £439.16 out on 23 March (11 days apart) When the check runs Then the line is unreconciled_no_record and the record is only in Xero, as before
Given the last line of March, £439.16 out on 31 March, and its Xero record on 8 April When the check for March runs Then Xero is read 10 days either side of the period, so the record is found and the line is possible_match; the record, outside the period, is never only in Xero And a statement-text preview remembers the Xero records within 10 days of its lines, so one entered since is found at Approve
And the matching windows (QD-09, QD-13, QD-15) and the 3-day near match (S74 included) are unchanged, and their tests still assert no exact or near match. Only the read reaches further, so three existing tests now see a record 4 to 10 days away: 'an invoice payment 6 days away is not a match' (QD-09) and 'near matches never reach across more than 3 days, or pick between two equal options' now also expect possible_match instead of unreconciled_no_record, and the S36 test 'another direction or amount, or a record outside the window, leaves the line missing' moves its out-of-window record from 10 to 20 March so it stays outside both.
Product Owner, 2026-09-30 (QD-24): on FEAW's Amex BA Business card a £439.16 line and its Xero record were dated 8 days apart, so the check reported the line missing and the record Xero-only, and the line could have been entered twice. The windows stay as they are; exact-amount pairs up to 10 days apart are listed as possible matches for the owner to check in Xero, and are never matched or entered by GetMy Books.
S78: A VAT correction's outcome in Xero is reported even when its log row cannot be written (2026-11-04, #297)
Given an approved VAT correction journal that Xero refuses, and the ledger log that cannot be written at that moment When the owner presses Approve Then the outcome says "Nothing corrected:" with Xero's own reason, and says GetMy Books could not log the refusal and why And the log's error never replaces Xero's
Given an approved VAT correction journal that Xero posts, and the ledger log that cannot be written at that moment When the owner presses Approve Then the outcome says the journal was posted, with its Xero id, and lists each record whose log rows could not be written, and why
Codebase review, 2026-10-20 (#297): when Xero refused the journal, a log insert that then failed threw its own error, so the owner saw a database error and never Xero's reason. The journal is now made and logged the way bank entries are (one write, then its log row, whatever happens).
S79: The owner releases a possible match they have checked in Xero (2026-11-04, #328)
Given the 12 March £439.16 line with a possible match, the Xero record SPEND-9 of £439.16 on 20 March (S77), which the owner has checked in Xero and found to be a different payment When bank_entries_preview is asked to enter that line, the entry naming that record's id under possibleMatchCheckedNotThisRecord Then the line is planned as a line missing from Xero, coded as the owner says, and previewed And the approval card shows, for that line, that the owner checked in Xero that SPEND-9 (20 Mar 2026) is a different payment And the activity log keeps, on that line's preview row, the record ids the owner named
Given two possible-match records for one line, x-ba-2 on 16 March and x-ba on 20 March When the entry names only x-ba Then the whole call is refused and nothing is previewed, and the refusal names x-ba-2 as the record left out, to check in Xero too
Given a line with a possible match whose entry names no record When bank_entries_preview is asked to enter it Then it is refused as in S77, naming each record with its id, and the refusal tells the owner that once they have checked each record in Xero and found it is a different payment they can name the records checked and preview again
Given a released line previewed from statement text (or a checkId), and a new Xero record of the same amount entered within 10 days of it after the preview When the owner presses Approve Then that line is named and not entered, as in S36 and S77: the owner's choice covers only the records they named
Given a released line on an account read from the bank, and a new Xero record of the same amount entered 4 to 10 days from it after the preview When the owner presses Approve Then nothing is entered, and the refusal names the new record as one not checked by the owner
A record the owner names that is not a possible match of the line changes nothing: the line is planned or refused as it would be without it.
Product Owner, 2026-11-04 (#328, decided in chat; Decided by: Product Owner): a line that is really missing from Xero, such as one of a run of weekly payments of the same amount, could never be entered through GetMy Books while a record of the same amount sat 4 to 10 days away. The owner may now release it, but only by naming every record listed, after checking each in Xero; a record entered after the preview still stops it at Approve.
Edge cases
- Card payments are dated when made; Xero's feeds date them when they settle. Amex statement lines and Starling card payments match up to 2 days apart (QD-13).
- Dates: Starling timestamps are UTC. Convert to the Europe/London date before matching, so a purchase at 00:30 BST falls on the right day.
- Card payments in foreign currency: match on the GBP amount Starling settled.
- Refunds and reversals: separate items with their own direction.
- Starling Spaces transfers: check whether Xero's feed includes them before build (QD-10). If it does not, exclude them and report them apart.
- Bank transfers between the entity's own accounts: match against Xero bank transfers, not spend or receive money.
- A payment covering several invoices, or a batch payment: one Starling item to many Xero lines is
ambiguousunless the batch total matches exactly. - Period boundaries (Product Owner, 2026-10-20): an item dated in the period whose only Xero record falls outside it but inside the window is not matched. The record may belong to the neighbouring period's bank line, which the check does not read, so the item is
ambiguouswith that record as its candidate, shown for the owner to check, and never entered. This replaces "is still matched".
S80: A write preview and its checkId last 60 minutes (2026-11-17, #433)
Given the owner reading invoices while a write preview waits in the approval card When the preview is made Then it expires 60 minutes after it was made, and the card and the approval page show that time (London time) And a checkId from the check lasts 60 minutes too, from the same named constant, so its lines outlive any preview made from them And at Approve, on the card or the approval page, an expired preview is refused as before, saying previews last 60 minutes, and nothing is written And a preview made from statement text still has its lines and summary cleared when it ends (S36)
Changed 2026-11-17 (#433, evidence: the Product Owner's Amex session that day): every card expired in about 15 minutes, while the owner was still reading invoices. The card and the approval page stay the only ways to approve.
Dependencies
- A Starling personal access token for each entity's business account.
- The Xero app scope change and a reconnect.
- The
bank_connectiontable and its row-level security policy.
Exit test
For one recent full month on FEAW's Starling account, and for one Amex statement period on FEAW's Amex BA Business card, the items classified as unreconciled equal the lines open in Xero's Reconcile tab, one for one, and the totals check passes. The Product Owner runs it on real data.
Validation
| id | name | rule | assert |
|---|---|---|---|
| V1 | Same-day window | Card and bank payments match only on the same Europe/London date | S1, S4 |
| V2 | Invoice payment window | Invoice payments match within 5 days | S2 |
| V3 | Xero complete | Xero records read for the period move exactly what Xero's Bank Summary says, in pence | S6 |
| V4 | Unpaid duplicates shown, never chosen | An unpaid bill that equals, adds up to, or (less a credit) makes up a matched spend is listed for the owner; the check picks no record and writes nothing | S29 |