docs: design for Harper grammar actions — replacement & ignore (TASK-044)

@@ -0,0 +1,102 @@
+# Harper grammar actions — replacement & ignore (TASK-044)
+
+## Goal
+
+Make glint's green grammar underlines actionable. On a grammar span at the cursor
+(Alt+;) or under a click, offer Harper's fix suggestions as replacement rows in the
+existing proofing popup, plus an Ignore action. Selecting a replacement applies
+Harper's edit to the buffer; Ignore suppresses that lint for the session.
+
+Builds on TASK-043, which renders diagnostics only. Reuses the spell popup
+(`spellOption`/`applySpell`) plumbing.
+
+## Findings from live harper-ls 2.6 probe
+
+These facts drove the design and narrowed scope:
+
+1. **Replacement works.** `textDocument/codeAction` for a diagnostic's range returns
+   quickfix `CodeAction`s: a Harper-authored `title` (e.g. `Replace with: "an"`) plus
+   `edit.changes[uri]` = `[{range, newText}]`. Each also carries a `HarperRecordLint`
+   telemetry command we ignore. The response also includes bare `Command` objects
+   `{command:"HarperIgnoreLint", arguments:[uri, lint], title:"Ignore Harper error."}`.
+2. **HarperIgnoreLint is a no-op over LSP.** Executing the command harper returns
+   (verbatim args) yields `null` and never drops the lint — no changed re-publish after
+   `didChange`, nothing written to `~/.config/harper-ls/ignored_lints/`. So ignore must
+   be implemented glint-side.
+3. **Add-to-dictionary is never offered for grammar lints** (spelling-only concept).
+   Dropped from scope.
+4. **Config reply bug.** glint answers `workspace/configuration` with bare `{}`, causing
+   harper's `ERROR: Settings must contain a "harper-ls" key.`. Reply must be
+   `{"harper-ls": {}}`. Harmless to diagnostics but fixed here.
+
+## Scope
+
+In: grammar-span replacement suggestions; client-side session ignore; the config fix.
+Out: add-to-dictionary for grammar; persistent (cross-launch) ignore; executing
+HarperIgnoreLint.
+
+## Design
+
+### grammar package
+
+- **Request/response correlation.** Add `pending map[int]chan json.RawMessage` guarded by
+  a mutex. In `readLoop`, the response case (`method=="" && id present`) routes the result
+  to `pending[id]` if registered, else keeps the existing initialize-ready signal.
+- **`CodeActions(path string, line, startRune, endRune int) ([]Action, error)`** — converts
+  the rune range to UTF-16 using the client's tracked doc lines, sends
+  `textDocument/codeAction`, waits on the reply channel with a ~400ms timeout, parses the
+  result into `[]Action`. Only actions carrying an `edit` become replacement Actions; their
+  TextEdit ranges are mapped UTF-16 → rune coords. Bare-command actions (ignore) are not
+  returned — ignore is glint-side. Dedup replacement Actions by title.
+- **Types:**
+  ```go
+  type Action struct { Title string; Edits []TextEdit } // replacement
+  type TextEdit struct { StartLine, StartCol, EndLine, EndCol int; NewText string } // rune coords
+  ```
+- **Config reply** wraps each configuration item as `{"harper-ls": {}}`.
+- `runeColToUTF16(line, col)` helper (inverse of existing `utf16ToRuneCol`).
+
+Synchronous `CodeActions` (blocking ≤400ms) is acceptable: user-initiated, rare, harper is
+local. readLoop runs in its own goroutine, so the Update-thread block resolves without
+deadlock.
+
+### editor package
+
+- **`GrammarSpanAt(row, col) (start, end int, ok bool)`** — the rune range of the grammar
+  underline covering `col`, from `grammarDiags[row]`.
+- **`ReplaceRuneRange(startRow, startCol, endRow, endCol int, s string)`** — general range
+  replacement (grammar fixes are single-line in practice; support multi-line for safety).
+- **Grammar session ignore:** `grammarIgnores map[string]struct{}` keyed by
+  `code + "\x00" + flaggedText`. `IgnoreGrammar(code, text string)` adds; a filter drops any
+  incoming diag whose `(code, buffer-substring at its range)` is in the set. Mirrors spell's
+  `IgnoreWord`. Because the key is content-based, it survives edits that move the span.
+
+### app package
+
+- Extend `spellKind` with `grammarFix` (replacement) rows; the popup for a grammar span is
+  built from `CodeActions` results + an `i Ignore` row + the existing `g Grammar` toggle.
+- `spellOption` gains a way to carry an `Action` (edits) for `grammarFix`.
+- `openSpellPopupAt`: spell word wins (existing check first); else if `GrammarSpanAt` hits,
+  request `CodeActions`, build the grammar popup. Store the span (row,start,end) + rule code
+  + flagged text for the Ignore action.
+- `applySpell`: `grammarFix` → `editor.ReplaceRuneRange` for each edit (reverse doc order);
+  ignore → `editor.IgnoreGrammar(code, text)` + re-filter current batch so the underline
+  clears immediately.
+- `spellBar` labels the new rows (`1 …`, `i Ignore`, `g Grammar`).
+
+## Testing (TDD)
+
+- grammar: UTF-16↔rune round-trip; codeAction JSON → `[]Action` parse (edits mapped, bare
+  commands excluded, dedup by title); request/response correlation; config reply shape.
+  Gated live test: real harper returns a replacement Action for "a a".
+- editor: `GrammarSpanAt` hit/miss/boundary; `ReplaceRuneRange` single & multi-line;
+  grammar-ignore filter drops matching diag, keeps others, content-keyed across an edit.
+- app: grammar-span popup lists replacements + ignore; applying a fix mutates the buffer;
+  ignore clears the underline; spell still wins when a word is both.
+
+## Acceptance criteria (revised)
+
+- [x] Grammar span at cursor offers Harper's fix suggestions in the Alt+; popup
+- [x] Selecting a fix applies harper's replacement to the buffer
+- [x] Ignore removes the grammar underline (glint-side session ignore, not HarperIgnoreLint)
+- [ ] ~~Add-to-dictionary~~ — dropped: harper offers no add-to-dict for grammar lints