coilyco-flight-deck/scoop-bucket

Watch

docs: declare a band, 1 oversized docs #13

New issue

Closed

opened 2026-08-17 00:48:52 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

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

Member

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

What this repo needs

Declare a band. This repo declares none, so documentation-layout fails on that alone before any size question. A missing declaration is a hard failure rather than a silent default, because an undeclared repo and a chosen-small repo were previously the same file.

[tool.agentic-os.documentation-layout]
band = "small"

Declaring it is the decision about which band this repo is in, so pick deliberately rather than copying. Small is 40 lines / 3,000 chars / 20 docs. Large is 120 / 8,000 / 40.

1 doc 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. **Declare a band.** This repo declares none, so `documentation-layout` fails on that alone before any size question. A missing declaration is a hard failure rather than a silent default, because an undeclared repo and a chosen-small repo were previously the same file. ```toml [tool.agentic-os.documentation-layout] band = "small" ``` Declaring it **is** the decision about which band this repo is in, so pick deliberately rather than copying. Small is 40 lines / 3,000 chars / 20 docs. Large is 120 / 8,000 / 40. 2. **1 doc 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:34 +00:00

Author

Member

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

Nothing is urgent. This repo pins an older rev, 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.

The band is declared. Kai assigned it and it has landed, so that item above is done.

Epic: coilysiren/inbox#374.

Two corrections and a decision, all after this was filed. **Nothing is urgent.** This repo pins `an older rev`, 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. **The band is declared.** Kai assigned it and it has landed, so that item above is done. Epic: coilysiren/inbox#374.

coilyco-ops commented

2026-08-17 01:39:05 +00:00

Author

Member

Migrated and landed on main. documentation-layout from aos-precommit-v0.24.0 reports clean here.

The pin in this repo still points at its older rev, so this landed ahead of the bump rather than in response to a red build. Bumping is now safe whenever it comes up.

Epic: coilysiren/inbox#374.

Migrated and landed on `main`. `documentation-layout` from `aos-precommit-v0.24.0` reports clean here. The pin in this repo still points at its older rev, so this landed ahead of the bump rather than in response to a red build. Bumping is now safe whenever it comes up. Epic: coilysiren/inbox#374.

coilyco-ops closed this issue

2026-08-17 01:39:06 +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/scoop-bucket#13

No description provided.

Rows
Columns