amadan
Generalise the citation rule: tools that answer wrongly
Two verification traps cost this project real time today, and both were written down as a rastrillo-specific citation rule, which is too narrow to catch the next one. A checkout parked on a feature branch gives true statements about the wrong tree, with real line numbers that verify. git branch --merged against a squash-merging repo returns an empty list that reads as "never merged" while main carries every line. Neither errors. Both answer, and the answer disagrees with reality. The generalisation is the useful part: watch for a verification that cannot distinguish "no" from "I can't see it", and when you catch one, write it down rather than resolving to be more careful. Care is not a mechanism. Also stamps commit counts with the sha and date they were taken at. The 17-versus-18 confusion happened twice today, in both directions, because a bare number measured before a merge was quoted after one.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011F5CivVm4CmL9ByfSSAaXA
1 file changed,
+26
−7
AGENTS.md+26 −7
diff --git a/AGENTS.md b/AGENTS.md| index bd04f1d..cebba28 100644 |
| --- a/AGENTS.md |
| +++ b/AGENTS.md |
| @@ -162,13 +162,32 @@ one session's question exposing another's bug. |
| Writing attributes now would mean maintaining a parallel styling |
| implementation indefinitely; writing classes means one mechanical migration |
| alongside the framework's own. |
| -- **Check `origin/main`, not your checkout, before citing rastrillo.** A |
| - spec ruling, code on `main`, and code in the latest release are three |
| - different things. `v0.19.0` (2026-08-24) is 17 commits behind `main` and |
| - lacks the themes, shells and locales the design-system spec describes, so |
| - `go get` alone will not give you them. Note also that this project |
| - squash-merges, so `git branch --merged` reports nothing useful about |
| - whether work has landed — compare content, not ancestry. |
| +- **A spec ruling, code on `main`, and code in the latest release are three |
| + different things.** Reading one tells you nothing about the other two. |
| + `v0.19.0` (2026-08-24) is 18 commits behind rastrillo's `main` and lacks |
| + the themes, shells and locales the design-system spec describes, so |
| + `go get` alone will not give you them. Say which of the three you mean |
| + whenever you cite the framework, and stamp any commit count with the sha |
| + and date you took it at — a bare number ages into a wrong fact. |
| + |
| +### Watch for tools that answer wrongly instead of failing |
| + |
| +A tool that errors teaches you something. A tool that returns a confident |
| +wrong answer does not, and both of the ones below cost this project real |
| +time in a single afternoon: |
| + |
| +- **Citing your working tree instead of `origin/main`.** A checkout parked |
| + on a feature branch gives you *true statements about the wrong tree*, |
| + complete with real line numbers that verify. Cite `origin/main` after a |
| + fetch, or a tag, and say which. Never your checkout. |
| +- **`git branch --merged` against a squash-merging repo.** It returns an |
| + empty list that reads as "never merged" while `main` carries every line, |
| + because a squashed branch is not an ancestor. Compare content, not |
| + ancestry. |
| + |
| +The shape to watch for is a verification that cannot distinguish "no" from |
| +"I can't see it". When you catch one, write it here rather than resolving |
| +to be more careful — care is not a mechanism. |
| - **Re-copy `tokens.css` deliberately on every rastrillo upgrade.** It is |
| frozen into `static/` at scaffold time while the partials upgrade with the |
| module. `rastrillo doctor` will make this mechanical; until it lands it is |