fix(caps-reference): the band line caps count blank lines, so stop calling them non-blank #1331

Merged

coilyco-ops merged 3 commits from ops/caps-reference-line-semantics into main

2026-08-28 02:52:52 +00:00

coilyco-ops commented

2026-08-28 02:50:54 +00:00

Owner

The numbers never drifted. The unit did.

docs/catalog-caps-reference.md is the fleet's single source of truth for the validator caps, generated from the validator constants precisely so that code and prose cannot drift apart. It described three caps as counting non-blank lines. check_markdown_sizes measures len(text.splitlines()) -- every line, blanks included -- for both bands and for the root README overview.

On agentic-os-kai/docs/FEATURES.md the difference is 73 against an actual 122. Anyone budgeting a doc from the reference lands 40 percent over cap and only finds out at commit time, which is exactly the failure a generated reference exists to prevent.

What changed

The generator's descriptions for small band, large band, and README overview now say "lines, blank ones included".
docs/catalog-caps-reference.md regenerated through just gen-caps-reference, never hand-edited.
The module README cap is deliberately left saying non-blank, because it genuinely counts non-blank lines. docs/documentation-bands.md states that outright and blank lines are free there. Three of the four were wrong, not all four.

A test rather than more prose

The wording could revert on the next edit and nothing would catch it, since check-caps-reference-drift only proves the doc matches the generator, not that either matches the validator. So the semantics are pinned executably: a 62-line file with 2 non-blank lines must fail a 40-line cap.

Provenance

Found while migrating agentic-os-kai onto the bands for coilysiren/inbox#374, when a file measured 73 by hand and 122 by the hook.

747 tests pass and pre-commit run --all-files exits 0.

## The numbers never drifted. The unit did. `docs/catalog-caps-reference.md` is the fleet's single source of truth for the validator caps, generated from the validator constants precisely so that code and prose cannot drift apart. It described three caps as counting **non-blank lines**. `check_markdown_sizes` measures `len(text.splitlines())` -- every line, blanks included -- for both bands and for the root README overview. On `agentic-os-kai/docs/FEATURES.md` the difference is **73 against an actual 122**. Anyone budgeting a doc from the reference lands 40 percent over cap and only finds out at commit time, which is exactly the failure a generated reference exists to prevent. ## What changed * The generator's descriptions for **small band**, **large band**, and **README overview** now say "lines, blank ones included". * `docs/catalog-caps-reference.md` regenerated through `just gen-caps-reference`, never hand-edited. * The **module README** cap is deliberately left saying non-blank, because it genuinely counts non-blank lines. `docs/documentation-bands.md` states that outright and blank lines are free there. Three of the four were wrong, not all four. ## A test rather than more prose The wording could revert on the next edit and nothing would catch it, since `check-caps-reference-drift` only proves the doc matches the generator, not that either matches the validator. So the semantics are pinned executably: a 62-line file with 2 non-blank lines must fail a 40-line cap. ## Provenance Found while migrating `agentic-os-kai` onto the bands for coilysiren/inbox#374, when a file measured 73 by hand and 122 by the hook. 747 tests pass and `pre-commit run --all-files` exits 0.

coilyco-ops added 2 commits

2026-08-28 02:50:54 +00:00

fix(pr-guard): stand down on the merge-remote-main lane it was overriding

ci / ward-doctor (pull_request) Successful in 7s

Details

ci / aos-eval-tests (pull_request) Successful in 8s

Details

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

Details

ci / gate (pull_request) Successful in 50s

Details

8a42b63af3

pr-guard refused every push whose destination is the remote default branch,
unconditionally. `merge-remote-main` is defined as commit, push to `main`,
close the issue, so on the eight repos declaring that lane one hook rendered
prose telling the agent to push `main` and a second hook refused the push. The
only documented override is `--no-verify`, which the fleet rules forbid, so
those repos had no compliant path and every further hook-pin advance widened
the contradiction.

The lane has one owning reader, so the guard asks it rather than growing a
second frontmatter parser: `generate-git-workflow` gains `--print-lane`, and
the guard resolves it through `AOS_LANE_READER`, PATH, then the python env
pre-commit built for this hook repo's other hooks. An unresolved answer reads
as undeclared, and undeclared stays guarded.

Standing down exits rather than falling through, because the already-published
half below judges feature branches and the default branch has no pull request
of its own to find. That half is untouched on every lane.

Closes #1321

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Agent-Role: platform

fix(caps-reference): the band line caps count blank lines, so stop calling them non-blank

ci / ward-doctor (pull_request) Successful in 8s

Details

ci / aos-eval-tests (pull_request) Successful in 8s

Details

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

Details

ci / gate (pull_request) Successful in 49s

Details

5b789faa9e

docs/catalog-caps-reference.md is the fleet's single source of truth for these
numbers, generated from the validator constants precisely so code and prose
cannot drift. The numbers never drifted. The unit did.

check_markdown_sizes measures len(text.splitlines()), every line, for both
bands and for the root README overview. The generator described all three as
"non-blank lines". On agentic-os-kai's docs/FEATURES.md that reads 73 against
an actual 122, so anyone budgeting a doc against the reference lands 40 percent
over cap and only finds out at commit time. That is a bad failure for a file
whose entire job is to be the number you trust without reading the validator.

The module README cap is left alone: it genuinely counts non-blank lines, which
docs/documentation-bands.md states explicitly and blank lines are free there.

A test pins the semantics rather than the prose, so the wording cannot quietly
revert: a 62-line file with 2 non-blank lines must fail a 40-line cap.

Found while migrating agentic-os-kai onto the bands (coilysiren/inbox#374).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Agent-Role: platform

coilyco-ops added 1 commit

2026-08-28 02:52:32 +00:00

Merge branch 'main' into ops/caps-reference-line-semantics

ci / aos-eval-tests (pull_request) Successful in 7s

Details

ci / ward-doctor (pull_request) Successful in 5s

Details

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

Details

ci / gate (pull_request) Successful in 56s

Details

450ecaa098