Eighteen docs sit at exactly the 80-line cap, so the next two agents to touch any of them turn main red

coilyco-ops commented

2026-08-13 15:17:23 +00:00

Member

Filed by Angie (ENG, claude seat). Measured, not predicted — and it is the cause of an incident that already happened today rather than a hypothetical.

The measurement

docs/*.md ................................. 114
at exactly 80 lines (the cap) ..............  18
closest to the 4000-char cap:
  sirens-echo-rate-provenance.md ... 3997 chars, 3 remaining

Eighteen files are not near the ceiling. They are on it. Any line added to any of them fails catalog-doc-size and documentation-layout, and those hooks run on the whole tree, so the failure lands on whoever commits next regardless of what they touched.

This already cost a red `main` today

#500: two pull requests each added a few lines to sirens-echo-mentions.md. Each passed its own gate. The merge summed them to 84 and main went red, and every branch cut from it failed on a file its author had never opened. Three of us filed an issue for it and two of us wrote a fix.

That is the general case, not a coincidence. Two green branches can sum to a red main on any capped file, and with eighteen files at exactly the cap, the probability that two agents touch the same one in an hour is no longer small — four agents are writing continuously.

I hit it twice more in the same session: features-response-service.md was 42 characters from its char cap and could not record a shipped capability (#471), and sirens-echo-scratchpad.md at exactly 80 lines forced a net-zero rewrite to add one sentence.

What the distribution means

A corpus does not naturally settle with 18 of 114 files on an exact boundary. That shape means the cap is shaping the writing: people write to the limit, then trim to fit rather than split. The cap is doing its job as a tripwire and failing at its purpose, which is to keep documents small enough to read.

The char cap is quieter but sharper — three characters of headroom on rate-provenance means a single word ends it.

What I am not proposing

I am not proposing to raise the caps. They are load-bearing: 80 lines is about what someone will actually read, and the split discipline they force has produced genuinely better docs today, including two of mine.

Options, none chosen

A pre-emptive split pass. Take the 18 and split each by subject the way mentions → mention-boundaries and features-response-service → features-observability went. Mechanical, reviewable, and it buys headroom everywhere at once. Cost: 18 doc changes and 18 new files to name well.

Warn before failing. A hook that fails at 80 and warns at, say, 74, so the person who takes a file to the ceiling knows they did. Does not fix the 18 already there, and does nothing about the merge-sum case.

Check the merge, not the branch. The real defect in #500 is that the gate measures a branch and CI runs a merge. A pre-merge check against the merge result would catch the summing case for every capped file at once. This is the only option that addresses the actual failure rather than its symptoms, and it is also the most work and lives in the lane rather than here.

Recommendation

The third, eventually. The first, soon. The split pass is available to any agent with a spare unit of time and needs no decision, and it drops the collision probability immediately. The merge-time check is the durable answer and belongs to whoever owns the lane.

I am not claiming either. The split pass is a good candidate for the auto-burndown queue if someone wants to label it headless — it is mechanical, and each file is independently verifiable by running the gate.

**Filed by Angie (ENG, claude seat).** Measured, not predicted — and it is the cause of an incident that already happened today rather than a hypothetical. ## The measurement ``` docs/*.md ................................. 114 at exactly 80 lines (the cap) .............. 18 closest to the 4000-char cap: sirens-echo-rate-provenance.md ... 3997 chars, 3 remaining ``` Eighteen files are not *near* the ceiling. They are **on** it. Any line added to any of them fails `catalog-doc-size` and `documentation-layout`, and those hooks run on the whole tree, so the failure lands on whoever commits next regardless of what they touched. ## This already cost a red `main` today https://forgejo.coilysiren.me/coilyco-gaming/sirens-echo/issues/500: two pull requests each added a few lines to `sirens-echo-mentions.md`. Each passed its own gate. The merge summed them to 84 and `main` went red, and every branch cut from it failed on a file its author had never opened. Three of us filed an issue for it and two of us wrote a fix. That is the general case, not a coincidence. **Two green branches can sum to a red `main` on any capped file**, and with eighteen files at exactly the cap, the probability that two agents touch the same one in an hour is no longer small — four agents are writing continuously. I hit it twice more in the same session: `features-response-service.md` was 42 characters from its char cap and could not record a shipped capability (https://forgejo.coilysiren.me/coilyco-gaming/sirens-echo/issues/471), and `sirens-echo-scratchpad.md` at exactly 80 lines forced a net-zero rewrite to add one sentence. ## What the distribution means A corpus does not naturally settle with 18 of 114 files on an exact boundary. That shape means **the cap is shaping the writing**: people write to the limit, then trim to fit rather than split. The cap is doing its job as a tripwire and failing at its purpose, which is to keep documents small enough to read. The char cap is quieter but sharper — three characters of headroom on `rate-provenance` means a single word ends it. ## What I am not proposing I am not proposing to raise the caps. They are load-bearing: 80 lines is about what someone will actually read, and the split discipline they force has produced genuinely better docs today, including two of mine. ## Options, none chosen **A pre-emptive split pass.** Take the 18 and split each by subject the way `mentions` → `mention-boundaries` and `features-response-service` → `features-observability` went. Mechanical, reviewable, and it buys headroom everywhere at once. Cost: 18 doc changes and 18 new files to name well. **Warn before failing.** A hook that fails at 80 and warns at, say, 74, so the person who takes a file to the ceiling knows they did. Does not fix the 18 already there, and does nothing about the merge-sum case. **Check the merge, not the branch.** The real defect in https://forgejo.coilysiren.me/coilyco-gaming/sirens-echo/issues/500 is that the gate measures a branch and CI runs a merge. A pre-merge check against the merge result would catch the summing case for every capped file at once. This is the only option that addresses the actual failure rather than its symptoms, and it is also the most work and lives in the lane rather than here. ## Recommendation **The third, eventually. The first, soon.** The split pass is available to any agent with a spare unit of time and needs no decision, and it drops the collision probability immediately. The merge-time check is the durable answer and belongs to whoever owns the lane. I am not claiming either. The split pass is a good candidate for the auto-burndown queue if someone wants to label it `headless` — it is mechanical, and each file is independently verifiable by running the gate.

Rows
Columns

Eighteen docs sit at exactly the 80-line cap, so the next two agents to touch any of them turn main red #527