Contributing: license, CI, and reconciliation tests for the public API

[RMV-Coder]

First: this is a genuinely well-built codebase. public-api.ts validates years against an enum, rejects foreign cursors, parameterizes every bind, and sets sensible Cache-Control. The MCP server answers initialize correctly and its nine tool descriptions are better written than most commercial ones. I went looking for problems and mostly found good decisions.

So this issue isn't about fixing the code. It's about the things a solo maintainer shipping features every day never gets to — the scaffolding that lets other people help. I'd like to contribute, and I'd rather ask before sending a PR.

Four things, smallest first. Happy to do all of them, some of them, or none if you'd rather they went differently.

---

1. A license (blocking question)

repos/bettergovph/ai-budget currently reports license: null, so the repository is legally "all rights reserved." Meanwhile /api/v1/openapi.json declares CC-BY-4.0, and the Hugging Face dataset is CC0-1.0.

The intent is obviously open, but without a LICENSE file, contributions sit in an awkward place and downstream reuse (other BetterGov repos, researchers, journalists) has nothing to point at.

There's org precedent pointing two ways:

• CC0-1.0 — bettergovph/bettergov, bettergovph/kapwa, and bettergovph/open-budget-data, plus the bettergovph/gaa dataset on Hugging Face
• MIT — bettergovph/transparency-dashboard and bettergovph/flood-watch

Roughly: the data-shaped projects went CC0, the app-shaped ones went MIT. This repo is both, which is probably why it hasn't been decided yet.

Worth noting that CC-BY-4.0 — what the OpenAPI spec currently declares — matches nothing else in the org. So there may be a second small fix here: whichever license you pick, openapi.json should agree with it, or explicitly state that the code and the data carry different terms.

Which do you want? I'll add the file and align the spec. I just don't want to guess on your behalf.

2. .github/ scaffolding

There's currently no .github/ directory at all, and GitHub's community profile for this repo scores 12% — the lowest of any repo in the org. I'd add:

• workflows/ci.yml — run npm run lint and npm run build on pull requests and pushes to main. That's it; nothing that needs secrets, no deploy, no Wrangler auth.
• CONTRIBUTING.md
• Issue and PR templates, kept minimal.

On the CONTRIBUTING file specifically: I'd rather link than duplicate. bettergovph/bettergov already has a thorough guide, and the parts of it that are genuinely org-wide — the Code of Conduct, the Discord, volunteers@bettergov.ph, the ground rules — should be referenced from here rather than copy-pasted and left to drift. What's actually specific to this repo is short:

• the Node version constraint (^20.19.0 or >=22.12.0)
• cp .env.example .env.local, and why VITE_DATA_BASE_URL means the multi-gigabyte dataset isn't needed for normal UI work
• which commands are safe offline vs. which touch R2/D1 and therefore need Wrangler auth and credentials

That last one is the bit a newcomer will otherwise get wrong, and it's the one thing no other repo's guide can tell them.

The CI piece matters most. Right now a PR from a stranger can't be trusted without you building it locally, which makes reviewing outside contributions expensive — exactly the tax that keeps a project solo.

3. Reconciliation tests in CI

This is the one I think earns its keep.

The verification logic already exists — scripts/verify-nep-2027.ts, scripts/verify-budget-cycle.ts, scripts/verify-parquet-shape.ts, scripts/verify-sqlite.ts. It's just not wired to anything that runs automatically. I'd like to lift the invariants out of those scripts into a Vitest suite (via @cloudflare/vitest-pool-workers, so the Worker routes are exercised for real) that CI runs on every PR:

• expense classes sum to the department total, per department per year
• department totals sum to the published national total, per year
• NEP: amount - base_amount === delta, and pct agrees with both
• keyset cursors round-trip — paging a full result set returns each row exactly once, and meta.matched matches the row count
• REST and MCP return identical figures for the same question (they share public-api.ts, so this should hold by construction — the test is there to keep it that way)

Two bugs already in the commit log are exactly this shape:

fix(gaa): capital outlays were absent from every expense-class breakdown
fix: "cut most" lists showed increases -- sign-filter every movers list

Both are invariant violations that a sum-check would have caught before deploy. For a site whose numbers may end up quoted in reporting, a silently wrong aggregate is the worst failure mode available — worse than an outage, because nobody notices.

4. Two small fixes

• /llms.txt returns the SPA shell. For a project that ships an MCP server and an OpenAPI spec, this feels like a gap worth closing — a short llms.txt pointing agents at /api/v1, /mcp, /api/v1/openapi.json, and the HF dataset, with the units and department-id caveats stated up front.
• Unknown routes soft-404. GET /nonsense-route-xyz returns HTTP 200 with the homepage <title> and description. sitemap.xml and robots.txt are both real and well done, so the SEO work is mostly there already; this is the remaining piece. A 404 status plus a route-aware title would stop search engines indexing phantom pages.

---

On scope

I noticed src/pages/Portal.tsx is ~94 KB and src/worker/index.ts ~58 KB, and I'm deliberately not proposing to touch them. A large refactor from someone you've never worked with, against a codebase with no test coverage, is the PR most likely to waste both our time. If items 2 and 3 land, that conversation gets much easier later — and it should be yours to start, not mine.

One thing beyond this repo

While checking whether bettergov's CONTRIBUTING already applied here, I found it doesn't — and can't. GitHub only propagates community health files org-wide from a repo named .github in the org, and bettergovph/.github doesn't exist. So every repo starts from zero, and most have stayed there: of ten repos I checked, only bettergov and kapwa have a CONTRIBUTING or Code of Conduct at all.

Creating bettergovph/.github with a default CONTRIBUTING.md, CODE_OF_CONDUCT.md, and issue templates would lift all of them at once, and any repo could still override with its own file where it needs to.

That's out of scope for this issue and it needs an org admin rather than you — I'm flagging it because it's the kind of thing that stays invisible until someone goes looking. Happy to open it as a separate issue or draft the repo if it'd be useful; equally happy to drop it.

How I'd like to proceed

Item 1 is a question only you can answer. If you tell me the license, I'll open items 2 and 4 as one small PR (scaffolding + the two fixes, no behaviour change to any existing route), and item 3 as a separate PR so the test suite can be reviewed on its own terms.

If you'd rather I just sent the PRs and skipped the discussion, say so and I'll do that instead.