Split the nine oversized docs under the layout caps #88

New issue

Closed

opened 2026-08-11 00:57:54 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-11 00:57:54 +00:00

Member

Exempted at pre-commit adoption in #87 so the suite could land green. The exemption is a listed excludes in pyproject.toml, not a disabled hook, so every new or renamed doc is governed from day one and only this backlog is exempt. Each file drops off the list as it is split.

Over cap

Caps are 80 lines and 4000 chars.

docs/proxy.md - 333 lines, 18855 chars
docs/trajectory-contract-v1.md - 212 lines, 11698 chars
docs/architecture-v2.md - 180 lines, 10839 chars
docs/reliability_baseline.md - 110 lines, 4858 chars
docs/litellm-parity.md - 104 lines, 4604 chars
docs/trajectory-retention.md - 91 lines, 4546 chars
docs/route-registry.md - 87 lines
docs/FEATURES.md - 85 lines, 8425 chars
docs/ROADMAP.md - 5810 chars

Why this is not a mechanical split

Three of these are cited by path from outside this repository.

docs/trajectory-contract-v1.md is a versioned producer and consumer contract. Its filename carries the version, and other services build against it. Splitting it changes the citation surface for every consumer, so the split needs to preserve or redirect existing anchors deliberately.
docs/proxy.md is the request-path walkthrough and the longest file here. coilyco-bridge/deploy and this repository's own PRs cite its capture-contract section.
docs/architecture-v2.md is load-bearing for the v2 migration inventory and is named in AGENTS.md as read-first.

A fast split would leave dangling references in other repositories, which the dead-cross-links hook cannot see from here.

Suggested approach

Split by the boundaries the documents already have rather than by line count. proxy.md has clean H2 sections (request path, trace correlation, capture contract, SigNoz viewing) that are separate documents in everything but filename. Leave a short parent page that links the parts, so an existing inbound link to the parent still lands somewhere useful.

Take FEATURES.md and ROADMAP.md first. They are the least cited and the split is genuinely mechanical, which validates the pattern before touching the contract.

Exempted at pre-commit adoption in #87 so the suite could land green. The exemption is a listed `excludes` in `pyproject.toml`, not a disabled hook, so **every new or renamed doc is governed from day one** and only this backlog is exempt. Each file drops off the list as it is split. ## Over cap Caps are 80 lines and 4000 chars. * `docs/proxy.md` - 333 lines, 18855 chars * `docs/trajectory-contract-v1.md` - 212 lines, 11698 chars * `docs/architecture-v2.md` - 180 lines, 10839 chars * `docs/reliability_baseline.md` - 110 lines, 4858 chars * `docs/litellm-parity.md` - 104 lines, 4604 chars * `docs/trajectory-retention.md` - 91 lines, 4546 chars * `docs/route-registry.md` - 87 lines * `docs/FEATURES.md` - 85 lines, 8425 chars * `docs/ROADMAP.md` - 5810 chars ## Why this is not a mechanical split Three of these are cited by path from outside this repository. * `docs/trajectory-contract-v1.md` is a **versioned producer and consumer contract**. Its filename carries the version, and other services build against it. Splitting it changes the citation surface for every consumer, so the split needs to preserve or redirect existing anchors deliberately. * `docs/proxy.md` is the request-path walkthrough and the longest file here. `coilyco-bridge/deploy` and this repository's own PRs cite its capture-contract section. * `docs/architecture-v2.md` is load-bearing for the v2 migration inventory and is named in `AGENTS.md` as read-first. A fast split would leave dangling references in other repositories, which the `dead-cross-links` hook cannot see from here. ## Suggested approach Split by the boundaries the documents already have rather than by line count. `proxy.md` has clean H2 sections (request path, trace correlation, capture contract, SigNoz viewing) that are separate documents in everything but filename. Leave a short parent page that links the parts, so an existing inbound link to the parent still lands somewhere useful. Take `FEATURES.md` and `ROADMAP.md` first. They are the least cited and the split is genuinely mechanical, which validates the pattern before touching the contract.

coilyco-ops referenced this issue from a commit

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

chore: adopt the catalog pre-commit suite at aos-precommit-v0.18.0

coilyco-ops referenced this issue

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

Adopt the catalog pre-commit suite at aos-precommit-v0.18.0 #90

coilyco-ops referenced this issue from a commit

2026-08-12 10:54:15 +00:00

Expose the all-files pre-commit suite as a Ward verb

coilyco-ops referenced this issue

2026-08-12 10:54:36 +00:00

Expose the all-files pre-commit suite as a Ward verb #93