07. Comments hygiene check (first end-to-end check)

meta: id: pygienium-07 feature: pygienium priority: P1 depends_on: [pygienium-06] tags: [check, e2e-reference]

objective:

Implement the comments hygiene check as the first full end-to-end check, serving as the reference pattern for the remaining checks: remove low-value comments, tighten verbose ones, keep "why" comments.

deliverables:

src/checks/comments.ts: a CheckDefinition with buildScanTask and buildFixTask
agents/comments-scanner.md and agents/comments-fixer.md (or reuse generic scanner/fixer with a check-specific rubric embedded in the task text)
Rubric encoded in task text: comments that restate code = remove; verbose narration = tighten; why comments = keep; self-explanatory code = no comment needed; short + high value
/pygienium-comments runs E2E: recon → agent scans for comment smells → (on --fix) agent edits → report of changes

steps:

Author the check definition: name comments, phaseId C1, allowedTools for analysis = read/bash/grep; for fix = read/edit/write/bash
Build scan task text instructing the agent to read candidates from recon, identify comment smells, write findings to pygienium/checks/comments/findings.md with per-file line refs
Build fix task text: apply safe removals/tightenings, leave why comments, write changes.md summarizing edits and anything needing human review
Register the check in index.ts via registerCheck
Implement gate(cwd): findings.md exists

tests:

Integration: create a temp file with restating comments + a why comment; run /pygienium-comments --fix; assert restating comments removed, why comment kept, changes.md present

acceptance_criteria:

validation:

notes:

This task proves the whole framework works; prioritize getting it green before 08-11
The rubric is the user's spec: short + high value; what-comments bad, why-comments good