The docs/ budget is exhausted: 40/40 pages and the native family at its line cap #1315

New issue

Closed

opened 2026-08-27 04:12:22 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

2026-08-27 04:12:22 +00:00

Owner

Found while landing #1215 (PR #1309). Recording it because the next feature touching native startup hits the same wall, and rediscovering it costs the same hour twice.

What is true today

docs/ holds 40 pages against the large band's 40-doc cap, so no new page can be added. The native-* family is simultaneously at its per-page cap:

native-session-start.md - 120 lines / 6175 chars, exactly at the 120-line cap
native-agent-workspaces.md - 120 lines / 6172 chars, exactly at the 120-line cap
native-shadow.md - 75 lines / 7881 chars, 119 chars under the 8000-char cap
native-claude-credentials.md - 104 lines
native-harness-config.md - 90 lines, the only real headroom in the family and topically unrelated

So a native-startup feature can neither take a new page nor extend the page that owns its subject.

Why this is not just "write less"

The two caps are deliberately opposed, and that is the point: check_documentation_layout says the count cap exists because a per-doc cap alone "does not bound a docs folder, it reshapes it", and its own failure text says splitting one doc to clear a size cap "trades one violation for another". Both halves are working as designed. What is missing is the release valve: at 40/40 with every topical page full, the only moves left are to merge two unrelated pages, or to compress a page nobody asked you to touch.

#1309 took the second one. The provenance section went into native-session-start.md, and buying the room meant reflowing that whole page to denser lines. The content survived byte for byte, but the diff touches prose the change had no business rewriting, which is exactly the churn the comment-density doctrine avoids in code.

What would resolve it

Not obvious, which is why this is an issue rather than a patch. Some candidates, none costed:

Merge genuinely related pages to free slots. The native-* family is five pages describing one subsystem, and one native.md with sections may be the honest shape, though it would blow the size cap immediately.
Let a declared doc family count as one entry against the count cap, so a subsystem can hold several pages without spending five of forty.
Raise the large band's count cap with the measured rationale that docs/documentation-bands.md already uses for the line and char pairs.
Decide the overflow belongs in skills rather than docs, and say so, since SKILL.md takes its cap from check-skills instead.

Not urgent

Nothing is broken and #903 and #1215 both landed documented. This is back-pressure that has reached its limit, so the next person pays it rather than notices it.

Found while landing #1215 (PR #1309). Recording it because the next feature touching native startup hits the same wall, and rediscovering it costs the same hour twice. ## What is true today `docs/` holds 40 pages against the large band's 40-doc cap, so no new page can be added. The `native-*` family is simultaneously at its per-page cap: * `native-session-start.md` - 120 lines / 6175 chars, exactly at the 120-line cap * `native-agent-workspaces.md` - 120 lines / 6172 chars, exactly at the 120-line cap * `native-shadow.md` - 75 lines / 7881 chars, 119 chars under the 8000-char cap * `native-claude-credentials.md` - 104 lines * `native-harness-config.md` - 90 lines, the only real headroom in the family and topically unrelated So a native-startup feature can neither take a new page nor extend the page that owns its subject. ## Why this is not just "write less" The two caps are deliberately opposed, and that is the point: `check_documentation_layout` says the count cap exists because a per-doc cap alone "does not bound a docs folder, it reshapes it", and its own failure text says splitting one doc to clear a size cap "trades one violation for another". Both halves are working as designed. What is missing is the release valve: at 40/40 with every topical page full, the only moves left are to merge two unrelated pages, or to compress a page nobody asked you to touch. #1309 took the second one. The provenance section went into `native-session-start.md`, and buying the room meant reflowing that whole page to denser lines. The content survived byte for byte, but the diff touches prose the change had no business rewriting, which is exactly the churn the comment-density doctrine avoids in code. ## What would resolve it Not obvious, which is why this is an issue rather than a patch. Some candidates, none costed: * Merge genuinely related pages to free slots. The `native-*` family is five pages describing one subsystem, and one `native.md` with sections may be the honest shape, though it would blow the size cap immediately. * Let a declared doc *family* count as one entry against the count cap, so a subsystem can hold several pages without spending five of forty. * Raise the large band's count cap with the measured rationale that `docs/documentation-bands.md` already uses for the line and char pairs. * Decide the overflow belongs in skills rather than docs, and say so, since `SKILL.md` takes its cap from check-skills instead. ## Not urgent Nothing is broken and #903 and #1215 both landed documented. This is back-pressure that has reached its limit, so the next person pays it rather than notices it.

coilyco-ops commented

2026-08-27 04:25:27 +00:00

Author

Owner

Duplicate. #1303 owns this and filed first, and #1312 is the same wall hit from #1105. Closing this and moving the one thing it adds, the native-* measurement, onto #1303.

My fault for filing without searching the tracker first. Three issues now describe one wall, which is the shape #1303 itself is about.

Duplicate. #1303 owns this and filed first, and #1312 is the same wall hit from #1105. Closing this and moving the one thing it adds, the `native-*` measurement, onto #1303. My fault for filing without searching the tracker first. Three issues now describe one wall, which is the shape #1303 itself is about.

coilyco-ops closed this issue

2026-08-27 04:25:45 +00:00

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/agentic-os#1315

No description provided.

Rows
Columns