rubrics: penalise hidden infrastructure, process narrative, and blocked dot notation - #119
Open
kim-em wants to merge 1 commit into
Open
rubrics: penalise hidden infrastructure, process narrative, and blocked dot notation#119kim-em wants to merge 1 commit into
kim-em wants to merge 1 commit into
Conversation
…ed dot notation Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U5KGWwFSnMen8xF69m94bV
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three defect classes turned up across a cleanup pass on TauCeti that no rubric currently catches. Two of them are produced by interactions between existing rubrics rather than by carelessness, which is why they recur.
api-design.mdandplacement.md: under-exposure is unpenalised.api-designfails an "over-exposed surface" but never an under-exposed one, and licensesprivatefor anything with "no use outside the proof or file it serves". Meanwhileplacementmakes relocation expensive: update every import, delete the old path, all in one PR. So when a declaration turns out to be too general for the file it landed in, marking itprivatesatisfiesapi-designand removes it fromplacement's reach. It is the locally cheapest move and the wrong one.This is not hypothetical. Twelve files carry an explicit "kept private because…" docstring. The clearest read, before it was fixed:
Mathlib has the setoid and ring-idempotent forms of that statement but no submodule form, so Tau Ceti proved a missing piece of general infrastructure and sealed it, giving its generality as the reason. Another gave the reason as "the general-topology statement belongs upstream rather than in a complex-analysis file" — identifying the correct home and hiding it there instead.
documentation.md: the "why" clause manufactures process narrative. The rubric asks each module docstring to say what lives there "and why", andscope.mdrequires new material to cite a roadmap target, so authors satisfy the "why" with the roadmap citation. 1370 of 2053 files (67%) now carry roadmap prose naming targets, layers and coordination status with in-flight upstream work, in the one place nothing will ever update it. This is newly fixable becauseAGENTS.mdnow mandates aRoadmap:line in every PR description, so the justification has a correct home.naming.md: no rule for which namespace. The rubric says a name must not be "wrong for its namespace" but never says which namespace a declaration about a Mathlib type belongs in. 1860 of 2053 files opennamespace TauCeti; 875 declarations across 168 files thereby block dot notation on a Mathlib type, and 395 files work around it with_root_. The bullet added here is deliberately narrow, excluding the three false-positive classes that a naive reading over-reports by roughly 40%: organisational namespaces, Tau Ceti's own types that share a Mathlib name, and declarations taking no argument of the type.Five merged PRs have cleared roughly 400 of the 875, and a further round of findings on those PRs came from this angle, so the rule is already being applied by hand — it just is not written down.