feat(documentation-layout): add size_excludes for a repo's own co-located docs #1144

Merged

coilysiren merged 2 commits from feat/documentation-layout-size-excludes into main

2026-08-20 06:36:39 +00:00

coilyco-ops commented

2026-08-19 23:42:41 +00:00

Owner

A third key beside excludes and vendored, opt-in and empty by default, so no repo changes behaviour until it declares it.

The gap

The size caps deliberately ignore excludes (markdown_files(apply_excludes=False)) because that key governs placement. They honour only vendored, which states the Markdown is not this repo's to shape.

A monorepo that co-locates a README and docs/ under each component fits neither. Those docs are the repo's own, and the root-plus-flat-docs/ shape the caps assume does not describe them. Without a third key such a repo can buy the exemption only by declaring its own docs vendored, which is a false statement about provenance sitting in a tracked config file.

How it surfaced

Moving coilyco-bridge/deploy off v0.102.0 onto the aos-precommit-v* train. That repo already declares the services/** and charts/** carve-out under excludes, with a written rationale about being a multi-service monorepo. One half of the hook honours that carve-out and the other does not, so 13 of its co-located service docs are over cap, including a 1015-line service README.

The alternatives were splitting 13 docs as a precondition for a hook pin bump, or lying in a config file. Neither is right.

Scope

size_excludes takes the same gitignore-style globs as excludes, through the existing is_excluded.
Answers the size caps only. It cannot widen where Markdown may live, exactly as vendored cannot.
The debt stays visible: this exempts a declared subtree rather than raising a cap, so the number in the config is a standing statement about which tree is unusual.

3 new tests. pre-commit run --all-files green. pytest green apart from test_ward_specs_bundle.py, which fails identically on a clean tree here because the ward binary is absent from this shadow.

A third key beside `excludes` and `vendored`, **opt-in and empty by default**, so no repo changes behaviour until it declares it. ## The gap The size caps deliberately ignore `excludes` (`markdown_files(apply_excludes=False)`) because that key governs placement. They honour only `vendored`, which states the Markdown is not this repo's to shape. A monorepo that co-locates a README and `docs/` under each component fits neither. Those docs **are** the repo's own, and the root-plus-flat-`docs/` shape the caps assume does not describe them. Without a third key such a repo can buy the exemption only by declaring its own docs `vendored`, which is a false statement about provenance sitting in a tracked config file. ## How it surfaced Moving coilyco-bridge/deploy off `v0.102.0` onto the `aos-precommit-v*` train. That repo already declares the `services/**` and `charts/**` carve-out under `excludes`, with a written rationale about being a multi-service monorepo. One half of the hook honours that carve-out and the other does not, so **13 of its co-located service docs are over cap**, including a 1015-line service README. The alternatives were splitting 13 docs as a precondition for a hook pin bump, or lying in a config file. Neither is right. ## Scope - `size_excludes` takes the same gitignore-style globs as `excludes`, through the existing `is_excluded`. - Answers the size caps only. It cannot widen where Markdown may live, exactly as `vendored` cannot. - The debt stays visible: this exempts a declared subtree rather than raising a cap, so the number in the config is a standing statement about which tree is unusual. 3 new tests. `pre-commit run --all-files` green. `pytest` green apart from `test_ward_specs_bundle.py`, which fails identically on a clean tree here because the `ward` binary is absent from this shadow.

coilyco-ops added 1 commit

2026-08-19 23:42:41 +00:00

feat(documentation-layout): add size_excludes for a repo's own co-located docs

ci / aos-eval-tests (pull_request) Successful in 5s

Details

ci / aos-cli-tests (pull_request) Successful in 19s

Details

ci / ward-doctor (pull_request) Failing after 35s

Details

ci / gate (pull_request) Successful in 56s

Details

38ff78a541

The size caps deliberately ignore `excludes`, which governs placement, and
honour only `vendored`, which states the Markdown is not this repo's. A
monorepo that co-locates a README and docs/ under each component fits neither:
those docs are the repo's own, and the root-plus-flat-docs shape the caps
assume does not describe them.

Without a third key such a repo can buy the exemption only by declaring its own
docs vendored, which is a false statement about provenance sitting in a tracked
config file. `size_excludes` is the honest key for that case.

Found while moving coilyco-bridge/deploy onto the aos-precommit train: it
already declares the services/ and charts/ carve-out under `excludes` with a
written rationale, and one half of the hook honours that while the other does
not. 13 of its co-located service docs are over cap as a result.

Opt-in and empty by default, so no repo changes behaviour until it declares the
key. The debt stays visible: this exempts a declared subtree from the caps
rather than raising them.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-19 23:42:41 +00:00

coilysiren added 1 commit

2026-08-20 06:31:38 +00:00