Appearance
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
- 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.
- SPEC-007 (HMRC connection) must exist: the connection that filing would use, and its
write:vatscope. - 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)
S4: A link works once
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
| id | name | rule | assert |
|---|---|---|---|
| V1 | No tool submits | No MCP tool name contains "submit" or "approve" | S1 |
| V2 | One caller | The HMRC submit function is called only from src/approvals/ | S2 |
| V3 | Approval is bound | A change after approval is refused | S3 |