documentation-layout: near-cap index files tax every subsequent feature - add a headroom warning tier #210

New issue

Closed

opened 2026-06-12 14:27:26 +00:00 by coilysiren · 1 comment

coilysiren commented

2026-06-12 14:27:26 +00:00

Owner

Options, not mutually exclusive:

A headroom warning tier - the validator warns (not fails) when a capped file crosses ~90 percent, so the squeeze is visible before it blocks an unrelated commit.
Encourage the per-repo cap override (the aosk agents_md_max_chars pattern) for repos whose FEATURES legitimately outgrows 4000 chars as the service count grows - a deploy monorepo accretes sections by design.
House style for FEATURES at scale: one line per service with detail pushed to service-dir docs (which services/** excludes already exempt from caps).

The caps are doing their job (forcing detail out of the index files), but at the edge they tax the wrong moment. Origin: the ser8-observability move, coilyco-bridge/deploy.

Observed 2026-06-12 during the ser8 o11y build: four separate trim rounds across two repos because AGENTS.md and docs/FEATURES.md sat at 99 percent of the 4000-char cap before any new feature arrived. coilyco-bridge/deploy AGENTS.md now has 8 chars of headroom and FEATURES 19. The next feature anyone lands there hits the wall again, and the failure mode is an agent or Kai burning a cycle on prose compression instead of the actual change. Options, not mutually exclusive: 1. A headroom warning tier - the validator warns (not fails) when a capped file crosses ~90 percent, so the squeeze is visible before it blocks an unrelated commit. 2. Encourage the per-repo cap override (the aosk agents_md_max_chars pattern) for repos whose FEATURES legitimately outgrows 4000 chars as the service count grows - a deploy monorepo accretes sections by design. 3. House style for FEATURES at scale: one line per service with detail pushed to service-dir docs (which services/** excludes already exempt from caps). The caps are doing their job (forcing detail out of the index files), but at the edge they tax the wrong moment. Origin: the ser8-observability move, coilyco-bridge/deploy.

coilysiren added the

label

2026-06-17 07:04:41 +00:00

coilysiren commented

2026-06-17 08:23:03 +00:00

Author

Owner

Backlog burndown 2026-06-17: closing low-priority (P3/P4) to bring the open count to a manageable level. Nothing lost — reopen if this resurfaces. Batch tag: burndown-2026-06.

Backlog burndown 2026-06-17: closing low-priority (P3/P4) to bring the open count to a manageable level. Nothing lost — reopen if this resurfaces. Batch tag: `burndown-2026-06`.

coilysiren

2026-06-17 08:23:03 +00:00