coilyco-flight-deck/agent-proxy

Watch

docs: 68 docs to 20, 43 oversized docs #133

New issue

Open

opened 2026-08-17 00:48:45 +00:00 by coilyco-ops · 3 comments

coilyco-ops commented

2026-08-17 00:48:45 +00:00

Member

Part of coilysiren/inbox#374. The cap landed in coilyco-flight-deck/agentic-os#1108.

What this repo needs

Merge 68 docs down to 20. docs/ currently holds 68 files against the small-band cap of 20, totalling 3237 lines. The ceiling at the cap is 800 lines, so the arithmetic decides whether this is merging alone or merging plus trimming: it does not fit at any packing, so content has to come out.
43 docs over the per-file cap of 40 lines / 3,000 chars.

What agentic-os learned migrating first

Merging costs lines rather than saving them, measured at 3.7 per fold: each adds a heading and its spacing. Budget a trimming pass rather than expecting consolidation to shrink the total.

Rephrasing prose to be tighter does not reduce line count, because reflowed text occupies the same rows. What works is deleting whole restatements, and folding a small trailing section into the paragraph above it, which drops a heading and a blank line without touching a word.

A generated doc cannot be merged, since folding it into another page turns its drift test red.

Acceptance

pre-commit run --all-files clean, with documentation-layout passing.
No live capability loses its reference material.

Part of coilysiren/inbox#374. The cap landed in coilyco-flight-deck/agentic-os#1108. ## What this repo needs 1. **Merge 68 docs down to 20.** `docs/` currently holds 68 files against the small-band cap of 20, totalling 3237 lines. The ceiling at the cap is 800 lines, so the arithmetic decides whether this is merging alone or merging plus trimming: it does not fit at any packing, so content has to come out. 2. **43 docs over the per-file cap** of 40 lines / 3,000 chars. ## What agentic-os learned migrating first **Merging costs lines rather than saving them**, measured at 3.7 per fold: each adds a heading and its spacing. Budget a trimming pass rather than expecting consolidation to shrink the total. **Rephrasing prose to be tighter does not reduce line count**, because reflowed text occupies the same rows. What works is deleting whole restatements, and folding a small trailing section into the paragraph above it, which drops a heading and a blank line without touching a word. **A generated doc cannot be merged**, since folding it into another page turns its drift test red. ## Acceptance * `pre-commit run --all-files` clean, with `documentation-layout` passing. * No live capability loses its reference material.

coilyco-ops commented

2026-08-17 01:11:11 +00:00

Author

Member

Two corrections and a decision, all after this was filed.

Nothing is urgent. This repo pins aos-precommit-v0.18.0, so the new caps do not apply here until that pin advances. aos-precommit-v0.24.0 carries them. The bump is the trigger, so the sequencing is migrate first then bump, or both in one change. Bumping first turns this repo's own commits red.

Skills are out of scope. documentation-layout was applying the band cap to SKILL.md and COMPOSED.md while check-skills allows 500 lines for the same file. Kai's call is to ignore skills, and the exemption is in coilyco-flight-deck/agentic-os#1110. Any skill-file count above is struck from the work.

Epic: coilysiren/inbox#374.

Two corrections and a decision, all after this was filed. **Nothing is urgent.** This repo pins `aos-precommit-v0.18.0`, so the new caps do not apply here until that pin advances. `aos-precommit-v0.24.0` carries them. The bump is the trigger, so the sequencing is migrate first then bump, or both in one change. Bumping first turns this repo's own commits red. **Skills are out of scope.** `documentation-layout` was applying the band cap to `SKILL.md` and `COMPOSED.md` while `check-skills` allows 500 lines for the same file. Kai's call is to ignore skills, and the exemption is in coilyco-flight-deck/agentic-os#1110. Any skill-file count above is struck from the work. Epic: coilysiren/inbox#374.

coilyco-ops commented

2026-08-17 03:25:16 +00:00

Author

Member

Agent Proxy's band landed on main, and it takes 61 of the 62 violations with it. One remains, and it cannot land before the pin advances.

The band

small came from the chore(docs): declare the small documentation band sweep, not a decision, and Kai's call on coilysiren/inbox#374 was to re-pick per repo. Large is right: this is the estate's model transport layer, its docs total 158,652 chars, and 20 files at the small cap hold at most 60,000. Every doc already passes the large per-file cap, the longest being 79 lines against 120, so nothing was edited.

The one left: 68 docs against the 40-doc cap

This repo is the shape the count cap was written against, and it is worth naming precisely, because the fix is mechanical once someone starts. It uses hub-and-spoke: a tiny index doc plus its detail pages.

architecture-v2.md (611 chars) over -flow, -migration, -ownership, -ownership-cold
trajectory-contract-v1.md (610) over -envelope, -governance, -identity, -model-facts, -taxonomy
FEATURES.md (780) over features-landed, -gateway, -trajectory, features-planned
route-registry.md (645), litellm-parity.md (628), trajectory-retention.md (684), reliability_baseline.md (653), and ROADMAP.md (871) each over two spokes

Folding each spoke set back into its hub is 28 fewer files and reads better, since a 610-char page that exists only to link four others is pure navigation overhead.

It cannot be done at the current pin. aos-precommit-v0.18.0 caps a doc at 4,000 chars. The docs total 158,652 against a ceiling of 40 x 4,000 = 160,000, a margin of 0.8%, so every merged file would have to land within one percent of the cap. That is not a real plan.

At the large band's 8,000-char cap the ceiling is 320,000 and the same merges fit with room to spare. So this repo needs the merges and the pin bump in one change, or the bump first. The epic's suggested "migrate first, then bump" ordering does not work here. I raised it on coilysiren/inbox#374, since galaxy-gen and lore hit the same wall and lore's case is arithmetically impossible rather than merely tight.

Agent Proxy's band landed on `main`, and it takes 61 of the 62 violations with it. One remains, and it cannot land before the pin advances. ## The band `small` came from the `chore(docs): declare the small documentation band` sweep, not a decision, and Kai's call on coilysiren/inbox#374 was to re-pick per repo. Large is right: this is the estate's model transport layer, its docs total **158,652 chars**, and 20 files at the small cap hold at most 60,000. Every doc already passes the large per-file cap, the longest being 79 lines against 120, so nothing was edited. ## The one left: 68 docs against the 40-doc cap This repo is the shape the count cap was written against, and it is worth naming precisely, because the fix is mechanical once someone starts. It uses hub-and-spoke: a tiny index doc plus its detail pages. * `architecture-v2.md` (611 chars) over `-flow`, `-migration`, `-ownership`, `-ownership-cold` * `trajectory-contract-v1.md` (610) over `-envelope`, `-governance`, `-identity`, `-model-facts`, `-taxonomy` * `FEATURES.md` (780) over `features-landed`, `-gateway`, `-trajectory`, `features-planned` * `route-registry.md` (645), `litellm-parity.md` (628), `trajectory-retention.md` (684), `reliability_baseline.md` (653), and `ROADMAP.md` (871) each over two spokes Folding each spoke set back into its hub is 28 fewer files and reads better, since a 610-char page that exists only to link four others is pure navigation overhead. **It cannot be done at the current pin.** `aos-precommit-v0.18.0` caps a doc at 4,000 chars. The docs total 158,652 against a ceiling of 40 x 4,000 = 160,000, a margin of 0.8%, so every merged file would have to land within one percent of the cap. That is not a real plan. At the large band's 8,000-char cap the ceiling is 320,000 and the same merges fit with room to spare. So this repo needs the merges and the pin bump in one change, or the bump first. The epic's suggested "migrate first, then bump" ordering does not work here. I raised it on coilysiren/inbox#374, since galaxy-gen and lore hit the same wall and lore's case is arithmetically impossible rather than merely tight.

coilyco-ops referenced this issue

2026-08-19 03:13:54 +00:00

docs band migration: merge 48 docs, trim 43 files #132

coilyco-ops commented

2026-08-19 03:13:57 +00:00

Author

Member

Duplicate of #132, filed 2026-08-16 with the same numbers for this repo: 68 docs against the small-band cap of 20, 43 files over the per-file cap. This issue carries the more useful analysis - the 3.7-lines-per-fold cost, and the arithmetic showing it does not fit at any packing - so it is the better one to keep. Flagging the pair rather than closing either, since which survives is a call.

No milestone

No project

No assignees

1 participant

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-flight-deck/agent-proxy#133

No description provided.

Rows
Columns