xtrm-tools 0.5.45 → 0.5.47

package/plugins/xtrm-tools/hooks/statusline.mjs

@@ -4,7 +4,7 @@
 // Line 2: ◐ italic(claim title)  OR  ○ bold(N) open  — no background
 //
 // Colors: bold/dim/italic only — no explicit fg/bg, adapts to dark & light themes.
-// State: .xtrm/statusline-claim (written by beads-claim-sync.mjs)
+// State: .xtrm/statusline-claim[-<worktreeName>] (written by beads-claim-sync.mjs)
 // Cache: /tmp per cwd, 5s TTL
 
 import { execSync } from 'node:child_process';
@@ -125,8 +125,10 @@ if (!data) {
   let claimTitle = null;
   let openCount = 0;
   if (existsSync(join(cwd, '.beads')) || existsSync(join(mainRoot, '.beads'))) {
-    // Use mainRoot so all sessions (main + worktrees) share one canonical claim file.
-    const claimFile = join(mainRoot, '.xtrm', 'statusline-claim');
+    // Per-worktree claim file — prevents cross-session contamination.
+    const worktreeMatch = cwd.match(/\/\.xtrm\/worktrees\/([^/]+)/);
+    const claimFileName = worktreeMatch ? `statusline-claim-${worktreeMatch[1]}` : 'statusline-claim';
+    const claimFile = join(mainRoot, '.xtrm', claimFileName);
     claimId = existsSync(claimFile) ? (readFileSync(claimFile, 'utf8').trim() || null) : null;
     if (claimId) {
       try {

package/plugins/xtrm-tools/skills/planning/SKILL.md

@@ -62,16 +62,33 @@ If the request is under 8 words or the scope is unclear, ask **one** clarifying
 
 Use GitNexus and Serena to understand the landscape. No file edits.
 
+### GitNexus-first protocol (mandatory when available)
+
 ```bash
-# Find relevant execution flows
+# 1) Find relevant execution flows by concept
 gitnexus_query({query: "<concept related to task>"})
 
-# Understand a specific symbol
+# 2) Get full caller/callee/process context for likely symbols
 gitnexus_context({name: "<affected symbol>"})
 
-# Check blast radius before planning changes
+# 3) Assess blast radius before locking the implementation plan
 gitnexus_impact({target: "<symbol to change>", direction: "upstream"})
+```
+
+### Refactor planning checks (when rename/extract/move is in scope)
+
+```bash
+# Preview safe multi-file rename plan first
+gitnexus_rename({symbol_name: "<old>", new_name: "<new>", dry_run: true})
+
+# Confirm context before extraction/split plans
+gitnexus_context({name: "<symbol to extract/split>"})
+gitnexus_impact({target: "<symbol to extract/split>", direction: "upstream"})
+```
+
+### Serena symbol-level inspection (targeted reads)
 
+```bash
 # Map a file without reading all of it
 get_symbols_overview("path/to/relevant/file.ts")
 
@@ -79,11 +96,44 @@ get_symbols_overview("path/to/relevant/file.ts")
 find_symbol("SymbolName", include_body=true)
 ```
 
+### Fallback when GitNexus MCP tools are unavailable
+
+If MCP GitNexus tools are unavailable, use the GitNexus CLI first, then Serena symbol exploration if needed.
+
+```bash
+# Verify index freshness / repository indexing
+npx gitnexus status
+npx gitnexus list
+
+# Concept and architecture exploration
+npx gitnexus query "<concept or symptom>" --limit 5
+npx gitnexus context "<symbolName>"
+
+# Blast radius before committing to a plan
+npx gitnexus impact "<symbolName>" --direction upstream --depth 3
+
+# If index is stale
+npx gitnexus analyze
+```
+
+Notes:
+- In this environment, `detect_changes` and `rename` are available via MCP tools, not GitNexus CLI subcommands.
+- If both MCP and CLI are unavailable, fall back to Serena search + symbols and state this explicitly in your plan output.
+
+```bash
+search_for_pattern("<concept or symbol>")
+get_symbols_overview("path/to/relevant/file.ts")
+find_symbol("<candidate symbol>", include_body=true)
+find_referencing_symbols("<symbol>", "path/to/file.ts")
+```
+
 **Capture from exploration:**
 - Which files/symbols will be affected
+- Which execution flows/processes are involved (from `gitnexus_query`/`gitnexus_context`)
 - What existing patterns to follow (naming, structure, error handling)
 - Any d=1 dependents that require updates when you change a symbol
-- Risk level: if CRITICAL or HIGH → warn user before proceeding
+- Risk level from impact analysis: if CRITICAL or HIGH → warn user before proceeding
+- If GitNexus fallback path was used, explicitly call it out in the handoff
 
 ---
 
@@ -101,6 +151,7 @@ Think through the plan before writing any bd commands. Use structured CoT:
 3. What are the dependencies? (what must be done before X can start?)
 4. What can run in parallel? (independent tasks → no deps between them)
 5. What are the risks? (complex areas, unclear spec, risky refactors)
+6. What is the blast-radius summary from GitNexus? (direct callers, affected processes, risk level)
 </thinking>
 
 <plan>
@@ -244,7 +295,13 @@ test-planning will:
 
 ## Phase 6 — Handoff
 
-Present the board and transition to implementation:
+Present the board and transition to implementation.
+
+Include a short **Architecture & Impact Summary** in your handoff message:
+- Key execution flows/processes involved
+- Top d=1 dependents to watch
+- Highest observed risk (LOW/MEDIUM/HIGH/CRITICAL)
+- Whether GitNexus-first or fallback exploration was used
 
 ```bash
 # Show the full board
@@ -292,30 +349,26 @@ Then begin work on the first task. The planning phase is complete.
 ### Example 2 — Bug fix with investigation
 
 <example>
-  <scenario>User: "bd close sometimes doesn't auto-commit"</scenario>
+  <scenario>User: "bd close doesn't commit my changes"</scenario>
 
   <exploration>
-    gitnexus_query({query: "bd close auto-commit"})
+    gitnexus_query({query: "bd close commit workflow"})
     → finds: beads-claim-sync.mjs, close event handler
-    find_symbol("handleClose", include_body=true)
-    → discovers: auto-commit only fires if tracked files changed, not untracked
+    find_symbol("main", include_body=true)
+    → discovers: bd close sets closed-this-session KV only; no git commit
   </exploration>
 
   <thinking>
-    Root cause identified: git commit -am skips untracked files.
-    Fix: check git ls-files --others before committing.
-    Risk: LOW — only beads-claim-sync.mjs changes.
-    Single task, no phases needed.
+    bd close does NOT auto-commit (removed in xtrm-wr0o).
+    Correct workflow: bd close <id>, then git add + git commit separately, then xt end.
+    No issue needed — this is expected behavior.
   </thinking>
 
   <bd_command>
-    bd create \
-      --title="Fix bd close auto-commit skips untracked new files" \
-      --description="Context: beads-claim-sync.mjs uses 'git commit -am' which skips
-      untracked files. Fix: add 'git ls-files --others --exclude-standard' check and
-      'git add -A' scoped to expected paths before committing.
-      AC: [ ] auto-commit includes new untracked files [ ] existing behavior preserved"
-      --type=bug --priority=1
+    # No issue needed — explain the correct workflow to the user:
+    # 1. bd close <id> --reason="..."   ← closes issue
+    # 2. git add . && git commit -m "..." ← commit changes manually
+    # 3. xt end                           ← push, PR, merge, worktree cleanup
   </bd_command>
 </example>
 
@@ -343,6 +396,8 @@ Before presenting the plan to the user:
 - [ ] Every issue has context / what / AC / notes
 - [ ] Dependencies are correct (A blocks B when B needs A's output)
 - [ ] No task is more than "one session" of work (split if needed)
+- [ ] GitNexus evidence captured (query/context/impact) or fallback path explicitly stated
+- [ ] If refactor scope exists, rename/extract safety checks were included in plan
 - [ ] test-planning was invoked (or scheduled as next step)
 - [ ] First implementation issue is ready to claim
 

package/plugins/xtrm-tools/skills/using-xtrm/SKILL.md

@@ -78,7 +78,7 @@ gitnexus_impact({target: "parseComposeServices", direction: "upstream"})
 get_symbols_overview("hooks/init.ts")                           # map file
 find_symbol("parseComposeServices", include_body=True)          # read just this
 replace_symbol_body("parseComposeServices", newBody)            # Serena edit
-bd close bd-xyz --reason="Fix YAML parse edge case"            # close + auto-commit
+bd close bd-xyz --reason="Fix YAML parse edge case"            # close issue
 xt end                                                         # push, PR, merge, cleanup
 ```
 

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

@@ -0,0 +1,149 @@
+---
+name: xt-debugging
+description: Complete debugging workflow — error analysis, log interpretation, performance profiling, and GitNexus call-chain tracing. Use when investigating bugs, errors, crashes, or performance issues.
+---
+
+# xt-debugging
+
+Systematic debugging using the GitNexus knowledge graph for call-chain tracing, combined with error analysis, log interpretation, and performance profiling.
+
+## When to Use
+
+- "Why is this function failing?"
+- "Trace where this error comes from"
+- "This endpoint returns 500"
+- Investigating crashes, unexpected behavior, or regressions
+- Performance issues
+- Reading logs or stack traces
+
+---
+
+## Prerequisites
+
+GitNexus must be indexed before starting. If you see "index is stale" or no results:
+
+```bash
+npx gitnexus analyze   # re-index the repo (run this, then retry)
+npx gitnexus status    # verify freshness
+```
+
+---
+
+## Phase 1 — Triage
+
+Understand the symptom before touching any code.
+
+1. Read the full error message and stack trace
+2. Identify the suspect symbol (function, class, endpoint)
+3. Check for regressions — what changed recently?
+   ```
+   gitnexus_detect_changes({scope: "compare", base_ref: "main"})
+   ```
+
+---
+
+## Phase 2 — Knowledge Graph Investigation
+
+```
+1. gitnexus_query({query: "<error text or symptom>"})   → Related execution flows + symbols
+2. gitnexus_context({name: "<suspect>"})                → Callers, callees, process participation
+3. READ gitnexus://repo/{name}/process/{processName}    → Full step-by-step execution trace
+4. gitnexus_cypher({...})                               → Custom call chain if needed
+```
+
+### Patterns by Symptom
+
+| Symptom | Approach |
+|---------|----------|
+| Error message | `query` for error text → `context` on throw site |
+| Wrong return value | `context` on function → trace callees for data flow |
+| Intermittent failure | `context` → look for external calls, async deps, race conditions |
+| Performance issue | `context` → find hot-path symbols with many callers |
+| Recent regression | `detect_changes` to see what changed |
+
+### Example — "Payment endpoint returns 500 intermittently"
+
+```
+1. gitnexus_query({query: "payment error handling"})
+   → Processes: CheckoutFlow, ErrorHandling
+   → Symbols: validatePayment, handlePaymentError
+
+2. gitnexus_context({name: "validatePayment"})
+   → Outgoing calls: verifyCard, fetchRates (external API!)
+
+3. READ gitnexus://repo/my-app/process/CheckoutFlow
+   → Step 3: validatePayment → calls fetchRates (external, no timeout)
+
+4. Root cause: fetchRates has no timeout → intermittent failures under load
+```
+
+---
+
+## Phase 3 — Root Cause Analysis
+
+1. **Reproduce** — Identify minimal reproduction steps
+2. **Trace data flow** — Follow the value/control flow from input to error
+3. **Isolate** — Narrow to the smallest failing unit
+4. **Hypothesize** — Form explicit hypothesis before reading more code
+5. **Confirm** — Verify hypothesis against source, not just symptoms
+
+Common root cause categories:
+- **Null/undefined** — missing guard, wrong assumption about data shape
+- **Race condition** — async ordering, missing await, shared mutable state
+- **External dependency** — timeout, API contract change, env difference
+- **Type mismatch** — serialization, casting, implicit coercion
+- **Configuration** — env var missing, wrong default, deployment drift
+
+---
+
+## Phase 4 — Log Analysis
+
+1. Read the full log output (not just the last line)
+2. Identify: timestamps, error levels, request IDs, correlation tokens
+3. Correlate events across log lines to build timeline
+4. Look for: first occurrence, frequency, affected subset, preceding events
+5. Summarize: what happened, when, why, and what was affected
+
+---
+
+## Phase 5 — Performance Profiling
+
+1. **Measure baseline** — Never optimize blind
+   ```bash
+   time <command>
+   ```
+2. **Profile** — Language-appropriate tools:
+   - Node.js: `--prof`, `clinic.js`, `0x`
+   - Python: `cProfile`, `py-spy`, `line_profiler`
+   - Go: `pprof`
+3. **Identify hotspot** — Usually 1–2 functions account for >80% of time; use `gitnexus_context` to confirm call frequency
+4. **Fix the bottleneck** — Minimal targeted change
+5. **Verify** — Measure again, compare against baseline
+
+---
+
+## Phase 6 — Remediation
+
+1. **Fix** — Minimal change that addresses the confirmed root cause
+2. **Verify** — Run the failing case to confirm fix
+3. **Regression test** — Add a test that would have caught this bug
+4. **Check blast radius** — `gitnexus_impact({target: "fixedSymbol", direction: "upstream"})`
+5. **Pre-commit scope check** — `gitnexus_detect_changes({scope: "staged"})`
+
+---
+
+## Checklist
+
+```
+- [ ] Read full error / stack trace
+- [ ] Identify suspect symbol
+- [ ] gitnexus_detect_changes to check for regressions
+- [ ] gitnexus_query for error text or symptom
+- [ ] gitnexus_context on suspect (callers, callees, processes)
+- [ ] Trace execution flow via process resource
+- [ ] Read source files to confirm root cause
+- [ ] Form explicit hypothesis before fixing
+- [ ] Verify fix against failing reproduction
+- [ ] Add regression test
+- [ ] gitnexus_detect_changes() before committing
+```

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

@@ -78,6 +78,33 @@ If changes cannot be classified safely, stop with `BLOCKED_DIRTY_UNCLASSIFIED_CH
 
 ---
 
+## 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:
@@ -260,6 +287,7 @@ If linkage had to be inferred from commits rather than detected by `xt end`, say
 
 The autonomous rule is simple:
 - normalize the session
+- verify scope with gitnexus before committing
 - dry-run
 - auto-fix predictable anomalies
 - rerun dry-run

package/skills/planning/SKILL.md

@@ -62,16 +62,33 @@ If the request is under 8 words or the scope is unclear, ask **one** clarifying
 
 Use GitNexus and Serena to understand the landscape. No file edits.
 
+### GitNexus-first protocol (mandatory when available)
+
 ```bash
-# Find relevant execution flows
+# 1) Find relevant execution flows by concept
 gitnexus_query({query: "<concept related to task>"})
 
-# Understand a specific symbol
+# 2) Get full caller/callee/process context for likely symbols
 gitnexus_context({name: "<affected symbol>"})
 
-# Check blast radius before planning changes
+# 3) Assess blast radius before locking the implementation plan
 gitnexus_impact({target: "<symbol to change>", direction: "upstream"})
+```
+
+### Refactor planning checks (when rename/extract/move is in scope)
+
+```bash
+# Preview safe multi-file rename plan first
+gitnexus_rename({symbol_name: "<old>", new_name: "<new>", dry_run: true})
+
+# Confirm context before extraction/split plans
+gitnexus_context({name: "<symbol to extract/split>"})
+gitnexus_impact({target: "<symbol to extract/split>", direction: "upstream"})
+```
+
+### Serena symbol-level inspection (targeted reads)
 
+```bash
 # Map a file without reading all of it
 get_symbols_overview("path/to/relevant/file.ts")
 
@@ -79,11 +96,44 @@ get_symbols_overview("path/to/relevant/file.ts")
 find_symbol("SymbolName", include_body=true)
 ```
 
+### Fallback when GitNexus MCP tools are unavailable
+
+If MCP GitNexus tools are unavailable, use the GitNexus CLI first, then Serena symbol exploration if needed.
+
+```bash
+# Verify index freshness / repository indexing
+npx gitnexus status
+npx gitnexus list
+
+# Concept and architecture exploration
+npx gitnexus query "<concept or symptom>" --limit 5
+npx gitnexus context "<symbolName>"
+
+# Blast radius before committing to a plan
+npx gitnexus impact "<symbolName>" --direction upstream --depth 3
+
+# If index is stale
+npx gitnexus analyze
+```
+
+Notes:
+- In this environment, `detect_changes` and `rename` are available via MCP tools, not GitNexus CLI subcommands.
+- If both MCP and CLI are unavailable, fall back to Serena search + symbols and state this explicitly in your plan output.
+
+```bash
+search_for_pattern("<concept or symbol>")
+get_symbols_overview("path/to/relevant/file.ts")
+find_symbol("<candidate symbol>", include_body=true)
+find_referencing_symbols("<symbol>", "path/to/file.ts")
+```
+
 **Capture from exploration:**
 - Which files/symbols will be affected
+- Which execution flows/processes are involved (from `gitnexus_query`/`gitnexus_context`)
 - What existing patterns to follow (naming, structure, error handling)
 - Any d=1 dependents that require updates when you change a symbol
-- Risk level: if CRITICAL or HIGH → warn user before proceeding
+- Risk level from impact analysis: if CRITICAL or HIGH → warn user before proceeding
+- If GitNexus fallback path was used, explicitly call it out in the handoff
 
 ---
 
@@ -101,6 +151,7 @@ Think through the plan before writing any bd commands. Use structured CoT:
 3. What are the dependencies? (what must be done before X can start?)
 4. What can run in parallel? (independent tasks → no deps between them)
 5. What are the risks? (complex areas, unclear spec, risky refactors)
+6. What is the blast-radius summary from GitNexus? (direct callers, affected processes, risk level)
 </thinking>
 
 <plan>
@@ -244,7 +295,13 @@ test-planning will:
 
 ## Phase 6 — Handoff
 
-Present the board and transition to implementation:
+Present the board and transition to implementation.
+
+Include a short **Architecture & Impact Summary** in your handoff message:
+- Key execution flows/processes involved
+- Top d=1 dependents to watch
+- Highest observed risk (LOW/MEDIUM/HIGH/CRITICAL)
+- Whether GitNexus-first or fallback exploration was used
 
 ```bash
 # Show the full board
@@ -292,30 +349,26 @@ Then begin work on the first task. The planning phase is complete.
 ### Example 2 — Bug fix with investigation
 
 <example>
-  <scenario>User: "bd close sometimes doesn't auto-commit"</scenario>
+  <scenario>User: "bd close doesn't commit my changes"</scenario>
 
   <exploration>
-    gitnexus_query({query: "bd close auto-commit"})
+    gitnexus_query({query: "bd close commit workflow"})
     → finds: beads-claim-sync.mjs, close event handler
-    find_symbol("handleClose", include_body=true)
-    → discovers: auto-commit only fires if tracked files changed, not untracked
+    find_symbol("main", include_body=true)
+    → discovers: bd close sets closed-this-session KV only; no git commit
   </exploration>
 
   <thinking>
-    Root cause identified: git commit -am skips untracked files.
-    Fix: check git ls-files --others before committing.
-    Risk: LOW — only beads-claim-sync.mjs changes.
-    Single task, no phases needed.
+    bd close does NOT auto-commit (removed in xtrm-wr0o).
+    Correct workflow: bd close <id>, then git add + git commit separately, then xt end.
+    No issue needed — this is expected behavior.
   </thinking>
 
   <bd_command>
-    bd create \
-      --title="Fix bd close auto-commit skips untracked new files" \
-      --description="Context: beads-claim-sync.mjs uses 'git commit -am' which skips
-      untracked files. Fix: add 'git ls-files --others --exclude-standard' check and
-      'git add -A' scoped to expected paths before committing.
-      AC: [ ] auto-commit includes new untracked files [ ] existing behavior preserved"
-      --type=bug --priority=1
+    # No issue needed — explain the correct workflow to the user:
+    # 1. bd close <id> --reason="..."   ← closes issue
+    # 2. git add . && git commit -m "..." ← commit changes manually
+    # 3. xt end                           ← push, PR, merge, worktree cleanup
   </bd_command>
 </example>
 
@@ -343,6 +396,8 @@ Before presenting the plan to the user:
 - [ ] Every issue has context / what / AC / notes
 - [ ] Dependencies are correct (A blocks B when B needs A's output)
 - [ ] No task is more than "one session" of work (split if needed)
+- [ ] GitNexus evidence captured (query/context/impact) or fallback path explicitly stated
+- [ ] If refactor scope exists, rename/extract safety checks were included in plan
 - [ ] test-planning was invoked (or scheduled as next step)
 - [ ] First implementation issue is ready to claim
 

package/skills/using-xtrm/SKILL.md

@@ -78,7 +78,7 @@ gitnexus_impact({target: "parseComposeServices", direction: "upstream"})
 get_symbols_overview("hooks/init.ts")                           # map file
 find_symbol("parseComposeServices", include_body=True)          # read just this
 replace_symbol_body("parseComposeServices", newBody)            # Serena edit
-bd close bd-xyz --reason="Fix YAML parse edge case"            # close + auto-commit
+bd close bd-xyz --reason="Fix YAML parse edge case"            # close issue
 xt end                                                         # push, PR, merge, cleanup
 ```