The docs kept three hooks alive after the code deleted them
Purge leftover from #3835 · closes #3850 · 2026-08-31
How it surfaced
Two hooks blocked a session on this machine hours after they were deleted: one refused a standard IFS=$'\t' read, the other refused an rm string that was a quoted filter argument, never a command. Both were already gone from main; the session was running the pre-purge build. Looking them up is what found the docs still describing them as current features.
What was actually stale
| surface | state |
|---|---|
| 3 spotlight pages, hand-written | documenting deleted hooks as live |
3 mirrored copies under reference/ | generated by scripts/build-docs.sh, byte-identical |
meta.json nav | 3 of 8 entries pointed at them |
| 4 surviving spotlight pages | cross-linked to the three, so deleting only the pages would have left dangling links |
The issue said six pages. Six was the count of dedicated pages; the coherent unit is eleven files, because a page is not just a file, it is also a nav entry and whatever links to it. Deleting the smaller set would have made the site worse, not better.
Not fixed here, and stated rather than quietly skipped
dangerous-command-blocker 21 files 43 mentions file-guard 18 files 33 mentions block-writes 11 files 18 mentions Of those, only the spotlights were DEDICATED pages. The rest is prose in 21 hand-written files (cookbook, troubleshooting, foundations, getting-started) that uses these hooks as the worked example while explaining a concept. Rewriting an explanation around a different example is editorial work, not a delete, so it is a separate pass rather than something to rush behind a mechanical cleanup.
Verified
grep for spotlights/{the three} -> no dangling link remains
reference/hooks/spotlights/ -> the three copies gone after build-docs.sh
check-docs-facts.mjs -> OK (floor 2.1.251, 106 skills, 36 agents, 172 hooks)