A schedule trigger runs daily. The routine scans every PR merged since the last successful run, flags the curated documentation that references the APIs those PRs changed, and opens a single rolling update PR against the docs repository for an editor to review. It flags. The editor decides.
automation/docs-api-drift, draft-by-defaultEvery step is bounded: the scan window closes on the previous successful run, the API scope is a fixed prefix list, and the deliverable is a single rolling PR. Nothing escapes the envelope.
Lower bound is the created_at of this workflow's previous successful run. Cold start falls back to the last 24h; manual dispatch can override via since. When the rolling PR is open, the bound widens to the window that PR recorded — so the originating merges stay in scope until drift clears.
Every PR with merged_at > since via gh. Pagination is bounded — a run that exhausts the cap exits inconclusive, so the next run rescans the same window instead of advancing past unpublished drift.
A change counts as API only when it lands under scripts/, portal/, or apps/ in a code file (.py .sh .js .mjs .cjs .ts .tsx). Test trees and build noise are filtered out — your editor's morning is not spent on __pycache__.
Path drift — a file the docs name was modified, removed, or renamed (renames tracked by the old path, since that is what the docs still point at). Symbol drift — a def / class / export was removed or renamed. Re-added names are excluded, so a body edit that keeps the signature never registers.
Every signal is matched against every Markdown file under docs/ (excluding _generated/ and _shared/). Path match is exact. Symbol match requires the identifier as a whole token. Every hit carries the doc path, line number, originating PR, and the changed path or symbol.
One PR on branch automation/docs-api-drift. New on first drift, refreshed on subsequent runs, closed automatically when a complete scan clears the worklist. Opened as draft — the merge button stays off until an editor explicitly clicks "Ready for review," the affirmative gate for "I actioned every flag."
Path matching is exact and effectively false-positive-free. Symbol matching is the noisier signal, so it is deliberately conservative — generic identifiers never reach the editor.
The docs cite a path by name; the merged PR modified, removed, or renamed that file. Exact-match. Renames are tracked by the old path because the docs still point there.
A def, class, or export was removed or renamed. The identifier must be distinctive — long, snake_cased, or camelCased — and survive the stopword filter before it is chased into the docs.
The PR body is the generated report. A per-document worklist, each line citing the changed path or symbol, the originating PR, and the exact line in the doc that still references it.
One trigger. One concurrency group. Permissions narrowed to what the publisher step actually needs. Failure modes are inconclusive-by-default so a partial scan can never silently un-flag stale docs.
.github/workflows/docs-api-drift.ymlschedule at 17 6 * * * · workflow_dispatch with optional sincescripts/docs_api_drift.py — stdlib-only, shells out to ghdocs/_generated/api-drift-report.md — rewritten every run; never hand-editedautomation/docs-api-drift — rolling, fast-forward only, draft PRSTONEWALL_AUTO_REBASE_PAT (draft create) · falls back to GITHUB_TOKEN for scan-only pathsactions: read · contents: write · pull-requests: writedocs-api-drift, queued (not cancelled)scripts/ · portal/ · apps/ — tests & build noise excludeddocs/, excluding _generated/ and _shared/tests/test_docs_api_drift.py — window, classifier, symbol noise, report shapeThe scanner is stdlib-only and shells out to gh. Authenticate gh first and the local run is byte-equivalent to what CI emits.
This page is the front door. The deeper artifacts — editor contract, walkthrough, showcase, marketing spotlight — live alongside.