Bring 96 comment blocks under the two-line discipline #89

New issue

Closed

opened 2026-08-11 00:58:04 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-11 00:58:04 +00:00

Member

Exempted at pre-commit adoption in #87 so the suite could land green. The exemption is a listed excludes in pyproject.toml rather than a disabled hook, so every file not on the list is governed now, including all new ones. Each file drops off as it is cleaned.

Where the violations are

96 total. The rule is that contiguous comment blocks stay at 2 lines, with longer explanations moved into docs/.

app/config.py - 22
.ward/ward.yaml - 21
app/models.py - 16
app/resilience.py - 14
app/main.py - 5
tests/test_reliability.py - 4
app/analysis.py, scripts/probe_endpoints.sh, tests/test_analysis.py - 3 each
tests/test_api.py - 2
app/obs.py, tests/test_upstream.py, tests/test_validation.py - 1 each

Why it wants care rather than speed

These are not decorative comments. The concentration in app/config.py, app/models.py, and app/resilience.py is where this service explains its context-budget arithmetic, route resolution, and fallback and circuit-breaker policy. That reasoning is the reason the reliability behavior is defensible, and #41 has not yet demonstrated LiteLLM parity, so it is still load-bearing.

The hook's own instruction is to move the explanation into docs/, not to delete it. Deleting would be the fast reading of a green build and the wrong one.

.ward/ward.yaml is the easiest starting point. Its 21 violations are a header block explaining the schema migration and the absence of a Makefile, which belongs in a doc that AGENTS.md already has a natural place to link.

Note

agentic-os hit this same file in aos-precommit-v0.16.0, which dropped the parked-config-block exclusion and brought its own .ward/ward.yaml under discipline. That change is a usable worked example for this one.

Exempted at pre-commit adoption in #87 so the suite could land green. The exemption is a listed `excludes` in `pyproject.toml` rather than a disabled hook, so **every file not on the list is governed now**, including all new ones. Each file drops off as it is cleaned. ## Where the violations are 96 total. The rule is that contiguous comment blocks stay at 2 lines, with longer explanations moved into `docs/`. * `app/config.py` - 22 * `.ward/ward.yaml` - 21 * `app/models.py` - 16 * `app/resilience.py` - 14 * `app/main.py` - 5 * `tests/test_reliability.py` - 4 * `app/analysis.py`, `scripts/probe_endpoints.sh`, `tests/test_analysis.py` - 3 each * `tests/test_api.py` - 2 * `app/obs.py`, `tests/test_upstream.py`, `tests/test_validation.py` - 1 each ## Why it wants care rather than speed These are not decorative comments. The concentration in `app/config.py`, `app/models.py`, and `app/resilience.py` is where this service explains its context-budget arithmetic, route resolution, and fallback and circuit-breaker policy. That reasoning is the reason the reliability behavior is defensible, and #41 has not yet demonstrated LiteLLM parity, so it is still load-bearing. The hook's own instruction is to move the explanation into `docs/`, not to delete it. Deleting would be the fast reading of a green build and the wrong one. `.ward/ward.yaml` is the easiest starting point. Its 21 violations are a header block explaining the schema migration and the absence of a Makefile, which belongs in a doc that `AGENTS.md` already has a natural place to link. ## Note `agentic-os` hit this same file in `aos-precommit-v0.16.0`, which dropped the parked-config-block exclusion and brought its own `.ward/ward.yaml` under discipline. That change is a usable worked example for this one.

coilyco-ops referenced this issue from a commit

2026-08-11 01:00:28 +00:00

chore: adopt the catalog pre-commit suite at aos-precommit-v0.18.0

coilyco-ops referenced this issue

2026-08-11 01:01:48 +00:00

Adopt the catalog pre-commit suite at aos-precommit-v0.18.0 #90

coilyco-ops referenced this issue from a commit

2026-08-12 10:54:15 +00:00

Expose the all-files pre-commit suite as a Ward verb

coilyco-ops referenced this issue

2026-08-12 10:54:36 +00:00

Expose the all-files pre-commit suite as a Ward verb #93