docs: codify the agent-ready issue standard

AGENTS.md

@@ -79,6 +79,10 @@
 - Review PRs from code, tests, linked issues, comments, and check results — let
   those, rather than the title or labels alone, drive every merge, close,
   harvest, or defer decision on community work.
+- Triage issues toward the agent-ready standard in
+  `docs/AGENT_READY_ISSUES.md`: maintainer-authored bodies get restructured
+  into executable specs with verified anchors; community-authored issues get a
+  maintainer deconstruction comment instead of a body rewrite.
 - Respect concurrent work in the tree — leave unrelated edits by other people or
   agents intact.
 

docs/AGENT_READY_ISSUES.md

@@ -0,0 +1,106 @@
+# Agent-Ready Issues
+
+CodeWhale's tracker is worked by humans and by autonomous agents. An issue is
+**agent-ready** when a fresh agent — with a clone of `main`, shell/read/write
+tools, and *no other context* — can execute it end-to-end and prove the result.
+This document defines that standard for new issues, for triage reworks of
+existing issues, and for maintainer replies on community threads.
+
+The filing-time version of this standard is the
+[Agent task issue form](../.github/ISSUE_TEMPLATE/agent-task.yml). This page
+extends it to the rest of the tracker.
+
+## Source of truth
+
+- The **active milestone** decides what lane an issue is in. Version labels
+  (`v0.9.2`, `v0.9.3`, …) are historical metadata; they never choose or change
+  a milestone.
+- The **issue body** is the executable spec. Refinements that arrive as
+  comments get folded into the body during triage so the body never lies.
+- Queue order within a lane (from `AGENTS.md`): release blockers, recently
+  approved PRs, clean small PRs, blocked PRs with obvious fixes, safely
+  harvestable dirty PRs, then larger architecture work.
+
+## Required structure
+
+```markdown
+## Problem
+2–6 sentences. What is wrong or missing, and why it matters now.
+
+## Current evidence
+Verified anchors and observed behavior, e.g.
+`crates/tui/src/model_routing.rs::provider_router_candidates`.
+
+## Scope
+Numbered steps; one concrete action per step, file paths where known.
+
+## Key files
+One verified path per line. The executing agent reads these first.
+
+## Acceptance criteria
+Behavior-level `- [ ]` checkboxes. Every item must be testable.
+
+## Verification
+Exact commands, e.g.
+`cargo test -p codewhale-tui --bin codewhale-tui --locked <filter>`.
+
+## Out of scope
+What this issue deliberately does not change.
+
+## Related
+Real issue/PR numbers only, each with one line on the boundary between them.
+```
+
+Epics additionally get a `## Phases` section: each phase sized as one
+agent-executable slice with its own acceptance bullet. An epic without phases
+is not agent-ready.
+
+## Anchor discipline
+
+- Every file path, symbol, config key, and command in an issue body must be
+  verified against the current tree before it is written down. `rg`/`ls`
+  first, then cite.
+- If something cannot be located, write
+  `(anchor not found — needs discovery)` rather than a guess. A wrong anchor
+  costs an executing agent more than a missing one.
+- Verification commands use real workspace package names
+  (`codewhale-tui`, `codewhale-config`, `codewhale-protocol`, …) — confirm in
+  the crate's `Cargo.toml`, not from memory.
+
+## Reworking existing issues
+
+- **Maintainer-authored issues**: restructure the body in place. Preserve
+  every constraint and concrete fact from the original; fold in refinements
+  from comments; end the body with a dated triage note, e.g.
+  `_Triage note: body restructured for agent execution on YYYY-MM-DD; prior
+  comment refinements folded in. Original wording preserved in edit history._`
+- **Community-authored issues**: never rewrite the reporter's body. Post a
+  maintainer comment carrying the same skeleton instead — status in the lane,
+  what a fix looks like (anchored bullets + acceptance criteria), and the
+  smallest set of asks that unblocks the issue.
+- Apply the `agent-ready` label only when the body (or, for community issues,
+  body + maintainer deconstruction comment) genuinely meets this standard.
+  The label is a gate, not a wish.
+
+## Community thread etiquette
+
+- Open with specific thanks that references a real detail of the report —
+  proof it was read. Vary phrasing across issues.
+- State status honestly: milestone lane, what already shipped (cite the
+  version, PR, or commit — only with evidence), and what is blocking.
+- Never claim testing or reproduction that did not happen; never promise
+  dates. "Queued in the v0.9.2 release lane" is the honest formulation.
+- Reporters writing in Chinese (or another language) get the key points and
+  asks translated at the end of the English reply.
+- `needs-info` issues get exactly one crisp ask (typically
+  `codewhale --version`, `codewhale doctor --json`, OS + terminal, minimal
+  repro), plus a pointer that the stale policy in
+  [ISSUE_TRIAGE.md](./ISSUE_TRIAGE.md) applies once a maintainer labels the
+  issue `needs-info`.
+
+## Why this exists
+
+A deconstructed issue is cheap to execute and cheap to verify: the researcher
+pays the discovery cost once, at triage time, instead of every executing agent
+paying it again. When an issue is agent-ready, "pick up the next item in the
+milestone" becomes a safe instruction for any contributor — human or agent.

docs/ISSUE_TRIAGE.md

@@ -1,5 +1,10 @@
 # Issue Triage
 
+Triage aims issues at the agent-ready standard defined in
+[AGENT_READY_ISSUES.md](./AGENT_READY_ISSUES.md): bodies that a fresh agent
+can execute without extra context. This page covers the stale/`needs-info`
+lifecycle that runs alongside that standard.
+
 ## Stale `needs-info` cleanup
 
 The stale workflow only acts on issues that a maintainer has explicitly labeled

docs/KEYBINDINGS.md

@@ -163,7 +163,8 @@ tmux's `load-buffer -w` path when running inside tmux.
 
 ## v0.8.29 audit notes
 
-- **`Shift+Enter` / `Alt+Enter` newlines now work in VSCode on Windows (#1359).** crossterm's `PushKeyboardEnhancementFlags` command unconditionally returns `Unsupported` on Windows (`is_ansi_code_supported() == false`), so the Kitty keyboard protocol escape was never written to the terminal. Without it, VSCode's xterm.js stays in legacy mode where `Shift+Enter` is indistinguishable from plain `Enter`, causing the composer to send the message instead of inserting a newline. The fix writes the push/pop escapes (`\x1b[>1u` / `\x1b[<1u`) directly on Windows, bypassing crossterm's capability gate. VSCode integrated terminal and Windows Terminal ≥1.17 both honour the Kitty keyboard protocol; terminals that do not understand the sequences silently discard them.
+- **`Shift+Enter` / `Alt+Enter` newlines now work in VSCode on Windows (#1359).** crossterm's `PushKeyboardEnhancementFlags` command unconditionally returns `Unsupported` on Windows (`is_ansi_code_supported() == false`), so the Kitty keyboard protocol escape was never written to the terminal. Without it, VSCode's xterm.js stays in legacy mode where `Shift+Enter` is indistinguishable from plain `Enter`, causing the composer to send the message instead of inserting a newline. The fix wrote the push/pop escapes (`\x1b[>1u` / `\x1b[<1u`) directly on Windows, bypassing crossterm's capability gate. VSCode integrated terminal and Windows Terminal ≥1.17 both honour the Kitty keyboard protocol; terminals that do not understand the sequences silently discard them.
+  - *Superseded:* current builds probe the protocol without enabling any flags on Windows — `push_keyboard_enhancement_flags` in `crates/tui/src/tui/ui.rs` writes `\x1b[>0u` (flag value `0`), so modified keys are no longer delivered CSI-u-encoded; newline chords are decoded per terminal via `is_composer_newline_key`.
 
 ## v0.8.13 audit notes