xtrm-tools 2.1.17 → 2.1.21

package/config/pi/extensions/quality-gates.ts

@@ -0,0 +1,67 @@
+import type { ExtensionAPI, ToolResultEvent } from "@mariozechner/pi-coding-agent";
+import { SubprocessRunner, EventAdapter, Logger } from "./core";
+import * as path from "node:path";
+import * as fs from "node:fs";
+
+const logger = new Logger({ namespace: "quality-gates" });
+
+export default function (pi: ExtensionAPI) {
+	pi.on("tool_result", async (event, ctx) => {
+		if (!EventAdapter.isMutatingFileTool(event)) return undefined;
+
+		const cwd = ctx.cwd || process.cwd();
+		const filePath = EventAdapter.extractPathFromToolInput(event, cwd);
+		if (!filePath) return undefined;
+
+		const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+		const ext = path.extname(fullPath);
+
+		let scriptPath: string | null = null;
+		let runner: string = "node";
+
+		if ([".ts", ".tsx", ".js", ".jsx"].includes(ext)) {
+			scriptPath = path.join(cwd, ".claude", "hooks", "quality-check.cjs");
+			runner = "node";
+		} else if (ext === ".py") {
+			scriptPath = path.join(cwd, ".claude", "hooks", "quality-check.py");
+			runner = "python3";
+		}
+
+		if (!scriptPath || !fs.existsSync(scriptPath)) return undefined;
+
+		const hookInput = JSON.stringify({
+			tool_name: event.toolName,
+			tool_input: event.input,
+			cwd: cwd,
+		});
+
+		const result = await SubprocessRunner.run(runner, [scriptPath], {
+			cwd,
+			input: hookInput,
+			env: { ...process.env, CLAUDE_PROJECT_DIR: cwd },
+			timeoutMs: 30000,
+		});
+
+		if (result.code === 0) {
+			if (result.stderr && result.stderr.trim()) {
+				const newContent = [...event.content];
+				newContent.push({ type: "text", text: `\n\n**Quality Gate**: ${result.stderr.trim()}` });
+				return { content: newContent };
+			}
+			return undefined;
+		}
+
+		if (result.code === 2) {
+			const newContent = [...event.content];
+			newContent.push({ type: "text", text: `\n\n**Quality Gate FAILED**:\n${result.stderr || result.stdout || "Unknown error"}` });
+			
+			if (ctx.hasUI) {
+				ctx.ui.notify(`Quality Gate failed for ${path.basename(fullPath)}`, "error");
+			}
+
+			return { isError: true, content: newContent };
+		}
+
+		return undefined;
+	});
+}

package/config/pi/extensions/service-skills.ts

@@ -0,0 +1,88 @@
+import type { ExtensionAPI, ToolCallEvent, ToolResultEvent } from "@mariozechner/pi-coding-agent";
+import { isToolCallEventType, isBashToolResult } from "@mariozechner/pi-coding-agent";
+import { SubprocessRunner, Logger } from "./core";
+import * as path from "node:path";
+import * as fs from "node:fs";
+
+const logger = new Logger({ namespace: "service-skills" });
+
+export default function (pi: ExtensionAPI) {
+	const getCwd = (ctx: any) => ctx.cwd || process.cwd();
+
+	// 1. Catalog Injection
+	pi.on("before_agent_start", async (event, ctx) => {
+		const cwd = getCwd(ctx);
+		const catalogerPath = path.join(cwd, ".claude", "skills", "using-service-skills", "scripts", "cataloger.py");
+		if (!fs.existsSync(catalogerPath)) return undefined;
+
+		const result = await SubprocessRunner.run("python3", [catalogerPath], {
+			cwd,
+			env: { ...process.env, CLAUDE_PROJECT_DIR: cwd }
+		});
+
+		if (result.code === 0 && result.stdout.trim()) {
+			return { systemPrompt: event.systemPrompt + "\n\n" + result.stdout.trim() };
+		}
+		return undefined;
+	});
+
+	// 2. Territory Activation
+	pi.on("tool_call", async (event, ctx) => {
+		const cwd = getCwd(ctx);
+		const activatorPath = path.join(cwd, ".claude", "skills", "using-service-skills", "scripts", "skill_activator.py");
+		if (!fs.existsSync(activatorPath)) return undefined;
+
+		const hookInput = JSON.stringify({
+			tool_name: event.toolName === "bash" ? "Bash" : event.toolName,
+			tool_input: event.input,
+			cwd: cwd
+		});
+
+		const result = await SubprocessRunner.run("python3", [activatorPath], {
+			cwd,
+			input: hookInput,
+			env: { ...process.env, CLAUDE_PROJECT_DIR: cwd },
+			timeoutMs: 5000
+		});
+
+		if (result.code === 0 && result.stdout.trim()) {
+			try {
+				const parsed = JSON.parse(result.stdout.trim());
+				const context = parsed.hookSpecificOutput?.additionalContext;
+				if (context && ctx.hasUI) {
+					ctx.ui.notify(context, "info");
+				}
+			} catch (e) {
+				logger.error("Failed to parse skill_activator output", e);
+			}
+		}
+		return undefined;
+	});
+
+	// 3. Drift Detection
+	pi.on("tool_result", async (event, ctx) => {
+		const cwd = getCwd(ctx);
+		const driftDetectorPath = path.join(cwd, ".claude", "skills", "updating-service-skills", "scripts", "drift_detector.py");
+		if (!fs.existsSync(driftDetectorPath)) return undefined;
+
+		const hookInput = JSON.stringify({
+			tool_name: event.toolName === "bash" ? "Bash" : event.toolName,
+			tool_input: event.input,
+			cwd: cwd
+		});
+
+		const result = await SubprocessRunner.run("python3", [driftDetectorPath], {
+			cwd,
+			input: hookInput,
+			env: { ...process.env, CLAUDE_PROJECT_DIR: cwd },
+			timeoutMs: 10000
+		});
+
+		if (result.code === 0 && result.stdout.trim()) {
+			const newContent = [...event.content];
+			newContent.push({ type: "text", text: "\n\n" + result.stdout.trim() });
+			return { content: newContent };
+		}
+		return undefined;
+	});
+}

package/config/pi/extensions/xtrm-loader.ts

@@ -0,0 +1,89 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { Logger } from "./core";
+
+const logger = new Logger({ namespace: "xtrm-loader" });
+
+/**
+ * Recursively find markdown files in a directory.
+ */
+function findMarkdownFiles(dir: string, basePath: string = ""): string[] {
+	const results: string[] = [];
+	if (!fs.existsSync(dir)) return results;
+
+	const entries = fs.readdirSync(dir, { withFileTypes: true });
+	for (const entry of entries) {
+		const relativePath = basePath ? `${basePath}/${entry.name}` : entry.name;
+		if (entry.isDirectory()) {
+			results.push(...findMarkdownFiles(path.join(dir, entry.name), relativePath));
+		} else if (entry.isFile() && entry.name.endsWith(".md")) {
+			results.push(relativePath);
+		}
+	}
+	return results;
+}
+
+export default function (pi: ExtensionAPI) {
+	let projectContext: string = "";
+
+	pi.on("session_start", async (_event, ctx) => {
+		const cwd = ctx.cwd;
+		const contextParts: string[] = [];
+
+		// 1. Architecture & Roadmap
+		const roadmapPaths = [
+			path.join(cwd, "architecture", "project_roadmap.md"),
+			path.join(cwd, "ROADMAP.md"),
+			path.join(cwd, "architecture", "index.md")
+		];
+
+		for (const p of roadmapPaths) {
+			if (fs.existsSync(p)) {
+				const content = fs.readFileSync(p, "utf8");
+				contextParts.push(`## Project Roadmap & Architecture (${path.relative(cwd, p)})\n\n${content}`);
+				break; // Only load the first one found
+			}
+		}
+
+		// 2. Project Rules (.claude/rules)
+		const rulesDir = path.join(cwd, ".claude", "rules");
+		if (fs.existsSync(rulesDir)) {
+			const ruleFiles = findMarkdownFiles(rulesDir);
+			if (ruleFiles.length > 0) {
+				const rulesContent = ruleFiles.map(f => {
+					const content = fs.readFileSync(path.join(rulesDir, f), "utf8");
+					return `### Rule: ${f}\n${content}`;
+				}).join("\n\n");
+				contextParts.push(`## Project Rules\n\n${rulesContent}`);
+			}
+		}
+
+		// 3. Project Skills (.claude/skills)
+		const skillsDir = path.join(cwd, ".claude", "skills");
+		if (fs.existsSync(skillsDir)) {
+			const skillFiles = findMarkdownFiles(skillsDir);
+			if (skillFiles.length > 0) {
+				const skillsContent = skillFiles.map(f => {
+					// We only want to list the paths/names so the agent knows what it can read
+					return `- ${f} (Path: .claude/skills/${f})`;
+				}).join("\n");
+				contextParts.push(`## Available Project Skills\n\nExisting service skills and workflows found in .claude/skills/:\n\n${skillsContent}\n\nUse the read tool to load any of these skills if relevant to the current task.`);
+			}
+		}
+
+		projectContext = contextParts.join("\n\n---\n\n");
+		
+		if (projectContext && ctx.hasUI) {
+			ctx.ui.notify("XTRM-Loader: Project context and skills indexed", "info");
+		}
+	});
+
+	pi.on("before_agent_start", async (event) => {
+		if (!projectContext) return undefined;
+
+		return {
+			systemPrompt: event.systemPrompt + "\n\n# Project Intelligence Context\n\n" + projectContext
+		};
+	});
+}

package/hooks/README.md

@@ -1,350 +1,75 @@
 # Hooks
 
-Claude Code hooks that extend agent behavior with automated checks, suggestions, and workflow enhancements.
+Claude Code hooks that extend agent behavior with automated checks, workflow enhancements, and safety guardrails.
 
 ## Overview
 
-Hooks intercept specific events in the Claude Code lifecycle to provide:
-- Proactive skill suggestions
-- Safety guardrails (venv enforcement, type checking)
-- Workflow reminders
-- Status information
+Hooks intercept specific events in the Claude Code lifecycle. Following architecture decisions in v2.0.0+, the hook ecosystem is designed exclusively for Claude Code.
 
-## Skill-Associated Hooks
+*Note: In v2.1.15+, several older hooks (`skill-suggestion.py`, `skill-discovery.py`, `gitnexus-impact-reminder.py`, and `type-safety-enforcement.py`) were removed or superseded by native capabilities, CLI commands, and consolidated quality gates.*
 
-### skill-suggestion.py
+## Project Hooks
 
-**Purpose**: Proactively suggests `/prompt-improving` or `/delegating` based on prompt analysis.
+### main-guard.mjs
 
-**Trigger**: UserPromptSubmit
+**Purpose**: Enforces PR-only merge workflow with full git protection. Blocks direct commits and dangerous `git checkout`, `git reset`, and file writes via Bash on protected branches (`main`/`master`).
 
-**Skills**: 
-- `prompt-improving` - Suggested for short/generic prompts
-- `delegating` - Suggested for simple tasks or explicit delegation requests
+**Trigger**: PreToolUse (Write|Edit|MultiEdit|Serena edit tools|Bash)
 
-**Configuration**:
-```json
-{
-  "hooks": {
-    "UserPromptSubmit": [{
-      "hooks": [{
-        "type": "command",
-        "command": "/home/user/.claude/hooks/skill-suggestion.py",
-        "timeout": 5000  // Claude: seconds (5000s), Gemini: milliseconds (5s)
-      }]
-    }]
-  },
-  "skillSuggestions": {
-    "enabled": true
-  }
-}
-```
+**Configuration**: Installed automatically to protect the main branch from unreviewed changes.
 
-### skill-discovery.py
+### main-guard-post-push.mjs
 
-**Purpose**: Scans the `@skills/` directory for `SKILL.md` files and injects a summarized list of all available local skills into the agent's context at the start of a session.
+**Purpose**: Workflow enforcement. After pushing a feature branch, reminds to open a PR, merge using `gh pr merge --squash`, and sync local via `git reset --hard origin/main`.
 
-**Trigger**: SessionStart
+**Trigger**: PostToolUse (Bash: git push)
 
-**Skills**: All skills found in the repository's `skills/` directory.
+### gitnexus-hook.cjs
 
-**Configuration**:
-```json
-{
-  "hooks": {
-    "SessionStart": [{
-      "hooks": [{
-        "type": "command",
-        "command": "/home/user/.claude/hooks/skill-discovery.py",
-        "timeout": 5000
-      }]
-    }]
-  }
-}
-```
+**Purpose**: Enriches tool calls with knowledge graph context via `gitnexus augment`. Now supports Serena tools and uses a deduplication cache for efficiency.
 
-### serena-workflow-reminder.py
+**Trigger**: PostToolUse (Grep|Glob|Bash|Serena edit tools)
 
-**Purpose**: Enforces semantic workflow using "Using Serena LSP".
+## Beads Issue Tracking Gates
 
-**Triggers**: 
-- `SessionStart`: Injects skill context.
-- `PreToolUse` (Read|Edit): Blocks inefficient usage.
+The beads gate hooks integrate the `bd` (beads) issue tracker directly into Claude's workflow, ensuring no code changes happen without an active ticket.
 
-**Skill**: `using-serena-lsp`
+**Installation**: Installed with `xtrm install all` or included when `beads`+`dolt` is available.
 
-**Configuration**:
-```json
-{
-  "hooks": {
-    "SessionStart": [{
-      "hooks": [{ "type": "command", "command": "/home/user/.claude/hooks/serena-workflow-reminder.py" }]
-    }],
-    "PreToolUse": [{
-      "matcher": "Read|Edit",
-      "hooks": [{ "type": "command", "command": "/home/user/.claude/hooks/serena-workflow-reminder.py" }]
-    }]
-  }
-}
-```
+### Core Gates
+- **`beads-edit-gate.mjs`** (PreToolUse) — Blocks writes/edits without an active issue claim.
+- **`beads-commit-gate.mjs`** (PreToolUse) — Blocks commits with an unresolved session claim.
+- **`beads-stop-gate.mjs`** (Stop) — Blocks session stop while a claim remains open.
+- **`beads-close-memory-prompt.mjs`** (PostToolUse) — Prompts memory handoff after `bd close`.
 
-## Standalone Hooks
+### Compaction & State Preservation (v2.1.18+)
+- **`beads-pre-compact.mjs`** (PreCompact) — Saves the currently `in_progress` beads state before Claude clears context.
+- **`beads-session-start.mjs`** (SessionStart) — Restores the `in_progress` state when the session restarts after compaction.
 
-### pip-venv-guard.py
+*Note: As of v2.1.18+, hook blocking messages are quieted and compacted to save tokens.*
 
-**Purpose**: Prevents accidental `pip install` outside virtual environments.
+## Hook Timeouts
 
-**Trigger**: PreToolUse (Bash)
+Adjust hook execution timeouts in `settings.json` if commands take longer than expected:
 
-**Configuration**:
 ```json
 {
   "hooks": {
-    "PreToolUse": [{
-      "matcher": "Bash",
+    "PostToolUse": [{
       "hooks": [{
-        "type": "command",
-        "command": "/home/user/.claude/hooks/pip-venv-guard.py",
-        "timeout": 3000  // 3 seconds in milliseconds (both Claude & Gemini)
+        "timeout": 5000  // Timeout in milliseconds (5000ms = 5 seconds)
       }]
     }]
   }
 }
 ```
 
-### type-safety-enforcement.py
-
-**Purpose**: Enforces type safety checks in Python code before execution.
-
-**Trigger**: PreToolUse (Bash, Edit, Write)
-
-**Configuration**:
-```json
-{
-  "hooks": {
-    "PreToolUse": [{
-      "matcher": "Bash|Edit|Write",
-      "hooks": [{
-        "type": "command",
-        "command": "/home/user/.claude/hooks/type-safety-enforcement.py",
-        "timeout": 10000  // 10 seconds in milliseconds (both Claude & Gemini)
-      }]
-    }]
-  }
-}
-```
-
-### statusline.js
-
-**Purpose**: Displays custom status line information.
-**Trigger**: StatusLine
-
-## Workflow Enforcement Hooks (JavaScript)
-
-Installed globally to `~/.claude/hooks/` by `xtrm install`. Require Node.js.
-
-### main-guard.mjs
-
-**Purpose**: Blocks direct file edits and dangerous git operations on protected branches (`main`/`master`). Enforces the feature-branch → PR workflow.
-
-**Trigger**: PreToolUse (`Edit|Write|MultiEdit|NotebookEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol|Bash`)
-
-**Blocks**:
-- Write/Edit/MultiEdit/NotebookEdit on protected branches
-- `git commit` directly on protected branches
-- `git push` to protected branches
-
-**Configuration** (global Claude config):
-```json
-{
-  "hooks": {
-    "PreToolUse": [{
-      "matcher": "Edit|Write|MultiEdit|NotebookEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol|Bash",
-      "hooks": [{ "type": "command", "command": "node \"~/.claude/hooks/main-guard.mjs\"", "timeout": 5000 }]
-    }]
-  }
-}
-```
-
----
-
-### main-guard-post-push.mjs
-
-**Purpose**: After a successful `git push` from a non-protected branch, injects a reminder for the next PR workflow steps.
-
-**Trigger**: PostToolUse (`Bash`) — only fires when command matches `git push` and appears successful.
-
-**Behavior**:
-- No blocking (informational only)
-- Skips protected branches (`main`/`master`)
-- Skips explicit pushes targeting protected branches
-
-**Guidance injected**:
-- `gh pr create --fill`
-- `gh pr merge --squash`
-- `git checkout main && git pull --ff-only`
-- Reminder to keep beads issue state updated
-
----
-
-### beads-gate-utils.mjs
-
-**Purpose**: Shared utility module imported by all beads gate hooks. Not registered as a hook itself.
-
-**Exports**: `resolveCwd`, `isBeadsProject`, `getSessionClaim`, `getTotalWork`, `getInProgress`, `clearSessionClaim`, `withSafeBdContext`
-
-**Requires**: `bd` (beads CLI), `dolt`
-
----
-
-### beads-edit-gate.mjs
-
-**Purpose**: Blocks file edits when the current session has not claimed a beads issue via `bd kv`. Prevents free-riding in multi-agent and multi-session scenarios.
-
-**Trigger**: PreToolUse (`Edit|Write|MultiEdit|NotebookEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol`)
-
-**Behavior**:
-- Session has claim (`bd kv get "claimed:<session_id>"`) → allow
-- No claim + no trackable work → allow (clean-start state)
-- No claim + open/in_progress issues exist → block
-- Falls back to global in_progress check when `session_id` is absent
-
-**Requires**: `bd`, `dolt`
-
----
-
-### beads-commit-gate.mjs
-
-**Purpose**: Blocks `git commit` when the current session still has an unclosed beads claim.
-
-**Trigger**: PreToolUse (`Bash`) — only fires when command matches `git commit`
-
-**Requires**: `bd`, `dolt`
-
----
-
-### beads-stop-gate.mjs
-
-**Purpose**: Blocks the agent from stopping when the current session has an unclosed beads claim.
-
-**Trigger**: Stop
-
-**Requires**: `bd`, `dolt`
-
----
-
-### beads-close-memory-prompt.mjs
-
-**Purpose**: After `bd close`, clears the session's kv claim and injects a reminder to capture knowledge before moving on.
-
-**Trigger**: PostToolUse (`Bash`) — only fires when command matches `bd close`
-
-**Requires**: `bd`, `dolt`
-
----
-
-## Beads claim workflow
-
-```bash
-# Claim an issue before editing
-bd update <id> --status=in_progress
-bd kv set "claimed:<session_id>" "<id>"
-
-# Edit files freely
-# ...
-
-# Close when done — hook auto-clears the claim
-bd close <id>
-```
-
----
-
-## Installation
-
-Use `xtrm install` to deploy all hooks automatically. For manual setup:
-
-1. Copy hooks to the global Claude Code directory:
-   ```bash
-   cp hooks/*.mjs hooks/*.py ~/.claude/hooks/
-   ```
-
-2. Make scripts executable:
-   ```bash
-   chmod +x ~/.claude/hooks/*.mjs ~/.claude/hooks/*.py
-   ```
-
-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
+## Creating Custom Hooks
 
-| 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) |
+To create new project-specific hooks, use the `hook-development` global skill. Follow the canonical structure defined in the `xtrm-tools` core libraries.
 
-### Exit Semantics
+For debugging orphaned hooks, use `xtrm clean`.
 
-All hooks follow strict exit semantics:
-- `exit 0` — Allow the operation
-- `exit 2` — Block with message shown to Claude
+## Pi Extensions Migration
 
-The core functions are pure and never call `process.exit()`. Entrypoints are responsible for side effects.
+Core workflow hooks have been migrated to native Pi Extensions for better performance and integration. See the [Pi Extensions Migration Guide](../docs/pi-extensions-migration.md) for details.