Skip to content

Correct two stale claims in tiers_ratchet.py's docstring - #2014

Merged
andrewboudreau merged 1 commit into
mainfrom
docs/ratchet-docstring-current
Aug 30, 2026
Merged

Correct two stale claims in tiers_ratchet.py's docstring#2014
andrewboudreau merged 1 commit into
mainfrom
docs/ratchet-docstring-current

Conversation

@andrewboudreau

Copy link
Copy Markdown
Collaborator

Docstring only. --check still PASS 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's on: 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 through tools/tu_manifest.py and reports MOVED; when the absorbing file is itself CONVERTED the removal is absorbed_clean, needing no --reason and 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 more and demands a --reason, which would write a permanent fake backslide row into config/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

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
@tangos-validator

tangos-validator Bot commented Aug 30, 2026

Copy link
Copy Markdown

✅ PR validation — Passed

noverify: no source/build-data changes in this PR

Each changed src/*.c|*.cpp is compiled and its relocated bytes compared to the binary data on a private build box. Passing requires every changed file to reproduce the ROM byte-for-byte with correct relocation targets — this catches WRONG-DEST relocations and non-reproducing near-misses that ledger-scoped linkcheck skips.

@andrewboudreau
andrewboudreau merged commit 25cfc13 into main Aug 30, 2026
6 checks passed
@andrewboudreau
andrewboudreau deleted the docs/ratchet-docstring-current branch August 30, 2026 16:17
andrewboudreau added a commit that referenced this pull request Aug 30, 2026
Refresh the validation base: the queued job was pinned to 8c0b811, which
predates #2005 and #2014. Merge tree verified to preserve #2005's
deadstrip-data fix for _ZTI16dPathLiftActor_c and to hold source-built
coverage at 2,066,772 B with 0 bytes handed back.
andrewboudreau added a commit that referenced this pull request Aug 30, 2026
Refresh the validation base: the queued job was pinned to 207d932, which
predates #2014. Merge tree verified to preserve #2005's deadstrip-data fix
for _ZTI16dPathLiftActor_c and to hold source-built coverage at
2,066,772 B with 0 bytes handed back.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant