declaring-invariants

Find tests that enumerate a domain by copying it, and declare the invariants a
codebase depends on. Stdlib ast only — no install, no config file, no
network. Python.

python3 scripts/totality_lint.py <repo>   # tests that copy a domain
python3 scripts/claims.py <repo>          # what the repo declares, and what backs it

Features

• Copied-domain detection — a parametrize or for over a literal whose
  members are a strict subset of a dict/set/tuple/Enum in the source, with the
  uncovered members named
• Ratchets, the second claim form — an enumeration loops whatever the
  domain now holds, so it cannot see the domain narrowing.
  # totality: ratchet — <why> marks a hand-list as a deliberate floor, and the
  linter checks the pin: ratchet-broken names a member that left, statically,
  before any test runs. unratcheted names a registry with an enumeration and
  no floor
• Vacuity detection — a live registry iterated with no len(...) >= n
  assertion, which passes over an emptied collection
• Membership join — [1, 2, 3, 4, 8] and SUPPORTED_BITS share no token,
  so containment is the join key; no naming convention is assumed
• Reachability filter — a literal matches a registry only when the test
  imports its module, shares its top-level directory, or is its paired
  tests/test_<mod>.py
• First-class acknowledgement — # totality: partial — <why> retires a
  finding, and an acknowledgement on a test that later covers the whole domain
  is reported as stale-ack
• Claim inventory — a claim is a test whose docstring opens invariant:,
  and refuted: records the observed negative control
• Report by default — --strict opts into a nonzero exit; --json for
  machine consumption; --selftest runs fixtures with no repo

Why

On oaustegard/remex, adding a fourth member to ROTATION_CODES with no
construction behind it left the entire 267-test suite green. Four tests looked
total; each parametrized ["haar", "rht"] against a three-member registry.

The other direction is worse. Substituting "xyz" for "none" in both
spellings of that domain — cardinality unchanged, both spellings agreeing — left
the domain floor, the enumeration and the parity check green, five passing tests
over a registry that had stopped supporting a rotation every index on disk was
written with. That is what the ratchet form is for.

Adapted from the meta-oracle in
daniloc/coherence, which classifies
an oracle's iteration root as LIVE or LITERAL by parsing the oracle's own AST.
The check needs none of that harness's spec files, claim grammar, ledger or
Node runtime.

See SKILL.md for the full reference, including how to write a
refutation you have actually observed.

Skill folder: declaring-invariants

Release of declaring-invariants version 0.2.3

📥 Download & Install

⬇️ Download declaring-invariants.zip

To install:

1. Click the download link above (ignore the "Source code" archives below - they're auto-generated by GitHub)
2. Go to Claude.ai Skills Settings
3. Upload the downloaded ZIP file
4. Requires paid Claude Pro or Team account

See official documentation for more details.

Recent Changes

559c886 declaring-invariants: a skill for domains a test copies instead of loops (#773)