feat(code-comments): add header_cap and yaml_comments_below_content dials #1143

Merged

coilysiren merged 1 commit from feat/code-comments-header-cap into main

2026-08-19 23:22:33 +00:00

coilyco-ops commented

2026-08-19 23:17:55 +00:00

Owner

Two per-repo dials under [tool.agentic-os.code-comments], both defaulting off, so no repo in the fleet changes behaviour until it opts in. The existing 27 tests all still pass unmodified.

`header_cap`

Applies the existing two-line cap to the top-of-file header, for YAML and KDL only. The exemption let a header grow without bound, which is exactly where explanation accumulates once every other position is capped. Prose languages keep the exemption, since a license or teaching header is the case it was written for.

Counted across blank lines, so a blank inside the header cannot reset the streak and uncap the block. Reports once per file rather than once per surplus line.

`yaml_comments_below_content`

Drops the YAML-only top-block restriction, giving YAML the same capped comments every other language gets.

That restriction exists solely because yaml-strict sorts keys and would drift a comment off its target. A repo not running that hook has no sorter, so the rule only pushes per-key rationale into one unbounded block at the top. In coilyco-bridge/deploy that is 2062 surplus header lines, and 14 of its files name this rule in their own text as the reason the prose sits where it does, in wording like "kept in this top block so a key-sorter cannot drift a comment off its target".

Setting this while yaml-strict is configured fails closed with an explanation rather than being silently obeyed, since that pair would sort the keys and then strip the comments. Detection reads the hook id textually from .pre-commit-config.yaml, because this hook ships with no dependencies.

Verification against a real consumer

Ran the new scan over coilyco-bridge/deploy, which has already swept its .mcp.kdl headers:

KDL with header_cap on: 0 violations. The completed sweep already satisfies the new rule exactly, so the two halves line up.
YAML with both dials off: unchanged from today.
YAML with header_cap on: 89 files, which is precisely the set deploy's own YAML sweep plan covers.
YAML with both on: the below-content violations disappear and only the 89 header ones remain, which is the intended split.

15 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.

Notes

No docs/FEATURES.md entry: this tightens and relaxes an existing validator rather than adding a capability. docs/catalog-caps-reference.md is regenerated through just gen-caps-reference, not hand-edited.

Consumers still need a tag and a pin bump before any of this reaches them; deploy is still pinned at v0.102.0, off the aos-precommit-v* train entirely.

Two per-repo dials under `[tool.agentic-os.code-comments]`, **both defaulting off**, so no repo in the fleet changes behaviour until it opts in. The existing 27 tests all still pass unmodified. ## `header_cap` Applies the existing two-line cap to the top-of-file header, for YAML and KDL only. The exemption let a header grow without bound, which is exactly where explanation accumulates once every other position is capped. Prose languages keep the exemption, since a license or teaching header is the case it was written for. Counted across blank lines, so a blank inside the header cannot reset the streak and uncap the block. Reports once per file rather than once per surplus line. ## `yaml_comments_below_content` Drops the YAML-only top-block restriction, giving YAML the same capped comments every other language gets. That restriction exists **solely** because `yaml-strict` sorts keys and would drift a comment off its target. A repo not running that hook has no sorter, so the rule only pushes per-key rationale into one unbounded block at the top. In coilyco-bridge/deploy that is 2062 surplus header lines, and **14 of its files name this rule in their own text** as the reason the prose sits where it does, in wording like "kept in this top block so a key-sorter cannot drift a comment off its target". Setting this while `yaml-strict` is configured **fails closed with an explanation** rather than being silently obeyed, since that pair would sort the keys and then strip the comments. Detection reads the hook id textually from `.pre-commit-config.yaml`, because this hook ships with no dependencies. ## Verification against a real consumer Ran the new scan over coilyco-bridge/deploy, which has already swept its `.mcp.kdl` headers: - **KDL with `header_cap` on: 0 violations.** The completed sweep already satisfies the new rule exactly, so the two halves line up. - YAML with both dials off: unchanged from today. - YAML with `header_cap` on: 89 files, which is precisely the set deploy's own YAML sweep plan covers. - YAML with both on: the below-content violations disappear and only the 89 header ones remain, which is the intended split. 15 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. ## Notes No `docs/FEATURES.md` entry: this tightens and relaxes an existing validator rather than adding a capability. `docs/catalog-caps-reference.md` is regenerated through `just gen-caps-reference`, not hand-edited. Consumers still need a tag and a pin bump before any of this reaches them; deploy is still pinned at `v0.102.0`, off the `aos-precommit-v*` train entirely.

coilyco-ops added 1 commit

2026-08-19 23:17:55 +00:00

feat(code-comments): add header_cap and yaml_comments_below_content dials

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

Details

ci / ward-doctor (pull_request) Successful in 15s

Details

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

Details

ci / gate (pull_request) Successful in 53s

Details

1be77c1889

Two per-repo dials under [tool.agentic-os.code-comments], both defaulting off
so no repo in the fleet changes behaviour until it opts in.

`header_cap` applies the existing two-line cap to the top-of-file header for
YAML and KDL. The exemption let a header grow without bound, which is exactly
where explanation accumulates once every other position is capped. Prose
languages keep the exemption, since a license or teaching header is the case
the exemption was written for.

`yaml_comments_below_content` drops the YAML-only top-block restriction, giving
YAML the same capped comments every other language gets. That restriction
exists solely because yaml-strict sorts keys and would drift a comment off its
target. A repo that does not run that hook has no sorter, so the restriction
only pushes per-key rationale into one unbounded block at the top: deploy has
2062 such surplus lines, and 14 of its files name this rule in their own text
as the reason the prose sits where it does.

Setting the second dial while yaml-strict is configured fails closed with an
explanation rather than being silently obeyed, because that pair would sort the
keys and then strip the comments. Detection reads the hook id textually, since
this hook ships with no dependencies.

Verified against coilyco-bridge/deploy, which has already swept its .mcp.kdl
headers: KDL with header_cap on reports zero violations, so the two halves line
up. YAML reports the 89 files its own sweep plan covers, and enabling the
second dial resolves exactly the below-content violations, leaving the header
ones.

No FEATURES entry: this tightens and relaxes an existing validator rather than
adding a capability.

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:17:56 +00:00