xtrm-tools 0.7.2 → 0.7.4

package/.xtrm/skills/default/documenting/scripts/list_by_category.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# List Serena memories filtered by category suffix
+#
+# Usage: list_by_category.sh [category]
+# category: ssot | pattern | plan | reference | archive | troubleshoot | all
+#
+# Examples:
+#   list_by_category.sh ssot       -> List all SSOT memories
+#   list_by_category.sh archive    -> List all archived memories
+#   list_by_category.sh all        -> List all memories grouped by category
+
+set -e
+
+CATEGORY="${1:-all}"
+MEMORIES_DIR="${SERENA_MEMORIES_DIR:-.serena/memories}"
+
+if [ ! -d "$MEMORIES_DIR" ]; then
+    echo "ERROR: Memories directory not found: $MEMORIES_DIR"
+    echo "Set SERENA_MEMORIES_DIR environment variable or run from project root"
+    exit 1
+fi
+
+# Function to list files with a given suffix
+list_suffix() {
+    local suffix=$1
+    local label=$2
+    local files
+
+    files=$(find "$MEMORIES_DIR" -maxdepth 1 -name "*_${suffix}.md" -type f 2>/dev/null | sort)
+
+    if [ -n "$files" ]; then
+        echo ""
+        echo "=== ${label} ==="
+        echo "$files" | while read -r file; do
+            basename "$file"
+        done
+    fi
+}
+
+# List by category
+case "$CATEGORY" in
+    ssot)
+        list_suffix "ssot" "SSOT Memories"
+        ;;
+    pattern)
+        list_suffix "pattern" "Pattern Memories"
+        ;;
+    plan)
+        list_suffix "plan" "Plan Memories"
+        ;;
+    reference)
+        list_suffix "reference" "Reference Memories"
+        ;;
+    archive)
+        list_suffix "archive" "Archived Memories"
+        ;;
+    troubleshoot)
+        list_suffix "troubleshoot" "Troubleshooting Guides"
+        ;;
+    all)
+        echo "Memories in: $MEMORIES_DIR"
+        list_suffix "ssot" "SSOT Memories"
+        list_suffix "pattern" "Pattern Memories"
+        list_suffix "plan" "Plan Memories"
+        list_suffix "reference" "Reference Memories"
+        list_suffix "troubleshoot" "Troubleshooting Guides"
+        list_suffix "archive" "Archived Memories (Deprecated)"
+
+        # Count special files
+        commit_logs=$(find "$MEMORIES_DIR" -maxdepth 1 -name "*_commit_log.md" -type f 2>/dev/null | wc -l)
+        if [ "$commit_logs" -gt 0 ]; then
+            echo ""
+            echo "=== Commit Logs ==="
+            find "$MEMORIES_DIR" -maxdepth 1 -name "*_commit_log.md" -type f | sort | while read -r file; do
+                basename "$file"
+            done
+        fi
+        ;;
+    *)
+        echo "ERROR: Invalid category: $CATEGORY"
+        echo "Valid categories: ssot, pattern, plan, reference, archive, troubleshoot, all"
+        exit 1
+        ;;
+esac

package/.xtrm/skills/default/documenting/scripts/orchestrator.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""
+Documentation orchestrator for coordinating SSOT, CHANGELOG, README, CLAUDE.md updates.
+
+Workflow:
+1. Classify change type (feature, bugfix, refactor, breaking, docs, chore)
+2. Update SSOT memories (.serena/memories/)
+3. Update CHANGELOG.md
+4. Suggest README.md updates
+5. Suggest CLAUDE.md/AGENT.md updates
+6. Validate all changes
+"""
+
+import sys
+from enum import Enum
+from pathlib import Path
+from typing import Dict, List, Optional
+from datetime import datetime, timezone
+
+from scripts.changelog.add_entry import add_entry_to_file, ChangeCategory
+from scripts.changelog.validate_changelog import validate_file as validate_changelog_file
+
+
+class ChangeType(Enum):
+    """Types of changes to document."""
+    FEATURE = "feature"
+    BUGFIX = "bugfix"
+    REFACTOR = "refactor"
+    BREAKING = "breaking"
+    DOCS = "docs"
+    CHORE = "chore"
+
+
+# Mapping of ChangeType to CHANGELOG category
+CHANGE_TYPE_TO_CATEGORY = {
+    ChangeType.FEATURE: ChangeCategory.ADDED,
+    ChangeType.BUGFIX: ChangeCategory.FIXED,
+    ChangeType.REFACTOR: ChangeCategory.CHANGED,
+    ChangeType.BREAKING: ChangeCategory.CHANGED,
+    ChangeType.DOCS: ChangeCategory.CHANGED,
+    ChangeType.CHORE: ChangeCategory.CHANGED,
+}
+
+
+class DocumentingOrchestrator:
+    """Coordinates documentation updates across multiple doc types."""
+
+    def __init__(self, project_root: Path):
+        self.project_root = Path(project_root)
+        self.changelog_path = self.project_root / "CHANGELOG.md"
+        self.readme_path = self.project_root / "README.md"
+        self.claude_path = self._find_agent_doc()
+        self.ssot_dir = self.project_root / ".serena" / "memories"
+
+    def _find_agent_doc(self) -> Optional[Path]:
+        """Find CLAUDE.md or AGENT.md."""
+        for name in ["CLAUDE.md", "AGENT.md"]:
+            path = self.project_root / name
+            if path.exists():
+                return path
+        return None
+
+    def document_change(
+        self,
+        change_type: ChangeType,
+        description: str,
+        details: Optional[Dict] = None
+    ) -> Dict:
+        """
+        Document a change across all relevant documentation.
+
+        Args:
+            change_type: Type of change
+            description: Brief description
+            details: Additional context:
+                - scope: SSOT scope identifier
+                - category: SSOT category
+                - subcategory: SSOT subcategory
+                - files_changed: List of affected files
+                - breaking: Whether change is breaking
+
+        Returns:
+            {
+                "changelog_updated": bool,
+                "ssot_updated": bool,
+                "ssot_file": Optional[Path],
+                "readme_suggestions": List[str],
+                "claude_suggestions": List[str],
+                "validation_errors": List[str]
+            }
+        """
+        details = details or {}
+        result = {
+            "changelog_updated": False,
+            "ssot_updated": False,
+            "ssot_file": None,
+            "readme_suggestions": [],
+            "claude_suggestions": [],
+            "validation_errors": []
+        }
+
+        # 1. Update CHANGELOG
+        if self.changelog_path.exists():
+            try:
+                category = CHANGE_TYPE_TO_CATEGORY[change_type]
+                if details.get("breaking"):
+                    description = f"**BREAKING**: {description}"
+
+                add_entry_to_file(self.changelog_path, category, description)
+                result["changelog_updated"] = True
+            except Exception as e:
+                result["validation_errors"].append(f"CHANGELOG update failed: {e}")
+
+        # 2. Update/Create SSOT (if relevant)
+        if change_type in [ChangeType.FEATURE, ChangeType.REFACTOR, ChangeType.BREAKING]:
+            ssot_result = self._update_ssot(change_type, description, details)
+            result.update(ssot_result)
+
+        # 3. Generate README suggestions
+        if change_type == ChangeType.FEATURE:
+            result["readme_suggestions"] = self._generate_readme_suggestions(description, details)
+
+        # 4. Generate CLAUDE.md suggestions
+        if change_type in [ChangeType.FEATURE, ChangeType.REFACTOR]:
+            result["claude_suggestions"] = self._generate_claude_suggestions(description, details)
+
+        # 5. Validate all documentation
+        validation = self.validate_all()
+        result["validation_errors"].extend(validation["errors"])
+
+        return result
+
+    def _update_ssot(self, change_type: ChangeType, description: str, details: Dict) -> Dict:
+        """Update or create SSOT memory."""
+        # This will be implemented with Serena tools in later tasks
+        # For now, just return placeholder
+        return {
+            "ssot_updated": False,
+            "ssot_file": None
+        }
+
+    def _generate_readme_suggestions(self, description: str, details: Dict) -> List[str]:
+        """Generate suggestions for README.md updates."""
+        suggestions = []
+
+        # Suggest updating features section
+        suggestions.append(f"Consider adding to ## Features section: {description}")
+
+        # If files_changed includes examples, suggest updating usage
+        if details.get("files_changed"):
+            if any("example" in f.lower() for f in details["files_changed"]):
+                suggestions.append("Update ## Usage section with new example")
+
+        return suggestions
+
+    def _generate_claude_suggestions(self, description: str, details: Dict) -> List[str]:
+        """Generate suggestions for CLAUDE.md/AGENT.md updates."""
+        suggestions = []
+
+        if not self.claude_path:
+            return suggestions
+
+        # Suggest architecture updates for major features
+        suggestions.append(f"Review ## Architecture section for: {description}")
+
+        # If files_changed affects setup, suggest updating
+        if details.get("files_changed"):
+            setup_files = ["requirements.txt", "package.json", ".env", "docker-compose.yml"]
+            if any(f in details["files_changed"] for f in setup_files):
+                suggestions.append("Update ## Development Environment section")
+
+        return suggestions
+
+    def validate_all(self) -> Dict:
+        """Validate all documentation."""
+        errors = []
+        warnings = []
+
+        # Validate CHANGELOG
+        if self.changelog_path.exists():
+            result = validate_changelog_file(self.changelog_path)
+            errors.extend(result.get("errors", []))
+            warnings.extend(result.get("warnings", []))
+
+        # TODO: Add SSOT validation
+        # TODO: Add README validation (check for broken links, etc.)
+
+        return {
+            "valid": len(errors) == 0,
+            "errors": errors,
+            "warnings": warnings
+        }
+
+
+def main():
+    """CLI entry point."""
+    if len(sys.argv) < 4:
+        print("Usage: orchestrator.py <project_root> <change_type> <description> [--scope=X] [--category=Y]")
+        print("")
+        print("Change Types: feature, bugfix, refactor, breaking, docs, chore")
+        print("")
+        print("Example:")
+        print('  orchestrator.py . feature "Add semantic search" --scope=search --category=backend')
+        sys.exit(1)
+
+    project_root = Path(sys.argv[1])
+    change_type = ChangeType(sys.argv[2])
+    description = sys.argv[3]
+
+    # Parse optional details
+    details = {}
+    for arg in sys.argv[4:]:
+        if arg.startswith("--"):
+            key, value = arg[2:].split("=", 1)
+            details[key] = value
+
+    orchestrator = DocumentingOrchestrator(project_root)
+    result = orchestrator.document_change(change_type, description, details)
+
+    # Print results
+    print("")
+    print("📝 Documentation Update Results")
+    print("=" * 60)
+
+    if result["changelog_updated"]:
+        print("✅ CHANGELOG.md updated")
+
+    if result["ssot_updated"]:
+        print(f"✅ SSOT updated: {result['ssot_file']}")
+
+    if result["readme_suggestions"]:
+        print("")
+        print("💡 README.md suggestions:")
+        for suggestion in result["readme_suggestions"]:
+            print(f"  - {suggestion}")
+
+    if result["claude_suggestions"]:
+        print("")
+        print("💡 CLAUDE.md suggestions:")
+        for suggestion in result["claude_suggestions"]:
+            print(f"  - {suggestion}")
+
+    if result["validation_errors"]:
+        print("")
+        print("❌ Validation errors:")
+        for error in result["validation_errors"]:
+            print(f"  - {error}")
+        sys.exit(1)
+
+    print("")
+    print("✅ All documentation validated")
+
+
+if __name__ == "__main__":
+    main()

package/.xtrm/skills/default/documenting/scripts/validate_metadata.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""
+Validate SSOT memory metadata compliance.
+
+Checks if a memory file has all required frontmatter fields and follows
+the naming conventions defined in the SSOT guidelines.
+"""
+
+import sys
+import re
+from pathlib import Path
+import yaml
+
+
+def extract_headings(content: str) -> list:
+    """Extract (heading, first_sentence) for every ## section (not ###)."""
+    results = []
+    lines = content.splitlines()
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        if line.startswith("## ") and not line.startswith("### "):
+            heading = line[3:].strip()
+            summary = ""
+            j = i + 1
+            in_code = False
+            while j < len(lines):
+                l = lines[j].strip()
+                if l.startswith("```"):
+                    in_code = not in_code
+                    j += 1
+                    continue
+                if not in_code and l and not l.startswith("#") and not l.startswith("|") and not l.startswith("-"):
+                    # Take up to first period, strip trailing period
+                    sentence = l.split(".")[0].strip()
+                    summary = sentence[:120]
+                    break
+                j += 1
+            results.append((heading, summary))
+        i += 1
+    return results
+
+
+def generate_index_table(headings: list) -> str:
+    """Generate a full markdown table string from headings list."""
+    rows = ["| Section | Summary |", "|---|---|"]
+    for heading, summary in headings:
+        anchor = heading.lower()
+        for ch in "/()":
+            anchor = anchor.replace(ch, "")
+        anchor = re.sub(r"[\s_]+", "-", anchor)
+        anchor = re.sub(r"-+", "-", anchor)
+        anchor = anchor.strip("-")
+        rows.append(f"| [{heading}](#{anchor}) | {summary or '_no summary_'} |")
+    return "\n".join(rows) + "\n"
+
+
+def inject_index(content: str, table: str) -> str:
+    """Replace existing INDEX block or insert one after frontmatter closing ---."""
+    header = "<!-- INDEX: auto-generated by validate_metadata.py — do not edit manually -->\n"
+    footer = "<!-- END INDEX -->"
+    block = f"{header}{table}{footer}"
+
+    # Replace existing block
+    existing = re.search(r"<!-- INDEX:.*?-->.*?<!-- END INDEX -->", content, re.DOTALL)
+    if existing:
+        return content[:existing.start()] + block + content[existing.end():]
+
+    # Insert after second --- (end of frontmatter)
+    fm_match = re.match(r"^(---\n.*?\n---\n)(.*)", content, re.DOTALL)
+    if fm_match:
+        return fm_match.group(1) + "\n" + block + "\n" + fm_match.group(2)
+
+    return block + "\n" + content
+
+
+REQUIRED_FIELDS = {
+    "ssot": ["title", "version", "updated", "scope", "category", "subcategory", "domain"],
+    "pattern": ["title", "version", "updated", "scope", "category", "domain"],
+    "plan": ["title", "version", "updated", "scope", "category"],
+    "reference": ["title", "scope", "category"],
+    "archive": ["title", "version", "updated", "scope", "category", "archived_date"],
+}
+
+CATEGORY_SUFFIXES = ["ssot", "pattern", "plan", "reference", "archive", "troubleshoot", "commit_log"]
+
+
+def extract_frontmatter(content):
+    """Extract YAML frontmatter from markdown content."""
+    match = re.match(r'^---\n(.*?)\n---\n', content, re.DOTALL)
+    if not match:
+        return None
+    try:
+        return yaml.safe_load(match.group(1))
+    except yaml.YAMLError as e:
+        print(f"ERROR: Invalid YAML frontmatter: {e}")
+        return None
+
+
+def validate_naming(filename):
+    """Validate filename follows naming conventions."""
+    errors = []
+
+    # Check if ends with .md
+    if not filename.endswith('.md'):
+        errors.append("Filename should end with .md")
+        return errors
+
+    stem = filename[:-3]  # Remove .md
+    
+    # Check if ends with known category suffix
+    has_suffix = any(stem.endswith(f"_{suffix}") for suffix in CATEGORY_SUFFIXES)
+    if not has_suffix:
+        errors.append(f"Filename should end with one of: {', '.join(['_' + s + '.md' for s in CATEGORY_SUFFIXES])}")
+
+    return errors
+
+
+def validate_version(version):
+    """Validate semantic version format (x.y.z)."""
+    if not version:
+        return False
+    pattern = r'^\d+\.\d+\.\d+$'
+    return bool(re.match(pattern, str(version)))
+
+
+def validate_metadata(filepath):
+    """Validate memory metadata."""
+    path = Path(filepath)
+
+    if not path.exists():
+        print(f"ERROR: File not found: {filepath}")
+        return False
+
+    print(f"Validating: {path.name}")
+    print("=" * 60)
+
+    errors = []
+    warnings = []
+
+    # Check naming convention
+    naming_errors = validate_naming(path.name)
+    errors.extend(naming_errors)
+
+    # Read content
+    content = path.read_text(encoding='utf-8')
+
+    # Extract frontmatter
+    metadata = extract_frontmatter(content)
+    if metadata is None:
+        errors.append("Missing or invalid YAML frontmatter (should be between --- markers)")
+        print_results(errors, warnings)
+        return False
+
+    # Determine category from filename suffix
+    category = None
+    stem = path.name[:-3]
+    for suffix in CATEGORY_SUFFIXES:
+        if stem.endswith(f"_{suffix}"):
+            category = suffix
+            break
+
+    # Check required fields based on category
+    # If category is troubleshoot or commit_log, they might not have strict requirements yet
+    if category in REQUIRED_FIELDS:
+        required = REQUIRED_FIELDS[category]
+        missing_fields = [field for field in required if field not in metadata]
+        if missing_fields:
+            errors.append(f"Missing required fields: {', '.join(missing_fields)}")
+    else:
+        # Default to ssot requirements if unknown but has suffix
+        required = REQUIRED_FIELDS["ssot"]
+        missing_fields = [field for field in required if field not in metadata]
+        if missing_fields:
+            errors.append(f"Missing required fields: {', '.join(missing_fields)}")
+
+    # Validate version format (if present)
+    if "version" in metadata:
+        if not validate_version(metadata["version"]):
+            errors.append(f"Invalid version format: {metadata['version']} (should be x.y.z)")
+
+    # Validate updated timestamp (if present)
+    if "updated" in metadata:
+        updated = str(metadata["updated"])
+        # Check for ISO8601-ish format (basic validation)
+        if not re.match(r'^\d{4}-\d{2}-\d{2}', updated):
+            warnings.append(f"Updated timestamp should be ISO8601 format: {updated}")
+
+    # Check for domain field (should be array)
+    if "domain" in metadata:
+        if not isinstance(metadata["domain"], list):
+            errors.append("Domain field should be an array/list")
+
+    # Check for changelog in SSOT files
+    if category == "ssot" and "changelog" not in metadata:
+        warnings.append("SSOT files should include a changelog section in frontmatter")
+
+    print_results(errors, warnings)
+
+    # Regenerate INDEX block unconditionally (navigation aid, independent of schema validity)
+    headings = extract_headings(content)
+    if headings:
+        table = generate_index_table(headings)
+        new_content = inject_index(content, table)
+        if new_content != content:
+            path.write_text(new_content, encoding="utf-8")
+            print("  ✏️  INDEX regenerated.")
+
+    return len(errors) == 0
+
+
+def print_results(errors, warnings):
+    """Print validation results."""
+    if errors:
+        print("\n❌ ERRORS:")
+        for error in errors:
+            print(f"  - {error}")
+
+    if warnings:
+        print("\n⚠️  WARNINGS:")
+        for warning in warnings:
+            print(f"  - {warning}")
+
+    if not errors and not warnings:
+        print("\n✅ VALID: All checks passed!")
+
+    print("=" * 60)
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: validate_metadata.py <memory-file.md>")
+        print("Example: validate_metadata.py analytics_volatility_ssot.md")
+        sys.exit(1)
+
+    filepath = sys.argv[1]
+    success = validate_metadata(filepath)
+    sys.exit(0 if success else 1)
+
+
+if __name__ == "__main__":
+    main()

package/.xtrm/skills/default/documenting/templates/CHANGELOG.md.template

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [{initial_version}] - {release_date}
+
+### Added
+- Initial release