chore: require updating docs/reviews when review suggestions resolve

.cursor/rules/code-review-agent.md

@@ -80,6 +80,15 @@ Use this structure in **both** the saved document and (abbreviated if you want)
 
 In **chat only**, you may use Cursor line-number **code citations** when referencing existing code. For hypothetical fixes, use normal fenced code blocks everywhere.
 
+## Resolved suggestions (mandatory when feedback is addressed)
+
+If you **implement** changes that resolve **blocking issues**, **suggestions**, or agreed **nits** from an existing **`docs/reviews/…`** file for the same work:
+
+- **Edit that review document** in the same commit or the immediate follow-up commit: add or update **`## Resolved suggestions`** / **`## Follow-up`** per [planning-implementation-docs](planning-implementation-docs.md) **Code review follow-up**.
+- Do **not** ship code-only fixes while the saved review still reads as if those items were open.
+
+The **initial** review does not need an empty “Resolved” section; this rule applies when **closing the loop** after the review exists.
+
 ## Boundaries
 
 - Do **not** skip writing `docs/reviews/…`; the document is mandatory output of this agent.

.cursor/rules/commit-and-review.md

@@ -29,3 +29,7 @@ alwaysApply: true
 ## Scope
 
 - Applies to **all** commits the agent might make, including **documentation-only** changes (e.g. `docs/plans/`, `docs/reviews/`, README), not only application source.
+
+## Code review follow-up
+
+When commits **address** feedback from a saved **`docs/reviews/…`** file, include an update to **that review file** documenting what was resolved (or explicitly deferred/declined). See [planning-implementation-docs](planning-implementation-docs.md) **Code review follow-up** and [code-review-agent](code-review-agent.md) **Resolved suggestions**.

.cursor/rules/docs-review-agent.md

@@ -66,6 +66,10 @@ In the saved file, use **normal fenced code blocks** and **backtick paths** —
 
 **Chat:** Short summary + **path to** `docs/reviews/YYYY-MM-DD-{slug}.md`.
 
+## Resolved suggestions (mandatory when feedback is addressed)
+
+If later edits **address** **blocking issues**, **suggestions**, or **nits** from a **docs-review** `docs/reviews/…` file, **update that review file** with **`## Resolved suggestions`** / **`## Follow-up`** per [planning-implementation-docs](planning-implementation-docs.md) **Code review follow-up** (same audit trail as code reviews).
+
 ## Boundaries
 
 - Do **not** skip writing `docs/reviews/…` unless the user explicitly asks for **chat-only** (then state that exception in chat and **do not** claim full agent output).

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

@@ -15,6 +15,14 @@ Whenever you **decide** something during **story planning** or **implementation*
 | 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. |
 | Review findings | **`docs/reviews/…`** when using the code-review agent; link back to the plan if the review changed direction. |
 
+## 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, **update that review file** in the **same** change-set or the **next** commit on the story branch—do **not** only fix the code and leave the review implying feedback is still open.
+
+- Add or extend a section such as **`## Resolved suggestions`** or **`## Follow-up`**: for **each** item from the review that you addressed, record **what** changed and **where** (paths or commits). Match the review’s numbering or headings so readers can correlate.
+- Items **declined**, **out of scope**, or **deferred** to a ticket: state that in the same section so the audit trail is honest.
+- Applies to **any** agent pass that implements review feedback, not only a second invocation of the code-review agent—see [code-review-agent](code-review-agent.md) **Resolved suggestions**.
+
 ## What to capture
 
 - **What** was chosen (or rejected) and **why** in one short paragraph or bullets.
@@ -25,5 +33,6 @@ Whenever you **decide** something during **story planning** or **implementation*
 
 - 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.
+- After **implementing** review feedback, **edit the corresponding `docs/reviews/…` file** 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

@@ -4,8 +4,8 @@ Optional **personas** for Cursor. Enable by **@ mentioning** the rule in chat or
 
 | Agent | Rule file | When to use |
 |--------|-----------|-------------|
-| **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/`; 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`; use when working in **documents** or @ mention |
+| **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, update that review 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, update that review 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). **PR / push text:** no “Made-with: Cursor” boilerplate (same file).