Appearance
Standing rules audit
Checked against main at 39b1017 on 2026-09-29; statuses refreshed against main at bcb4620 on 2026-10-02 (#156). Rules come from the Product Owner's standing instructions; where one conflicts with SGE (CLAUDE.md, ADRs, specs), SGE wins and the conflict is noted. No evidence means FAIL.
Severity: H money or security correctness, M robustness, L hygiene. Ask marks a fix that changes product behaviour and needs the Product Owner's go-ahead first (standing rule 5).
Money and data
| # | Rule | Status | Sev | Evidence |
|---|---|---|---|---|
| M1 | Money never a float; integer pence with a currency code | PASS | H | (a) PASS, PR #51: cash-basis scaling runs in whole pence (scalePence, src/shared/money.ts:27; used at src/vat/cash-basis.ts:41-42). Tests tests/shared/money.test.ts, tests/vat/cash-basis.test.ts:50 ("M1: a part payment is scaled in whole pence, never float pounds": 90p x 33/108 = 27.5p rounds to 28p). (b) PASS for every boundary in ADR 0025, PR #65 (Product Owner, 2026-09-29: no Money type): rule src/rules/currency.ts:8; connect refuses a non-GBP organisation scripts/xero-connect.ts:93; bank tools refuse before reading (openReconciliation, src/mcp/reconciliation.ts:97); vat_prepare_return and vat_verify_return block before reading documents src/mcp/vat-tools.ts:82, :154; payments_aged refuses too src/mcp/xero-tools.ts:30; documents need a GBP base currency src/vat/from-xero-documents.ts:86; Xero bank transactions not in GBP stop the read src/xero/bank-records.ts:111; Starling refuses non-GBP src/starling/client.ts:79. Tests: tests/rules/currency.test.ts, tests/vat/from-xero-documents.test.ts:210, tests/xero/bank-records.test.ts:218, tests/mcp/vat-tools.test.ts:236, tests/mcp/bank-tools.test.ts:276, tests/starling/client.test.ts:109; all pass (2026-10-02). (c) PASS, #155 and #161: xero_list_invoices and xero_list_payments return whole pence (poundsToPence, src/xero/client.ts:127-128, :159) with a currency code only when not GBP, refuse a non-GBP organisation before reading any list (requireGbpOrganisation, src/mcp/xero-tools.ts:85, :108), and leave other currencies out of the pounds total (src/present/xero.ts:30-31). Tests: tests/xero/client.test.ts ("maps each invoice to a compact record in whole pence"), tests/mcp/xero-tools.test.ts ("#161, AUDIT M1"), tests/present/xero.test.ts:33. |
| M2 | Reconciliation matching is a pure, fully unit-tested function | PASS | M | Pure: src/rules/bank-reconciliation.ts, import ban on I/O modules for src/rules/** in eslint.config.js:4, :28-30. Tested: PR #52 made pnpm test run vitest run --coverage (package.json:15) with an 80% per-file floor on lines, branches, functions and statements (vitest.config.ts). On main, 2026-10-02: bank-reconciliation.ts 99.43% lines, 91.91% branches; reconciliation-summary.ts 100% lines, 87.87% branches. CI run 605, verify green on bcb4620. |
| M3 | Ambiguous or partial matches flagged, never auto-applied | PASS | H | Ambiguous and near matches are only reported (src/rules/bank-reconciliation.ts classes ambiguous, near_match); planEntries refuses any line not unreconciled_no_record (tests/rules/plan-entries.test.ts "S13: a line that is already matched…"). |
| M4 | Every Xero write: preview, then explicit confirm that takes the preview ID | PASS | H | PR #48: bank_entries_preview and vat_corrections_preview only preview and store the plan in write_preview (src/platform/migrations/0006-write-preview.sql, src/banks/write-preview.ts); bank_entries_confirm and vat_corrections_confirm take only entity and previewId, claim it once within 15 minutes by the same person, re-run the check and write the stored plan (src/mcp/bank-tools.ts, src/mcp/vat-tools.ts). RLS and revoked delete in policies.sql and bootstrap.sql. Tests: tests/mcp/bank-tools.test.ts (M4 tests), tests/banks/write-preview.test.ts (single use under two simultaneous claims, expiry, other person, other company). CI run 110, verify green on 61b39c6. Web release gate unchanged. |
| M5 | Payment writes send an Idempotency-Key | PASS | H | Every Xero write (xeroPut, src/xero/bank-writes.ts) sends Idempotency-Key: a SHA-256 of tenant, path and body, so a retry or a repeated call sends the same key. Test: tests/xero/bank-writes.test.ts "AUDIT M5". |
| M6 | Nothing deleted or voided without confirmation; every write audit-logged (who, what, when, before/after) | PASS | H | No delete or void calls exist. 3f5fda0: ledger_write gains principal_id, before, after (src/platform/migrations/0004-ledger-write-audit.sql); append-only by RLS (src/platform/policies.sql) and revoked update/delete (src/platform/bootstrap.sql). tests/banks/write-change.test.ts and the Postgres tests in tests/banks/write-log.test.ts pass: CI run 99, verify green on 1c31f7e. |
Xero
| # | Rule | Status | Sev | Evidence |
|---|---|---|---|---|
| X1 | OAuth2 with automatic refresh; tokens encrypted at rest, never logged | PASS | H | Refresh: src/xero/session.ts getValidAccessToken, tested in tests/xero/session.test.ts. Encryption: src/platform/crypto.ts, src/xero/entity-token-store.ts. No logging of tokens: grep -rn "console\.|logger\." src is empty. |
| X2 | Least-privilege scopes; xero-tenant-id handled per org | PASS | M | Scopes are read-only except bank transactions, manual journals, files and invoices, which the write tools need (src/xero/session.ts, ADR 0016, 0017, 0031, 0043). The tenant ID is stored per entity and sent on every call (src/xero/http.ts Xero-tenant-id). |
| X3 | 429 backoff honouring Retry-After; concurrency capped | PASS | M | src/xero/http.ts rateLimitWait (Retry-After, daily limit), tests/xero/http.test.ts. Every Xero call is awaited in sequence: no Promise.all in src/xero. The list tools went through their own xeroGet with no 429 handling until #161: src/xero/client.ts now uses the shared one; tests tests/xero/client.test.ts ("a 429 from Xero is retried", "daily limit"). |
| X4 | Pagination on every list call | PASS | M | PR #53: the accrual Invoices and CreditNotes lists (listAll, src/xero/vat-documents.ts:266) and BatchPayments (readAllPages, src/xero/bank-records.ts:92, used at :172) read every page until a short one; tests tests/xero/vat-documents.test.ts:392 and tests/xero/bank-records.test.ts:374 ("AUDIT X4") pass (2026-10-02). Later list reads also page: open documents src/xero/open-documents.ts:51-52, bills src/xero/purchase-records.ts:73. Accounts and TaxRates are not paginated endpoints. The list tools page too (#155): listInvoices and listPayments read one Xero page of 100 per call with Xero's page parameter, newest first, and say whether there may be more, so the owner asks for the next page rather than one call reading thousands of records; tests tests/xero/client.test.ts:50, :128, :184. |
| X5 | Tests use recorded fixtures or mocks, never live client data; manual testing on the Demo Company only | PASS | M | All tests mock fetch (PASS). Merged in #54: FEAW's filed return figures (tests/vat/verify-return.test.ts, and the example in src/mcp/vat-tools.ts), the EE and Premium Credit corrections (tests/vat/vat-corrections.test.ts), the Amex card's last four digits, real bank references and a customer number, and a director's name as a counterparty are replaced with made-up values. In #64 (CI green), per the Product Owner's decision of 2026-09-29: big-brand supplier names (O2, EE, Adobe, Anthropic, OpenAI, Virgin Media, ScotRail, Pulumi, Marriott and others) stay; small businesses and anything naming a person are made up: The Bugle Inn, Black Sheep Coffee (London), Lightbulb, Blocknews and Meals on Wheels, a sole trader's first name, and a director's name in record ids (tests, and two code comments in src/rules/). Test users named after the team (robId, rob@example.com) are not counterparties and stay. The two emails in tests/platform/migrate.test.ts stay, since that test checks the access-grant migration, which names them. Conflict: CLAUDE.md's definition of done requires the Product Owner's exit test on real data; SGE wins, so exit tests stay on real data and development testing moves to the Demo Company. |
MCP
| # | Rule | Status | Sev | Evidence |
|---|---|---|---|---|
| C1 | Every tool: clear description, validated input schema, readOnlyHint and destructiveHint set | PASS | M | PR #55: every tool declares both hints, through READS_OUTSIDE, READS_NOTHING, SAVES_OWN_MEMORY and WRITES_XERO (src/mcp/annotations.ts:3-8), used by src/mcp/server.ts, src/mcp/attachment-tools.ts and the tool modules beside them, the write pairs (src/mcp/bank-tools.ts:333, :397, src/mcp/vat-tools.ts:269, :331) and the app-only approval tool (src/mcp/approval-card.ts:143). Reads are read-only; only the preview and confirm pairs, vat_remember_treatment and the approval tool are not; none is destructive. Test: tests/mcp/tools.test.ts:70 ("AUDIT C1"), which lists every tool the server registers, passes (2026-10-02). |
| C2 | Errors as structured tool errors in plain English, no stack traces or secrets | PASS | M | src/mcp/context.ts errorContent returns isError: true with the message only. |
| C3 | stdio writes nothing to stdout but protocol messages | PASS | H | src/mcp/stdio.ts has no logging; grep -rn "console\." src is empty. |
| C4 | HTTP endpoint: auth required, Origin validated, request size limited | PASS | H | src/web/app.ts: every /mcp request needs a Cloudflare Access token verified against the team's keys, issuer and application AUD (src/web/access.ts, jose). A foreign Origin gets 403, a body over 1 MB gets 413, and with Access unconfigured /mcp returns 503, never open. Before this, /mcp answered 200 with no token. Tests: tests/web/access.test.ts, tests/web/app-security.test.ts. |
| C5 | A Xero write needs a human action the model cannot perform; writes respect Xero's lock dates | FIXED | H | Found by the Product Owner, 2026-09-30 (#118). Lock dates: every write is refused on or before the later of PeriodLockDate and EndOfYearLockDate, at preview and at confirm (#122). Human action: each preview shows an approval card (MCP Apps); its Approve button calls an app-only tool the model cannot see, with a one-time token only the card receives (hash stored). *_confirm refuses without that approval. Injection tests in tests/mcp/bank-tools.test.ts ("C5:"). Since SPEC-003 S38 (2026-10-05) Approve also makes the write in the same app-only call: it approves and claims the preview in one statement (approveAndClaimPreview), then runs the same re-plan, lock-date checks and ledger_write logging as *_confirm (src/mcp/approval-card.ts). The card shows the outcome and puts it in Claude's context marked as data (updateModelContext: a data note and a fixed line first), which Claude sees with the owner's next message; it never sends a message (sendMessage), since Claude Desktop drafts those into the owner's prompt box with a warning (Product Owner, 2026-10-05), and the token is never in the context (tests/mcp/approval-card.test.ts). The model still cannot see or call write_preview_decide nor read the token; *_confirm stays as a fallback, still refuses without the card's approval, and writes nothing the card already wrote (tests "SPEC-003 S38:"). The web release gate was lifted by the Product Owner on 2026-10-01. Plan: docs/plans/human-confirmation-for-writes.md. |
Deadlines (SPEC-004, in progress)
| # | Rule | Status | Sev | Evidence |
|---|---|---|---|---|
| D1 | All date logic in Europe/London, with tests around the BST changeovers | PASS | M | PR #41: "today" is the London date from londonDate (src/rules/london-date.ts, used at src/mcp/deadline-tools.ts:32), and src/rules/deadlines.ts works only on those calendar dates (YYYY-MM-DD, day arithmetic at :28-37), so no clock change can move a due date. BST tests: tests/mcp/deadline-tools.test.ts:80 (00:30 BST on 7 Oct is the VAT due day) and :91-100 (both 2026 changeovers, either side of each), and tests/rules/london-date.test.ts; all pass (2026-10-02). |
| D2 | A deadline never triggers duplicate notifications (dedupe key per item and date) | N/A | — | Notifications are not built yet (SPEC-004 out of scope, later slice). Recorded as a requirement for that slice. |
Code
| # | Rule | Status | Sev | Evidence |
|---|---|---|---|---|
| K1 | Strict types, no any, zero lint warnings, no TODOs in merged code | PASS | L | Strict: tsconfig.json:6, with noUncheckedIndexedAccess. No any: no any type in src, tests or scripts. Zero warnings: pnpm lint (eslint . --max-warnings 0) passes on bcb4620. TODOs: PR #56 replaced the two in tests/vat/prepare.spec.test.ts and the one in SPEC-001's validation table (QD-03's 0p tolerance recorded as V1); git grep -n TODO -- src tests scripts docs finds none on main. |
| K2 | Secrets only from env vars, validated at startup; nothing sensitive in the repo or its history | PASS | H | History: the 2026-09-29 scan found no secrets; since then CI's security job runs gitleaks over the full history on every push (scripts/security/gitleaks.sh, the security job in .github/workflows/ci.yml), and a local run on 2026-10-02 found no leaks. The only database URLs with passwords are CI's throwaway test Postgres in .github/workflows/ci.yml. Startup: PR #60, as the Product Owner decided (2026-09-29): both entry points refuse to start if the database URL, token encryption key or Xero client ID and secret are missing or malformed, and the web endpoint also needs the Access team domain and AUD (src/platform/settings.ts:10-19, src/main.ts:8, src/mcp/stdio.ts:12); integration keys stay optional and are reported unavailable. Tests tests/platform/settings.test.ts pass (2026-10-02). |
| K3 | Tests cover 401 refresh, 429, 5xx, timeout, partial batch failure | PASS | M | 401 and refresh: tests/xero/session.test.ts. 429: tests/xero/http.test.ts. 5xx: tests/xero/vat-documents.test.ts. Partial batch: tests/mcp/bank-tools.test.ts "a Xero refusal is logged and reported, and the other entries still go in". Timeout: PR #57, every Xero and Starling request goes through timedFetch (src/platform/timed-fetch.ts, 30 s), and a timeout is a plain message naming the service; tests tests/platform/timed-fetch.test.ts pass (2026-10-02). Companies House (src/companies-house/client.ts:39-42) and push alerts (src/platform/alerts.ts:21-25) set their own AbortSignal.timeout. |
| K4 | At least 80% coverage on the reconciliation and deadline modules | PASS | M | PR #52: per-file thresholds of 80% for lines, branches, functions and statements in vitest.config.ts, enforced by pnpm test in CI; the list now also covers aged balances, card and receipt matching and src/present/**. On main, 2026-10-02, every measured file passes; the reconciliation and deadline modules: bank-reconciliation.ts 91.91% branches, reconciliation-summary.ts 87.87%, outstanding.ts 86.11% (lowest), deadlines.ts, london-date.ts and src/deadlines/** 100%. CI run 605, verify green on bcb4620. |
| K5 | Dependency audit clean | PASS | M | pnpm audit --prod: "No known vulnerabilities found". |
Loop log
- 2026-09-30: C5 added as FAIL, severity High (#118): Xero writes can be confirmed by the model, so a prompt injection in Xero data could write without the owner; lock dates are not checked. Plan written for approval.
- 2026-10-01: C5 fixed. Lock dates (#122); approval card with an app-only decide tool, tried by the Product Owner in Claude Desktop (spike #125), now required by every confirm.
- 2026-10-05: C5 evidence updated for SPEC-003 S38: Approve in the card makes the write itself and tells Claude the outcome, so the owner no longer says "I pressed Approve". The model still has no way to approve.
- 2026-10-05: C5 evidence updated: the card no longer sends Claude a message; the outcome goes into Claude's context only, seen with the owner's next message (Product Owner's choice, as Claude Desktop drafts app messages into the prompt box with a warning).
- 2026-10-02: M1 and X4 PASS, X3 gap closed (#161, after #155): the list tools page, return whole pence with a currency code, refuse a non-GBP organisation, and use the shared Xero client with its 429 backoff.
- 2026-10-02: statuses refreshed against main at bcb4620 (#156). M2, C1, D1, K1, K2, K3 and K4 are PASS, their fixes merged (#41, #52, #55, #56, #57, #60) and their tests passing on main. M1 and X4 stay FAIL: their fixes merged (#51, #53, #65), but
xero_list_invoicesandxero_list_paymentsread one page only, carry float pounds with no currency, and skip the base currency check. - 2026-09-29: first audit, 13 FAIL, 8 PASS, 1 N/A. Next: fixes that don't change product behaviour, in severity order, while the Ask items wait for the Product Owner.
- 2026-09-29: Product Owner approved M4 (preview and confirm by ID for both write tools) and C4 (Access token, Origin and size checks in the app). Reverse-charge fix merged (8137ea7), found by
vat_verify_returnon FEAW's filed return. - 2026-09-29: C4 fixed and M5 fixed; K2 history scan clean. Product Owner chose: deploy job over SSH from the pipeline, production settings in Doppler
prd, order C4 then deploy then attachments plan.
Queue
Done (2026-10-01): C5, #118. Lock dates and the approval card ship; see the C5 row. The Product Owner lifted the web release gate the same day: the web route now has the write tools, each approved in the card.
Order set by the Product Owner on 2026-09-29: the auth layer, then M4, then the rest of the audit loop, then branch protection with required approval. Nothing below starts until the auth layer and M4 are merged, unless the Product Owner says "now". Items marked plan first need a written plan and the Product Owner's go-ahead before anything changes.
Done: per-person auth layer (PR #44, merged 2026-09-29).
Planning pass: written, awaiting approval (asked 2026-09-29): docs/ROADMAP.md with the decision sheet, SPEC-005 and SPEC-006 drafts, ADRs 0021 and 0022 (proposed), docs/plans/email-reminders.md, QD-18 to QD-24, issue #45 for the possible-match list. No code until the Product Owner approves.
Done: M4, preview then confirm by ID (PR #48, merged 2026-09-29).
Rest of the audit loop, in this order:
- M1 first (Product Owner, 2026-09-29): money as floats in cash-basis scaling; currency codes on every money value.
- M2 and K4 (coverage tool, 80% on reconciliation and deadlines), X4 (paging on the accrual invoice list), X5 (made-up data in test fixtures), C1 (readOnlyHint and destructiveHint on every tool), K1 (two TODOs), K2 (settings validated at startup), K3 (request timeouts on Xero calls).
- The adversarial review (security reviewer and non-technical business owner), log the findings, fix, loop again.
Lift the web release gate: its own PR, later. Only after all three: the NAS deploy works (ADR 0023); the Product Owner has tested each preview→confirm pair on the Xero Demo Company; M1 is fixed (Product Owner, 2026-09-29).
Local testing:
- Enable Docker Desktop's WSL integration (or document how), so the Postgres tests run locally, not only in CI. Documented in
docs/dev/local-postgres-tests.md(branchdocs/local-postgres); turning it on is the Product Owner's, on their machine.
CI and release:
- Security checks in
verify:pnpm auditfailing on high or critical, and a gitleaks secret scan (tested locally 2026-09-29: tree and history clean). - Branch protection with the Product Owner's required approval on every PR, no admin bypass (last in the order).
- Tag releases with a changelog.
- Automated dependency update PRs (Renovate on GitHub), gated by the same CI.
Infrastructure (plan first):
- A dedicated
deployuser on the NAS: steps b to d done 2026-09-29 (ADR 0023). Deploys run through it from the merge ofci/enable-nas-deploy. Step e (remove the pipeline key fromrob) follows the first good deploy. - Separate prd secrets from dev: new
XERO_TOKEN_ENCRYPTION_KEYand database passwords for prd, and a separate Xero app for prod. Write it up as an ADR. - Cloudflare Access policy: done 2026-09-29, ADR 0020 accepted (named allowlist, Entra with MFA required in the policy, 8-hour session). Rob still needs
rob.duncan@feaw.co.ukadded as a guest in the getmy.group tenant. - Infra access details (hosts, users, how to get in) in a repo doc; they are kept out of agent memory.
Deploy, later: build the app image in CI and have the NAS pull it by digest, so nothing is built on the NAS (Product Owner, 2026-09-29; ADR 0023).
Optional hardening, later: a Match User deploy block in the NAS's sshd config with AuthenticationMethods publickey (and password and keyboard-interactive login off), so sshd itself refuses passwords for deploy. Not needed for step b: deploy's password field is *, so no password can match (ADR 0023). It changes the NAS's sshd config and needs an sshd reload, so it goes through the Product Owner (2026-09-29).
Operations:
- Nightly Postgres backups off the NAS, with a tested restore (script, plus one real restore documented). Back up the token encryption key separately from the data. Scripts on
ops/nas-backups(infra/nas/backup/): nightly root cron dump with validity check and 14-day retention, and a restore test in a throwaway container. Off-NAS copy: a DSM Hyper Backup task, set by the Product Owner. - Rollback: the deploy keeps the previous image, and one pipeline action rolls back to it.
- Alerting: a failed deploy,
/healthdown, and repeated Xero auth failures notify the Product Owner (email or push). Built, off until set up (docs/plans/alerting.md): ntfy push to the Product Owner's phone. Main failing (checks, migration or deploy) alerts from the pipeline; 3 failed Xero refreshes in a row for one entity log an alert and push; a scheduled/healthcheck through Cloudflare Access is written and off. Product Owner: subscribe to an ntfy topic and put it in DopplerprdasALERT_NTFY_TOPIC; reinstall the NAS compose file; for/health, an Access service token with a Service Auth policy, three Dopplerprdsecrets (HEALTH_CHECK_URL,HEALTH_CHECK_ACCESS_CLIENT_ID,HEALTH_CHECK_ACCESS_CLIENT_SECRET) and the repository variableHEALTH_CHECK_ENABLED=true. - Structured logs with no PII or financial detail, with a retention period.
Accounts and data:
- Offboarding: disconnecting a user or organisation revokes its Xero token and deletes stored tokens, and keeps the audit log.
- Data protection ADR: what personal and financial data is stored, where and for how long, plus a privacy notice. Say whether ICO registration is needed. Drafted:
docs/decisions/0026-data-protection.md(proposed, awaiting the Product Owner's decisions on controller, retention and the ICO fee). - Xero's connection limit for uncertified apps and what certification needs, in an ADR, before onboarding anyone outside FEAW.
Features:
- Attachments (invoices and receipts): SPEC-005 and the not-doing ADR. Plan first.
- Deadline email reminders (SPEC-004's later step, deduplicated per item and date). Plan first.