TODO - residuals that drive themselves out A `// TODO:` comment is a promise with no way to collect on it. It cannot fail, cannot be counted, cannot be assigned, and cannot tell you it came true while nobody was looking. Measured 2026-08-11: 128 of them in this repo (88 in src/, 40 in koru_std/), every one invisible to everything but grep. This module makes a residual DRIVABLE, which is a different and much narrower claim than making it visible. The distinction is the whole design: WHAT MAKES A RESIDUAL DRIVABLE IS NOT THAT IT IS DECLARED. IT IS THAT SOMETHING CAN RUN AND DECIDE IT. The proof already sits in this repo. 66 regression tests carry a `TODO` marker file, and scripts/todo_sweep.sh drives every one of them without reading a single word of their prose — it runs them and reads the verdict. That works because a parked test HAS A BODY. A comment does not, so no amount of declaring one makes it drivable; it only makes it tidy. So a declaration here is not a nicer comment. It is the act of GIVING A RESIDUAL A BODY, and the module refuses declarations that fail to. TWO DISPOSITIONS, TWO DIFFERENT CLOSERS. They differ by who can close them, and — as with std/invariants — the NAME carries the bit, because you cannot recover it by re-reading afterwards. "Implement cross-flow optimization" reads like a build task and is actually a ruling; nothing in the text says so, and the person who knew has moved on. owed — someone must BUILD this. It names a witness: a regression test that is red today and green when the residual is discharged. The sweep drives it with no human in the loop. Growth is debt. doubted — someone must RULE on this. No amount of building closes it, because the open question is whether the thing should exist at all. It names the question and what evicts if the answer is no. A machine can only surface it. Growth means unanswered questions accumulating, which is a different illness from debt and wants a different medicine. The gradients are opposite in the way that lets a gate judge the pile without understanding any entry in it: `owed` shrinks by writing code, `doubted` shrinks by someone answering. A pile that only ever grows on the `doubted` side is not a backlog, it is a queue of decisions nobody is making. A WITNESS IS MANDATORY, AND THIS IS THE POINT OF THE MODULE An `owed` residual MUST name a test, and the reader below exits non-zero if that test does not exist or pins nothing. That refusal is not pedantry — it is the entire safety property, and it was bought with a measured failure. The first run of scripts/todo_sweep.sh found three parked tests passing and NONE of them promotable: two asserted only that the program exited zero, and both printed the exact error they were parked on. A driver pointed at residuals with no real assertion does not close them, it manufactures victories — green-by-edit with a work queue attached. So the entry fee is a failing test, and it doubles as an honesty filter: a residual you cannot write a red test for is one you do not yet understand well enough to declare. Leave it a comment until you do. EVERY FIELD HERE IS READ BY THE READER BELOW Deliberate, and a correction of a live defect in the sibling module: the three rules in invariants/invariants.kz each carry a `"check"` command, the reader never prints it, and nothing runs it. A declared field with no consumer is a residual wearing the costume of a feature. If a field is added here it gets printed or it gets refused. Usage — a JSON block, exactly as flag.declare and std/invariants take one: std/todo:owed { "name": "serializer-drops-branches", "site": "src/ast_serializer.zig:1325", "owed": "The serializer writes an empty branch list for every conditional, so a program round-tripped through it comes back with its branches gone. Silent wrong output, no diagnostic.", "witness": "395_020_serializer_round_trips_a_conditional", "tags": ["silent-wrong-output"] } std/todo:doubted { "name": "optimizer-layer", "question": "Does an optimizer layer exist in this compiler, or not?", "evicts": "21 residuals and their dead stubs: nine slots in src/compiler_coordinator.zig that take a program and return false, four emit sites writing a comment where a fused or inlined event belongs, and the loop and kernel notes in koru_std/optimizations/.", "tags": ["ruling"] } `name` is the identity — nothing else is. `site` says where the residual physically lives, because unlike an invariant (a claim about the whole program) a residual is always about ONE PLACE. `tags` route it to consumers. In pure `.k` there is no tilde — this is a Koru feature, not a host-embedding one. A host-embedding file writes the same block with ``. [norun] for the same reason as flag.declare and std/invariants: the declaration never executes. It is data in the AST, harvested after the parse by whoever asks. That is what makes the surface metacircular — a consumer discovers residuals by parsing the program, never from a hardcoded list.