AGENTS.md

1# src/hooks/comment-checker/ (AI Slop Comment Blocker)
2 
3**Generated:** 2026-07-17 (7d664b96b)
4 
5## OVERVIEW
6 
7Tool Guard tier hook. Runs after `write`/`edit` tools to detect AI-generated comment patterns in code and block them before they land. Backed by `@code-yeongyu/comment-checker` binary (trusted dependency).
8 
9## WHAT IT BLOCKS
10 
11AI slop comment smells:
12- Restating what code literally does (`// increment counter`)
13- Filler phrases (`// obviously`, `// clearly`, `// simply`)
14- Decorative separators without purpose
15- JSDoc on trivially-named functions
16- `// TODO:` without context
17- Comments contradicting surrounding code
18 
19See `@code-yeongyu/comment-checker` for the authoritative blocklist.
20 
21## EXECUTION FLOW
22 
23```
24tool.execute.before (write | edit | multiedit)
25  → register pending call (filePath + old/new strings) keyed by callID
26tool.execute.after (same callID, or apply_patch)
27  → take pending call (or extract apply_patch edits from metadata)
28  → resolve comment-checker CLI path (node_modules / PATH / cached download)
29  → run CLI on changed content, parse JSON findings (line ranges + category)
30  → if findings → inject tool-level error → agent must fix
31```
32 
33## KEY FILES
34 
35| File | Purpose |
36|------|---------|
37| `hook.ts` | `createCommentCheckerHooks()`: main factory. `tool.execute.before` registers pending calls; `tool.execute.after` runs the CLI check. Accepts an optional `cliRunner` for dependency injection (defaults to `cli-runner.ts` exports) |
38| `cli-runner.ts` | CLI orchestration: resolve path, `processWithCli` / `processApplyPatchEditsWithCli`, per-session dedup, run lock |
39| `cli.ts` | Resolve `comment-checker` binary path (node_modules / PATH / cached download), spawn `runCommentChecker` |
40| `downloader.ts` | Download + cache the binary (`getCachedBinaryPath`, `ensureCommentCheckerBinary`) |
41| `initialization-gate.ts` | `ensureCommentCheckerInitialization()`: run CLI init once |
42| `pending-calls.ts` | Pending-call registry between `tool.execute.before` and `after` (TTL cleanup) |
43| `types.ts` | `PendingCall` and config types |
44 
45## CONFIG
46 
47```jsonc
48// .omo/omo.jsonc
49{
50  "comment_checker": {
51    "enabled": true,      // default: true
52    "severity": "error"   // error blocks, warning notifies only
53  }
54}
55```
56 
57Disable via `"disabled_hooks": ["comment-checker"]`.
58 
59## BYPASS FOR LEGITIMATE COMMENTS
60 
61Prefix with `// @allow` or mark file scope with `// comment-checker-disable-file` at top. Use sparingly; it defeats the purpose.
62 
63## RELATED
64 
65- Doctor check: `src/cli/doctor/checks/tools.ts` verifies `comment-checker` binary availability
66- Postinstall: `postinstall.mjs` downloads binary if missing
67