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
+  <https://source.starfort.tech/andrew/libakgl/issues> — `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.