Appearance
SPEC-010: Activity log
Amended 2026-10-06 by SPEC-011 S4 (approved by the Product Owner, pre-sale review, track C): the
*_confirmtools are removed. The owner's Approve in the approval card makes every write (SPEC-003 S38), andwrite_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
On 2026-10-06 an entry that Claude prepared coded an insurance premium at 20% VAT. Insurance is exempt, so the VAT reclaimed was wrong. Nobody could see when the entry was made, what Claude proposed, why, or who approved it: write_preview keeps only the live preview, and ledger_write keeps only what was written. The Product Owner wants a log so mistakes like that can be traced: when it happened and how. Supports SM-3 (every VAT figure traced to its source).
User story
When a figure in Xero looks wrong, I want to ask Claude "when did this happen and how?" and see what Claude proposed (account, tax rate, VAT and its reason), who approved or declined it and when, and what Xero then held, so I can fix the cause, not only the entry.
Scope
- What is logged (decisions and writes, never reads). One row each for:
- A write preview (
bank_entries_preview,vat_corrections_preview,attachments_preview): the previewId, the kind of write, who, when, and for each line what Claude proposed: the bank line ID, date, amount in pence, the contact and description as sent to Xero, the account code and name, the tax type, the VAT figure worked out by code, the receipt's fileId (if any) and a short reason. Lines held back for a receipt (SPEC-003 S42) are logged with why. - A decision in the approval card (
write_preview_decide): Approve or Decline, who, when, the previewId, and whether it was recorded. - A write outcome (the card's Approve or a
*_confirmtool): the Xero record IDs created, posted or attached, or why nothing was written.
- A write preview (
- A reason for each proposed line. The three preview tools take an optional
reasonon each entry, correction and link: plain text, at most 200 characters, cleaned of control characters. The tool descriptions ask Claude to give one ("why this account and tax rate"). A named VAT correction's existingreasonis logged as its reason. - A read tool,
activity_log(read-only): one company's log, newest first, 50 rows a page, with an optional date range, search text and kind. It leads with a plain-English summary built by code, one block per preview: what was proposed, who decided and when, and what Xero now holds. - Visibility. Everyone with access to a company sees that company's whole log, each row naming who acted. Nobody on another company sees any of it. The entity comes only from the session (CLAUDE.md rule 4).
Out of scope
- Logging reads (checks, lists, explanations).
- Deleting old rows. Retention is proposed as 6 years (ADR 0033); the scheduled delete is a later decision.
- Changing or removing a row: the log is append-only.
- Showing the log anywhere but through Claude (
docs/not-doing.md: no dashboard of our own).
MCP tools sketch
| Tool | Returns |
|---|---|
activity_log | For one entity: rows newest first (50 a page), each with when, who, kind, previewId and detail, and a summary grouped by preview. Read-only |
Scenarios
S1: A preview is logged with what Claude proposed and why
Given the owner asks Claude to enter a missing Starling line When Claude calls bank_entries_preview with an entry coded 433 at INPUT2 and the reason "past coding" Then the activity log has a preview row with the previewId, who, when, and the line's bank line ID, date, amount in pence, contact as sent to Xero, the description if Claude gave one (else a marker that it defaults to the bank line), account 433 and its name, tax type INPUT2, the VAT worked out by code, and the reason "past coding" And the preview's reply and approval card are exactly as before
S2: Lines held back are logged with why
Given a preview where one spend reclaims VAT with no receipt (SPEC-003 S42) When the preview is made for the other lines Then the preview row lists the held-back line with its tax type, its VAT, and why it was held back And a line left out because its receipt cannot be attached is listed with a fixed reason code and the file ID
S3: Approve and Decline are logged
Given a preview shown in the approval card When the owner presses Approve, or Decline Then the activity log has a row naming who decided, when, the previewId and the decision
S4: The write outcome is logged
Given an approved preview When its write is made, by the card's Approve or by its confirm tool Then the activity log has an outcome row with the Xero record IDs created, posted or attached, each created entry's description as written, and each failure's reason And when nothing is written, the row says why And a failure that could name a file is a fixed code with the file ID, never the file's name
S5: A log failure never changes the money path
Given the activity log cannot be written (the database refuses the row) When a preview, a decision or a write happens Or the insert never finishes, or building the row's detail throws Then the preview, the decision and the write behave and reply exactly as they do with the log working, without waiting for the log And the failure is logged to the server log with no content, only that it failed
S6: No statement text is stored
Given an account read from statement text or statement files (ADR 0032) When its lines are previewed, approved and written Then the activity log holds only what Xero is sent (contact, description, account, tax type, amount, date) and never the statement's own text And a description that defaults to the statement's text is not stored at preview, nor after a decline or expiry And a bank line ID built from a statement row's text is stored only as a keyed hash (ADR 0033)
S7: Each company sees its own whole log, and nobody else's
Given Fraser and Rob both have access to FEAW, and a stranger has access only to WealthTechPros When Rob reads FEAW's activity log Then he sees Fraser's previews and decisions as well as his own, each naming who acted And the stranger cannot read or add a row for FEAW, even with FEAW's entity set by mistake And nobody can change or delete a row
S8: The log is read newest first, with a summary from code
Given a company with logged previews, decisions and outcomes When Claude calls activity_log with an optional date range, search text or kind Then the rows come back newest first, 50 a page, with a cursor for older rows when there are more And a page read with a cursor says a preview's later rows may be on the newer page And the reply leads with a summary built by code, such as "6 Oct 2026 14:02: Fraser previewed 1 entry: Premium Credit £120.00 to 433 Insurance at 20% (VAT £20.00), reason: 'past coding'. Approved by Fraser at 14:03. Xero: spend money created." And search matches only the contact, description, account, tax type or a record ID
Exit test
The Product Owner previews, approves and declines real FEAW entries, then asks Claude "when was this entry made and why?" and the activity log answers with what was proposed, the reason, who approved it and the Xero record.