Skip to content

A ratchet's pin never makes two honest pull requests conflict #1608

Open

Description

@markramm

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 beside scripts/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 a Ratchet-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.py already 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

  1. NOT_YET_PINNED_SIZE first (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.
  2. 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-tree in 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.py has.
  • 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

  1. added this to the 0.26.4 milestone on Nov 17, 2026
  2. added
    help wantedExtra attention is needed
    processFriction in the development process itself (conductor, skills, scripts); the retro root-causes these
    qualityRefactoring, test refactoring, code health
    on Nov 17, 2026
  3. markramm commented on Nov 17, 2026

    @markramm
    CollaboratorAuthor

    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.

  4. markramm commented on Nov 17, 2026

    @markramm
    CollaboratorAuthor

    Slice 1 claimed: draft pull request #1614.


    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    help wantedExtra attention is neededprocessFriction in the development process itself (conductor, skills, scripts); the retro root-causes thesequalityRefactoring, test refactoring, code health

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions