Repository navigation
Description
The quality theme from the 2026-11-17 loop retro (maintainer-approved).
What happens today. Sixteen structural tests guard a shrinking list with one integer beside it, for example:
| Test | Pin |
|---|---|
tests/test_cli_numeric_options_declare_a_range.py |
NOT_YET_PINNED_SIZE = 40 |
tests/test_tests_drive_the_surface_not_the_mock.py |
ALLOWLIST_SIZE = 52 |
tests/test_every_entry_point_passes_the_policy.py |
REST_NOT_YET_MIGRATED_SIZE = 67, MCP_NOT_YET_MIGRATED_SIZE = 106, REST_WRITE_TIER_NOT_YET_MIGRATED_SIZE = 10, PUBLIC_ENTRY_POINTS_SIZE = 8, two more |
tests/test_layer_boundaries.py |
ALLOWLIST_SIZE = 21, COMPOSITION_ROOTS_SIZE = 33 |
tests/test_response_text_is_pyrites.py |
ALLOWED_SIZE = 2 |
tests/characterization/ |
PINNED_MCP_TOOL_COUNT, PINNED_REST_OPERATION_COUNT, PINNED_MCP_TOTAL_TOOL_COUNT |
(git grep -nE '^[A-Z_]*(SIZE|COUNT|PINNED|TOTAL)[A-Z_]* *= *[0-9]+' -- tests lists them all.)
The rule each one states is right: the list only shrinks, and raising it is a reviewed decision. The cost is in how it is stated. Every pull request that removes a row must also edit the one line that holds the count, so two honest pull requests that remove different rows conflict with each other. It has started: #1595 and #1599, both from a first-time contributor, each remove rows from the numeric-option list and conflict on NOT_YET_PINNED_SIZE. Seven more per-module issues under #1541 will do the same, and the 0.26.5 themes plan dozens of slices that each lower REST_NOT_YET_MIGRATED_SIZE or MCP_NOT_YET_MIGRATED_SIZE (#1532, #1529). A conflict on the pin sends a contributor back for a rebase: 16 of 27 open outside pull requests were waiting on one when this was filed.
The property. A ratchet says "this list only shrinks" in a way that lets any two pull requests that remove different rows merge without touching the same line. Adding a row stays a visible, reviewed change.
Options
- (B, recommended) The list is its own pin; a range check guards growth. Drop the count constant where the rows are hand-written in the test file (one row per line, sorted, so removals do not collide). Add
scripts/check_ratchets_only_shrink.py --range BASE HEAD, run in CI besidescripts/check_fix_commit_has_tests.py: for each registered ratchet list it compares the rows at BASE and HEAD and fails when a row was added, unless the commit that adds it carries aRatchet-raise: <list> <reason>trailer. "Never raise it" is then enforced where it can be seen, on the diff, instead of by a number two people must both edit. - (A, fallback) A pin per module or per section. Keep counts but split each into one per source file or surface, as
tests/test_kb_reads_are_one_function.pyalready does with its per-file rows. Fewer collisions, not none. - (C) Leave it. Rejected by the retro: the collisions land on contributors.
If (B) turns out not to hold for a list (for example one generated from a walk, such as the characterization counts), say why and use (A) for that list.
Slices
NOT_YET_PINNED_SIZEfirst (small, and it unblocks fix(sw): declare min=0 on limit and offset for sw list commands (#1565) #1595, fix(wiki): declare min=1 on limit for wiki stubs (#1560) #1599 and the other Every numeric CLI option declares its range, and a test says so #1541 slices now): the numeric-option list under option (B) or (A), with the range check introduced for this one list.- The rest, one pull request: every pin in the table, the range check registered for each, and the comments that say "lower it with every entry removed" updated to say what now enforces it. Lands before the 0.26.5 theme waves that lower the REST and MCP lists.
Acceptance
- For each converted ratchet: two branches that each remove a different row merge into each other with no conflict in the test file (show it once with
git merge-treein the PR; no test needs to run git). - Adding a row without the trailer fails the range check; adding it with the trailer passes; removing rows passes. The check has its own tests, as
tests/test_fix_commit_check.pyhas. - A row removed from the source but left in the list still fails the structural test (stale rows are caught as they are today).
- CONTRIBUTING, "Running the tests", says in two sentences how to remove a row and how a row is added.
Footprint. tests/ and scripts/ only, one CI step in .github/workflows/ci.yml (the maintainer merges that file), CONTRIBUTING. No production file. Sonnet, M (slice 1: S). Cold read not needed; the range check gets a careful review since it becomes a gate.
🤖 Filed by the maintainer's conductor agent from the 2026-11-17 retro (Claude Code)
Activity
markramm commentedon Nov 17, 2026
Slice 1 (the numeric-option list, option B) is dispatched to a cloud worker by the maintainer's conductor agent, 2026-11-17. Its draft pull request will be linked here when it opens. Slice 2 (the other pins) is not claimed.
markramm commentedon Nov 17, 2026
Slice 1 claimed: draft pull request #1614.
Generated by Claude Code
test: a range check refuses a row added to a ratchet list without a R…
test: the numeric-option NOT_YET list is its own pin, groups separate…
test: give the ratchet check's subprocess calls a deadline (#1608)
ci: run the ratchet range check beside the fix-commit check (#1608)
docs: how a ratchet row is removed and how one is added (#1608)
kb: #1608 slice 1 is done, backlog item to done/
kb: #1608 slice 1 backlog item status is done
Merge origin/dev into the #1608 slice 1 branch
Merge origin/dev into the #1608 slice 1 branch (second time)
Merge origin/dev into the #1608 slice 1 branch (third time)