docs/ is at both caps at once, so no change can add a page #1020

New issue

Open

opened 2026-08-19 02:10:12 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-19 02:10:12 +00:00

Member

Not urgent, but it now blocks work rather than merely looking untidy. Hit while landing #1018.

The state

docs/ holds 40 pages against a 40-page cap, and they are all pressed against the 8000-character cap:

7993  delivery, phrases, tools
7994  commands
7995  FEATURES, progress, reply-assembly, turn-stages
8000  access, admission, mcp, telemetry
8014  worklog

That distribution is not natural. Pages do not independently arrive within seven characters of a limit. It is the signature of successive changes shaving prose to fit, which is what I did on #1007 and #1003 and said at the time was the wrong move.

Why both caps at once is a wall

large is the top band, so there is nothing to declare upward. The two caps then close every exit:

Adding a page fails the count cap.
Adding a paragraph to any existing page fails the size cap.
Splitting a page to make room fails the count cap, and the validator names this directly: "splitting one doc into two to clear the size cap trades one violation for another."
There is no per-file escape. check_documentation_layout.py says so outright: "There is no per-file escape from a size or count cap."

None of that is a bug. The count cap exists "because a per-doc cap on its own does not bound a docs folder, it reshapes it", which is exactly the reshaping I attempted. The design is working. It is telling us the docs need consolidating.

What #1018 did instead

It shipped without a page. The mechanism it introduces is documented in agent-compose, which authors it, and the lane carries a two-line comment naming the issue. That is defensible for one change, because the owning layer really is upstream. It is not a general answer: the next lane-local behaviour with nowhere upstream to document it has no exit at all.

What would fix it

Merging related pages, which is the validator's own instruction. Plausible groupings from the current list, offered as a starting point rather than a plan:

turn-stages, reply-assembly, and progress all describe one turn's path.
access and admission are two halves of who gets answered.
phrases and commands are both surface vocabulary.

Each merge buys a page and, because the merged page still has to fit 8000 characters, forces the compression that has been happening silently to happen deliberately and in review. That is the actual value here: the shaving is already occurring, it is just invisible.

Worth doing when someone has a clear afternoon and can read the pages properly. Not worth doing at speed, since the failure mode is deleting something load-bearing to hit a number.

Not urgent, but it now blocks work rather than merely looking untidy. Hit while landing #1018. ## The state `docs/` holds 40 pages against a 40-page cap, and they are all pressed against the 8000-character cap: ``` 7993 delivery, phrases, tools 7994 commands 7995 FEATURES, progress, reply-assembly, turn-stages 8000 access, admission, mcp, telemetry 8014 worklog ``` That distribution is not natural. Pages do not independently arrive within seven characters of a limit. It is the signature of successive changes shaving prose to fit, which is what I did on #1007 and #1003 and said at the time was the wrong move. ## Why both caps at once is a wall `large` is the top band, so there is nothing to declare upward. The two caps then close every exit: - Adding a page fails the count cap. - Adding a paragraph to any existing page fails the size cap. - Splitting a page to make room fails the count cap, and the validator names this directly: "splitting one doc into two to clear the size cap trades one violation for another." - There is no per-file escape. `check_documentation_layout.py` says so outright: "There is no per-file escape from a size or count cap." None of that is a bug. The count cap exists "because a per-doc cap on its own does not bound a docs folder, it reshapes it", which is exactly the reshaping I attempted. The design is working. It is telling us the docs need consolidating. ## What #1018 did instead It shipped without a page. The mechanism it introduces is documented in agent-compose, which authors it, and the lane carries a two-line comment naming the issue. That is defensible for one change, because the owning layer really is upstream. It is not a general answer: the next lane-local behaviour with nowhere upstream to document it has no exit at all. ## What would fix it Merging related pages, which is the validator's own instruction. Plausible groupings from the current list, offered as a starting point rather than a plan: - `turn-stages`, `reply-assembly`, and `progress` all describe one turn's path. - `access` and `admission` are two halves of who gets answered. - `phrases` and `commands` are both surface vocabulary. Each merge buys a page and, because the merged page still has to fit 8000 characters, forces the compression that has been happening silently to happen deliberately and in review. That is the actual value here: the shaving is already occurring, it is just invisible. Worth doing when someone has a clear afternoon and can read the pages properly. Not worth doing at speed, since the failure mode is deleting something load-bearing to hit a number.

coilyco-ops referenced this issue

2026-08-19 02:10:24 +00:00

feat(dowel): compose the lane without boundaries it has no seat for #1018

coilyco-ops referenced this issue

2026-08-19 02:54:34 +00:00

feat(temporal): serve the lane's own Temporal namespace as read-only MCP #1028

coilyco-ops added the

labels