The documentation budget is exhausted: docs/ is at the 40-doc cap and bundle-protocol.md is at the 120-line cap #371

New issue

Open

opened 2026-08-27 10:16:03 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-27 10:16:03 +00:00

Member

What is wrong

This repository has no documentation headroom left in either dimension the
documentation-layout validator caps.

docs/*.md holds exactly 40 files, and the large band's cap is 40. Adding
any new page fails the hook.
docs/bundle-protocol.md was at exactly 120 lines, and the large band's
per-file cap is 120. Adding any line to it failed the hook.

Both were discovered while landing #331, which required a new producer-contract
section in that exact file. Neither escape route existed: the file could not
grow and the content could not move to a new page. The section was paid for by
compressing the protocol half of bundle-protocol.md in place, dropping no
review decision, and that trick is not available a second time.

Why it matters now rather than later

#333 ports the semantic layer to Python and #337 moves it to housecast. Both are
documentation-heavy by their own acceptance criteria: #333 owes a record of
every cheat discharged, and #337 owes a producer-facing story for a package
other people install. Neither has anywhere to put it.

The validator's own message names the fix: "Merge related pages; splitting one
doc into two to clear the size cap trades one violation for another."

Candidates, none of them decided

Named as observations rather than a plan, because consolidating another seat's
documentation was outside #331's scope and is outside this issue's too until
someone picks.

docs/FEATURES.md, docs/features-landed.md, and docs/features-planned.md
are three overlapping inventories. FEATURES.md is the trifecta member and
has to stay at that path.
docs/architecture-v2.md and docs/architecture-v2-flow.md are a page and
its diagram.
docs/trajectory-contract-v1.md, -envelope.md, and -taxonomy.md are one
contract in three files.

Merging any one of those groups frees a slot or two. Raising the band is not an
option: large is already the top band.

Acceptance criteria

docs/*.md is below 40 files with room for at least two new pages.
No page is within five lines of its per-file cap.
No content is lost in a merge, and every cross-link still resolves under
dead-cross-links.
just test passes, which includes pre-commit run --all-files.

Ownership

Filed from the Agentic Platform Engineer seat while landing #331. This is
repository plumbing rather than a wording decision, so it stays in this seat's
lane, but it is a deliberate deferral from #331 rather than part of it.

## What is wrong This repository has no documentation headroom left in either dimension the `documentation-layout` validator caps. * `docs/*.md` holds exactly 40 files, and the large band's cap is 40. Adding any new page fails the hook. * `docs/bundle-protocol.md` was at exactly 120 lines, and the large band's per-file cap is 120. Adding any line to it failed the hook. Both were discovered while landing #331, which required a new producer-contract section in that exact file. Neither escape route existed: the file could not grow and the content could not move to a new page. The section was paid for by compressing the protocol half of `bundle-protocol.md` in place, dropping no review decision, and that trick is not available a second time. ## Why it matters now rather than later #333 ports the semantic layer to Python and #337 moves it to housecast. Both are documentation-heavy by their own acceptance criteria: #333 owes a record of every cheat discharged, and #337 owes a producer-facing story for a package other people install. Neither has anywhere to put it. The validator's own message names the fix: "Merge related pages; splitting one doc into two to clear the size cap trades one violation for another." ## Candidates, none of them decided Named as observations rather than a plan, because consolidating another seat's documentation was outside #331's scope and is outside this issue's too until someone picks. * `docs/FEATURES.md`, `docs/features-landed.md`, and `docs/features-planned.md` are three overlapping inventories. `FEATURES.md` is the trifecta member and has to stay at that path. * `docs/architecture-v2.md` and `docs/architecture-v2-flow.md` are a page and its diagram. * `docs/trajectory-contract-v1.md`, `-envelope.md`, and `-taxonomy.md` are one contract in three files. Merging any one of those groups frees a slot or two. Raising the band is not an option: `large` is already the top band. ## Acceptance criteria - [ ] `docs/*.md` is below 40 files with room for at least two new pages. - [ ] No page is within five lines of its per-file cap. - [ ] No content is lost in a merge, and every cross-link still resolves under `dead-cross-links`. - [ ] `just test` passes, which includes `pre-commit run --all-files`. ## Ownership Filed from the Agentic Platform Engineer seat while landing #331. This is repository plumbing rather than a wording decision, so it stays in this seat's lane, but it is a deliberate deferral from #331 rather than part of it.

coilyco-ops added the

labels

2026-08-27 10:16:03 +00:00

coilyco-ops referenced this issue

2026-08-27 10:16:24 +00:00

Invert the stack: data, compositor, bundle, then Go. Drop KDL, move composition out of the engine, mount the roster #329