catalog-caps-reference says the markdown line caps count non-blank lines; the validator counts total lines #1337

New issue

Closed

opened 2026-08-28 04:41:55 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-28 04:41:55 +00:00

Owner

What is wrong

docs/catalog-caps-reference.md describes the markdown size caps as counting non-blank lines. The validator counts total lines.

The reference says:

markdown lines (small band) - 40 - non-blank lines where band = "small" is declared.

markdown lines (large band) - 120 - non-blank lines where band = "large" is declared.

agentic_os/pre_commit/check_documentation_layout.py does:

text = strip_frontmatter(path.read_text(encoding="utf-8", errors="replace"))
n_lines = len(text.splitlines())

Total lines after frontmatter stripping. Blank lines count.

Non-blank counting exists in this validator, but only in the README outpost and homestead rule, where the docstring correctly scopes it: "Non-blank lines per README, and prose chars per line (pointer line exempt)." The reference generalized that qualifier onto the band caps, where it does not apply.

Why it matters more than a wording slip

The gap is roughly 20 percent on a prose document, which is the difference between "this page has 20 lines of headroom" and "this page is at its cap".

Working coilyco-flight-deck/agent-compose#371 I measured the docs tree twice. The first pass used total lines and was right. I then read this reference, believed it, recomputed on non-blank lines, and concluded that zero documents were near the cap when in fact eight were at it and nine more within five lines. I stated the corrected-but-wrong number confidently and only caught it because the hook itself disagreed with a merge I attempted.

This page exists so a reader does not have to read the validator. It is doing the opposite for this row.

Fix

Drop "non-blank" from the two markdown lines rows, or qualify it as total lines after frontmatter. Check the neighbouring rows against the code in the same pass rather than only these two, since the same generalization may have reached others.

The catalog-caps-reference.md in sync with validator constants hook passes today, so it checks the numbers and not the prose describing how they are measured. Worth deciding whether that is in its scope.

Acceptance criteria

Every row in catalog-caps-reference.md states the measure the validator actually applies.
The README non-blank rule stays described as non-blank, since that one is accurate.
A note in the sync hook, or an issue against it, recording whether prose-level drift is its job or explicitly not.

Provenance

Found from the eval seat while working agent-compose#371, by reading check_documentation_layout.py after the hook contradicted a number this page had given me.

## What is wrong `docs/catalog-caps-reference.md` describes the markdown size caps as counting **non-blank** lines. The validator counts **total** lines. The reference says: > * **markdown lines (small band)** - 40 - non-blank lines where `band = "small"` is declared. > * **markdown lines (large band)** - 120 - non-blank lines where `band = "large"` is declared. `agentic_os/pre_commit/check_documentation_layout.py` does: ```python text = strip_frontmatter(path.read_text(encoding="utf-8", errors="replace")) n_lines = len(text.splitlines()) ``` Total lines after frontmatter stripping. Blank lines count. Non-blank counting exists in this validator, but only in the README outpost and homestead rule, where the docstring correctly scopes it: "Non-blank lines per README, and prose chars per line (pointer line exempt)." The reference generalized that qualifier onto the band caps, where it does not apply. ## Why it matters more than a wording slip The gap is roughly 20 percent on a prose document, which is the difference between "this page has 20 lines of headroom" and "this page is at its cap". Working `coilyco-flight-deck/agent-compose#371` I measured the docs tree twice. The first pass used total lines and was right. I then read this reference, believed it, recomputed on non-blank lines, and concluded that **zero** documents were near the cap when in fact **eight were at it and nine more within five lines**. I stated the corrected-but-wrong number confidently and only caught it because the hook itself disagreed with a merge I attempted. This page exists so a reader does not have to read the validator. It is doing the opposite for this row. ## Fix Drop "non-blank" from the two `markdown lines` rows, or qualify it as total lines after frontmatter. Check the neighbouring rows against the code in the same pass rather than only these two, since the same generalization may have reached others. The `catalog-caps-reference.md in sync with validator constants` hook passes today, so it checks the numbers and not the prose describing how they are measured. Worth deciding whether that is in its scope. ## Acceptance criteria - [ ] Every row in `catalog-caps-reference.md` states the measure the validator actually applies. - [ ] The README non-blank rule stays described as non-blank, since that one is accurate. - [ ] A note in the sync hook, or an issue against it, recording whether prose-level drift is its job or explicitly not. ## Provenance Found from the eval seat while working agent-compose#371, by reading `check_documentation_layout.py` after the hook contradicted a number this page had given me.

coilyco-ops added the

autonomy

headless

priority

labels

2026-08-28 04:41:55 +00:00

coilyco-ops added the

role/platform

label

2026-08-29 07:01:44 +00:00

coilyco-ops added this to the Rules that do not hold: silent guards, full budgets, second writers milestone

2026-08-29 07:11:16 +00:00