andrew/libakerror
1
0
Fork 0
Code Issues 15 Pull Requests 1 Actions 1 Packages Projects Releases Wiki Activity

Point AGENTS.md at the issue tracker for outstanding work

Browse Source 
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) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
This commit is contained in:
Tachikoma
2026-08-02 19:24:49 -04:00
parent 24469e83d4
commit 23df4069ab
1 changed files with 22 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
AGENTS.md
View File

@@ -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 Recent commits use short, imperative, sentence-case subjects, for example
`Fix refcount leak and stack-trace buffer overflow`. Keep commits focused and `Fix refcount leak and stack-trace buffer overflow`. Keep commits focused and
describe the observable behavior changed. Pull requests should include a brief describe the observable behavior changed. Pull requests should include a brief
summary, tests run, and any compatibility impact for public macros, generated summary, tests run, any compatibility impact for public macros, generated
headers, installation paths, or CMake/pkg-config consumers. headers, installation paths, or CMake/pkg-config consumers, and a link to the
issue they close.
## Agent-Specific Instructions ## Agent-Specific Instructions
**Outstanding work goes in the issue tracker, not in a file.** Open an issue at
<https://source.starfort.tech/andrew/libakerror/issues> — `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 Do not overwrite uncommitted user changes. Avoid editing generated files in
`build/`; update `include/akerror.tmpl.h`, `src/error.c`, CMake files, tests, `build/`; update `include/akerror.tmpl.h`, `src/error.c`, CMake files, tests,
or scripts instead. or scripts instead.