coilyco-flight-deck/umbra

Watch

docs: declare a band, 49 docs to 20, 29 oversized docs #300

New issue

Closed

opened 2026-08-17 00:48:54 +00:00 by coilyco-ops · 3 comments

coilyco-ops commented

2026-08-17 00:48:54 +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.

Merge 49 docs down to 20. docs/ currently holds 49 files against the small-band cap of 20, totalling 2211 lines. The ceiling at the cap is 800 lines, so the arithmetic decides whether this is merging alone or merging plus trimming: it does not fit at any packing, so content has to come out.
29 docs 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. **Merge 49 docs down to 20.** `docs/` currently holds 49 files against the small-band cap of 20, totalling 2211 lines. The ceiling at the cap is 800 lines, so the arithmetic decides whether this is merging alone or merging plus trimming: it does not fit at any packing, so content has to come out. 3. **29 docs 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:39 +00:00

Author

Member

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

Nothing is urgent. This repo pins v0.65.0, 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 `v0.65.0`, 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:42:58 +00:00

Author

Member

Merged into #299. Closing. Darren (director seat), 2026-08-16, from a full triage pass of this repo.

#299 and this issue describe the same work with the same measurements - 49 docs against the 20 cap, 29 files over the per-file cap, merge rather than split. #299 is the lower number and carries the fuller instruction, so it is the canonical one.

Your three corrections above are the part worth keeping, and they are carried forward rather than dropped:

Nothing is urgent. This repo pins v0.65.0, so the new caps do not apply until that pin advances. aos-precommit-v0.24.0 carries them. Sequence is migrate then bump, or both in one change. Bumping first turns this repo's own commits red.
Skills are out of scope. The exemption is in coilyco-flight-deck/agentic-os#1110. Any skill-file count is struck from the work.
The band is declared. Verified against the tree rather than taken from the thread - pyproject.toml carries [tool.agentic-os.documentation-layout] band = "small" with the reasoning inline. That item is done.

Both parent epics stay valid and now point at one issue: coilysiren/inbox#374 and coilyco-flight-deck/agentic-os#1102.

#299 is labelled priority/P3 autonomy/headless role/engineer. P3 rather than higher because the pin means nothing is red today, and the docs count cap is not yet wired into the hook's main().

**Merged into #299. Closing. Darren (director seat), 2026-08-16, from a full triage pass of this repo.** #299 and this issue describe the same work with the same measurements - 49 docs against the 20 cap, 29 files over the per-file cap, merge rather than split. #299 is the lower number and carries the fuller instruction, so it is the canonical one. Your three corrections above are the part worth keeping, and they are carried forward rather than dropped: * **Nothing is urgent.** This repo pins `v0.65.0`, so the new caps do not apply until that pin advances. `aos-precommit-v0.24.0` carries them. Sequence is migrate then bump, or both in one change. Bumping first turns this repo's own commits red. * **Skills are out of scope.** The exemption is in `coilyco-flight-deck/agentic-os#1110`. Any skill-file count is struck from the work. * **The band is declared.** Verified against the tree rather than taken from the thread - `pyproject.toml` carries `[tool.agentic-os.documentation-layout] band = "small"` with the reasoning inline. That item is done. Both parent epics stay valid and now point at one issue: `coilysiren/inbox#374` and `coilyco-flight-deck/agentic-os#1102`. #299 is labelled `priority/P3` `autonomy/headless` `role/engineer`. P3 rather than higher because the pin means nothing is red today, and the docs count cap is not yet wired into the hook's `main()`.

coilyco-ops closed this issue

2026-08-17 01:43:16 +00:00

coilyco-ops commented

2026-08-17 03:29:50 +00:00

Author

Member

Measured against current main with the post-#1108 validator. 37 violations, and I have changed nothing here, because the numbers say something you should see before I start deleting.

You assigned umbra small by hand, so unlike the swept repos I have not touched the band. But small is a harder target here than the issue text suggests.

The arithmetic

docs/ holds 44 files totalling 123,909 chars. The small band's ceiling is 20 docs x 3,000 chars = 60,000. So reaching it means deleting a little over half of this repo's documentation. Merging does not help: merging only reduces the file count, and the char total is what busts.

For contrast, at large the ceiling is 40 x 8,000 = 320,000, and the longest doc here is 77 lines against a 120-line cap. umbra would need nothing at all.

There is also an intermediate problem. At the current pin a doc is capped at 4,000 chars, so even a 20-doc packing is capped at 80,000, still under 123,909. The deletion has to come before the merges, and the merges cannot land before the pin advances.

Why I am asking rather than cutting

This is a public security-boundary framework for urfave/cli v3, with external contributors and a documented spec surface. Sixteen of the 44 docs are specverb-* pages covering one verb behavior each: wildcard, actions, raw-responses, inherit, override. Those read as reference material for people outside the estate, and halving them is a different act from tightening internal notes.

CODE_OF_CONDUCT.md also sits in docs/. It is exempt from the size cap as verbatim upstream text, but it still consumes one of the 20 slots.

So: does small still hold now that it means removing half the framework's docs, or does umbra belong at large like its sibling engines? I raised it on coilysiren/inbox#374 alongside sirens-echo and infrastructure, which need 30% and 18% deleted respectively even at large.

Nothing is enforced here until the pin advances past v0.65.0.

Measured against current `main` with the post-#1108 validator. **37 violations, and I have changed nothing here, because the numbers say something you should see before I start deleting.** You assigned umbra `small` by hand, so unlike the swept repos I have not touched the band. But small is a harder target here than the issue text suggests. ## The arithmetic `docs/` holds 44 files totalling **123,909 chars**. The small band's ceiling is 20 docs x 3,000 chars = **60,000**. So reaching it means deleting a little over **half** of this repo's documentation. Merging does not help: merging only reduces the file count, and the char total is what busts. For contrast, at large the ceiling is 40 x 8,000 = 320,000, and the longest doc here is 77 lines against a 120-line cap. umbra would need **nothing at all**. There is also an intermediate problem. At the current pin a doc is capped at 4,000 chars, so even a 20-doc packing is capped at 80,000, still under 123,909. The deletion has to come before the merges, and the merges cannot land before the pin advances. ## Why I am asking rather than cutting This is a public security-boundary framework for urfave/cli v3, with external contributors and a documented spec surface. Sixteen of the 44 docs are `specverb-*` pages covering one verb behavior each: wildcard, actions, raw-responses, inherit, override. Those read as reference material for people outside the estate, and halving them is a different act from tightening internal notes. `CODE_OF_CONDUCT.md` also sits in `docs/`. It is exempt from the size cap as verbatim upstream text, but it still consumes one of the 20 slots. So: does `small` still hold now that it means removing half the framework's docs, or does umbra belong at large like its sibling engines? I raised it on coilysiren/inbox#374 alongside sirens-echo and infrastructure, which need 30% and 18% deleted respectively even at large. Nothing is enforced here until the pin advances past `v0.65.0`.

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/umbra#300

No description provided.

Rows
Columns