From ced9936414a557093ac6b294ac364fff6b2f131a Mon Sep 17 00:00:00 2001
From: VinPropane <don@donmail.org>
Date: Sun, 5 Apr 2026 00:05:42 -0400
Subject: [PATCH] chore: add story-end rule (main, pull, delete local branch)

---
 .cursor/rules/git-workflow.md  |  2 ++
 .cursor/rules/story-end.md     | 35 ++++++++++++++++++++++++++++++++++
 .cursor/rules/story-kickoff.md |  2 ++
 AGENTS.md                      |  2 +-
 4 files changed, 40 insertions(+), 1 deletion(-)
 create mode 100644 .cursor/rules/story-end.md

diff --git a/.cursor/rules/git-workflow.md b/.cursor/rules/git-workflow.md
index d7db2b6..75f5337 100644
--- a/.cursor/rules/git-workflow.md
+++ b/.cursor/rules/git-workflow.md
@@ -14,3 +14,5 @@ alwaysApply: true
 - **Code or implementation changes** — Use a **branch**, then merge to `main` when ready. **Commit subjects must start with the Jira key** when the work maps to an issue (e.g. `NS-14: …`). See [jira-git-naming](jira-git-naming.md). This includes application source (**C#**, **GDScript**), Godot scenes and project files, `docker-compose.yml`, `.csproj` / build config, CI workflows, **JSON/YAML game data** under `content/`, and JSON Schema when it ships with data pipelines—not standalone doc prose.
 
 When a change mixes documentation and code, treat it as a **code change** (use a branch). Per-story implementation plans are part of the story branch, not an exception for `main`.
+
+After the PR for a story branch is **merged**, clean up locally per [story-end](story-end.md) (`checkout main`, `pull`, `branch -d`).
diff --git a/.cursor/rules/story-end.md b/.cursor/rules/story-end.md
new file mode 100644
index 0000000..96603c8
--- /dev/null
+++ b/.cursor/rules/story-end.md
@@ -0,0 +1,35 @@
+---
+description: When a Jira story is finished (merged or abandoned locally), return to main, pull, delete the local story branch
+alwaysApply: true
+---
+
+# Story end (Jira)
+
+When the user **ends story work** on a ticketed branch—phrases like “end story”, “story is merged”, “clean up branch after NS-…”, or they confirm the PR is **merged** to `main`—run this **git** sequence so local state matches the remote default branch.
+
+## 1. Preconditions
+
+- **Merged:** Prefer deleting the local branch only after **`main`** on the remote includes the story (PR merged). If the PR is **not** merged, `git branch -d` will refuse; use **`git branch -D`** only when the user explicitly wants to drop unmerged work.
+- **Uncommitted changes:** Stash, commit, or discard before switching branches; do not leave a dirty tree without the user’s choice.
+
+## 2. Steps (run in order)
+
+1. **`git checkout main`**
+2. **`git pull origin main`** (or `git pull` if `main` already tracks `origin/main` and that is correct for this repo)
+3. **`git branch -d <story-branch>`** — use the branch that was used for the issue (first path segment should be the Jira key, e.g. `NS-19-move-validation`). If Git reports “not fully merged”, **stop** and tell the user; do not `-D` unless they ask.
+
+## 3. What not to do
+
+- Do **not** delete **`main`** or **`origin/*`**.
+- Do **not** assume the remote story branch should be deleted unless the user asks (many teams keep `origin/NS-…` for history or delete via GitHub UI).
+
+## 4. Jira (optional)
+
+- If the issue should move to **Done** (or equivalent), use Atlassian MCP when available; otherwise the user updates the board. This rule does **not** require Jira transitions.
+
+## Related
+
+- [story-kickoff](story-kickoff.md) — start of story workflow  
+- [git-workflow](git-workflow.md) — branch vs `main`  
+- [jira-git-naming](jira-git-naming.md) — branch names  
+- [commit-and-review](commit-and-review.md) — push only when the user requests it
diff --git a/.cursor/rules/story-kickoff.md b/.cursor/rules/story-kickoff.md
index 436dcb9..8d88a65 100644
--- a/.cursor/rules/story-kickoff.md
+++ b/.cursor/rules/story-kickoff.md
@@ -54,3 +54,5 @@ These three lists (**files to add**, **files to modify**, **tests**) must **alwa
 ## 5. After the plan
 
 - Implement only after the user confirms. All implementation commits stay on the **same story branch** from step 1b; follow [git workflow](git-workflow.md).
+
+When the story is **done** and merged to `main`, follow [story-end](story-end.md) to return to `main`, pull, and remove the local story branch.
diff --git a/AGENTS.md b/AGENTS.md
index c9d0ef6..5eb55e8 100644
--- a/AGENTS.md
+++ b/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/`; 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 |
 
-Project-wide conventions live under [`.cursor/rules/`](.cursor/rules/) (many are `alwaysApply`). **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` — [`.cursor/rules/commit-and-review.md`](.cursor/rules/commit-and-review.md). **PR / push text:** no “Made-with: Cursor” boilerplate (same file).
+Project-wide conventions live under [`.cursor/rules/`](.cursor/rules/) (many are `alwaysApply`). **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).
 
 **Commits tied to a Jira issue** must start the subject with the **issue key** and a colon (e.g. `NS-17: …`). Branch naming and exceptions (`chore:` when there is no ticket) — [`.cursor/rules/jira-git-naming.md`](.cursor/rules/jira-git-naming.md).