Publish a daily cross-repository Babel milestones page as part of the dashboard site

[gaurav]

Milestones are the commitment mechanism across the Babel repositories, but they cannot span repositories — so "what have I actually committed to?" currently means visiting five separate milestone pages across two organizations. This adds a page to the dashboard site that merges them into one chronological list, regenerated daily.

Closes no issue of its own — the need was recorded in docs/milestones-page.md rather than as a ticket.

Live numbers from a run against the API this morning: 18 open milestones, 313 open issues, 11 of the milestones priority buckets rather than releases, 3 past due.

What's here

A generator, not a page-builder. src/babel_validation/tools/generate_milestones.py reads open milestones and their open issues and writes data/milestones.json next to report.json and history.jsonl. The first version of this PR wrote a self-contained HTML file with its own inline CSS, because it was going to be published by its own workflow into gh-pages:milestones/.

A page of the site, not a page beside it. /milestones/ is an Astro route mounting a Vue island inside Layout.astro, exactly like the three dashboard pages: it gets the nav bar, the theme, dark mode and the load-error state for free. Releases first, sorted by due date; the legacy priority buckets (Immediate, Needed soon, …) in their own section below, because they have no due date and never close, so sorting them among real deadlines would either bury the deadlines or dress the buckets up as ones.

One workflow still owns gh-pages. This is the point of the whole restructure. JamesIves/github-pages-deploy-action cleans by default, so the original arrangement — a second workflow publishing milestones/, protected by a clean-exclude on the site's deploy — was one merge away from the dashboard's daily run silently deleting this page. Two publishers need a shared concurrency group and a clean-exclude, which is two things that have to stay in step forever and fail quietly when they don't. One publisher needs neither.

dashboard.yaml splits into three jobs so the two data products cannot sink each other. validate is 26 minutes of pytest against six deployments; milestones is ~23 GitHub API calls in about a second. They run in parallel, each uploading its own data file, and publish assembles what arrived and makes the single write to gh-pages. milestones is never on the critical path, so this costs an extra checkout and a uv sync and no wall clock.

Two parts of that needed care, and both are the kind of thing that would have looked fine until the day it mattered:

• publish gates on job outputs, not needs.<job>.result. validate deliberately fails itself when a target's run broke — that is what the step added in 5f90b3b is for, and it fires on ordinary days. A result-based condition would therefore skip the download of a report that had generated perfectly well, and quietly publish yesterday's instead. The output is set immediately after the generator succeeds, several steps before that failure, and Actions preserves outputs set before a later step fails.
• Anything this run did not produce is carried forward. A file missing from website/dist is a file deleted from the live site, so one producer failing would take down the other's page. publish refetches the last published copy instead — the same idiom validate already used for history.jsonl — and every page renders its own generated_at, so a carried-forward file reads as stale rather than as current. If even the live copy is gone, which is the case on the first run of a new data file, the page falls back to its own load-error state; verified by running the step against the live site with milestones.json not yet published.

The repository list comes from targets.ini's Repositories. It is already exactly this family of repositories, it is checked-in config the untrusted-input rules treat as trusted, and the workflow's target loop has drifted from read_targets() once already. A comment says what to do if the two questions ever diverge: add a MilestoneRepositories key that falls back to this one, not a hardcoded list.

Milestone and issue titles are untrusted, and are treated as such. They are written by anyone with a GitHub account and land on a public page, so they go through the same sanitize() that report.json's text does — escaped rather than stripped, and truncated. html.escape() was right for HTML and says nothing about ANSI escapes or bidi overrides. Links are never emitted as URLs: the generator emits validated org/repo#N ids and the page rebuilds github.com URLs from the captured parts, so an issue or milestone in a repository the allowlist does not name simply renders unlinked. Issue bodies are never read.

Those primitives moved to src/babel_validation/tools/sanitize.py so both generators share one copy. generate_report.py re-exports them, because its docstring's claim to be the choke point for report.json is still true and its tests import them from there.

The docs describe what now ships. CLAUDE.md said "three pages" and described the workflow as one pass producing two files; the root README.md said the same and gave no way to regenerate the milestones data locally; website/README.md counted two data files. All three are corrected, and CLAUDE.md additionally records the two properties of the new workflow that a restructure would silently undo — the output-based gating and the cleaning deploy — because #122 is a restructure of exactly this workflow.

Two unrelated cleanups ride along, both noticed while reviewing #120 and both one line: tests/conftest.py now closes the --report-jsonl file on pytest_unconfigure (nothing is lost today because every record is flushed, which is what makes it worth fixing — the flush is the obvious thing to remove for speed), and FilterBar.vue removes --filterbar-h from documentElement when it unmounts, so the load-error path stops holding the table header's sticky offset down a page with no filter bar on it.

Permissions drop. contents: read by default, with contents: write only on publish. The two jobs that run untrusted input no longer hold a token that can push anything.

What it produces

44KB of JSON, against report.json's 1.8MB — 18 open milestones and 313 open issues on the run this was verified against.

Tests: 14 new Python unit tests and 9 new vitest specs. The six Python tests that shipped on this branch originally were rewritten rather than kept: three of them tested render(), which no longer exists.

What it deliberately does not do

• No priority sorting yet — filed as Sort and style the milestones page by Priority: labels #127, which turns out to be unblocked: the label scheme it was waiting on already exists.
• Closed milestones are ignored, which hides ~253 open Babel issues parked in closed buckets. Filed as Open issues parked in closed milestones are invisible to every milestone view NCATSTranslator/Babel#1048.
• No grouping by repository or component; one chronological list, then the buckets.

Before merging

• Dispatch the workflow once after merge and watch all three jobs. The job split, the output-based gating and the carry-forward have been checked locally — the carry-forward step was extracted and run against the live site, and the YAML parses to the expected job graph — but workflow_dispatch only exercises a workflow that is on the default branch, so none of it has run on a runner. Worth confirming that publish runs and deploys on a day validate goes red over a broken target, since that is the case the gating exists for.

Follow-on work

• Sort and style the milestones page by Priority: labels #127 — sort and style the milestones page by Priority: labels. Publish a daily cross-repository Babel milestones page as part of the dashboard site #112's note said this was blocked on a label scheme that did not exist; it does, and is on 162 of the 313 open issues (Priority: High 66, Medium 55, Low 41), alongside Size: XS/S/M/L. Ordinary UI work now rather than a decision, and the page is correct without it.
• Drop BUCKET_TITLES once the legacy priority-bucket milestones are cleaned up #128 — drop BUCKET_TITLES once the legacy priority-bucket milestones are cleaned up. Still 11 of the 18 open milestones, so blocked on the cleanup rather than on the code.
• Bump the GitHub Actions that still target the deprecated Node 20 runtime #129 — bump the Actions still targeting the deprecated Node 20 runtime, which the first live run of dashboard.yaml annotated. Not caused by this PR, but this PR is what surfaced it.
• StatusMatrix counts the shared ci NodeNorm deployment twice, inventing a majority #145 — StatusMatrix counts the shared ci/ci-es NodeNorm deployment twice, which can turn a genuine 3–3 promotion split into a 4–2 "majority" and shade the wrong half of the row. Pre-existing; noticed reviewing Replace the website with a daily cross-environment test dashboard built around promotion drift #120.
• Two active workflows named Tests, and #106 would merge a second one rather than replace the first #146 — the repository has two active workflows named Tests, so gh run list --workflow Tests is ambiguous today, and Make babel_validation a top-level import; add ruff and offline unit tests to CI #106 would merge a second one alongside the first rather than replace it. An earlier revision of this description recorded this as resolved by time, which was wrong: test.yml being off main is not the same as it being gone.
• A note on A shared ?sig= link silently matches nothing once the environment list changes #123 recording the second way a shared /results/ link goes stale: ?page= is clamped for rendering but only written back to the URL on a user edit, so ?page=9999 copied straight out of the address bar stays ?page=9999.

Why generated rather than a GitHub Project

A cross-repo project board was the obvious alternative. A board is a second record of commitment that has to be kept in step with the milestones by hand, and drifts as soon as that stops happening; this page is derived, so the milestone is the only input and there is nothing to sync. A board also can't answer the question that matters most from outside — roughly when someone's issue will be looked at — whereas a public URL can.

Automating a board is also expensive: the built-in auto-add filter supports only is/label/reason/assignee/no (not milestone:) and never removes items, so keeping one in step would need an Action in all five repos listening for milestoned/demilestoned, plus a PAT with project scope as an org secret in both organizations.

The constraint worth preserving: all five repositories are public, so the built-in GITHUB_TOKEN reads them across both orgs with no secrets to configure or rotate. Reading fields off a GitHub Project would break that. Priority and component therefore live in labels — which, as above, they already do.

History — the HTML-page version, the wiring that had to be removed, and the rebuild. Kept for anyone tracing why a particular line looks the way it does; the durable conclusions are in docs/milestones-page.md and CLAUDE.md above.

The first version generated a self-contained HTML document and published it from its own milestones-page.yaml into gh-pages:milestones/, at 06:17 UTC, just ahead of the dashboard's 06:30. It needed clean-exclude: milestones/ on deploy-website-to-gh-pages.yaml and a shared concurrency: gh-pages group, because that workflow deployed to the root of the branch and cleaned by default.

#120 invalidated all three pieces at once: it deleted deploy-website-to-gh-pages.yaml (and with it the clean-exclude), replaced the index.astro that carried the link, and moved publishing into dashboard.yaml with a deploy that also cleans. Every one of those would have merged without a conflict and then deleted this page on the next daily run, so the wiring was removed from this branch before #120 merged rather than left to break quietly. That is why this PR sat for a while with a tool, some tests and a doc saying "not currently published".

Also fixed along the way: the six tests in test_milestones_page.py carried no unit marker, and CI's only pytest job is pytest -m unit, so they were deselected and had never once run. That is now a rule in CLAUDE.md, with this file as the cautionary example.

Two things the live run found after the rebuild, both committed separately: the generator assumed its output directory existed, which it does not on a fresh checkout or in the workflow; and the summary line rendered "3 past due· as of 2026-09-01", because Vue condenses whitespace at a <template> boundary and silently dropped a trailing separator. The second is now written down in website/README.md, next to the replaceState trap, because it has the same shape: no test catches it unless it compares the whole rendered string, since none of the words go missing.

main has since advanced past the merge commit on this branch — #130 and the seven commits behind it reworked the Google Sheet download. They touch no file this branch touches except CLAUDE.md, in a different section, and the PR's checks run against the merge result and are green, so no merge was made purely to prove that.