coilyco-gaming/sirens-echo

Watch

The docs band is saturated: four pages at their cap, and no room for a 41st page either #1009

New issue

Closed

opened 2026-08-19 01:38:39 +00:00 by coilyco-ops · 3 comments

coilyco-ops commented

2026-08-19 01:38:39 +00:00

Member

Filed by the engineer seat after hitting this on four consecutive changes tonight. Not a complaint about the rule, which is a good rule. A report that it has stopped having anywhere to give.

Measured, on `main`

page	chars	cap
`docs/sirens-echo-mcp.md`	8000	8000
`docs/sirens-echo-tools.md`	7993	8000
`docs/sirens-echo-delivery.md`	7976	8000
`docs/sirens-echo-commands.md`	7958	8000

And docs/ holds 40 pages against a 40-page cap.

So documenting a new behaviour on any of those four pages has between 0 and 42 characters of room, and the escape hatch the hook itself suggests ("Split large docs into smaller docs/*.md files") is closed by the count cap, whose message says the opposite: "Merge related pages; splitting one doc into two to clear the size cap trades one violation for another."

What that did to four PRs tonight

#1001 (/mcp) - merged the /mcps section into one covering both commands and compressed it to fit.
#1003 (#933) - replaced the paragraph's enumeration of six notice phrases with the classification rule. The enumeration duplicated notice.go and grew by one entry per condition, which is part of how the page filled.
#1005 (#948) - fit only because sirens-deep-owl-glass is longer than sirens-dowel.
#1007 (#943) - the tool breaker gets one sentence, and three unrelated sentences on the page were compressed to make room for it. The reasoning lives in the PR.

Every one of those is a real edit I would defend individually. Together they are a pattern: the cap is now paid for by compressing prose Kai wrote, and by moving rationale out of docs and into PR descriptions, which is the opposite of what the comment-density doctrine in AGENTS.md asks for. It sends explanation to docs/ precisely so it is read.

Why it is worth deciding rather than absorbing

The next person to document a new behaviour on one of those four pages will do the same thing, and the compression is lossy in a way a diff makes hard to see. #1003's own commit had to cut an enumeration to fit a rule about not collapsing categories, which is a small irony but a real one.

Options, not a recommendation

I am the wrong seat to pick, because this is repo-wide policy rather than a defect.

Raise the band. pyproject.toml already carries band = "large" under [tool.agentic-os.documentation-layout]. The caps live in agentic-os, so a new band is an upstream change, not a local one.
Raise only the docs count, so pages can split. That contradicts the count cap's stated reasoning, which is worth taking seriously rather than routing around.
Merge pages. There are 40, several of which are narrow. That frees count and chars together and is the option the hook's own message points at.
Accept it and treat PR descriptions as the durable home for rationale. Defensible, but it should be a decision rather than a drift, because it changes where a reader looks.

Not claimed

I have not established that any of tonight's compressions lost a fact. I checked each one as I made it. I am reporting that the mechanism now requires that judgement on every docs change to four pages, which is a different and more fragile situation than the cap was designed for.

**Filed by the engineer seat** after hitting this on four consecutive changes tonight. Not a complaint about the rule, which is a good rule. A report that it has stopped having anywhere to give. ## Measured, on `main` | page | chars | cap | | --- | --- | --- | | `docs/sirens-echo-mcp.md` | **8000** | 8000 | | `docs/sirens-echo-tools.md` | **7993** | 8000 | | `docs/sirens-echo-delivery.md` | **7976** | 8000 | | `docs/sirens-echo-commands.md` | **7958** | 8000 | And `docs/` holds **40 pages against a 40-page cap**. So documenting a new behaviour on any of those four pages has between **0 and 42 characters** of room, and the escape hatch the hook itself suggests ("Split large docs into smaller docs/\*.md files") is closed by the count cap, whose message says the opposite: "Merge related pages; splitting one doc into two to clear the size cap trades one violation for another." ## What that did to four PRs tonight * **#1001** (`/mcp`) - merged the `/mcps` section into one covering both commands and compressed it to fit. * **#1003** (#933) - replaced the paragraph's enumeration of six notice phrases with the classification rule. The enumeration duplicated `notice.go` and grew by one entry per condition, which is part of how the page filled. * **#1005** (#948) - fit only because `sirens-deep-owl-glass` is longer than `sirens-dowel`. * **#1007** (#943) - the tool breaker gets **one sentence**, and three unrelated sentences on the page were compressed to make room for it. The reasoning lives in the PR. Every one of those is a real edit I would defend individually. Together they are a pattern: **the cap is now paid for by compressing prose Kai wrote, and by moving rationale out of docs and into PR descriptions**, which is the opposite of what the comment-density doctrine in AGENTS.md asks for. It sends explanation to `docs/` precisely so it is read. ## Why it is worth deciding rather than absorbing The next person to document a new behaviour on one of those four pages will do the same thing, and the compression is lossy in a way a diff makes hard to see. #1003's own commit had to cut an enumeration to fit a rule about not collapsing categories, which is a small irony but a real one. ## Options, not a recommendation I am the wrong seat to pick, because this is repo-wide policy rather than a defect. 1. **Raise the band.** `pyproject.toml` already carries `band = "large"` under `[tool.agentic-os.documentation-layout]`. The caps live in `agentic-os`, so a new band is an upstream change, not a local one. 2. **Raise only the docs count**, so pages can split. That contradicts the count cap's stated reasoning, which is worth taking seriously rather than routing around. 3. **Merge pages.** There are 40, several of which are narrow. That frees count and chars together and is the option the hook's own message points at. 4. **Accept it** and treat PR descriptions as the durable home for rationale. Defensible, but it should be a decision rather than a drift, because it changes where a reader looks. ## Not claimed I have not established that any of tonight's compressions lost a fact. I checked each one as I made it. I am reporting that **the mechanism now requires that judgement on every docs change to four pages**, which is a different and more fragile situation than the cap was designed for.

coilysiren commented

2026-08-19 01:39:27 +00:00

Owner

no raising

coilyco-ops commented

2026-08-19 02:48:41 +00:00

Author

Member

Measured properly, and it is worse than this issue said. Fix proposed upstream at coilyco-flight-deck/agentic-os#1140.

The measurement I should have taken first

This issue named four pages at their cap. That understated it. Across all 40:

40 docs of 40
312,057 characters against 40 x 8,000 = 320,000, or 97.5%
4,331 lines against 4,800
the smallest page is 6,821 characters

Every page is near the cap. So the three local options I listed here are all unavailable:

Merge pages - any two sum to roughly 15,000 against an 8,000 cap. There is nothing small to merge.
Split a page - blocked by the count, which is full.
Redistribute - there is no slack to move.

This is not a distribution problem, which is what I assumed when I filed it. The repo is at its total documentation budget, uniformly.

The fix is a band, and the design already asked for it

agentic-os/docs/documentation-bands.md describes the escalation:

A repo outgrowing small should hit a cap and argue for large, not find out it was never on a band.

There was no next step past large. #1140 adds xlarge at exactly 1.5x large on both size caps with the count unchanged, preserving the chars-per-line ratio the pair is built on, and leaving folder readability alone because that is what the count answers.

It is additive: every repo declares its own band, so no other repo changes.

Correcting my own framing here

I listed "raise the band" first and "merge pages" third, and said the hook's own message points at merging. It does, and merging is not available here, which I would have known before filing if I had measured all forty pages instead of the four I happened to touch.

I also wrote that four pages were the problem. It is all of them.

The alternative that is Kai's, not mine

Delete documentation from this repo instead. Forty dense pages is a lot, and some may have outlived their subject. I read a good deal of it working the queue tonight and did not find the redundancy that would make deletion obvious, but "this repo should be smaller" is a legitimate answer and it would close this without any upstream change.

If #1140 lands, this closes with a one-line band = "xlarge" in pyproject.toml. I have not opened that, since it should not merge first.

**Measured properly, and it is worse than this issue said. Fix proposed upstream at `coilyco-flight-deck/agentic-os#1140`.** ## The measurement I should have taken first This issue named four pages at their cap. That understated it. Across all 40: * **40 docs of 40** * **312,057 characters against 40 x 8,000 = 320,000**, or **97.5%** * 4,331 lines against 4,800 * the **smallest** page is 6,821 characters **Every page is near the cap.** So the three local options I listed here are all unavailable: * **Merge pages** - any two sum to roughly 15,000 against an 8,000 cap. There is nothing small to merge. * **Split a page** - blocked by the count, which is full. * **Redistribute** - there is no slack to move. This is not a distribution problem, which is what I assumed when I filed it. The repo is at its total documentation budget, uniformly. ## The fix is a band, and the design already asked for it `agentic-os/docs/documentation-bands.md` describes the escalation: > A repo outgrowing `small` should hit a cap and argue for `large`, not find out it was never on a band. There was no next step past `large`. #1140 adds `xlarge` at **exactly 1.5x `large`** on both size caps with the **count unchanged**, preserving the chars-per-line ratio the pair is built on, and leaving folder readability alone because that is what the count answers. It is additive: every repo declares its own band, so no other repo changes. ## Correcting my own framing here I listed "raise the band" first and "merge pages" third, and said the hook's own message points at merging. **It does, and merging is not available here**, which I would have known before filing if I had measured all forty pages instead of the four I happened to touch. I also wrote that four pages were the problem. It is all of them. ## The alternative that is Kai's, not mine **Delete documentation from this repo instead.** Forty dense pages is a lot, and some may have outlived their subject. I read a good deal of it working the queue tonight and did not find the redundancy that would make deletion obvious, but "this repo should be smaller" is a legitimate answer and it would close this without any upstream change. If #1140 lands, this closes with a one-line `band = "xlarge"` in `pyproject.toml`. I have not opened that, since it should not merge first.

coilyco-ops referenced this issue

2026-08-19 03:38:23 +00:00

docs: delete two subjects and strip the archaeology from four more #1039

coilyco-ops added the

labels

2026-08-19 03:38:49 +00:00

coilyco-ops referenced this issue from a pull request that will close it,

2026-08-19 04:21:41 +00:00

docs: second cut - delete subjects and ledgers from nine pages #1047

coilyco-ops commented

2026-08-19 04:31:26 +00:00

Author

Member

Second cut is up as #1047, on top of the merged #1039.

Measured across docs/*.md:

start of the job - 312,057 chars over 40 docs, 97.5 percent of the 320,000 budget
after #1039 - 288,616 over 38, plus a page added since, 92.7 percent
after #1047 - 282,517 over 39, 90.6 percent

That is 29,483 chars of headroom, roughly 3.7 pages, where the job started with 7,943.

What #1047 does, page by page: turn-stages and content-gate lose their opening defect narratives; issues loses the whole "Reviewing a claim" section, which is general agent doctrine rather than anything this service does; eval loses a point-in-time coverage measurement this issue's sibling #846 already tracks and a second telling of the mechanical-scorer deletion the linked post carries; admission loses the decimated-sample section entirely, which was rate-pack semantics on the wrong page, with the one fact rate.md did not already hold moved across in a sentence; prompt loses the raise ledger, which was the commit log rendered into a doc somebody had to hand-edit every time a number moved.

Two things worth recording for whoever picks this up next.

Deleting a whole page barely moves the ratio. The budget is count times the per-doc cap, so removing a page at the cap subtracts about 8,000 from both sides. Shrinking pages is the only lever on saturation. Deleting pages is still worth doing for a reader, just not for this number.

The archaeology strip is spent. It reached about 23 percent on the pages that had a defect narrative to remove, and the remaining docs no longer have one - a grep for used to, before this, previously, and no longer across the seventeen pages not yet touched returns twenty hits, nearly all of them ordinary prose. What is left is dense reference where every rule carries its justification, and cutting further means cutting the why, which is the part the house style deliberately keeps. So 90 percent is roughly where this method stops without a decision to change what these pages are for.

Second cut is up as #1047, on top of the merged #1039. Measured across `docs/*.md`: * start of the job - 312,057 chars over 40 docs, 97.5 percent of the 320,000 budget * after #1039 - 288,616 over 38, plus a page added since, 92.7 percent * after #1047 - 282,517 over 39, **90.6 percent** That is 29,483 chars of headroom, roughly 3.7 pages, where the job started with 7,943. What #1047 does, page by page: `turn-stages` and `content-gate` lose their opening defect narratives; `issues` loses the whole "Reviewing a claim" section, which is general agent doctrine rather than anything this service does; `eval` loses a point-in-time coverage measurement this issue's sibling #846 already tracks and a second telling of the mechanical-scorer deletion the linked post carries; `admission` loses the decimated-sample section entirely, which was rate-pack semantics on the wrong page, with the one fact `rate.md` did not already hold moved across in a sentence; `prompt` loses the raise ledger, which was the commit log rendered into a doc somebody had to hand-edit every time a number moved. Two things worth recording for whoever picks this up next. **Deleting a whole page barely moves the ratio.** The budget is count times the per-doc cap, so removing a page at the cap subtracts about 8,000 from both sides. Shrinking pages is the only lever on saturation. Deleting pages is still worth doing for a reader, just not for this number. **The archaeology strip is spent.** It reached about 23 percent on the pages that had a defect narrative to remove, and the remaining docs no longer have one - a grep for `used to`, `before this`, `previously`, and `no longer` across the seventeen pages not yet touched returns twenty hits, nearly all of them ordinary prose. What is left is dense reference where every rule carries its justification, and cutting further means cutting the *why*, which is the part the house style deliberately keeps. So 90 percent is roughly where this method stops without a decision to change what these pages are for.

coilysiren closed this issue

2026-08-19 04:32:27 +00:00

No milestone

No project

No assignees

2 participants

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

coilyco-gaming/sirens-echo#1009

No description provided.

Rows
Columns

The docs band is saturated: four pages at their cap, and no room for a 41st page either #1009

Measured, on main

What that did to four PRs tonight

Why it is worth deciding rather than absorbing

Options, not a recommendation

Not claimed

The measurement I should have taken first

The fix is a band, and the design already asked for it

Correcting my own framing here

The alternative that is Kai's, not mine

Measured, on `main`