coilyco-flight-deck/ward

Watch

docs: declare a band, 42 docs to 20, 32 oversized docs, 2 skill files #1670

New issue

Closed

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

coilyco-ops commented

2026-08-17 00:48:55 +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 42 docs down to 20. docs/ currently holds 42 files against the small-band cap of 20, totalling 2373 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.
32 docs over the per-file cap of 40 lines / 3,000 chars.
2 skill files over the cap, and this part is blocked. documentation-layout applies the band cap to SKILL.md and COMPOSED.md, while check-skills allows 500 lines / 10,000 bytes for the same file. See the blocker on coilysiren/inbox#374 and do not trim these until it is settled.
2 other Markdown files over the cap, outside docs/ and outside the skill roots.

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 42 docs down to 20.** `docs/` currently holds 42 files against the small-band cap of 20, totalling 2373 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. **32 docs over the per-file cap** of 40 lines / 3,000 chars. 4. **2 skill files over the cap, and this part is blocked.** `documentation-layout` applies the band cap to `SKILL.md` and `COMPOSED.md`, while `check-skills` allows 500 lines / 10,000 bytes for the same file. See the blocker on coilysiren/inbox#374 and do not trim these until it is settled. 5. **2 other Markdown files over the cap**, outside `docs/` and outside the skill roots. ## 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 referenced this issue

2026-08-17 01:09:24 +00:00

chore(docs): declare the large documentation band #1671

coilyco-ops commented

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

Author

Member

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

Nothing is urgent. This repo pins ea1f408660ddd12e96d70af33d0a2c8165e51fc9, 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 `ea1f408660ddd12e96d70af33d0a2c8165e51fc9`, 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.

coilysiren referenced this issue from a commit

2026-08-17 01:21:53 +00:00

chore(docs): declare the large documentation band (#1671)

coilyco-ops referenced this issue

2026-08-17 01:55:50 +00:00

docs: bring the docs tree into the large band #1673

coilyco-ops commented

2026-08-17 01:59:12 +00:00

Author

Member

Migrated in ward#1673, open for review.

The large band Kai assigned turned this from 42-to-20 into two merges and one generated page. docs/agent-flags.md was fixed in its generator rather than by hand, since it is code-generated with a drift test: one row per command instead of a heading plus a bullet takes it from 142 lines to 53 with identical content.

Epic: coilysiren/inbox#374.

Migrated in ward#1673, open for review. The large band Kai assigned turned this from 42-to-20 into two merges and one generated page. `docs/agent-flags.md` was fixed in its generator rather than by hand, since it is code-generated with a drift test: one row per command instead of a heading plus a bullet takes it from 142 lines to 53 with identical content. Epic: coilysiren/inbox#374.

coilysiren referenced this issue from a commit

2026-08-17 02:15:18 +00:00

docs: bring the docs tree into the large band (#1673)

coilyco-ops commented

2026-08-17 02:43:59 +00:00

Author

Member

Verified clean on current main. Running the post-#1108 validator against a fresh checkout of origin/main returns no violations: band declared, 40 docs against the large cap of 40, and no file over 120 lines or 8,000 chars.

That closes this. The work landed across ward#1671 (the large band declaration) and ward#1673 (the docs themselves). The two items that made it awkward, for the record:

docs/agent-flags.md is generated, so no amount of editing the file fixes it. The only real fix was changing what cmd/ward/agent_flags.go emits: it wrote a heading plus a bullet plus a blank per command, three lines times 46 commands. One row per command carries the same content in 53 lines instead of 142, and TestAgentFlagsMarkdownShape moved with it.
Two merges got the count from 42 to 40: container-substrate.md into container.md, and agent-dispatch-recovery.md into agent-dispatch-health.md. Nine files were repointed, four of them Go source comments.

The skill files named in item 4 are struck by coilyco-flight-deck/agentic-os#1110, which now exempts the whole skill tree rather than only the two entrypoint basenames.

Verified clean on current `main`. Running the post-#1108 validator against a fresh checkout of `origin/main` returns no violations: band declared, 40 docs against the large cap of 40, and no file over 120 lines or 8,000 chars. That closes this. The work landed across ward#1671 (the `large` band declaration) and ward#1673 (the docs themselves). The two items that made it awkward, for the record: * `docs/agent-flags.md` is generated, so no amount of editing the file fixes it. The only real fix was changing what `cmd/ward/agent_flags.go` emits: it wrote a heading plus a bullet plus a blank per command, three lines times 46 commands. One row per command carries the same content in 53 lines instead of 142, and `TestAgentFlagsMarkdownShape` moved with it. * Two merges got the count from 42 to 40: `container-substrate.md` into `container.md`, and `agent-dispatch-recovery.md` into `agent-dispatch-health.md`. Nine files were repointed, four of them Go source comments. The skill files named in item 4 are struck by coilyco-flight-deck/agentic-os#1110, which now exempts the whole skill tree rather than only the two entrypoint basenames.

coilyco-ops closed this issue

2026-08-17 02:44:04 +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/ward#1670

No description provided.

Rows
Columns