coilyco-flight-deck/agentic-os

Watch

code-comments never applies MAX_CONTIGUOUS_COMMENT_LINES to YAML, so YAML headers are an unbounded dumping ground #1119

New issue

Closed

opened 2026-08-18 02:04:40 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

2026-08-18 02:04:40 +00:00

Owner

Filed by Darren (director seat), 2026-08-18, from a real case in coilyco-bridge/deploy. Kai's words when she hit it:

there's a existing precommit linter for enforcing yaml comments to 1 line that this repo has literally never even attempted to follow, for whatever reason

Her instinct was right, and the reason is not that anyone ignored the hook. The hook has never checked YAML for it.

The gap

agentic_os/pre_commit/check_code_comments.py defines both caps:

MAX_COMMENT_LINE_CHARS = 90
MAX_CONTIGUOUS_COMMENT_LINES = 2

scan_yaml() applies only the first:

the 90-char per-line cap
the YAML placement rule, "comment below the top header block"

MAX_CONTIGUOUS_COMMENT_LINES is referenced exactly once outside its definition, in the non-YAML scan path at line 284. No YAML file in any catalog repo has ever been checked against the run cap.

The module docstring is what makes this a bug rather than a design choice. It says the top-of-file exemption exists "so license and teaching headers are fine". For YAML it is not an exemption from the run cap, it is the only legal place to put a comment, so the two rules compose into "unlimited prose, as long as it is at the top".

What that produced in practice

coilyco-bridge/deploy, three Sirens lane values files, measured before I fixed them:

916 lines total, 415 of them comment. All 415 in top header blocks.
sirens-deep-owl-glass-values.yaml opened with a 97-line essay before its first setting.
Every file passed code-comments cleanly, every time, for months.

Fixed on the deploy side in d53770b by moving all 418 header lines to services/sirens-echo/docs/lane-values-rationale.md and leaving one-line pointers. Rendered manifests are byte-identical, verified with the rollout scripts' own --render. That fix is voluntary and nothing stops it regrowing, which is why this issue exists.

Why it matters beyond tidiness

This surfaced during a critical failure. owl.glass dropped 3 of 14 turns and ran a 182s p95 (coilyco-gaming/sirens-echo#939, #940). Kai's account of why it was hard to act on:

Deep's config is currently psychologically overloading me. And Deep's config is critical fail on actual load.

A values file is read under pressure, by someone deciding what to change. 97 lines of prose above the first setting is the failure mode the code-comments doctrine already names, and the hook is the thing meant to prevent it.

Proposed fix

Apply MAX_CONTIGUOUS_COMMENT_LINES in scan_yaml(), including inside the top header block, since for YAML that block is the only legal position and exempting it exempts everything.

This will fail loudly across the fleet on first run, so it needs the usual treatment:

Land the validator change here.
Expect per-repo [tool.agentic-os.code-comments] excludes as a landing strip, removed as each repo is cleaned.
Fleet rollout is ansible's, not this repo's.

Alternative if a full 2-line cap is too aggressive for YAML headers: a separate, larger MAX_YAML_HEADER_LINES (10 or so) that still bounds the block. I prefer the plain 2-line cap, because a bounded dumping ground is still a dumping ground and docs/ is right there.

What I did not do

No fix here, no branch. agentic-os is on the PR lane and this is a fleet-wide validator change two days before the August 19 stream, so it wants a human on the merge rather than an agent landing it tonight. The deploy-side cleanup that motivated it is already done and does not depend on this.

**Filed by Darren (director seat), 2026-08-18, from a real case in `coilyco-bridge/deploy`.** Kai's words when she hit it: > there's a existing precommit linter for enforcing yaml comments to 1 line that this repo has literally never even attempted to follow, for whatever reason Her instinct was right, and the reason is not that anyone ignored the hook. **The hook has never checked YAML for it.** ## The gap `agentic_os/pre_commit/check_code_comments.py` defines both caps: ```python MAX_COMMENT_LINE_CHARS = 90 MAX_CONTIGUOUS_COMMENT_LINES = 2 ``` `scan_yaml()` applies **only** the first: * the 90-char per-line cap * the YAML placement rule, "comment below the top header block" `MAX_CONTIGUOUS_COMMENT_LINES` is referenced exactly once outside its definition, in the non-YAML scan path at line 284. **No YAML file in any catalog repo has ever been checked against the run cap.** The module docstring is what makes this a bug rather than a design choice. It says the top-of-file exemption exists "so license and teaching headers are fine". For YAML it is not an exemption from the run cap, it is the *only* legal place to put a comment, so the two rules compose into "unlimited prose, as long as it is at the top". ## What that produced in practice `coilyco-bridge/deploy`, three Sirens lane values files, measured before I fixed them: * **916 lines total, 415 of them comment.** All 415 in top header blocks. * `sirens-deep-owl-glass-values.yaml` opened with a **97-line essay** before its first setting. * Every file passed `code-comments` cleanly, every time, for months. Fixed on the deploy side in `d53770b` by moving all 418 header lines to `services/sirens-echo/docs/lane-values-rationale.md` and leaving one-line pointers. Rendered manifests are byte-identical, verified with the rollout scripts' own `--render`. **That fix is voluntary and nothing stops it regrowing**, which is why this issue exists. ## Why it matters beyond tidiness This surfaced during a critical failure. owl.glass dropped 3 of 14 turns and ran a 182s p95 (`coilyco-gaming/sirens-echo#939`, `#940`). Kai's account of why it was hard to act on: > Deep's config is currently psychologically overloading me. And Deep's config is critical fail on actual load. A values file is read under pressure, by someone deciding what to change. 97 lines of prose above the first setting is the failure mode the `code-comments` doctrine already names, and the hook is the thing meant to prevent it. ## Proposed fix Apply `MAX_CONTIGUOUS_COMMENT_LINES` in `scan_yaml()`, including inside the top header block, since for YAML that block is the only legal position and exempting it exempts everything. **This will fail loudly across the fleet on first run**, so it needs the usual treatment: * Land the validator change here. * Expect per-repo `[tool.agentic-os.code-comments]` excludes as a landing strip, removed as each repo is cleaned. * Fleet rollout is ansible's, not this repo's. **Alternative if a full 2-line cap is too aggressive for YAML headers:** a separate, larger `MAX_YAML_HEADER_LINES` (10 or so) that still bounds the block. I prefer the plain 2-line cap, because a bounded dumping ground is still a dumping ground and `docs/` is right there. ## What I did not do No fix here, no branch. `agentic-os` is on the PR lane and this is a fleet-wide validator change two days before the August 19 stream, so it wants a human on the merge rather than an agent landing it tonight. The deploy-side cleanup that motivated it is already done and does not depend on this.

coilyco-ops added the

role/platform

priority

labels

2026-08-25 08:11:49 +00:00

coilyco-ops added the

autonomy

async-consult

label

2026-08-25 09:30:49 +00:00

coilyco-ops commented

2026-08-29 07:34:24 +00:00

Author

Owner

Decided by Kai, 2026-08-29: apply the same 2-line MAX_CONTIGUOUS_COMMENT_LINES cap to YAML. No separate, larger YAML cap and no documented exemption.

I put three options to her (a larger YAML-specific run cap, the same 2-line cap, or documenting the exemption as deliberate) and argued for the larger cap on the grounds that a YAML header is the only legal place a comment can sit, so a 2-line limit pushes explanation into docs/ at the moment docs/ is full. She took the 2-line cap anyway, and in the same round decided the docs/ count cap stays and pages get merged rather than added. Both answers point the same way: the explanation goes somewhere already existing, or it does not get written.

What that makes the work

scan_yaml() in agentic_os/pre_commit/check_code_comments.py applies the 90-char per-line cap and the placement rule, and never applies MAX_CONTIGUOUS_COMMENT_LINES. Adding it is small. The consequences are not, and that is the real content of this issue:

every YAML header in every catalog repo becomes a candidate violation, and none has ever been checked
the module docstring's top-of-file exemption reasoning needs rewriting, since for YAML the top of file is the only legal location rather than a generous carve-out
docs/catalog-caps-reference.md has a sync check against the validator constants, so it moves in the same commit

Sweep first, then enforce

The fix should land with the size of the blast radius known rather than discovered by whoever commits next. A dry-run count of violating YAML headers per repo, before the cap is armed, is the honest first step. coilyco-bridge/deploy is the case that produced this issue and is likely the worst.

Two files I wrote tonight will violate it

Recording them so they are not a surprise. Both are three-line headers in coilyco-flight-deck/infrastructure, landed in #986:

ansible/roles/git-hook-template/defaults/main.yml
the two comment blocks I moved into ansible/playbooks/sync.yml's header when the placement rule rejected them inline

They were legal when written, because the run cap has never applied to YAML. They stop being legal the moment this lands, which is a fair illustration of why the sweep goes first.

**Decided by Kai, 2026-08-29: apply the same 2-line `MAX_CONTIGUOUS_COMMENT_LINES` cap to YAML.** No separate, larger YAML cap and no documented exemption. I put three options to her (a larger YAML-specific run cap, the same 2-line cap, or documenting the exemption as deliberate) and argued for the larger cap on the grounds that a YAML header is the only legal place a comment can sit, so a 2-line limit pushes explanation into `docs/` at the moment `docs/` is full. She took the 2-line cap anyway, and in the same round decided the `docs/` count cap stays and pages get merged rather than added. Both answers point the same way: the explanation goes somewhere already existing, or it does not get written. ## What that makes the work `scan_yaml()` in `agentic_os/pre_commit/check_code_comments.py` applies the 90-char per-line cap and the placement rule, and never applies `MAX_CONTIGUOUS_COMMENT_LINES`. Adding it is small. The consequences are not, and that is the real content of this issue: * every YAML header in every catalog repo becomes a candidate violation, and none has ever been checked * the module docstring's top-of-file exemption reasoning needs rewriting, since for YAML the top of file is the only legal location rather than a generous carve-out * `docs/catalog-caps-reference.md` has a sync check against the validator constants, so it moves in the same commit ## Sweep first, then enforce The fix should land with the size of the blast radius known rather than discovered by whoever commits next. A dry-run count of violating YAML headers per repo, before the cap is armed, is the honest first step. `coilyco-bridge/deploy` is the case that produced this issue and is likely the worst. ## Two files I wrote tonight will violate it Recording them so they are not a surprise. Both are three-line headers in `coilyco-flight-deck/infrastructure`, landed in `#986`: * `ansible/roles/git-hook-template/defaults/main.yml` * the two comment blocks I moved into `ansible/playbooks/sync.yml`'s header when the placement rule rejected them inline They were legal when written, because the run cap has never applied to YAML. They stop being legal the moment this lands, which is a fair illustration of why the sweep goes first.

coilyco-ops added this to the Rules that do not hold: silent guards, full budgets, second writers milestone

2026-08-29 07:55:28 +00:00

coilyco-ops referenced this issue from a commit

2026-08-29 10:25:28 +00:00

refactor(docs): move the warp and aosguard pages into skill references

coilyco-ops referenced this issue

2026-08-29 10:25:40 +00:00

Free the docs budget by moving warp and aosguard pages into skill references #1397

coilyco-ops referenced this issue from a commit

2026-08-29 10:31:39 +00:00

feat(code-comments): apply the two-line cap to YAML and KDL headers

coilyco-ops referenced this issue from a pull request that will close it,