feat: edit-time comment gate — scope/block-all, narration/density heuristics + PostToolUse hook

[robdmoore]

What & why

Morphs the ideas from jackawatts/claude-comment-gate into @makerx/verify's comment tooling, re-expressed in our AST-based, cross-agent TS architecture. The comments check gains real heuristics and an edit-time gate so an agent gets back-pressure the moment it writes a low-value comment — not just at verify/CI time.

The comments check — two axes + a strictness dial

• Scope — --scope diff (default: only comments on changed lines) or --scope all (whole codebase).
• Strictness — heuristics (default), --block-all (every non-exempt comment fails), or, at its strictest, --block-all --no-context-override (a no-comments-at-all, JSDoc-only policy). --block-new-comments is the alias for --scope diff --block-all.
• context: override — context:-prefixed comments are exempt by default; --no-context-override (config comments.contextOverride: false) disables that, judging them like any other comment. Useful for a stricter gate or to drive a context: cleanup. When disabled, all output goes context-free: the reports drop their "prefix with context:" lines and --pushback swaps to a strict variant that offers no escape.

Heuristics (JSDoc / context: / machine directives exempt): long blocks, narration (session narration + LLM punctuation tells), density (comment share of the lines in scope, with a net-trim guard).

Example invocations

# Default: gate the current diff — long blocks, narration, density (context:/JSDoc/machine directives exempt)
verifyx comments --pushback

# Audit the whole codebase, not just the diff
verifyx comments --scope all --pushback

# Block every comment introduced on changed lines (context:/JSDoc still allowed) — the old --block-new-comments
verifyx comments --block-all              # == --scope diff --block-all
verifyx comments --block-new-comments     # alias

# Zero-comment policy across the whole repo, JSDoc only (no context: escape)
verifyx comments --scope all --block-all --no-context-override

# Stricter heuristics on the diff: no context: escape, tighter density, narration only
verifyx comments --no-context-override --comment-density 0.2
verifyx comments --comment-density 0            # disable density; keep blocks + narration

# Drive a context: cleanup — surface every context: comment as if it were any other
verifyx comments --scope all --no-context-override

# Edit-time hook (reads the PostToolUse payload on stdin; wired up by init)
echo "$TOOL_JSON" | verifyx comments-hook

# Scaffolding presets
verifyx init                                    # interactive: scope + 3-way strictness prompts
verifyx init --yes --comment-scope all          # non-interactive, whole-repo scope
verifyx init --yes --comment-strict             # no-comments/JSDoc-only preset (block-all + no-context-override)

Edit-time PostToolUse hook (verifyx comments-hook)

Reads the Claude Code tool payload on stdin (Write/Edit/MultiEdit; no git), scans only the text the edit introduced, and on a violation writes the canonical pushback to stderr and exits 2 — surfaced to the agent in the same turn. Honours contextOverride (context-free feedback when disabled).

Scaffolding & remediation (verifyx init)

• Registers the hook, and drops a prune-comments skill + a comments-only-when-non-obvious rule (keep/delete criteria + worked examples).
• Prompts for the comment gate's scope and a 3-way strictness (heuristics / block-all / strict-no-comments), baking the flags into the scaffolded verify:comments script; also --comment-scope, --comment-block-all, --comment-strict.
• Monorepo-safe: writes to the nearest existing .claude (cwd → nearest ancestor within 3 levels, never past the git root → cwd), with --claude-dir to override, and prints where it landed.

Config (verify.config.json#comments)

scope, blockAll, narration, density, minAddedLines, contextOverride, ignore.

Divergences from claude-comment-gate (deliberate)

• Language coverage: TS/JS/YAML only (TS compiler API), vs his ~18 languages (bash prefix-matching).
• Hook input: we parse the tool payload (exact edit, incl. MultiEdit, no git/jq); his re-derives via git diff HEAD of the file.

Testing

• npm run verify green (all checks + tests + lint + format + types + knip + duplicate-code), including the gates running against this PR's own diff.
• Unit tests cover scope diff/all, block-all, punctuation tells, density net-trim, the context: opt-out (check + hook), payload parsing, the .claude resolver, and the init flag/preset emission.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR extends the built-in comments check from a single long-block heuristic into a two-axis gate (scope: diff|all, strictness: heuristics vs --block-all) and adds an edit-time Claude PostToolUse hook (verifyx comments-hook) that rejects low-value comments immediately after Write/Edit/MultiEdit operations.

Changes:

• Expand verifyx comments to support diff/all scoping, narration detection, comment-density gating, and --block-all (with --block-new-comments as an alias).
• Add a Claude PostToolUse hook pipeline (payload parsing + added-text analysis + CLI command) and scaffold/init support for writing hook/settings + new skills/rules.
• Add templates + generated .claude/ artifacts and update documentation/tests to cover the new behavior.

Reviewed changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
templates/skills/prune-comments/SKILL.md	Adds a remediation skill template for pruning low-value comments.
templates/rules/comments-only-when-non-obvious.md	Adds a rule template defining when comments are justified vs noise.
src/shared/diff.ts	Adds parsing of removed diff lines to support density net-trim logic.
src/shared/config.ts	Extends verify config schema for comments scope/strictness/heuristics tuning.
src/shared/comment-scan.ts	Refactors comment scanning to accept source text (enables hook scanning).
src/scaffold/init.ts	Adds init flags and wiring for comment gate options and hook installation.
src/scaffold/init.test.ts	Tests init script emission for comment gate options.
src/scaffold/claudeSettings.ts	Implements idempotent merge into .claude/settings.json for PostToolUse hook.
src/scaffold/claudeSettings.test.ts	Tests settings merge/idempotence/unparseable handling.
src/scaffold/claudeDir.ts	Adds monorepo-safe resolution of the target .claude directory.
src/scaffold/claudeDir.test.ts	Tests .claude resolution rules (ancestor search + git root cap + override).
src/scaffold/agentFiles.ts	Scaffolds new prune-comments skill and comment rule into agent integrations.
src/report.ts	Adds reporting for block-all, narration, and density violations; exports PUSHBACK.
src/hook/payload.ts	Parses Claude PostToolUse payloads and extracts added text for scanning.
src/hook/payload.test.ts	Tests payload parsing across tool variants and edge cases.
src/hook/analyze.ts	Runs comment heuristics against added text and formats hook feedback.
src/hook/analyze.test.ts	Tests hook analysis behavior (narration/blocks/density/exemptions/blockAll).
src/comments.ts	Exposes findLongCommentBlocksInContent for reuse by diff/hook analyzers.
src/commands/registerInit.ts	Adds init prompts/flags for comment scope/strictness and hook, plus reporting.
src/commands/registerCommentsHook.ts	Adds hidden CLI command implementing the PostToolUse hook.
src/commands/registerChecks.ts	Updates comments command flags/help and forwards new options into the check.
src/cli.ts	Registers the new comments-hook command with the CLI.
src/checks/registry.ts	Updates the registry description for the enhanced comments check.
src/checks/comments.ts	Reworks the comments check around scope/strictness + narration/density heuristics.
src/checks/comments.test.ts	Adds hermetic diff mocking and new test coverage for narration/density/block-all behavior.
src/checks/comment-heuristics.ts	Introduces narration detection and density computation utilities.
src/checks/comment-heuristics.test.ts	Adds unit tests for narration/density logic.
src/checks/comment-common.ts	Centralizes comment exemption logic, scanned extensions, and comment-line helpers.
src/checks/comment-collect.ts	Adds diff/all collection pipeline for candidates used by all comment gates.
README.md	Documents new comments gate axes, flags, config, hook behavior, and remediation assets.
.claude/skills/prune-comments/SKILL.md	Adds repo-local Claude skill for pruning low-value comments.
.claude/settings.json	Adds repo-local Claude PostToolUse hook configuration.
.claude/rules/comments-only-when-non-obvious.md	Adds repo-local Claude rule for when comments are justified.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.