maths-laws
Authors Puck.Maths.Tests laws: laws/*.json rows, LawRegistry bindings, oracles, legs, waivers, structural law completeness. Primitive choice: maths-usage.
SKILL.md.claude/skills/maths-laws/SKILL.md
GitHubWriting a Puck.Maths law that bites
This skill owns authoring and validating tests/Puck.Maths.Tests. The suite's
code and tests are authoritative; reconcile its README, XML documentation and
this skill with them when they disagree.
What a law is for
AGENTS.md sets the owner's target for the suite: the smallest set of tests
that reaches 100% line coverage, plus a short keep-list of invariant tests that
coverage cannot see (determinism, exact fixed-point results). That shapes every
decision here.
- Write a law where running the change cannot show the behavior: an exact
fixed-point result, a refusal or overflow boundary, a determinism property.
CI requires 100% line coverage of live
src/, so a new public member lands with a law (or an existing test) that reaches it. - Author at the
Defaulttier. A Deep row that only draws more random operands from its Default sibling's domain adds no evidence and no line coverage; write one only for a domain Default cannot reach (the exhaustive edge cross product, a whole finite carrier, a longer ladder), and delete a mirror you touch that does not. - The owner's ruling deletes the Maths coverage ratchet, its floor, all recorded registers and their generator. Keep structural declaration/binding completeness and member-reference checks against current LawRegistry data; write no recorded artifact.
Required workflow
- Declare a law in two places and nowhere else: the declaration (id, tier,
covered members, legs) as a JSON row in
tests/Puck.Maths.Tests/laws/<family>.json, and one binding inLawRegistry.csor its per-family partial (ClaimCase,SweptCase, orCase(id, run)for any other run). A bare[Fact]runs but credits no member to the structural completeness check and declares no leg. A declaration without a binding, or a binding without a declaration, failsLawDeclarationTests.EveryDeclarationHasExactlyOneCaseby name. - Choose the cheapest honest tier by measured cost, not by whether the word
"exhaustive" fits.
Exhaustiveholds full-carrier sweeps and expensive finite checks, which take their own basis rather than aDomainand never imply a full-carrier proof. - State the claim, subject, operand domain and evidence legs explicitly.
- Instantiate the existing
Laws.cscombinators and shared domains instead of re-implementing their loops. - Give the claim independent evidence. A second expression of the same
implementation is not an oracle: reference arithmetic lives in
Oracles.cs, computed inBigInteger, and never calls aPuck.Mathskernel. - Classify every affected public Maths member with a covering law (
Membersin its declaration) or a precise waiver (Coverage.WaiverDeclarations).LawCompletenessTestsvalidates those references and waiver reasons without a baseline; declaration/binding parity lives inLawDeclarationTests. - When it is in doubt whether a new law can fail, apply a plausible one-line
mutation in a worktree of your own and watch the law go red, or run
puck laws prove <law> --fix <commit>(--file-listfor an uncommitted fix). Most laws are rows of one theory, whichpuck laws provecannot select one at a time; prove such a row with an exact mutation, failing at the intended assertion, and name the mutation in the commit. Never hand-revert files in a shared tree.
Deleting a law removes its JSON row, binding and any oracle only it used. Every run uses the same deterministic operand window; no counter is persisted.
Run a tier
Build the test project with -nodeReuse:false, then run it:
dotnet build tests/Puck.Maths.Tests/Puck.Maths.Tests.csproj -c Release -nodeReuse:false
dotnet test tests/Puck.Maths.Tests/Puck.Maths.Tests.csproj -c Release --no-build
-nodeReuse:false belongs to the build step only
(verification). The plain run is the
Default tier and includes the completeness and leg checks,
which only a run that includes the Default tier checks. Deep and Exhaustive
cases are explicit:
--explicit on --filter-trait tier=<tier>, and without --explicit on such a
filter selects no test. One law runs with
--explicit on --filter-display-name '<law-id>*'; the trailing wildcard is
required.
Load the full reference selectively
Read references/complete-reference.md for
the exact Case shape and combinators, tier budgets, the leg taxonomy and its
markers (ENVELOPE:, OWED:, MIRROR of, DOC GAP:), oracle standards,
domain construction, coverage categories and waivers, claim-body rules, the
mutation procedure and deliberate-correction rules.
Route adjacent work
| Skill | Use when |
|---|---|
maths-usage |
Selecting a Maths primitive, applying consumer determinism rules, or deciding which verification tier an implementation change owes. |
content-search |
Finding law ids, declarations, member names or textual patterns across the suite. |
symbol-analysis |
Resolving semantic C# references, overloads, implementers or rename and deletion safety. |
gaming-bricks |
Verifying a Maths change that reaches emulator code and its dedicated batteries. |
verification |
The landing bar, optional checks beyond the law suite, and the CLI copy. |