Skip to content

SPEC-002: VAT filing with approval ​

Status: parked by ADR 0036. GetMy Books does not file with HMRC or Companies House; the owner or their accountant files. This spec is not built while ADR 0036 stands, and filing is on docs/not-doing.md.

Not started, on purpose. This spec records the rules filing must meet and the gates in front of it. It is not yet a build spec: the scenarios below are the constraints already decided elsewhere, and the steps in between wait for the answers named under "Before this can be built".

Business intent ​

Today a VAT return prepared and verified by GetMy Books (SPEC-001) is filed outside it, in Xero or by the accountant (docs/plans/hmrc-connection.md). Filing from GetMy Books would close the loop, and it is also HMRC's route to production credentials for the MTD VAT API (docs/plans/hmrc-connection.md, QD-25 option 2). It is also where liability jumps: a wrong figure here is a wrong filing. So filing only ever happens after the owner's explicit approval, given outside the chat.

User story ​

When a return is prepared and checked, I want to approve it on a web page and have GetMy Books submit exactly that return to HMRC, so that nothing is filed that I have not seen and approved, and nothing I approved is changed.

Rules already decided ​

  • No MCP tool submits or approves (CLAUDE.md rule 5, ADR 0005). Only code under src/approvals/ may call the HMRC submit function, after approval on the web page. A test asserts no MCP tool name contains "submit" or "approve".
  • Approval happens on a web page after fresh sign-in with MFA, through a single-use link that expires in 24 hours (ADR 0005).
  • Bound to a hash of the payload. A draft changed after approval is refused.
  • One submission per entity and period. A timeout is resolved by reading back from HMRC, never by retrying (ADR 0005).
  • Fraud prevention headers describe the person acting (ADR 0006).
  • The entity comes only from the authenticated session (rule 4); money is integer pence from code (rule 3).

Before this can be built ​

  1. QD-25: the route to HMRC production credentials. If HMRC will issue read-only production credentials, filing can wait. If it insists on a live submission, filing comes first, in the sandbox, then one real FEAW return.
  2. SPEC-007 (HMRC connection) must exist: the connection that filing would use, and its write:vat scope.
  3. For anyone outside FEAW and WealthTechPros: the liability, terms and insurance review in ADR 0024 (a solicitor and a broker). Filing is not started for outside customers before it.

Out of scope ​

  • Filing anything other than a VAT return: Corporation Tax and accounts, Companies House filing and Self Assessment are post-MVP in the capability model (CAP-02.4, CAP-02.5, CAP-02.6).
  • Any filing without the web-page approval.
  • Retrying a submission HMRC may already have received.

Scenarios ​

These restate decided rules as acceptance tests. More are added when the build is specified.

S1: No tool can submit or approve ​

Given the list of MCP tools When their names are checked Then none contains "submit" or "approve"

S2: Only the approvals module submits ​

Given the HMRC submit function When the code is searched for callers Then the only caller is under src/approvals/

S3: A changed draft is refused ​

Given a return the owner approved When its figures change before submission Then the submission is refused (ADR 0005)

Given an approval link When it is used a second time, or after 24 hours Then it is refused

S5: One submission per period ​

Given a return already submitted for an entity and period When another submission is attempted Then it is refused

S6: A timeout is read back, not retried ​

Given a submission that timed out When the outcome is unknown Then GetMy Books reads HMRC's record of the period and never submits again

Exit test ​

Not defined until the build is specified. It will be a real FEAW return, in the sandbox first, approved on the web page by the Product Owner.

Validation ​

idnameruleassert
V1No tool submitsNo MCP tool name contains "submit" or "approve"S1
V2One callerThe HMRC submit function is called only from src/approvals/S2
V3Approval is boundA change after approval is refusedS3