diff --git a/AGENTS.md b/AGENTS.md index 8006936..bdc8c4f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -124,7 +124,7 @@ Every suite runs in every job. The `character` suite used to be excluded from the coverage and memory-check jobs on the grounds that it failed deliberately. It did not: it was reporting success while running one of its four tests, for two independent reasons, and both are fixed. See TODO.md, "Test suites that -could not fail". +could not fail", which is the record of how that happened. ## Coding Style @@ -549,12 +549,13 @@ cheap to check and expensive to assume. a bit that is **not** set whose value is **not** 1. The obvious test passes either way. -- **Do not trust a comment, a TODO entry, or a CI exclusion that states a +- **Do not trust a comment, an issue, or a CI exclusion that states a premise.** Verify it. `tests/character.c` was excluded from two CI jobs and from the mutation harness because it "fails deliberately". It did not: it was - exiting 0 while running one of its four tests. `TODO.md` carried eleven - entries describing code that had already changed. A premise nobody has - re-checked is where the next defect is hiding. + exiting 0 while running one of its four tests. `TODO.md`, when it still held + outstanding work, carried eleven entries describing code that had already + changed, and three more were found stale when it was migrated to the tracker. + A premise nobody has re-checked is where the next defect is hiding. - **When a measurement moves, say what you measured.** Absolute benchmark numbers drift with the machine. The `akgl_game_update` fix is recorded as the @@ -564,6 +565,19 @@ cheap to check and expensive to assume. ## Rules +- **Outstanding work goes in the issue tracker, not in a file.** Open an issue at + — `tea issues create --repo andrew/libakgl` + — with the file and line it touches, the functional consequence, and what closing it would + touch. Label it by kind and blast radius, and leave `status::grooming` on it until its scope + and approach are settled. **Do not add outstanding items to `TODO.md`**; that file is the + record of decisions, measurements and defects already closed, and the reason for the split is + that a description of work still to do goes stale the moment somebody does it. +- **When you learn something about an open issue, say so in the issue** — including that it is + worse than recorded, that it is already fixed, or that its premise has expired. An issue + nobody has re-checked is worth what an unverified comment is worth. +- **A defect in a dependency is filed against that dependency**, not worked around here. + `libakerror`, `libakstdlib` and `akbasic` all have trackers on the same forge. Comment the + workaround at its site with the words "filed upstream" and delete it when the fix lands. - Add yourself (agent program name, model name and version) as a co-author on every commit message - Avoid dynamic memory allocation. Use the `akgl_heap_*` methods to retrieve necessary objects at runtime, and to release them when done. If the akgl heap facilities don't provide the kind of object needed, create a new heap layer to support that type of object.