@jaggerxtrm/specialists 3.4.0 → 3.4.2

package/config/specialists/sync-docs.specialist.yaml

@@ -11,9 +11,11 @@ specialist:
     mode: tool
     model: anthropic/claude-sonnet-4-6
     fallback_model: google-gemini-cli/gemini-3-flash-preview
-    timeout_ms: 300000
+    timeout_ms: 0
+    stall_timeout_ms: 120000
     response_format: markdown
     permission_required: LOW
+    interactive: true
 
   prompt:
     system: |
@@ -28,8 +30,10 @@ specialist:
         Phase 5: Validate (validate_doc.py, final drift scan)
 
       **Audit vs Execute:**
-      - If the prompt says "audit", "check", "report", or "what's stale" — stop after Phase 3.
-      - Only run Phase 4 fixes when the prompt explicitly asks for changes.
+      - If `$bead_id` is present (run started with `--bead`), default to EXECUTE mode and run all phases through Phase 5.
+      - A bead-linked run is an explicit change request: do not stop after Phase 3 and do not ask for confirmation before Phase 4.
+      - If no bead is linked and the prompt says "audit", "check", "report", or "what's stale" — stop after Phase 3.
+      - If no bead is linked, only run Phase 4 fixes when the prompt explicitly asks for changes.
 
       **Script paths:** Use `~/.agents/skills/sync-docs/scripts/` for global install.
 
@@ -39,13 +43,24 @@ specialist:
       Working directory: $cwd
 
       Follow the sync-docs workflow from your injected skill. Start with Phase 1 context
-      gathering, then drift detection, then structure analysis. Report findings before
-      making any changes unless the task explicitly asks for fixes.
+      gathering, then drift detection, then structure analysis.
+
+      Bead context: $bead_id
+      If Bead context is present, execute all phases (1-5) and apply fixes directly.
+      If Bead context is empty, report findings before making changes unless the task
+      explicitly asks for fixes.
 
   skills:
     paths:
       - ~/.agents/skills/sync-docs/SKILL.md
 
+  validation:
+    files_to_watch:
+      - src/specialist/schema.ts
+      - src/specialist/runner.ts
+      - .agents/skills/sync-docs/SKILL.md
+    stale_threshold_days: 30
+
   communication:
     output_to: .specialists/sync-docs-report.md
     publishes: [docs_audit, drift_report, changelog_update]

package/config/specialists/test-runner.specialist.yaml

@@ -11,7 +11,8 @@ specialist:
     mode: tool
     model: anthropic/claude-haiku-4-5
     fallback_model: google-gemini-cli/gemini-3-flash-preview
-    timeout_ms: 300000
+    timeout_ms: 0
+    stall_timeout_ms: 120000
     response_format: markdown
     permission_required: LOW
 
@@ -54,5 +55,11 @@ specialist:
       - "cat vitest.config.ts"
       - "cat package.json | grep -A5 '\"test\"'"
 
+  validation:
+    files_to_watch:
+      - src/specialist/schema.ts
+      - src/specialist/runner.ts
+    stale_threshold_days: 30
+
   communication:
     publishes: [test_results]

package/config/specialists/xt-merge.specialist.yaml

@@ -1,17 +1,18 @@
 specialist:
   metadata:
     name: xt-merge
-    version: 1.0.0
-    description: "Drains the xt worktree PR queue in FIFO order: lists open xt/ PRs sorted by creation time, checks CI status on the oldest, merges it with --rebase --delete-branch, then rebases all remaining branches onto the new default branch and force-pushes them. Handles rebase conflicts, CI re-triggering, and reports final queue state."
+    version: 1.1.0
+    description: "Drains the xt worktree PR queue in FIFO order: pre-flight checks (auth, fetch, dirty tree), lists open xt/ PRs sorted by creation time, checks CI status on the oldest (verifying SHA matches post-rebase tip), merges it with --rebase --delete-branch, then rebases all remaining branches onto the new default branch with --force-with-lease --force-if-includes and verifies each push landed. Handles rebase conflicts (abort + report), stale CI detection, push verification, stash/pop for dirty state, and reports final queue state."
     category: workflow
     tags: [git, pr, merge, worktree, xt, rebase, ci]
-    updated: "2026-03-22"
+    updated: "2026-03-28"
 
   execution:
     mode: tool
     model: anthropic/claude-sonnet-4-6
     fallback_model: google-gemini-cli/gemini-3-flash-preview
-    timeout_ms: 300000
+    timeout_ms: 0
+    stall_timeout_ms: 120000
     response_format: markdown
     permission_required: MEDIUM
 
@@ -23,6 +24,23 @@ specialist:
       were created by `xt end` — each branch was rebased onto origin/main at the time
       it was pushed, so they form an ordered queue that must be merged FIFO.
 
+      ## Stage 0 — Pre-flight (run before touching any branch)
+
+      1. Confirm you are in a git repo: `git rev-parse --git-dir`
+         Stop immediately if this fails.
+
+      2. Verify gh auth: `gh auth status`
+         Stop immediately if this fails — auth errors mid-run corrupt the cascade state.
+
+      3. Fetch all remotes: `git fetch --all --prune`
+         Required before any CI check or rebase target reference.
+
+      4. Check for uncommitted changes: `git status --porcelain`
+         If non-empty, STOP and tell the user. The rebase cascade checks out other
+         branches — a dirty tree will either fail or bleed changes onto the wrong branch.
+         Options: `git stash push -m "xt-merge cascade stash"`, commit first, or abort.
+         If the user stashes, record the stash ref so you can pop it when done.
+
       ## FIFO ordering
 
       Merge the oldest-created PR first. After each merge, main advances and all
@@ -31,37 +49,84 @@ specialist:
 
       ## Your workflow
 
-      1. List open PRs: `gh pr list --state open --json number,title,headRefName,createdAt,isDraft`
+      1. List open PRs:
+         ```
+         gh pr list --state open --json number,title,headRefName,createdAt,isDraft \
+           --jq '.[] | select(.headRefName | startswith("xt/")) | [.number, .createdAt, .headRefName, .title] | @tsv' \
+           | sort -k2
+         ```
          Filter for branches starting with "xt/", sort by createdAt ascending.
-         Skip draft PRs.
+         Skip draft PRs. If gh pr list errors, stop — do not continue with stale data.
+         Present the sorted queue to the user before proceeding.
 
       2. Check CI on the head PR: `gh pr checks <number>`
+
+         IMPORTANT — stale CI after rebase: the PR's HEAD SHA changes after a cascade
+         push. Always verify CI ran against the current tip:
+         ```
+         gh pr view <number> --json headRefOid --jq '.headRefOid'
+         ```
+         Compare against the SHA shown in gh pr checks. If they differ, the green result
+         is from before the rebase — wait for the new run. Do NOT merge on a stale green.
+
          Do NOT merge if checks are pending or failing. Report status and stop.
 
       3. Merge the head PR:
          `gh pr merge <number> --rebase --delete-branch`
-         Always use --rebase for linear history. Always --delete-branch to clean up remote.
+         Always --rebase for linear history. Always --delete-branch to clean up remote.
+
+         If gh pr merge fails with "No commits between main and xt/<branch>", the branch
+         was already absorbed into main. Close the PR and continue to the next.
+
+         After merge, fetch and confirm main advanced:
+         `git fetch origin && git log origin/main --oneline -3`
 
       4. Rebase all remaining xt/ branches 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
          ```
-         Repeat in queue order. If a rebase produces conflicts, stop and report the
-         conflicted files with enough context for the user to resolve them.
+         Use --force-with-lease --force-if-includes together (Git 2.30+). If Git is
+         older, use --force-with-lease alone. Never bare --force.
+
+         After EACH push, verify it landed:
+         `git rev-parse HEAD` must equal `git rev-parse origin/xt/<branch>`
+         If the push was rejected or SHAs differ, STOP and report — do not continue.
+
+         Repeat in queue order. If a rebase produces conflicts you cannot safely
+         resolve, run `git rebase --abort` immediately. Report the branch name and
+         conflicted files. Continue the cascade for other branches; the user resolves
+         this one manually.
 
       5. Repeat from step 2 until the queue is empty.
 
+      6. When done: if the user stashed in Stage 0, run `git stash pop`. Report any
+         stash pop conflicts — do not discard silently.
+         Run `gh pr list --state open` and `git log origin/main --oneline -5` to
+         confirm final state.
+
       ## Constraints
 
       - Never merge a PR with failing or pending CI.
+      - Never merge on a stale CI result — verify SHA before trusting green.
       - Never use --squash or --merge; always --rebase.
-      - Never force-push without --force-with-lease.
-      - If you hit a rebase conflict you cannot safely resolve, stop and show the
-        conflicted files. Do not guess at conflict resolution.
-      - Report the queue state (PR number, branch, CI status) before each merge action.
+      - Never force-push without --force-with-lease (--force-if-includes preferred).
+      - After each cascade push, verify local HEAD == remote tip before continuing.
+      - If a rebase conflict cannot be safely resolved, abort (git rebase --abort) and
+        report — do not guess at conflict resolution.
+      - If gh auth fails at any point, stop and report what was completed vs not.
+      - Report queue state (PR number, branch, CI status) before each merge action.
+
+      ## Rollback / abort mid-cascade
+
+      If anything goes wrong:
+      1. `git rebase --abort` if a rebase is in progress
+      2. `git checkout <original-branch>` to return to start
+      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 from the correct point.
 
     task_template: |
       Drain the xt worktree PR merge queue.
@@ -70,9 +135,25 @@ specialist:
 
       Working directory: $cwd
 
-      List all open PRs from xt/ branches, sort oldest-first, check CI on the oldest,
-      merge it if green, rebase the remaining branches onto the new main, and repeat
+      Run Stage 0 pre-flight checks first (git repo check, gh auth, git fetch --all,
+      git status --porcelain). Stop and report if any check fails.
+
+      Then list all open PRs from xt/ branches, sort oldest-first, check CI on the
+      oldest (verify SHA matches current tip — not a pre-rebase result), merge it if
+      green, rebase the remaining branches onto the new main with
+      --force-with-lease --force-if-includes, verify each push landed, and repeat
       until the queue is empty. Report final state when done.
 
+  skills:
+    paths:
+      - .agents/skills/xt-merge/SKILL.md
+
+  validation:
+    files_to_watch:
+      - src/specialist/schema.ts
+      - src/specialist/runner.ts
+      - .agents/skills/xt-merge/SKILL.md
+    stale_threshold_days: 30
+
   communication:
     output_to: .specialists/merge-prs-result.md