xtrm-tools 2.1.13 → 2.1.16

package/cli/package.json

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

package/config/hooks.json

@@ -4,6 +4,10 @@
       {
         "script": "skill-suggestion.py",
         "timeout": 5000
+      },
+      {
+        "script": "gitnexus-impact-reminder.py",
+        "timeout": 5000
       }
     ],
     "SessionStart": [
@@ -35,11 +39,6 @@
         "matcher": "Edit|Write|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
         "script": "type-safety-enforcement.py"
       },
-      {
-        "matcher": "Grep|Glob|Bash",
-        "script": "gitnexus/gitnexus-hook.cjs",
-        "timeout": 8000
-      },
       {
         "matcher": "Edit|Write|MultiEdit|NotebookEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
         "script": "beads-edit-gate.mjs",
@@ -56,6 +55,11 @@
         "matcher": "Bash",
         "script": "main-guard-post-push.mjs",
         "timeout": 5000
+      },
+      {
+        "matcher": "Read|Grep|Glob|Bash|mcp__serena__find_symbol|mcp__serena__get_symbols_overview|mcp__serena__search_for_pattern|mcp__serena__find_referencing_symbols|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol|mcp__serena__rename_symbol",
+        "script": "gitnexus/gitnexus-hook.cjs",
+        "timeout": 10000
       }
     ],
     "Stop": [

package/config/mcp_servers.json

@@ -41,6 +41,17 @@
     "deepwiki": {
       "type": "http",
       "url": "https://mcp.deepwiki.com/mcp"
+    },
+    "gitnexus": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "gitnexus", "mcp"],
+      "env": {},
+      "_notes": {
+        "description": "Code intelligence MCP - provides graph queries for impact analysis, execution flows, symbol context",
+        "prerequisite": "Run 'gitnexus analyze' in the project first to build the index",
+        "auto_index": "xtrm project init runs gitnexus analyze automatically"
+      }
     }
   }
 }

package/hooks/README.md

@@ -276,3 +276,75 @@ Use `xtrm install` to deploy all hooks automatically. For manual setup:
 3. Merge hook entries into `~/.claude/settings.json`.
 
 4. Restart Claude Code.
+
+---
+
+## Beads Hooks Architecture
+
+The beads gate hooks are organized into three layers:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        HOOK ENTRYPOINTS                         │
+│  (thin wrappers - just parse, call core, emit, exit)           │
+├──────────────────┬──────────────────┬──────────────────────────┤
+│ beads-edit-gate  │ beads-commit-gate│ beads-stop-gate         │
+│ beads-memory-gate│                  │                          │
+└────────┬─────────┴────────┬─────────┴─────────────┬────────────┘
+         │                  │                       │
+         ▼                  ▼                       ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    beads-gate-core.mjs                          │
+│  Pure decision functions - no I/O, return {allow, reason}      │
+├─────────────────────────────────────────────────────────────────┤
+│ • readHookInput()          → parsed input or null              │
+│ • resolveSessionContext()  → {cwd, sessionId, isBeadsProject}  │
+│ • resolveClaimAndWorkState() → {claimed, claimId, work}        │
+│ • decideEditGate()         → {allow: bool, reason?: string}    │
+│ • decideCommitGate()       → {allow: bool, reason?: string}    │
+│ • decideStopGate()         → {allow: bool, reason?: string}    │
+└─────────────────────────────────────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                  beads-gate-messages.mjs                        │
+│  Centralized message templates                                  │
+├─────────────────────────────────────────────────────────────────┤
+│ • WORKFLOW_STEPS          - full 7-step workflow                │
+│ • SESSION_CLOSE_PROTOCOL  - stop gate steps                     │
+│ • editBlockMessage(sessionId)                                   │
+│ • commitBlockMessage(summary, claimed)                          │
+│ • stopBlockMessage(summary, claimed)                            │
+│ • memoryPromptMessage()                                         │
+└─────────────────────────────────────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    beads-gate-utils.mjs                         │
+│  Low-level adapters - bd CLI, shell, fs operations             │
+├─────────────────────────────────────────────────────────────────┤
+│ • resolveCwd(input)                                             │
+│ • isBeadsProject(cwd)                                           │
+│ • getSessionClaim(sessionId, cwd)                               │
+│ • getTotalWork(cwd), getInProgress(cwd)                        │
+│ • clearSessionClaim(sessionId, cwd)                             │
+│ • withSafeBdContext(fn)                                         │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Where to Make Changes
+
+| Change type | File to edit |
+|-------------|--------------|
+| Policy logic (when to block/allow) | `beads-gate-core.mjs` |
+| User-facing messages | `beads-gate-messages.mjs` |
+| bd CLI integration | `beads-gate-utils.mjs` |
+| Hook registration/wiring | Entrypoints (rarely needed) |
+
+### Exit Semantics
+
+All hooks follow strict exit semantics:
+- `exit 0` — Allow the operation
+- `exit 2` — Block with message shown to Claude
+
+The core functions are pure and never call `process.exit()`. Entrypoints are responsible for side effects.

package/hooks/beads-commit-gate.mjs

@@ -7,58 +7,32 @@
 //
 // Installed by: xtrm install
 
-import { readFileSync } from 'node:fs';
 import {
-  resolveCwd, isBeadsProject, getSessionClaim,
-  getInProgress, withSafeBdContext,
-} from './beads-gate-utils.mjs';
-
-let input;
-try {
-  input = JSON.parse(readFileSync(0, 'utf8'));
-} catch {
-  process.exit(0);
-}
-
+  readHookInput,
+  resolveSessionContext,
+  resolveClaimAndWorkState,
+  decideCommitGate,
+} from './beads-gate-core.mjs';
+import { withSafeBdContext } from './beads-gate-utils.mjs';
+import { commitBlockMessage } from './beads-gate-messages.mjs';
+
+const input = readHookInput();
+if (!input) process.exit(0);
+
+// Only intercept git commit commands
 if ((input.tool_name ?? '') !== 'Bash') process.exit(0);
 if (!/\bgit\s+commit\b/.test(input.tool_input?.command ?? '')) process.exit(0);
 
-const NEXT_STEPS =
-  '  3. bd close <id1> <id2> ...             ← you are here\n' +
-  '  4. git add <files> && git commit -m "..."\n' +
-  '  5. git push -u origin <feature-branch>\n' +
-  '  6. gh pr create --fill && gh pr merge --squash\n' +
-  '  7. git checkout master && git reset --hard origin/master\n';
-
 withSafeBdContext(() => {
-  const cwd = resolveCwd(input);
-  if (!isBeadsProject(cwd)) process.exit(0);
-
-  const sessionId = input.session_id;
-
-  if (sessionId) {
-    const claimed = getSessionClaim(sessionId, cwd);
-    if (claimed === null) process.exit(0);
-    if (!claimed) process.exit(0);
+  const ctx = resolveSessionContext(input);
+  if (!ctx || !ctx.isBeadsProject) process.exit(0);
 
-    const ip = getInProgress(cwd);
-    const summary = ip?.summary ?? `  Claimed: ${claimed}`;
+  const state = resolveClaimAndWorkState(ctx);
+  const decision = decideCommitGate(ctx, state);
 
-    process.stderr.write(
-      '🚫 BEADS GATE: Close open issues before committing.\n\n' +
-      `Open issues:\n${summary}\n\n` +
-      'Next steps:\n' + NEXT_STEPS
-    );
-    process.exit(2);
-  } else {
-    const ip = getInProgress(cwd);
-    if (ip === null || ip.count === 0) process.exit(0);
+  if (decision.allow) process.exit(0);
 
-    process.stderr.write(
-      '🚫 BEADS GATE: Close open issues before committing.\n\n' +
-      `Open issues:\n${ip.summary}\n\n` +
-      'Next steps:\n' + NEXT_STEPS
-    );
-    process.exit(2);
-  }
+  // Block with message
+  process.stderr.write(commitBlockMessage(decision.summary, decision.claimed));
+  process.exit(2);
 });

package/hooks/beads-edit-gate.mjs

@@ -7,66 +7,32 @@
 //
 // Installed by: xtrm install
 
-import { readFileSync } from 'node:fs';
 import {
-  resolveCwd, isBeadsProject, getSessionClaim,
-  getTotalWork, getInProgress, withSafeBdContext,
-} from './beads-gate-utils.mjs';
+  readHookInput,
+  resolveSessionContext,
+  resolveClaimAndWorkState,
+  decideEditGate,
+} from './beads-gate-core.mjs';
+import { withSafeBdContext } from './beads-gate-utils.mjs';
+import { editBlockMessage, editBlockFallbackMessage } from './beads-gate-messages.mjs';
 
-let input;
-try {
-  input = JSON.parse(readFileSync(0, 'utf8'));
-} catch {
-  process.exit(0);
-}
+const input = readHookInput();
+if (!input) process.exit(0);
 
 withSafeBdContext(() => {
-  const cwd = resolveCwd(input);
-  if (!isBeadsProject(cwd)) process.exit(0);
+  const ctx = resolveSessionContext(input);
+  if (!ctx || !ctx.isBeadsProject) process.exit(0);
 
-  const sessionId = input.session_id;
+  const state = resolveClaimAndWorkState(ctx);
+  const decision = decideEditGate(ctx, state);
 
-  if (sessionId) {
-    const claimed = getSessionClaim(sessionId, cwd);
-    if (claimed === null) process.exit(0); // bd kv unavailable — fail open
-    if (claimed) process.exit(0);          // this session has an active claim
+  if (decision.allow) process.exit(0);
 
-    const totalWork = getTotalWork(cwd);
-    if (totalWork === null) process.exit(0); // can't determine — fail open
-    if (totalWork === 0) process.exit(0);    // nothing to track — clean-start state
-
-    process.stderr.write(
-      '🚫 BEADS GATE: This session has no active claim — claim an issue before editing files.\n\n' +
-      '  bd update <id> --status=in_progress\n' +
-      `  bd kv set "claimed:${sessionId}" "<id>"\n\n` +
-      'Or create a new issue:\n' +
-      '  bd create --title="<what you\'re doing>" --type=task --priority=2\n' +
-      '  bd update <id> --status=in_progress\n' +
-      `  bd kv set "claimed:${sessionId}" "<id>"\n`
-    );
-    process.exit(2);
+  // Block with appropriate message
+  if (decision.reason === 'no_claim_with_work') {
+    process.stderr.write(editBlockMessage(decision.sessionId));
   } else {
-    // Fallback: global in_progress check (non-Claude environments / no session_id).
-    const ip = getInProgress(cwd);
-    if (ip === null) process.exit(0);
-    if (ip.count > 0) process.exit(0);
-
-    const totalWork = getTotalWork(cwd);
-    if (totalWork === null || totalWork === 0) process.exit(0);
-
-    process.stderr.write(
-      '🚫 BEADS GATE: No active issue — create one before editing files.\n\n' +
-      '  bd create --title="<what you\'re doing>" --type=task --priority=2\n' +
-      '  bd update <id> --status=in_progress\n\n' +
-      'Full workflow (do this every session):\n' +
-      '  1. bd create + bd update in_progress   ← you are here\n' +
-      '  2. Edit files / write code\n' +
-      '  3. bd close <id>                        close when done\n' +
-      '  4. git add <files> && git commit\n' +
-      '  5. git push -u origin <feature-branch>\n' +
-      '  6. gh pr create --fill && gh pr merge --squash\n' +
-      '  7. git checkout master && git reset --hard origin/master\n'
-    );
-    process.exit(2);
+    process.stderr.write(editBlockFallbackMessage());
   }
+  process.exit(2);
 });

package/hooks/beads-gate-core.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+// beads-gate-core.mjs — pure decision functions for beads gate hooks
+// Import from sibling hooks using: import { ... } from './beads-gate-core.mjs';
+//
+// All functions are pure: they return decision objects, never call process.exit()
+// or write to stdout/stderr. Side effects belong in entrypoint wrappers.
+//
+// Dependencies: beads-gate-utils.mjs (adapters)
+
+import { readFileSync } from 'node:fs';
+import {
+  resolveCwd,
+  isBeadsProject,
+  getSessionClaim,
+  getTotalWork,
+  getInProgress,
+} from './beads-gate-utils.mjs';
+
+// ── Input parsing ────────────────────────────────────────────────────────────
+
+/**
+ * Read and parse hook input from stdin. Returns null on parse error.
+ * Entrypoints should exit 0 if this returns null (fail-open).
+ */
+export function readHookInput() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// ── Session context resolution ───────────────────────────────────────────────
+
+/**
+ * Resolve session context from hook input.
+ * Returns { cwd, sessionId, isBeadsProject } or null if cwd can't be resolved.
+ */
+export function resolveSessionContext(input) {
+  const cwd = resolveCwd(input);
+  if (!cwd) return null;
+  return {
+    cwd,
+    sessionId: input.session_id ?? null,
+    isBeadsProject: isBeadsProject(cwd),
+  };
+}
+
+// ── Claim and work state resolution ──────────────────────────────────────────
+
+/**
+ * Resolve the claim and work state for a session.
+ * Returns { claimed, claimId, totalWork, inProgress } or null if bd unavailable.
+ */
+export function resolveClaimAndWorkState(ctx) {
+  if (!ctx.isBeadsProject) {
+    return { claimed: false, claimId: null, totalWork: 0, inProgress: null };
+  }
+
+  const totalWork = getTotalWork(ctx.cwd);
+  if (totalWork === null) return null; // bd unavailable
+
+  const inProgress = getInProgress(ctx.cwd);
+
+  if (ctx.sessionId) {
+    const claimId = getSessionClaim(ctx.sessionId, ctx.cwd);
+    if (claimId === null) return null; // bd kv unavailable
+    return {
+      claimed: !!claimId,
+      claimId: claimId || null,
+      totalWork,
+      inProgress,
+    };
+  }
+
+  // No session_id: fallback to global in_progress check
+  return {
+    claimed: false,
+    claimId: null,
+    totalWork,
+    inProgress,
+  };
+}
+
+// ── Decision functions ───────────────────────────────────────────────────────
+
+/**
+ * Decide whether to allow or block an edit operation.
+ * Returns { allow: boolean, reason?: string, sessionId?: string }
+ */
+export function decideEditGate(ctx, state) {
+  // Not a beads project → allow
+  if (!ctx.isBeadsProject) {
+    return { allow: true };
+  }
+
+  // bd unavailable → fail open
+  if (state === null) {
+    return { allow: true };
+  }
+
+  // Session has an active claim → allow
+  if (state.claimed) {
+    return { allow: true };
+  }
+
+  // No trackable work → allow (clean-start state)
+  if (state.totalWork === 0) {
+    return { allow: true };
+  }
+
+  // Has session_id but no claim + has work → block
+  if (ctx.sessionId) {
+    return {
+      allow: false,
+      reason: 'no_claim_with_work',
+      sessionId: ctx.sessionId,
+    };
+  }
+
+  // Fallback: no session_id, check global in_progress
+  if (state.inProgress && state.inProgress.count > 0) {
+    return { allow: true };
+  }
+
+  // No session_id, no in_progress, but has open work → block
+  if (state.totalWork > 0) {
+    return {
+      allow: false,
+      reason: 'no_claim_fallback',
+    };
+  }
+
+  return { allow: true };
+}
+
+/**
+ * Decide whether to allow or block a git commit operation.
+ * Returns { allow: boolean, reason?: string, summary?: string, claimed?: string }
+ */
+export function decideCommitGate(ctx, state) {
+  // Not a beads project → allow
+  if (!ctx.isBeadsProject) {
+    return { allow: true };
+  }
+
+  // bd unavailable → fail open
+  if (state === null) {
+    return { allow: true };
+  }
+
+  // No active claim → allow (nothing to close)
+  if (!state.claimed) {
+    return { allow: true };
+  }
+
+  // Has claim but check if there are still in_progress issues
+  const summary = state.inProgress?.summary ?? null;
+
+  // Session has claim → block (need to close first)
+  return {
+    allow: false,
+    reason: 'unclosed_claim',
+    summary,
+    claimed: state.claimId,
+  };
+}
+
+/**
+ * Decide whether to allow or block a stop operation.
+ * Returns { allow: boolean, reason?: string, summary?: string, claimed?: string }
+ */
+export function decideStopGate(ctx, state) {
+  // Not a beads project → allow
+  if (!ctx.isBeadsProject) {
+    return { allow: true };
+  }
+
+  // bd unavailable → fail open
+  if (state === null) {
+    return { allow: true };
+  }
+
+  // No active claim → allow
+  if (!state.claimed) {
+    // But check for global in_progress (no session_id fallback)
+    if (!ctx.sessionId && state.inProgress && state.inProgress.count > 0) {
+      return {
+        allow: false,
+        reason: 'global_in_progress',
+        summary: state.inProgress.summary,
+      };
+    }
+    return { allow: true };
+  }
+
+  // Has claim but no in_progress issues → allow (stale claim)
+  if (!state.inProgress || state.inProgress.count === 0) {
+    return { allow: true };
+  }
+
+  // Has claim + in_progress issues → block
+  return {
+    allow: false,
+    reason: 'unclosed_claim',
+    summary: state.inProgress.summary,
+    claimed: state.claimId,
+  };
+}

package/hooks/beads-gate-messages.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// beads-gate-messages.mjs — centralized message templates for beads gate hooks
+// Import from sibling hooks using: import { ... } from './beads-gate-messages.mjs';
+//
+// All user-facing strings live here. Edit this file to change messaging.
+// Policy logic lives in beads-gate-core.mjs.
+
+// ── Shared workflow steps ────────────────────────────────────────────────────
+
+export const WORKFLOW_STEPS =
+  '  1. git checkout -b feature/<name>         ← start here\n' +
+  '  2. bd create + bd update in_progress      track your work\n' +
+  '  3. Edit files / write code\n' +
+  '  4. bd close <id> && git add && git commit\n' +
+  '  5. git push -u origin feature/<name>\n' +
+  '  6. gh pr create --fill && gh pr merge --squash\n' +
+  '  7. git checkout master && git reset --hard origin/master\n';
+
+export const SESSION_CLOSE_PROTOCOL =
+  '  3. bd close <id1> <id2> ...               close all in_progress issues\n' +
+  '  4. git add <files> && git commit -m "..."  commit your changes\n' +
+  '  5. git push -u origin <feature-branch>     push feature branch\n' +
+  '  6. gh pr create --fill                     create PR\n' +
+  '  7. gh pr merge --squash                    merge PR\n' +
+  '  8. git checkout master && git reset --hard origin/master\n';
+
+export const COMMIT_NEXT_STEPS =
+  '  3. bd close <id1> <id2> ...             ← you are here\n' +
+  '  4. git add <files> && git commit -m "..."\n' +
+  '  5. git push -u origin <feature-branch>\n' +
+  '  6. gh pr create --fill && gh pr merge --squash\n' +
+  '  7. git checkout master && git reset --hard origin/master\n';
+
+// ── Edit gate messages ───────────────────────────────────────────────────────
+
+export function editBlockMessage(sessionId) {
+  return (
+    '🚫 BEADS GATE: This session has no active claim — claim an issue before editing files.\n\n' +
+    '  bd update <id> --status=in_progress\n' +
+    `  bd kv set "claimed:${sessionId}" "<id>"\n\n` +
+    'Or create a new issue:\n' +
+    '  bd create --title="<what you\'re doing>" --type=task --priority=2\n' +
+    '  bd update <id> --status=in_progress\n' +
+    `  bd kv set "claimed:${sessionId}" "<id>"\n`
+  );
+}
+
+export function editBlockFallbackMessage() {
+  return (
+    '🚫 BEADS GATE: No active issue — create one before editing files.\n\n' +
+    '  bd create --title="<what you\'re doing>" --type=task --priority=2\n' +
+    '  bd update <id> --status=in_progress\n\n' +
+    'Full workflow (do this every session):\n' +
+    WORKFLOW_STEPS
+  );
+}
+
+// ── Commit gate messages ─────────────────────────────────────────────────────
+
+export function commitBlockMessage(summary, claimed) {
+  const issueSummary = summary ?? `  Claimed: ${claimed}`;
+  return (
+    '🚫 BEADS GATE: Close open issues before committing.\n\n' +
+    `Open issues:\n${issueSummary}\n\n` +
+    'Next steps:\n' + COMMIT_NEXT_STEPS
+  );
+}
+
+// ── Stop gate messages ───────────────────────────────────────────────────────
+
+export function stopBlockMessage(summary, claimed) {
+  const issueSummary = summary ?? `  Claimed: ${claimed}`;
+  return (
+    '🚫 BEADS STOP GATE: Unresolved issues — complete the session close protocol.\n\n' +
+    `Open issues:\n${issueSummary}\n\n` +
+    'Session close protocol:\n' + SESSION_CLOSE_PROTOCOL
+  );
+}
+
+// ── Memory gate messages ─────────────────────────────────────────────────────
+
+export function memoryPromptMessage() {
+  return (
+    '🧠 MEMORY GATE: Before ending the session, evaluate this session\'s work.\n\n' +
+    'For each issue you worked on and closed, ask:\n' +
+    '  Is this a stable pattern, key decision, or solution I\'ll encounter again?\n\n' +
+    '  YES → bd remember "<precise, durable insight>"\n' +
+    '  NO  → explicitly note "nothing worth persisting" and continue\n\n' +
+    'When done, signal completion and stop again:\n' +
+    '  touch .beads/.memory-gate-done\n'
+  );
+}

package/hooks/beads-memory-gate.mjs

@@ -8,18 +8,17 @@
 // Installed by: xtrm install
 
 import { execSync } from 'node:child_process';
-import { readFileSync, existsSync, unlinkSync } from 'node:fs';
+import { existsSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
+import { readHookInput } from './beads-gate-core.mjs';
+import { resolveCwd, isBeadsProject } from './beads-gate-utils.mjs';
+import { memoryPromptMessage } from './beads-gate-messages.mjs';
 
-let input;
-try {
-  input = JSON.parse(readFileSync(0, 'utf8'));
-} catch {
-  process.exit(0);
-}
+const input = readHookInput();
+if (!input) process.exit(0);
 
-const cwd = input.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
-if (!existsSync(join(cwd, '.beads'))) process.exit(0);
+const cwd = resolveCwd(input);
+if (!cwd || !isBeadsProject(cwd)) process.exit(0);
 
 // Agent signals evaluation complete by touching this marker, then stops again
 const marker = join(cwd, '.beads', '.memory-gate-done');
@@ -44,13 +43,5 @@ try {
 
 if (!hasClosed) process.exit(0);
 
-process.stderr.write(
-  '🧠 MEMORY GATE: Before ending the session, evaluate this session\'s work.\n\n' +
-  'For each issue you worked on and closed, ask:\n' +
-  '  Is this a stable pattern, key decision, or solution I\'ll encounter again?\n\n' +
-  '  YES → bd remember "<precise, durable insight>"\n' +
-  '  NO  → explicitly note "nothing worth persisting" and continue\n\n' +
-  'When done, signal completion and stop again:\n' +
-  '  touch .beads/.memory-gate-done\n'
-);
+process.stderr.write(memoryPromptMessage());
 process.exit(2);