Skip to content

SPEC-004: Deadline radar, HMRC and Companies House obligations, with a heads-up ​

Business intent ​

FEAW was fined because Companies House obligations went overdue without anyone noticing, and on 29 Sep 2026 its confirmation statement was overdue again (due 7 Sep). Xero does not show these deadlines clearly. GetMy Books must know every upcoming filing and payment for each company and tell the owner before it is due, without being asked. Moves SM-1 (late filings or penalties to zero).

User story ​

When I start any conversation with GetMy Books, I want to be told straight away about anything overdue or due soon for my companies, so nothing is missed because nobody looked.

Scope ​

  • Companies House (public data API, read-only, key in Doppler as COMPANIES_HOUSE_API_KEY): annual accounts and confirmation statement, next due date and whether overdue, per company number. FEAW is 10345690, WealthTechPros 14111544.
  • HMRC VAT: each return's due date from the company's VAT quarters (one month and seven days after the quarter ends, payment the same day). FEAW's quarters end in Feb, May, Aug and Nov. Replaced by HMRC's own obligations feed once HMRC is connected (SPEC-001).
  • HMRC Corporation Tax: from the accounting reference date Companies House gives, and from the company's incorporation date and next accounts period when the register gives them (S10 to S12, added 2026-10-30, issue #309): no period ends before the company was incorporated; its first period of account runs from incorporation to the register's next accounts period end when that period starts at incorporation (else to the first reference date more than six and at most eighteen months after incorporation, CA 2006 s391(5)); a first period longer than twelve months is two Corporation Tax accounting periods, the first twelve months then the rest; later periods are the years to the reference date. For each accounting period: payment nine months and one day after it ends (the 1st of the tenth month when it ends on a month's last day, S9; TMA 1970 s59D). The CT600 return is due twelve months after the period of account ends (FA 1998 Sch 18 para 14), so both accounting periods of a long first period share one filing date. Trading from incorporation is assumed: GetMy Books cannot see when a company started trading, and a dormant company has no accounting period. A full year is labelled "year to <end>"; a first or short period "period <start> to <end>". Without an incorporation date the periods are the years to the reference date, as before.
  • HMRC PAYE (companies that run payroll: FEAW, QD-17 (b)): the PAYE and National Insurance payment on the 22nd of each next tax month (tax months end on the 5th), or on 22 Jul, 22 Oct, 22 Jan and 22 Apr for a company that pays quarterly; P60s to employees by 31 May; P11D, P11D(b) and employee copies by 6 July; Class 1A National Insurance by 22 July (issue #92). Monthly payments are listed from two months back, not thirteen.
  • Heads-up: a deadlines_upcoming MCP tool, and the MCP server's instructions tell the client to call it at the start of every conversation and lead the first reply with anything overdue or due within 30 days.
  • Each obligation shows the company, what it is, the period, the due date, days left (negative when overdue) and where to file it.
  • HMRC dates stay listed for 13 months after they fall due, as "check it was done", because GetMy Books cannot see whether they were met and late-filing penalties escalate at 3, 6 and 12 months. Companies House says itself when a filing is overdue.
  • A short reply, and "done" (added 2026-11-17, issue #408): by default deadlines_upcoming lists the heads-up (every overdue and due-within-30-days item, never capped) and the next three upcoming dates, with one line counting the past HMRC dates still to check. The owner can say a past HMRC filing or payment was made: deadline_mark_done records it in GetMy Books' own records, with who (the signed-in person) and when, and it stops reappearing. A done mark never hides an overdue or due-within-30-days item; it is shown beside it. The full list, done marks included, is given on request.

Out of scope ​

Filing anything (Companies House or HMRC). Email reminders (a later slice, reusing SPEC-001 S6's thresholds). Self Assessment (QD-17 (c), post-MVP). The PAYE Full Payment Submission, due on or before each payday, which GetMy Books does not know; the payment's note names it. Whether a past obligation was actually met: Companies House says when accounts or a statement are overdue, but GetMy Books cannot see whether Corporation Tax was paid until HMRC is connected, so past HMRC dates are shown as "check it was done", never as done, until the owner marks one done (S15). Recording "done" never writes to Xero, HMRC or Companies House and is not a filing (CLAUDE.md rule 5).

Data model sketch ​

Company number and VAT quarter-end months per entity (config first; a table when a third entity arrives). Nothing written back anywhere.

deadline_done (migration 0037, issue #408): one row per HMRC obligation the owner marked done, keyed by company, obligation, period and due date, with who marked it (the signed-in person's email) and when. entity_id under row-level security; deleted with the company.

MCP tools sketch ​

ToolReturns
deadlines_upcomingBy default the heads-up (overdue and due within 30 days), the next three upcoming dates and a count of past HMRC dates still to check; with full: true, every obligation for every entity the owner can see, overdue first, then by due date: company, obligation, period, due date, days left, status (overdue, due soon, upcoming, check it was done), where to file, and who marked it done and when
deadline_mark_doneRecords that the owner says one HMRC obligation was filed or paid, with who and when, in GetMy Books only; undo: true takes back a mark the owner says was wrong

Scenarios ​

S1: Companies House deadlines come from Companies House ​

Given a company number When the deadlines are read Then the accounts and confirmation statement due dates are the ones Companies House gives And an obligation Companies House marks overdue is shown as overdue with its days overdue

S2: VAT return due dates follow the company's VAT quarters ​

Given a company whose VAT quarters end in Feb, May, Aug and Nov When the deadlines are read on 29 Sep 2026 Then the return for the quarter to 31 Aug 2026 is due on 7 Oct 2026, 8 days away

S3: Corporation Tax dates follow the year end ​

Given a company whose accounts run to 31 Aug When the deadlines are read Then Corporation Tax for the year to 31 Aug 2025 was payable by 1 Jun 2026 and its CT600 due by 31 Aug 2026 And past HMRC dates are shown as "check it was done", never as done

S4: The heads-up comes first, unasked ​

Given the MCP server is connected When a conversation starts Then the client is instructed to call deadlines_upcoming before anything else And anything overdue or due within 30 days leads the first reply

S5: A missing key or an unreachable register is said, not hidden ​

Given Companies House cannot be reached or the key is missing When the deadlines are read Then the HMRC dates are still shown And the reply says Companies House dates could not be checked, and why

S6: Companies are isolated ​

Given a session authorised for FEAW only When deadlines are requested Then no WealthTechPros obligations are returned

S7: The confirmation statement names the identity check it needs ​

Given a company with a confirmation statement listed, due or overdue When the deadlines are read Then its entry says every director and person with significant control must have verified their identity with Companies House before it can be filed, that each director gives their personal code in the filing, and that each PSC gives theirs through Companies House's separate PSC service (corrected 2026-10-05 from GOV.UK guidance: https://www.gov.uk/guidance/when-you-need-to-verify-your-identity-for-companies-house) (Companies House refuses the filing otherwise, since 18 Nov 2025; see docs/plans/making-tax-digital.md)

S8: A company that runs payroll gets its PAYE dates ​

Given FEAW runs payroll and pays HMRC monthly When the deadlines are read on 30 Sep 2026 Then the PAYE payment for the tax month to 5 Oct 2026 is due on 22 Oct 2026, 22 days away, and its note names the Full Payment Submission due on or before each payday And the payments due 22 Aug and 22 Sep 2026 are shown as "check it was done", and none from before August And P60s are due by 31 May 2027, P11Ds by 6 Jul 2027 and Class 1A National Insurance by 22 Jul 2027 And WealthTechPros, which has no employees, gets no PAYE dates

S9: A year ending on a month's last day pays Corporation Tax on the 1st (approved 2026-10-06 by the Product Owner, pre-sale review) ​

Given a company whose year ends on the last day of a month, such as 30 Jun 2026 or 29 Feb 2028 When the deadlines are read Then its Corporation Tax payment is due on the 1st of the tenth month after: 1 Apr 2027 and 1 Dec 2028 (TMA 1970 s59D, HMRC CTM01800) And a year ending on any other day still pays nine months and one day after it, such as 28 May 2027 on 29 Feb 2028

S10: No Corporation Tax period ends before the company was incorporated (added 2026-10-30, issue #309) ​

Given a company incorporated on 20 Aug 2026 whose accounting reference date is 31 Aug When the deadlines are read on 30 Oct 2026 Then no Corporation Tax period for the year to 31 Aug 2025 or the year to 31 Aug 2026 is listed And a company whose incorporation date the register does not give keeps the years to its reference date, as before

S11: The first period runs from incorporation to the first accounts date and is split at twelve months (added 2026-10-30, issue #309) ​

Given a company incorporated on 20 Aug 2026 whose first accounts, as the register says, run to 31 Aug 2027 When the deadlines are read on 1 Oct 2027 Then the period 20 Aug 2026 to 19 Aug 2027 pays Corporation Tax by 20 May 2028 (nine months and one day: 19 Aug is not a month end) and its CT600 is due by 31 Aug 2028, twelve months after the period of account ends (FA 1998 Sch 18 para 14) And the period 20 Aug 2027 to 31 Aug 2027 pays by 1 Jun 2028 (the 1st of the tenth month, S9) and its CT600 is due by 31 Aug 2028 too And the year to 31 Aug 2028 follows as a full year And when the register gives no accounts period, the first period ends on the first reference date more than six months after incorporation: 31 Aug 2027, not 31 Aug 2026 (CA 2006 s391(5)) And trading from incorporation is assumed

S12: The register's next accounts period and incorporation date are read and used (added 2026-10-30, issue #309) ​

Given the register gives date_of_creation 2026-08-20, accounts.next_accounts 2026-08-20 to 2027-08-31, accounts due 20 May 2028 and the confirmation statement due 3 Sep 2027 When the deadlines are read on 30 Oct 2026 Then no Corporation Tax dates are listed, because the first ones (20 May 2028) are more than 13 months away And a note says "first Corporation Tax period runs 20 Aug 2026 to 19 Aug 2027; nothing is due in the next 13 months", so an empty list is not read as nothing due And that note is shown under the heading Notes, as information from a check that found nothing due; only a check that failed (S5: an unreachable register, a missing key, no year end, no company profile) is shown under Could not check, and that heading is absent when nothing failed (amended 2026-11-02, issue #317) And the accounts and confirmation statement dates are listed as the register gives them (V1) And accounts.last_accounts.period_end_on is read too, for a company that has filed accounts

S13: Once the first accounts are filed, the register's next accounts period is the current Corporation Tax period of account (added 2026-11-02, issue #316) ​

Given a company incorporated on 15 Jan 2025 whose first accounts ran to 31 Jan 2026 (accounts.last_accounts.period_end_on) and which then moved its reference date to 31 Dec, so the register's accounts.next_accounts runs 1 Feb 2026 to 31 Dec 2026 When the deadlines are read on 30 Oct 2026 Then the register's next accounts period is the current period of account, split at twelve months if longer (CTA 2009 s10): the period 1 Feb 2026 to 31 Dec 2026 pays Corporation Tax by 1 Oct 2027 and its CT600 is due by 31 Dec 2027 And full years to the reference date follow it (the year to 31 Dec 2027) And because the span from incorporation to the last accounts date is eighteen months or less, the company has filed exactly its first accounts, so its first period of account runs from incorporation to that date, split at twelve months: the period 15 Jan 2025 to 14 Jan 2026 pays by 15 Oct 2026 and its CT600 is due by 31 Jan 2027 (twelve months after the period of account ends, S11), and the period 15 Jan 2026 to 31 Jan 2026 pays by 1 Nov 2026 with its CT600 due by 31 Jan 2027 too And no period 15 Jan 2025 to 31 Dec 2025, year to 31 Dec 2025 or year to 31 Dec 2026 is listed: none of them existed And for an older company (incorporated 10 Mar 2015, last accounts to 31 Mar 2026, next accounts 1 Apr 2026 to 31 Mar 2027), whose span from incorporation to its last accounts date is more than eighteen months, nothing is synthesised from incorporation: before the next accounts period only the years ending on the last accounts date and its anniversaries are listed (the year to 31 Mar 2026), then the register's period, then full years after it And when such an older company has changed its reference date since its last accounts (last accounts to 31 Mar 2026, next accounts 1 Apr 2026 to 31 Dec 2026, reference date now 31 Dec), the years before the register's period end on the last accounts date and its anniversaries, not on the new reference date: the year to 31 Mar 2026 pays by 1 Jan 2027 with its CT600 due by 31 Mar 2027, and no year to 31 Dec 2025 or 31 Dec 2024 is listed. Each is taken to be twelve months: the register does not give the length of earlier periods And a register period of exactly twelve months is labelled as a year, "year to 31 Mar 2027", not "period 1 Apr 2026 to 31 Mar 2027" And a company whose first accounts are not yet filed (next_accounts starting at incorporation) keeps S11

S14: The default reply is short, and nothing urgent is hidden (added 2026-11-17, issue #408) ​

Given FEAW with a confirmation statement overdue, a VAT return due in 8 days, 11 past HMRC dates to check and 14 later dates When deadlines_upcoming is called with no options Then the reply lists the overdue confirmation statement, the VAT return and the next three later dates by due date: 5 table rows, under ten And one line says "11 past HMRC dates to check it was done are not listed", and how to see them or mark them done And every overdue or due-within-30-days item is listed, however many there are

S15: A past HMRC date the owner marks done stops reappearing, logged with who and when (added 2026-11-17, issue #408) ​

Given the PAYE payment due 22 Sep 2026 is listed as "check it was done" When the owner says it was paid and deadline_mark_done is called for it, confirmed by the owner Then GetMy Books records it for that company with the signed-in person's email and the time, in its own records only, never Xero, HMRC or Companies House And it is no longer listed or counted by default, and the count line says how many were marked done And marking it again keeps the first who and when And a mark the owner says was made by mistake is taken back (undo), and the date is listed and counted again And a company the session cannot see is refused, an item not in the current list is refused, and a call the owner has not confirmed is refused

S16: A done mark never hides an overdue or due-soon item (added 2026-11-17, issue #408) ​

Given the VAT return due in 8 days was marked done When the deadlines are read Then it is still listed in the heads-up, with "Marked done by <email> on <date>" beside its status And a Companies House obligation cannot be marked done: the register says itself once it is filed

S17: The full list on request (added 2026-11-17, issue #408) ​

When deadlines_upcoming is called with full: true Then every obligation is listed, as before this change, with each one marked done showing who marked it and when

Exit test ​

On a real conversation start, the first reply names FEAW's overdue confirmation statement (or, once filed, shows it as met by Companies House) and FEAW's next VAT return, with dates matching Companies House and HMRC.

Validation ​

idnameruleassert
V1Register dates are the register'sCompanies House due dates are taken from Companies House, never calculated. A filing is overdue if the register says so, or if its due date has passedS1
V2VAT due dateA VAT return and its payment are due on the 7th of the second month after the quarter ends (31 Aug is due 7 Oct, 30 Nov is due 7 Jan)S2
V3Past HMRC dates are never "done" by inferenceA past HMRC date is shown as "check it was done" until HMRC's own data says otherwise or the owner marks it done, which records who and whenS3, S8, S15
V4Dates are London dates"Today" and every due date are Europe/London dates; S2 and S8 use fixed dates, and the London-date rule itself is pinned by tests/rules/london-date.test.ts and the DEADLINES: tests in tests/mcp/deadline-tools.test.tsS2, S8
V5Never hiddenAn unreachable register or missing key is reported with the HMRC dates still shownS5
V6Entity isolationA session sees only the obligations of the companies it can access, and marks done only theirsS6, S15
V7Urgent is never hiddenEvery overdue and due-within-30-days item is in the default reply, done mark or not; the default reply has under ten table rows when at most four items are urgentS14, S16