Multi-line block comments don't fire markers

open   by a73x

Labels: backlog

[claude 2026-04-29] v1 limitation surfaced during manual smoke and discussion.

## What's broken

Markers in multi-line block comments are silently ignored. Examples:

```js
/*
 * @claude refactor this function
 * to use the visitor pattern
 */
```

```html
<!--
  @claude add aria-labels to
  every interactive element below
-->
```

The scanner only matches single-line comments and single-line block comments (open and close on the same line). See \`internal/scanner/scanner.go\`: the loop checks each line independently. Multi-line block-comment spans never get a chance to be evaluated as marker text.

## Why it bites users

A user trying a multi-line ask sees no response and has no diagnostic — looks identical to "the watcher didn't notice my save."

## Two ways to fix

### A. State machine (recommended for v1.1)

Track \`/* ... */\` and \`<!-- ... -->\` open/close across lines per-language. When a span closes, evaluate its accumulated body for an \`@claude\` marker. Stamping inserts the UUID after the first \`@claude\` token within the span (single-line or multi-line).

- ~50 lines added to \`internal/scanner\`, no new dependencies
- Handles realistic usage (block comments not nested inside string literals)
- Edge case: \`@claude\` inside a string that happens to look like a comment open/close → wrong fire. Cost is one false positive that Claude reads and ignores.

### B. Tree-sitter (defer)

Per-language grammar gives proper "is this a comment?" AST nodes including multi-line spans.

- ~30 MB binary growth from grammars
- CGO (or wasm) — breaks pure-Go cross-compile, adds runtime cost
- Per-scan parse cost is real on hot saves
- Only earns its weight if we *also* want AST-aware behavior (stamp at end of function body, scope reads to the symbol the marker refers to, etc.) — not needed for "find @claude inside a comment"

## Recommendation

Ship A as v1.1. Revisit B in a v2 that does something genuinely AST-aware.

## Files involved

- \`internal/scanner/scanner.go\` — \`Scan()\` line loop, \`blockCommentDelims\` table
- \`internal/scanner/scanner_test.go\` — needs new tests for multi-line spans across the existing supported block-comment languages (CSS, HTML, XML, MD)
- \`internal/rewriter/rewriter.go\` — \`stampLine\` already operates on a single line; for multi-line, the stamping target is the line where \`@claude\` appears within the span, so existing logic should work without changes. Worth verifying with a test.