feat(ast): add the role census, kind-coverage ratchet and bypass lint #1692

Objective

Add the three gates that make an omission visible — the per-(language, role) census, the kind-coverage ratchet keyed by runtime kind id, and the bypass lint — with self-tests, wired into make pre-commit and make ci. State in each what it cannot detect.

Umbrella: R00: #1690 · Planning ID: R02: #1692
Completion prerequisites: R01: #1691

Status: implemented on branch refactor/1691-role-table-proof as two commits on R01's tip b9ea546f: 9c03629a (every language's table, the kind-flags sidecar, the shared reader) and 92d7ff74 (the three gates, baselines, integration). Not pushed; the one pull request will carry R01 and R02 together.

Adjustments to this body, recorded before implementation. R01 fixed the DSL by compiling it, and it differs from the illustrative syntax below: absent(role, reason) is Role { absent "reason" } emitting role::ABSENT; pending(R0n) is Role { pending Rnn } emitting role::PENDING; Excluded(role, reason) is a row-level excludes [Kind "reason"] emitting role::EXCLUDED under the row that rejected the kind. R01 shipped three proof tables (Java, Python, Elixir), not two. A plan review (astra-review, before any code) also moved four things stated below: baselines are exact record sets rather than counts, so a swap cannot hide inside an unchanged total; the bypass boundary includes the parent dispatcher modules and the macros that generate consumers (Java's cyclomatic membership lives in cyclomatic.rs's impl_cyclomatic_java_like!, outside the per-language files); named/visible labels come from the runtime via a generated KIND_FLAGS sidecar in each language_<lang>.rs, not from node-types.json; and no kind category is excluded from debt implicitly — _repeatN / _tokenN internals and _-prefixed kinds (C::Volatile2 spells __volatile__) are baselined like any other until a row claims or excludes them.

A second review pass (the review and rust-optimize skills, a performance agent, and astra-review on the least-reviewed surfaces, then astra-review on every fix) moved three more things: make fmt / make fmt-check now reach the excluded enums/ and fuzz/ crates by manifest path, since cargo fmt --all had never seen the sidecar's test file; corpus staleness is judged against the index gitlinks so a corpus bump staged with its re-observation passes pre-commit; and --migrate-pin is repeatable with an all spelling because the five vendored grammars share one pin that every release bumps (RELEASING.md gains the step). Four more absent cells became pending (C Catch — the pinned grammar emits seh_except_clause; Tcl and iRules DeclKeyword — their grammars emit proc / namespace / when leaves; Tcl Closure — apply is a recognition boundary, not an absence).

Why this exists

A table nobody is forced to use decays into another copy — kind_sets.rs has existed since May and never served getter/* (umbrella, "What prior consolidations did"). And a table that records only what someone remembered to list has today's blind spot: grammar-dispatch.md §1 says an arm list is a coverage claim the compiler cannot check. These gates are that check, modelled on check-snapshot-anchors.py and check-rustfmt-bail.py because a ratchet that enumerates existing debt is honest about what is and is not covered, where a one-shot "classify everything first" would stall the migration or be padded with blanket exclusions.

Two scope limits come from the design review and must be stated in the gate output, not just here: the ratchet catches newly unclaimed kinds and is not a substitute for #1458's measured sweeps; and grammar.json is not the id table — aliased kinds share a spelling and differ in id (grammar-dispatch.md §1), so identity is the runtime id from enums/.

Implementation steps

• Create roles/<lang>.rs for every remaining LANG with every role pending(R0n) naming the package that will declare it, so the census has a complete input from this package on. The two helper grammars are not blanket-absent: Ccomment and Preproc recognise comments and string literals (checker/ccomment.rs, checker/preproc.rs), so their Comment/DocComment cells are pending(R09) and StringLit pending(R08); only the roles they genuinely lack are absent with a reason.
• utils/check-role-census.py: for every LANG and every role in R01: #1691's set, require rows, absent(role, reason), or pending(R0n); print the (language × role) matrix with pending cells marked; fail on a hole; a missing roles/<lang>.rs is a failure, not a skip. pending cells are a ratchet of their own (--update may only remove them) and must be empty when R11: #1701 closes the umbrella.
• utils/check-role-coverage.py: per language, candidates are the grammar's full symbol list from the pinned crate's grammar.json — named rules and anonymous terminals (__volatile__, co_return) — resolved to runtime ids through the generated language_<lang>.rs enum; subtract kinds any row of any role names (raw sets — a kind claimed by one role is claimed) and kinds listed Excluded; the residue per language is compared against .role-coverage-baseline.txt. The guarantee is exactly "every grammar kind is either claimed by some role, excluded with a reason, or in the baseline" — global coverage, not per-role correctness. An Excluded(role, reason) entry's role names whose author considered and rejected the kind, printed in the report so a reviewer sees which rejection is relied on; it asserts nothing about other roles, and a kind may carry several; increases fail; --update ratchets down. A column marks which residue kinds the integration corpus emits at this pin, so a reviewer can tell live from latent.
• utils/check-role-bypass.py: scope is the consumer boundary per role — the files that read owns_/pays_ for that role (abc/*, cyclomatic/*, cognitive/*, getter/*, checker/*, npm/*, npa/*, nexits.rs). Inside that boundary, a kind in a row's raw set appearing in a matches!, a match arm, a kind_id() ==, a kind() == "…" string comparison, or a const array fails unless under // role-bypass: allow(<role>) — <reason>. Outside the boundary (naming, traversal, doc attachment, tests) it is not checked, and the gate's header says so. Own ratchet, .role-bypass-baseline.txt, during migration.
• Each gate carries a *-test.py pinning both directions, as check-snapshot-anchors-test.py does.
• Makefile targets; wire into lint, pre-commit, ci, .pre-commit-config.yaml, the lint CI job.

Tests and edge cases

• Census: a table with neither Modifier rows nor absent(Modifier) nor pending fails naming language and role; a pending cell passes and is counted.
• Coverage: a stub enum + flags pair (not grammar.json — identity is the enum, see the adjustments) + enum pair where two kinds share a spelling with different ids — claiming one must leave the other in the residue. Adding an anonymous terminal raises the residue; Excluded(Branch, …) on it removes it from the residue and is reported under Branch; a cross-role self-test asserts a kind claimed by Container is not in the residue at all.
• Bypass: kind_id() == Java::MethodInvocation under src/metrics/abc/ fails; the same under src/spaces/ (traversal) passes; an exempted one passes; a kind() == "call_expression" string dispatch inside the boundary fails.

Acceptance criteria

• All three gates run in make pre-commit and make ci; none skips silently.
• Baseline files committed with headers explaining an entry, the ratchet direction, and what the gate cannot see (wrong-role claims, incomplete entries, dead walker paths).
• With R01: #1691's two partial tables plus the pending tables for every other language, the census passes with every undeclared cell marked pending; the coverage residue per language is in the baseline, not hidden.

Verification and completion evidence

• Self-test output for each gate and one real run; BCA_GATE: line.