From 43f62ddfeee54adb4abef4b9398255a412ace494 Mon Sep 17 00:00:00 2001 From: Edwin van den Houdt Date: Fri, 4 Sep 2026 18:08:21 +0200 Subject: [PATCH] docs: record the fifth acceptance-check miss, and the stale SQLite trap RD-11 asserted that `git grep "machineRemoteData\|LoadLifecycle"` returns nothing, but the replacement it mandates is named `fromLoadLifecycle`, which contains the old name as a substring. The check could never pass. When a new name contains the old one, anchor on word boundaries. Add a fourth habit: prefer a number over a prohibition for anything that must not change. "Do not rename BriefStatus" invites reasoning around it. "This count must still be 54, and if it moves, revert rather than adjust the number" does not. RD-11 renamed tags across 19 files with a wire contract in the same file, and the count held. Also record a real trap found during RD-11: stale gitignored bigregister.db artifacts fail backend tests with "no such table" on an otherwise clean tree. A 0-byte file months old failed 6 tests. Co-Authored-By: Claude Opus 5 --- docs/project/readable-codebase/README.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/docs/project/readable-codebase/README.md b/docs/project/readable-codebase/README.md index b2447fd..8aa4961 100644 --- a/docs/project/readable-codebase/README.md +++ b/docs/project/readable-codebase/README.md @@ -192,8 +192,13 @@ Three rules when you write a ticket file, because the agent reads its ticket and files (they name the deleted method as the history of `done` work) and 22 gitignored abandoned worktrees. Satisfying it literally would have corrupted completed-ticket history. + - RD-11 asserted `git grep "machineRemoteData\|LoadLifecycle"` returns nothing, but the + replacement it mandates is named **`fromLoadLifecycle`** — which contains the old name as + a substring. The check can never pass. **When the new name contains the old one, anchor + on word boundaries**: `git grep -w machineRemoteData` and + `git grep -nE "(^|[^a-zA-Z])LoadLifecycle\b"`. - Three habits that prevent all four: + Four habits that prevent all five: - **Use `git grep`, not `grep -r`.** It searches tracked files only, so untracked and gitignored paths never pollute the result. Measured on this repo: `grep -r` finds 132 @@ -203,3 +208,20 @@ Three rules when you write a ticket file, because the agent reads its ticket and appear elsewhere. - **Keep the Files list consistent with the Acceptance commands.** If a command reaches a file the ticket says not to touch, one of the two is wrong. + - **Prefer a number over a prohibition for anything that must not change.** "Do not rename + `BriefStatus`" invites reasoning around it; "this count must still be 54, and if it moves, + revert rather than adjust the number" does not. RD-11 renamed tags across 19 files with a + wire contract in the same file — on the same line in one place — and the count held. + +## Troubleshooting + +**`dotnet test` fails with `SQLite Error 1: 'no such table: '`.** Stale, gitignored +`bigregister.db` artifacts from an old build. Found during RD-11, where a 0-byte file dated +months earlier failed 6 backend tests on an otherwise clean tree. Delete all three and re-run: + +```bash +rm -f backend/bigregister.db backend/src/BigRegister.Api/bigregister.db \ + backend/tests/BigRegister.Tests/bin/Debug/net10.0/bigregister.db +``` + +These are build artifacts, not fixtures — removing them is always safe.