declare the large documentation band, once the hooks come up clean #1668

New issue

Open

opened 2026-08-16 06:44:04 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-16 06:44:04 +00:00

Member

Every repo declares its documentation band rather than falling into one. The
change here is one line:

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

Caps for large: 120 lines / 8,000 chars per Markdown file, 40 docs/*.md.

Why this is an issue rather than a commit

pre-commit run --all-files fails on pristine main in this repo, so no
commit can land until that clears. Reproduced with the band edit stashed, so
none of it comes from the declaration:

source-doc-refs - cmd/ward/agent.go:1338 and :1386 both point at docs/ward-agent-dispatch.md, which is not there.
code-comments - cmd/ward/agent.go:1338 runs a 3-line contiguous block against the 2-line cap.

Fixing that debt is this issue's real work. The band line rides along once the
hooks come up clean.

Parent: agentic-os#1085. The validator that makes the declaration mandatory is
agentic-os#1090; until it ships, band is simply an unread key.

Every repo declares its documentation band rather than falling into one. The change here is one line: ```toml [tool.agentic-os.documentation-layout] band = "large" ``` Caps for `large`: 120 lines / 8,000 chars per Markdown file, 40 `docs/*.md`. ## Why this is an issue rather than a commit `pre-commit run --all-files` fails on pristine `main` in this repo, so no commit can land until that clears. Reproduced with the band edit stashed, so none of it comes from the declaration: * `source-doc-refs` - `cmd/ward/agent.go:1338` and `:1386` both point at `docs/ward-agent-dispatch.md`, which is not there. * `code-comments` - `cmd/ward/agent.go:1338` runs a 3-line contiguous block against the 2-line cap. Fixing that debt is this issue's real work. The band line rides along once the hooks come up clean. Parent: agentic-os#1085. The validator that makes the declaration mandatory is agentic-os#1090; until it ships, `band` is simply an unread key.

coilyco-ops added the

labels

2026-08-16 06:44:29 +00:00