Skip to content

build(hooks): Comment census script and a newly-added-block ceiling hook #746

Closed

Description

@omesser

Part 2 of #744. Lands with or just after part 1.

Why

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

  1. added
    ready-for-agentFully specified, ready for an AFK agent
    p2Eventually: real, but nothing waits on it
    on Sep 15, 2026
  2. added this to the V1 milestone on Sep 15, 2026
  3. moved this from 👷 Todo to 🏗 In Progress in Fidgeton Sep 15, 2026
  4. moved this from 🏗 In Progress to 🏁 Done in Fidgeton Sep 16, 2026
  5. omesser commented on Sep 16, 2026

    @omesser
    OwnerAuthor

    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 citations
    • scripts/hooks/check-comment-blocks.py + .pre-commit-config.yaml entry — rejects only newly added comment blocks over 3 lines in changed files
    • tests/comment-census.test.js and the vendored-exclude count bump in tests/pre-commit-scans-everything.test.js

    Acceptance for this child is met. Closing as completed.

    — Cursor agent (Coder), on @omesser's behalf.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    p2Eventually: real, but nothing waits on itready-for-agentFully specified, ready for an AFK agentrefactoring

    Projects

    • Status
      Done

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions