xtrm-tools 0.5.20 → 0.5.21

package/cli/package.json

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

package/config/hooks.json

@@ -4,9 +4,6 @@
       {
         "script": "beads-compact-restore.mjs",
         "timeout": 5000
-      },
-      {
-        "script": "serena-workflow-reminder.py"
       }
     ],
     "UserPromptSubmit": [

package/hooks/hooks.json

@@ -16,10 +16,6 @@
             "type": "command",
             "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/quality-check-env.mjs",
             "timeout": 5000
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/serena-workflow-reminder.py"
           }
         ]
       }

package/hooks/statusline.mjs

@@ -95,11 +95,12 @@ if (!data) {
   const venv = process.env.VIRTUAL_ENV ? `(${basename(process.env.VIRTUAL_ENV)})` : null;
 
   // Beads
+  let claimId = null;
   let claimTitle = null;
   let openCount = 0;
   if (existsSync(join(cwd, '.beads'))) {
     const claimFile = join(cwd, '.xtrm', 'statusline-claim');
-    const claimId = existsSync(claimFile) ? (readFileSync(claimFile, 'utf8').trim() || null) : null;
+    claimId = existsSync(claimFile) ? (readFileSync(claimFile, 'utf8').trim() || null) : null;
     if (claimId) {
       try {
         const raw = run(`bd show ${claimId} --json`);

package/package.json

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

package/skills/sync-docs/SKILL.md

@@ -55,7 +55,30 @@ python3 "skills/sync-docs/scripts/drift_detector.py" scan --since 30
 python3 "skills/sync-docs/scripts/drift_detector.py" scan --since 30 --json
 ```
 
-A docs file is stale when frontmatter `source_of_truth_for` (or `tracks`) matches files changed in recent commits.
+A docs file is stale when:
+1. It declares `source_of_truth_for` globs in frontmatter
+2. AND there are commits affecting matching files AFTER the `synced_at` hash
+
+### synced_at Checkpoint
+
+Add `synced_at: <git-hash>` to doc frontmatter to mark the last sync point:
+
+```yaml
+---
+title: Hooks Reference
+updated: 2026-03-21
+synced_at: a1b2c3d  # git hash when doc was last synced
+source_of_truth_for:
+  - "hooks/**/*.mjs"
+---
+```
+
+After updating a doc, run:
+```bash
+python3 "skills/sync-docs/scripts/drift_detector.py" update-sync docs/hooks.md
+```
+
+This sets `synced_at` to current HEAD, marking the doc as synced.
 
 ---
 

package/skills/sync-docs/scripts/drift_detector.py

@@ -2,13 +2,17 @@
 """
 Detect documentation drift between docs/ files and git-modified files.
 
-A docs file is considered stale when it declares source globs in frontmatter
-(`source_of_truth_for` or `tracks`) and recent commits modified matching files.
+A docs file is considered stale when:
+1. It declares source globs in frontmatter (`source_of_truth_for` or `tracks`)
+2. AND there are commits affecting those source files AFTER the doc's `synced_at` hash
+
+If `synced_at` is not set, the doc is considered stale (never synced).
 
 Subcommands:
   scan [--since N] [--json]  — scan all docs files (default N=30 commits)
   check <docs-file> [--since N] [--json]  — check one docs file
   hook [--json]              — check current uncommitted changes
+  update-sync <docs-file>    -- update synced_at to current HEAD hash
 """
 
 import sys
@@ -98,6 +102,70 @@ def extract_updated(content: str) -> str:
     return str(fm.get("updated", ""))
 
 
+def extract_synced_at(content: str) -> str | None:
+    """Extract the synced_at git hash from frontmatter."""
+    fm = extract_frontmatter(content)
+    synced = fm.get("synced_at")
+    if synced and isinstance(synced, str) and synced.strip():
+        return synced.strip()
+    return None
+
+
+def get_current_head_hash(project_root: Path) -> str | None:
+    """Get the current HEAD commit hash (short form)."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"],
+            cwd=project_root,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+    except Exception:
+        pass
+    return None
+
+
+def get_commits_after_hash(project_root: Path, synced_hash: str, source_files: list[str]) -> list[str]:
+    """
+    Check if there are commits affecting source_files after synced_hash.
+    Returns list of affected files (empty if no changes after sync point).
+    """
+    affected: list[str] = []
+    try:
+        # Check each source file for commits after the sync point
+        for source in source_files:
+            result = subprocess.run(
+                ["git", "log", f"{synced_hash}..HEAD", "--oneline", "--", source],
+                cwd=project_root,
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                affected.append(source)
+    except Exception:
+        pass
+    return affected
+
+
+def is_valid_git_hash(project_root: Path, hash_ref: str) -> bool:
+    """Check if a hash/ref is valid in the git repository."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--verify", hash_ref],
+            cwd=project_root,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        return result.returncode == 0
+    except Exception:
+        return False
+
+
 def _match_glob(path: str, pattern: str) -> bool:
     path_parts = Path(path).as_posix().split("/")
     pattern_parts = Path(pattern).as_posix().split("/")
@@ -143,6 +211,28 @@ def get_recent_modified_files(project_root: Path, since_n_commits: int = 30) ->
         return []
 
 
+def get_files_matching_globs(project_root: Path, globs: list[str]) -> list[str]:
+    """Get all tracked files matching the given glob patterns."""
+    matched: list[str] = []
+    try:
+        # Get all tracked files
+        result = subprocess.run(
+            ["git", "ls-files"],
+            cwd=project_root,
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if result.returncode != 0:
+            return []
+        
+        all_files = [l.strip() for l in result.stdout.splitlines() if l.strip()]
+        matched = match_files_to_globs(all_files, globs)
+    except Exception:
+        pass
+    return matched
+
+
 def get_session_written_files(project_root: Path) -> list[str]:
     try:
         unstaged = subprocess.run(
@@ -165,7 +255,13 @@ def get_session_written_files(project_root: Path) -> list[str]:
         return []
 
 
-def scan_docs(project_root: Path, changed_files: list[str]) -> list[dict[str, Any]]:
+def scan_docs(project_root: Path, changed_files: list[str], use_hash_check: bool = True) -> list[dict[str, Any]]:
+    """
+    Scan docs for drift.
+    
+    If use_hash_check=True (default): use synced_at hash comparison
+    If use_hash_check=False: use legacy recent-commits matching (for --since flag)
+    """
     stale: list[dict[str, Any]] = []
     for doc_path in get_docs_files(project_root):
         content = doc_path.read_text(encoding="utf-8", errors="replace")
@@ -173,16 +269,66 @@ def scan_docs(project_root: Path, changed_files: list[str]) -> list[dict[str, An
         if not globs:
             continue
 
-        matched = match_files_to_globs(changed_files, globs)
-        if matched:
-            stale.append(
-                {
+        synced_at = extract_synced_at(content)
+        updated = extract_updated(content)
+        
+        if use_hash_check and synced_at:
+            # Hash-based check: are there commits affecting source files after synced_at?
+            if not is_valid_git_hash(project_root, synced_at):
+                # Invalid hash (maybe rebased/force-pushed) - treat as stale
+                stale.append({
+                    "doc": str(doc_path.relative_to(project_root)),
+                    "updated": updated,
+                    "synced_at": synced_at,
+                    "synced_at_valid": False,
+                    "matched_files": [],
+                    "globs": globs,
+                    "reason": "synced_at hash not found in git history",
+                })
+                continue
+            
+            # Get all tracked files matching the globs
+            source_files = get_files_matching_globs(project_root, globs)
+            
+            # Check which files have commits after synced_at
+            affected = get_commits_after_hash(project_root, synced_at, source_files)
+            
+            if affected:
+                stale.append({
+                    "doc": str(doc_path.relative_to(project_root)),
+                    "updated": updated,
+                    "synced_at": synced_at,
+                    "synced_at_valid": True,
+                    "matched_files": affected[:10],
+                    "globs": globs,
+                    "reason": "source files changed after sync point",
+                })
+        elif use_hash_check:
+            # No synced_at hash - doc needs initial sync
+            source_files = get_files_matching_globs(project_root, globs)
+            if source_files:
+                stale.append({
+                    "doc": str(doc_path.relative_to(project_root)),
+                    "updated": updated,
+                    "synced_at": None,
+                    "synced_at_valid": False,
+                    "matched_files": source_files[:10],
+                    "globs": globs,
+                    "reason": "no synced_at hash - needs initial sync",
+                })
+        else:
+            # Legacy check: match against recent commits
+            matched = match_files_to_globs(changed_files, globs)
+            if matched:
+                stale.append({
                     "doc": str(doc_path.relative_to(project_root)),
-                    "updated": extract_updated(content),
+                    "updated": updated,
+                    "synced_at": synced_at,
+                    "synced_at_valid": synced_at is not None,
                     "matched_files": matched[:10],
                     "globs": globs,
-                }
-            )
+                    "reason": "recent commits match",
+                })
     return stale
 
 
@@ -191,34 +337,56 @@ def print_human_report(stale: list[dict[str, Any]], source: str) -> None:
         print(f"[Docs Drift] All docs up to date ({source}).")
         return
 
-    print(f"[Drift Report] {len(stale)} stale doc(s) detected from {source}:\n")
+    print(f"[Drift Report] {len(stale)} stale doc(s) detected:\n")
     for item in stale:
         print(f"  {item['doc']}")
+        synced = item.get("synced_at")
+        if synced:
+            valid = item.get("synced_at_valid", True)
+            status = "valid" if valid else "INVALID (not in git history)"
+            print(f"    Synced at: {synced} ({status})")
+        else:
+            print(f"    Synced at: (not set)")
         print(f"    Last updated: {item['updated'] or 'unknown'}")
-        for file_path in item["matched_files"][:3]:
-            print(f"    Modified: {file_path}")
+        reason = item.get("reason", "source files changed")
+        print(f"    Reason: {reason}")
+        if item.get("matched_files"):
+            for file_path in item["matched_files"][:3]:
+                print(f"    Modified: {file_path}")
         print("")
     print("Run /sync-docs to review and update stale docs.")
+    print("After updating, run: drift_detector.py update-sync <docs-file>")
 
 
 def cmd_scan(args: list[str]) -> None:
     since = 30
     as_json = "--json" in args
+    use_legacy = "--legacy" in args or "--since" in args
+    
     if "--since" in args:
         idx = args.index("--since")
         if idx + 1 < len(args):
             since = int(args[idx + 1])
 
     project_root = find_project_root()
-    changed = get_recent_modified_files(project_root, since)
-    stale = scan_docs(project_root, changed)
+    
+    if use_legacy:
+        # Legacy mode: match against recent commits
+        changed = get_recent_modified_files(project_root, since)
+        stale = scan_docs(project_root, changed, use_hash_check=False)
+        source = f"last {since} commits (legacy mode)"
+    else:
+        # Default: hash-based check
+        stale = scan_docs(project_root, [], use_hash_check=True)
+        source = "hash-based sync check"
 
     if as_json:
         print(
             json.dumps(
                 {
                     "mode": "scan",
-                    "since": since,
+                    "legacy": use_legacy,
+                    "since": since if use_legacy else None,
                     "count": len(stale),
                     "stale": stale,
                 },
@@ -226,7 +394,7 @@ def cmd_scan(args: list[str]) -> None:
             )
         )
     else:
-        print_human_report(stale, f"last {since} commits")
+        print_human_report(stale, source)
 
     sys.exit(1 if stale else 0)
 
@@ -284,7 +452,8 @@ def cmd_hook(args: list[str]) -> None:
     if not changed:
         sys.exit(0)
 
-    stale = scan_docs(project_root, changed)
+    # Hook mode always uses legacy check (uncommitted changes, not committed history)
+    stale = scan_docs(project_root, changed, use_hash_check=False)
     if not stale:
         sys.exit(0)
 
@@ -308,16 +477,83 @@ def cmd_hook(args: list[str]) -> None:
     sys.exit(1)
 
 
-SUBCOMMANDS = {"scan": cmd_scan, "check": cmd_check, "hook": cmd_hook}
+def cmd_update_sync(args: list[str]) -> None:
+    """Update synced_at field in a doc's frontmatter to current HEAD hash."""
+    if not args or args[0].startswith("--"):
+        print("Usage: drift_detector.py update-sync <docs-file>")
+        print("  Updates the synced_at field to current HEAD hash")
+        sys.exit(1)
+
+    target = args[0]
+    project_root = find_project_root()
+    doc_path = (project_root / target).resolve()
+    
+    if not doc_path.exists():
+        print(f"Doc not found: {target}")
+        sys.exit(1)
+
+    # Get current HEAD hash
+    head_hash = get_current_head_hash(project_root)
+    if not head_hash:
+        print("Failed to get current HEAD hash")
+        sys.exit(1)
+
+    # Read doc content
+    content = doc_path.read_text(encoding="utf-8")
+    
+    # Check for frontmatter
+    fm_match = re.match(r"^(---\n)(.*?)(\n---\n)", content, re.DOTALL)
+    if not fm_match:
+        print(f"No frontmatter found in {target}")
+        sys.exit(1)
+
+    frontmatter_block = fm_match.group(2)
+    rest_of_content = content[fm_match.end():]
+
+    # Parse frontmatter
+    fm = extract_frontmatter(content)
+    
+    # Update or add synced_at
+    if "synced_at" in fm:
+        # Replace existing synced_at
+        new_frontmatter = re.sub(
+            r"^synced_at:\s*.*$",
+            f"synced_at: {head_hash}",
+            frontmatter_block,
+            flags=re.MULTILINE,
+        )
+    else:
+        # Add synced_at after updated field, or at end
+        if "updated" in fm:
+            new_frontmatter = re.sub(
+                r"^(updated:\s*.*)$",
+                rf"\1\nsynced_at: {head_hash}",
+                frontmatter_block,
+                flags=re.MULTILINE,
+            )
+        else:
+            new_frontmatter = frontmatter_block.rstrip() + f"\nsynced_at: {head_hash}"
+
+    # Reconstruct file
+    new_content = f"---\n{new_frontmatter}\n---\n{rest_of_content}"
+    
+    # Write back
+    doc_path.write_text(new_content, encoding="utf-8")
+    print(f"Updated {target}: synced_at = {head_hash}")
+
+
+SUBCOMMANDS = {"scan": cmd_scan, "check": cmd_check, "hook": cmd_hook, "update-sync": cmd_update_sync}
 
 
 def main() -> None:
     args = sys.argv[1:]
     if not args or args[0] not in SUBCOMMANDS:
-        print("Usage: drift_detector.py <scan|check|hook> [options]")
-        print("  scan [--since N] [--json]          scan all docs files")
-        print("  check <docs-file> [--since N]      check one docs file")
-        print("  hook [--json]                      stop-hook mode")
+        print("Usage: drift_detector.py <scan|check|hook|update-sync> [options]")
+        print("  scan [--legacy] [--since N] [--json]  scan all docs (hash-based by default)")
+        print("  scan --legacy --since N               legacy mode: match recent commits")
+        print("  check <docs-file> [--since N]         check one docs file")
+        print("  hook [--json]                         stop-hook mode (uncommitted changes)")
+        print("  update-sync <docs-file>               set synced_at to current HEAD")
         sys.exit(1)
 
     SUBCOMMANDS[args[0]](args[1:])

package/hooks/serena-workflow-reminder.py

@@ -1,74 +0,0 @@
-#!/usr/bin/env python3
-import sys
-import os
-
-# Add script directory to path to allow importing shared modules
-sys.path.append(os.path.dirname(os.path.abspath(__file__)))
-from agent_context import AgentContext
-
-def get_skill_reminder(agent_type):
-    folder = f".{agent_type}"
-    return f"""
-*** MANDATORY SKILL: Using Serena LSP ***
-You are REQUIRED to use semantic tools for all code interactions to ensure safety and token efficiency.
-
-RULES:
-1. READING: NEVER read full code files >300 lines.
-   - START with `get_symbols_overview(depth=1)` to map the file.
-   - READ specific parts with `find_symbol(include_body=True)`.
-2. EDITING: NEVER use the generic `Edit` or `replace` tool on code.
-   - USE `replace_symbol_body` for atomic updates.
-   - USE `insert_after_symbol` / `insert_before_symbol` for additions.
-   - ALWAYS run `find_referencing_symbols` before changing signatures.
-3. SEARCH: USE `search_for_pattern` instead of grep/find.
-
-Ref: ~/{folder}/skills/using-serena-lsp/SKILL.md
-"""
-
-CODE_EXTENSIONS = {'.py', '.ts', '.js', '.jsx', '.tsx', '.go', '.rs', '.java', '.cpp', '.c', '.h'}
-
-def count_lines(filepath):
-    try:
-        with open(filepath, 'r') as f:
-            return sum(1 for _ in f)
-    except:
-        return 0
-
-try:
-    ctx = AgentContext()
-    event = ctx.event
-
-    if event == 'SessionStart':
-        ctx.allow(additional_context=get_skill_reminder(ctx.agent_type))
-
-    elif event in ['PreToolUse', 'BeforeTool']:
-        tool_name = ctx.tool_name
-        
-        # Rule 1: Block Reading Large Code Files
-        if tool_name in ['Read', 'read_file']:
-            file_path = ctx.get_file_path()
-            _, ext = os.path.splitext(file_path)
-            if ext in CODE_EXTENSIONS:
-                loc = count_lines(file_path)
-                if loc > 300:
-                    ctx.block(
-                        reason=f"VIOLATION: Reading full file of {loc} lines is forbidden. Use 'get_symbols_overview' and 'find_symbol' to save tokens.",
-                        system_message="⚠️ Blocked inefficient file read. Use Serena semantic tools."
-                    )
-
-        # Rule 2: Block Generic Edits on Code
-        if tool_name in ['Edit', 'replace']:
-            file_path = ctx.get_file_path()
-            _, ext = os.path.splitext(file_path)
-            if ext in CODE_EXTENSIONS:
-                 ctx.block(
-                    reason=f"VIOLATION: Generic '{tool_name}' is unsafe for code. Use 'replace_symbol_body' or 'insert_after_symbol' for surgical edits.",
-                    system_message="⚠️ Blocked unsafe edit. Use Serena semantic tools."
-                )
-
-    ctx.fail_open()
-
-except Exception as e:
-    # Fail safe: log error but allow operation
-    print(f"Hook Error: {e}", file=sys.stderr)
-    sys.exit(0)