Clear the comment-block backlog and drop its exemptions #95

Merged

coilysiren merged 1 commit from comment-block-discipline into main

2026-08-12 11:22:32 +00:00

coilyco-ops commented

2026-08-12 11:09:30 +00:00

Member

Closes #89.

The [tool.agentic-os.code-comments] exemption list in pyproject.toml is gone. Only the permanent .pre-commit-config.yaml entry remains — that file is generated by apply-agentic-os-hooks.py and its BEGIN/END markers are how the generator finds its own block on a re-run.

The shape of the work

The issue counted 96 violations; the hook now reports 98 (small drift since filing). But per-line failures overstate the job: an over-long block emits one failure per line past the second. 98 failures were 41 distinct blocks, and 17 of those were three-line section dividers — a rule line, a title, a rule line — which collapse to a single-line title with zero loss of meaning.

That left 17 blocks carrying real reasoning. Per the hook's own instruction those moved to docs/ rather than being deleted:

docs/ward-verbs.md — per-verb rationale, tower and daemon requirements, the empty security: policy. YAML turned out to have a stricter rule than Python: no comments below the top header at all, because a key-sorter would drift one away from the verb it describes. So every inline comment in .ward/ward.yaml had to move, not just the long ones.
docs/context-safety-settings.md — the num_ctx ceiling (#32), the OLLAMA_NUM_PARALLEL coupling (#33), and the delivered-context detection rule with both its outcomes.
docs/backend-catalog.md — /api/tags cache semantics, fail-open discovery, and why prompt measurement is deliberately approximate.

Each code site keeps a two-line comment naming the concept and pointing at the document. The context-budget arithmetic, route resolution, and fallback/circuit policy the issue flagged as load-bearing are all preserved — moved, not lost.

Two judgement calls worth flagging

Test comments were compressed, not relocated. The detail in tests/ is about why a specific assertion exists, which is most useful next to the assertion. Each is now a two-line comment that keeps the claim and drops the restatement. Nothing moved to docs/ from tests/.

The doc split was forced by #88's caps. context-safety-settings.md landed at 3741 of 4000 permitted chars. The catalog and token-measurement notes therefore went into a second file rather than a third section of the first, which would have breached the cap and simply added a new entry to #88's backlog. Both new documents sit under the 80-line and 4000-char limits.

Verification

pre-commit run code-comments --all-files — 0 failures with the backlog exemptions removed
pre-commit run --all-files — every hook passes
pytest 258 passed · ruff · black · mypy all clean
New docs are linked from README.md and from each other; dead-cross-links passes, so no pointer added here dangles

Note on overlap

This touches .ward/ward.yaml and README.md, which #93 also touches, in different regions (#93 adds verbs and a Development note; this rewrites the header comment and adds to the Planning index). They should merge cleanly in either order, but worth knowing if you are sequencing merges.

Closes #89. The `[tool.agentic-os.code-comments]` exemption list in `pyproject.toml` is gone. Only the permanent `.pre-commit-config.yaml` entry remains — that file is generated by `apply-agentic-os-hooks.py` and its BEGIN/END markers are how the generator finds its own block on a re-run. ## The shape of the work The issue counted 96 violations; the hook now reports 98 (small drift since filing). But per-line failures overstate the job: an over-long block emits one failure per line past the second. **98 failures were 41 distinct blocks**, and 17 of those were three-line section dividers — a rule line, a title, a rule line — which collapse to a single-line title with zero loss of meaning. That left 17 blocks carrying real reasoning. Per the hook's own instruction those moved to `docs/` rather than being deleted: - **`docs/ward-verbs.md`** — per-verb rationale, tower and daemon requirements, the empty `security:` policy. YAML turned out to have a stricter rule than Python: *no* comments below the top header at all, because a key-sorter would drift one away from the verb it describes. So every inline comment in `.ward/ward.yaml` had to move, not just the long ones. - **`docs/context-safety-settings.md`** — the `num_ctx` ceiling (#32), the `OLLAMA_NUM_PARALLEL` coupling (#33), and the delivered-context detection rule with both its outcomes. - **`docs/backend-catalog.md`** — `/api/tags` cache semantics, fail-open discovery, and why prompt measurement is deliberately approximate. Each code site keeps a two-line comment naming the concept and pointing at the document. The context-budget arithmetic, route resolution, and fallback/circuit policy the issue flagged as load-bearing are all preserved — moved, not lost. ## Two judgement calls worth flagging **Test comments were compressed, not relocated.** The detail in `tests/` is about why a specific assertion exists, which is most useful next to the assertion. Each is now a two-line comment that keeps the claim and drops the restatement. Nothing moved to `docs/` from `tests/`. **The doc split was forced by #88's caps.** `context-safety-settings.md` landed at 3741 of 4000 permitted chars. The catalog and token-measurement notes therefore went into a second file rather than a third section of the first, which would have breached the cap and simply added a new entry to #88's backlog. Both new documents sit under the 80-line and 4000-char limits. ## Verification - `pre-commit run code-comments --all-files` — **0 failures with the backlog exemptions removed** - `pre-commit run --all-files` — every hook passes - `pytest` 258 passed · `ruff` · `black` · `mypy` all clean - New docs are linked from `README.md` and from each other; `dead-cross-links` passes, so no pointer added here dangles ## Note on overlap This touches `.ward/ward.yaml` and `README.md`, which #93 also touches, in different regions (#93 adds verbs and a Development note; this rewrites the header comment and adds to the Planning index). They should merge cleanly in either order, but worth knowing if you are sequencing merges.

coilyco-ops added 1 commit

2026-08-12 11:09:31 +00:00

Clear the comment-block backlog and drop its exemptions

ci / smoke (pull_request) Successful in 6s

Details

ci / quality (pull_request) Successful in 22s

Details

aea146880b

Removes the agent-proxy#89 exemption list from pyproject.toml. Only the
permanent .pre-commit-config.yaml entry remains, because that file is generated
by apply-agentic-os-hooks.py and its BEGIN and END markers are how the generator
finds its own block.

98 violations across 13 files reduced to 41 distinct comment blocks, then to
zero. Two thirds of them were 3-line section dividers - a rule line, a title,
a rule line - which collapse to a single-line title with no loss of meaning.

The rest carried real reasoning, so per the hook's own instruction it moved to
docs/ rather than being deleted:

* docs/ward-verbs.md - per-verb rationale, tower and daemon requirements, and
  the empty security policy. YAML has the stricter rule: no comments at all
  below the top header, since a key-sorter would drift one away from its verb.
* docs/context-safety-settings.md - the num_ctx ceiling, the NUM_PARALLEL
  coupling, and the delivered-context detection rule.
* docs/backend-catalog.md - /api/tags cache semantics, fail-open discovery, and
  why prompt measurement is deliberately approximate.

The context-budget arithmetic, route resolution, and fallback policy the issue
flagged as load-bearing are all preserved. Each site keeps a two-line comment
naming the concept and pointing at the document.

Both new documents sit under the 80-line and 4000-char layout caps. The
catalog and token-measurement notes went into a second file rather than a
third section of the first, which would have breached the char cap.

closes #89

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-12 11:09:31 +00:00