From 8e5f48c5d2c80293402f98f38079529a4960a39d Mon Sep 17 00:00:00 2001 From: Edwin van den Houdt Date: Fri, 4 Sep 2026 18:28:13 +0200 Subject: [PATCH] docs: scope acceptance checks to the ticket's files, not a directory The sixth acceptance-check miss, and the first the executing agent caught using these rules rather than the supervisor. RD-12 asserted `git grep "ActionState" -- apps/ssp/src/app/brief` returns nothing, but org-template.store.ts lives in that directory and is deliberately out of scope until RD-13. The check could never pass. Sharpen the existing habit into a mechanical step: name the files, never a parent directory. The agent also caught the RD-11 substring trap in its own work, where the new type BriefActionState contains ActionState, and word-anchored the check instead of renaming away from the natural name. Co-Authored-By: Claude Opus 5 --- docs/project/readable-codebase/README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/project/readable-codebase/README.md b/docs/project/readable-codebase/README.md index 2b2e9f0..d0d3d3c 100644 --- a/docs/project/readable-codebase/README.md +++ b/docs/project/readable-codebase/README.md @@ -206,8 +206,12 @@ Three rules when you write a ticket file, because the agent reads its ticket and which are repo-wide sweeps. - **Anchor on a declaration** (`^ onRetry\(\)`), not on a name that may legitimately 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. + - **Scope every acceptance command to the ticket's Files list, never to a parent + directory.** This is the habit most often broken, including by the supervisor in RD-12: + the check `git grep "ActionState" -- apps/ssp/src/app/brief` cannot pass, because + `org-template.store.ts` lives in that directory and is deliberately out of scope until + RD-13. Name the files. 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