docs(turn-stages): bring the page back under its size cap #1081

Merged

coilysiren merged 1 commit from aos/claude/turn-stages-over-cap into main

2026-08-19 16:03:33 +00:00

coilyco-ops commented

2026-08-19 15:54:11 +00:00

Member

main is currently failing catalog-doc-size and documentation-layout.

What happened

#1077 and #1079 both landed content in docs/sirens-echo-turn-stages.md.
Each passed the caps on its own branch, and the merged result was never checked
against them, so the page has been at 8895 chars against a ceiling of 8000
since ba51431.

Reproduce on a clean main:

pre-commit run documentation-layout --all-files

The fix

Trims the turn-allowance section, the larger of the two additions and mine. The
measurement narrative it carried (round distributions, span counts, the
three-completions decomposition) is preserved in #1076 and the #1077 PR body,
which the section now cites rather than restates. #1079's correction is
untouched.

Back to 7951 chars, 49 of headroom.

The structural part, which this does not fix

docs/ is at 40 pages against a 40-page cap, and the pages that could
absorb overflow are all within a few hundred chars of their own ceiling:
tools.md 7987, tuning.md ~7900, model-call.md 7851, FEATURES.md 7924
against 8000 each.

So there is nowhere to put a new page and nowhere to move a section, and the
caps are now shaping what gets written rather than catching bloat. That is why
#1077 shipped without a FEATURES.md entry and why its prose landed here
instead of on its own page. Worth deciding whether to merge some pages or move
the band, but that is a call rather than a cleanup, so it is not in this PR.

`main` is currently failing `catalog-doc-size` and `documentation-layout`. ## What happened #1077 and #1079 both landed content in `docs/sirens-echo-turn-stages.md`. Each passed the caps on its own branch, and the merged result was never checked against them, so the page has been at **8895 chars** against a ceiling of 8000 since `ba51431`. Reproduce on a clean `main`: pre-commit run documentation-layout --all-files ## The fix Trims the turn-allowance section, the larger of the two additions and mine. The measurement narrative it carried (round distributions, span counts, the three-completions decomposition) is preserved in #1076 and the #1077 PR body, which the section now cites rather than restates. #1079's correction is untouched. Back to **7951 chars**, 49 of headroom. ## The structural part, which this does not fix `docs/` is at **40 pages against a 40-page cap**, and the pages that could absorb overflow are all within a few hundred chars of their own ceiling: `tools.md` 7987, `tuning.md` ~7900, `model-call.md` 7851, `FEATURES.md` 7924 against 8000 each. So there is nowhere to put a new page and nowhere to move a section, and the caps are now shaping what gets written rather than catching bloat. That is why #1077 shipped without a `FEATURES.md` entry and why its prose landed here instead of on its own page. Worth deciding whether to merge some pages or move the band, but that is a call rather than a cleanup, so it is not in this PR.

coilyco-ops added 1 commit

2026-08-19 15:54:11 +00:00

docs(turn-stages): bring the page back under its size cap

ci / image-build (pull_request) Successful in 31s

Details

ci / test (pull_request) Successful in 1m1s

Details

ci / publish-echo-image (pull_request) Has been skipped

Details

ci / publish-observed (pull_request) Has been skipped

Details

f14100f849

#1077 and #1079 both landed content in this page and the merged result was
never checked against the caps, so main has been failing catalog-doc-size and
documentation-layout at 8895 chars against a ceiling of 8000.

Trims the turn-allowance section, the larger of the two additions and mine.
The measurement narrative it carried is preserved in #1076 and the #1077 PR
body, which the section now cites rather than restates.

The page is left with 49 chars of headroom. docs/ is also at its 40-page cap,
so this repo has outgrown the large band rather than merely overshot one page.

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>

coilyco-ops requested review from coilysiren

2026-08-19 15:54:11 +00:00