Version at 0.2.0: complete the wishlist, document it, gate the docs

Closes what was left of TODO.md sections 1, 2 and 3, and rewrites that
file to hold outstanding items only.

The API break gets a minor bump, because pre-1.0 the soname carries
MAJOR.MINOR and 0.1 and 0.2 are therefore different ABIs. Five
signatures changed and the ato* contract with them; UPGRADING.md is new
and lists every one, with the before/after for the cases the compiler
cannot warn about.

Section 3.1 is finished: reallocarray with the multiplication checked,
aligned_alloc and posix_memalign, asprintf/vasprintf, scanf/vscanf.
Four functions on that list are deliberately absent rather than missing
-- sprintf, strtok, setbuf and perror -- and TODO.md now says which and
why, so nobody adds them thinking they were forgotten.

Section 1.9, the cross-cutting tests:

  tests/test_pool.c    drives every failure path AKERR_MAX_ARRAY_ERROR
                       + 10 times and checks the pool after each round,
                       because a wrapper that leaks a slot fails a
                       hundred calls later in unrelated code. It also
                       asserts that each error names the function and
                       file it was raised from, which is what catches a
                       FAIL that migrates into a helper during a
                       refactor: status right, message right, origin
                       quietly lying.
  tests/negative/      two sources that must FAIL to compile, built with
                       -Werror and registered WILL_FAIL. AKERR_NOIGNORE
                       and the format attributes are enforced by the
                       compiler and by nothing else; drop either and
                       every ordinary test still passes.

Thread safety is answered rather than tested: the library is not
thread-safe and cannot be made so from here, because libakerror's error
pool is an unlocked process-global array. README.md says so plainly and
TODO.md carries it as the item blocking any future pthread wrappers.

Doxygen is configured and gated. All 147 public functions have @brief,
a @param each, @throws per status and @return; EXTRACT_ALL is off and
WARN_NO_PARAMDOC on, so `cmake --build build --target docs` fails on an
undocumented entity. It ran to 0 warnings. The Doxyfile carries no
version -- cmake/RunDoxygen.cmake feeds PROJECT_NUMBER in from
project(), so that stays the one place a version is written.

CI now builds against the submodule it pins instead of also installing
libakerror@main and never linking it, adds -Werror, and gains a
sanitizer job. The pre-push hook matches, and runs the docs check too.

Coverage: 99.5% of lines (1643/1651), 100% of functions (147/147). The
eight uncovered lines are each uncovered on purpose and TODO.md says
which and why.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -2,14 +2,27 @@
 
 ## Project Structure & Module Organization
 
-`libakstdlib` is a C shared library that wraps libc calls and small data
-structures in `libakerror` error contexts. Public API declarations live in
-`include/akstdlib.h`; implementation lives in `src/stdlib.c`. Tests are
-one-file CTest executables under `tests/test_<name>.c`, with shared test helpers
-in `tests/aksl_capture.h`. CMake package templates are in `cmake/` and
-`akstdlib.pc.in`. The vendored dependency is `deps/libakerror`; update it as a
-submodule rather than editing generated files under `build/`, `build-asan/` or
-`build-coverage/`.
+`libakstdlib` is a C shared library that wraps libc calls and data structures in
+`libakerror` error contexts.
+
+Public API declarations live in `include/akstdlib.h`, which is also where the
+Doxygen documentation lives -- the header is the contract, the sources carry the
+reasoning. The implementation is split by domain:
+
+| File | Covers |
+|---|---|
+| `src/stdlib.c` | memory, formatted output, string-to-number, realpath, djb2, and the list/tree traversal entry points |
+| `src/string.c` | the `string.h` surface |
+| `src/stream.c` | `stdio.h` beyond open/read/write/close |
+| `src/collections.c` | list and tree operations, hash map, string buffer, FNV-1a |
+| `src/aksl_internal.h` | shared internals; not installed, not public |
+
+Tests are one-file CTest executables under `tests/test_<name>.c`, with shared
+helpers in `tests/aksl_capture.h`. `tests/negative/` holds sources that must
+*fail* to compile -- see the testing section below. CMake package templates are
+in `cmake/` and `akstdlib.pc.in`. The vendored dependency is `deps/libakerror`;
+update it as a submodule rather than editing generated files under `build/`,
+`build-asan/` or `build-coverage/`.
 
 ## Build, Test, and Development Commands
 
@@ -40,8 +53,15 @@ cmake --build build-coverage --target coverage
 ```
 
 Run `cmake --build build --target mutation` only when you need the slower
-mutation harness. `rebuild.sh` installs to `/home/andrew/local` and removes the
-local build directory, so treat it as a local convenience script.
+mutation harness, and `cmake --build build --target docs` to regenerate the API
+documentation -- that one fails if any public function, parameter or return value
+is undocumented, so it is a check as well as a generator.
+
+`.githooks/pre-push` runs the default build, the sanitizer build and the
+documentation check before a push; enable it with
+`git config core.hooksPath .githooks`. `rebuild.sh` installs to
+`/home/andrew/local` and removes the local build directory, so treat it as a
+local convenience script.
 
 ## Coding Style & Naming Conventions
 
@@ -51,16 +71,45 @@ prefix, structs use `aksl_<Name>`, and tests use `test_<feature>.c` plus static
 `test_<case>` functions. Preserve the `akerr_ErrorContext AKERR_NOIGNORE *`
 return convention and the `PREPARE_ERROR` / `FAIL_*` / `SUCCEED_RETURN` pattern.
 
+Four conventions hold across the whole library, and a new wrapper that breaks one
+of them is wrong even if it compiles and passes:
+
+- **A NULL out-param is a caller error**, not "don't care".
+- **Finding nothing is success** -- searching functions write NULL or zero and
+  return NULL.
+- **Truncation is a failure.** Take the destination's size, raise
+  AKERR_OUTOFBOUNDS, and write nothing rather than a prefix.
+- **Clear `errno` before the wrapped call** and read it back through
+  `AKSL_ERRNO_OR`, so no error can carry status 0 -- which every downstream
+  `DETECT` reads as success.
+
+Every new public function needs a Doxygen block on its **declaration** with
+`@brief`, a `@param` per parameter, a `@throws` per status it can raise, and
+`@return`. The `docs` target fails otherwise.
+
+The build is `-Wall -Wextra` and CI adds `-Werror`. `-Wpedantic` is deliberately
+off: libakerror's `FAIL_*` macros trip "ISO C99 requires at least one argument
+for the ..." on their own expansion, not on anything at the call site.
+
 ## Testing Guidelines
 
 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
-starts unexpectedly passing, move it into `AKSL_TESTS` with the fix.
+starts unexpectedly passing, move it into `AKSL_TESTS` with the fix. Both of the
+latter are currently empty -- all six confirmed defects are fixed -- but the
+mechanism stays for the next one.
 
-`src/stdlib.c` is at 99.1% line coverage and CI gates it at 90 (line) / 40
-(branch), so new code needs tests in the same commit. Run
+`tests/negative/` holds sources that must **fail** to compile. Each is an
+`EXCLUDE_FROM_ALL` target built with `-Werror` and registered as a `WILL_FAIL`
+CTest entry, so the test passes only when the compile fails. They cover the two
+guarantees the compiler enforces and nothing else does: `AKERR_NOIGNORE` and the
+format attributes. Drop either in a refactor and every ordinary test still
+passes.
+
+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
 defective belong in `AKSL_KNOWN_FAILING_TESTS` asserting the *correct* contract —