beads/docs
matt wilkie 2c0f92318e
fix(reset): a comment is content when the question is deletion (follow-up to #5221) (#5227)
* fix(reset): a comment is content when the question is deletion

GH#5221 stopped `bd admin reset` from deleting hooks it never installed, but
left one path open. classifyResetHook decides a sectioned hook by stripping
bd's block and asking isOnlyShebangOrEmpty whether anything remains — and that
predicate, by its own documented design, treats every comment as nothing.

So a hook of the user's whose own content is a shebang plus comments — a header
they wrote, a note to whoever edits it next, a lint step they commented out for
now — strips to "empty", classifies hookBdOwned, and is deleted whole. There is
nothing to restore it from: performReset renames <hook>.backup back into place,
and a backup exists only for hooks bd itself displaced, which is never the case
for a hook bd only injected a section into. A comment was once again enough to
make a hook bd's to delete, which is the failure GH#5221 exists to close.

The looser predicate is right where it lives. shouldPreserveHookContent is
deciding whether to COPY a hook forward into .beads/hooks, and declining to
carry a comment-only file loses a comment out of a file that still exists on
disk (GH#3536). Reset is deciding whether to DESTROY the file. The two
questions differ in what being wrong costs, so they no longer share an answer:
isOnlyShebangOrBlank counts only the leading shebang and blank lines as
nothing. It anchors the shebang on the first non-blank line rather than on
index 0, so it does not depend on whether stripping bd's section left a blank
line above it, and a second `#!` further down is read as the comment it is.

The divergence is deliberate and one-way, so both tests that could hide it now
say so. TestClassifyResetHook_AgreesWithHookPreservation keeps the arm that
matters — what preservation calls the user's, reset must not delete — and
replaces its converse with the weaker claim that still needs pinning: reset may
never call a marker-carrying file none of bd's business, or a hook bd wrote
survives a reset unremoved and unreported. TestResetEmptinessPredicateIsStricter
ThanPreservation pins the gap between the two predicates directly, so a later
cleanup that notices they answer "the same" question and collapses them into
one fails here instead of quietly restoring the deletion.

Verified the fix is load-bearing: pointed classifyResetHook back at the old
predicate and the three new cases fail (both classify cases, and the
collectResetItems case in both directions — removed when it should be kept,
absent from the preserved report when it should be named).

Agent-Signature: claude-opus-5-high on behalf of maphew

* docs(uninstall): stop handing out an rm -f batch under a "check first" warning

GH#5221 added a warning above the manual-cleanup hook deletions telling the
reader that these are the standard git hook names, that any of them may be a
hook they wrote, and to check each file before deleting it. It then left the
five unconditional `rm -f .git/hooks/<name>` lines directly beneath it, inside
the same copy-pasteable fence.

A warning that is followed, in the same block, by the commands that do the
thing it warns about is not a safeguard. Anyone treating the fence the way
fences in this document are meant to be treated deletes all five hooks and
reads the reason afterwards. Someone in this section has already lost the
command that could tell the difference for them.

So the hook step is no longer a batch. A read-only grep lists which of the five
exist and which carry a beads marker, and the disposition is then per file:
delete the ones beads generated whole, edit the block out of the ones that are
yours, leave the rest. `rm -f .git/hooks/<name>` appears once, with a
placeholder, in a sentence about a file the reader has just opened.

The per-file rules are the ones the code applies, including the case the
accompanying commit fixes: a hook that is your header comment plus beads'
block is yours to edit, not beads' to delete.

`bd dolt stop` and the `.beads` / worktree removals stay executable; those are
beads' own state, not files that might be the user's.

Agent-Signature: claude-opus-5-high on behalf of maphew
2026-08-01 03:04:55 -07:00
..
architecture docs: align user docs and CLI reference with the v1.1.0 release (#4874) 2026-07-17 14:17:28 -07:00
cli-reference docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) 2026-07-17 18:03:28 -07:00
core-concepts docs: caveat --parent label inheritance with size/effort labels (#4562) (#5123) 2026-07-31 01:44:50 -07:00
diagrams docs: port the Excalidraw diagram pipeline (machinery only) 2026-07-12 10:37:17 -07:00
getting-started docs: caveat --parent label inheritance with size/effort labels (#4562) (#5123) 2026-07-31 01:44:50 -07:00
images docs: port user docs into the Mintlify site tree under docs/ 2026-07-12 10:37:07 -07:00
integrations [codex] Add Kiro setup recipe (#4535) 2026-07-27 22:28:43 -07:00
multi-agent docs: caveat --parent label inheritance with size/effort labels (#4562) (#5123) 2026-07-31 01:44:50 -07:00
recovery fix(reset): a comment is content when the question is deletion (follow-up to #5221) (#5227) 2026-08-01 03:04:55 -07:00
reference docs: remove stale 8-char prefix limit claim from rename-prefix help (GH#770) (#4813) 2026-07-26 12:29:39 -07:00
workflows docs: caveat --parent label inheritance with size/effort labels (#4562) (#5123) 2026-07-31 01:44:50 -07:00
cli-docs.pin docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) 2026-07-17 18:03:28 -07:00
CLI_REFERENCE.md docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) 2026-07-17 18:03:28 -07:00
community-tools.md docs: add Beadazzle to Native Apps in community-tools.md (#4735) 2026-07-26 12:28:50 -07:00
docs.json [codex] Add Kiro setup recipe (#4535) 2026-07-27 22:28:43 -07:00
index.md docs: align user docs and CLI reference with the v1.1.0 release (#4874) 2026-07-17 14:17:28 -07:00
RECOVERY.md docs(recovery): reduce the stub to a pure pointer 2026-07-17 18:56:33 -07:00
related-projects.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00