AGENTS.md

@@ -98,8 +98,9 @@ for the ..." on their own expansion, not on anything at the call site.
 Add a new test by creating `tests/test_mything.c` and adding `mything` to the
 right list in `CMakeLists.txt`. `AKSL_TESTS` must exit zero.
 `AKSL_WILL_FAIL_TESTS` are deliberate abort/contract tests.
-`AKSL_KNOWN_FAILING_TESTS` assert documented defects from `TODO.md`; when one
+`AKSL_KNOWN_FAILING_TESTS` assert defects that have an open issue; when one
-starts unexpectedly passing, move it into `AKSL_TESTS` with the fix. Both of the
+starts unexpectedly passing, move it into `AKSL_TESTS` with the fix and close the
+issue. Both of the
 latter are currently empty -- all six confirmed defects are fixed -- but the
 mechanism stays for the next one.
 
@@ -119,7 +120,7 @@ file, `find_dependency(akerror)` resolving, and the exported
 Coverage is 99.5% of lines and 100% of functions across all four sources; CI
 gates at 90 (line) / 40 (branch), so new code needs tests in the same commit. Run
 `cmake --build build-coverage --target coverage` and check the uncovered-line
-listing before proposing a change. Tests for behaviour that `TODO.md` records as
+listing before proposing a change. Tests for behaviour an open issue records as
 defective belong in `AKSL_KNOWN_FAILING_TESTS` asserting the *correct* contract —
 do not pin current-but-wrong behaviour in `AKSL_TESTS`, since that turns the
 eventual fix into a test failure.
@@ -130,10 +131,26 @@ Recent commits use short imperative summaries, for example `Add memory wrapper
 tests` and `Make error-status assertions authoritative`. Keep commits focused
 and include tests with behavior changes. Pull requests should describe the
 changed API or behavior, list the CTest/sanitizer/mutation commands run, and
-link the relevant `TODO.md` item or issue when fixing a known defect.
+link the issue it closes.
 
 ## Agent-Specific Instructions
 
+**Outstanding work goes in the issue tracker, not in a file.** Open an issue at
+<https://source.starfort.tech/andrew/libakstdlib/issues> — `tea issues create
+--repo andrew/libakstdlib` — naming the file and line, 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 where
+the library stands, what is deliberately not wrapped, and which uncovered lines
+are uncoverable rather than untested. A description of work still to do goes
+stale the moment somebody does it, which is why the two are separated.
+
+**A defect in a dependency is filed against that dependency.** `libakerror` has
+a tracker on the same forge, and three defects that cost this library a
+workaround each sat in this repository's own notes for months without anybody
+upstream being able to see them. Comment the workaround at its site with the
+words "filed upstream" and delete it when the fix lands.
+
 Do not modify generated build trees, profiling artifacts, or untracked scratch
 files unless explicitly asked. Prefer small, test-backed changes and update
-`README.md` or `TODO.md` when changing documented workflows or known failures.
+`README.md` when changing documented workflows.