Hold ward-kdl guardfiles to the 2-contiguous-comment rule (drop the code-comments exclusion, migrate rationale to describe/message) #242

New issue

Closed

opened 2026-06-24 05:29:52 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

2026-06-24 05:29:52 +00:00

Member

Goal

Hold the *.guardfile.kdl files to the same ≤2 contiguous comment lines rule every other code file obeys. No special KDL exemption.

State today

The catalog code-comments hook already lints .kdl with MAX_CONTIGUOUS_COMMENT_LINES = 2 (agentic-os agentic_os/pre_commit/check_code_comments.py, shipped v0.65.0). .go / .py / .ts / .kdl are all covered — no linter change needed.
But ward's [tool.agentic-os.code-comments] in pyproject.toml excludes the guardfiles (cmd/ward-kdl/*.guardfile.kdl, cmd/ward/opsassets/*.guardfile.kdl), added in #136 to preserve ~32 inline per-leaf allow/deny rationale comments. So the guardfiles are the one KDL class not held to the rule.

Change

Drop the *.guardfile.kdl entries from the [tool.agentic-os.code-comments] excludes in pyproject.toml.
Migrate each leaf's inline rationale (issue cites, scope notes) that runs past 2 contiguous comment lines into first-class describe / message fields on the grant — auditable beside the leaf AND surfaced in ward ops <wrap> describe and the generated .md. Keep ≤2 genuine comment lines where they help.
Net: guardfiles read like the rest of the code; durable rationale lives in queryable fields, not free comments.

Relationship

Refines/supersedes ward#205 ("zero KDL code comments"): the policy is the standard ≤2 contiguous lines like other code, not strictly zero. Reconcile or close #205.
Reverses the temporary exclusion from #136 (an in-burndown unblock, not a deliberate long-term carve-out).
No agentic-os change — the linter already supports .kdl.

Acceptance

cmd/ward-kdl/*.guardfile.kdl + cmd/ward/opsassets/*.guardfile.kdl removed from the code-comments excludes.
pre-commit run code-comments --all-files passes with no guardfile exclusion.
Per-leaf rationale preserved as describe / message fields (visible in describe output) — nothing durable lost.
Conventional commit, closes via the full Forgejo URL trailer, push to canonical main.

## Goal Hold the `*.guardfile.kdl` files to the same **≤2 contiguous comment lines** rule every other code file obeys. No special KDL exemption. ## State today - The catalog `code-comments` hook **already lints `.kdl`** with `MAX_CONTIGUOUS_COMMENT_LINES = 2` (agentic-os `agentic_os/pre_commit/check_code_comments.py`, shipped v0.65.0). `.go` / `.py` / `.ts` / `.kdl` are all covered — **no linter change needed.** - But ward's `[tool.agentic-os.code-comments]` in `pyproject.toml` **excludes** the guardfiles (`cmd/ward-kdl/*.guardfile.kdl`, `cmd/ward/opsassets/*.guardfile.kdl`), added in #136 to preserve ~32 inline per-leaf allow/deny rationale comments. So the guardfiles are the one KDL class not held to the rule. ## Change - Drop the `*.guardfile.kdl` entries from the `[tool.agentic-os.code-comments]` excludes in `pyproject.toml`. - Migrate each leaf's inline rationale (issue cites, scope notes) that runs past 2 contiguous comment lines into **first-class `describe` / `message` fields** on the grant — auditable beside the leaf AND surfaced in `ward ops <wrap> describe` and the generated `.md`. Keep ≤2 genuine comment lines where they help. - Net: guardfiles read like the rest of the code; durable rationale lives in queryable fields, not free comments. ## Relationship - **Refines/supersedes ward#205** ("zero KDL code comments"): the policy is the standard **≤2 contiguous lines like other code**, not strictly zero. Reconcile or close #205. - Reverses the temporary exclusion from #136 (an in-burndown unblock, not a deliberate long-term carve-out). - No agentic-os change — the linter already supports `.kdl`. ## Acceptance 1. `cmd/ward-kdl/*.guardfile.kdl` + `cmd/ward/opsassets/*.guardfile.kdl` removed from the code-comments excludes. 2. `pre-commit run code-comments --all-files` passes with no guardfile exclusion. 3. Per-leaf rationale preserved as `describe` / `message` fields (visible in `describe` output) — nothing durable lost. 4. Conventional commit, closes via the full Forgejo URL trailer, push to canonical main.

coilyco-ops added the

headless

labels

2026-06-24 05:31:44 +00:00

coilyco-ops commented

2026-06-24 05:31:45 +00:00

Author

Member

🔒 Reserved by ward agent claude — container ward-ward-issue-242-claude-306c4b78 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-06-24T05:31:45Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent claude` — container `ward-ward-issue-242-claude-306c4b78` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-06-24T05:31:45Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`