fix(re): the capture checker counted its own selftest fixture as a citation #37

fabi · 2026-09-14T19:19:21Z

fabi commented

2026-09-14 19:19:21 +00:00

⚠️ Based on fix/capture-citations (#33) — one commit on top. Merge #33 first.

`check-capture-citations` fails on a clean checkout of its own branch

$ python3 tools/re/check-capture-citations
🔴 cited but NOT committed: 1
    docs/re/captures/no-such-file-anywhere.png
rc=1

SEARCH includes tools, so the scan reads this file — and selftest()'s planted
fixture is a literal capture path. The checker cited its own test data, pointing at a
file that cannot exist by construction. Nobody changed anything; it is red out of the box
and stays red.

That matters because of what the check is for. Phase 4 built it as the missing gate on
docs/re/. A gate that is red before anyone touches the repo teaches people to ignore
it — and this page's own Phase 0 already names that failure once.

The fix

SELF = ":!tools/re/check-capture-citations", applied to both greps. Excluding only this
one file keeps every other tool in scope — which matters, because named_bare() exists
precisely to catch screen_match.py opening captures by bare filename. A real citation
belongs in a page or in a tool that opens the capture, never in the checker.

The guard, and proof it can fail

Added own fixtures not counted to the selftest. This file already documents surviving
exactly this class of bug — the ERE that matched nothing while five ticks stayed green —
so the guard was verified by breaking it rather than by assuming:

	selftest	real check
exclusion neutralised	`own fixtures not counted` 🔴 FAILED, rc=2	rc=1, reproduces the original dangling citation
exclusion restored	ok, 7 cases	rc=0

After the fix

captures committed          : 212
  cited by a page or a tool : 212
  cited by nothing          : 0
  🔴 cited but NOT committed: 0
rc=0

That is also the first independent confirmation of Phase 4's "212 captures, all cited" —
until now the number came from the page, and the tool that should agree with it exited 1.

📌 Found by running the checks rather than reading them, which is what
CONSOLIDATION.md asks for: "Run them again rather than trusting the results recorded
here." The selftest itself passes and always did — it was the real run that was broken,
and only running both showed it.

🤖 Generated with Claude Code

⚠️ **Based on `fix/capture-citations` (#33)** — one commit on top. Merge #33 first. ## `check-capture-citations` fails on a clean checkout of its own branch ``` $ python3 tools/re/check-capture-citations 🔴 cited but NOT committed: 1 docs/re/captures/no-such-file-anywhere.png rc=1 ``` `SEARCH` includes `tools`, so the scan reads **this file** — and `selftest()`'s planted fixture is a literal capture path. The checker cited its own test data, pointing at a file that cannot exist by construction. Nobody changed anything; it is red out of the box and stays red. That matters because of what the check is *for*. Phase 4 built it as the missing gate on `docs/re/`. **A gate that is red before anyone touches the repo teaches people to ignore it** — and this page's own Phase 0 already names that failure once. ## The fix `SELF = ":!tools/re/check-capture-citations"`, applied to both greps. Excluding only this one file keeps every other tool in scope — which matters, because `named_bare()` exists precisely to catch `screen_match.py` opening captures by bare filename. A real citation belongs in a page or in a tool that opens the capture, never in the checker. ## The guard, and proof it can fail Added `own fixtures not counted` to the selftest. This file already documents surviving exactly this class of bug — the ERE that matched nothing while five ticks stayed green — so the guard was verified by breaking it rather than by assuming: | | selftest | real check | |---|---|---| | exclusion neutralised | `own fixtures not counted` **🔴 FAILED**, rc=2 | rc=1, reproduces the original dangling citation | | exclusion restored | ok, 7 cases | **rc=0** | ## After the fix ``` captures committed : 212 cited by a page or a tool : 212 cited by nothing : 0 🔴 cited but NOT committed: 0 rc=0 ``` That is also the **first independent confirmation of Phase 4's "212 captures, all cited"** — until now the number came from the page, and the tool that should agree with it exited 1. 📌 Found by running the checks rather than reading them, which is what `CONSOLIDATION.md` asks for: *"Run them again rather than trusting the results recorded here."* The selftest itself passes and always did — it was the real run that was broken, and only running both showed it. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

fabi changed target branch from fix/capture-citations to main

2026-09-15 19:45:50 +00:00

fabi added 1 commit 2026-09-15 19:45:50 +00:00

fix(re): the capture checker counted its own selftest fixture as a citation a259514032

`check-capture-citations` exits 1 on a clean checkout of this branch, and would
have kept doing so for ever:

    🔴 cited but NOT committed: 1
        docs/re/captures/no-such-file-anywhere.png

`SEARCH` includes `tools`, so the scan reads this file -- and `selftest()`'s
planted fixture is a literal capture path. The checker cited its own test data,
to a file that will never exist by construction. A gate that is red before
anyone changes anything teaches people to ignore it, which is the opposite of
what Phase 4 built it for.

Excluding only this one file (`SELF`) keeps every other tool in scope. A real
citation belongs in a page, or in a tool that opens the capture -- never in the
checker itself.

Added a selftest case for it, because this is exactly the class of bug the rest
of this file already documents surviving: the ERE that matched nothing while
five ticks stayed green. Verified the guard can fail, rather than assuming it:

    exclusion neutralised -> "own fixtures not counted 🔴 FAILED",
                             selftest rc=2, real check rc=1 reproducing the bug
    exclusion restored    -> selftest ok (7 cases), check rc=0

After the fix, on this branch:

    captures committed          : 212
      cited by a page or a tool : 212
      cited by nothing          : 0
      🔴 cited but NOT committed: 0        rc=0

which is also the first independent confirmation of Phase 4's "212 captures,
all cited" -- the checker now agrees with the page.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>