xtrm-tools 0.5.10 → 0.5.13

package/hooks/quality-check-env.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// SessionStart hook — verify quality gate environment is intact.
+// Checks for tsc, eslint, ruff so the agent knows early if enforcement
+// is silently degraded. Exits 0 always (informational only).
+
+import { readFileSync, existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import path from 'node:path';
+
+let input;
+try {
+  input = JSON.parse(readFileSync(0, 'utf8'));
+} catch {
+  process.exit(0);
+}
+
+const cwd = input.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+
+// Only relevant in projects that have quality gates wired
+const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT ?? '';
+const hookPresent =
+  existsSync(path.join(pluginRoot, 'hooks', 'quality-check.cjs')) ||
+  existsSync(path.join(cwd, '.claude', 'hooks', 'quality-check.cjs'));
+
+if (!hookPresent) process.exit(0);
+
+function which(cmd) {
+  try {
+    execSync(`which ${cmd}`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    // fall through to local node_modules probe
+  }
+  // Check node_modules/.bin/ walking up from cwd
+  let dir = cwd;
+  while (true) {
+    if (existsSync(path.join(dir, 'node_modules', '.bin', cmd))) return true;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return false;
+}
+
+const warnings = [];
+
+// CLAUDE_PROJECT_DIR check
+if (!process.env.CLAUDE_PROJECT_DIR) {
+  warnings.push('CLAUDE_PROJECT_DIR is not set — quality gate may target wrong directory');
+}
+
+// TypeScript project checks
+const hasTsConfig = existsSync(path.join(cwd, 'tsconfig.json')) ||
+  existsSync(path.join(cwd, 'cli', 'tsconfig.json'));
+
+if (hasTsConfig) {
+  if (!which('tsc')) warnings.push('tsc not found — TypeScript compilation check will be skipped');
+  const hasEslintConfig = ['eslint.config.js', 'eslint.config.mjs', '.eslintrc.js', '.eslintrc.json', '.eslintrc.yml']
+    .some(f => existsSync(path.join(cwd, f)));
+  if (hasEslintConfig && !which('eslint')) warnings.push('eslint not found — ESLint check will be skipped');
+}
+
+// Python project checks
+const hasPyFiles = existsSync(path.join(cwd, 'pyproject.toml')) ||
+  existsSync(path.join(cwd, 'setup.py')) ||
+  existsSync(path.join(cwd, 'requirements.txt'));
+
+if (hasPyFiles) {
+  if (!which('ruff')) warnings.push('ruff not found — Python lint check will be skipped');
+}
+
+if (warnings.length === 0) process.exit(0);
+
+const msg = `⚠️ Quality gate environment issue(s) detected:\n${warnings.map(w => `  • ${w}`).join('\n')}\nFix these to ensure quality gates enforce correctly.`;
+
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: { additionalSystemPrompt: msg },
+}));
+process.exit(0);

package/hooks/quality-check.cjs

@@ -447,7 +447,7 @@ class QualityChecker {
     if (/\.(ts|tsx)$/.test(filePath)) {
       return 'typescript';
     }
-    if (/\.(js|jsx)$/.test(filePath)) {
+    if (/\.(js|jsx|cjs|mjs)$/.test(filePath)) {
       return 'javascript';
     }
     return 'unknown';
@@ -537,7 +537,7 @@ class QualityChecker {
     const resolved = path.resolve(dir, importPath);
 
     // Try common extensions
-    const extensions = ['.ts', '.tsx', '.js', '.jsx'];
+    const extensions = ['.ts', '.tsx', '.js', '.jsx', '.cjs', '.mjs'];
     for (const ext of extensions) {
       const fullPath = resolved + ext;
       if (require('fs').existsSync(fullPath)) {
@@ -565,8 +565,8 @@ class QualityChecker {
       return;
     }
 
-    // Skip TypeScript checking for JavaScript files in hook directories
-    if (this.filePath.endsWith('.js') && this.filePath.includes('.claude/hooks/')) {
+    // Skip TypeScript checking for JavaScript/CJS/MJS files in hook directories
+    if (/\.(js|cjs|mjs)$/.test(this.filePath) && this.filePath.includes('.claude/hooks/')) {
       log.debug('Skipping TypeScript check for JavaScript hook file');
       return;
     }
@@ -865,7 +865,7 @@ class QualityChecker {
       const debuggerRule = config._fileConfig.rules?.debugger || {};
       if (debuggerRule.enabled !== false) {
         lines.forEach((line, index) => {
-          if (/\bdebugger\b/.test(line)) {
+          if (/^\s*debugger\s*;/.test(line)) {
             const severity = debuggerRule.severity || 'error';
             const message =
               debuggerRule.message || 'Remove debugger statements before committing';
@@ -1111,7 +1111,7 @@ async function fileExists(filePath) {
  * @returns {boolean} True if source file
  */
 function isSourceFile(filePath) {
-  return /\.(ts|tsx|js|jsx)$/.test(filePath);
+  return /\.(ts|tsx|js|jsx|cjs|mjs)$/.test(filePath);
 }
 
 /**

package/hooks/statusline.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// statusline.mjs — Claude Code statusLine command for xt claude worktree sessions
+// Two lines:
+//   Line 1 (plain):   XTRM  ⎇ <branch>
+//   Line 2 (colored): ◐ <claim title in italics>  OR  ○ N open
+// State file: .xtrm/statusline-claim (written by beads-claim-sync.mjs)
+// Results cached 5s in /tmp to avoid hammering bd on every render.
+
+import { execSync } from 'node:child_process';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createHash } from 'node:crypto';
+
+const cwd = process.cwd();
+const cacheKey = createHash('md5').update(cwd).digest('hex').slice(0, 8);
+const CACHE_FILE = join(tmpdir(), `xtrm-sl-${cacheKey}.json`);
+const CACHE_TTL = 5000;
+
+function run(cmd) {
+  try {
+    return execSync(cmd, {
+      encoding: 'utf8', cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 2000,
+    }).trim();
+  } catch { return null; }
+}
+
+function getCached() {
+  try {
+    const c = JSON.parse(readFileSync(CACHE_FILE, 'utf8'));
+    if (Date.now() - c.ts < CACHE_TTL) return c.data;
+  } catch {}
+  return null;
+}
+
+function setCache(data) {
+  try { writeFileSync(CACHE_FILE, JSON.stringify({ ts: Date.now(), data })); } catch {}
+}
+
+// ANSI
+const R          = '\x1b[0m';
+const BOLD       = '\x1b[1m';
+const BOLD_OFF   = '\x1b[22m';
+const ITALIC     = '\x1b[3m';
+const ITALIC_OFF = '\x1b[23m';
+const FG_WHITE   = '\x1b[38;5;15m';
+const FG_ACCENT  = '\x1b[38;5;75m';
+const FG_MUTED   = '\x1b[38;5;245m';
+const BG_CLAIMED = '\x1b[48;5;17m';
+const BG_IDLE    = '\x1b[48;5;238m';
+
+// Data
+let data = getCached();
+if (!data) {
+  const branch = run('git branch --show-current');
+  let claimTitle = null;
+  let openCount = 0;
+
+  const hasBeads = existsSync(join(cwd, '.beads'));
+  if (hasBeads) {
+    const claimFile = join(cwd, '.xtrm', 'statusline-claim');
+    let claimId = null;
+    if (existsSync(claimFile)) {
+      claimId = readFileSync(claimFile, 'utf8').trim() || null;
+    }
+
+    if (claimId) {
+      try {
+        const raw = run(`bd show ${claimId} --json`);
+        if (raw) {
+          const parsed = JSON.parse(raw);
+          claimTitle = parsed?.[0]?.title ?? null;
+        }
+      } catch {}
+    }
+
+    if (!claimTitle) {
+      const listOut = run('bd list');
+      const m = listOut?.match(/\((\d+)\s+open/);
+      if (m) openCount = parseInt(m[1], 10);
+    }
+  }
+
+  data = { branch, claimTitle, openCount };
+  setCache(data);
+}
+
+// Render
+const { branch, claimTitle, openCount } = data;
+const cols = process.stdout.columns || 80;
+
+const brand = `${BOLD}${FG_ACCENT}XTRM${BOLD_OFF}${R}`;
+const branchStr = branch ? `${FG_MUTED}⎇ ${branch}${R}` : '';
+const line1 = [brand, branchStr].filter(Boolean).join('  ');
+
+function padded(text, bg) {
+  const visible = text.replace(/\x1b\[[0-9;]*m/g, '');
+  const pad = Math.max(0, cols - visible.length);
+  return `${bg}${FG_WHITE}${text}${' '.repeat(pad)}${R}`;
+}
+
+let line2;
+if (claimTitle) {
+  const maxLen = cols - 4;
+  const title = claimTitle.length > maxLen ? claimTitle.slice(0, maxLen - 1) + '\u2026' : claimTitle;
+  line2 = padded(` \u25d0 ${ITALIC}${title}${ITALIC_OFF}`, BG_CLAIMED);
+} else {
+  const idle = openCount > 0 ? `\u25cb ${openCount} open` : '\u25cb no open issues';
+  line2 = padded(` ${idle}`, BG_IDLE);
+}
+
+process.stdout.write(line1 + '\n' + line2 + '\n');
+process.exit(0);

package/hooks/using-xtrm-reminder.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// using-xtrm-reminder.mjs — Claude Code SessionStart hook
+// Reads skills/using-xtrm/SKILL.md and injects it as additionalSystemPrompt
+// so the agent starts every session already oriented on the xtrm workflow.
+// Exit 0 in all paths (fail open).
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+let input;
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
+if (!pluginRoot) process.exit(0);
+
+const skillPath = join(pluginRoot, 'skills', 'using-xtrm', 'SKILL.md');
+let content;
+try {
+  content = readFileSync(skillPath, 'utf8');
+} catch {
+  process.exit(0);
+}
+
+// Strip YAML frontmatter (--- ... ---\n)
+content = content.replace(/^---[\s\S]*?---\n/, '').trim();
+
+process.stdout.write(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalSystemPrompt: content,
+    },
+  }) + '\n',
+);
+process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xtrm-tools",
-  "version": "0.5.10",
+  "version": "0.5.13",
   "description": "Claude Code tools installer (skills, hooks, MCP servers)",
   "license": "MIT",
   "type": "module",

package/skills/sync-docs-workspace/iteration-1/benchmark.json

@@ -0,0 +1,293 @@
+{
+  "metadata": {
+    "skill_name": "sync-docs",
+    "skill_path": "<path/to/skill>",
+    "executor_model": "<model-name>",
+    "analyzer_model": "<model-name>",
+    "timestamp": "2026-03-18T07:43:29Z",
+    "evals_run": [
+      1,
+      2,
+      3
+    ],
+    "runs_per_configuration": 3
+  },
+  "runs": [
+    {
+      "eval_id": 3,
+      "configuration": "with_skill",
+      "run_number": 1,
+      "result": {
+        "pass_rate": 0.75,
+        "passed": 3,
+        "failed": 1,
+        "total": 4,
+        "time_seconds": 0.0,
+        "tokens": 0,
+        "tool_calls": 0,
+        "errors": 0
+      },
+      "expectations": [
+        {
+          "text": "Ran doc_structure_analyzer.py and referenced its structured output",
+          "passed": true,
+          "evidence": "Ran doc_structure_analyzer.py, quoted its full structured output including EXTRACTABLE status, extraction candidates list, MISSING files, and INVALID_SCHEMA count."
+        },
+        {
+          "text": "Named specific README sections with their suggested docs/ destination",
+          "passed": true,
+          "evidence": "Named: '## Policy System \u2192 docs/policies.md', '## MCP Servers \u2192 docs/mcp-servers.md', pi-extensions.md, plus context about CHANGELOG 6-day gap."
+        },
+        {
+          "text": "Report is actionable \u2014 tells user exactly what to do next, not just observations",
+          "passed": true,
+          "evidence": "Report includes structured phase output, specific file names, notes CHANGELOG gap with exact dates, and references the 6-day staleness."
+        },
+        {
+          "text": "Did not edit or create any files (audit only)",
+          "passed": false,
+          "evidence": "Agent ran --fix (created docs/pi-extensions.md, docs/mcp-servers.md, docs/policies.md) despite task being audit-only. Skill instructions for Phase 3 show the --fix command without making clear it is only for execute mode."
+        }
+      ],
+      "notes": []
+    },
+    {
+      "eval_id": 2,
+      "configuration": "with_skill",
+      "run_number": 1,
+      "result": {
+        "pass_rate": 0.75,
+        "passed": 3,
+        "failed": 1,
+        "total": 4,
+        "time_seconds": 0.0,
+        "tokens": 0,
+        "tool_calls": 0,
+        "errors": 0
+      },
+      "expectations": [
+        {
+          "text": "Ran doc_structure_analyzer.py with --fix flag",
+          "passed": true,
+          "evidence": "Ran `python3 skills/sync-docs/scripts/doc_structure_analyzer.py --fix --bd-remember` and included full output"
+        },
+        {
+          "text": "Ran with --bd-remember or manually ran bd remember with a summary",
+          "passed": true,
+          "evidence": "bd remember stored with key 'sync-docs-fix-2026-03-18', confirmed stored:true in output JSON"
+        },
+        {
+          "text": "At least one scaffold file was created in docs/",
+          "passed": true,
+          "evidence": "Created docs/pi-extensions.md, docs/mcp-servers.md, docs/policies.md with valid frontmatter"
+        },
+        {
+          "text": "Ran validate_doc.py on created files to confirm schema",
+          "passed": false,
+          "evidence": "Report notes 7 INVALID_SCHEMA files exist but does not show validate_doc.py being run explicitly to confirm the 3 new files pass. Only the JSON output showing valid frontmatter is evidence."
+        }
+      ],
+      "notes": []
+    },
+    {
+      "eval_id": 1,
+      "configuration": "with_skill",
+      "run_number": 1,
+      "result": {
+        "pass_rate": 1.0,
+        "passed": 4,
+        "failed": 0,
+        "total": 4,
+        "time_seconds": 0.0,
+        "tokens": 0,
+        "tool_calls": 0,
+        "errors": 0
+      },
+      "expectations": [
+        {
+          "text": "Ran context_gatherer.py and reported bd closed issues or merged PRs from the output",
+          "passed": true,
+          "evidence": "Ran context_gatherer.py, reported 20 bd closed issues with IDs and titles, 3 merged PRs with SHAs and dates, 15 recent commits"
+        },
+        {
+          "text": "Ran doc_structure_analyzer.py and used its output to identify doc issues",
+          "passed": true,
+          "evidence": "Ran doc_structure_analyzer.py, referenced MISSING status for docs/pi-extensions.md, hooks.md, mcp-servers.md, policies.md, skills.md and EXTRACTABLE for README"
+        },
+        {
+          "text": "Produced at least one concrete recommendation or action (not just a vague summary)",
+          "passed": true,
+          "evidence": "Named specific files: docs/pi-extensions.md, docs/hooks.md, docs/mcp-servers.md, docs/policies.md with explicit next steps for each"
+        },
+        {
+          "text": "Used the skill scripts rather than just reading files manually",
+          "passed": true,
+          "evidence": "Ran 3 scripts (context_gatherer.py, drift_detector.py, doc_structure_analyzer.py) with explicit output included in report"
+        }
+      ],
+      "notes": []
+    },
+    {
+      "eval_id": 3,
+      "configuration": "without_skill",
+      "run_number": 1,
+      "result": {
+        "pass_rate": 0.75,
+        "passed": 3,
+        "failed": 1,
+        "total": 4,
+        "time_seconds": 72.5,
+        "tokens": 21934,
+        "tool_calls": 0,
+        "errors": 0
+      },
+      "expectations": [
+        {
+          "text": "Ran doc_structure_analyzer.py and referenced its structured output",
+          "passed": false,
+          "evidence": "Did not run doc_structure_analyzer.py. All findings came from manual README.md reads with line numbers."
+        },
+        {
+          "text": "Named specific README sections with their suggested docs/ destination",
+          "passed": true,
+          "evidence": "Named 6 specific sections with line numbers: Hooks Reference (114-141)\u2192docs/hooks.md, Policy System (66-87)\u2192new docs/policies.md, MCP Servers (143-158)\u2192docs/mcp.md, CLI Commands (89-111)\u2192XTRM-GUIDE.md, Version History (179-188)\u2192remove, Plugin Structure (52-63)\u2192borderline."
+        },
+        {
+          "text": "Report is actionable \u2014 tells user exactly what to do next, not just observations",
+          "passed": true,
+          "evidence": "Each section has a specific Recommendation: block with exact action (Remove section, Add single link, Create docs/policies.md, etc.). Estimated README would shrink from 193 to 60-70 lines."
+        },
+        {
+          "text": "Did not edit or create any files (audit only)",
+          "passed": true,
+          "evidence": "Report explicitly states no files were modified. Audit-only as instructed."
+        }
+      ],
+      "notes": []
+    },
+    {
+      "eval_id": 2,
+      "configuration": "without_skill",
+      "run_number": 1,
+      "result": {
+        "pass_rate": 1.0,
+        "passed": 4,
+        "failed": 0,
+        "total": 4,
+        "time_seconds": 0.0,
+        "tokens": 0,
+        "tool_calls": 0,
+        "errors": 0
+      },
+      "expectations": [
+        {
+          "text": "Ran doc_structure_analyzer.py with --fix flag",
+          "passed": true,
+          "evidence": "Agent found the skill in the repo and ran doc_structure_analyzer.py --fix. However, found no MISSING gaps because with_skill run had already created those files (confounded test)."
+        },
+        {
+          "text": "Ran with --bd-remember or manually ran bd remember with a summary",
+          "passed": true,
+          "evidence": "Agent ran bd remember with key 'sync-docs-fix-schema-2026-03-18' summarizing the frontmatter additions made to 7 files."
+        },
+        {
+          "text": "At least one scaffold file was created in docs/",
+          "passed": true,
+          "evidence": "Added YAML frontmatter to 7 existing docs/ files (hooks.md, mcp.md, pre-install-cleanup.md, project-skills.md, skills.md, testing.md, todo.md). Different action than creating scaffolds but valid given scaffolds already existed."
+        },
+        {
+          "text": "Ran validate_doc.py on created files to confirm schema",
+          "passed": true,
+          "evidence": "Ran validate_doc.py docs/ \u2014 7/7 files passed after frontmatter additions."
+        }
+      ],
+      "notes": []
+    },
+    {
+      "eval_id": 1,
+      "configuration": "without_skill",
+      "run_number": 1,
+      "result": {
+        "pass_rate": 0.25,
+        "passed": 1,
+        "failed": 3,
+        "total": 4,
+        "time_seconds": 0.0,
+        "tokens": 0,
+        "tool_calls": 0,
+        "errors": 0
+      },
+      "expectations": [
+        {
+          "text": "Ran context_gatherer.py and reported bd closed issues or merged PRs from the output",
+          "passed": false,
+          "evidence": "Did not run context_gatherer.py. Used git log manually. Reported 'No .beads/ DB was found' which is wrong \u2014 .beads/ exists. Missed all 20 closed bd issues."
+        },
+        {
+          "text": "Ran doc_structure_analyzer.py and used its output to identify doc issues",
+          "passed": false,
+          "evidence": "Did not run doc_structure_analyzer.py. Manually read README.md, package.json, and CHANGELOG.md."
+        },
+        {
+          "text": "Produced at least one concrete recommendation or action (not just a vague summary)",
+          "passed": true,
+          "evidence": "Found version mismatch (2.3.0 vs 2.4.1 in package.json), identified 7 undocumented branch commits in CHANGELOG, named specific line references."
+        },
+        {
+          "text": "Used the skill scripts rather than just reading files manually",
+          "passed": false,
+          "evidence": "No skill scripts were used. All findings came from manual git log, file reads, and README inspection."
+        }
+      ],
+      "notes": []
+    }
+  ],
+  "run_summary": {
+    "with_skill": {
+      "pass_rate": {
+        "mean": 0.8333,
+        "stddev": 0.1443,
+        "min": 0.75,
+        "max": 1.0
+      },
+      "time_seconds": {
+        "mean": 0.0,
+        "stddev": 0.0,
+        "min": 0.0,
+        "max": 0.0
+      },
+      "tokens": {
+        "mean": 0.0,
+        "stddev": 0.0,
+        "min": 0,
+        "max": 0
+      }
+    },
+    "without_skill": {
+      "pass_rate": {
+        "mean": 0.6667,
+        "stddev": 0.3819,
+        "min": 0.25,
+        "max": 1.0
+      },
+      "time_seconds": {
+        "mean": 24.1667,
+        "stddev": 41.8579,
+        "min": 0.0,
+        "max": 72.5
+      },
+      "tokens": {
+        "mean": 7311.3333,
+        "stddev": 12663.6008,
+        "min": 0,
+        "max": 21934
+      }
+    },
+    "delta": {
+      "pass_rate": "+0.17",
+      "time_seconds": "-24.2",
+      "tokens": "-7311"
+    }
+  },
+  "notes": []
+}

package/skills/sync-docs-workspace/iteration-1/benchmark.md

@@ -0,0 +1,13 @@
+# Skill Benchmark: sync-docs
+
+**Model**: <model-name>
+**Date**: 2026-03-18T07:43:29Z
+**Evals**: 1, 2, 3 (3 runs each per configuration)
+
+## Summary
+
+| Metric | With Skill | Without Skill | Delta |
+|--------|------------|---------------|-------|
+| Pass Rate | 83% ± 14% | 67% ± 38% | +0.17 |
+| Time | 0.0s ± 0.0s | 24.2s ± 41.9s | -24.2s |
+| Tokens | 0 ± 0 | 7311 ± 12664 | -7311 |

package/skills/sync-docs-workspace/iteration-1/eval-doc-audit/eval_metadata.json

@@ -0,0 +1,27 @@
+{
+  "eval_id": 3,
+  "eval_name": "doc-audit",
+  "prompt": "Do a doc audit. I think the README has sections that should be in docs/ but I'm not sure which ones.",
+  "assertions": [
+    {
+      "id": "ran-analyzer",
+      "description": "Ran doc_structure_analyzer.py and referenced its structured output",
+      "check": "result.md cites the analyzer output (EXTRACTABLE, BLOATED, line count, or specific section names from the report)"
+    },
+    {
+      "id": "named-specific-sections",
+      "description": "Named specific README sections with their suggested docs/ destination",
+      "check": "result.md lists at least 2 specific sections (e.g. '## Policy System → docs/policies.md') not just generic advice"
+    },
+    {
+      "id": "actionable-report",
+      "description": "Report is actionable — tells user exactly what to do next, not just observations",
+      "check": "result.md includes a prioritized list or clear next steps, not just 'the README could be shorter'"
+    },
+    {
+      "id": "no-edits-made",
+      "description": "Did not edit or create any files (audit only)",
+      "check": "result.md does not claim to have modified README.md or created docs/ files"
+    }
+  ]
+}