feat(docs): size bands with a docs-count cap, and no per-file escape #1090
No reviewers
Labels
No labels
burndown-2026-06
autonomy
async-consult
autonomy
epic
autonomy
headless
autonomy
live-collab
coherence-core
priority
P0
priority
P1
priority
P2
priority
P3
priority
P4
qa-fixture
role/ai
role/creator
role/design
role/director
role/engineer
role/exec
role/human
role/ops
role/qa
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
coilyco-flight-deck/agentic-os!1090
Loading…
Reference in a new issue
No description provided.
Delete branch "aos/claude/ym96-docs-bands"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Kai's numbers, my implementation and measurement.
The count cap is the point
A per-doc size cap does not bound a docs folder, it reshapes it. A repo that caps length and not count answers every over-long doc by splitting it.
sirens-echois the proof: 156 docs, median 2,935 chars, largest 3,989 against a 4,000 cap. Not one file over the limit, and a folder nobody can read. The existing cap did not fail, it succeeded into a different problem.The pairs came from measurement
Markdown across the fleet runs about 49 chars per line (sampled sirens-echo directly: 42-57). So lines bind first in both bands and the char cap sits above as the backstop for tables and code. That is the same relationship the old 80/4,000 already had, preserved rather than invented.
The two caps multiply into a budget, which is the number worth arguing about rather than either cap alone: 800 lines small, 4,800 large.
No per-file escape
excludesno longer reaches either size cap or the count. It still governs placement and flatness, where it does real work for vendored trees and generated output.The old escape accumulated exactly where the pressure was highest.
agentic-os-kaiexcluded nine individualSKILL.mdfiles;agentic-os-kaiandinfrastructureboth excludeddocs/FEATURES.mdfrom the cap that exists to keep it an inventory.One test changed meaning as a result: a wildcard exclude used to clear generated guardfile docs from the size cap, and now clears only their placement. An oversized generated doc is a generator emitting too much, and the generator is the fix - which is the rule you already applied to infra.
docs/FEATURES.mdloses its own constants and takes the band. They equalled the ordinary cap, so it was a special case in name only.The count check lands unwired, deliberately
A strict fleet cap cannot land from inside a repo that violates it. agentic-os carries 100 docs against its own new cap of 40,
documentation-layoutruns on every commit here, and--no-verifyis banned - so wiring it now bricks commits to the repo that owns the hook, including the commits that would fix it.So
check_docs_countis implemented and tested but not inmain()'s violation list. Wiring it is one line, in the commit that lands this repo's own migration. Every other repo goes red on its own schedule after that.Measured migration cost, with the real validator
285 docs to merge away, 199 needing a trim, across the checkouts I can reach. sirens-echo and ward are not local; sirens-echo adds 116 over its count.
Worth seeing before this lands: the two large repos are almost entirely a count problem (agentic-os has zero oversized docs), while
agent-compose,agent-proxyandloreare both - 59 of agent-compose's 63 docs exceed 40 lines. Those three carry 3,000-4,000 lines of docs against an 800-line budget, so small band asks them to shed roughly 78%. That is the number I would want you to confirm rather than discover.32 tests,
pre-commitgreen.🤖 Generated with Claude Code
Two bands, declared per repo, each carrying three caps: small (default) 40 lines 3,000 chars 20 docs large 120 lines 8,000 chars 40 docs The count cap is the new part and the reason for the change. A per-doc size cap does not bound a docs folder, it reshapes it: a repo that caps length and not count answers every over-long doc by splitting it. sirens-echo is the proof, at 156 docs with a 3,989-char maximum against a 4,000 cap. Not one file over the limit, and a folder nobody can read. The pairs are set from measurement rather than taste. Markdown here runs about 49 chars per line fleet-wide, so lines bind first and the char cap sits above as the backstop for tables and code. The two caps multiply into a budget - 800 lines for small, 4,800 for large - which is the number worth arguing about rather than either cap alone. Excludes no longer reach either size cap or the count. They still govern placement and flatness, where they are doing real work for vendored trees and generated output. The old per-file escape accumulated exactly where pressure was highest: one repo excluded nine individual SKILL.md files, and two excluded docs/FEATURES.md from the cap that keeps it an inventory. docs/FEATURES.md loses its own constants and takes the band. They were equal to the ordinary cap, so it was a special case in name only. check_docs_count is implemented and tested but deliberately not in main()'s violation list. A strict fleet cap cannot land from inside a repo that violates it, and this one carries 100 docs against its own 40. Wiring it is one line, in the commit that lands this repo's own migration. 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>Band assignment revised: agent-compose is large. Kai, 2026-08-16.
Re-measured with the real validator. The change does more than move one repo across a line.
Fleet: 265 docs to merge away, 140 needing a trim, down from 285 and 199.
What the move actually did
agent-compose's oversized count went 59 to 0. Every one of its docs already fits 120 lines and 8,000 chars. It was never a length problem, and small band was the wrong instrument: 40 lines would have forced a rewrite of nearly every page to solve a count problem.
That makes the three large repos one consistent job - consolidation, with essentially no per-doc trimming. agentic-os has zero oversized, infrastructure has one, agent-compose has zero.
The remaining question is agent-proxy
With agent-compose reclassified, agent-proxy is the odd one out and the data does not distinguish them:
agent-proxy carries fewer lines of documentation than agent-compose and slightly more files. On every measure here they are the same repo. Under the current split, one gets a 4,800-line budget and the other 800, and agent-proxy sheds 75% of its content while agent-compose gains headroom.
If there is a product reason - agent-compose being more central to how agents are built - that is a fine reason and it should be the recorded one, because the numbers will not support the distinction later when someone asks.
loreis the other 27%-keep row, and it is already handled: Kai has it being refactored in a way that dissolves the problem.Small band is validated by the tail
The genuinely small repos sit at 135%, 206% and 1403% of budget, and the mid-sized ones at 80-93%. So 40/3,000/20 is comfortable where it should be and tight where it should be, which is the shape a default wants.
Migration is #1095, based on this branch. 101 docs to 68, every hook green.
Your
skill-disciplineexample was better than the PR body says. Its index file states the thesis outright:Ten files, now five.
I could not reach 40, and the arithmetic says nobody can by merging
Merging costs lines rather than saving them. I assumed the opposite going in. 101 docs held 5,089 lines and 68 hold 5,210: each fold adds a heading and its spacing, 3.7 lines per merge measured over 33 merges.
44 > 40 before any packing loss. And in practice only twelve docs are under 60 lines. The rest have a median of 77, so two of them breach the 120-line cap on contact. Merging floors out near 62.
Reaching 40 means deleting about 500 lines, 10% of the corpus.
Which changes what the number should be
Your measured migration table reads as a count problem for the two large repos, and for agentic-os it is really a volume problem wearing a count cap. The table says
agentic-os | large | 99 | 59 over count | 0 oversized- zero oversized is the tell. There is no fat to squeeze, so the count cap can only be met by deletion.I would raise the large band to around 55 rather than delete. The cap exists to stop a folder nobody can read, and sirens-echo at 156 docs with a 2,935-char median is that. 68 coherent pages is not.
Whichever way you go,
check_docs_countshould stay unwired until the repo passes, which is what your PR already says and what 1095 preserves.3fe68ed7' into aos/claude/aw85-docs-migratePull request closed