code-comments v0.16.0 YAML-comment rule is too aggressive (227 hits in one repo); make it opt-in or scoped #195

New issue

Closed

opened 2026-06-07 19:25:08 +00:00 by coilysiren · 1 comment

coilysiren commented

2026-06-07 19:25:08 +00:00

Owner

Concern

v0.16.0's code-comments check added a rule that flags any YAML comment not on the first line ("YAML comment outside the top 1-line header. A key-sorter would drift it away from its target. Keep YAML comments to the first line; move the rest to docs/").

Adopting v0.16.0 in agentic-os-kai surfaced 227 violations across 10 hand-maintained config files — .agents/skills/categories.yaml (127), data/repo-split-decisions.yaml (47), .coily/coily.yaml (13), lib/my/*.yaml, .github/workflows/*.yml, even .pre-commit-config.yaml itself. These are ordinary inline / section comments in deliberately-commented config, not drift.

Why this seems too aggressive

Inline and section comments in YAML are standard and useful (annotating a key, a block, a workflow step). The rule effectively bans them everywhere.
The stated rationale (a key-sorter would drift the comment) only applies to files that are actually run through an alphabetizing sorter. Most config YAML is hand-ordered and never sorted.
It blocks adoption of unrelated v0.16.0 features (e.g. the AGENTS.<harness>.md override allowance) behind a large, unrelated cleanup — coupling a doc-layout feature to a comment-style migration.

Options to consider

Make the YAML-comment rule opt-in (off by default), or scoped to files a repo declares as sorter-managed.
Limit it to catalog/registry YAML (the files actually sorted), not all *.yaml/*.yml.
Downgrade to a warning.

Immediate workaround

agentic-os-kai excluded the 10 files via [tool.agentic-os.code-comments].excludes to land the unrelated unpin/carve (agentic-os-kai#635). That exclude should be revisited once this rule's scope is settled.

## Concern v0.16.0's `code-comments` check added a rule that flags **any YAML comment not on the first line** ("YAML comment outside the top 1-line header. A key-sorter would drift it away from its target. Keep YAML comments to the first line; move the rest to docs/"). Adopting v0.16.0 in `agentic-os-kai` surfaced **227 violations across 10 hand-maintained config files** — `.agents/skills/categories.yaml` (127), `data/repo-split-decisions.yaml` (47), `.coily/coily.yaml` (13), `lib/my/*.yaml`, `.github/workflows/*.yml`, even `.pre-commit-config.yaml` itself. These are ordinary inline / section comments in deliberately-commented config, not drift. ## Why this seems too aggressive - Inline and section comments in YAML are standard and useful (annotating a key, a block, a workflow step). The rule effectively bans them everywhere. - The stated rationale (a key-sorter would drift the comment) only applies to files that are actually run through an alphabetizing sorter. Most config YAML is hand-ordered and never sorted. - It blocks adoption of unrelated v0.16.0 features (e.g. the `AGENTS.<harness>.md` override allowance) behind a large, unrelated cleanup — coupling a doc-layout feature to a comment-style migration. ## Options to consider 1. Make the YAML-comment rule **opt-in** (off by default), or scoped to files a repo declares as sorter-managed. 2. Limit it to catalog/registry YAML (the files actually sorted), not all `*.yaml`/`*.yml`. 3. Downgrade to a warning. ## Immediate workaround `agentic-os-kai` excluded the 10 files via `[tool.agentic-os.code-comments].excludes` to land the unrelated unpin/carve (agentic-os-kai#635). That exclude should be revisited once this rule's scope is settled.

coilysiren referenced this issue from a commit

2026-06-07 19:30:29 +00:00

feat(agents): unpin AGENTS.md from the claude slice, carve Claude mechanics to override

coilysiren added the

priority

autonomy

async-consult

labels

2026-06-17 07:04:54 +00:00

coilysiren commented

2026-06-18 06:42:08 +00:00

Author

Owner

Goose triage - 2026-06-17

Tier: P3 (score 68) - Medium priority backlog issue, significant impact but not urgent
Mode: consult - Ambiguous issue requiring design decision on rule scope

_{Auto-generated by ward exec goose-triage (qwen3-coder:30b), edited in place on each run. Labels are the conclusion; this is the why.}

**Goose triage** - 2026-06-17 - **Tier:** `P3` (score 68) - Medium priority backlog issue, significant impact but not urgent - **Mode:** `consult` - Ambiguous issue requiring design decision on rule scope <sub>Auto-generated by `ward exec goose-triage` (qwen3-coder:30b), edited in place on each run. Labels are the conclusion; this is the why.</sub>