From 23df4069abef64ca624401728edcaebc7353003b Mon Sep 17 00:00:00 2001 From: Tachikoma Date: Sun, 2 Aug 2026 19:24:49 -0400 Subject: [PATCH] Point AGENTS.md at the issue tracker for outstanding work The agent instructions now say where new work goes -- an issue on the forge, carrying status::grooming until its scope is settled -- and that TODO.md is the record: why the handler ladder is a major-version change, why a copied akerr_ErrorContext is a trap, why validating more inputs lowers branch coverage, and why the mutation score is a floor. The instruction that matters most here is about consumers. Three defects in this library -- IGNORE() leaking a context, the un-namespaced coverage target, and the missing akerrorConfigVersion.cmake -- were written down in libakstdlib's notes and never here, so each was worked around once per consumer and nobody saw the pattern. Filing upstream should cost a consumer one issue instead of one workaround. Co-Authored-By: Claude Opus 5 (1M context) Co-Authored-By: Andrew Kesterson --- AGENTS.md | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0ed2b95..6919a09 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -133,11 +133,31 @@ anything that touches the pool, the registry, initialization, or the lock. Recent commits use short, imperative, sentence-case subjects, for example `Fix refcount leak and stack-trace buffer overflow`. Keep commits focused and describe the observable behavior changed. Pull requests should include a brief -summary, tests run, and any compatibility impact for public macros, generated -headers, installation paths, or CMake/pkg-config consumers. +summary, tests run, any compatibility impact for public macros, generated +headers, installation paths, or CMake/pkg-config consumers, and a link to the +issue they close. ## Agent-Specific Instructions +**Outstanding work goes in the issue tracker, not in a file.** Open an issue at + — `tea issues create +--repo andrew/libakerror` — 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 why +the handler ladder is a major-version change, why a copied `akerr_ErrorContext` +is a trap, why validating more inputs lowers branch coverage, and why the +mutation score is a floor. A description of work still to do goes stale the +moment somebody does it. + +**This library's defects are most often found by its consumers, so make filing +them cheap.** Three defects in this library — `IGNORE()` leaking a context, the +un-namespaced `coverage` target, and the missing `akerrorConfigVersion.cmake` — +were written down in `libakstdlib`'s own notes and never here, so each was +worked around once per consumer and nobody saw the pattern. A consumer filing +upstream should cost them one issue instead of one workaround. `libakgl`, +`libakstdlib` and `akbasic` are all on the same forge. + Do not overwrite uncommitted user changes. Avoid editing generated files in `build/`; update `include/akerror.tmpl.h`, `src/error.c`, CMake files, tests, or scripts instead.