fix(check-new-line-breaks): scope from the working tree when dirty and report the examined count (#825)

[d-morrison]

Closes #825.

check-new-line-breaks.py scoped its check with git diff <base>...HEAD (committed only) and then read line content from the working tree, so a run before committing reported clean about lines it never examined. Recorded five times in Morrison-Lab/ai-config (latest ai-config#2542, which carries the reproducer).

What changes

• Working-tree-aware scope. NLB_SCOPE=auto|worktree|committed (default auto). In auto, a dirty tree (tracked changes, staged or unstaged, that the globs match and the ignore patterns do not exclude) scopes the diff from the explicit merge base against the working tree; a clean tree keeps the committed-only scope CI relies on. The merge base is resolved once with git merge-base, so a stale base does not widen the diff in either scope.
• Untracked files cannot be seen by git diff, so they do not widen the scope; the run prints a ::warning:: naming untracked files that match the globs and telling the user to git add them.
• Search-space line. Examined N added line(s) across M file(s) (scope: committed|working tree). precedes the verdict, so a run that examined nothing is visibly different from a clean run.
• Docstrings state that line content is always read from the working tree, so forcing committed on a dirty tree can desync; CLAUDE.md's passage on the local run is rewritten to describe the fix rather than the limitation.

Tests

check-new-line-breaks/tests/: 99 to 110 passing. New cases cover the uncommitted violation (with the committed case as control), staged-but-uncommitted, untracked (warns, does not widen), clean dirty tree and clean committed tree examined counts, the empty diff, explicit NLB_SCOPE=committed on a dirty tree, and the merge-base anchor under an advancing base in both scopes, each with a naive-diff sibling assertion proving the control would flag without the anchor.

The ai-config#2542 reproducer now exits 1 on the uncommitted state and 1 on the committed control.

Review provenance

Implemented by a sonnet subagent; two agy --print adversarial rounds (seven implementation findings, then three test-quality findings), all addressed. Pushed with ALLOW_UNREVIEWED_PUSH=1 because those reviews came from a separate CLI rather than a subagent, one of the guard's named override cases.

Consumer follow-up: bump scripts/vendor/gha-check-new-line-breaks.pin in ai-config once this merges.

🤖 Generated with Claude Code

[d-morrison]

Round at 2fb827fb, addressing the review of a687dfbc and the one red check:

• Missing changelog fragment --- Addressed. changelog.d/check-new-line-breaks-worktree-scope.fixed.md describes the NLB_SCOPE knob, the dirty-tree scope, the untracked-file warning, and the examined-count line, citing check-new-line-breaks: a diff-scoped run before committing cannot fail; scope from the working tree when dirty and report the examined count #825 and this PR.
• one-function-per-file red --- Addressed. The script carried 18 helper functions before this PR and gained five more; the changed-file scan flags it now that the diff touches it. It now carries the # check-one-function-per-file: allow-multiple marker the check names, which is how check-one-function-per-file.py itself opts out. The whole-repo local run no longer lists this file.

Posted by Claude Code (AI agent) --- not written by a human.

[d-morrison]

Round at 6c18993b, addressing the review of 2fb827fb and the two red checks:

• Changelog fragment packs several sentences on one line --- Addressed. The bullet is re-broken at clause boundaries like its sibling fragments. Both new-line-breaks and diff-scoped-guard were red on that same line, so one fix covers both.

Measured while fixing it: with the fragment edited but not yet committed, this branch's own checker reported Examined 56 added line(s) across 2 file(s) (scope: working tree). and then No lines missing semantic breaks., which is the behaviour #825 asks for; on main the same pre-commit run would have examined nothing.

Posted by Claude Code (AI agent) --- not written by a human.

[github-actions]

Claude finished review — View run

---

This matches what the prior rounds already reviewed — this round's actual delta is just the two commits in the computed range (the changelog fragment reflow, plus a merge commit). No other files changed.

The fix is verified correct: reflowing the fragment across ten lines at clause boundaries resolves the semantic-line-breaks violation flagged in the prior round, confirmed by re-running the exact reproduction command from that review (NLB_GLOBS='*.md *.qmd' NLB_SCOPE=committed NLB_BASE_REF=origin/main python3 check-new-line-breaks/check-new-line-breaks.py), which now reports "No lines missing semantic breaks." The full test suite still passes (110 passed). No new files or logic changed in this range beyond the fragment itself.

Review

Scope of this round: commits 6c18993 (reflow the #825 changelog fragment at clause boundaries) and the merge commit 1f4d2f8, closing the range 2fb827f..1f4d2f8. This addresses the prior round's sole finding — the fragment's self-inflicted new-line-breaks CI failure.

Verification performed:

• Reproduced the prior round's failing command against the new fragment content: now passes clean (No lines missing semantic breaks, 47 lines examined across 2 files).
• Confirmed the fragment's prose content is byte-identical in meaning to the pre-fix version — only line breaks changed, at clause/sentence boundaries, matching the style of sibling fragments (e.g. nlb-moved-content-exemption.fixed.md).
• Re-ran python3 -m pytest check-new-line-breaks/tests/ -q → 110 passed, unchanged.
• Confirmed no other file changed in this range (git diff --stat 2fb827f 1f4d2f8 touches only the fragment).

No new findings. This closes the last two rounds' issues in sequence: round 1 flagged the missing changelog fragment (fixed in c2ccbaa), round 2 flagged that fragment's own line-length violation (fixed in 6c18993, this round). Both fixes verified by direct reproduction rather than by inspection alone.

Verdict

Ready for merge — both prior findings are resolved and verified by reproduction; no new issues found in this round's diff.

Structured Review Data (JSON)

{
  "schema_version": "1.1",
  "reviewer": "claude",
  "commit_sha": "1f4d2f865797ad0620bed9d7f881fd1030417798",
  "verdict": "CLEAN",
  "findings": [],
  "detailed_assessment": "The changelog.d/check-new-line-breaks-worktree-scope.fixed.md fragment was reflowed at clause boundaries across 10 lines, verified to pass the new-line-breaks check via direct reproduction of the exact command that previously failed it.",
  "holistic_assessment": "Both prior rounds' findings (missing changelog fragment, then that fragment's own semantic-line-break violation) are now closed in sequence, the full test suite remains green at 110 passed, and no other file changed in this round's diff range."
}

Reviewed commit: 6c18993

[github-actions]

💰 Cost: $0.7400 (review) — run