chore: clean up code-comments violations (agentic-os v0.2.8) #8

New issue

Closed

opened 2026-05-26 05:22:56 +00:00 by coilysiren · 1 comment

coilysiren commented

2026-05-26 05:22:56 +00:00

Owner

Problem

The agentic-os pre-commit suite v0.2.8 enables code-comments with MAX_CONTIGUOUS=2 and a 90-char line cap. This repo currently has approximately 246 violations - mostly first-party multi-line docstrings, package godoc, and inline explanations.

Fix

Walk every flagged file. For each block:

Single sentence fitting 2 lines: leave as-is (allowed).
3+ line block: move durable detail to docs/<topic>.md, leave a one-line pointer (// see docs/<topic>.md) at the comment site.
Go package godoc: keep first 2 lines as summary, move rest to docs/.

Verify with:

pre-commit run code-comments --all-files

The dirty .claude/lockdown-deny.sh / .claude/settings.json and the rev: v0.2.8 bump in .pre-commit-config.yaml belong in the same commit per AGENTS.md sweep rule.

Rule shape

Rule softened from TOL=1 to TOL=2 in coilysiren/agentic-os#24. Vendored-file escape hatch tracked separately at coilysiren/agentic-os#22.

Ported from coilysiren/galaxy-gen#76.

**Problem** The agentic-os pre-commit suite v0.2.8 enables `code-comments` with MAX_CONTIGUOUS=2 and a 90-char line cap. This repo currently has approximately **246** violations - mostly first-party multi-line docstrings, package godoc, and inline explanations. **Fix** Walk every flagged file. For each block: - Single sentence fitting 2 lines: leave as-is (allowed). - 3+ line block: move durable detail to `docs/<topic>.md`, leave a one-line pointer (`// see docs/<topic>.md`) at the comment site. - Go package godoc: keep first 2 lines as summary, move rest to `docs/`. Verify with: ``` pre-commit run code-comments --all-files ``` The dirty `.claude/lockdown-deny.sh` / `.claude/settings.json` and the `rev: v0.2.8` bump in `.pre-commit-config.yaml` belong in the same commit per AGENTS.md sweep rule. **Rule shape** Rule softened from TOL=1 to TOL=2 in coilysiren/agentic-os#24. Vendored-file escape hatch tracked separately at coilysiren/agentic-os#22. --- _Ported from coilysiren/galaxy-gen#76._

coilysiren added the

label

2026-05-31 01:54:26 +00:00

coilysiren commented

2026-06-17 08:23:32 +00:00

Author

Owner

Backlog burndown 2026-06-17: closing low-priority (P3/P4) to bring the open count to a manageable level. Nothing lost — reopen if this resurfaces. Batch tag: burndown-2026-06.

Backlog burndown 2026-06-17: closing low-priority (P3/P4) to bring the open count to a manageable level. Nothing lost — reopen if this resurfaces. Batch tag: `burndown-2026-06`.

coilysiren

2026-06-17 08:23:33 +00:00