jepegit · jepegit · Apr 19, 2026 · Apr 19, 2026
diff --git a/.cursor/commands/issue-close.md b/.cursor/commands/issue-close.md
@@ -34,7 +34,7 @@ Other optional notes still apply: branch name, PR title, draft PR, skip issue do
    - Before staging, run `git status` to list all modified/untracked files. If any changes are **not relevant** to this issue, tell the user which ones and ask whether to include them in this commit or leave them for later. Do not silently drop or include unrelated changes.
    - Unless told to commit all, stage the right files (avoid unrelated changes). Include `pyproject.toml` (and `uv.lock` if it changed) when a version bump ran.
    - Write a commit message that states what changed and why in normal sentences.
-   - Make sure you have pulled the last changes from the default branch (e.g. `main`) and check for and fix merge conflicts.
+   - Sync with the default branch before pushing: run `git fetch --prune` then `git pull --ff-only` from the default branch (e.g. `main`) merged into the issue branch (or rebase, per project preference). Use `--ff-only` so unrelated work never gets merged in silently; if it refuses, stop and ask how to reconcile. Check for and fix merge conflicts.
 
 5. **Push**
    - Push your branch to `origin` (or the remote you use).
@@ -43,12 +43,18 @@ Other optional notes still apply: branch name, PR title, draft PR, skip issue do
    - Open a PR against the default branch (e.g. `main`).
    - Describe the change, how to test it, and link the GitHub issue (e.g. `Closes #123` or `Refs #123` in the PR body).
 
-7. **Branch reminder**
-   - After the PR is created, remind the user that the working copy is still on the issue branch, not the default branch (e.g. `main`).
-   - Suggest they run `git switch main` (or the repo's default) before starting any unrelated work, so new changes don't accidentally land on the issue branch.
+7. **Post-merge branch cleanup**
+   - Detect the default branch (prefer `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`; fall back to `git symbolic-ref --quiet --short refs/remotes/origin/HEAD | sed 's|^origin/||'`, else `main`).
+   - Detect merge status of this PR with `gh pr view <branch> --json state,mergedAt,mergeCommit,headRefName`. If `gh` is unavailable, approximate with `git fetch --prune` followed by `git rev-list <branch>..origin/<default>` and `git cherry origin/<default> <branch>` (all commits marked `-` means squash-merged).
+   - **If the PR is merged:**
+     - Ask once whether to run the standard post-merge cleanup. On yes, run: `git switch <default> && git pull --ff-only && git fetch --prune`. These are non-destructive because the issue branch is already merged.
+     - List local branches whose tip is already reachable from `origin/<default>` (including squash-merged ones detected via `git cherry`). Present them as a single group and ask **once** (one consolidated yes/no listing every branch) before running `git branch -d <branch>` for each. Never use `-D` automatically; if `-d` refuses, report the branch and stop touching it.
+   - **If the PR is not yet merged:**
+     - Remind the user that the working copy is still on the issue branch, not the default branch. Suggest `git switch <default>` before starting any unrelated work so new changes don't accidentally land on the issue branch. Tell them to re-run `/issue-close` after the PR merges so the post-merge cleanup actually runs.
 
 8. **After review**
    - Address feedback, push updates, and merge when approved and CI is green.
+   - Re-run `/issue-close` after the merge to pick up the post-merge cleanup in step 7.
 
 ## Output
 

diff --git a/.cursor/commands/issue-init.md b/.cursor/commands/issue-init.md
@@ -21,6 +21,7 @@ The text after this slash command is the **issue reference**. It may also be **e
        - Ask: "You have not provided an issue reference. Should I use issue #NN from the current branch `<branchname>`?" (use the real branch name).
        - If the user **confirms**, treat `NN` as the issue number and continue with the bullets under **B** as if the user had typed only `NN`.
        - If the user **declines** or is **unclear**, ask for an issue number, full URL, or `owner/repo`, and do not proceed until you have a clear reference.
+       - **Archived-issue guard:** if files for issue `NN` are already present under `.issueflows/02-partly-solved-issues/` or `.issueflows/03-solved-issues/`, warn the user that the issue is archived and require a second, explicit confirmation before re-opening it in `.issueflows/01-current-issues/`.
      - Else (branch does not match that pattern): **do not guess.** Ask the user for an issue number, full GitHub issue URL, or `owner/repo/#number`, and do not proceed until they provide it.
    - **B. You have a concrete issue reference** (from user input or from **A** after confirmation):
      - If the reference is a full URL, extract `owner`, `repo`, and `issue number`.
@@ -36,6 +37,11 @@ The text after this slash command is the **issue reference**. It may also be **e
    - number
    - and confirm resolved `owner/repo`
 
+2.5. **Branch status preflight** (report only; do not block and do not delete anything).
+   - Run `git fetch --prune` so tracking info is fresh.
+   - Report: current branch, clean/dirty working tree, and ahead/behind counts vs `origin/<default>` (detect default via `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`, else `git symbolic-ref --quiet --short refs/remotes/origin/HEAD`, else `main`).
+   - If the current branch matches `^(\d+)-.+` and files for that issue now live under `.issueflows/02-partly-solved-issues/` or `.issueflows/03-solved-issues/`, note that the branch looks stale. Do not delete or move anything at this step.
+
 3. Archive existing issue files already in `.issueflows/01-current-issues` (except the current issue number).
    - Inspect issue groups by issue number (for example `issue121_*` belongs to issue 121).
    - Consider all files for that issue in `.issueflows/01-current-issues` (original + status/supplementary files) as one group to move together.

diff --git a/.cursor/commands/issue-start.md b/.cursor/commands/issue-start.md
@@ -9,6 +9,23 @@ If additional input is added, use that for further detailed guidance
 
 0. If the issue markdown file is not present, or it is ambiguous which one to select, ask. Could it be that the user has not run the /issue-init command?
 
+0.5 **Branch status preflight** (non-destructive — report, do not delete).
+   - Detect the default branch: `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`. If `gh` is unavailable, use `git symbolic-ref --quiet --short refs/remotes/origin/HEAD | sed 's|^origin/||'`, else fall back to `main`.
+   - Run `git fetch --prune` so tracking info is fresh.
+   - Report: current branch, clean/dirty working tree (`git status --porcelain`), and ahead/behind counts vs `origin/<default>` (`git rev-list --left-right --count origin/<default>...HEAD`).
+   - Classify the current branch:
+     - On default (`main`/`master`/etc.): propose switching to or creating an issue branch before implementing, e.g. `git switch -c <N>-<short-slug>` where `N` is the focus issue number. Ask before running.
+     - Matches `^(\d+)-.+`: treat the leading digits as issue number `N`. Cross-check `.issueflows/01-current-issues/`, `.issueflows/02-partly-solved-issues/`, and `.issueflows/03-solved-issues/`. If `issueN_*` is already under `02-partly-solved-issues/` or `03-solved-issues/`, warn that the branch looks stale and ask whether to switch back to default before continuing. Never delete a branch from `/issue-start`.
+     - Any other branch name: warn that the branch does not look like an issue branch and ask whether to continue on it.
+
+0.6 **Sweep stale current issues** (auto-safe file moves — no destructive git).
+   - Group files in `.issueflows/01-current-issues/` by issue number (`issueNN_*`).
+   - For every group **other than the focus issue**:
+     - If any status markdown for that group contains `- [x] Done` (case-insensitive on `done`), move the whole group to `.issueflows/03-solved-issues/`.
+     - Otherwise, move the whole group to `.issueflows/02-partly-solved-issues/`.
+   - Never move the focus issue's own files.
+   - Report every move (source -> destination, grouped by issue number) in the opening summary.
+
 1. Plan. If not in plan mode, stop and ask for a confirmation.
 
 2. Check that the plan is not too broad. If too broad, ask if it should be split into several parts.

diff --git a/.cursor/rules/issueflow-rules.mdc b/.cursor/rules/issueflow-rules.mdc
@@ -84,3 +84,17 @@ If the issue is fully resolved (no additional subtasks present), move the origin
 ### Scripts that can help us when working on issues
 
 If you want, you can put small scripts etc. that you have made and think could be useful in the future in our llm tools folder: `.issueflows/00-tools`. Also, feel free to use the tools in our llm tools folder if you find someone that could be useful.
+
+
+### Branch hygiene
+
+- Do issue work on an **issue branch** named like `<N>-<short-slug>`, not on the default branch.
+- Before starting or continuing work on an issue branch, run `git fetch --prune` and check where the branch sits relative to `origin/<default>` (ahead/behind). A branch that is "several commits ahead" after a merged PR usually means the PR was squash-merged and the local branch is stale.
+- **Assume squash-merges on GitHub.** After a PR merges: switch to the default branch, `git pull --ff-only`, `git fetch --prune`, and delete the local issue branch with `git branch -d <branch>` (never `-D` automatically). `/issue-close` does this with a single consolidated confirm.
+- If an issue is already archived under `.issueflows/02-partly-solved-issues` or `.issueflows/03-solved-issues`, the matching local branch is stale; don't resume work on it silently — switch back to the default branch and, if the issue really needs re-opening, do it deliberately through `/issue-init` (which will ask for a second confirmation).
+
+
+### Folder hygiene for `.issueflows/01-current-issues`
+
+- Only the **focus issue** (the one currently being worked on) should live in `.issueflows/01-current-issues`.
+- `/issue-init` and `/issue-start` both sweep that folder automatically: every `issue<n>_*` group **other than the focus issue** is moved to `.issueflows/03-solved-issues` if a status file contains `- [x] Done`, otherwise to `.issueflows/02-partly-solved-issues`. Keep status files accurate so the sweep routes them correctly.
diff --git a/.cursor/skills/issueflow-issue-close/SKILL.md b/.cursor/skills/issueflow-issue-close/SKILL.md
@@ -35,15 +35,17 @@ When a bump applies: read `.cursor/skills/issueflow-version-bump/SKILL.md`, run
 
 4. **Commit** — First check `git status`; if there are unrelated uncommitted changes, surface them and ask the user whether to include them — do not auto-include or drop silently. Then stage intentionally (include `pyproject.toml` and `uv.lock` if changed after a bump); write a commit message in full sentences describing what changed and why.
 
-5. **Branch hygiene** — Ensure the branch is up to date with the default branch where appropriate; resolve merge conflicts before pushing.
+5. **Branch hygiene before push** — Run `git fetch --prune`, then sync with the default branch using `git pull --ff-only` (rebase or merge per project preference). Use `--ff-only` so unrelated history never gets pulled in silently; if it refuses, stop and ask how to reconcile. Resolve merge conflicts before pushing.
 
 6. **Push** — Push to the remote the project uses (typically `origin`).
 
 7. **Pull request** — Open (or update) a PR against the default branch. Body should explain the change, how to test, and link the GitHub issue (`Closes #n` / `Refs #n`).
 
-8. **Branch reminder** — After opening the PR, tell the user the working copy is still on the issue branch (not the default branch like `main`). Suggest switching back with `git switch main` before starting unrelated work so new changes don't land on the issue branch.
+8. **Post-merge branch cleanup** — Detect the default branch (prefer `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`; fall back to `git symbolic-ref --quiet --short refs/remotes/origin/HEAD`, else `main`). Detect merge status with `gh pr view <branch> --json state,mergedAt,mergeCommit,headRefName`. If `gh` is unavailable, approximate with `git fetch --prune` + `git cherry origin/<default> <branch>` (all commits marked `-` means squash-merged).
+   - **If merged:** ask once whether to run the standard cleanup. On yes: `git switch <default> && git pull --ff-only && git fetch --prune`. Then list every local branch whose tip is already reachable from `origin/<default>` (including squash-merged ones) and ask **once** (one consolidated yes/no listing every branch) before running `git branch -d <branch>` for each. Never use `-D` automatically; if `-d` refuses, report the branch and leave it alone.
+   - **If not yet merged:** remind the user the working copy is still on the issue branch (not the default). Suggest `git switch <default>` before starting unrelated work, and tell them to re-run `/issue-close` after the PR merges so the post-merge cleanup runs.
 
-9. **Output** — Summarize commit, push result, and PR URL, or the next blocker.
+9. **Output** — Summarize commit, push result, PR URL, and (when applicable) which local branches were deleted during post-merge cleanup. If blocked, report the next step.
 
 ## Constraints
 

diff --git a/.cursor/skills/issueflow-issue-init/SKILL.md b/.cursor/skills/issueflow-issue-init/SKILL.md
@@ -24,10 +24,13 @@ Follow this skill when the user wants to **capture a GitHub issue locally** usin
    - **URL** — Parse `owner`, `repo`, issue number.
    - **Number only** — Use `git remote get-url origin` (HTTPS or SSH) to derive `owner/repo`. If parsing fails, ask for a full URL or `owner/repo`.
    - **Empty / whitespace** — Run `git branch --show-current`. If empty or `main`/`master` (case-insensitive), **stop** and ask for a number, URL, or `owner/repo/#n`. If the branch matches `^\d+-.+`, ask once whether to use that leading issue number; do not proceed without a clear yes/no.
+   - **Archived-issue guard** — Before writing, check `.issueflows/02-partly-solved-issues/` and `.issueflows/03-solved-issues/` for existing `issue<n>_*` files. If the issue is already archived, warn and require a second explicit confirmation before re-opening it in `.issueflows/01-current-issues/`.
 
 3. **Fetch** — `gh issue view <n> --repo owner/repo --json title,body,url,number`. On failure, report the error and suggest `gh auth login`.
 
-4. **Archive** — In `.issueflows/01-current-issues/`, group files by issue number (`issue121_*`). For each group **other than** the issue being created: move the whole group to `.issueflows/03-solved-issues/` only if a status file for that issue contains a checked **Done** line matching `- [x] Done` (case-insensitive on “done”). Otherwise move to `.issueflows/02-partly-solved-issues/`. If no status file or checkbox is unclear, treat as **not done**.
+3.5 **Branch status preflight** (report only) — Run `git fetch --prune`. Report current branch, clean/dirty working tree, and ahead/behind counts vs `origin/<default>` (detect default via `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`, else `git symbolic-ref --quiet --short refs/remotes/origin/HEAD`, else `main`). If the current branch matches `^(\d+)-.+` and files for that issue already live in `.issueflows/02-partly-solved-issues/` or `.issueflows/03-solved-issues/`, note that the branch looks stale. Never delete or move anything at this step.
+
+4. **Archive** — In `.issueflows/01-current-issues/`, group files by issue number (`issue121_*`). For each group **other than** the issue being created: move the whole group to `.issueflows/03-solved-issues/` only if a status file for that issue contains a checked **Done** line matching `- [x] Done` (case-insensitive on "done"). Otherwise move to `.issueflows/02-partly-solved-issues/`. If no status file or checkbox is unclear, treat as **not done**.
 
 5. **Write** — Create `.issueflows/01-current-issues/issue<number>_original.md` with:
 

diff --git a/.cursor/skills/issueflow-issue-start/SKILL.md b/.cursor/skills/issueflow-issue-start/SKILL.md
@@ -20,20 +20,25 @@ Follow this skill when the user wants to **begin implementation** from issue not
 
 1. **Select the issue** — Read `.issueflows/01-current-issues/`. If there is no `*_original.md` (or multiple ambiguous groups), **stop** and ask which issue to use.
 
-2. **Plan first** — Produce a concrete plan (steps, files touched, tests). If you are **not** in plan mode, **stop and ask for explicit confirmation** before implementing, per the command definition.
+2. **Branch status preflight** (non-destructive) — Detect the default branch (prefer `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`, else `git symbolic-ref --quiet --short refs/remotes/origin/HEAD`, else `main`). Run `git fetch --prune`. Report current branch, clean/dirty working tree, and ahead/behind counts vs `origin/<default>`. If on the default branch, propose creating an issue branch (`git switch -c <N>-<short-slug>`); ask before running. If the current branch matches `^(\d+)-.+` and files for that issue now live in `.issueflows/02-partly-solved-issues/` or `.issueflows/03-solved-issues/`, warn the branch looks stale and ask whether to switch back before continuing. If the branch is neither default nor an issue-style branch, warn and ask whether to continue. Never delete a branch from `/issue-start`.
 
-3. **Scope check** — If the plan is broad, propose splitting into phases and ask whether to narrow scope before coding.
+3. **Sweep stale current issues** (auto-safe) — Group files in `.issueflows/01-current-issues/` by `issueNN_` prefix. For every group **other than the focus issue**, move the whole group to `.issueflows/03-solved-issues/` if any of its status files contains `- [x] Done` (case-insensitive on `done`), otherwise move it to `.issueflows/02-partly-solved-issues/`. Never move the focus issue's files. Report every move.
 
-4. **Implement** — Execute the confirmed plan. Prefer minimal, focused diffs. Match existing code style and tooling.
+4. **Plan first** — Produce a concrete plan (steps, files touched, tests). If you are **not** in plan mode, **stop and ask for explicit confirmation** before implementing, per the command definition.
 
-5. **Project conventions**
+5. **Scope check** — If the plan is broad, propose splitting into phases and ask whether to narrow scope before coding.
+
+6. **Implement** — Execute the confirmed plan. Prefer minimal, focused diffs. Match existing code style and tooling.
+
+7. **Project conventions**
    - Run Python via **`uv run`** (scripts, pytest, tools), not bare `python`, unless the user overrides.
    - Manage dependencies with **`uv add` / `uv remove` / `uv sync`** only.
    - After meaningful progress, update or create a status markdown file under `.issueflows/01-current-issues/` (e.g. `issue<number>_status.md`) with an explicit **Done** checkbox: `- [ ] Done` until fully resolved, then `- [x] Done`.
 
-6. **Reporting** — Summarize what changed, what remains, and where the issue docs live.
+8. **Reporting** — Summarize what changed, what remains, and where the issue docs live. Include any branch warnings from step 2 and any issue-group moves from step 3.
 
 ## Constraints
 
 - Do not invent issue text; treat `*_original.md` as read-only source of requirements unless the user asks to edit it.
-- Do not move issue files between `01-` / `02-` / `03-` folders during `/issue-start` unless the user explicitly asked for that housekeeping.
+- The stale sweep in step 3 is the **only** automatic move `/issue-start` performs, and it never touches the focus issue's own files. Do not move the focus issue's files between `01-` / `02-` / `03-` folders during `/issue-start`.
+- Never delete or force-update git branches from `/issue-start`.
diff --git a/.issueflows/03-solved-issues/issue31_original.md b/.issueflows/03-solved-issues/issue31_original.md
@@ -0,0 +1,9 @@
+# Issue #31: problems with branches and merging
+
+Source: https://github.com/jepegit/issue-flow/issues/31
+
+## Original issue text
+
+When using issue-flow I experience many times (probably due to mistakes I do) that issue branches ends up being marked as several commits ahead of main, though the code changes are actually implemented. What can we implement to help users prevent experiencing the same as me?
+
+Also, many times there are left-overs in the .issueflows folder. I guess mostly within the 01-current-issues folder. Are there any things we can do to help that from happening that often?