xtrm-tools 0.7.0 → 0.7.2

package/skills/xt-end/SKILL.md

@@ -1,297 +0,0 @@
----
-name: xt-end
-description: |
-  Autonomous session close flow for xt worktree sessions. Use this skill whenever
-  the user says "done", "finished", "wrap up", "close session", "ship it", "I'm done",
-  "ready to merge", or similar. Also activate when all beads issues in the session
-  are closed, or when the user explicitly runs /xt-end. This skill is designed for
-  headless/specialist use: it must make deterministic decisions, auto-remediate common
-  anomalies, and avoid clarification questions unless execution is truly blocked.
----
-
-# xt-end — Autonomous Session Close Flow
-
-You are closing an `xt` worktree session. The canonical CLI is `xt end`, but you must normalize the session first and automatically handle common anomalies.
-
-## Operating Mode
-
-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
-
-Use these mental result classes while operating:
-- `SUCCESS_PR_CREATED`
-- `SUCCESS_PR_CREATED_WITH_WARNINGS`
-- `BLOCKED_UNCLOSED_SESSION_WORK`
-- `BLOCKED_NO_COMMITS`
-- `BLOCKED_AUTH`
-- `BLOCKED_CONFLICTS`
-- `BLOCKED_DIRTY_UNCLASSIFIED_CHANGES`
-
----
-
-## Stage 1 — Session Work Audit
-
-Run:
-```bash
-bd list --status=in_progress
-bd list --status=open
-git log --oneline @{upstream}..HEAD 2>/dev/null || git log --oneline origin/main..HEAD 2>/dev/null || git log --oneline
-```
-
-Rules:
-- **Block** on `in_progress` issues
-- **Do not block** on unrelated open backlog issues
-- infer **session-touched issues** from commit messages and recent session work
-- if a touched issue is still not closed, close it if the work is complete; otherwise stop with `BLOCKED_UNCLOSED_SESSION_WORK`
-
-This skill is stricter about unfinished session work than about unrelated backlog.
-
----
-
-## Stage 2 — Tree Normalization
-
-Run:
-```bash
-git status --short
-```
-
-If clean, continue.
-
-If dirty:
-- if the changes clearly belong to the just-finished session work, commit them automatically
-- if they look like unrelated WIP, stash them with a labeled stash message
-- never run `xt end` with a dirty tree
-
-Preferred automatic actions:
-```bash
-git add -A && git commit -m "<descriptive summary> (<issue-id>)"
-# or
-
-git stash push -m "xt-end:auto-stash before session close"
-```
-
-If changes cannot be classified safely, stop with `BLOCKED_DIRTY_UNCLASSIFIED_CHANGES`.
-
----
-
-## Stage 2.5 — Scope Verification
-
-Before committing or pushing, verify that branch changes match the expected scope of the session's closed issues. **Never skip this step** — unreviewed scope is the primary source of oversized or unintended PRs.
-
-Run:
-```bash
-git diff --stat origin/main..HEAD 2>/dev/null || git diff --stat $(git merge-base HEAD main)..HEAD
-```
-
-For each significantly changed symbol, check blast radius:
-```bash
-npx gitnexus impact <symbol-name>                   # upstream dependants — what else breaks
-npx gitnexus impact <symbol-name> -d downstream    # downstream dependencies
-```
-
-For Claude agents with MCP access, also run:
-```
-gitnexus_detect_changes({scope: "compare", base_ref: "main"})
-```
-
-**Rules:**
-- Changes clearly tied to session issues → continue
-- Files unrelated to session issues → classify as overscoped (handle in Stage 3D)
-- `npx gitnexus impact` returns HIGH or CRITICAL risk on a changed symbol → **stop and report to user** before continuing
-
----
-
-## Stage 3 — Dry Run and Anomaly Detection
-
-Run:
-```bash
-xt end --dry-run
-```
-
-Parse the preview and check for anomalies:
-
-### A. Generic PR title
-Treat these as invalid:
-- `session changes`
-- `update`
-- `updates`
-- `misc`
-- `wip`
-- `work in progress`
-
-Auto-remediation:
-- prefer closed issue titles from this session
-- otherwise infer from changed files / dominant area
-- examples:
-  - `Add docs cross-check command and tests`
-  - `Integrate docs workflow with sync-docs`
-  - `Update docs workflow and CLI help`
-
-### B. Missing beads linkage
-If dry-run says no beads issues were found, but commit messages contain issue-like IDs, treat that as a tooling mismatch.
-
-Auto-remediation:
-- extract issue IDs directly from commit messages
-- continue with those IDs as manually inferred linkage
-- report the mismatch in the final summary
-
-### C. Generated artifacts in scope
-If files like `dist/` are included:
-- keep them if the repo conventionally commits built artifacts
-- otherwise revert them before continuing
-
-Use repository history/common practice as the heuristic; do not ask.
-
-### D. Overscoped PR
-Classify the PR scope into buckets:
-- source
-- tests
-- docs
-- skills
-- generated artifacts
-
-If all buckets support one coherent feature/change, continue.
-If they look unrelated, continue but mark the PR as `WITH_WARNINGS` and mention overscope in the final report.
-
-After auto-remediating anomalies, re-run:
-```bash
-xt end --dry-run
-```
-
-Repeat until the preview is acceptable or a hard blocker appears.
-
----
-
-## Stage 4 — No-Commit / Session-Sanity Gate
-
-Before actual execution, ensure the branch really has changes:
-```bash
-git log --oneline @{upstream}..HEAD 2>/dev/null || git log --oneline origin/main..HEAD 2>/dev/null
-```
-
-If there are no commits ahead of base, stop with `BLOCKED_NO_COMMITS`.
-
----
-
-## Stage 5 — Run xt end
-
-Run:
-```bash
-xt end --yes
-```
-
-Use non-interactive mode by default for autonomous execution.
-
-### If it succeeds
-Capture:
-- rebase success
-- push success
-- PR URL
-- linked issue count
-
-### If rebase conflicts occur
-Run:
-```bash
-git status
-```
-
-Resolve all conflict markers, then:
-```bash
-git add <resolved-files>
-git rebase --continue
-xt end --yes
-```
-
-If conflicts are too complex to resolve safely, stop with `BLOCKED_CONFLICTS`.
-
-### If push fails
-Try:
-```bash
-git fetch origin
-xt end --yes
-```
-
-### If `gh` auth fails
-Stop with `BLOCKED_AUTH` and report:
-```bash
-gh auth login
-```
-
----
-
-## Stage 6 — Autonomous Cleanup
-
-Default behavior: **remove the worktree automatically** after a successful PR creation.
-
-Rationale:
-- branch is pushed
-- PR is open
-- worktree is disposable local state
-
-If cleanup is needed after `xt end --yes`:
-```bash
-git worktree remove <path> --force
-```
-
-Keep the worktree only if an explicit keep policy exists (for example, known immediate follow-up work on the same branch).
-
----
-
-## Stage 7 — Final Report
-
-Always report:
-- final result class (`SUCCESS_PR_CREATED` or `SUCCESS_PR_CREATED_WITH_WARNINGS`)
-- PR URL
-- linked or inferred issues
-- whether anomalies were auto-remediated
-- whether the worktree was removed
-- reminder: monitor CI and merge when green; no auto-merge assumption
-
-If linkage had to be inferred from commits rather than detected by `xt end`, say so explicitly.
-
----
-
-## Edge Cases
-
-**Already on main/master/default branch**
-- stop immediately; this is not an xt worktree session
-
-**No commits yet on branch**
-- stop with `BLOCKED_NO_COMMITS`
-
-**Dirty tree with unclear ownership**
-- stop with `BLOCKED_DIRTY_UNCLASSIFIED_CHANGES`
-
-**`gh` not authenticated**
-- stop with `BLOCKED_AUTH`
-
-**beads unavailable**
-- continue PR creation if possible
-- infer issues from commit messages when available
-- report linkage as unavailable/manual
-
-**Multiple anomalies at once**
-- remediate in order:
-  1. dirty tree
-  2. missing commits
-  3. generic title
-  4. missing issue linkage
-  5. generated artifacts
-  6. overscope warning
-
-## Policy Summary
-
-The autonomous rule is simple:
-- normalize the session
-- verify scope with gitnexus before committing
-- dry-run
-- auto-fix predictable anomalies
-- rerun dry-run
-- execute non-interactively
-- clean up automatically
-- stop only on genuine safety blockers

package/skills/xt-merge/SKILL.md

@@ -1,313 +0,0 @@
----
-name: xt-merge
-description: |
-  Merges queued PRs from xt worktree sessions in the correct order (FIFO), maintaining linear
-  history by rebasing remaining PRs after each merge. Use this skill whenever the user has
-  multiple open PRs from xt worktrees, asks to "merge my PRs", "process the PR queue",
-  "drain the queue", "merge worktree branches", or says "what PRs do I have open".
-  Also activate after any xt-end completion when other PRs are already open, or when the
-  user asks "can I merge yet" or "is CI green". Handles the full sequence: list → sort →
-  CI check → merge oldest → rebase cascade → repeat until queue is empty.
----
-
-# merge-prs — Worktree PR Merge Workflow
-
-You are draining a queue of PRs created by `xt end` from multiple worktree sessions.
-The key constraint is **ordering**: merge in FIFO order and rebase the remaining PRs
-after each merge. Work through the stages below in sequence.
-
----
-
-## Why FIFO and why the rebase cascade matters
-
-When `xt end` runs, it rebases the worktree branch onto `origin/main` at that moment
-and pushes. If you ran three sessions in sequence:
-
-```
-Session A finishes at t=1 → xt/feature-a rebased onto main@sha1
-Session B finishes at t=2 → xt/feature-b rebased onto main@sha2 (sha2 >= sha1)
-Session C finishes at t=3 → xt/feature-c rebased onto main@sha3 (sha3 >= sha2)
-```
-
-After merging A, main advances to sha4. Branch B is now based on sha2 — it still
-compiles and CI passes, but it doesn't include A's changes. You must rebase B onto
-sha4 before merging, so the history stays linear and B's CI reflects the real state
-of main + B.
-
-**FIFO = merge the oldest-created PR first.** The older the PR, the smaller the
-rebase cascade it triggers in subsequent branches. Merging out of order means
-you're rebasing more than necessary and risk conflicts that wouldn't have existed.
-
----
-
-## 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:
-
-```bash
-gh pr list --state open --json number,title,headRefName,createdAt,isDraft \
-  --jq '.[] | select(.headRefName | startswith("xt/")) | [.number, .createdAt, .headRefName, .title] | @tsv' \
-  | sort -k2
-```
-
-This sorts by creation time. The top row is the **head of the queue** — merge it first.
-
-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):
-  #42  xt/fix-auth-gate       "Fix beads edit gate claim check"     2026-03-21 10:14
-  #45  xt/add-release-script  "Add release script for npm publish"  2026-03-21 14:32
-  #47  xt/default-branch      "Detect default branch in xt end"     2026-03-22 09:11
-```
-
----
-
-## Stage 2 — Check CI on the head PR
-
-```bash
-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.
-
-If CI is failing:
-- Show the failing check names and link to the run
-- Do NOT proceed with the merge
-- Let the user decide: fix the issue in the worktree (may already be deleted), push a
-  fixup commit directly to the branch, or close the PR
-
----
-
-## Stage 3 — Merge the head PR
-
-```bash
-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.
-
-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)
-
-For every remaining PR in the queue, rebase its branch onto the new main:
-
-```bash
-git fetch origin main
-git checkout xt/<branch>
-git rebase origin/main
-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 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.
-
-### If rebase conflicts occur
-
-```bash
-git status          # shows conflicted files
-# edit each file to resolve <<<< ==== >>>> markers
-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, abort and escalate to the user
-
-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 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:
-  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)
-  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>
-```
-
----
-
-## 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
-```
-
-Confirm no open xt/ PRs remain and show the user the final state of main.
-
----
-
-## Edge cases
-
-**PR was already merged**: `gh pr merge` will error. Skip it and continue.
-
-**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
-git checkout -b xt/<branch> origin/xt/<branch>
-```
-
-**CI never triggers after rebase push**: GitHub sometimes needs a nudge. Close and
-re-open the PR, or push an empty commit:
-```bash
-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. 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.