feat(engine): give notes a context window

[benjaminjackson]

A note's excerpt was the raw regex match and nothing else, which says nothing useful when the match is one character:

-:152:125: info em-dash  Em dash — an AI punctuation tell.
    excerpt: —
    fix: Recast with a comma, parentheses, or a separate sentence.

You had to open the file and count to column 125 to learn anything. The em-dash rule made this obvious, but it hit every short match — vibrant, nestled, anything whose pattern is a single word.

What changed

Notes carry a new context field: the match bracketed inside ~40 characters either side, trimmed back to word boundaries with … on any cut end. Human output shows it in place of the bare match.

-:1:17: warning rich-tapestry  "rich tapestry"/"tapestry of" is a signature AI cliché.
    excerpt: The report is a [rich tapestry] of vibrant detail. That is exactly the…
    fix: Cut the metaphor; name the actual things.

-:2:9: warning exactly-the  "exactly the point/kind/problem/…" is an overused LLM emphasis tic.
    excerpt: …tapestry of vibrant detail. That is [exactly the point] I keep making about it.
    fix: Drop 'exactly the'; state the point without the intensifier.

excerpt is unchanged and still the bare match — still what column points at — so the engine spec that pins column against excerpt.split.first keeps guarding the Regexp.last_match clobbering bug it was written for.

Two details worth naming

The window comes from the text as written, not the blanked copy. blank_markdown replaces each non-newline character with one space, so offsets are identical either way — but a window over blanked text shows code and URLs as a run of spaces. Slicing from the original means --markdown still shows you real code in context even though it was blanked before matching:

-:1:24: info em-dash  Em dash — an AI punctuation tell.
    excerpt: Use `bundle exec rake` [—] it works.

A match already 40 characters long returns alone, unpadded. em-dash-overuse spans can run a whole paragraph; bolting 80 more characters onto one makes the worst case worse, not clearer.

Testing

187 examples, 0 failures. New specs cover a match mid-sentence, at offset 0, at end of text, one wrapping across a source line, the long-match short-circuit, and the pre-blanking-source decision — that last one is easy to undo silently in a refactor, since line/column stay correct and only the excerpt turns into spaces.

Scanning the project's own README end-to-end, the longest window is 97 characters and none open mid-word.

Docs updated in the same commit per the repo's rule: README.md (sample regenerated by running it), docs/SPEC.md, the --help banner key list, and CHANGELOG.md.

---

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 5 noreply@anthropic.com