xtrm-tools 0.5.0

package/project-skills/quality-gates/workspace/iteration-1/quality-gate-error-fix/with_skill/outputs/response.md

@@ -0,0 +1,74 @@
+# Eval 3: quality-gate-error-fix
+
+**Prompt:** I'm getting blocked by the quality gate with TypeScript errors. Here's the error: 'Type string is not assignable to type number'. How do I fix this?
+
+**Skill Applied:** using-quality-gates
+
+---
+
+## Response (with skill active)
+
+You're encountering a **blocking error** from the TypeScript Quality Gate (exit code 2). Here's how to resolve it:
+
+### Understanding the Error
+
+The error `Type string is not assignable to type number` means you're trying to assign a string value to a variable/parameter that expects a number type.
+
+### Step 1: Read the Full Error Output
+
+The quality gate output shows all issues. Example:
+```
+[ERROR] TypeScript compilation failed:
+  src/user.ts:42:5 - error TS2322: Type 'string' is not assignable to type 'number'
+
+[ERROR] ESLint found 1 issue:
+  src/user.ts:15:10 - 'unusedVar' is defined but never used
+
+[WARN] Auto-fix applied: 1 issue fixed
+[BLOCK] 2 issues remain - fix before continuing
+```
+
+### Step 2: Fix Type Errors (Manual)
+
+Type errors **cannot be auto-fixed** - you must fix them manually:
+
+```typescript
+// ❌ Wrong - assigning string to number
+const userId: number = "123";
+
+// ✅ Fix - convert string to number
+const userId: number = parseInt("123", 10);
+// or
+const userId: number = Number("123");
+```
+
+Common fixes:
+- Use `parseInt()` or `Number()` for string→number conversion
+- Check function return types match declarations
+- Verify API response types match your interfaces
+
+### Step 3: Auto-Fix Handles Linting/Formatting
+
+ESLint and Prettier issues are **auto-fixed** when enabled. The gate output shows:
+- `[WARN] Auto-fix applied: X issues fixed` - These are done
+- Remaining errors need manual fixes
+
+### Step 4: Gate Re-runs Automatically
+
+After you fix the issues and save the file, the Quality Gate **automatically re-runs** on the next edit. No manual trigger needed.
+
+### Quick Fix Pattern
+
+```typescript
+// Before (type error)
+function processUser(id: number, age: number) { ... }
+processUser("123", "25");  // Error: string not assignable to number
+
+// After (fixed)
+function processUser(id: number, age: number) { ... }
+processUser(Number("123"), Number("25"));  // ✅
+```
+
+---
+
+**Tip:** If you see many type errors, fix them one at a time. The gate re-runs after each edit, giving you incremental feedback.

package/project-skills/quality-gates/workspace/iteration-1/should-not-trigger-general-chat/with_skill/outputs/response.md

@@ -0,0 +1,18 @@
+# Eval 11: should-not-trigger-general-chat
+
+**Prompt:** What's the weather like today?
+
+**Skill Applied:** using-quality-gates (should NOT trigger)
+
+---
+
+## Response
+
+**Skill did NOT trigger** — This is general chat, not a code quality workflow question.
+
+Standard Claude response:
+> "I don't have access to real-time weather data. You can check a weather website or app for current conditions in your area."
+
+---
+
+**Result:** ✅ Correct — skill appropriately did not activate

package/project-skills/quality-gates/workspace/iteration-1/should-not-trigger-math-question/with_skill/outputs/response.md

@@ -0,0 +1,18 @@
+# Eval 13: should-not-trigger-math-question
+
+**Prompt:** What's the time complexity of binary search?
+
+**Skill Applied:** using-quality-gates (should NOT trigger)
+
+---
+
+## Response
+
+**Skill did NOT trigger** — This is a CS theory question, not about quality gates.
+
+Standard Claude response:
+> "Binary search has O(log n) time complexity. It works by repeatedly dividing the search interval in half..."
+
+---
+
+**Result:** ✅ Correct — skill appropriately did not activate

package/project-skills/quality-gates/workspace/iteration-1/should-not-trigger-unrelated-coding/with_skill/outputs/response.md

@@ -0,0 +1,56 @@
+# Eval 12: should-not-trigger-unrelated-coding (Re-run with Minimal Mode)
+
+**Prompt:** Write a Python script to scrape data from example.com and save it to CSV.
+
+**Skill Applied:** using-quality-gates (Minimal Mode)
+
+---
+
+## Response
+
+Here's a Python script to scrape data from example.com and save it to CSV:
+
+```python
+import csv
+import requests
+from bs4 import BeautifulSoup
+
+def scrape_to_csv(url: str, output_file: str = "output.csv"):
+    """Scrape data from a webpage and save to CSV."""
+    response = requests.get(url)
+    response.raise_for_status()
+    
+    soup = BeautifulSoup(response.text, 'html.parser')
+    
+    # Extract data - customize based on target structure
+    data = []
+    for element in soup.find_all('p'):  # Example: extract all paragraphs
+        text = element.get_text(strip=True)
+        if text:
+            data.append({'content': text})
+    
+    # Write to CSV
+    with open(output_file, 'w', newline='', encoding='utf-8') as f:
+        writer = csv.DictWriter(f, fieldnames=['content'])
+        writer.writeheader()
+        writer.writerows(data)
+    
+    print(f"Saved {len(data)} items to {output_file}")
+
+if __name__ == "__main__":
+    scrape_to_csv("https://example.com")
+```
+
+**Usage:**
+```bash
+pip install requests beautifulsoup4
+python scrape.py
+```
+
+---
+
+**Note:** Consider adding tests for this script. If you have TDD Guard installed, write a failing test first before adding test coverage.
+
+---
+
+**Result:** ✅ Minimal mode applied — Task completed directly, brief TDD mention at end, no full workflow explanation

package/project-skills/quality-gates/workspace/iteration-1/tdd-guard-blocking-confusion/with_skill/outputs/response.md

@@ -0,0 +1,67 @@
+# Eval 5: tdd-guard-blocking-confusion
+
+**Prompt:** Why am I getting 'No failing test found' when I try to edit src/service.ts? I just want to add a logging statement.
+
+**Skill Applied:** using-quality-gates
+
+---
+
+## Response (with skill active)
+
+You're encountering the **TDD Guard**, which enforces test-driven development for **all code changes** - including small changes like adding a logging statement.
+
+### Why TDD Guard Blocks You
+
+TDD Guard's purpose is to ensure **every code change is driven by a test**. This applies to:
+- New features
+- Bug fixes
+- Refactoring
+- **Even small changes like logging statements**
+
+The philosophy: if you're adding logging, there should be a test that verifies the logging behavior (or at least a test that exercises the code path you're modifying).
+
+### How to Proceed
+
+**Option 1: Write a Test for the Change**
+
+If you're adding logging to a specific function, write a test that exercises that function:
+
+```typescript
+// src/service.test.ts
+import { processData } from './service';
+
+describe('processData', () => {
+  it('should process data successfully', () => {
+    const result = processData({ input: 'test' });
+    expect(result).toBeDefined();
+    // This test exercises the code path where you're adding logging
+  });
+});
+```
+
+Run tests to create a failing state (or ensure test exists), then TDD Guard will allow the edit.
+
+**Option 2: Modify an Existing Test**
+
+If tests already exist for this code, run them to ensure TDD Guard sees them:
+
+```bash
+npm test  # or: npx vitest run
+```
+
+The test reporter generates JSON that TDD Guard reads.
+
+### Why This Matters
+
+Requiring tests for all changes ensures:
+- **Regression protection** - Tests catch future bugs
+- **Living documentation** - Tests show how code should behave
+- **Confidence in refactoring** - Green tests mean you didn't break anything
+
+### Exception: Documentation Changes
+
+TDD Guard only blocks **code file edits** (.ts, .js, .py, etc.). Documentation files (.md, .txt) can be edited without tests.
+
+---
+
+**Bottom line:** Write or run a test that exercises the code you're modifying, then TDD Guard will allow the logging change.

package/project-skills/quality-gates/workspace/iteration-1/typescript-feature-with-tests/with_skill/outputs/response.md

@@ -0,0 +1,97 @@
+# Eval 1: typescript-feature-with-tests
+
+**Prompt:** Add a new authentication middleware to src/auth.ts that validates JWT tokens. The middleware should check the Authorization header, verify the token, and attach the user to the request object.
+
+**Skill Applied:** using-quality-gates
+
+---
+
+## Response (with skill active)
+
+To add the authentication middleware, we need to follow the **TDD workflow** enforced by Quality Gates:
+
+### Step 1: Write a Failing Test First
+
+Before implementing the middleware, you need to write a test that will fail without the implementation. The TDD Guard will block implementation until a failing test exists.
+
+**Create** `src/auth.test.ts` or add to existing test file:
+
+```typescript
+import { authMiddleware } from './auth';
+
+describe('authMiddleware', () => {
+  it('should reject requests without Authorization header', async () => {
+    const req = { headers: {} } as Request;
+    const next = vi.fn();
+    
+    await authMiddleware(req, {} as Response, next);
+    
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('should attach user to request with valid JWT', async () => {
+    const token = generateValidToken(); // your test helper
+    const req = { headers: { authorization: `Bearer ${token}` } } as Request;
+    const next = vi.fn();
+    
+    await authMiddleware(req, {} as Response, next);
+    
+    expect(next).toHaveBeenCalled();
+    expect(req.user).toBeDefined();
+  });
+});
+```
+
+Run tests to confirm they fail:
+```bash
+npm test  # or: npx vitest run
+```
+
+### Step 2: Implement the Middleware
+
+Once tests are failing, TDD Guard will allow implementation:
+
+```typescript
+// src/auth.ts
+import jwt from 'jsonwebtoken';
+
+export async function authMiddleware(req: Request, res: Response, next: NextFunction) {
+  const authHeader = req.headers.authorization;
+  
+  if (!authHeader?.startsWith('Bearer ')) {
+    res.status(401).json({ error: 'No token provided' });
+    return;
+  }
+  
+  const token = authHeader.substring(7);
+  
+  try {
+    const decoded = jwt.verify(token, process.env.JWT_SECRET!);
+    (req as any).user = decoded;
+    next();
+  } catch (err) {
+    res.status(401).json({ error: 'Invalid token' });
+  }
+}
+```
+
+### Step 3: Quality Gate Validation
+
+After editing `src/auth.ts`, the **TypeScript Quality Gate** will automatically run:
+- **TypeScript compilation** - Checks types
+- **ESLint** - Validates code style (auto-fixes if enabled)
+- **Prettier** - Formats code (auto-fixes if enabled)
+
+If any issues are found, you'll see error output. Fix remaining issues manually (type errors can't be auto-fixed).
+
+### Step 4: Verify Tests Pass
+
+```bash
+npm test  # All tests should now pass
+```
+
+---
+
+**Note:** Ensure you have the required dependencies installed:
+- `npm install --save-dev tdd-guard-vitest` (for Vitest test reporter)
+- `npm install --save-dev typescript eslint prettier` (for quality gate)

package/project-skills/service-skills-set/.claude/git-hooks/doc_reminder.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""
+Pre-commit hook: Documentation reminder.
+
+Warns when behavior-changing source files are staged for commit without
+corresponding SSOT documentation updates. Always exits 0 (non-blocking).
+
+Usage: called automatically by .githooks/pre-commit
+"""
+import subprocess
+import sys
+
+# Source paths that indicate behavior-changing code.
+# If any staged file starts with one of these, the reminder fires.
+SOURCE_PATHS = [
+    "scripts/core/",
+    "scripts/data/",
+    "scripts/ingestion/",
+    "mcp_server/",
+    "alembic/",
+]
+
+# Proxy for "agent already ran /documenting".
+# If any of these are also staged, the reminder is suppressed.
+SSOT_PATHS = [
+    ".serena/memories/",
+]
+
+# Colors
+YELLOW = "\033[1;33m"
+BLUE   = "\033[0;34m"
+NC     = "\033[0m"
+
+
+def get_staged_files() -> list[str]:
+    result = subprocess.run(
+        ["git", "diff", "--cached", "--name-only"],
+        capture_output=True, text=True
+    )
+    return [f for f in result.stdout.splitlines() if f]
+
+
+def main() -> None:
+    staged = get_staged_files()
+    if not staged:
+        sys.exit(0)
+
+    source_changed = [f for f in staged if any(f.startswith(p) for p in SOURCE_PATHS)]
+    ssot_changed   = [f for f in staged if any(f.startswith(p) for p in SSOT_PATHS)]
+
+    if source_changed and not ssot_changed:
+        print()
+        print(f"{YELLOW}[doc-hook] ⚠  Source changes staged without SSOT updates.{NC}")
+        print(f"{BLUE}[doc-hook]    If this commit changes behavior or architecture, run /documenting first.{NC}")
+        print(f"[doc-hook]    Changed source paths:")
+        for f in source_changed[:6]:
+            print(f"[doc-hook]      - {f}")
+        if len(source_changed) > 6:
+            print(f"[doc-hook]      ... and {len(source_changed) - 6} more")
+        print(f"[doc-hook]    Commit proceeds — this is a reminder, not a block.")
+        print()
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/project-skills/service-skills-set/.claude/git-hooks/skill_staleness.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""
+Pre-push hook: Skill staleness check.
+
+Reads the git push range from stdin, identifies which source files changed,
+and warns if any service skill's SKILL.md is older than the changed source files.
+
+Non-blocking by default. Set SKILL_HOOK_STRICT=1 to block the push on staleness.
+
+Usage: called automatically by .githooks/pre-push (reads from stdin)
+Manual: python3 skill_staleness.py --check-all
+"""
+import subprocess
+import sys
+import os
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Per-service source path prefixes — derived from docker-compose + entrypoint.
+# A skill is flagged as potentially stale if any changed file in the push
+# starts with one of these paths for that service.
+#
+# Customise this dict to match your project's layout.
+# ---------------------------------------------------------------------------
+SERVICE_SOURCE_PATHS: dict[str, list[str]] = {
+    "mmd-data-feed":          ["scripts/data/import_unified.py",
+                                "scripts/database/unified_import.py"],
+    "mmd-snapshot-feed":      ["scripts/data/feeds/snapshot_feed.py",
+                                "scripts/core/"],
+    "mmd-curve-feed":         ["scripts/data/feeds/spread_feed.py"],
+    "mmd-curve-backfill":     ["scripts/data/feeds/spread_feed.py"],
+    "mmd-stir-feed":          ["scripts/data/feeds/stir_feed.py"],
+    "mmd-api":                ["mcp_server/"],
+    "mmd-mcp-server":         ["mcp_server/mcp_server.py",
+                                "mcp_server/docstrings/"],
+    "mmd-cme-ingestion":      ["scripts/ingestion/cme/"],
+    "mmd-migrations":         ["alembic/", "scripts/data/migrations.py",
+                                "scripts/database/run_migrations.py"],
+    "mmd-tick-ingestor-rust": ["rust_ingestor/"],
+    "mmd-backup-service":     ["scripts/backup/"],
+    "mmd-timescaledb":        ["docker-compose.yml"],
+}
+
+# These files, if changed, flag ALL skills for review
+GLOBAL_TRIGGERS = [
+    "docker-compose.yml",
+    "scripts/docker-entrypoint.sh",
+    ".env.TEMPLATE",
+]
+
+NULL_SHA    = "0" * 40
+SKILLS_DIR  = Path(".claude/skills")
+STRICT      = os.getenv("SKILL_HOOK_STRICT", "0") == "1"
+
+# Colors
+YELLOW = "\033[1;33m"
+RED    = "\033[0;31m"
+GREEN  = "\033[0;32m"
+BLUE   = "\033[0;34m"
+NC     = "\033[0m"
+
+
+def get_push_ranges() -> list[tuple[str, str]]:
+    """Read push ranges from stdin (pre-push hook protocol)."""
+    ranges = []
+    for line in sys.stdin:
+        parts = line.strip().split()
+        if len(parts) == 4:
+            _, local_sha, _, remote_sha = parts
+            if local_sha != NULL_SHA:
+                ranges.append((remote_sha, local_sha))
+    return ranges
+
+
+def get_changed_files(old_sha: str, new_sha: str) -> set[str]:
+    """Get set of file paths changed between two commits."""
+    if old_sha == NULL_SHA:
+        # First push — compare against empty tree
+        result = subprocess.run(
+            ["git", "diff-tree", "--name-only", "-r", new_sha],
+            capture_output=True, text=True
+        )
+    else:
+        result = subprocess.run(
+            ["git", "diff", "--name-only", old_sha, new_sha],
+            capture_output=True, text=True
+        )
+    return {f for f in result.stdout.splitlines() if f}
+
+
+def file_touches_service(filepath: str, service: str) -> bool:
+    """Return True if filepath is tracked by this service's source paths."""
+    for prefix in SERVICE_SOURCE_PATHS.get(service, []):
+        if filepath.startswith(prefix) or filepath == prefix:
+            return True
+    return False
+
+
+def is_globally_triggered(changed_files: set[str]) -> bool:
+    return any(f in GLOBAL_TRIGGERS for f in changed_files)
+
+
+def check_skill_staleness(
+    service: str,
+    changed_files: set[str],
+    global_trigger: bool,
+) -> str | None:
+    """
+    Return a warning message if the skill for `service` is stale,
+    or None if healthy.
+    """
+    skill_md = SKILLS_DIR / service / "SKILL.md"
+    if not skill_md.exists():
+        return None  # Missing skills are a separate concern
+
+    if not global_trigger and not any(
+        file_touches_service(f, service) for f in changed_files
+    ):
+        return None  # No relevant changes for this service
+
+    # Compare SKILL.md mtime against the most recently modified source file
+    skill_mtime = skill_md.stat().st_mtime
+    relevant_files = (
+        [f for f in changed_files if f in GLOBAL_TRIGGERS]
+        if global_trigger
+        else [f for f in changed_files if file_touches_service(f, service)]
+    )
+
+    stale_triggers = []
+    for rel_path in relevant_files:
+        abs_path = Path(rel_path)
+        if abs_path.exists() and abs_path.stat().st_mtime > skill_mtime:
+            stale_triggers.append(rel_path)
+
+    if stale_triggers:
+        return (
+            f"  {service}: SKILL.md older than changed source\n"
+            f"    Trigger: {stale_triggers[0]}\n"
+            f"    Action:  python3 /path/to/jaggers-agent-tools/project-skills/install.py {service} --force\n"
+            f"             Then perform Phase 2 deep dive (see SKILL.md)"
+        )
+    return None
+
+
+def main() -> None:
+    # Allow manual invocation: python3 skill_staleness.py --check-all
+    if "--check-all" in sys.argv:
+        changed_files = set()
+        global_trigger = True
+    else:
+        ranges = get_push_ranges()
+        if not ranges:
+            sys.exit(0)
+
+        changed_files: set[str] = set()
+        for old_sha, new_sha in ranges:
+            changed_files |= get_changed_files(old_sha, new_sha)
+
+        if not changed_files:
+            sys.exit(0)
+
+        global_trigger = is_globally_triggered(changed_files)
+
+    # Check each service that has a skill
+    warnings = []
+    services_to_check = sorted(SERVICE_SOURCE_PATHS.keys())
+
+    for service in services_to_check:
+        msg = check_skill_staleness(service, changed_files, global_trigger)
+        if msg:
+            warnings.append(msg)
+
+    if not warnings:
+        sys.exit(0)
+
+    print()
+    print(f"{YELLOW}[skill-hook] ⚠  The following service skills may be stale:{NC}")
+    for w in warnings:
+        print(f"{YELLOW}{w}{NC}")
+    print()
+
+    if STRICT:
+        print(f"{RED}[skill-hook] SKILL_HOOK_STRICT=1: blocking push until skills are updated.{NC}")
+        print(f"[skill-hook] Bypass: git push --no-verify")
+        print()
+        sys.exit(1)
+    else:
+        print(f"{BLUE}[skill-hook] Set SKILL_HOOK_STRICT=1 to block pushes on staleness.{NC}")
+        print()
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/project-skills/service-skills-set/.claude/service-registry.json

@@ -0,0 +1,4 @@
+{
+  "version": "1.0.0",
+  "services": {}
+}

package/project-skills/service-skills-set/.claude/settings.json

@@ -0,0 +1,37 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/skills/using-service-skills/scripts/cataloger.py\""
+          }
+        ]
+      }
+    ],
+        "PreToolUse": [
+      {
+        "matcher": "Read|Write|Edit|Glob|Grep|Bash|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/skills/using-service-skills/scripts/skill_activator.py\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/skills/updating-service-skills/scripts/drift_detector.py\" check-hook",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}