[sonichi]

main is red on its own src-map gate

main at 1f526886 fails two checks. This fixes one of them:

refuse docs/src-map.md stale vs src/   → failure
tsc + tests (clean install)            → failure     (not this PR)

The shipped check, run on a clean origin/main worktree:

$ python3 scripts/gen-src-map.py --check
gen-src-map: docs/src-map.md is stale — run 'python3 scripts/gen-src-map.py' and commit the result

$ python3 scripts/gen-src-map.py
gen-src-map: wrote docs/src-map.md (204 modules)
$ git diff --stat docs/src-map.md
 docs/src-map.md | 2 +-

The whole diff is the header count: 203 modules indexed. → 204 modules indexed.
After: gen-src-map: docs/src-map.md is up to date.

Why this is worth a PR rather than leaving to the next toucher

The gate measures a PR merged with main, so a stale map on main fails every open
Python PR regardless of what that PR changed. I hit it on two of mine today (#2741,
#2757) and cleared it on each by merging main and regenerating — which works, but is
per-PR and has to be repeated by every author. Fixing it here clears it once.

Credit for the diagnosis: Sutando-Pro identified the merged-with-main mechanism after
hitting identical symptoms on #2779 — gen-src-map producing no diff in the branch
alone while CI still failed.

Scope

One generated file, one line. No source, no tests, no behaviour.

[github-actions]

Coverage Gate

✅ No Python changes — nothing to gate (bar: 95% on changed lines).

[sonichi]

This is the second time, and the recurrence is the more useful finding.

#2635 merged 2026-08-04 with a nearly identical title and the same one-line diff —
202 → 203 then, 203 → 204 now. Six days apart. So the gate reliably detects
staleness and nothing keeps the file fresh: any merge that adds a module under src/
leaves main red until a human happens to look, and meanwhile every open Python PR
inherits the failure because the gate measures merged-with-main.

That makes this a design gap rather than a chore. Options, roughly in increasing cost:

• generate in CI and commit, or fail only when the content (not the count) drifts
• pre-commit hook — gen-src-map --check already exists and exits non-zero, so the
  hook is a two-line addition and it moves the catch to the author who added the module
• stop hand-carrying the count — 203 modules indexed. is the only line that ever
  drifts here; deriving it at render time removes the whole class

I have not implemented any of them: which one is right depends on whether the map is
meant to be reviewable in a diff (in which case CI must not silently rewrite it), and
that is a maintainer call. Filing the observation with the fix rather than picking.

[sonichi]

@sonichi flagging you — one generated line, clears one of the two checks currently red on main.

[qingyun-wu]

Reviewed exact head f391296a501116ec0e4eb523bdfc43d522c756f3.

APPROVE — code-ready; no blocking finding in this generated one-line repair.

The failure exists on origin/main at 1f526886: python3 scripts/gen-src-map.py --check exits 1 with the stale-map diagnostic. The same command passes on both this PR head and GitHub's merge ref 3257110f. The full diff is only docs/src-map.md's generated count changing from 203 to 204; git diff --check and the REVIEW hardcoded-path scan also pass.

Worst-case user disruption is none: this changes documentation generated from the existing src/ tree and no runtime behavior. Hosted source-map, coverage, lint, ruff, shellcheck, and workspace gates are green. Code-ready; final merge-readiness still requires the in-progress clean-install CI and CLA status to finish green.

Reviewed by Qingyun's Personal Codex.

[sonichi]

This one line clears TWO gates per PR, not one — measured

The case for merging this first got stronger. refuse docs/src-map.md stale vs src/ is the
obvious victim, but the stale map also fails tests/src-map.test.py, and that in turn
fails the coverage gate, because coverage-gate.sh refuses to measure a red suite.

From my #2785 run (a 14-line, test-only PR that touches nothing under src/):

✖ test failed under instrumentation: tests/src-map.test.py
coverage-gate: 7 test case(s) SKIPPED in this environment.
coverage-gate: suite must be green before coverage is meaningful.

Reproduced on a clean origin/main worktree, before and after this PR's one-line change:

origin/main as-is                     Results: 1 failed, 24 passed
after `python3 scripts/gen-src-map.py`  Results: 25 passed

So the accounting for any open Python PR is:

red check	cause
refuse docs/src-map.md stale vs src/	this stale map — fixed here
diff coverage >= 95% (python)	tests/src-map.test.py red → gate won't measure — fixed here
tsc + tests (clean install)	independently red on main; not this PR

#2762 and #2760 are also failing the coverage gate right now, consistent with a shared
cause rather than three separate authors' mistakes.

One correction to my own earlier reasoning

I had been comparing a PR's red checks against main's to decide what was inherited. That
comparison is invalid for the coverage gate: coverage-gate.yml is on: pull_request, so it
never runs on main and can never appear red there. "Not red on main" meant "not measured
on main", and I nearly filed the coverage failure as my own defect on that basis.

[sonichi]

Closing: already fixed on main. fedcbd05 (#2324) carried the regenerated map, so this PR's content is now redundant — verified byte-identical rather than inferred:

docs/src-map.md @ f391296a (this PR)  sha256 610a3bc46d78  22933 B
docs/src-map.md @ fedcbd05 (main)     sha256 610a3bc46d78  22933 B

And gen-src-map.py --check on origin/main now reports "docs/src-map.md is up to date" with 204 modules indexed. — exactly what this PR was going to set it to.

The knock-on matters more than this PR. While main's count line was one behind its tree, that single staleness made three checks fail on any PR carrying main's HEAD — refuse docs/src-map.md stale vs src/, tsc + tests (clean install), and diff coverage >= 95% (python) (the coverage job fails because tests/src-map.test.py fails under instrumentation, verified in #2785's job log). I was holding all bulk update-branch for that reason: of 64 BEHIND PRs, 60 were green at their own head and would have gone red on three checks each.

That hold is now lifted — main is clean on this axis, so updating a branch no longer inherits the triple.