xtrm-tools 0.5.35 → 0.5.37

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xtrm-cli",
-  "version": "0.5.35",
+  "version": "0.5.37",
   "description": "Claude Code tools installer (skills, hooks, MCP servers)",
   "main": "./dist/index.js",
   "type": "module",

package/config/instructions/agents-top.md

@@ -8,7 +8,7 @@
 1. `bd prime` — load workflow context and active claims
 2. `bd memories <keyword>` — retrieve memories relevant to today's task
 3. `bd recall <key>` — retrieve a specific memory by key if needed
-4. `bd ready` — find available work
+4. `bv --robot-triage` — graph-aware triage: ranked picks, unblock targets, project health
 5. `bd update <id> --claim` — claim before any file edit
 
 ## Active Gates (extensions enforce these — not optional)
@@ -88,6 +88,53 @@ Run on every file edit via PostToolUse extension:
 
 Gate output appears as extension context. Fix failures before proceeding — do not commit with lint errors.
 
+## bv — Graph-Aware Triage
+
+bv is a graph-aware triage engine for the beads issue board. Use it instead of `bd ready` when you need ranked picks, dependency-aware scheduling, or project health signals.
+
+> **CRITICAL: Use ONLY `--robot-*` flags. Bare `bv` launches an interactive TUI that blocks your session.**
+
+```bash
+bv --robot-triage             # THE entry point — ranked picks, quick wins, blockers, health
+bv --robot-next               # Single top pick + claim command (minimal output)
+bv --robot-triage --format toon  # Token-optimized output for lower context usage
+```
+
+**Scope boundary:** bv = *what to work on*. `bd` = creating, claiming, closing issues.
+
+### Planning & Analysis
+
+| Command | Returns |
+|---------|---------|
+| `--robot-plan` | Parallel execution tracks with unblocks lists |
+| `--robot-priority` | Priority misalignment detection |
+| `--robot-insights` | Full graph metrics: PageRank, betweenness, HITS, eigenvector, critical path, cycles |
+| `--robot-forecast <id\|all>` | ETA predictions with dependency-aware scheduling |
+| `--robot-alerts` | Stale issues, blocking cascades, priority mismatches |
+| `--robot-diff --diff-since <ref>` | Changes since ref: new/closed/modified, cycles introduced/resolved |
+
+### Scoping & Filtering
+
+```bash
+bv --robot-plan --label backend        # Scope to label's subgraph
+bv --recipe actionable --robot-plan    # Pre-filter: ready to work (no blockers)
+bv --recipe high-impact --robot-triage # Pre-filter: top PageRank scores
+bv --robot-triage --robot-triage-by-track  # Group by parallel work streams
+```
+
+### Understanding Output
+
+- `data_hash` — fingerprint of beads state (verify consistency across calls)
+- Phase 1 (instant): degree, topo sort, density
+- Phase 2 (async, 500ms): PageRank, betweenness, HITS, cycles — check `status` flags
+
+```bash
+bv --robot-triage | jq '.quick_ref'              # At-a-glance summary
+bv --robot-triage | jq '.recommendations[0]'     # Top recommendation
+bv --robot-plan | jq '.plan.summary.highest_impact'
+bv --robot-insights | jq '.Cycles'               # Circular deps — must fix
+```
+
 ## Worktree Sessions
 
 - `xt pi` — launch Pi in a sandboxed worktree

package/config/instructions/claude-top.md

@@ -8,7 +8,7 @@
 1. `bd prime` — load workflow context and active claims
 2. `bd memories <keyword>` — retrieve memories relevant to today's task
 3. `bd recall <key>` — retrieve a specific memory by key if needed
-4. `bd ready` — find available work
+4. `bv --robot-triage` — graph-aware triage: ranked picks, unblock targets, project health
 5. `bd update <id> --claim` — claim before any file edit
 
 ## Active Gates (hooks enforce these — not optional)
@@ -80,6 +80,35 @@ xt end                                       # push, PR, merge, worktree cleanup
 
 **Never** continue new work on a previously used branch.
 
+## bv — Graph-Aware Triage
+
+bv is a graph-aware triage engine for the beads issue board. Use it instead of `bd ready` when you need ranked picks, dependency-aware scheduling, or project health signals.
+
+> **CRITICAL: Use ONLY `--robot-*` flags. Bare `bv` launches an interactive TUI that blocks your session.**
+
+```bash
+bv --robot-triage             # THE entry point — ranked picks, quick wins, blockers, health
+bv --robot-next               # Single top pick + claim command (minimal output)
+bv --robot-triage --format toon  # Token-optimized output for lower context usage
+```
+
+**Scope boundary:** bv = *what to work on*. `bd` = creating, claiming, closing issues.
+
+| Command | Returns |
+|---------|---------|
+| `--robot-plan` | Parallel execution tracks with unblocks lists |
+| `--robot-insights` | PageRank, betweenness, HITS, cycles, critical path |
+| `--robot-forecast <id\|all>` | ETA predictions with dependency-aware scheduling |
+| `--robot-alerts` | Stale issues, blocking cascades, priority mismatches |
+| `--robot-diff --diff-since <ref>` | Changes since ref: new/closed/modified |
+
+```bash
+bv --recipe actionable --robot-plan    # Pre-filter: ready to work
+bv --robot-triage --robot-triage-by-track  # Group by parallel work streams
+bv --robot-triage | jq '.quick_ref'   # At-a-glance summary
+bv --robot-insights | jq '.Cycles'    # Circular deps — must fix
+```
+
 ## Code Intelligence (mandatory before edits)
 
 Use **Serena** (`using-serena-lsp` skill) for all code reads and edits:

package/config/pi/extensions/lsp-bootstrap/index.ts

@@ -114,7 +114,7 @@ function runInstall(target: LspTarget, ctx: any): void {
 }
 
 export default function register(api: ExtensionAPI) {
-    api.on("session_start", async (ctx: any) => {
+    api.on("before_agent_start", async (_event: any, ctx: any) => {
         const cwd = process.cwd();
         const detected = detectTargets(cwd);
         if (detected.length === 0) return;

package/config/pi/extensions/pi-serena-compact/index.ts

@@ -0,0 +1,121 @@
+import type { ExtensionAPI, ToolResultEvent } from "@mariozechner/pi-coding-agent";
+
+// Serena/GitNexus MCP tool names that produce verbose output
+const COMPACT_TOOLS = new Set([
+  // Serena symbol operations
+  "find_symbol",
+  "find_referencing_symbols", 
+  "get_symbols_overview",
+  "jet_brains_find_symbol",
+  "jet_brains_find_referencing_symbols",
+  "jet_brains_get_symbols_overview",
+  "jet_brains_type_hierarchy",
+  
+  // Serena file operations
+  "read_file",
+  "create_text_file",
+  "replace_content",
+  "replace_lines",
+  "delete_lines",
+  "insert_at_line",
+  
+  // Serena search/navigation
+  "search_for_pattern",
+  "list_dir",
+  "find_file",
+  
+  // Serena symbol editing
+  "replace_symbol_body",
+  "insert_after_symbol",
+  "insert_before_symbol",
+  "rename_symbol",
+  
+  // GitNexus
+  "gitnexus_query",
+  "gitnexus_context",
+  "gitnexus_impact",
+  "gitnexus_detect_changes",
+  "gitnexus_list_repos",
+  
+  // Serena memory
+  "read_memory",
+  "write_memory",
+  "list_memories",
+  
+  // Other verbose tools
+  "execute_shell_command",
+  "structured_return",
+]);
+
+// Tools that should show more output even when compacted
+const PRESERVE_OUTPUT_TOOLS = new Set([
+  "read_file",
+  "read_memory",
+  "execute_shell_command",
+  "structured_return",
+]);
+
+function isSerenaTool(toolName: string): boolean {
+  return COMPACT_TOOLS.has(toolName);
+}
+
+function getTextContent(content: Array<{ type: string; text?: string }>): string {
+  const item = content.find((c) => c.type === "text");
+  return item?.text ?? "";
+}
+
+function truncateLines(text: string, maxLines: number, maxLineLen = 180): string {
+  const lines = text.split("\n");
+  const truncated = lines.map(line => 
+    line.length > maxLineLen ? line.slice(0, maxLineLen) + "…" : line
+  );
+  
+  if (truncated.length <= maxLines) return truncated.join("\n");
+  return truncated.slice(0, maxLines).join("\n") + `\n… +${truncated.length - maxLines} more lines`;
+}
+
+function compactResult(
+  toolName: string,
+  content: Array<{ type: string; text?: string }>,
+  maxLines: number = 6,
+): Array<{ type: string; text: string }> {
+  const textContent = getTextContent(content);
+  
+  if (!textContent) {
+    return [{ type: "text", text: "✓ No output" }];
+  }
+  
+  // For certain tools, show more output
+  const effectiveMaxLines = PRESERVE_OUTPUT_TOOLS.has(toolName) ? 12 : maxLines;
+  
+  const compacted = truncateLines(textContent, effectiveMaxLines, 180);
+  
+  return [{ type: "text", text: compacted }];
+}
+
+export default function serenaCompactExtension(pi: ExtensionAPI): void {
+  let toolsExpanded = false;
+
+  // Track tools expanded state
+  pi.on("session_start", async (_event, ctx) => {
+    toolsExpanded = ctx.ui.getToolsExpanded();
+  });
+
+  pi.on("session_switch", async (_event, ctx) => {
+    toolsExpanded = ctx.ui.getToolsExpanded();
+  });
+
+  // Compact Serena tool results
+  pi.on("tool_result", async (event: ToolResultEvent) => {
+    // Only handle Serena/MCP tools
+    if (!isSerenaTool(event.toolName)) return undefined;
+    
+    // If tools are expanded, don't compact
+    if (toolsExpanded) return undefined;
+    
+    // Compact the content
+    const compacted = compactResult(event.toolName, event.content, 6);
+    
+    return { content: compacted };
+  });
+}

package/config/pi/extensions/pi-serena-compact/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "pi-serena-compact",
+  "version": "1.0.0",
+  "description": "Compact output for Serena MCP tools in Pi",
+  "keywords": ["pi", "pi-extension", "serena", "mcp"],
+  "license": "MIT",
+  "type": "module",
+  "main": "index.ts",
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.56.0",
+    "@mariozechner/pi-tui": "^0.56.0"
+  },
+  "pi": {
+    "extensions": ["./index.ts"]
+  }
+}

package/config/pi/install-schema.json

@@ -40,6 +40,7 @@
     "npm:lsp-pi",
     "npm:@zenobius/pi-worktrees",
     "npm:@robhowley/pi-structured-return",
-    "npm:@aliou/pi-guardrails"
+    "npm:@aliou/pi-guardrails",
+    "npm:@aliou/pi-processes"
   ]
 }

package/config/pi/settings.json.template

@@ -8,7 +8,8 @@
     "npm:@aliou/pi-guardrails",
     "npm:pi-gitnexus",
     "npm:pi-serena-tools",
-    "npm:@zenobius/pi-worktrees"
+    "npm:@zenobius/pi-worktrees",
+    "npm:@aliou/pi-processes"
   ],
   "steeringMode": "all",
   "followUpMode": "all",

package/hooks/beads-gate-messages.mjs

@@ -59,13 +59,19 @@ export function stopBlockMessage(summary, claimed) {
 export function memoryPromptMessage(claimId, sessionId) {
   const claimLine = claimId ? `claim \`${claimId}\` was closed.\n` : '';
   const ackCmd = sessionId
-    ? `bd kv set "memory-gate-done:${sessionId}" 1`
+    ? `bd kv set "memory-gate-done:${sessionId}"`
     : 'touch .beads/.memory-gate-done';
   return (
     `\u25cf Memory gate: ${claimLine}` +
-    'Ask: "Would this be useful in 14 days on a fresh session?"\n' +
-    '  YES → `bd remember "<insight>"`\n' +
-    '  NO  → note "nothing to persist"\n' +
-    `  Then: \`${ackCmd}\`\n`
+    'For each candidate insight, check ALL 4:\n' +
+    '  1. Hard to rediscover from code/docs?\n' +
+    '  2. Not obvious from the current implementation?\n' +
+    '  3. Will affect a future decision?\n' +
+    '  4. Still relevant in ~14 days?\n' +
+    'KEEP (all 4 yes) → `bd remember "<insight>"`\n' +
+    'SKIP examples: file maps, flag inventories, per-issue summaries,\n' +
+    '  wording tweaks, facts obvious from reading the source.\n' +
+    `KEEP: \`${ackCmd} "saved: <key>"\`\n` +
+    `SKIP: \`${ackCmd} "nothing novel — <one-line reason>"\`\n`
   );
 }

package/hooks/tsconfig-cache.json

@@ -0,0 +1,14 @@
+{
+  "hashes": {
+    "/home/dawid/projects/specialists/tsconfig.json": "84f37aa64b949b7aaba41974cb6137341a36730b7d3e174803cb9289eae1e7c7"
+  },
+  "mappings": {
+    "src/**/*": {
+      "configPath": "/home/dawid/projects/specialists/tsconfig.json",
+      "excludes": [
+        "node_modules",
+        "dist"
+      ]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xtrm-tools",
-  "version": "0.5.35",
+  "version": "0.5.37",
   "description": "Claude Code tools installer (skills, hooks, MCP servers)",
   "license": "MIT",
   "type": "module",
@@ -59,6 +59,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
+    "@artale/pi-procs": "^1.1.0",
     "comment-json": "^4.2.3",
     "conf": "^15.1.0",
     "dotenv": "^17.3.1",
@@ -77,7 +78,8 @@
       "npm:pi-serena-tools",
       "npm:@zenobius/pi-worktrees",
       "npm:@robhowley/pi-structured-return",
-      "npm:@aliou/pi-guardrails"
+      "npm:@aliou/pi-guardrails",
+      "npm:@aliou/pi-processes"
     ]
   }
 }

package/plugins/xtrm-tools/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xtrm-tools",
-  "version": "0.5.35",
+  "version": "0.5.37",
   "description": "xtrm-tools: dual-runtime workflow enforcement (Claude Code + Pi) — hooks, extensions, skills, and MCP servers",
   "author": {
     "name": "jaggers"

package/plugins/xtrm-tools/hooks/beads-gate-messages.mjs

@@ -59,13 +59,19 @@ export function stopBlockMessage(summary, claimed) {
 export function memoryPromptMessage(claimId, sessionId) {
   const claimLine = claimId ? `claim \`${claimId}\` was closed.\n` : '';
   const ackCmd = sessionId
-    ? `bd kv set "memory-gate-done:${sessionId}" 1`
+    ? `bd kv set "memory-gate-done:${sessionId}"`
     : 'touch .beads/.memory-gate-done';
   return (
     `\u25cf Memory gate: ${claimLine}` +
-    'Ask: "Would this be useful in 14 days on a fresh session?"\n' +
-    '  YES → `bd remember "<insight>"`\n' +
-    '  NO  → note "nothing to persist"\n' +
-    `  Then: \`${ackCmd}\`\n`
+    'For each candidate insight, check ALL 4:\n' +
+    '  1. Hard to rediscover from code/docs?\n' +
+    '  2. Not obvious from the current implementation?\n' +
+    '  3. Will affect a future decision?\n' +
+    '  4. Still relevant in ~14 days?\n' +
+    'KEEP (all 4 yes) → `bd remember "<insight>"`\n' +
+    'SKIP examples: file maps, flag inventories, per-issue summaries,\n' +
+    '  wording tweaks, facts obvious from reading the source.\n' +
+    `KEEP: \`${ackCmd} "saved: <key>"\`\n` +
+    `SKIP: \`${ackCmd} "nothing novel — <one-line reason>"\`\n`
   );
 }

package/plugins/xtrm-tools/hooks/tsconfig-cache.json

@@ -0,0 +1,14 @@
+{
+  "hashes": {
+    "/home/dawid/projects/specialists/tsconfig.json": "84f37aa64b949b7aaba41974cb6137341a36730b7d3e174803cb9289eae1e7c7"
+  },
+  "mappings": {
+    "src/**/*": {
+      "configPath": "/home/dawid/projects/specialists/tsconfig.json",
+      "excludes": [
+        "node_modules",
+        "dist"
+      ]
+    }
+  }
+}

package/plugins/xtrm-tools/skills/sync-docs/SKILL.md

@@ -4,11 +4,12 @@ description: >-
   Doc audit and structural sync for xtrm projects. Use whenever the README
   feels too long, docs are out of sync after a sprint, the CHANGELOG is behind,
   or the user asks to "sync docs", "doc audit", "split readme", "check docs
-  health", or "detect drift". Reads bd issues and git history, then runs
-  docs-only drift detection on README.md, CHANGELOG.md, and docs/ — creating
-  missing focused files instead of a monolithic README.
+  health", or "detect drift". Prefer the xtrm docs command suite (`xtrm docs
+  list`, `xtrm docs show`, `xtrm docs cross-check`) for operator-facing
+  inspection, then use docs-only drift detection on README.md, CHANGELOG.md,
+  and docs/ plus the Python analyzers as validation/backstop tools.
 gemini-command: sync-docs
-version: 1.2.0
+version: 1.3.0
 ---
 
 # sync-docs
@@ -19,18 +20,37 @@ Keeps project documentation in sync with code reality.
 
 ```
 Phase 1: Gather context     — what changed recently?
-Phase 2: Detect docs drift  — which docs/ files are stale?
-Phase 3: Analyze structure  — what belongs outside README?
-Phase 4: Plan + execute     — fix docs and changelog
-Phase 5: Validate           — schema-check all docs/
+Phase 2: Inspect with xtrm  — what does the docs suite already report?
+Phase 3: Detect docs drift  — which docs/ files are stale?
+Phase 4: Analyze structure  — what belongs outside README?
+Phase 5: Plan + execute     — fix docs and changelog
+Phase 6: Validate           — schema-check all docs/
 ```
 
-**Audit vs Execute mode:** If the user asked for an audit/report/check-only task, stop after Phase 3. Only run fixes when the user explicitly asks for changes.
+**Preferred workflow:** use the `xtrm docs` command suite first for human/operator-facing inspection, then use the Python scripts for drift validation, structure analysis, metadata checks, and sync checkpoints.
+
+**Audit vs Execute mode:** If the user asked for an audit/report/check-only task, stop after Phase 4. Only run fixes when the user explicitly asks for changes.
 
 ---
 
 ## Phase 1: Gather Context
 
+Start with the user-facing docs suite so the agent sees the same command surfaces users do:
+
+```bash
+xtrm docs list
+xtrm docs list --json
+xtrm docs show --json
+xtrm docs cross-check --json --days 30
+```
+
+Use these commands for:
+- `xtrm docs list` — inventory docs files, paths, titles, types, and cache-backed scans
+- `xtrm docs show --json` — inspect frontmatter for README, CHANGELOG, and `docs/*.md`
+- `xtrm docs cross-check --json` — gather stale-doc, coverage-gap, and open-issue-ref signals
+
+Then gather deeper repository context if needed:
+
 ```bash
 # Global install
 python3 "$HOME/.agents/skills/sync-docs/scripts/context_gatherer.py" [--since=30]
@@ -47,7 +67,30 @@ Outputs JSON with:
 
 ---
 
-## Phase 2: Detect docs/ Drift
+## Phase 2: Inspect with `xtrm docs`
+
+Treat the CLI docs suite as the primary operator workflow:
+
+```bash
+xtrm docs --help
+xtrm docs list --json
+xtrm docs show --json
+xtrm docs cross-check --json --days 30
+```
+
+Use it to answer:
+- what docs currently exist?
+- which docs have missing or outdated metadata?
+- are there coverage gaps between recent work and docs?
+- do docs reference open issues?
+
+If the xtrm docs suite already isolates the problem clearly, proceed directly to fixes. If you need machine-level drift validation for `docs/*.md`, continue to the Python drift detector.
+
+---
+
+## Phase 3: Detect docs/ Drift
+
+Use the Python detector as the authoritative drift/backstop check for tracked `docs/*.md` pages:
 
 ```bash
 python3 "skills/sync-docs/scripts/drift_detector.py" scan --since 30
@@ -82,7 +125,7 @@ This sets `synced_at` to current HEAD, marking the doc as synced.
 
 ---
 
-## Phase 3: Analyze Document Structure
+## Phase 4: Analyze Document Structure
 
 ```bash
 python3 "skills/sync-docs/scripts/doc_structure_analyzer.py"
@@ -96,11 +139,13 @@ Checks:
 
 Statuses: `BLOATED`, `EXTRACTABLE`, `MISSING`, `STALE`, `INVALID_SCHEMA`, `OK`.
 
-If this is audit-only, stop here and report.
+If this is audit-only, stop here and report. In the report, include both:
+- `xtrm docs` findings (operator-facing)
+- Python analyzer findings (drift/structure enforcement)
 
 ---
 
-## Phase 4: Execute Fixes
+## Phase 5: Execute Fixes
 
 | Situation | Action |
 |---|---|
@@ -131,6 +176,16 @@ python3 "skills/sync-docs/scripts/validate_doc.py" --generate docs/hooks.md \
 python3 "skills/sync-docs/scripts/validate_metadata.py" docs/
 ```
 
+### Re-run xtrm docs suite after fixes
+
+```bash
+xtrm docs list --json
+xtrm docs show --json
+xtrm docs cross-check --json --days 30
+```
+
+Use this pass to confirm the user-facing docs workflow now reflects the repaired state before final validation.
+
 ### Add changelog entry
 
 ```bash
@@ -140,13 +195,20 @@ python3 "skills/sync-docs/scripts/changelog/add_entry.py" \
 
 ---
 
-## Phase 5: Final Validation
+## Phase 6: Final Validation
+
+Run both layers:
 
 ```bash
+xtrm docs list --json
+xtrm docs show --json
+xtrm docs cross-check --json --days 30
 python3 "skills/sync-docs/scripts/validate_doc.py" docs/
 python3 "skills/sync-docs/scripts/drift_detector.py" scan --since 30
 ```
 
+The `xtrm docs` commands confirm the end-user/operator view; the Python tools confirm schema and tracked-doc drift guarantees.
+
 ---
 
 ## Frontmatter Schema
@@ -208,3 +270,17 @@ title: What's New in v2.0
 `docs/` is the only source of truth for project documentation in this workflow.
 Scripts validate `docs/*.md` only — subdirectories (`docs/plans/`, `docs/reference/`) are ignored.
 Use frontmatter (`source_of_truth_for`) to link docs pages to code areas and detect drift.
+
+## Command Selection Rules
+
+Use `xtrm docs` commands first when the task is about understanding the current docs state:
+- `xtrm docs list --json` → inventory and filtering
+- `xtrm docs show --json` → frontmatter inspection
+- `xtrm docs cross-check --json` → recent-work drift, coverage gaps, open issue refs
+
+Use Python scripts when the task is about enforcement or synchronization internals:
+- `drift_detector.py` → `synced_at` / `source_of_truth_for` drift checks for `docs/*.md`
+- `doc_structure_analyzer.py` → README bloat, missing focused docs, changelog version gaps
+- `validate_metadata.py` / `validate_doc.py` → schema/index validation
+
+Do not replace the Python tools with `xtrm docs`; use the CLI for operator-facing inspection and the scripts for authoritative structural validation.

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

@@ -19,10 +19,12 @@ priority: high
 ```bash
 bd prime                          # load workflow context + active claims
 bd memories <today's topic>       # retrieve relevant past context
-bd ready                          # find available work
+bv --robot-triage                 # graph-ranked picks, quick wins, unblock targets
 bd update <id> --claim            # claim before any edit
 ```
 
+> Use `bv --robot-next` for the single top pick. Use `bv --robot-triage --format toon` to save context tokens. **Never run bare `bv` — it launches an interactive TUI.**
+
 ---
 
 ## Trigger Patterns
@@ -30,6 +32,7 @@ bd update <id> --claim            # claim before any edit
 | Situation | Action |
 |-----------|--------|
 | User prompt contains `?` | `bd memories <keywords>` before answering — check stored context first |
+| "What should I work on?" | `bv --robot-triage` — ranked picks with dependency context |
 | "What was I working on?" | `bd list --status=in_progress` |
 | Unfamiliar area of code | `gitnexus_query({query: "concept"})` before opening any file |
 | About to edit a symbol | `gitnexus_impact({target: "name", direction: "upstream"})` |