Point at the roadmap before a release, and at mathlib for a hypothesis - #900
Merged
Conversation
Two things a maintainer had to point out after the fact, written down so the next session reads them first. AGENTS.md gains "Read the roadmap before you release anything". #746's v1.0-v9.0 are capability tiers rather than versions -- v1.0 is the polynomial layer, a written canonical-form specification, pattern matching as data, and assumptions that travel with a node; v2.0 is the rewrite graph. Publishing a package version spends a label the roadmap was using, which is what happened to 2.0.0 while tier 1 is still unfinished. The three conditions #746 puts on every tier are listed with it, and the release checklist now says what 2.0.0 skipped: a performance column measured against the previous one on the same machine. CLAUDE.md is added as a pointer to AGENTS.md, carrying the four things most often learned the hard way, so a tool looking for that filename does not start from nothing. And mathlib4 joins the reference list, for the one thing it is unmatched at: the hypotheses of an identity. Checked after the fact, its Real.arcsin_sin, Real.arccos_cos, Real.arctan_tan and Real.tan_arctan carry exactly the four intervals this library now guards with -- including the open-versus-closed distinction between arctan and arcsin. Reading four lines would have been quicker than the measurements that produced them. Two caveats recorded with it, since both cost something today. Real.sin_arcsin needs -1 <= x <= 1 and we need no condition at all, because mathlib's arcsin clamps where ours goes complex -- a convention difference, not a mathematical one. And mathlib has no arccot, which is exactly the rule this library got wrong twice.
AGENTS.md itself says not to record wrong turns in the code or the documentation, and the previous commit here did exactly that: the roadmap section and the mathlib section each explained themselves by naming what had gone wrong instead of stating the rule. Same content, told forwards. Check #746 before picking a version and say on the issue which tier the release advances; measure the previous performance column again on the same machine and publish the pair, because a uniform factor across every row is the machine rather than the code; mathlib's hypotheses are where to look first, its arcsin clamps where ours goes complex, and it has no arccot at all. The incidents are kept, in the workspace's own CLAUDE.md on the other side of the submodule boundary, where a post-mortem does not ship to users.
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.
Documentation only. Two additions, both aimed at things being read before they are needed rather than pointed out afterwards.
1.
AGENTS.md— read the roadmap before a release#746 is the ten-year vision, and nothing
pointed at it from the instructions an agent or a new contributor actually reads. Two things in it are
easy to break by accident and impossible to undo:
v1.0–v9.0are capability tiers, not versions.v1.0is "a symbolic engine worth buildingon" — polynomial layer, a written canonical-form specification, pattern matching as data, assumptions
travelling with a node.
v2.0is "the rewrite graph". Choosing a package version spends a label theroadmap is using, so it is worth checking the issue first and saying there which tier a release does
and does not advance.
else it delivered: the common case pays for nothing it does not use (package boundaries decided
early, since a published one cannot move — its item 78), speed and memory measured rather than hoped
for, and correctness coverage growing with the surface.
With a release checklist that follows from them, including the one thing easiest to get wrong about
the performance table: re-measure the previous column on the same machine and publish the pair,
because columns from different hardware cannot be read as a ratio and a uniform factor across every row
is the machine rather than the code.
CLAUDE.mdis added as a pointer toAGENTS.md, so a tool looking for that filename finds its way,carrying four rules in case nothing else is read.
2. mathlib4, for the hypotheses of an identity
SimplificationContract.mdasks a rule to state its assumption set and did not say where to find one.For classical analysis, mathlib4 has already
stated and machine-checked them — Lean does not accept a lemma otherwise.
The intervals this library guards the inverse-trigonometric cancellations with are the ones mathlib
states, checked against the current docs:
Real.arcsin_sin (hx₁ : -(π / 2) ≤ x) (hx₂ : x ≤ π / 2) : arcsin (sin x) = xWithinHalfPi(closed: true)Real.arccos_cos (hx₁ : 0 ≤ x) (hx₂ : x ≤ π) : arccos (cos x) = xWithinZeroAndPi(closed: true)Real.arctan_tan (hx₁ : -(π / 2) < x) (hx₂ : x < π / 2) : arctan (tan x) = xWithinHalfPi(closed: false)@[simp] Real.tan_arctan (x : ℝ) : tan (arctan x) = x— no hypothesisIncluding the open-versus-closed distinction between
arctanandarcsin, and the fact that theright-inverse direction carries no hypothesis at all — §5 of the contract in someone else's notation.
Two warnings go with it, because the lookup is not mechanical.
Real.sin_arcsinrequires-1 ≤ x ≤ 1and we need no such condition, because mathlib'sarcsinclamps outside[-1, 1]to staya total real function while ours continues into the complex plane — a difference of convention, not of
mathematics. And mathlib has no
arccot, which is where this library departs furthest from thetextbooks: its range is
(-pi/2, pi/2], soarccotan(-1)is-pi/4(#887). Where the lookup is empty, measure at
a positive argument, a negative one and zero, and write the three values into the comment.
Why this shape
Leibniz's characteristica universalis wanted three things: a perfectly logical language, an
encyclopedia of verified knowledge, and an engine of reason. #746's
v7.0already plans the bridge tothe first two. The point of this PR is narrower and available now: the encyclopedia is usable today,
with no dependency and no bridge, as a place to look up a side condition — which is the single thing
this library's rules have most often been missing.
No code changes;
AGENTS.md, a newCLAUDE.md, and one section inSimplificationContract.md.