Correct two stale claims in tiers_ratchet.py's docstring - #2014
Merged
Conversation
Both were introduced by me and both actively mislead. An agent working #1993 read the second one, believed the gate was unwired, and spent a cycle on a theory that could not be true. 1. "NOT WIRED INTO ANYTHING YET -- deliberately." False since #2011, which added .github/workflows/converted-ratchet.yml (pull_request + push: main). Replaced with what the workflow actually does, pointing at its `on:` block as the authoritative path list rather than duplicating it here -- the duplicate is what would go stale next. 2. "staleness only ever runs one way." False for two shapes, both of which cost real time this week: - TU promotion removes banked paths. classify_missing() resolves them through the TU manifest and reports MOVED; when the absorbing file is itself CONVERTED the removal is absorbed_clean and needs no --reason. The banked COUNT drops and that is CORRECT. Stated explicitly, because I circulated the opposite rule ("the floor is 2565, never go below it") to three agents and two of them had to come back with the source to correct me. This is a SET ratchet; there is no floor number to defend. - A plain file rename has no detection at all: it reports GONE and demands a --reason, which writes a permanent fake backslide row. The workaround (apply renames to the parent's banked set first, then regenerate) is recorded until the detection lands. Also records that a CI red here is usually a base desync, not a regression -- the #1996 shape, where a PR cut before a re-bank inherits the red and the next unrelated src/** PR is the one that turns red for it. Fix is to merge main in, never to lower the pin. Docstring only. No behaviour change; --check still PASS 2565/2565. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WdCK1xgrJdiJzPCh3bAJfQ
✅ PR validation — Passednoverify: no source/build-data changes in this PR Each changed |
This was referenced Aug 30, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Docstring only.
--checkstillPASS 2565/2565; no behaviour change.Both claims were introduced by me, and both actively mislead a reader:
1. "NOT WIRED INTO ANYTHING YET -- deliberately."
False since #2011, which added
.github/workflows/converted-ratchet.yml(pull_request+push: main). An agent working #1993 read this line, concluded the gate was unwired, and spent a cycle on a theory that could not be true. Replaced with what the workflow actually does — and it points at that workflow'son:block as the authoritative path list rather than duplicating it here, since a duplicated list is the thing that goes stale next.2. "staleness only ever runs one way."
False for two shapes, both of which cost real time this week.
TU promotion removes banked paths.
classify_missing()already handles it — resolves the gone path throughtools/tu_manifest.pyand reportsMOVED; when the absorbing file is itself CONVERTED the removal isabsorbed_clean, needing no--reasonand logging no exception row. The banked COUNT drops, and that is correct. Stated explicitly because I circulated the opposite rule — "the floor is 2565, never go below it" — to three agents, and two of them had to come back with the source to correct me. This is a SET ratchet. There is no floor number to defend, and a promotion batch is expected to lower the count.A plain file rename has no detection at all. It reports
GONE -- not a tracked source file any moreand demands a--reason, which would write a permanent fake backslide row intoconfig/converted-backslide-exceptions.jsonl. The workaround (apply the renames to the parent's banked set first, then regenerate) is now recorded in the docstring until real rename detection lands.Also records the failure shape from #1996: a CI red here is usually a base desync, not a regression — a PR cut before a re-bank merges against a baseline that predates it, inherits the red, and the next unrelated
src/**PR is the one that turns red for it. Fix is to merge main in, never to lower the pin.🤖 Generated with Claude Code
https://claude.ai/code/session_01WdCK1xgrJdiJzPCh3bAJfQ