docs(re): give docs/re/ the citation check docs/port/ has always had, and prune #33

fabi · 2026-09-13T19:15:12Z

fabi commented

2026-09-13 19:15:12 +00:00

CONSOLIDATION.md Phase 4. tools/port/check-citations has checked docs/port/*.md since it was written. docs/re/ never had one — and docs/re/captures/ is the largest thing in the repository, the one place a file can be added, never cited, and never noticed.

captures committed          : 212
  cited by a page or a tool : 212
  cited but NOT committed   : 0

🔴 My premise was wrong four times. Each correction is in the tool, not just in my head.

"10 dangling citations" — the real number was one. Eight were directory references (docs/re/captures/ui-layout/), which resolve perfectly and are absent only from git ls-tree, which lists files. One was a path at the end of a sentence with the full stop pulled into the match. I reported that 10 to you and put it in the plan; it was a regex artifact. A checker that cries wolf nine times in ten teaches you to ignore it.

The one real dangler was evidence someone deleted while keeping the claim. live-submenu-unidentified.png was committed in cab62796, then removed on 2026-08-30 — while the citing page went on saying "The capture is 99.7 % inked" and linking to it. Restored rather than de-linked.

Two "orphans" are opened by filename, not by path, from tools/re-capture/screen_match.py. A path-only scan called them unreferenced; deleting them would have broken the tool. The check now counts any basename named anywhere.

Pruning then emptied two directories that pages cite as directories, and the check went red on the very citations that made them evidence. It caught its own damage. A file inside a cited directory is cited.

The selftest covers the failure that actually happened

An earlier version printed five green ticks while the scan silently returned nothing — git grep -E is POSIX ERE and cannot compile (?:, so it matched zero and exited 0. Same shape as the export table that returned empty and let the build succeed. The selftest now asserts the gathering works, not only the resolver.

What was dropped

46 orphaned captures, 30.7 MB out of the checkout.

⚠️ This reclaims no repository space — the blobs stay in history, and that is Phase 5's separate question. What it buys is that every capture here is evidence some page or tool actually uses.

CONSOLIDATION.md **Phase 4**. `tools/port/check-citations` has checked `docs/port/*.md` since it was written. **`docs/re/` never had one** — and `docs/re/captures/` is the largest thing in the repository, the one place a file can be added, never cited, and never noticed. ``` captures committed : 212 cited by a page or a tool : 212 cited but NOT committed : 0 ``` ### 🔴 My premise was wrong four times. Each correction is in the tool, not just in my head. **"10 dangling citations" — the real number was one.** Eight were **directory** references (`docs/re/captures/ui-layout/`), which resolve perfectly and are absent only from `git ls-tree`, which lists files. One was a path at the end of a sentence with the full stop pulled into the match. I reported that 10 to you and put it in the plan; it was a regex artifact. A checker that cries wolf nine times in ten teaches you to ignore it. **The one real dangler was evidence someone deleted while keeping the claim.** `live-submenu-unidentified.png` was committed in `cab62796`, then removed on 2026-08-30 — while the citing page went on saying *"The capture is 99.7 % inked"* and linking to it. **Restored** rather than de-linked. **Two "orphans" are opened by filename**, not by path, from `tools/re-capture/screen_match.py`. A path-only scan called them unreferenced; deleting them would have broken the tool. The check now counts any basename named anywhere. **Pruning then emptied two directories that pages cite *as* directories**, and the check went red on the very citations that made them evidence. It caught its own damage. A file inside a cited directory is cited. ### The selftest covers the failure that actually happened An earlier version printed **five green ticks while the scan silently returned nothing** — `git grep -E` is POSIX ERE and cannot compile `(?:`, so it matched zero and exited 0. Same shape as the export table that returned empty and let the build succeed. The selftest now asserts the gathering works, not only the resolver. ### What was dropped 46 orphaned captures, 30.7 MB out of the checkout. ⚠️ **This reclaims no repository space** — the blobs stay in history, and that is Phase 5's separate question. What it buys is that every capture here is evidence some page or tool actually uses.

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

docs(re): give docs/re/ the citation check docs/port/ has always had, and prune

CI / Native — linux (pull_request) Successful in 37m10s

Details

CI / WASM — Web (pull_request) Successful in 28m25s

Details

CI / Formatting (pull_request) Successful in 57s

Details

2e7e4b17a8

CONSOLIDATION.md Phase 4. `tools/port/check-citations` has checked
`docs/port/*.md` since it was written; `docs/re/` never had one, and
`docs/re/captures/` is the largest thing in the repository -- the one place a
file can be added, never cited, and never noticed.

  captures committed          : 212
    cited by a page or a tool : 212
    cited but NOT committed   : 0

🔴 THE PREMISE I STARTED FROM WAS WRONG FOUR TIMES, AND EACH CORRECTION IS IN
THE TOOL RATHER THAN JUST IN MY HEAD:

  * "10 dangling citations" -- the real number was ONE. Eight were DIRECTORY
    references, which resolve and are simply absent from `git ls-tree`; one was
    a path at the end of a sentence with the full stop pulled into the match.
    A checker that cries wolf nine times in ten teaches you to ignore it.
  * The one real dangler, `live-submenu-unidentified.png`, was COMMITTED and
    then deleted on 2026-08-30 while the page kept citing it and kept making
    the claim it backs. Restored from cab62796 rather than dropping the link:
    deleting evidence while keeping the conclusion is the thing this corpus
    exists to prevent.
  * Two "orphans" are opened BY FILENAME from `screen_match.py`, which builds
    the directory separately. A path-only scan called them unreferenced and
    deleting them would have broken the tool. The check now counts any
    basename named anywhere.
  * Pruning then EMPTIED two directories that pages cite as directories, and
    the check went red on the very citations that made them evidence. It
    caught its own damage. A file inside a cited directory is cited.

The selftest covers all of it, including the failure that actually happened:
an earlier version passed five green ticks while the scan silently returned
NOTHING, because `git grep -E` is POSIX ERE and cannot compile `(?:`. A
selftest that cannot see the failure that occurred is decoration.

46 orphaned captures dropped, 30.7 MB from the checkout. ⚠️ That reclaims no
repository space -- the blobs stay in history -- and it is not meant to. It
means every capture here is now evidence some page or tool actually uses.

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

fabi referenced this pull request

2026-09-13 19:23:07 +00:00

docs(agents): the plan to consolidate six repositories into two #29

fabi referenced this pull request

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

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

fabi merged commit 33d14109ae into main

2026-09-15 19:44:49 +00:00

fabi referenced this issue from a commit

2026-09-15 19:44:49 +00:00

Merge pull request 'docs(re): give docs/re/ the citation check docs/port/ has always had, and prune' (#33) from fix/capture-citations into main

fabi referenced this issue from a commit