xtrm-tools 0.5.48 → 0.6.0

package/plugins/xtrm-tools/skills/xt-merge/SKILL.md

@@ -40,6 +40,46 @@ you're rebasing more than necessary and risk conflicts that wouldn't have existe
 
 ---
 
+## Stage 0 — Pre-flight checks
+
+Run these before touching any branch.
+
+**1. Verify you are in a git repository:**
+```bash
+git rev-parse --git-dir
+```
+Stop immediately if this fails.
+
+**2. Verify gh auth:**
+```bash
+gh auth status
+```
+If this fails, stop immediately. Without auth, `gh pr merge` will silently fail or
+produce confusing errors mid-run.
+
+**3. Fetch all remotes:**
+```bash
+git fetch --all --prune
+```
+This ensures local remote-tracking refs reflect current upstream state before any
+rebase or CI check. Without this, CI status checks and rebase targets may be stale.
+
+**4. Check for uncommitted local changes:**
+```bash
+git status --porcelain
+```
+If the output is non-empty, **warn the user and stop**. The rebase cascade will
+check out other branches (`git checkout xt/<branch>`), which will either fail or
+silently carry dirty changes into the wrong branch. Resolve before continuing:
+- `git stash push -m "xt-merge cascade stash"` — stash and pop after cascade finishes
+- Or commit the work first
+- Or abort if the changes belong to a live worktree session
+
+If the user stashes, record the stash ref (`git stash list | head -1`) so you can
+pop it when done in Stage 6.
+
+---
+
 ## Stage 1 — Build the queue
 
 List all open PRs from xt worktree branches:
@@ -54,6 +94,9 @@ This sorts by creation time. The top row is the **head of the queue** — merge
 
 If there are draft PRs in the list, skip them. Drafts are not ready to merge.
 
+If `gh pr list` returns an error (network, auth, wrong repo), stop and report the
+error. Do not continue with stale or incomplete data.
+
 Present the sorted queue to the user before proceeding:
 ```
 Queue (oldest → newest):
@@ -70,6 +113,14 @@ Queue (oldest → newest):
 gh pr checks <number>
 ```
 
+**Stale CI warning:** After a rebase cascade the PR's HEAD SHA changes. Always verify
+the SHA that CI ran against matches the current branch tip before trusting a green result:
+```bash
+gh pr view <number> --json headRefOid --jq '.headRefOid'
+# compare against the commit SHA shown in gh pr checks output
+```
+If they differ, the green result is from before the rebase — wait for the new run.
+
 Wait for all checks to pass. If CI is still running, tell the user and pause — don't
 merge a PR with pending or failing checks.
 
@@ -90,12 +141,18 @@ gh pr merge <number> --rebase --delete-branch
 Use `--rebase` (not `--squash` or `--merge`) to keep linear history and preserve
 individual commits from the session. Use `--delete-branch` to clean up the remote branch.
 
-After merge, confirm main advanced:
+If `gh pr merge` fails with "No commits between main and xt/<branch>", the branch's
+commits were already absorbed into main (e.g. from a previous push). Close the PR
+and continue to the next.
+
+After merge, fetch and confirm main advanced:
 ```bash
 git fetch origin
 git log origin/main --oneline -3
 ```
 
+Record the new HEAD SHA of main — you will verify the cascade rebases onto it.
+
 ---
 
 ## Stage 4 — Rebase cascade (all remaining PRs)
@@ -106,10 +163,24 @@ For every remaining PR in the queue, rebase its branch onto the new main:
 git fetch origin main
 git checkout xt/<branch>
 git rebase origin/main
-git push origin xt/<branch> --force-with-lease
+git push origin xt/<branch> --force-with-lease --force-if-includes
+```
+
+`--force-with-lease` rejects the push if the remote has commits your local ref
+doesn't know about. `--force-if-includes` additionally verifies that whatever
+you're overwriting was reachable from your local history — together they prevent
+accidentally overwriting a collaborator's push that arrived after your last fetch.
+(Requires Git 2.30+. If not available, `--force-with-lease` alone is acceptable.)
+
+**After each push, verify it landed:**
+```bash
+git rev-parse HEAD
+git rev-parse origin/xt/<branch>
 ```
+Both SHAs must match. If the push was rejected (lease violation or other error),
+stop and report — do not silently continue to the next branch.
 
-Repeat for each remaining branch. Do them in queue order (oldest next).
+Repeat for each remaining branch in queue order (oldest next).
 
 After pushing, GitHub will re-trigger CI on each rebased PR. You don't need to wait
 for CI here — the rebase just gets the branches current. CI will run in parallel.
@@ -123,27 +194,43 @@ git add <resolved-files>
 git rebase --continue
 ```
 
+If you cannot safely resolve a conflict, **abort the rebase immediately**:
+```bash
+git rebase --abort
+```
+The branch is left unchanged. Report the branch name and conflicted files to the
+user. Continue the cascade for remaining branches; the user can resolve and push
+this one manually before you loop back to merge it.
+
 Conflicts mean two sessions touched the same file. Resolve carefully:
 - Keep both changes if they're in different parts of the file
 - If they overlap, understand what each session was doing and merge the intent
-- When unsure, call the user in to review before continuing
+- When unsure, abort and escalate to the user
 
-After resolving, push with `--force-with-lease` and move to the next branch.
+After resolving, push with `--force-with-lease --force-if-includes` and verify the
+push landed (SHA check above) before moving to the next branch.
 
 ---
 
 ## Stage 5 — Repeat
 
-Go back to Stage 2 with the new head of the queue. Check CI, merge, rebase cascade,
+Go back to Stage 2 with the new head of the queue. Check CI on the **new SHA**
+produced by the rebase cascade push — not a pre-rebase result. Merge, cascade,
 repeat until the queue is empty.
 
 The full loop:
 ```
 while queue not empty:
-  wait for CI green on head PR
+  check CI on head PR
+    → verify: gh pr view <n> headRefOid == SHA in gh pr checks output
+    → wait for green; stop if failing
   merge head PR (--rebase --delete-branch)
-  rebase all remaining PRs onto new main
-  push each (--force-with-lease)
+  git fetch origin → confirm main advanced
+  for each remaining branch in queue order:
+    git checkout xt/<branch>
+    git rebase origin/main
+    git push --force-with-lease --force-if-includes
+    verify: git rev-parse HEAD == git rev-parse origin/xt/<branch>
 ```
 
 ---
@@ -151,7 +238,11 @@ while queue not empty:
 ## Stage 6 — Done
 
 When the queue is empty:
+
 ```bash
+# If you stashed changes in Stage 0, pop now:
+git stash pop   # report any conflicts — do not discard silently
+
 gh pr list --state open
 git log origin/main --oneline -5
 ```
@@ -164,7 +255,10 @@ Confirm no open xt/ PRs remain and show the user the final state of main.
 
 **PR was already merged**: `gh pr merge` will error. Skip it and continue.
 
-**Branch was deleted** (worktree cleaned up by `xt end --keep`): The remote branch
+**No commits between main and xt/branch**: branch was already absorbed into main.
+Close the PR and continue.
+
+**Branch was deleted** (worktree cleaned up by `xt end`): The remote branch
 still exists (pushed by `xt end`). The local branch may not. Check out from remote:
 ```bash
 git fetch origin
@@ -178,13 +272,42 @@ git commit --allow-empty -m "trigger CI"
 git push origin xt/<branch>
 ```
 
+**Stale CI result after rebase**: Always confirm the SHA in `gh pr checks` matches
+`git rev-parse origin/xt/<branch>` before treating a green result as valid. If they
+differ, wait for the new run.
+
+**Push rejected (lease violation)**: Do not retry blindly. Fetch and inspect:
+```bash
+git fetch origin xt/<branch>
+git log origin/xt/<branch> --oneline -5
+```
+Decide whether the remote commits should be incorporated or overwritten, then act
+deliberately.
+
+**`gh auth` expired mid-run**: Stop the cascade immediately. Report which branches
+were successfully rebased/pushed and which were not, so the user can resume from the
+right point after re-authenticating.
+
+**Uncommitted changes on current branch**: Stash before the cascade, pop after:
+```bash
+git stash push -m "xt-merge cascade stash"
+# ... run cascade ...
+git stash pop
+```
+If `git stash pop` produces conflicts, report them — do not silently discard work.
+
 **Dependent sessions** (B was intentionally built on A's work): If session B was
 started from inside session A's worktree rather than from main, B's branch already
-contains A's commits. In this case B will rebase cleanly onto main after A merges —
-its commits are a superset. No special handling needed; the rebase just eliminates
-the duplicate commits.
-
-**Multiple conflicts across many PRs**: If the cascade produces conflicts in several
-branches, tackle them one at a time in queue order. Don't try to resolve all of them
-before pushing any — push each one as you resolve it so CI starts running in parallel
-while you work on the next.
+contains A's commits. B will rebase cleanly onto main after A merges — the rebase
+eliminates the duplicate commits. No special handling needed.
+
+**Multiple conflicts across many PRs**: Abort each failing rebase (`git rebase --abort`)
+and tackle them one at a time in queue order after the user resolves. Push each
+resolved branch immediately so CI starts running in parallel.
+
+**Rollback / abort mid-cascade**: If anything goes wrong and you need to stop cleanly:
+1. `git rebase --abort` if a rebase is in progress
+2. `git checkout <original-branch>` to return to where you started
+3. `git stash pop` if you stashed in Stage 0
+4. Report exactly which PRs were merged, which were rebased-and-pushed, and which
+   were untouched — so the user can resume or restart from the correct point.

package/skills/xt-end/SKILL.md

@@ -19,6 +19,7 @@ Default to **autonomous execution**:
 - do not ask the user routine clarification questions
 - prefer deterministic fallbacks over conversational review
 - only stop when a real blocker prevents safe progress
+- **always invoke `xt end --yes`** — never call `xt end` without this flag; the bare command prompts interactively for worktree removal which blocks autonomous execution
 
 ## Success States
 

package/skills/xt-merge/SKILL.md

@@ -40,6 +40,46 @@ you're rebasing more than necessary and risk conflicts that wouldn't have existe
 
 ---
 
+## Stage 0 — Pre-flight checks
+
+Run these before touching any branch.
+
+**1. Verify you are in a git repository:**
+```bash
+git rev-parse --git-dir
+```
+Stop immediately if this fails.
+
+**2. Verify gh auth:**
+```bash
+gh auth status
+```
+If this fails, stop immediately. Without auth, `gh pr merge` will silently fail or
+produce confusing errors mid-run.
+
+**3. Fetch all remotes:**
+```bash
+git fetch --all --prune
+```
+This ensures local remote-tracking refs reflect current upstream state before any
+rebase or CI check. Without this, CI status checks and rebase targets may be stale.
+
+**4. Check for uncommitted local changes:**
+```bash
+git status --porcelain
+```
+If the output is non-empty, **warn the user and stop**. The rebase cascade will
+check out other branches (`git checkout xt/<branch>`), which will either fail or
+silently carry dirty changes into the wrong branch. Resolve before continuing:
+- `git stash push -m "xt-merge cascade stash"` — stash and pop after cascade finishes
+- Or commit the work first
+- Or abort if the changes belong to a live worktree session
+
+If the user stashes, record the stash ref (`git stash list | head -1`) so you can
+pop it when done in Stage 6.
+
+---
+
 ## Stage 1 — Build the queue
 
 List all open PRs from xt worktree branches:
@@ -54,6 +94,9 @@ This sorts by creation time. The top row is the **head of the queue** — merge
 
 If there are draft PRs in the list, skip them. Drafts are not ready to merge.
 
+If `gh pr list` returns an error (network, auth, wrong repo), stop and report the
+error. Do not continue with stale or incomplete data.
+
 Present the sorted queue to the user before proceeding:
 ```
 Queue (oldest → newest):
@@ -70,6 +113,14 @@ Queue (oldest → newest):
 gh pr checks <number>
 ```
 
+**Stale CI warning:** After a rebase cascade the PR's HEAD SHA changes. Always verify
+the SHA that CI ran against matches the current branch tip before trusting a green result:
+```bash
+gh pr view <number> --json headRefOid --jq '.headRefOid'
+# compare against the commit SHA shown in gh pr checks output
+```
+If they differ, the green result is from before the rebase — wait for the new run.
+
 Wait for all checks to pass. If CI is still running, tell the user and pause — don't
 merge a PR with pending or failing checks.
 
@@ -90,12 +141,18 @@ gh pr merge <number> --rebase --delete-branch
 Use `--rebase` (not `--squash` or `--merge`) to keep linear history and preserve
 individual commits from the session. Use `--delete-branch` to clean up the remote branch.
 
-After merge, confirm main advanced:
+If `gh pr merge` fails with "No commits between main and xt/<branch>", the branch's
+commits were already absorbed into main (e.g. from a previous push). Close the PR
+and continue to the next.
+
+After merge, fetch and confirm main advanced:
 ```bash
 git fetch origin
 git log origin/main --oneline -3
 ```
 
+Record the new HEAD SHA of main — you will verify the cascade rebases onto it.
+
 ---
 
 ## Stage 4 — Rebase cascade (all remaining PRs)
@@ -106,10 +163,24 @@ For every remaining PR in the queue, rebase its branch onto the new main:
 git fetch origin main
 git checkout xt/<branch>
 git rebase origin/main
-git push origin xt/<branch> --force-with-lease
+git push origin xt/<branch> --force-with-lease --force-if-includes
+```
+
+`--force-with-lease` rejects the push if the remote has commits your local ref
+doesn't know about. `--force-if-includes` additionally verifies that whatever
+you're overwriting was reachable from your local history — together they prevent
+accidentally overwriting a collaborator's push that arrived after your last fetch.
+(Requires Git 2.30+. If not available, `--force-with-lease` alone is acceptable.)
+
+**After each push, verify it landed:**
+```bash
+git rev-parse HEAD
+git rev-parse origin/xt/<branch>
 ```
+Both SHAs must match. If the push was rejected (lease violation or other error),
+stop and report — do not silently continue to the next branch.
 
-Repeat for each remaining branch. Do them in queue order (oldest next).
+Repeat for each remaining branch in queue order (oldest next).
 
 After pushing, GitHub will re-trigger CI on each rebased PR. You don't need to wait
 for CI here — the rebase just gets the branches current. CI will run in parallel.
@@ -123,27 +194,43 @@ git add <resolved-files>
 git rebase --continue
 ```
 
+If you cannot safely resolve a conflict, **abort the rebase immediately**:
+```bash
+git rebase --abort
+```
+The branch is left unchanged. Report the branch name and conflicted files to the
+user. Continue the cascade for remaining branches; the user can resolve and push
+this one manually before you loop back to merge it.
+
 Conflicts mean two sessions touched the same file. Resolve carefully:
 - Keep both changes if they're in different parts of the file
 - If they overlap, understand what each session was doing and merge the intent
-- When unsure, call the user in to review before continuing
+- When unsure, abort and escalate to the user
 
-After resolving, push with `--force-with-lease` and move to the next branch.
+After resolving, push with `--force-with-lease --force-if-includes` and verify the
+push landed (SHA check above) before moving to the next branch.
 
 ---
 
 ## Stage 5 — Repeat
 
-Go back to Stage 2 with the new head of the queue. Check CI, merge, rebase cascade,
+Go back to Stage 2 with the new head of the queue. Check CI on the **new SHA**
+produced by the rebase cascade push — not a pre-rebase result. Merge, cascade,
 repeat until the queue is empty.
 
 The full loop:
 ```
 while queue not empty:
-  wait for CI green on head PR
+  check CI on head PR
+    → verify: gh pr view <n> headRefOid == SHA in gh pr checks output
+    → wait for green; stop if failing
   merge head PR (--rebase --delete-branch)
-  rebase all remaining PRs onto new main
-  push each (--force-with-lease)
+  git fetch origin → confirm main advanced
+  for each remaining branch in queue order:
+    git checkout xt/<branch>
+    git rebase origin/main
+    git push --force-with-lease --force-if-includes
+    verify: git rev-parse HEAD == git rev-parse origin/xt/<branch>
 ```
 
 ---
@@ -151,7 +238,11 @@ while queue not empty:
 ## Stage 6 — Done
 
 When the queue is empty:
+
 ```bash
+# If you stashed changes in Stage 0, pop now:
+git stash pop   # report any conflicts — do not discard silently
+
 gh pr list --state open
 git log origin/main --oneline -5
 ```
@@ -164,7 +255,10 @@ Confirm no open xt/ PRs remain and show the user the final state of main.
 
 **PR was already merged**: `gh pr merge` will error. Skip it and continue.
 
-**Branch was deleted** (worktree cleaned up by `xt end --keep`): The remote branch
+**No commits between main and xt/branch**: branch was already absorbed into main.
+Close the PR and continue.
+
+**Branch was deleted** (worktree cleaned up by `xt end`): The remote branch
 still exists (pushed by `xt end`). The local branch may not. Check out from remote:
 ```bash
 git fetch origin
@@ -178,13 +272,42 @@ git commit --allow-empty -m "trigger CI"
 git push origin xt/<branch>
 ```
 
+**Stale CI result after rebase**: Always confirm the SHA in `gh pr checks` matches
+`git rev-parse origin/xt/<branch>` before treating a green result as valid. If they
+differ, wait for the new run.
+
+**Push rejected (lease violation)**: Do not retry blindly. Fetch and inspect:
+```bash
+git fetch origin xt/<branch>
+git log origin/xt/<branch> --oneline -5
+```
+Decide whether the remote commits should be incorporated or overwritten, then act
+deliberately.
+
+**`gh auth` expired mid-run**: Stop the cascade immediately. Report which branches
+were successfully rebased/pushed and which were not, so the user can resume from the
+right point after re-authenticating.
+
+**Uncommitted changes on current branch**: Stash before the cascade, pop after:
+```bash
+git stash push -m "xt-merge cascade stash"
+# ... run cascade ...
+git stash pop
+```
+If `git stash pop` produces conflicts, report them — do not silently discard work.
+
 **Dependent sessions** (B was intentionally built on A's work): If session B was
 started from inside session A's worktree rather than from main, B's branch already
-contains A's commits. In this case B will rebase cleanly onto main after A merges —
-its commits are a superset. No special handling needed; the rebase just eliminates
-the duplicate commits.
-
-**Multiple conflicts across many PRs**: If the cascade produces conflicts in several
-branches, tackle them one at a time in queue order. Don't try to resolve all of them
-before pushing any — push each one as you resolve it so CI starts running in parallel
-while you work on the next.
+contains A's commits. B will rebase cleanly onto main after A merges — the rebase
+eliminates the duplicate commits. No special handling needed.
+
+**Multiple conflicts across many PRs**: Abort each failing rebase (`git rebase --abort`)
+and tackle them one at a time in queue order after the user resolves. Push each
+resolved branch immediately so CI starts running in parallel.
+
+**Rollback / abort mid-cascade**: If anything goes wrong and you need to stop cleanly:
+1. `git rebase --abort` if a rebase is in progress
+2. `git checkout <original-branch>` to return to where you started
+3. `git stash pop` if you stashed in Stage 0
+4. Report exactly which PRs were merged, which were rebased-and-pushed, and which
+   were untouched — so the user can resume or restart from the correct point.