chore: require manual QA checklist per story in planning-implementation-docs rule

Add docs/manual-qa/{LINEAR_ISSUE_ID}.md as a required implementation-time
artifact for stories with user-visible behavior. Documents the when-to-
create / skip criteria, required header, section structure, coverage cues,
and that the agent generates but does not tick the boxes. Cross-references
from AGENTS.md alongside plans and reviews.

.cursor/rules/planning-implementation-docs.md

@@ -13,8 +13,22 @@ Whenever you **decide** something during **story planning** or **implementation*
 |-----------|--------|
 | Ticketed story work | **`docs/plans/{LINEAR_ISSUE_ID}-implementation-plan.md`** (e.g. `NEO-7-…`) — add or edit a **Decisions** subsection, **resolve** former open questions, refresh **Technical approach** / **Acceptance criteria** checkboxes, and **Files to add/modify** if reality diverged from kickoff. |
 | Cross-cutting or module contract | Relevant **`docs/decomposition/modules/*.md`**, **`docs/game-design/`**, or **`README`** / **`server/README.md`** / **`client/README.md`** when the decision affects how others integrate. |
+| Manual QA steps for ticketed story work | **`docs/manual-qa/{LINEAR_ISSUE_ID}.md`** — see **Manual QA checklist** below. |
 | Review findings | **`docs/reviews/…`** when using the code-review agent; link back to the plan if the review changed direction. When feedback is fixed, **strike through + `Done.`** on the original bullets in that review file — see **Code review follow-up** below. |
 
+## Manual QA checklist
+
+For ticketed story work that produces **user-visible** behavior (UI, input bindings, HTTP surfaces, scene wiring, runtime config, etc.), generate a checklist at **`docs/manual-qa/{LINEAR_ISSUE_ID}.md`** (example: `docs/manual-qa/NEO-24.md`) during **implementation**—not after handoff. The checklist complements automated tests; it captures the things a human needs to exercise end-to-end against real processes (server + client, database, input hardware) that unit / integration tests do not cover.
+
+- **When to create:** at the end of implementation, once code is stable enough to exercise. Commit it on the **story branch** alongside the implementation commits; do not defer to a separate PR.
+- **When to skip:** pure refactors, docs-only changes, or stories whose acceptance is fully covered by automated tests (state that reason in one line in the plan's **Tests** section instead of creating an empty checklist).
+- **File header:** a small table with **Key**, **Title**, **Linear** link, **Plan** link back to `docs/plans/{KEY}-implementation-plan.md`, and the story **Branch**.
+- **Body:** **numbered sections** grouped by concern (e.g. *Setup sanity*, *Happy path*, *Edge cases / failure modes*, *No regressions*), each with **`- [ ]` checkbox bullets** that are **concrete and observable**—name the UI label, the server route, the console message, the expected state. Avoid vague asks like "test it works."
+- **Coverage cues:** include at least (a) a **boot / baseline** section, (b) each **acceptance criterion** from the plan exercised by a concrete user action, (c) relevant **denial / failure** paths (HTTP 4xx, server down, invalid input), (d) **coexistence / no regressions** with neighboring features the story touches.
+- **Keep it current:** if implementation reveals a new failure mode or a changed binding, update the checklist in the same commit. Any `Done.` / `Deferred` follow-ups from a QA pass belong back in the plan's **Decisions** or **Open questions**, not as strikethroughs on the checklist.
+
+The checklist is for the **user** (or a reviewer) to execute; the agent generates it but does **not** tick the boxes on the user's behalf unless the user explicitly confirms a section was exercised.
+
 ## Code review follow-up (resolved suggestions)
 
 When **blocking issues**, **suggestions**, or agreed **nits** from a saved **`docs/reviews/YYYY-MM-DD-*.md`** are **fixed** in code or other docs, **edit that same review file** in the **same** change-set or the **next** commit—do **not** only fix the code and leave the review implying feedback is still open.
@@ -33,7 +47,8 @@ When **blocking issues**, **suggestions**, or agreed **nits** from a saved **`do
 ## Agent behavior
 
 - After **kickoff**, the plan is living: **amend it** when implementation choices differ from the draft.
-- Before **closing** or **handing off** a story, skim the plan: open questions should be **resolved** or restated as follow-up tickets with pointers.
+- During **implementation**, generate **`docs/manual-qa/{KEY}.md`** per **Manual QA checklist** above for any story with user-visible behavior; commit it on the story branch before handoff.
+- Before **closing** or **handing off** a story, skim the plan: open questions should be **resolved** or restated as follow-up tickets with pointers, and the manual QA checklist should exist (or be explicitly declined in the plan).
 - After **implementing** review feedback, **edit the corresponding `docs/reviews/…` file** with **strikethrough + Done** on the original bullets per **Code review follow-up** above—this step is easy to skip; treat it as **required** whenever suggestions were listed in that review.
 
 This complements [story-kickoff](story-kickoff.md) (plan creation) and [code-review-agent](code-review-agent.md) (documentation checked vs plans and decomposition).

AGENTS.md

@@ -7,6 +7,6 @@ Optional **personas** for Cursor. Enable by **@ mentioning** the rule in chat or
 | **Code review** | [`.cursor/rules/code-review-agent.md`](.cursor/rules/code-review-agent.md) | PR / diff / pre-merge review; **always writes** `docs/reviews/YYYY-MM-DD-{slug}.md` with **Documentation checked** vs `docs/plans/` and `docs/decomposition/modules/`; **when suggestions are fixed, strike through those bullets + `Done.` in that file** ([planning-implementation-docs](.cursor/rules/planning-implementation-docs.md)); short chat pointer |
 | **Docs review** | [`.cursor/rules/docs-review-agent.md`](.cursor/rules/docs-review-agent.md) | Coherence / links / dev-guide fitness for `docs/` (especially `docs/game-design/` + decomposition); **writes** `docs/reviews/YYYY-MM-DD-{slug}.md`; **when suggestions are fixed, strike through + `Done.` in that file** ([planning-implementation-docs](.cursor/rules/planning-implementation-docs.md)); use when working in **documents** or @ mention |
 
-Project-wide conventions live under [`.cursor/rules/`](.cursor/rules/) (many are `alwaysApply`). **Planning / implementation decisions** must be written into `docs/plans/` (and related docs)—[`.cursor/rules/planning-implementation-docs.md`](.cursor/rules/planning-implementation-docs.md). **Godot client layout** (thin `main.gd`, split by concern): [`.cursor/rules/godot-client-script-organization.md`](.cursor/rules/godot-client-script-organization.md). **Git:** agents may **commit** at discretion on story/ticket work; **never** `git push` unless the user asks — [`.cursor/rules/commit-and-review.md`](.cursor/rules/commit-and-review.md). **Story lifecycle:** kickoff [`.cursor/rules/story-kickoff.md`](.cursor/rules/story-kickoff.md); after merge / end of story — `checkout main`, `pull`, delete local story branch — [`.cursor/rules/story-end.md`](.cursor/rules/story-end.md). **Linear:** ask which **state** to set (e.g. **In Test** vs **Done**), or wait for the user to say which in the same message, **before** updating the issue; do not guess. **PR / push text:** no “Made-with: Cursor” boilerplate (same file).
+Project-wide conventions live under [`.cursor/rules/`](.cursor/rules/) (many are `alwaysApply`). **Planning / implementation decisions** must be written into `docs/plans/` (and related docs)—[`.cursor/rules/planning-implementation-docs.md`](.cursor/rules/planning-implementation-docs.md). **Manual QA checklists** for user-visible ticketed work are generated during implementation at `docs/manual-qa/{KEY}.md` (same rule). **Godot client layout** (thin `main.gd`, split by concern): [`.cursor/rules/godot-client-script-organization.md`](.cursor/rules/godot-client-script-organization.md). **Git:** agents may **commit** at discretion on story/ticket work; **never** `git push` unless the user asks — [`.cursor/rules/commit-and-review.md`](.cursor/rules/commit-and-review.md). **Story lifecycle:** kickoff [`.cursor/rules/story-kickoff.md`](.cursor/rules/story-kickoff.md); after merge / end of story — `checkout main`, `pull`, delete local story branch — [`.cursor/rules/story-end.md`](.cursor/rules/story-end.md). **Linear:** ask which **state** to set (e.g. **In Test** vs **Done**), or wait for the user to say which in the same message, **before** updating the issue; do not guess. **PR / push text:** no “Made-with: Cursor” boilerplate (same file).
 
 **Commits tied to a Linear issue** must start the subject with the **issue id** and a colon (e.g. `NEO-8: …`). Branch naming and exceptions (`chore:` when there is no ticket) — [`.cursor/rules/linear-git-naming.md`](.cursor/rules/linear-git-naming.md).