@pjmendonca/devflow 1.9.0

package/tooling/scripts/memory_summarize.py

@@ -0,0 +1,324 @@
+#!/usr/bin/env python3
+"""
+Memory Summarization Utility
+
+Summarizes agent memory files to prevent unbounded growth.
+Uses simple heuristics to identify and consolidate similar entries.
+
+Usage:
+    python3 memory_summarize.py [agent_name] [--dry-run] [--max-entries 50]
+    python3 memory_summarize.py --all [--dry-run] [--max-entries 50]
+
+Examples:
+    python3 memory_summarize.py dev                    # Summarize dev agent memory
+    python3 memory_summarize.py --all                  # Summarize all agents
+    python3 memory_summarize.py dev --dry-run          # Preview without changes
+    python3 memory_summarize.py dev --max-entries 30   # Keep max 30 entries
+"""
+
+import argparse
+import re
+import sys
+from collections import defaultdict
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+# Find project root
+SCRIPT_DIR = Path(__file__).parent.resolve()
+PROJECT_ROOT = SCRIPT_DIR.parent.parent
+MEMORY_DIR = PROJECT_ROOT / ".automation" / "memory"
+
+
+def parse_memory_entry(line: str) -> tuple[Optional[datetime], str]:
+    """Parse a memory entry line into timestamp and content."""
+    # Format: - YYYY-MM-DD HH:MM: content
+    match = re.match(r"^-\s*(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}):\s*(.+)$", line.strip())
+    if match:
+        try:
+            timestamp = datetime.strptime(match.group(1), "%Y-%m-%d %H:%M")
+            return timestamp, match.group(2).strip()
+        except ValueError:
+            pass
+
+    # Format without timestamp: - content
+    match = re.match(r"^-\s*(.+)$", line.strip())
+    if match:
+        return None, match.group(1).strip()
+
+    return None, line.strip()
+
+
+def categorize_entry(content: str) -> str:
+    """Categorize a memory entry by its content."""
+    content_lower = content.lower()
+
+    # Error/bug related
+    if any(word in content_lower for word in ["error", "bug", "fix", "crash", "issue", "fail"]):
+        return "errors"
+
+    # Preference/style related
+    if any(
+        word in content_lower for word in ["prefer", "style", "convention", "pattern", "approach"]
+    ):
+        return "preferences"
+
+    # Code/implementation related
+    if any(
+        word in content_lower
+        for word in ["implement", "code", "function", "class", "module", "file"]
+    ):
+        return "implementation"
+
+    # Testing related
+    if any(word in content_lower for word in ["test", "spec", "coverage", "assert"]):
+        return "testing"
+
+    # Architecture/design related
+    if any(
+        word in content_lower for word in ["architect", "design", "structure", "pattern", "layer"]
+    ):
+        return "architecture"
+
+    # Performance related
+    if any(
+        word in content_lower
+        for word in ["performance", "optimize", "slow", "fast", "memory", "cache"]
+    ):
+        return "performance"
+
+    # Documentation related
+    if any(word in content_lower for word in ["doc", "readme", "comment", "explain"]):
+        return "documentation"
+
+    return "general"
+
+
+def similarity_score(entry1: str, entry2: str) -> float:
+    """Calculate simple similarity between two entries."""
+    words1 = set(entry1.lower().split())
+    words2 = set(entry2.lower().split())
+
+    if not words1 or not words2:
+        return 0.0
+
+    intersection = words1 & words2
+    union = words1 | words2
+
+    return len(intersection) / len(union)
+
+
+def find_duplicates(
+    entries: list[tuple[Optional[datetime], str]], threshold: float = 0.7
+) -> list[list[int]]:
+    """Find groups of similar entries."""
+    groups = []
+    used = set()
+
+    for i, (_, content1) in enumerate(entries):
+        if i in used:
+            continue
+
+        group = [i]
+        for j, (_, content2) in enumerate(entries[i + 1 :], start=i + 1):
+            if j in used:
+                continue
+
+            if similarity_score(content1, content2) >= threshold:
+                group.append(j)
+                used.add(j)
+
+        if len(group) > 1:
+            groups.append(group)
+            used.add(i)
+
+    return groups
+
+
+def summarize_group(entries: list[tuple[Optional[datetime], str]]) -> str:
+    """Create a summary for a group of similar entries."""
+    # Keep the most recent entry's content
+    sorted_entries = sorted(entries, key=lambda x: x[0] or datetime.min, reverse=True)
+    most_recent = sorted_entries[0][1]
+
+    if len(entries) > 2:
+        return f"{most_recent} (noted {len(entries)} times)"
+    return most_recent
+
+
+def load_memory_file(agent_name: str) -> list[str]:
+    """Load memory file contents."""
+    memory_file = MEMORY_DIR / f"{agent_name}.memory.md"
+
+    if not memory_file.exists():
+        return []
+
+    with open(memory_file) as f:
+        return [line.strip() for line in f.readlines() if line.strip()]
+
+
+def save_memory_file(agent_name: str, lines: list[str]) -> None:
+    """Save memory file contents."""
+    memory_file = MEMORY_DIR / f"{agent_name}.memory.md"
+
+    with open(memory_file, "w") as f:
+        f.write("\n".join(lines) + "\n")
+
+
+def summarize_agent_memory(agent_name: str, max_entries: int = 50, dry_run: bool = False) -> dict:
+    """Summarize an agent's memory file."""
+    lines = load_memory_file(agent_name)
+
+    if not lines:
+        return {"agent": agent_name, "status": "empty", "original": 0, "final": 0}
+
+    # Parse entries
+    entries = [parse_memory_entry(line) for line in lines]
+
+    result = {
+        "agent": agent_name,
+        "original": len(entries),
+        "categories": defaultdict(int),
+        "duplicates_found": 0,
+        "final": 0,
+        "changes": [],
+    }
+
+    # Categorize entries
+    for _, content in entries:
+        category = categorize_entry(content)
+        result["categories"][category] += 1
+
+    # Find and consolidate duplicates
+    duplicate_groups = find_duplicates(entries)
+    result["duplicates_found"] = sum(len(g) - 1 for g in duplicate_groups)
+
+    # Build new entry list
+    indices_to_remove = set()
+    summaries = []
+
+    for group in duplicate_groups:
+        group_entries = [entries[i] for i in group]
+        summary = summarize_group(group_entries)
+        most_recent_time = max((e[0] for e in group_entries if e[0]), default=None)
+        summaries.append((most_recent_time, summary))
+        indices_to_remove.update(group)
+        result["changes"].append(f"Consolidated {len(group)} similar entries")
+
+    # Keep non-duplicate entries
+    new_entries = []
+    for i, entry in enumerate(entries):
+        if i not in indices_to_remove:
+            new_entries.append(entry)
+
+    # Add summaries
+    new_entries.extend(summaries)
+
+    # Sort by timestamp (most recent first for trimming)
+    new_entries.sort(key=lambda x: x[0] or datetime.min, reverse=True)
+
+    # Trim to max entries if needed
+    if len(new_entries) > max_entries:
+        trimmed_count = len(new_entries) - max_entries
+        new_entries = new_entries[:max_entries]
+        result["changes"].append(f"Trimmed {trimmed_count} oldest entries")
+
+    # Sort back to chronological order for output
+    new_entries.sort(key=lambda x: x[0] or datetime.min)
+
+    result["final"] = len(new_entries)
+
+    # Format output lines
+    output_lines = []
+    for timestamp, content in new_entries:
+        if timestamp:
+            output_lines.append(f"- {timestamp.strftime('%Y-%m-%d %H:%M')}: {content}")
+        else:
+            output_lines.append(f"- {content}")
+
+    if not dry_run and output_lines != lines:
+        save_memory_file(agent_name, output_lines)
+        result["status"] = "updated"
+    else:
+        result["status"] = "dry-run" if dry_run else "no-change"
+
+    return result
+
+
+def get_all_agents() -> list[str]:
+    """Get list of agents with memory files."""
+    agents = []
+
+    if MEMORY_DIR.exists():
+        for file in MEMORY_DIR.glob("*.memory.md"):
+            agent_name = file.stem.replace(".memory", "")
+            agents.append(agent_name)
+
+    return agents
+
+
+def print_result(result: dict) -> None:
+    """Print summarization result."""
+    print(f"\n{'=' * 50}")
+    print(f"Agent: {result['agent']}")
+    print(f"Status: {result['status']}")
+
+    if result["status"] == "empty":
+        print("No memory entries found.")
+        return
+
+    print(f"Original entries: {result['original']}")
+    print(f"Final entries: {result['final']}")
+
+    if result.get("duplicates_found", 0) > 0:
+        print(f"Duplicates consolidated: {result['duplicates_found']}")
+
+    if result.get("categories"):
+        print("\nCategories:")
+        for cat, count in sorted(result["categories"].items(), key=lambda x: -x[1]):
+            print(f"  - {cat}: {count}")
+
+    if result.get("changes"):
+        print("\nChanges made:")
+        for change in result["changes"]:
+            print(f"  - {change}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Summarize agent memory files to prevent unbounded growth."
+    )
+    parser.add_argument("agent", nargs="?", help="Agent name to summarize")
+    parser.add_argument("--all", action="store_true", help="Summarize all agents")
+    parser.add_argument("--dry-run", action="store_true", help="Preview without making changes")
+    parser.add_argument(
+        "--max-entries", type=int, default=50, help="Maximum entries to keep (default: 50)"
+    )
+
+    args = parser.parse_args()
+
+    if not args.agent and not args.all:
+        parser.print_help()
+        print("\nError: Please specify an agent name or use --all")
+        sys.exit(1)
+
+    if args.all:
+        agents = get_all_agents()
+        if not agents:
+            print("No agent memory files found.")
+            sys.exit(0)
+
+        print(f"Summarizing memory for {len(agents)} agents...")
+        for agent in agents:
+            result = summarize_agent_memory(agent, args.max_entries, args.dry_run)
+            print_result(result)
+    else:
+        result = summarize_agent_memory(args.agent, args.max_entries, args.dry_run)
+        print_result(result)
+
+    if args.dry_run:
+        print("\n(Dry run - no changes made)")
+
+
+if __name__ == "__main__":
+    main()

package/tooling/scripts/new-doc.ps1

@@ -0,0 +1,405 @@
+<#
+.SYNOPSIS
+    NEW-DOC - Documentation Template Generator for Windows
+
+.DESCRIPTION
+    Creates new documentation files following the documentation standard.
+
+.PARAMETER Type
+    Document type: guide, spec, status, reference, example
+
+.PARAMETER Name
+    Document name (kebab-case)
+
+.PARAMETER Author
+    Author name (default: current user)
+
+.EXAMPLE
+    .\new-doc.ps1 -Type guide -Name "checkpoint-setup"
+    .\new-doc.ps1 -Type spec -Name "epic-4" -Author "SM Agent"
+
+.NOTES
+    Version: 1.0.0
+#>
+
+#Requires -Version 5.1
+
+param(
+    [Parameter(Mandatory=$true)]
+    [ValidateSet("guide", "spec", "status", "reference", "example")]
+    [string]$Type,
+
+    [Parameter(Mandatory=$true)]
+    [string]$Name,
+
+    [string]$Author = $env:USERNAME
+)
+
+$script:ScriptDir = $PSScriptRoot
+$script:ProjectRoot = (Get-Item "$script:ScriptDir\.." -ErrorAction SilentlyContinue).FullName
+$script:DocsDir = Join-Path $script:ProjectRoot "tooling\docs"
+
+function Get-GuideTemplate {
+    param([string]$Name, [string]$Author, [string]$Date)
+
+    return @"
+# [Document Title]
+
+**Type**: Guide
+**Version**: 1.0
+**Last Updated**: $Date
+**Author**: $Author
+**Status**: Draft
+
+---
+
+## Purpose
+
+[1-2 sentence description of what this guide helps users accomplish]
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Quick Start](#quick-start)
+- [Step-by-Step Instructions](#step-by-step-instructions)
+- [Examples](#examples)
+- [Troubleshooting](#troubleshooting)
+- [Next Steps](#next-steps)
+
+---
+
+## Prerequisites
+
+Before starting, ensure you have:
+
+- [ ] Prerequisite 1
+- [ ] Prerequisite 2
+- [ ] Prerequisite 3
+
+---
+
+## Quick Start
+
+For experienced users:
+
+``````powershell
+# Quick command to get started
+``````
+
+---
+
+## Step-by-Step Instructions
+
+### Step 1: [First Step]
+
+Description of what to do.
+
+``````powershell
+# Command to run
+``````
+
+**Expected output**:
+``````
+Output here
+``````
+
+### Step 2: [Second Step]
+
+Description of what to do.
+
+---
+
+## Examples
+
+### Example 1: [Common Use Case]
+
+**Problem**: [What problem this solves]
+
+**Solution**:
+``````powershell
+# Commands
+``````
+
+**Result**: [What happens]
+
+---
+
+## Troubleshooting
+
+### Issue: [Common Problem]
+
+**Symptoms**: [What you see]
+
+**Cause**: [Why it happens]
+
+**Solution**:
+``````powershell
+# Fix commands
+``````
+
+---
+
+## Next Steps
+
+After completing this guide:
+
+1. [Next logical step]
+2. [Another option]
+3. [Advanced topics]
+
+---
+
+## Changelog
+
+### 1.0 ($Date)
+- Initial version
+
+---
+
+**Document Control**
+- **Created**: $Date
+- **Owner**: $Author
+"@
+}
+
+function Get-SpecTemplate {
+    param([string]$Name, [string]$Author, [string]$Date)
+
+    return @"
+# [Technical Specification Title]
+
+**Type**: Spec
+**Version**: 1.0
+**Last Updated**: $Date
+**Author**: $Author
+**Status**: Draft
+
+---
+
+## Overview
+
+[High-level description of what is being specified]
+
+## Table of Contents
+
+- [Objectives and Scope](#objectives-and-scope)
+- [Architecture](#architecture)
+- [Implementation Details](#implementation-details)
+- [Dependencies](#dependencies)
+- [Testing Requirements](#testing-requirements)
+- [Acceptance Criteria](#acceptance-criteria)
+
+---
+
+## Objectives and Scope
+
+### In Scope
+- Feature 1
+- Feature 2
+- Feature 3
+
+### Out of Scope
+- Feature A
+- Feature B
+
+### Success Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+---
+
+## Architecture
+
+### System Components
+
+``````
+[ASCII diagram or description]
+``````
+
+### Data Flow
+
+``````
+[Flow description]
+``````
+
+---
+
+## Implementation Details
+
+### Component 1: [Name]
+
+**Purpose**: [What it does]
+
+**Files to Create**:
+- ``path/to/file1``
+- ``path/to/file2``
+
+**Files to Modify**:
+- ``path/to/existing``
+
+---
+
+## Dependencies
+
+| Dependency | Version | Purpose |
+|-----------|---------|---------|
+| package_name | ^1.0.0 | Description |
+
+---
+
+## Testing Requirements
+
+### Unit Tests
+- [ ] Test scenario 1
+- [ ] Test scenario 2
+
+### Integration Tests
+- [ ] Test scenario 1
+- [ ] Test scenario 2
+
+### Test Coverage Target
+- Minimum: 80%
+- Target: 90%
+
+---
+
+## Acceptance Criteria
+
+- [ ] AC 1: [Specific, measurable criterion]
+- [ ] AC 2: [Specific, measurable criterion]
+- [ ] AC 3: [Specific, measurable criterion]
+
+---
+
+## Changelog
+
+### 1.0 ($Date)
+- Initial specification
+
+---
+
+**Document Control**
+- **Created**: $Date
+- **Owner**: $Author
+"@
+}
+
+function Get-StatusTemplate {
+    param([string]$Name, [string]$Author, [string]$Date)
+
+    return @"
+# [Status Report Title]
+
+**Type**: Status
+**Version**: 1.0
+**Last Updated**: $Date
+**Author**: $Author
+**Status**: Active
+
+---
+
+## Current Status
+
+**Overall**: [Green/Yellow/Red]
+
+**Summary**: [1-sentence current state]
+
+---
+
+## Integration Points
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| Component 1 | Complete | Working as expected |
+| Component 2 | In Progress | 75% complete |
+| Component 3 | Not Started | Planned for next week |
+
+---
+
+## What's Working
+
+- Feature 1 - Fully operational
+- Feature 2 - Deployed and tested
+- Feature 3 - In production
+
+---
+
+## What's Not Working
+
+- Issue 1 - Description
+- Issue 2 - Description
+
+---
+
+## Metrics
+
+| Metric | Value | Target | Status |
+|--------|-------|--------|--------|
+| Coverage | 85% | 80% | OK |
+| Performance | 200ms | <300ms | OK |
+| Bugs | 3 | <5 | OK |
+
+---
+
+## Next Steps
+
+### Immediate (This Week)
+1. [ ] Task 1
+2. [ ] Task 2
+
+### Short Term (Next Week)
+1. [ ] Task 3
+2. [ ] Task 4
+
+---
+
+## Changelog
+
+### 1.0 ($Date)
+- Initial status report
+
+---
+
+**Document Control**
+- **Created**: $Date
+- **Owner**: $Author
+"@
+}
+
+# Main execution
+$date = (Get-Date).ToString("yyyy-MM-dd")
+$filename = "$($Type.ToUpper())-$Name.md"
+$outputFile = Join-Path $script:DocsDir $filename
+
+# Check if file exists
+if (Test-Path $outputFile) {
+    Write-Host "File already exists: $outputFile" -ForegroundColor Yellow
+    $overwrite = Read-Host "Overwrite? (y/n)"
+    if ($overwrite -notmatch '^[Yy]') {
+        Write-Host "Aborted." -ForegroundColor Blue
+        exit 0
+    }
+}
+
+Write-Host "Creating $Type document: $filename" -ForegroundColor Blue
+
+# Generate template
+$template = switch ($Type) {
+    "guide" { Get-GuideTemplate -Name $Name -Author $Author -Date $date }
+    "spec" { Get-SpecTemplate -Name $Name -Author $Author -Date $date }
+    "status" { Get-StatusTemplate -Name $Name -Author $Author -Date $date }
+    "reference" { Get-GuideTemplate -Name $Name -Author $Author -Date $date }
+    "example" { Get-GuideTemplate -Name $Name -Author $Author -Date $date }
+}
+
+# Write file
+Set-Content -Path $outputFile -Value $template
+
+Write-Host "[OK] Created: $outputFile" -ForegroundColor Green
+Write-Host ""
+Write-Host "Next steps:" -ForegroundColor Blue
+Write-Host "  1. Edit the document: $outputFile"
+Write-Host "  2. Fill in the template placeholders"
+Write-Host "  3. Review against: tooling\docs\DOC-STANDARD.md"
+Write-Host ""