@pennyfarthing/core 6.6.0

package/pennyfarthing-dist/scripts/utils/session-cleanup.sh

@@ -0,0 +1,319 @@
+#!/usr/bin/env zsh
+# Session artifact cleanup utility for Pennyfarthing
+# Cleans accumulated artifacts from .session/ directory
+#
+# Usage: session-cleanup.sh [OPTIONS]
+#
+# Options:
+#   --dry-run       Show what would be cleaned without deleting
+#   --aggressive    Also archive epic contexts for completed epics
+#   --story ID      Clean artifacts for specific story only
+#   --retention N   Days to retain artifacts (default: 1)
+#
+# Called by:
+#   - /retro (end of sprint - deep clean)
+#   - /start-epic (before starting new work)
+#   - sm-finish-execution (story-specific cleanup)
+
+set -e
+
+# Allow globs to return empty instead of failing
+setopt NULL_GLOB 2>/dev/null || true
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "${SCRIPT_DIR}/common.sh"
+
+#############################################
+# Configuration
+#############################################
+
+DRY_RUN=false
+AGGRESSIVE=false
+STORY_ID=""
+RETENTION_DAYS=1
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --dry-run)
+            DRY_RUN=true
+            shift
+            ;;
+        --aggressive)
+            AGGRESSIVE=true
+            shift
+            ;;
+        --story)
+            STORY_ID="$2"
+            shift 2
+            ;;
+        --retention)
+            RETENTION_DAYS="$2"
+            shift 2
+            ;;
+        *)
+            error "Unknown option: $1"
+            exit 1
+            ;;
+    esac
+done
+
+# Find project root
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(cd "$SCRIPT_DIR/../../.." && pwd)}"
+SESSION_DIR="$PROJECT_ROOT/.session"
+ARCHIVE_DIR="$PROJECT_ROOT/sprint/archive"
+
+if [ ! -d "$SESSION_DIR" ]; then
+    info "No .session directory found - nothing to clean"
+    exit 0
+fi
+
+#############################################
+# Cleanup Functions
+#############################################
+
+# Count and optionally remove files matching pattern
+cleanup_pattern() {
+    local pattern="$1"
+    local description="$2"
+    local use_mtime="${3:-true}"
+
+    local files=()
+    if [ "$use_mtime" = true ]; then
+        files=($(find "$SESSION_DIR" -maxdepth 1 -name "$pattern" -mtime +${RETENTION_DAYS} 2>/dev/null || true))
+    else
+        files=($(find "$SESSION_DIR" -maxdepth 1 -name "$pattern" 2>/dev/null || true))
+    fi
+
+    if [ ${#files[@]} -eq 0 ]; then
+        return 0
+    fi
+
+    info "Found ${#files[@]} $description"
+
+    for f in "${files[@]}"; do
+        if dry_run_check "remove $(basename "$f")"; then
+            continue
+        fi
+        rm -f "$f"
+        success "Removed $(basename "$f")"
+    done
+}
+
+# Archive files matching pattern (move to sprint/archive)
+archive_pattern() {
+    local pattern="$1"
+    local description="$2"
+
+    local files=($(find "$SESSION_DIR" -maxdepth 1 -name "$pattern" -mtime +${RETENTION_DAYS} 2>/dev/null || true))
+
+    if [ ${#files[@]} -eq 0 ]; then
+        return 0
+    fi
+
+    info "Found ${#files[@]} $description to archive"
+
+    for f in "${files[@]}"; do
+        local basename=$(basename "$f")
+        if dry_run_check "archive $basename"; then
+            continue
+        fi
+        mv "$f" "$ARCHIVE_DIR/" 2>/dev/null || rm -f "$f"
+        success "Archived $basename"
+    done
+}
+
+# Story-specific cleanup (when --story is provided)
+cleanup_story() {
+    local story="$1"
+    info "Cleaning artifacts for story: $story"
+
+    # New normalized patterns (category-{STORY_ID}-*)
+    local patterns=(
+        "test-${story}-*.log"
+        "test-${story}-*.md"
+        "lint-${story}-*.log"
+        "handoff-${story}-*.md"
+        "handoff-${story}-*.json"
+        "context-story-${story}.md"
+        # Legacy patterns (for migration)
+        "test-*-${story}*.log"
+        "test-*-${story}*.md"
+        "tea-*-${story}*.md"
+        "*-${story}-handoff*.md"
+        "*-${story}-handoff*.txt"
+        "dev-${story}-*.md"
+        "${story}-*.log"
+        "${story}-*.txt"
+        "story-${story}-context.md"
+    )
+
+    for pattern in "${patterns[@]}"; do
+        local files=($(find "$SESSION_DIR" -maxdepth 1 -name "$pattern" 2>/dev/null || true))
+        for f in "${files[@]}"; do
+            if dry_run_check "remove $(basename "$f")"; then
+                continue
+            fi
+            rm -f "$f"
+            success "Removed $(basename "$f")"
+        done
+    done
+}
+
+# Rotate session-log.txt to prevent unbounded growth
+rotate_session_log() {
+    local log_file="$SESSION_DIR/session-log.txt"
+    local max_lines=1000
+
+    if [ ! -f "$log_file" ]; then
+        return 0
+    fi
+
+    local current_lines=$(wc -l < "$log_file" | tr -d ' ')
+
+    if [ "$current_lines" -le "$max_lines" ]; then
+        info "session-log.txt has $current_lines lines (under $max_lines limit)"
+        return 0
+    fi
+
+    info "session-log.txt has $current_lines lines - rotating to $max_lines"
+
+    if dry_run_check "rotate session-log.txt from $current_lines to $max_lines lines"; then
+        return 0
+    fi
+
+    tail -${max_lines} "$log_file" > "${log_file}.tmp"
+    mv "${log_file}.tmp" "$log_file"
+    success "Rotated session-log.txt"
+}
+
+# Archive epic contexts for completed epics
+cleanup_epic_contexts() {
+    local sprint_file="$PROJECT_ROOT/sprint/current-sprint.yaml"
+
+    if [ ! -f "$sprint_file" ]; then
+        return 0
+    fi
+
+    # New pattern: context-epic-{N}.md
+    for f in "$SESSION_DIR"/context-epic-*.md; do
+        [ -f "$f" ] || continue
+
+        local basename=$(basename "$f")
+        local epic_num=$(echo "$basename" | grep -oE '[0-9]+')
+
+        # Check if epic is done in sprint file
+        if grep -qE "epic-${epic_num}:.*status:\s*done" "$sprint_file" 2>/dev/null || \
+           grep -A5 "epic-${epic_num}:" "$sprint_file" 2>/dev/null | grep -q "status: done"; then
+            info "Epic $epic_num is done - archiving context"
+            if dry_run_check "archive $basename"; then
+                continue
+            fi
+            mv "$f" "$ARCHIVE_DIR/"
+            success "Archived $basename"
+        fi
+    done
+
+    # Legacy pattern: epic-{N}-context.md (for migration)
+    for f in "$SESSION_DIR"/epic-*-context.md; do
+        [ -f "$f" ] || continue
+
+        local basename=$(basename "$f")
+        local epic_num=$(echo "$basename" | grep -oE '[0-9]+')
+
+        if grep -qE "epic-${epic_num}:.*status:\s*done" "$sprint_file" 2>/dev/null || \
+           grep -A5 "epic-${epic_num}:" "$sprint_file" 2>/dev/null | grep -q "status: done"; then
+            info "Epic $epic_num is done - archiving legacy context"
+            if dry_run_check "archive $basename"; then
+                continue
+            fi
+            mv "$f" "$ARCHIVE_DIR/"
+            success "Archived $basename"
+        fi
+    done
+}
+
+#############################################
+# Main Execution
+#############################################
+
+info "=== Session Cleanup ==="
+info "Project: $PROJECT_ROOT"
+info "Retention: ${RETENTION_DAYS} days"
+[ "$DRY_RUN" = true ] && warn "DRY RUN MODE - no files will be deleted"
+[ "$AGGRESSIVE" = true ] && info "Aggressive mode enabled"
+echo ""
+
+# If story-specific cleanup requested
+if [ -n "$STORY_ID" ]; then
+    cleanup_story "$STORY_ID"
+    exit 0
+fi
+
+# 1. Clean test artifacts (new pattern: test-{STORY_ID}-{agent}-{phase}.*)
+cleanup_pattern "test-*.log" "old test log files"
+cleanup_pattern "test-*.md" "old test report files"
+
+# 2. Clean lint artifacts (new pattern: lint-{STORY_ID}-{repo}.log)
+cleanup_pattern "lint-*.log" "old lint log files"
+
+# 3. Clean handoff artifacts (new pattern: handoff-{STORY_ID}-{agent}.*)
+cleanup_pattern "handoff-*.md" "old handoff files"
+cleanup_pattern "handoff-*.json" "old handoff JSON files"
+
+# 4. Clean context files (new pattern: context-story-{STORY_ID}.md)
+cleanup_pattern "context-story-*.md" "orphaned story context files"
+
+# 5. Legacy patterns (for migration - will be removed in future)
+cleanup_pattern "tea-*.md" "old TEA report files (legacy)"
+cleanup_pattern "*-red-*.md" "old RED phase files (legacy)"
+cleanup_pattern "*-green-*.md" "old GREEN phase files (legacy)"
+cleanup_pattern "*-red-*.log" "old RED phase logs (legacy)"
+cleanup_pattern "*-green-*.log" "old GREEN phase logs (legacy)"
+cleanup_pattern "*-handoff*.md" "old handoff files (legacy)"
+cleanup_pattern "*-handoff*.txt" "old handoff text files (legacy)"
+cleanup_pattern "dev-*.md" "old dev report files (legacy)"
+cleanup_pattern "dev-*.log" "old dev log files (legacy)"
+cleanup_pattern "story-*-context.md" "orphaned story context files (legacy)"
+
+# 6. Clean miscellaneous artifacts
+cleanup_pattern "*-result.yaml" "old result YAML files"
+cleanup_pattern "*-spec.md" "old spec files"
+cleanup_pattern "*-research*.md" "old research files"
+cleanup_pattern "*-failing-tests.json" "old failing tests JSON files"
+cleanup_pattern "*-SUMMARY.md" "old summary files"
+cleanup_pattern "test-summary-*.txt" "old test summary files"
+
+# 6. Rotate session log
+rotate_session_log
+
+# 7. Clean old agent sessions (already in sm-finish-execution but ensure it runs)
+if [ -d "$SESSION_DIR/agents" ]; then
+    local old_agents=($(find "$SESSION_DIR/agents" -type f -mtime +${RETENTION_DAYS} 2>/dev/null || true))
+    if [ ${#old_agents[@]} -gt 0 ]; then
+        info "Found ${#old_agents[@]} old agent session files"
+        for f in "${old_agents[@]}"; do
+            if dry_run_check "remove agent session $(basename "$f")"; then
+                continue
+            fi
+            rm -f "$f"
+        done
+        success "Cleaned old agent sessions"
+    fi
+fi
+
+# 8. Aggressive mode: archive completed epic contexts
+if [ "$AGGRESSIVE" = true ]; then
+    cleanup_epic_contexts
+fi
+
+# 9. Summary
+echo ""
+info "=== Cleanup Complete ==="
+local remaining=$(find "$SESSION_DIR" -maxdepth 1 -type f ! -name ".gitkeep" 2>/dev/null | wc -l | tr -d ' ')
+info "Remaining files in .session/: $remaining"
+
+if [ "$DRY_RUN" = true ]; then
+    echo ""
+    warn "This was a dry run. Run without --dry-run to actually clean files."
+fi

package/pennyfarthing-dist/scripts/utils/skill-usage-report.sh

@@ -0,0 +1,193 @@
+#!/usr/bin/env zsh
+# Generate skill usage reports from .session/skill-usage.log
+# Usage: skill-usage-report.sh [--weekly|--all] [--output FILE]
+#
+# Reads JSON Lines from .session/skill-usage.log and generates:
+#   - Invocation counts per skill
+#   - Most/least used skills
+#   - Unused skills (in registry but never invoked)
+#   - Weekly breakdown (optional)
+#
+# Environment:
+#   PROJECT_ROOT - Set by run.sh bootstrap (required)
+
+set -uo pipefail
+
+# --- Configuration ---
+SCRIPT_DIR="${0:A:h}"
+source "${SCRIPT_DIR}/common.sh" 2>/dev/null || true
+
+# --- Argument parsing ---
+REPORT_TYPE="all"
+OUTPUT_FILE=""
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --weekly)
+            REPORT_TYPE="weekly"
+            shift
+            ;;
+        --all)
+            REPORT_TYPE="all"
+            shift
+            ;;
+        --output)
+            OUTPUT_FILE="$2"
+            shift 2
+            ;;
+        -h|--help)
+            echo "Usage: skill-usage-report.sh [--weekly|--all] [--output FILE]"
+            echo ""
+            echo "Options:"
+            echo "  --weekly    Show only last 7 days of usage"
+            echo "  --all       Show all-time usage (default)"
+            echo "  --output    Write report to FILE instead of stdout"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1" >&2
+            exit 1
+            ;;
+    esac
+done
+
+# --- Find project root ---
+if [[ -z "${PROJECT_ROOT:-}" ]]; then
+    dir="$PWD"
+    while [[ ! -d "$dir/.claude" ]] && [[ "$dir" != "/" ]]; do
+        dir="$(dirname "$dir")"
+    done
+    if [[ -d "$dir/.claude" ]]; then
+        PROJECT_ROOT="$dir"
+    else
+        echo "Error: Could not find project root" >&2
+        exit 1
+    fi
+fi
+
+SESSION_DIR="$PROJECT_ROOT/.session"
+LOG_FILE="$SESSION_DIR/skill-usage.log"
+REGISTRY_FILE="$PROJECT_ROOT/pennyfarthing-dist/skills/skill-registry.yaml"
+
+# --- Helper functions ---
+generate_report() {
+    local cutoff_date=""
+    local title=""
+
+    if [[ "$REPORT_TYPE" == "weekly" ]]; then
+        # Get date 7 days ago in ISO format
+        if [[ "$(uname)" == "Darwin" ]]; then
+            cutoff_date=$(date -v-7d -u +"%Y-%m-%dT%H:%M:%SZ")
+        else
+            cutoff_date=$(date -d '7 days ago' -u +"%Y-%m-%dT%H:%M:%SZ")
+        fi
+        title="Skill Usage Report (Last 7 Days)"
+    else
+        title="Skill Usage Report (All Time)"
+    fi
+
+    echo "# $title"
+    echo ""
+    echo "Generated: $(date -u +"%Y-%m-%d %H:%M UTC")"
+    echo ""
+
+    # Check if log file exists
+    if [[ ! -f "$LOG_FILE" ]]; then
+        echo "## No Usage Data"
+        echo ""
+        echo "No skill usage has been logged yet."
+        echo "Log file: \`$LOG_FILE\`"
+        return 0
+    fi
+
+    # Filter entries if weekly
+    local entries
+    if [[ -n "$cutoff_date" ]]; then
+        entries=$(jq -c "select(.ts >= \"$cutoff_date\")" "$LOG_FILE" 2>/dev/null || echo "")
+    else
+        entries=$(cat "$LOG_FILE")
+    fi
+
+    if [[ -z "$entries" ]]; then
+        echo "## No Usage Data"
+        echo ""
+        echo "No skill invocations found for the selected period."
+        return 0
+    fi
+
+    # Count invocations per skill
+    echo "## Usage by Skill"
+    echo ""
+    echo "| Skill | Invocations |"
+    echo "|-------|-------------|"
+
+    echo "$entries" | jq -r '.skill' | sort | uniq -c | sort -rn | while read count skill; do
+        echo "| $skill | $count |"
+    done
+
+    echo ""
+
+    # Usage by agent
+    echo "## Usage by Agent"
+    echo ""
+    echo "| Agent | Invocations |"
+    echo "|-------|-------------|"
+
+    echo "$entries" | jq -r '.agent' | sort | uniq -c | sort -rn | while read count agent; do
+        echo "| $agent | $count |"
+    done
+
+    echo ""
+
+    # Total stats
+    local total_count=$(echo "$entries" | wc -l | tr -d ' ')
+    local unique_skills=$(echo "$entries" | jq -r '.skill' | sort -u | wc -l | tr -d ' ')
+
+    echo "## Summary"
+    echo ""
+    echo "- **Total invocations:** $total_count"
+    echo "- **Unique skills used:** $unique_skills"
+
+    # Find unused skills
+    if [[ -f "$REGISTRY_FILE" ]]; then
+        echo ""
+        echo "## Unused Skills"
+        echo ""
+
+        # Get all skills from registry
+        local registry_skills=$(yq -r '.skills | keys | .[]' "$REGISTRY_FILE" 2>/dev/null || echo "")
+
+        # Get used skills
+        local used_skills=$(echo "$entries" | jq -r '.skill' | sort -u)
+
+        # Find unused
+        local unused=""
+        for skill in ${(f)registry_skills}; do
+            if ! echo "$used_skills" | grep -q "^${skill}$" 2>/dev/null; then
+                unused="$unused$skill\n"
+            fi
+        done
+
+        if [[ -n "$unused" ]]; then
+            echo "The following skills are in the registry but have not been invoked:"
+            echo ""
+            echo "$unused" | while read skill; do
+                [[ -n "$skill" ]] && echo "- \`$skill\`"
+            done
+        else
+            echo "All registered skills have been used!"
+        fi
+    fi
+
+    return 0
+}
+
+# --- Main ---
+if [[ -n "$OUTPUT_FILE" ]]; then
+    generate_report > "$OUTPUT_FILE"
+    echo "Report written to: $OUTPUT_FILE"
+else
+    generate_report
+fi
+
+exit 0