Gap
#44 added guidance on what to cut (YAGNI, comment density) but nothing on proving the cut changed no behaviour. Searching coding-standards.md for byte-identical, subtractive, or prove unchanged returns nothing; CLAUDE.md §4/§6 cover regression tests for bug fixes, not refactors.
That leaves the guidance telling an agent to delete aggressively with no paired discipline for doing it safely — arguably worse than saying nothing.
Where it bit
A six-PR cleanup driven by #44 removed ~2,240 lines. What kept it safe was never written down:
- Byte-comparing generated artifacts. For the CDKTF PRs this meant
cdk.tf.json and moved.tf and removed.tf across four stack shapes. That last pair is where an alarm-destruction hazard lived: a renamed Terraform logical id destroys and recreates live AWS resources, and no unit test sees it. Green tests would have shipped it.
- Subtractive-only edits — delete and inline, never restructure.
- A named protected list carried into each agent brief. Hard-won constraints (an inverted-looking
opt-out tag, deliberately non-positional alarm ids) look exactly like cruft to someone who wasn't there.
- "Nothing worth removing" being an acceptable outcome. Two agents returned it for specific files; without that permission they'd have manufactured changes.
- Not deleting security assertions on self-assessment. One agent removed IAM privilege-escalation tests judging them subsumed. It was right — the coupling held transitively via two exact-equality assertions — but that verification was the human's to do.
Separately, a repo-level trap worth recording: git hooks silently do not run in worktrees where core.hooksPath points at an install-generated directory (.husky/_). It was present in 2 of 5 worktrees here; commits from the other 3 skipped lint, formatting and a bundle rebuild with no warning. Since worktrees are the default for non-trivial work, this is easy to hit.
Proposed
A short "Verifying a Refactor" section in coding-standards.md, directly after Simplicity & Scope (YAGNI), plus one paragraph in git-workflow.md on the worktree hook trap.
Gap
#44 added guidance on what to cut (YAGNI, comment density) but nothing on proving the cut changed no behaviour. Searching
coding-standards.mdforbyte-identical,subtractive, orprove unchangedreturns nothing;CLAUDE.md§4/§6 cover regression tests for bug fixes, not refactors.That leaves the guidance telling an agent to delete aggressively with no paired discipline for doing it safely — arguably worse than saying nothing.
Where it bit
A six-PR cleanup driven by #44 removed ~2,240 lines. What kept it safe was never written down:
cdk.tf.jsonandmoved.tfandremoved.tfacross four stack shapes. That last pair is where an alarm-destruction hazard lived: a renamed Terraform logical id destroys and recreates live AWS resources, and no unit test sees it. Green tests would have shipped it.opt-outtag, deliberately non-positional alarm ids) look exactly like cruft to someone who wasn't there.Separately, a repo-level trap worth recording: git hooks silently do not run in worktrees where
core.hooksPathpoints at an install-generated directory (.husky/_). It was present in 2 of 5 worktrees here; commits from the other 3 skipped lint, formatting and a bundle rebuild with no warning. Since worktrees are the default for non-trivial work, this is easy to hit.Proposed
A short "Verifying a Refactor" section in
coding-standards.md, directly after Simplicity & Scope (YAGNI), plus one paragraph ingit-workflow.mdon the worktree hook trap.