Record what the caps-reference drift hook cannot catch #1395

Merged

coilyco-ops merged 2 commits from aos/claude/ee98-capsprose into main

2026-08-29 10:20:41 +00:00

coilyco-ops commented

2026-08-29 09:13:07 +00:00

Owner

#1337's first two acceptance criteria were already met by 4ed13fe6, which landed under #1331: every band row now reads "lines, blank ones included" and the module README row correctly keeps "non-blank lines". #1337 is a duplicate that stayed open.

This closes the third criterion, which asked whether prose-level drift is the sync hook's job.

The answer is split, and worth writing down where the hook is:

check_drift byte-compares the whole rendered document (actual == expected), so doc-vs-generator drift is impossible. The doc cannot be hand-edited at all.
It cannot see the generator's own prose drifting from validator behavior. Those description strings are hand-written and nothing compares them to the code. That is precisely how the band rows came to say "non-blank" while the validator counted every line.

The guard for that second class is a behavior test, test_the_line_cap_counts_blank_lines_too, which measures a 62-line file against the 40-line cap rather than trusting prose. The docstring now names it.

Closes #1337

#1337's first two acceptance criteria were already met by `4ed13fe6`, which landed under **#1331**: every band row now reads "lines, blank ones included" and the module README row correctly keeps "non-blank lines". #1337 is a duplicate that stayed open. This closes the third criterion, which asked whether prose-level drift is the sync hook's job. The answer is split, and worth writing down where the hook is: * `check_drift` byte-compares the whole rendered document (`actual == expected`), so **doc-vs-generator drift is impossible**. The doc cannot be hand-edited at all. * It cannot see the **generator's own prose drifting from validator behavior**. Those description strings are hand-written and nothing compares them to the code. That is precisely how the band rows came to say "non-blank" while the validator counted every line. The guard for that second class is a behavior test, `test_the_line_cap_counts_blank_lines_too`, which measures a 62-line file against the 40-line cap rather than trusting prose. The docstring now names it. Closes #1337

coilyco-ops added 1 commit

2026-08-29 09:13:08 +00:00

docs(caps-reference): record what the drift hook cannot catch

ci / aos-cli-tests (pull_request) Successful in 40s

Details

ci / gate (pull_request) Failing after 43s

Details

ffc7812d2a

The hook byte-compares the whole doc against a fresh render, so the doc
cannot drift from the generator. The class it cannot see is this
generator's own prose drifting from what the validator measures, which is
how the band rows came to say "non-blank" against a validator counting
every line. Name the behavior test that guards that instead.

Closes coilyco-flight-deck/agentic-os#1337

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Agent-Role: platform

coilysiren added 1 commit

2026-08-29 09:52:30 +00:00