From 32dac0491e261659a7f74b41ff6306ed09c4bedf Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 13:34:43 +0000 Subject: [PATCH 1/8] kb: claim #1608 slice 1, the numeric-option ratchet is its own pin Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_013BnEiZFj8CP7nEnkefXVU3 --- ...-honest-pull-requests-conflict-the-numeric.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 kb/backlog/a-ratchet-s-pin-never-makes-two-honest-pull-requests-conflict-the-numeric.md diff --git a/kb/backlog/a-ratchet-s-pin-never-makes-two-honest-pull-requests-conflict-the-numeric.md b/kb/backlog/a-ratchet-s-pin-never-makes-two-honest-pull-requests-conflict-the-numeric.md new file mode 100644 index 000000000..8a3764fd1 --- /dev/null +++ b/kb/backlog/a-ratchet-s-pin-never-makes-two-honest-pull-requests-conflict-the-numeric.md @@ -0,0 +1,16 @@ +--- +id: a-ratchet-s-pin-never-makes-two-honest-pull-requests-conflict-the-numeric +title: "A ratchet's pin never makes two honest pull requests conflict: the numeric-option list (#1608, slice 1)" +type: backlog_item +tags: +- quality +importance: 5 +kind: improvement +status: in_progress +priority: high +assignee: agent:cloud-worker +effort: S +rank: 0 +--- + +Drops NOT_YET_PINNED_SIZE so the numeric-option list is its own pin, and adds scripts/check_ratchets_only_shrink.py, a CI range check that fails when a registered list gains a row unless a commit in the range carries a Ratchet-raise trailer. Two pull requests that remove different rows then merge without touching the same line. From 0b47252525c5fc7ae39bec219e8ebfaff1c493c8 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 13:36:38 +0000 Subject: [PATCH 2/8] test: a range check refuses a row added to a ratchet list without a Ratchet-raise trailer (#1608) Reads each registered list at BASE and HEAD with git show + ast (never imports the test module); removals pass, additions need the trailer, an unreadable list fails by name. Registry holds NOT_YET only in slice 1. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_013BnEiZFj8CP7nEnkefXVU3 --- scripts/check_ratchets_only_shrink.py | 185 ++++++++++++++ tests/test_check_ratchets_only_shrink.py | 313 +++++++++++++++++++++++ 2 files changed, 498 insertions(+) create mode 100755 scripts/check_ratchets_only_shrink.py create mode 100644 tests/test_check_ratchets_only_shrink.py diff --git a/scripts/check_ratchets_only_shrink.py b/scripts/check_ratchets_only_shrink.py new file mode 100755 index 000000000..fd922a7c8 --- /dev/null +++ b/scripts/check_ratchets_only_shrink.py @@ -0,0 +1,185 @@ +#!/usr/bin/env python3 +"""Refuse a pull request that adds a row to a ratchet list (#1608). + +A ratchet is a hand-written list that may only shrink. Removing rows needs no +other edit, so two pull requests that remove different rows never touch the +same line. Adding a row is a reviewed decision: it fails this check unless a +commit in BASE..HEAD carries a trailer in its final paragraph: + + Ratchet-raise: + +Usage: ``check_ratchets_only_shrink.py --range BASE HEAD`` (exit 0 pass, 1 a +row was added without the trailer or a list could not be read, 2 usage). + +For each ``(path, name)`` in REGISTRY the script reads the file at BASE and at +HEAD with ``git show``, parses it with ``ast`` (it never imports the file), +finds the module-level assignment to ``name`` and reads its rows with +``ast.literal_eval``: a set, list or tuple gives its elements, a dict its keys. +A list absent at BASE counts as empty there. A file or name missing at HEAD, +or a value that is not a literal, FAILS: the check never passes by not being +able to look. Stdlib only. +""" + +from __future__ import annotations + +import ast +import subprocess +import sys +from pathlib import Path + +# (path, name) of every ratchet list guarded by the range check. Slice 2 of +# #1608 registers the others. +REGISTRY: list[tuple[str, str]] = [ + ("tests/test_cli_numeric_options_declare_a_range.py", "NOT_YET"), +] + +TRAILER_KEY = "Ratchet-raise" + + +class RatchetReadError(Exception): + """The list cannot be read as a literal; the message says why.""" + + +def read_rows(source: str, name: str) -> set: + """The rows of the module-level literal ``name`` in ``source``. + + Raises RatchetReadError when the name is not assigned at module level or + its value is not a literal set, list, tuple or dict. + """ + try: + tree = ast.parse(source) + except SyntaxError as exc: + raise RatchetReadError(f"the file does not parse ({exc.msg}, line {exc.lineno})") from exc + value = None + for node in tree.body: # the last module-level assignment wins, as at import + if isinstance(node, ast.Assign): + if any(isinstance(t, ast.Name) and t.id == name for t in node.targets): + value = node.value + elif isinstance(node, ast.AnnAssign): + if isinstance(node.target, ast.Name) and node.target.id == name and node.value: + value = node.value + if value is None: + raise RatchetReadError(f"no module-level assignment to {name}") + try: + literal = ast.literal_eval(value) + except (ValueError, TypeError, SyntaxError, MemoryError, RecursionError) as exc: + raise RatchetReadError( + f"the value of {name} is not a literal (a set, list, tuple or dict of literals)" + ) from exc + if isinstance(literal, dict): + return set(literal.keys()) + if isinstance(literal, (set, frozenset, list, tuple)): + return set(literal) + raise RatchetReadError(f"{name} is a {type(literal).__name__}, not a set, list, tuple or dict") + + +def _git(args: list[str], cwd) -> subprocess.CompletedProcess: + return subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True) + + +def _show(rev: str, path: str, cwd) -> str | None: + """File contents at ``rev``, None when the path does not exist there. + + An unknown revision raises CalledProcessError (git's own error). + """ + _git_ok(["rev-parse", "--verify", "--quiet", f"{rev}^{{commit}}"], cwd) + result = _git(["cat-file", "-e", f"{rev}:{path}"], cwd) + if result.returncode != 0: + return None + return _git_ok(["show", f"{rev}:{path}"], cwd).stdout + + +def _git_ok(args: list[str], cwd) -> subprocess.CompletedProcess: + result = _git(args, cwd) + if result.returncode != 0: + raise subprocess.CalledProcessError( + result.returncode, ["git", *args], output=result.stdout, stderr=result.stderr + ) + return result + + +def raised_lists(base: str, head: str, cwd=None) -> set[str]: + """Names with a non-empty-reason ``Ratchet-raise`` trailer in base..head.""" + out = _git_ok( + [ + "log", + f"--format=%x01%(trailers:key={TRAILER_KEY},valueonly,unfold)", + f"{base}..{head}", + ], + cwd, + ).stdout + names: set[str] = set() + for line in out.replace("\x01", "\n").splitlines(): + parts = line.strip().split(None, 1) + if len(parts) == 2 and parts[1].strip(): + names.add(parts[0]) + return names + + +def check_range(base: str, head: str, registry=None, cwd=None) -> int: + """0 if no registered list gained a row without its trailer, else 1.""" + registry = REGISTRY if registry is None else registry + raised = raised_lists(base, head, cwd) + failed = False + for path, name in registry: + head_src = _show(head, path, cwd) + if head_src is None: + print( + f"ERROR: {path} does not exist at {head}, so ratchet list {name} cannot be read.\n" + " Renaming or moving a ratchet needs its registry entry in " + "scripts/check_ratchets_only_shrink.py updated in the same change.", + file=sys.stderr, + ) + failed = True + continue + try: + head_rows = read_rows(head_src, name) + except RatchetReadError as exc: + print( + f"ERROR: cannot read ratchet list {name} in {path} at {head}: {exc}.\n" + " Keep it a literal, or update scripts/check_ratchets_only_shrink.py.", + file=sys.stderr, + ) + failed = True + continue + base_src = _show(base, path, cwd) + base_rows: set = set() + if base_src is not None: + try: + base_rows = read_rows(base_src, name) + except RatchetReadError: + base_rows = set() # not a readable list at BASE: counts as empty there + added = sorted(head_rows - base_rows, key=repr) + if not added or name in raised: + continue + failed = True + print( + f"ERROR: ratchet list {name} in {path} gained {len(added)} row(s) " + f"between {base} and {head}:", + file=sys.stderr, + ) + for row in added: + print(f" {row!r}", file=sys.stderr) + print( + " A ratchet list only shrinks. Remove the rows, or if adding them is deliberate, " + "put this line in the final paragraph of a commit message in the range:\n" + f" {TRAILER_KEY}: {name} ", + file=sys.stderr, + ) + return 1 if failed else 0 + + +def main(argv: list[str] | None = None) -> int: + argv = sys.argv[1:] if argv is None else argv + if len(argv) != 3 or argv[0] != "--range": + print("usage: check_ratchets_only_shrink.py --range BASE HEAD", file=sys.stderr) + return 2 + try: + return check_range(argv[1], argv[2], cwd=Path.cwd()) + except subprocess.CalledProcessError as exc: + print(f"ERROR: {' '.join(exc.cmd)} failed:\n{exc.stderr}", file=sys.stderr) + return exc.returncode or 1 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/test_check_ratchets_only_shrink.py b/tests/test_check_ratchets_only_shrink.py new file mode 100644 index 000000000..ab057f84b --- /dev/null +++ b/tests/test_check_ratchets_only_shrink.py @@ -0,0 +1,313 @@ +"""Tests for scripts/check_ratchets_only_shrink.py (#1608, slice 1). + +The property: a registered ratchet list only shrinks. Removing rows passes +(and two pull requests removing different rows never touch the same line); +adding a row fails unless a commit in BASE..HEAD carries the trailer +``Ratchet-raise: ``. Every case builds a throwaway git +repository in ``tmp_path``; the real repository is never touched. +""" + +from __future__ import annotations + +import subprocess +import sys +from pathlib import Path + +import pytest + +SCRIPT = Path(__file__).resolve().parent.parent / "scripts" / "check_ratchets_only_shrink.py" +sys.path.insert(0, str(SCRIPT.parent)) + +import check_ratchets_only_shrink as crs # noqa: E402 + +FILE = "ratchet.py" +NAME = "NOT_YET" +REG = [(FILE, NAME)] + + +class Repo: + def __init__(self, path: Path): + self.path = path + self.git("init", "-q", "-b", "main") + self.git("config", "user.name", "Test") + self.git("config", "user.email", "test@example.com") + self.git("config", "commit.gpgsign", "false") + + def git(self, *args: str) -> str: + return subprocess.run( + ["git", *args], cwd=self.path, capture_output=True, text=True, check=True + ).stdout.strip() + + def write(self, text: str, path: str = FILE) -> None: + (self.path / path).write_text(text) + + def commit(self, message: str = "change") -> str: + self.git("add", "-A") + self.git("commit", "-q", "--allow-empty", "-m", message) + return self.git("rev-parse", "HEAD") + + def run(self, base: str, head: str = "HEAD", registry=REG) -> int: + return crs.check_range(base, head, registry=registry, cwd=self.path) + + +@pytest.fixture +def repo(tmp_path): + return Repo(tmp_path) + + +def literal(rows, form="set", annotated=False, name=NAME): + body = ", ".join(repr(r) for r in rows) + if form == "set": + value = "{" + body + "}" if rows else "set()" + elif form == "list": + value = "[" + body + "]" + elif form == "tuple": + value = "(" + body + ("," if len(rows) == 1 else "") + ")" + elif form == "dict": + value = "{" + ", ".join(f"{r!r}: 'why'" for r in rows) + "}" + else: + raise AssertionError(form) + ann = ": object" if annotated else "" + return f"{name}{ann} = {value}\n" + + +def two_commits(repo, before, after, message="change"): + repo.write(before) + base = repo.commit("base") + repo.write(after) + repo.commit(message) + return base + + +ROWS = [("a x", "limit"), ("b y", "limit"), ("c z", "offset")] + + +@pytest.mark.parametrize( + "kept", + [ROWS[:2], ROWS[1:], [ROWS[0]], []], + ids=["one-removed", "one-removed-other", "several-removed", "all-removed"], +) +def test_removing_rows_passes(repo, kept): + base = two_commits(repo, literal(ROWS), literal(kept)) + assert repo.run(base) == 0 + + +def test_adding_a_row_without_trailer_fails_and_names_the_row_and_list(repo, capsys): + base = two_commits(repo, literal(ROWS), literal(ROWS + [("d w", "limit")])) + assert repo.run(base) == 1 + err = capsys.readouterr().err + assert NAME in err and FILE in err + assert "('d w', 'limit')" in err + assert "Ratchet-raise: NOT_YET " in err + + +def test_each_added_row_is_printed_on_its_own_line(repo, capsys): + base = two_commits(repo, literal(ROWS), literal(ROWS + [("d w", "limit"), ("e v", "limit")])) + assert repo.run(base) == 1 + lines = capsys.readouterr().err.splitlines() + assert sum("('d w', 'limit')" in ln for ln in lines) == 1 + assert sum("('e v', 'limit')" in ln for ln in lines) == 1 + assert not any("('d w', 'limit')" in ln and "('e v', 'limit')" in ln for ln in lines) + + +GROWN = ROWS + [("d w", "limit")] + + +def test_trailer_on_the_adding_commit_passes(repo): + base = two_commits( + repo, + literal(ROWS), + literal(GROWN), + "change\n\nwhy\n\nRatchet-raise: NOT_YET a new command ships unbounded for now", + ) + assert repo.run(base) == 0 + + +def test_trailer_on_a_different_commit_of_the_range_passes(repo): + repo.write(literal(ROWS)) + base = repo.commit("base") + repo.write(literal(GROWN)) + repo.commit("adds the row") + repo.commit("later\n\nbody\n\nRatchet-raise: NOT_YET the row is deliberate") + assert repo.run(base) == 0 + + +@pytest.mark.parametrize( + "message", + [ + "change\n\nbody\n\nRatchet-raise: OTHER_LIST a reason", + "change\n\nbody\n\nRatchet-raise: NOT_YET", + "change\n\nbody\n\nRatchet-raise: NOT_YET ", + "change\n\nRatchet-raise: NOT_YET a reason\n\nand then more prose after it", + "change\n\nNote: Ratchet-raise: NOT_YET a reason, said in prose", + "Ratchet-raise: NOT_YET a reason in the subject", + "change", + ], + ids=[ + "other-list", + "no-reason", + "blank-reason", + "not-the-final-paragraph", + "inside-prose", + "in-subject", + "no-trailer", + ], +) +def test_a_trailer_that_does_not_count_fails(repo, message): + base = two_commits(repo, literal(ROWS), literal(GROWN), message) + assert repo.run(base) == 1 + + +def test_one_removed_and_a_different_one_added_fails(repo, capsys): + swapped = [ROWS[0], ROWS[1], ("d w", "limit")] + assert len(swapped) == len(ROWS) + base = two_commits(repo, literal(ROWS), literal(swapped)) + assert repo.run(base) == 1 + assert "('d w', 'limit')" in capsys.readouterr().err + + +def test_reordering_and_comment_changes_pass(repo): + before = "# first\n" + literal(ROWS) + after = "# a different comment\n" + literal(list(reversed(ROWS))).replace( + "{", "{\n # note\n", 1 + ) + base = two_commits(repo, before, after) + assert repo.run(base) == 0 + + +@pytest.mark.parametrize("annotated", [False, True], ids=["plain", "annotated"]) +@pytest.mark.parametrize("form", ["set", "list", "tuple", "dict"]) +def test_every_container_form_is_read(repo, form, annotated): + before = literal(ROWS, form, annotated) + after = literal(GROWN, form, annotated) + base = two_commits(repo, before, after) + assert repo.run(base) == 1 # the added row was seen + assert crs.read_rows(after, NAME) == set(GROWN) + assert crs.read_rows(before, NAME) == set(ROWS) + repo.write(literal(ROWS[:1], form, annotated)) + repo.commit("shrink") + assert repo.run(base) == 0 + + +def test_the_name_missing_at_head_fails_named(repo, capsys): + base = two_commits(repo, literal(ROWS), literal(ROWS, name="RENAMED")) + assert repo.run(base) == 1 + err = capsys.readouterr().err + assert FILE in err and NAME in err + + +def test_the_file_missing_at_head_fails_named(repo, capsys): + repo.write(literal(ROWS)) + base = repo.commit("base") + repo.write("x = 1\n", "other.py") + repo.git("rm", "-q", FILE) + repo.commit("removes the file") + assert repo.run(base) == 1 + err = capsys.readouterr().err + assert FILE in err and NAME in err + + +def test_a_value_that_is_not_a_literal_fails_named(repo, capsys): + base = two_commits(repo, literal(ROWS), "x = [1]\nNOT_YET = set(x)\n") + assert repo.run(base) == 1 + err = capsys.readouterr().err + assert FILE in err and NAME in err + + +def test_a_syntax_error_at_head_fails_named(repo, capsys): + base = two_commits(repo, literal(ROWS), "NOT_YET = {\n") + assert repo.run(base) == 1 + assert NAME in capsys.readouterr().err + + +def test_a_list_missing_at_base_needs_the_trailer(repo): + repo.write("x = 1\n") + base = repo.commit("base") + repo.write(literal(ROWS)) + head = repo.commit("introduces the list") + assert repo.run(base, head) == 1 + repo.commit("more\n\nbody\n\nRatchet-raise: NOT_YET a seeded list of existing rows") + assert repo.run(base) == 0 + + +def test_a_file_missing_at_base_counts_as_empty(repo): + repo.write("x = 1\n", "other.py") + base = repo.commit("base") + repo.write(literal(ROWS)) + repo.commit("adds the file") + assert repo.run(base) == 1 + + +def test_a_merge_commit_that_brings_no_new_row_passes(repo): + repo.write(literal(ROWS)) + base = repo.commit("base") + repo.git("checkout", "-q", "-b", "topic") + repo.write(literal(ROWS[1:])) + repo.commit("topic removes a row") + repo.git("checkout", "-q", "main") + repo.write(literal(ROWS) + "# dev moved\n", "notes.py") + repo.commit("dev moves on") + repo.git("checkout", "-q", "topic") + repo.git("merge", "-q", "--no-edit", "main") + assert len(repo.git("rev-list", "--merges", f"{base}..HEAD").splitlines()) == 1 + assert repo.run(base) == 0 + + +def test_an_unknown_revision_fails_with_gits_error(repo): + repo.write(literal(ROWS)) + repo.commit("base") + with pytest.raises(subprocess.CalledProcessError): + repo.run("no-such-revision") + + +def test_the_trailer_must_name_the_list_exactly(repo): + base = two_commits( + repo, literal(ROWS), literal(GROWN), "c\n\nb\n\nRatchet-raise: NOT_YET_MORE a reason" + ) + assert repo.run(base) == 1 + + +# ---- the script itself -------------------------------------------------- + + +def run_script(repo, *args): + return subprocess.run( + [sys.executable, str(SCRIPT), *args], cwd=repo.path, capture_output=True, text=True + ) + + +def test_the_script_exits_2_on_usage_error(repo): + for args in ([], ["--range"], ["--range", "a"], ["--bogus", "a", "b"]): + r = run_script(repo, *args) + assert r.returncode == 2, args + + +def test_the_script_with_the_real_registry_fails_when_its_files_are_missing(repo): + """Run in a repository that has none of the registered files: each is named.""" + repo.write("x = 1\n", "other.py") + base = repo.commit("base") + repo.commit("empty") + r = run_script(repo, "--range", base, "HEAD") + assert r.returncode == 1 + for path, name in crs.REGISTRY: + assert path in r.stderr and name in r.stderr + + +def test_the_script_with_an_unknown_revision_exits_non_zero(repo): + repo.write("x = 1\n") + repo.commit("base") + r = run_script(repo, "--range", "nope", "HEAD") + assert r.returncode not in (0, 2) + assert "nope" in r.stderr + + +# ---- the registry ------------------------------------------------------- + + +def test_every_registered_list_exists_in_the_working_tree_and_is_readable(): + root = SCRIPT.parent.parent + assert crs.REGISTRY, "the registry is empty" + for path, name in crs.REGISTRY: + source = (root / path).read_text() + rows = crs.read_rows(source, name) + assert rows, f"{path}:{name} is readable but empty; delete its registry entry" From a7ea363f332800494cf0bd7879fb71ebf68adb56 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 13:37:41 +0000 Subject: [PATCH 3/8] test: the numeric-option NOT_YET list is its own pin, groups separated so removals merge (#1608) Drops NOT_YET_PINNED_SIZE and its two tests; the range check (scripts/check_ratchets_only_shrink.py) now refuses growth. A comment-only '#' line between module groups keeps adjacent group removals from touching. test_listed_rows_are_not_stale is unchanged and still catches stale rows. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_013BnEiZFj8CP7nEnkefXVU3 --- ...est_cli_numeric_options_declare_a_range.py | 59 +++++++++++-------- 1 file changed, 34 insertions(+), 25 deletions(-) diff --git a/tests/test_cli_numeric_options_declare_a_range.py b/tests/test_cli_numeric_options_declare_a_range.py index 96418cb0c..a5c99b96a 100644 --- a/tests/test_cli_numeric_options_declare_a_range.py +++ b/tests/test_cli_numeric_options_declare_a_range.py @@ -3,8 +3,10 @@ The property: every ``int`` or ``float`` option or argument of every registered command has ``min`` or ``max`` on it (so click refuses an out-of-range value as a usage error, exit 2, before any code runs), or sits on the reviewed ``UNBOUNDED`` -list with the reason no range makes sense, or on the seeded ``NOT_YET`` list. A -new numeric option without a range fails here. +list with the reason no range makes sense, or on the seeded ``NOT_YET`` list, which may only +shrink: ``scripts/check_ratchets_only_shrink.py`` refuses an added row in CI unless a +commit carries ``Ratchet-raise: NOT_YET ``. A new numeric option without a +range fails here. The list of commands is the registry, not a scan of the source: the click tree Typer builds from the three root apps, extension groups included, through the @@ -263,36 +265,59 @@ def registry() -> dict[str, object]: #: #1541: unbounded on ``dev`` today, grouped by the module that declares them. #: Each module is a good first issue: add the range where the option is -#: declared, delete its rows here (test (b) requires it) and lower -#: NOT_YET_PINNED_SIZE. The ``pyrite-read`` rows are the same declarations as -#: their ``pyrite`` twins, except ``timeline``: a second copy in read_cli.py. +#: declared and delete its rows here (``test_listed_rows_are_not_stale`` requires +#: it). Nothing else needs editing: this list is its own pin. +#: +#: It may shrink and never grow. Growth is refused on the diff, not by a count: +#: ``scripts/check_ratchets_only_shrink.py --range BASE HEAD`` (a CI step) fails a +#: pull request that adds a row unless one of its commits carries the trailer +#: ``Ratchet-raise: NOT_YET ``. +#: +#: Layout, so that two pull requests that remove different rows never touch the +#: same line: one row per line, and a line holding only ``#`` between module +#: groups (``ruff format`` deletes a blank line here and keeps this one). Delete +#: a group's comment line and rows and leave the separators: an unchanged line +#: then stands between your hunk and the next group's, so the two merge. +#: +#: The ``pyrite-read`` rows are the same declarations as their ``pyrite`` twins, +#: except ``timeline``: a second copy in read_cli.py. NOT_YET: set[tuple[str, str]] = { # pyrite/cli/search_commands.py ("pyrite search", "limit"), ("pyrite-read search", "limit"), + # # pyrite/cli/entry_commands.py (see also #1537) ("pyrite create", "importance"), ("pyrite update", "importance"), + # # pyrite/cli/browse_commands.py ("pyrite orient", "recent"), + # # pyrite/cli/__init__.py ("pyrite ci", "tier"), ("pyrite serve", "port"), + # # pyrite/cli/kb_commands.py ("pyrite kb create", "ttl"), + # # pyrite/cli/collection_commands.py ("pyrite collections query", "limit"), + # # pyrite/cli/qa_commands.py ("pyrite qa assess", "tier"), ("pyrite qa assess", "max_age"), + # # pyrite/cli/link_commands.py ("pyrite links batch-suggest", "limit_per_entry"), ("pyrite links orphans", "min_importance"), + # # pyrite/cli/task_commands.py ("pyrite task list", "priority"), + # # pyrite/read_cli.py ("pyrite-read timeline", "min_importance"), ("pyrite-read timeline", "limit"), + # # extensions/software-kb/src/pyrite_software_kb/cli.py ("pyrite sw adrs", "limit"), ("pyrite sw adrs", "offset"), @@ -302,6 +327,7 @@ def registry() -> dict[str, object]: ("pyrite sw standards", "offset"), ("pyrite sw components", "limit"), ("pyrite sw components", "offset"), + # # extensions/journalism-investigation/src/pyrite_journalism_investigation/cli.py ("pyrite investigation timeline", "min_importance"), ("pyrite investigation timeline", "limit"), @@ -316,17 +342,15 @@ def registry() -> dict[str, object]: ("pyrite investigation money-flow", "hops"), ("pyrite investigation export", "min_importance"), ("pyrite investigation dedup", "threshold"), + # # extensions/encyclopedia/src/pyrite_encyclopedia/cli.py ("pyrite wiki stubs", "limit"), + # # extensions/social/src/pyrite_social/cli.py ("pyrite social newest", "limit"), ("pyrite social top", "limit"), } -#: May shrink, never grow (#1541). Lower it in the same commit that deletes rows -#: from NOT_YET; raising it is the thing this test exists to refuse. -NOT_YET_PINNED_SIZE = 40 - FIX = "declare min= or max= in the option where it is declared, see #1541" @@ -408,7 +432,7 @@ def test_listed_rows_are_not_stale(): elif found.bounded: problems.append( f"{label} row `{command}` `{name}` is bounded now; delete the row " - "(and lower NOT_YET_PINNED_SIZE)" + "(nothing else to edit: NOT_YET is its own pin, see its comment)" ) unclassified = {u.row for u in unclassified_params(registry())} for command, name in sorted(UNCLASSIFIED): @@ -419,21 +443,6 @@ def test_listed_rows_are_not_stale(): assert not problems, "\n".join(problems) -def test_not_yet_may_shrink_and_never_grow(): - assert len(NOT_YET) <= NOT_YET_PINNED_SIZE, ( - f"NOT_YET has {len(NOT_YET)} rows, the pinned size is {NOT_YET_PINNED_SIZE}: " - f"it may shrink and never grow (#1541). Give the new option a range instead: {FIX}" - ) - - -def test_the_pin_is_not_slack(): - """The pin follows the list down: a smaller NOT_YET with the old pin would let - a later PR add rows back.""" - assert len(NOT_YET) == NOT_YET_PINNED_SIZE, ( - f"NOT_YET has {len(NOT_YET)} rows; lower NOT_YET_PINNED_SIZE ({NOT_YET_PINNED_SIZE}) to match" - ) - - def test_the_lists_do_not_overlap_and_every_reason_is_a_sentence(): both = sorted(NOT_YET & set(UNBOUNDED)) assert not both, f"on both NOT_YET and UNBOUNDED, pick one: {both}" From f019e05a59b42d55b9cc642d89a737beb34982cb Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 13:39:59 +0000 Subject: [PATCH 4/8] test: give the ratchet check's subprocess calls a deadline (#1608) Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_013BnEiZFj8CP7nEnkefXVU3 --- tests/test_check_ratchets_only_shrink.py | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/tests/test_check_ratchets_only_shrink.py b/tests/test_check_ratchets_only_shrink.py index ab057f84b..8f3714532 100644 --- a/tests/test_check_ratchets_only_shrink.py +++ b/tests/test_check_ratchets_only_shrink.py @@ -35,7 +35,12 @@ def __init__(self, path: Path): def git(self, *args: str) -> str: return subprocess.run( - ["git", *args], cwd=self.path, capture_output=True, text=True, check=True + ["git", *args], + cwd=self.path, + capture_output=True, + text=True, + check=True, + timeout=60, ).stdout.strip() def write(self, text: str, path: str = FILE) -> None: @@ -272,7 +277,11 @@ def test_the_trailer_must_name_the_list_exactly(repo): def run_script(repo, *args): return subprocess.run( - [sys.executable, str(SCRIPT), *args], cwd=repo.path, capture_output=True, text=True + [sys.executable, str(SCRIPT), *args], + cwd=repo.path, + capture_output=True, + text=True, + timeout=60, ) From d6ac1160684df078da62ddb7e6fdbfb6bee85271 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 13:40:01 +0000 Subject: [PATCH 5/8] ci: run the ratchet range check beside the fix-commit check (#1608) Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_013BnEiZFj8CP7nEnkefXVU3 --- .github/workflows/ci.yml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3ddca5d4f..51f099312 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -400,6 +400,15 @@ jobs: python scripts/check_fix_commit_has_tests.py --range HEAD^1 HEAD + # A ratchet list (scripts/check_ratchets_only_shrink.py REGISTRY) may only + # shrink: a row added in the PR's range fails unless a commit carries a + # `Ratchet-raise: ` trailer (#1608). Same range as above. + - name: "Check ratchet lists only shrink (pull_request only)" + if: github.event_name == 'pull_request' && matrix.shard == 1 + run: >- + python scripts/check_ratchets_only_shrink.py --range + HEAD^1 HEAD + # Advisory, never blocking (#278). #173 merged with its entry appended to # CHANGELOG.md under the already-released 0.24.3 heading, so the # [Unreleased] invariant test had nothing to catch and the fix was absent From 3ae3f36696602255dbe81127c4e0b41eb1229a51 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 13:40:02 +0000 Subject: [PATCH 6/8] docs: how a ratchet row is removed and how one is added (#1608) Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_013BnEiZFj8CP7nEnkefXVU3 --- CONTRIBUTING.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 77e5fe26b..9ec70d7e8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -391,6 +391,14 @@ experimental tests it left out. A new test of an experimental surface needs no marker if its path is mapped; a new file for one needs a line in `tests/experimental_surface.py`. +**Ratchets.** To remove a row from a list that may only shrink, delete its line: +there is no count to edit, so two pull requests that remove different rows +merge. A row is added only by a commit whose final paragraph carries +`Ratchet-raise: `; the CI step `scripts/check_ratchets_only_shrink.py +--range` refuses the pull request otherwise. This applies to `NOT_YET` in +`tests/test_cli_numeric_options_declare_a_range.py` today; #1608 converts the +other pinned lists. + **Each tree is tested once.** A `--run` that passes on a clean tree (nothing uncommitted in tracked files, no untracked `.py` file, and no untracked or gitignored file under `pyrite/`, `tests/`, `extensions/`, `kb/` or `scripts/` From f0686ad850f1abaaa643452c672be2d8ad7b242a Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 14:50:52 +0000 Subject: [PATCH 7/8] kb: #1608 slice 1 is done, backlog item to done/ Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_013BnEiZFj8CP7nEnkefXVU3 --- ...n-never-makes-two-honest-pull-requests-conflict-the-numeric.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename kb/backlog/{ => done}/a-ratchet-s-pin-never-makes-two-honest-pull-requests-conflict-the-numeric.md (100%) diff --git a/kb/backlog/a-ratchet-s-pin-never-makes-two-honest-pull-requests-conflict-the-numeric.md b/kb/backlog/done/a-ratchet-s-pin-never-makes-two-honest-pull-requests-conflict-the-numeric.md similarity index 100% rename from kb/backlog/a-ratchet-s-pin-never-makes-two-honest-pull-requests-conflict-the-numeric.md rename to kb/backlog/done/a-ratchet-s-pin-never-makes-two-honest-pull-requests-conflict-the-numeric.md From 71276751f95a79fbd54ed6fa639fb67766237711 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 15:01:19 +0000 Subject: [PATCH 8/8] kb: #1608 slice 1 backlog item status is done Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_013BnEiZFj8CP7nEnkefXVU3 --- ...never-makes-two-honest-pull-requests-conflict-the-numeric.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/kb/backlog/done/a-ratchet-s-pin-never-makes-two-honest-pull-requests-conflict-the-numeric.md b/kb/backlog/done/a-ratchet-s-pin-never-makes-two-honest-pull-requests-conflict-the-numeric.md index 8a3764fd1..000a67841 100644 --- a/kb/backlog/done/a-ratchet-s-pin-never-makes-two-honest-pull-requests-conflict-the-numeric.md +++ b/kb/backlog/done/a-ratchet-s-pin-never-makes-two-honest-pull-requests-conflict-the-numeric.md @@ -6,7 +6,7 @@ tags: - quality importance: 5 kind: improvement -status: in_progress +status: done priority: high assignee: agent:cloud-worker effort: S