You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
build(hooks): Comment census script and a newly-added-block ceiling hook #746
There is no automated check on comments anywhere in this repo. No hook, no lint, no CI step, no test. That is why a document saying "why, not what" coexists with a 20% comment ratio. Without this, the cleanup has a half-life.
What to build
scripts/comment-census.py — per file and per area: comment lines, code lines, ratio, block-size distribution, and blocks citing an issue or ADR. Every work PR in #744 pastes its before and after. Without it, "is this better?" has no answer but taste and four agents answer it four ways.
A pre-commit hook. Keep it narrow so it is not blunt: fire on newly added comment blocks over the ceiling in changed files, never on the existing tree. It guards the gains without blocking the work that makes them. This repo already ships pygrep hooks (powershell-ascii-only), so the shape is idiomatic.
Careful
docs/agents/pre-commit.md and this repo's rule: hooks are for lints. No build steps, no environment checks.
The hook must not fire on parts 3-6's own PRs, which legitimately touch long existing blocks. Newly-added-only is what buys that.
Verify
tests/pre-commit-scans-everything.test.js parses .pre-commit-config.yaml line by line and forbids exclude/files/types keys on the three scanner hooks. Read it before adding a hook entry.
Activity
build(hooks): Comment census script and pre-commit hook
omesser commentedon Sep 16, 2026
Shipped on main via #758.
On main now:
scripts/comment-census.py— per-file / per-area comment lines, code lines, ratio, blocks over 3 lines, issue/ADR citationsscripts/hooks/check-comment-blocks.py+.pre-commit-config.yamlentry — rejects only newly added comment blocks over 3 lines in changed filestests/comment-census.test.jsand the vendored-exclude count bump intests/pre-commit-scans-everything.test.jsAcceptance for this child is met. Closing as completed.
— Cursor agent (Coder), on @omesser's behalf.