fix(re): the capture-citation check was red on a clean tree #65

fabi · 2026-09-21T16:12:48Z

fabi commented

2026-09-21 16:12:48 +00:00

Found by running the check on main after #64 merged: it exits 1 on a correct checkout.

committed() built its directory set from range(4, len(parts)). Index 3 is docs/re/captures itself, so every sub-directory was registered and the root never was. Eight pages cite the directory as a whole — PROTOCOL's evidence table, CONSOLIDATION.md, CONTAINERS-AND-AGENTS.md, decoder-loop.md, both HANDOFFs, BLOCKED.md, verify-screen-blend-divergence.md — and each of those read as a citation of a file that does not exist.

That is the failure mode the script's own comments warn about: "a gate that is red on every clean checkout" teaches people to ignore it, and this one has a second half (no game asset tracked, issue #49) that has to stay believed.

The selftest could not see it

It takes next(iter(dirs)) — and an arbitrary member of that set is always a sub-directory, the one case that already worked. It now asserts the root explicitly, with and without its trailing slash.

Both new cases were confirmed to FAIL against the unfixed function before the fix went in. A selftest case that passes either way is decoration, which is a lesson this file already learned once (see its SELF regression guard).

Measured

	before	after
exit code	1	0
citations	203	203
captures present	212	212
dangling	1 (`docs/re/captures/`)	0
tracked game assets	0	0
selftest	8 ok	10 ok

What to look at

Pass: python3 tools/re/check-capture-citations exits 0 and --selftest prints ten ok.
Fail: either still reports cited but NOT present, or the two new root cases pass when range(3, …) is reverted to range(4, …).

🤖 Generated with Claude Code

Found by running the check on `main` after #64 merged: **it exits 1 on a correct checkout.** `committed()` built its directory set from `range(4, len(parts))`. Index **3** is `docs/re/captures` itself, so every *sub*-directory was registered and the root never was. Eight pages cite the directory as a whole — PROTOCOL's evidence table, `CONSOLIDATION.md`, `CONTAINERS-AND-AGENTS.md`, `decoder-loop.md`, both HANDOFFs, `BLOCKED.md`, `verify-screen-blend-divergence.md` — and each of those read as a citation of a file that does not exist. That is the failure mode the script's own comments warn about: *"a gate that is red on every clean checkout"* teaches people to ignore it, and this one has a second half (**no game asset tracked**, issue #49) that has to stay believed. ### The selftest could not see it It takes `next(iter(dirs))` — and an arbitrary member of that set is *always* a sub-directory, the one case that already worked. It now asserts the root explicitly, with and without its trailing slash. Both new cases were confirmed to **FAIL** against the unfixed function before the fix went in. A selftest case that passes either way is decoration, which is a lesson this file already learned once (see its `SELF` regression guard). ### Measured | | before | after | |---|---|---| | exit code | **1** | **0** | | citations | 203 | 203 | | captures present | 212 | 212 | | dangling | **1** (`docs/re/captures/`) | **0** | | tracked game assets | 0 | 0 | | selftest | 8 ok | 10 ok | ### What to look at **Pass:** `python3 tools/re/check-capture-citations` exits 0 and `--selftest` prints ten `ok`. **Fail:** either still reports `cited but NOT present`, or the two new root cases pass when `range(3, …)` is reverted to `range(4, …)`. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

fabi added 1 commit 2026-09-21 16:12:48 +00:00

fix(re): the capture check was red on a clean tree

CI / Native — linux (pull_request) Failing after 1h1m57s

Details

CI / WASM — Web (pull_request) Successful in 24m51s

Details

CI / Formatting (pull_request) Successful in 28s

Details

43f0a905a0

`committed()` built the directory set from `range(4, len(parts))`. Index 3 is
`docs/re/captures` itself, so every SUB-directory was registered and the root
never was. Eight pages cite the directory as a whole -- PROTOCOL's evidence
table, CONSOLIDATION, CONTAINERS-AND-AGENTS, decoder-loop, both HANDOFFs,
BLOCKED, verify-screen-blend-divergence -- and each of those looked like a
citation of a file that does not exist. `check-capture-citations` exited 1 on a
correct checkout, which is the failure mode its own comments warn about: "a
gate that is red on every clean checkout" teaches people to ignore it.

The selftest could not see this. It takes `next(iter(dirs))`, and an arbitrary
member of that set is always a sub-directory -- the one case that works. It now
asserts the root explicitly, with and without its trailing slash. Both new cases
were confirmed to FAIL against the unfixed function before the fix went in; a
selftest case that passes either way is decoration.

Measured: full check 203 citations, 212 captures, 0 dangling, 0 tracked assets,
exit 0. Before: exit 1.

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

fabi merged commit c03e5c9bd0 into main

2026-09-21 16:13:54 +00:00

fabi referenced this issue from a commit

2026-09-21 16:13:55 +00:00

Merge pull request 'fix(re): the capture-citation check was red on a clean tree' (#65) from fix/captures-root-citation into main

fabi referenced this pull request

2026-09-21 16:17:34 +00:00

fix(port): check-citations was red, and its selftest BROKEN, on a clean tree #66

fabi referenced this pull request

2026-09-21 16:37:07 +00:00

Decide: do the public repos keep the game screenshots in `docs/re/captures/`? #49

Sign in to join this conversation.