docs band migration: trim 1 files #12

New issue

Open

opened 2026-08-16 06:59:47 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-16 06:59:47 +00:00

Member

This repo declares the small documentation band, so its caps are
40 lines / 3,000 chars per Markdown file and 20 docs/*.md.

Measured by running the validator against this checkout:

docs/: 2 files against a 20 cap - already under the cap, keep it there
1 files over a size cap - 1 docs/*.md prose

The work

Bring 1 files under 40 lines / 3,000 chars. Breakdown: 1 docs/*.md prose.

Merging is the move, not splitting. Splitting one over-long doc into two trades
a size violation for a count violation, which is the whole reason the count cap
exists.

Done means

pre-commit run --all-files green, with no new entry under
[tool.agentic-os.documentation-layout] excludes. Excludes still govern
placement and flatness and no longer reach either size cap or the count, so
adding one cannot close this issue. A generated file over the cap is a
generator emitting too much, and the fix is the generator.

Take as long as it needs. There is no partial-credit state to reach for.

This repo's pre-commit run --all-files fails on pristine main for reasons unrelated to this work, so nothing can commit until scoop-bucket#11 clears. Start there.

Parent: coilyco-flight-deck/agentic-os#1102. Rationale and the measurements behind the numbers:
docs/documentation-bands.md.

This repo declares the **`small`** documentation band, so its caps are **40 lines / 3,000 chars** per Markdown file and **20 `docs/*.md`**. Measured by running the validator against this checkout: * **`docs/`: 2 files against a 20 cap** - already under the cap, keep it there * **1 files over a size cap** - 1 `docs/*.md` prose ## The work 1. Bring 1 files under 40 lines / 3,000 chars. Breakdown: 1 `docs/*.md` prose. Merging is the move, not splitting. Splitting one over-long doc into two trades a size violation for a count violation, which is the whole reason the count cap exists. ## Done means `pre-commit run --all-files` green, with no new entry under `[tool.agentic-os.documentation-layout] excludes`. Excludes still govern placement and flatness and no longer reach either size cap or the count, so adding one cannot close this issue. A generated file over the cap is a generator emitting too much, and the fix is the generator. Take as long as it needs. There is no partial-credit state to reach for. This repo's `pre-commit run --all-files` fails on pristine `main` for reasons unrelated to this work, so nothing can commit until scoop-bucket#11 clears. Start there. Parent: coilyco-flight-deck/agentic-os#1102. Rationale and the measurements behind the numbers: [docs/documentation-bands.md](https://forgejo.coilysiren.me/coilyco-flight-deck/agentic-os/src/branch/main/docs/documentation-bands.md).

coilyco-ops added the

labels

2026-08-16 07:01:13 +00:00

coilyco-ops referenced this issue from coilyco-flight-deck/agentic-os

2026-08-16 07:03:24 +00:00

docs band migration: 468 docs to merge, 531 files to trim, 24 repos #1102