@pennyfarthing/core 6.6.0

package/pennyfarthing-dist/scripts/utils/sprint-common.sh

@@ -0,0 +1,286 @@
+#!/usr/bin/env zsh
+# Sprint Common Functions
+# Shared functions for sprint management
+# Source this file: source "${SCRIPT_DIR}/sprint-common.sh"
+
+# Jira project identifier
+export JIRA_PROJECT="MSSCI"
+
+# Find PROJECT_ROOT by looking for .claude/ marker
+find_project_root() {
+    local dir="$PWD"
+    while [[ ! -d "$dir/.claude" ]] && [[ "$dir" != "/" ]]; do
+        dir="$(dirname "$dir")"
+    done
+    if [[ -d "$dir/.claude" ]]; then
+        echo "$dir"
+    else
+        return 1
+    fi
+}
+
+# Get PROJECT_ROOT if not already set
+PROJECT_ROOT="${PROJECT_ROOT:-$(find_project_root)}"
+export PROJECT_ROOT
+
+# find_story_file STORY_KEY
+# Search for a story in sprint YAML files
+# Returns: path to the YAML file containing the story
+find_story_file() {
+    local story_key="$1"
+
+    # Extract epic number from story key (e.g., "11-9" from "11-9-theme-maker")
+    local epic_num="${story_key%%-*}"
+
+    # Check current sprint first
+    if [[ -f "$PROJECT_ROOT/sprint/current-sprint.yaml" ]]; then
+        # Simple check: grep for the story key in the file
+        if grep -q "id: \"$epic_num-" "$PROJECT_ROOT/sprint/current-sprint.yaml" 2>/dev/null; then
+            echo "$PROJECT_ROOT/sprint/current-sprint.yaml"
+            return 0
+        fi
+    fi
+
+    # Check archived sprints
+    local archive_dir="$PROJECT_ROOT/sprint/archive"
+    if [[ -d "$archive_dir" ]]; then
+        local found=$(grep -l "id: \"$epic_num-" "$archive_dir"/*.yaml 2>/dev/null | head -1)
+        if [[ -n "$found" ]]; then
+            echo "$found"
+            return 0
+        fi
+    fi
+
+    return 1
+}
+
+# get_story_field STORY_KEY FIELD_NAME
+# Extract a field value from a story in sprint YAML
+# Returns: the field value or "null"
+get_story_field() {
+    local story_key="$1"
+    local field_name="$2"
+
+    # Extract epic and story numbers from story key
+    local epic_num="${story_key%%-*}"
+    local story_rest="${story_key#*-}"
+    local story_num="${story_rest%%-*}"
+
+    local story_file=$(find_story_file "$story_key")
+    if [[ -z "$story_file" ]]; then
+        echo "null"
+        return 1
+    fi
+
+    # Use yq to extract the field if available, otherwise fallback to grep
+    if command -v yq &> /dev/null; then
+        yq eval ".epics[] | select(.id == \"$epic_num\") | .stories[] | select(.id == \"$story_num\") | .$field_name" "$story_file" 2>/dev/null || echo "null"
+    else
+        # Fallback: grep for the pattern and extract value
+        # This is a simplified approach - full YAML parsing is better
+        grep -A 50 "id: \"$story_key" "$story_file" 2>/dev/null | grep "$field_name:" | head -1 | sed "s/.*$field_name:[[:space:]]*\(.*\)/\1/" || echo "null"
+    fi
+}
+
+# extract_jira_key JIRA_URL_OR_KEY
+# Extract Jira issue key from URL or return as-is
+# Returns: MSSCI-12345 format
+extract_jira_key() {
+    local input="$1"
+
+    # If already in key format, return as-is
+    if [[ "$input" =~ ^${JIRA_PROJECT}-[0-9]+$ ]]; then
+        echo "$input"
+        return 0
+    fi
+
+    # If it's a URL, extract the key
+    if [[ "$input" =~ ${JIRA_PROJECT}-[0-9]+ ]]; then
+        grep -o "${JIRA_PROJECT}-[0-9]\+" <<< "$input"
+        return 0
+    fi
+
+    # Return input as-is if no extraction possible
+    echo "$input"
+    return 1
+}
+
+# extract_story_id BRANCH_NAME
+# Extract story ID from branch name pattern feat/X-Y-*
+# Returns: X-Y (e.g., "8-1" from "feat/8-1-merge-detection")
+# Returns empty string for non-matching branches
+extract_story_id() {
+    local branch="$1"
+
+    # Match pattern: feat/EPIC-STORY-description or feat/EPIC-STORY
+    # Uses basic regex compatible with both bash and zsh
+    if [[ "$branch" =~ ^feat/([0-9]+-[0-9]+) ]]; then
+        echo "${match[1]:-${BASH_REMATCH[1]}}"
+    fi
+    # Returns empty string for non-matching patterns
+}
+
+# update_story_status STORY_ID [NEW_STATUS]
+# Update story status in sprint YAML and add completed date
+# Uses yq for YAML manipulation
+# Arguments:
+#   STORY_ID - Story identifier (e.g., "8-1")
+#   NEW_STATUS - Optional status, defaults to "done"
+update_story_status() {
+    local story_id="$1"
+    local new_status="${2:-done}"
+    local completed_date
+    completed_date=$(date +%Y-%m-%d)
+
+    local sprint_file="$PROJECT_ROOT/sprint/current-sprint.yaml"
+
+    if [[ ! -f "$sprint_file" ]]; then
+        return 1
+    fi
+
+    # Check if yq is available
+    if ! command -v yq &>/dev/null; then
+        echo "Warning: yq not found, cannot update sprint YAML" >&2
+        return 1
+    fi
+
+    # Extract epic and story numbers
+    local epic_num="${story_id%%-*}"
+    local story_num="${story_id#*-}"
+
+    # Update status and add completed date using yq
+    yq eval -i "
+        (.epics[] | select(.id == \"$epic_num\") | .stories[] | select(.id == \"$story_num\")).status = \"$new_status\" |
+        (.epics[] | select(.id == \"$epic_num\") | .stories[] | select(.id == \"$story_num\")).completed = \"$completed_date\"
+    " "$sprint_file"
+
+    return $?
+}
+
+# log_reconciliation STORY_ID MESSAGE
+# Log reconciliation event to .session/ directory
+# Arguments:
+#   STORY_ID - Story identifier (e.g., "8-1")
+#   MESSAGE - Optional message, defaults to "Merge detected"
+log_reconciliation() {
+    local story_id="$1"
+    local message="${2:-Merge detected}"
+    local timestamp
+    timestamp=$(date +"%Y-%m-%d %H:%M:%S")
+
+    local session_dir="$PROJECT_ROOT/.session"
+
+    # Ensure session directory exists
+    mkdir -p "$session_dir"
+
+    local log_file="$session_dir/reconciliation.log"
+
+    echo "[$timestamp] Story $story_id: $message" >> "$log_file"
+}
+
+# detect_drift
+# Detect stories that have been merged but not marked as done in YAML or Jira
+# Scans git log for recent merges (past 7 days) and compares against YAML/Jira status
+# Returns: list of drifted stories in "story_id:yaml_status:jira_status" format
+# A story is "drifted" when its branch was merged but YAML or Jira still shows in_progress
+detect_drift() {
+    local drifted=()
+
+    # Get recently merged branches (past 7 days)
+    # Look for feat/X-Y-* pattern in merge commit messages
+    local merged_branches
+    merged_branches=$(git log --merges --oneline --since="7 days ago" develop 2>/dev/null | \
+        grep -oE 'feat/[0-9]+-[0-9]+[^[:space:]]*' | sort -u)
+
+    for branch in $merged_branches; do
+        # Use extract_story_id to parse branch name
+        local story_id
+        story_id=$(extract_story_id "$branch")
+
+        if [[ -n "$story_id" ]]; then
+            # Check current status in YAML via get_story_field
+            local yaml_status
+            yaml_status=$(get_story_field "$story_id" "status")
+
+            # Get Jira key and check Jira status
+            local jira_key jira_status
+            jira_key=$(get_story_field "$story_id" "jira")
+            jira_status="unknown"
+
+            if [[ -n "$jira_key" && "$jira_key" != "null" ]]; then
+                # Query Jira for current status
+                jira_status=$(jira issue view "$jira_key" --raw 2>/dev/null | \
+                    jq -r '.fields.status.name // "unknown"' 2>/dev/null || echo "unknown")
+            fi
+
+            # Story is drifted if merged but YAML status is not "done" and not "backlog"
+            # OR if Jira status is not "Done" (case-insensitive check)
+            local yaml_drifted=false
+            local jira_drifted=false
+
+            if [[ "$yaml_status" != "done" && "$yaml_status" != "backlog" && "$yaml_status" != "null" ]]; then
+                yaml_drifted=true
+            fi
+
+            # Check Jira drift - status should be "Done" for merged stories
+            if [[ "$jira_status" != "unknown" && "$jira_status" != "Done" && "$jira_status" != "Closed" ]]; then
+                jira_drifted=true
+            fi
+
+            # Report if either YAML or Jira is drifted
+            if [[ "$yaml_drifted" == "true" || "$jira_drifted" == "true" ]]; then
+                drifted+=("$story_id:$yaml_status:$jira_status")
+            fi
+        fi
+    done
+
+    # Output drifted stories (one per line)
+    printf '%s\n' "${drifted[@]}" 2>/dev/null || true
+}
+
+# reconcile_drift STORY_ID
+# Auto-reconcile a drifted story by updating YAML status to done and Jira to Done
+# Logs the reconciliation event
+# Arguments:
+#   STORY_ID - Story identifier (e.g., "8-1")
+reconcile_drift() {
+    local story_id="$1"
+
+    if [[ -z "$story_id" ]]; then
+        echo "Error: story_id required" >&2
+        return 1
+    fi
+
+    local yaml_updated=false
+    local jira_updated=false
+    local messages=()
+
+    # Update YAML status to done
+    update_story_status "$story_id" "done"
+    if [[ $? -eq 0 ]]; then
+        yaml_updated=true
+        messages+=("YAML status updated to done")
+    fi
+
+    # Get Jira key and transition to Done
+    local jira_key
+    jira_key=$(get_story_field "$story_id" "jira")
+
+    if [[ -n "$jira_key" && "$jira_key" != "null" ]]; then
+        # Try to transition Jira to Done
+        if jira issue move "$jira_key" "Done" 2>/dev/null; then
+            jira_updated=true
+            messages+=("Jira $jira_key transitioned to Done")
+        else
+            messages+=("Jira $jira_key transition failed (may need manual update)")
+        fi
+    fi
+
+    # Log the reconciliation event
+    if [[ "$yaml_updated" == "true" || "$jira_updated" == "true" ]]; then
+        log_reconciliation "$story_id" "Auto-reconciled: ${messages[*]}"
+        return 0
+    else
+        return 1
+    fi
+}

package/pennyfarthing-dist/scripts/utils/sprint-metrics.sh

@@ -0,0 +1,241 @@
+#!/usr/bin/env zsh
+# Sprint metrics calculator
+# Usage: ./sprint-metrics.sh [--json]
+#
+# Displays sprint statistics from sprint/current-sprint.yaml:
+# - Points burned vs remaining
+# - Story completion rates
+# - Days remaining in sprint
+# - Percentage complete
+
+set -e
+
+# Find project root
+find_project_root() {
+    local dir="$PWD"
+    while [[ ! -d "$dir/.claude" ]] && [[ "$dir" != "/" ]]; do
+        dir="$(dirname "$dir")"
+    done
+    if [[ -d "$dir/.claude" ]]; then
+        echo "$dir"
+    else
+        echo "$PWD"
+    fi
+}
+
+PROJECT_ROOT="${PROJECT_ROOT:-$(find_project_root)}"
+SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+MAGENTA='\033[0;35m'
+BOLD='\033[1m'
+NC='\033[0m'
+
+# Check for JSON output mode
+JSON_MODE=false
+for arg in "$@"; do
+    case $arg in
+        --json)
+            JSON_MODE=true
+            ;;
+        -h|--help)
+            cat << 'EOF'
+Sprint Metrics - Display current sprint statistics
+
+Usage: ./sprint-metrics.sh [--json]
+
+Options:
+  --json    Output in JSON format (for automation)
+  -h        Show this help
+
+Output includes:
+  - Sprint number and goal
+  - Points: completed, in progress, remaining
+  - Stories: done, in progress, backlog counts
+  - Days elapsed and remaining
+  - Percentage complete
+  - Velocity tracking
+
+EOF
+            exit 0
+            ;;
+    esac
+done
+
+# Verify sprint file exists
+if [[ ! -f "$SPRINT_FILE" ]]; then
+    echo -e "${RED}❌ Sprint file not found: $SPRINT_FILE${NC}"
+    exit 1
+fi
+
+# Parse sprint metadata
+SPRINT_NUMBER=$(grep -E "^  number:" "$SPRINT_FILE" | head -1 | awk '{print $2}')
+SPRINT_GOAL=$(grep -E "^  goal:" "$SPRINT_FILE" | head -1 | sed 's/.*goal: *"//' | sed 's/"$//')
+START_DATE=$(grep -E "^  start_date:" "$SPRINT_FILE" | head -1 | awk '{print $2}')
+END_DATE=$(grep -E "^  end_date:" "$SPRINT_FILE" | head -1 | awk '{print $2}')
+
+# Parse summary section
+TOTAL_POINTS=$(grep -E "^  total_points:" "$SPRINT_FILE" | awk '{print $2}')
+COMPLETED_POINTS=$(grep -E "^  completed_points:" "$SPRINT_FILE" | awk '{print $2}')
+IN_PROGRESS_POINTS=$(grep -E "^  in_progress_points:" "$SPRINT_FILE" | awk '{print $2}')
+BACKLOG_POINTS=$(grep -E "^  backlog_points:" "$SPRINT_FILE" | awk '{print $2}')
+VELOCITY_TARGET=$(grep -E "^  velocity_target:" "$SPRINT_FILE" | awk '{print $2}')
+
+# Count stories by status
+DONE_STORIES=$(grep -E "^\s+status: done" "$SPRINT_FILE" | wc -l | tr -d ' ')
+IN_PROGRESS_STORIES=$(grep -E "^\s+status: in.progress" "$SPRINT_FILE" | wc -l | tr -d ' ')
+BACKLOG_STORIES=$(grep -E "^\s+status: backlog" "$SPRINT_FILE" | wc -l | tr -d ' ')
+TOTAL_STORIES=$((DONE_STORIES + IN_PROGRESS_STORIES + BACKLOG_STORIES))
+
+# Calculate dates
+TODAY=$(date +%Y-%m-%d)
+START_EPOCH=$(date -j -f "%Y-%m-%d" "$START_DATE" +%s 2>/dev/null || date -d "$START_DATE" +%s 2>/dev/null)
+END_EPOCH=$(date -j -f "%Y-%m-%d" "$END_DATE" +%s 2>/dev/null || date -d "$END_DATE" +%s 2>/dev/null)
+TODAY_EPOCH=$(date +%s)
+
+TOTAL_DAYS=$(( (END_EPOCH - START_EPOCH) / 86400 ))
+DAYS_ELAPSED=$(( (TODAY_EPOCH - START_EPOCH) / 86400 ))
+DAYS_REMAINING=$(( (END_EPOCH - TODAY_EPOCH) / 86400 ))
+
+# Ensure non-negative
+[[ $DAYS_ELAPSED -lt 0 ]] && DAYS_ELAPSED=0
+[[ $DAYS_REMAINING -lt 0 ]] && DAYS_REMAINING=0
+
+# Calculate percentages
+if [[ $TOTAL_POINTS -gt 0 ]]; then
+    PERCENT_COMPLETE=$(( (COMPLETED_POINTS * 100) / TOTAL_POINTS ))
+else
+    PERCENT_COMPLETE=0
+fi
+
+if [[ $TOTAL_DAYS -gt 0 ]]; then
+    PERCENT_TIME=$(( (DAYS_ELAPSED * 100) / TOTAL_DAYS ))
+else
+    PERCENT_TIME=0
+fi
+
+# Calculate velocity tracking
+EXPECTED_POINTS=0
+if [[ $TOTAL_DAYS -gt 0 ]]; then
+    EXPECTED_POINTS=$(( (VELOCITY_TARGET * DAYS_ELAPSED) / TOTAL_DAYS ))
+fi
+
+# JSON output mode
+if [[ "$JSON_MODE" == "true" ]]; then
+    cat << EOF
+{
+  "sprint": $SPRINT_NUMBER,
+  "dates": {
+    "start": "$START_DATE",
+    "end": "$END_DATE",
+    "today": "$TODAY"
+  },
+  "points": {
+    "total": $TOTAL_POINTS,
+    "completed": $COMPLETED_POINTS,
+    "in_progress": $IN_PROGRESS_POINTS,
+    "backlog": $BACKLOG_POINTS,
+    "velocity_target": $VELOCITY_TARGET
+  },
+  "stories": {
+    "total": $TOTAL_STORIES,
+    "done": $DONE_STORIES,
+    "in_progress": $IN_PROGRESS_STORIES,
+    "backlog": $BACKLOG_STORIES
+  },
+  "progress": {
+    "percent_complete": $PERCENT_COMPLETE,
+    "percent_time": $PERCENT_TIME,
+    "days_elapsed": $DAYS_ELAPSED,
+    "days_remaining": $DAYS_REMAINING,
+    "total_days": $TOTAL_DAYS
+  },
+  "velocity": {
+    "expected_points": $EXPECTED_POINTS,
+    "actual_points": $COMPLETED_POINTS,
+    "on_track": $([ $COMPLETED_POINTS -ge $EXPECTED_POINTS ] && echo "true" || echo "false")
+  }
+}
+EOF
+    exit 0
+fi
+
+# Human-readable output
+echo ""
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${BLUE}  Sprint $SPRINT_NUMBER Metrics${NC}"
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+
+echo ""
+echo -e "${BOLD}📋 Goal:${NC} $SPRINT_GOAL"
+
+echo ""
+echo -e "${BOLD}📅 Timeline${NC}"
+echo -e "   Start:     ${CYAN}$START_DATE${NC}"
+echo -e "   End:       ${CYAN}$END_DATE${NC}"
+echo -e "   Today:     ${CYAN}$TODAY${NC} (Day $DAYS_ELAPSED of $TOTAL_DAYS)"
+if [[ $DAYS_REMAINING -gt 0 ]]; then
+    echo -e "   Remaining: ${GREEN}$DAYS_REMAINING days${NC}"
+else
+    echo -e "   Remaining: ${RED}Sprint ended${NC}"
+fi
+
+echo ""
+echo -e "${BOLD}📊 Points${NC}"
+printf "   Completed:   ${GREEN}%3d${NC} pts\n" "$COMPLETED_POINTS"
+printf "   In Progress: ${YELLOW}%3d${NC} pts\n" "$IN_PROGRESS_POINTS"
+printf "   Backlog:     ${CYAN}%3d${NC} pts\n" "$BACKLOG_POINTS"
+echo -e "   ─────────────────"
+printf "   Total:       ${BOLD}%3d${NC} pts\n" "$TOTAL_POINTS"
+
+echo ""
+echo -e "${BOLD}📈 Stories${NC}"
+printf "   Done:        ${GREEN}%3d${NC}\n" "$DONE_STORIES"
+printf "   In Progress: ${YELLOW}%3d${NC}\n" "$IN_PROGRESS_STORIES"
+printf "   Backlog:     ${CYAN}%3d${NC}\n" "$BACKLOG_STORIES"
+echo -e "   ─────────────────"
+printf "   Total:       ${BOLD}%3d${NC}\n" "$TOTAL_STORIES"
+
+echo ""
+echo -e "${BOLD}🎯 Progress${NC}"
+
+# Progress bar for points
+BAR_WIDTH=20
+FILLED=$(( (PERCENT_COMPLETE * BAR_WIDTH) / 100 ))
+EMPTY=$((BAR_WIDTH - FILLED))
+BAR=""
+for ((i=0; i<FILLED; i++)); do BAR+="█"; done
+for ((i=0; i<EMPTY; i++)); do BAR+="░"; done
+
+echo -e "   Points:   [${GREEN}${BAR}${NC}] ${PERCENT_COMPLETE}%"
+
+# Progress bar for time
+TIME_FILLED=$(( (PERCENT_TIME * BAR_WIDTH) / 100 ))
+TIME_EMPTY=$((BAR_WIDTH - TIME_FILLED))
+TIME_BAR=""
+for ((i=0; i<TIME_FILLED; i++)); do TIME_BAR+="█"; done
+for ((i=0; i<TIME_EMPTY; i++)); do TIME_BAR+="░"; done
+
+echo -e "   Time:     [${CYAN}${TIME_BAR}${NC}] ${PERCENT_TIME}%"
+
+echo ""
+echo -e "${BOLD}🏃 Velocity${NC}"
+echo -e "   Target:   ${CYAN}$VELOCITY_TARGET${NC} pts/sprint"
+echo -e "   Expected: ${CYAN}$EXPECTED_POINTS${NC} pts by now"
+echo -e "   Actual:   ${GREEN}$COMPLETED_POINTS${NC} pts completed"
+
+if [[ $COMPLETED_POINTS -ge $EXPECTED_POINTS ]]; then
+    echo -e "   Status:   ${GREEN}✅ On track${NC}"
+elif [[ $COMPLETED_POINTS -ge $((EXPECTED_POINTS - 2)) ]]; then
+    echo -e "   Status:   ${YELLOW}⚠️  Slightly behind${NC}"
+else
+    echo -e "   Status:   ${RED}❌ Behind schedule${NC}"
+fi
+
+echo ""
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"