Apply the two-line comment cap to YAML and KDL headers #1398

Merged

coilyco-ops merged 5 commits from aos/claude/ee98-headercap into main

2026-08-29 11:21:43 +00:00

coilyco-ops commented

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

Owner

header_cap shipped off, so MAX_CONTIGUOUS_COMMENT_LINES never applied to a YAML file in any catalog repo. For YAML the top block is also the only legal comment position, so the two rules composed into "unlimited prose, as long as it is at the top" - deploy carried 415 comment lines across three values files and passed cleanly every time.

The dial now defaults on. A repo opts back out with header_cap = false.

The 18 files here, and where their ~155 lines went

Nothing is cut.

11 aosguard guardfiles to .agents/skills/tooling-aosguard/references/guardfile-headers.md, which takes no size cap. This is why #1303's move mattered first: redis.kdl alone carried a 21-line header on why writes are absent and auth never reaches argv.
5 workflows, .ward/ward.yaml, docker/dev-base/fleet-precommit-hooks.yaml to docs/build-file-headers.md, using one of the four slots #1303 freed. docs/ is 37 of 40.

Each file keeps a one-sentence identity line plus a pointer. I hand-wrote nine of those summaries because sentence-splitting truncated them mid-clause.

Verified, not assumed

The hook caught my own 3-line comment in the change that turns it on, twice, which is the dogfooding working. Separately, a tracked 4-line-header probe:

ON : .ward/probe.yaml:3: top-of-file comment header is 3 lines, over the 2-line cap.
OFF: []

760 tests pass, full pre-commit suite green.

Fleet note

This is a behavior change for every catalog repo on the next pin bump. deploy's headers were already relocated in d53770b; other repos will fail loudly on their next run, which is the point - the fix is to move the prose to docs and leave a pointer.

Closes #1119

`header_cap` shipped **off**, so `MAX_CONTIGUOUS_COMMENT_LINES` never applied to a YAML file in any catalog repo. For YAML the top block is also the *only* legal comment position, so the two rules composed into "unlimited prose, as long as it is at the top" - deploy carried **415 comment lines** across three values files and passed cleanly every time. The dial now defaults on. A repo opts back out with `header_cap = false`. ## The 18 files here, and where their ~155 lines went Nothing is cut. * **11 aosguard guardfiles** to `.agents/skills/tooling-aosguard/references/guardfile-headers.md`, which takes no size cap. This is why #1303's move mattered first: `redis.kdl` alone carried a 21-line header on why writes are absent and auth never reaches argv. * **5 workflows, `.ward/ward.yaml`, `docker/dev-base/fleet-precommit-hooks.yaml`** to `docs/build-file-headers.md`, using one of the four slots #1303 freed. docs/ is 37 of 40. Each file keeps a one-sentence identity line plus a pointer. I hand-wrote nine of those summaries because sentence-splitting truncated them mid-clause. ## Verified, not assumed The hook caught **my own** 3-line comment in the change that turns it on, twice, which is the dogfooding working. Separately, a tracked 4-line-header probe: ``` ON : .ward/probe.yaml:3: top-of-file comment header is 3 lines, over the 2-line cap. OFF: [] ``` 760 tests pass, full pre-commit suite green. ## Fleet note This is a behavior change for every catalog repo on the next pin bump. deploy's headers were already relocated in `d53770b`; other repos will fail loudly on their next run, which is the point - the fix is to move the prose to docs and leave a pointer. Closes #1119

coilyco-ops added 2 commits

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

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

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

Details

ci / gate (pull_request) Successful in 54s

Details

13224d1c54

docs/ was at 39 of 40 with aterm.md at zero chars of headroom, so five
issues (#1303, #1274, #1341, #1312, #1119) all stalled on the same wall
with nowhere to put a page. Merging pages does not help: the per-page cap
is 120 lines and the candidates are ~100 lines each.

A skill's references/ takes no size cap and no docs count, which is the
escape check-skills already hands an author. warp.md and warp-host-setup.md
belong to tooling-warp, aosguard.md to tooling-aosguard. Nothing is cut.

docs/ is now 36 of 40.

.specgen/README.md was an outpost pointing at docs/aosguard.md, so with
that target gone it becomes a homestead naming the skill instead. Code
comments now name the skill rather than a deep path, and paths.go loses
four repeats of one pointer it already carried.

Refs coilyco-flight-deck/agentic-os#1303

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Agent-Role: platform

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

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

Details

ci / gate (pull_request) Successful in 59s

Details

dev-base-pr / build (pull_request) Successful in 9m20s

Details

24787d616e

`header_cap` shipped off, so nothing ever applied `MAX_CONTIGUOUS_COMMENT_LINES`
to a YAML file. For YAML the top block is also the only legal comment position,
so the two rules composed into "unlimited prose, as long as it is at the top":
deploy carried 415 comment lines across three values files, all of them legal.

The dial now defaults on. A repo opts back out with `header_cap = false`.

18 files in this repo were over, carrying ~155 lines. None of it is cut:

* 11 aosguard guardfiles land in the tooling-aosguard skill's references/,
  which takes no size cap.
* 5 workflows, .ward/ward.yaml and the fleet hooks file land in
  docs/build-file-headers.md, using one of the four slots #1303 freed.

Each file keeps a one-sentence identity line and a pointer.

Closes coilyco-flight-deck/agentic-os#1119

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Agent-Role: platform

coilyco-ops added 1 commit

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

merge: bring main into the branch

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

Details

ci / gate (pull_request) Successful in 57s

Details

dev-base-pr / build (pull_request) Failing after 15m22s

Details

b3589040eb

The three aosguard ops pages moved into the skill's references/ on main
while this branch was extracting their headers, so the extracted prose
re-anchors onto the new paths.

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Agent-Role: platform

coilyco-ops added 1 commit

2026-08-29 11:04:02 +00:00