fix: code-review: skip generated sources in the scanned file set

[bborbe]

/coding:code-review currently excludes files by path only:

grep -v -E '(^|/)(vendor|node_modules|dist|build|coverage|\.git)/'

Generated code does not live in those directories. It sits in ordinary package paths — k8s/client/, mocks/, zz_generated.deepcopy.go — so all of it is scanned, adjudicated, and refuted.

Why it matters

Findings in generated files are unactionable by construction: the file says DO NOT EDIT, regeneration reverts any change, and a genuine defect belongs upstream in the generator rather than in the repo under review.

Measured on bborbe/backup during a whole-codebase review on 2026-08-10:

• 97 of 553 findings came from 25 client-gen files under k8s/client/** plus the mocks/ tree
• 44+ of the 102 findings that survived triage and reached adjudicators were refuted for no reason other than "the file is generated" — the largest single adjudication cost on that repo

Adjudication is the expensive tier: it spawns specialist agents that read real code. This is pure waste, and it recurs on every repo with k8s clients or counterfeiter mocks.

The fix

A content-marker filter after the existing path filter:

while IFS= read -r f; do
  head -25 "$f" | grep -q 'Code generated .* DO NOT EDIT' || echo "$f"
done < /tmp/code-review-filelist.txt > /tmp/code-review-files.txt
mv /tmp/code-review-files.txt /tmp/code-review-filelist.txt

head -25, not head -1 or head -3 — placement varies by generator. counterfeiter emits the marker on line 1; client-gen emits a licence header first and the marker on line 4. A 3-line check finds the mocks/ files and misses every client-gen file, which is exactly what happened when I first measured this and briefly read a zero result as good news.

Scope

commands/pr-review.md is deliberately unchanged. It is diff-scoped, and a PR that regenerates mocks or clients arguably should surface those files — the same exclusion is not obviously correct there. Worth a separate decision.

make precommit green (225 tests, 30 checks).

[ben-s-pull-request-reviewer]

Now let me perform the Step 4c-sel CLASSIFY in-session. I have all inputs needed:

DIFF: CHANGELOG.md (+4 lines) and commands/code-review.md (+15 lines)

CANDIDATES from Step 4b-i:

• agent-cmd/command-frontmatter — trigger commands/**/*.md → matches commands/code-review.md
• agent-cmd/command-thin — trigger includes commands/**/*.md → matches
• agent-cmd/gap-driven-feedback / agent-cmd/no-user-prompts / agent-cmd/scripts-in-claude-dir / agent-cmd/single-source-of-truth — all trigger on commands/**/*.md
• changelog/conventional-prefix-required — trigger CHANGELOG.md → matches

Step 4c-sel CLASSIFY (recall contract: "INCLUDE if a reasonable reviewer would want to read this rule before judging"):

Rule	applies_when	Decision	Reason
agent-cmd/command-frontmatter	"any commands/*.md file is created"	SKIPPED	applies_when: file CREATED — this is a modification, not creation
agent-cmd/command-thin	"any new commands/*.md file is added or substantially changed"	SKIPPED	applies_when targets NEW files — no new command file added; substantial-change interpretation requires judgment beyond scope
agent-cmd/gap-driven-feedback	"an agent depends on documented information that may be incomplete"	SKIPPED	applies_when not triggered — no agent gap introduced
agent-cmd/no-user-prompts	"performs work that could prompt the user"	SKIPPED	applies_when not triggered — head+grep are non-interactive
agent-cmd/scripts-in-claude-dir	"an agent depends on executable scripts"	SKIPPED	applies_when not triggered — this is a doc change, no new script dependency
agent-cmd/single-source-of-truth	"agent's domain has multiple data sources"	SKIPPED	applies_when not triggered — not about data-source conflicts
changelog/conventional-prefix-required	"bullet under ## Unreleased does not start with conventional prefix"	APPLICABLE	changelog entry is fix: code-review: ... — fix: is in the allowed set

Citation check on applicable rule: changelog/conventional-prefix-required id exists in rules/index.json ✓

Step 4d-sel ADJUDICATE: For changelog/conventional-prefix-required, the ## Unreleased entry reads:

- fix: code-review: skip generated sources when building the scanned file set — ...

Prefix fix: is in the allowed set (feat:, fix:, refactor:, test:, docs:, chore:, perf:) — no violation found.

Mechanical funnel: Pre-filled result was findings_count: 0 with errors: [] — no citations to validate.

Short-circuit check: Applicable set is non-empty (1 rule) but produced no violations; mechanical findings are empty. Selector result: clean.

---

Step 5: Consolidated Report

Selector Mode Traceability:

• Candidates: 7 rules matched by Step 4b-i glob filter
• Applicable: 1 rule selected by Step 4c-sel
• Skipped (6 rules):
  • agent-cmd/command-frontmatter → applies_when: file created, this is edit
  • agent-cmd/command-thin → applies_when: new file added, not created here
  • agent-cmd/gap-driven-feedback → no agent gap introduced
  • agent-cmd/no-user-prompts → no interactive prompts introduced
  • agent-cmd/scripts-in-claude-dir → no script dependency introduced
  • agent-cmd/single-source-of-truth → not a data-source conflict

Must Fix (Critical)

None.

Should Fix (Important)

None.

Nice to Have (Optional)

None.

Notes:

• The two concerns from the plan's ## Plan section were both considered:
  1. Grep pattern regex (Code generated .* DO NOT EDIT) — within single-quoted single-quote in bash, the . is literal and .* is a basic regex match; correctly matches generator output including client-gen files with multi-line headers. No issue found.
  2. File readability before pipe (head -25 "$f" | grep -q) — files unreadable by head are silently excluded; this is the documented design of the new step (unreadable files are dropped from the scanned file set as unavailable to scan), not a defect. No issue found.
  3. Performance of while/read loop — the document explicitly acknowledges this trade-off: generated code has no path signature, so individual file inspection is required. Intentional design, not a bug.

---

Step 6 & 7

No test coverage gaps found; no manual review issues. Cleanup not needed (working tree was already at PR head, no worktree created).

---

Verdict

{
  "verdict": "approve",
  "summary": "PR adds a well-documented generated-source filter step to the code-review command. The changelog entry uses the correct `fix:` conventional prefix. All judgment rules are either inapplicable or pass. The mechanical funnel found zero findings. No issues to address.",
  "comments": [],
  "concerns_addressed": [
    "correctness: grep pattern 'Code generated .* DO NOT EDIT' uses literal . in single-quoted bash string — matches expected generator formats including client-gen multi-line headers",
    "correctness: head/grep pipe silently excludes unreadable files — this is the intentional design of the new step, not a defect",
    "performance: while/read loop spawns head+grep per file — documented trade-off since generated files have no path signature; intentional design"
  ]
}