@pennyfarthing/core 9.2.0 → 9.4.0

package/pennyfarthing-dist/scripts/jira/jira-reconcile.sh

@@ -1,260 +0,0 @@
-#!/bin/bash
-# Jira vs YAML Reconciliation Report
-# Usage: .pennyfarthing/scripts/jira/jira-reconcile.sh [--fix]
-#
-# Compares sprint YAML against Jira to find:
-# - Status mismatches
-# - Missing Jira keys
-# - Orphan issues (in Jira but not YAML)
-# - Sprint membership discrepancies
-#
-# Options:
-#   --fix    Apply recommended fixes automatically (where safe)
-
-set -euo pipefail
-
-# Find project root
-source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
-
-SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
-FIX_MODE="${1:-}"
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m' # No Color
-
-# Check dependencies
-if ! command -v yq &> /dev/null; then
-  echo "Error: yq is required but not installed"
-  echo "Install with: brew install yq"
-  exit 1
-fi
-
-if ! command -v jira &> /dev/null; then
-  echo "Error: jira CLI is required but not installed"
-  echo "Install with: brew install ankitpokhrel/jira/jira"
-  exit 1
-fi
-
-if [[ ! -f "$SPRINT_FILE" ]]; then
-  echo "Error: Sprint file not found at $SPRINT_FILE"
-  exit 1
-fi
-
-# Get sprint info
-SPRINT_NAME=$(yq eval '.sprint.name' "$SPRINT_FILE")
-SPRINT_ID=$(yq eval '.sprint.jira_sprint_id' "$SPRINT_FILE")
-
-echo "# Jira vs YAML Reconciliation Report"
-echo ""
-echo "**Sprint:** $SPRINT_NAME (Jira Sprint ID: $SPRINT_ID)"
-echo "**Generated:** $(date '+%Y-%m-%d %H:%M')"
-echo ""
-
-# Track issues
-STATUS_MISMATCHES=()
-MISSING_JIRA=()
-ORPHAN_ISSUES=()
-NOT_IN_SPRINT=()
-
-echo "## Checking YAML Stories Against Jira..."
-echo ""
-
-# Extract all stories from YAML and check against Jira
-while IFS=$'\t' read -r yaml_id jira_key yaml_status title; do
-  # Skip if no jira key
-  if [[ "$jira_key" == "null" ]] || [[ -z "$jira_key" ]]; then
-    MISSING_JIRA+=("$yaml_id|$title|$yaml_status")
-    continue
-  fi
-
-  # Get Jira status - use sed to remove the key prefix
-  jira_status=$(jira issue list --jql "project=MSSCI AND key=$jira_key" --plain --columns key,status --no-headers 2>/dev/null | sed "s/^$jira_key[[:space:]]*//" | xargs || echo "NOT_FOUND")
-
-  if [[ "$jira_status" == "NOT_FOUND" ]] || [[ -z "$jira_status" ]]; then
-    echo -e "${RED}[!]${NC} $jira_key not found in Jira"
-    continue
-  fi
-
-  # Normalize statuses for comparison
-  jira_norm=$(echo "$jira_status" | tr '[:upper:]' '[:lower:]' | tr ' ' '_')
-
-  # Check for mismatches
-  mismatch=false
-  case "$yaml_status" in
-    done)
-      [[ "$jira_norm" != "done" ]] && mismatch=true
-      ;;
-    ready|backlog)
-      [[ "$jira_norm" != "to_do" ]] && mismatch=true
-      ;;
-    in_progress)
-      [[ "$jira_norm" != "in_progress" ]] && mismatch=true
-      ;;
-  esac
-
-  if [[ "$mismatch" == "true" ]]; then
-    STATUS_MISMATCHES+=("$jira_key|$yaml_status|$jira_status")
-  fi
-done < <(yq -r '.epics[].stories[]? | [.id, .jira, .status, .title] | @tsv' "$SPRINT_FILE" 2>/dev/null)
-
-echo ""
-echo "## Checking Jira Sprint Against YAML..."
-echo ""
-
-# Get all issues in the Jira sprint and check if they're in YAML
-# Skip canceled issues - they're not relevant
-while read -r jira_key; do
-  # Check if in YAML (by id or jira field)
-  in_yaml=$(yq -r ".epics[].stories[]? | select(.id == \"$jira_key\" or .jira == \"$jira_key\") | .id" "$SPRINT_FILE" 2>/dev/null | head -1)
-
-  if [[ -z "$in_yaml" ]]; then
-    # Get more info about the orphan
-    status=$(jira issue list --jql "project=MSSCI AND key=$jira_key" --plain --columns key,status --no-headers 2>/dev/null | sed "s/^$jira_key[[:space:]]*//" | xargs || echo "Unknown")
-
-    # Skip canceled issues
-    if [[ "$status" == "Canceled" ]]; then
-      continue
-    fi
-
-    summary=$(jira issue list --jql "project=MSSCI AND key=$jira_key" --plain --columns key,summary --no-headers 2>/dev/null | sed "s/^$jira_key[[:space:]]*//" | xargs || echo "Unknown")
-    ORPHAN_ISSUES+=("$jira_key|$status|$summary")
-  fi
-done < <(jira issue list --jql "project=MSSCI AND labels=pennyfarthing AND sprint=$SPRINT_ID AND status != Canceled" --plain --columns key --no-headers 2>/dev/null)
-
-echo ""
-echo "## Checking for Issues Not in Sprint..."
-echo ""
-
-# Get done issues not in sprint
-while read -r jira_key; do
-  # Check if it should be in current sprint (exists in YAML)
-  in_yaml=$(yq -r ".epics[].stories[]? | select(.id == \"$jira_key\" or .jira == \"$jira_key\") | .id" "$SPRINT_FILE" 2>/dev/null | head -1)
-
-  if [[ -n "$in_yaml" ]]; then
-    summary=$(jira issue list --jql "project=MSSCI AND key=$jira_key" --plain --columns summary --no-headers 2>/dev/null | xargs || echo "Unknown")
-    NOT_IN_SPRINT+=("$jira_key|$summary")
-  fi
-done < <(jira issue list --jql "project=MSSCI AND labels=pennyfarthing AND sprint is EMPTY AND status != Canceled" --plain --columns key --no-headers 2>/dev/null)
-
-# Output Report
-echo ""
-echo "---"
-echo ""
-echo "# Summary"
-echo ""
-
-# Status Mismatches
-echo "## Status Mismatches (${#STATUS_MISMATCHES[@]})"
-echo ""
-if [[ ${#STATUS_MISMATCHES[@]} -eq 0 ]]; then
-  echo -e "${GREEN}No status mismatches found.${NC}"
-else
-  echo "| Jira Key | YAML Status | Jira Status | Action |"
-  echo "|----------|-------------|-------------|--------|"
-  for item in "${STATUS_MISMATCHES[@]}"; do
-    IFS='|' read -r key yaml jira <<< "$item"
-    echo "| $key | $yaml | $jira | Update YAML or Jira |"
-  done
-fi
-echo ""
-
-# Missing Jira Keys
-echo "## YAML Stories Missing Jira Key (${#MISSING_JIRA[@]})"
-echo ""
-if [[ ${#MISSING_JIRA[@]} -eq 0 ]]; then
-  echo -e "${GREEN}All YAML stories have Jira keys.${NC}"
-else
-  echo "| YAML ID | Title | Status | Action |"
-  echo "|---------|-------|--------|--------|"
-  for item in "${MISSING_JIRA[@]}"; do
-    IFS='|' read -r id title status <<< "$item"
-    echo "| $id | ${title:0:40} | $status | Create Jira issue |"
-  done
-fi
-echo ""
-
-# Orphan Issues
-echo "## Jira Issues Not in YAML (${#ORPHAN_ISSUES[@]})"
-echo ""
-if [[ ${#ORPHAN_ISSUES[@]} -eq 0 ]]; then
-  echo -e "${GREEN}All sprint issues are tracked in YAML.${NC}"
-else
-  echo "| Jira Key | Status | Summary | Action |"
-  echo "|----------|--------|---------|--------|"
-  for item in "${ORPHAN_ISSUES[@]}"; do
-    IFS='|' read -r key status summary <<< "$item"
-    if [[ "$status" == "Done" ]]; then
-      echo "| $key | $status | ${summary:0:40} | Info: Completed (not in current YAML) |"
-    else
-      echo "| $key | $status | ${summary:0:40} | Add to YAML or remove from sprint |"
-    fi
-  done
-  echo ""
-  echo "*Note: Done issues not in YAML are historical - they count toward sprint velocity but aren't actively tracked.*"
-fi
-echo ""
-
-# Not in Sprint
-echo "## YAML Stories Not in Jira Sprint (${#NOT_IN_SPRINT[@]})"
-echo ""
-if [[ ${#NOT_IN_SPRINT[@]} -eq 0 ]]; then
-  echo -e "${GREEN}All YAML stories are in Jira sprint.${NC}"
-else
-  echo "| Jira Key | Summary | Action |"
-  echo "|----------|---------|--------|"
-  for item in "${NOT_IN_SPRINT[@]}"; do
-    IFS='|' read -r key summary <<< "$item"
-    echo "| $key | ${summary:0:50} | Add to sprint $SPRINT_ID |"
-  done
-fi
-echo ""
-
-# Epic check
-echo "## Epic Sync Check"
-echo ""
-echo "| YAML Epic ID | Jira Field | Status |"
-echo "|--------------|------------|--------|"
-while IFS=$'\t' read -r epic_id jira_key title; do
-  if [[ "$jira_key" == "null" ]] || [[ -z "$jira_key" ]]; then
-    echo -e "| $epic_id | ${RED}MISSING${NC} | $title |"
-  else
-    echo "| $epic_id | $jira_key | $title |"
-  fi
-done < <(yq -r '.epics[] | [.id, .jira, .title] | @tsv' "$SPRINT_FILE" 2>/dev/null)
-echo ""
-
-# Total counts
-total_issues=$((${#STATUS_MISMATCHES[@]} + ${#MISSING_JIRA[@]} + ${#ORPHAN_ISSUES[@]} + ${#NOT_IN_SPRINT[@]}))
-
-echo "---"
-echo ""
-if [[ $total_issues -eq 0 ]]; then
-  echo -e "${GREEN}Sync Status: CLEAN${NC} - No discrepancies found!"
-else
-  echo -e "${YELLOW}Sync Status: $total_issues issue(s) found${NC}"
-  echo ""
-  echo "Run with --fix to apply automatic fixes where possible."
-fi
-
-# Fix mode
-if [[ "$FIX_MODE" == "--fix" ]]; then
-  echo ""
-  echo "## Applying Fixes..."
-  echo ""
-
-  # Add stories to sprint
-  for item in "${NOT_IN_SPRINT[@]}"; do
-    IFS='|' read -r key summary <<< "$item"
-    echo "Adding $key to sprint $SPRINT_ID..."
-    jira sprint add "$SPRINT_ID" "$key" 2>/dev/null && echo "  Done" || echo "  Failed"
-  done
-
-  echo ""
-  echo "Fix mode completed. Manual review still needed for:"
-  echo "- Status mismatches (requires decision on which source is correct)"
-  echo "- Missing Jira keys (requires creating new issues)"
-  echo "- Orphan issues (requires adding to YAML or removing from sprint)"
-fi

package/pennyfarthing-dist/scripts/jira/jira-sync-story.sh

@@ -1,18 +0,0 @@
-#!/usr/bin/env zsh
-# Sync a single story between sprint YAML and Jira
-# Usage: jira-sync-story.sh <story_key> [--transition] [--points] [--comment "message"]
-#
-# Thin wrapper that delegates to Python CLI:
-#   python -m pennyfarthing_scripts.jira create story <story_key> [options]
-#
-# Note: The subcommand is 'create story' but it handles sync, not creation.
-
-set -e
-
-# Source common functions for Python discovery
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-PARENT_DIR="$(dirname "$SCRIPT_DIR")"
-source "${PARENT_DIR}/lib/common.sh"
-
-# Delegate to Python CLI
-run_python_module jira create story "$@"

package/pennyfarthing-dist/scripts/jira/jira-sync.sh

@@ -1,16 +0,0 @@
-#!/usr/bin/env zsh
-# Sync an epic and its stories to Jira
-# Usage: jira-sync.sh <epic_number> [--dry-run] [--transition] [--points]
-#
-# Thin wrapper that delegates to Python CLI:
-#   python -m pennyfarthing_scripts.jira sync <epic_number> [options]
-
-set -e
-
-# Source common functions for Python discovery
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-PARENT_DIR="$(dirname "$SCRIPT_DIR")"
-source "${PARENT_DIR}/lib/common.sh"
-
-# Delegate to Python CLI
-run_python_module jira sync "$@"

package/pennyfarthing-dist/scripts/jira/sync-epic-jira.sh

@@ -1,16 +0,0 @@
-#!/usr/bin/env zsh
-# Sync an epic and its stories to Jira
-# Usage: sync-epic-jira.sh <epic-id> [--dry-run] [--transition] [--points] [--all]
-#
-# Thin wrapper that delegates to Python CLI:
-#   python -m pennyfarthing_scripts.jira sync <epic-id> [options]
-
-set -e
-
-# Source common functions for Python discovery
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-PARENT_DIR="$(dirname "$SCRIPT_DIR")"
-source "${PARENT_DIR}/lib/common.sh"
-
-# Delegate to Python CLI
-run_python_module jira sync "$@"

package/pennyfarthing-dist/scripts/jira/sync-epic-to-jira.sh

@@ -1,16 +0,0 @@
-#!/usr/bin/env zsh
-# Sync Pennyfarthing Epic to Jira MSSCI Project using jira
-# Usage: ./scripts/sync-epic-to-jira.sh <epic_number> [--dry-run] [--with-comments]
-#
-# Prerequisites:
-#   - jira installed: brew install ankitpokhrel/jira/jira
-#   - jira configured: jira init
-#   - JIRA_API_TOKEN environment variable set
-#
-# Options:
-#   --dry-run         Show what would be done without making changes
-#   --with-comments   (Deprecated - kept for compatibility)
-
-# Delegate to jira-sync.sh which implements the actual sync logic
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-exec "${SCRIPT_DIR}/jira-sync.sh" "$@"

package/pennyfarthing-dist/scripts/lib/README.md

@@ -1,29 +0,0 @@
-# Library Scripts
-
-Shared bash libraries sourced by other scripts.
-
-## Libraries
-
-| Script | Purpose |
-|--------|---------|
-| `common.sh` | Common utilities (colors, logging basics) |
-| `logging.sh` | Structured logging functions |
-| `retry.sh` | Retry logic with exponential backoff |
-| `checkpoint.sh` | Checkpointing for long-running operations |
-| `file-lock.sh` | File locking utilities |
-| `background-tasks.sh` | Background task management |
-| `find-root.sh` | Project root finder |
-
-## Usage
-
-These are sourced by other scripts, not run directly:
-
-```bash
-source "$SCRIPTS_DIR/lib/common.sh"
-source "$SCRIPTS_DIR/lib/logging.sh"
-```
-
-## Ownership
-
-- **Primary users:** All scripts
-- **Maintained by:** Core Pennyfarthing team

package/pennyfarthing-dist/scripts/lib/background-tasks.sh

@@ -1,177 +0,0 @@
-#!/usr/bin/env bash
-# Background task tracking utilities for session files
-#
-# Usage:
-#   source $CLAUDE_PROJECT_DIR/scripts/lib/background-tasks.sh
-#
-# Functions:
-#   bg_task_add <session_file> <task_id> <subagent_type> <description>
-#   bg_task_update <session_file> <task_id> <status>
-#   bg_task_cleanup <session_file>
-#   bg_task_list <session_file>
-#   bg_task_check <session_file>
-#
-# Example:
-#   # After spawning background task
-#   bg_task_add "$SESSION_FILE" "abc123" "testing-runner" "Background test run"
-#
-#   # After TaskOutput returns
-#   bg_task_update "$SESSION_FILE" "abc123" "completed"
-#   bg_task_cleanup "$SESSION_FILE"
-
-set -euo pipefail
-
-# Helper: count pattern matches in file (returns 0 if no matches)
-# grep -c outputs "0" AND exits 1 when no matches, so we capture and fallback separately
-_count_matches() {
-    local count
-    count=$(grep -c "$1" "$2" 2>/dev/null) || count=0
-    echo "$count"
-}
-
-# Add a background task to session file
-# Creates the Background Tasks section if it doesn't exist
-bg_task_add() {
-    local session_file="$1"
-    local task_id="$2"
-    local subagent_type="$3"
-    local description="${4:-}"
-    local timestamp
-    timestamp=$(date +"%H:%M")
-
-    if [[ ! -f "$session_file" ]]; then
-        echo "ERROR: Session file not found: $session_file" >&2
-        return 1
-    fi
-
-    # Check if Background Tasks section exists
-    if ! grep -q "^## Background Tasks" "$session_file" 2>/dev/null; then
-        # Add section before Workflow Tracking if present, otherwise at end
-        if grep -q "^## Workflow Tracking" "$session_file"; then
-            # Insert before Workflow Tracking using awk
-            awk '/^## Workflow Tracking/ {
-                print "## Background Tasks\n"
-                print "| Task ID | Type | Started | Status | Description |"
-                print "|---------|------|---------|--------|-------------|"
-                print ""
-            } {print}' "$session_file" > "${session_file}.tmp" && mv "${session_file}.tmp" "$session_file"
-        else
-            # Append to end
-            cat >> "$session_file" << EOF
-
-## Background Tasks
-
-| Task ID | Type | Started | Status | Description |
-|---------|------|---------|--------|-------------|
-EOF
-        fi
-    fi
-
-    # Add task row after the table header
-    awk -v tid="$task_id" -v stype="$subagent_type" -v ts="$timestamp" -v desc="$description" '
-        /^\|[-]+\|/ && in_section {
-            print
-            print "| " tid " | " stype " | " ts " | running | " desc " |"
-            next
-        }
-        /^## Background Tasks/ { in_section=1 }
-        /^## / && !/^## Background Tasks/ { in_section=0 }
-        { print }
-    ' "$session_file" > "${session_file}.tmp" && mv "${session_file}.tmp" "$session_file"
-
-    echo "Added background task: $task_id ($subagent_type)"
-}
-
-# Update background task status
-# Status: running, completed, error
-bg_task_update() {
-    local session_file="$1"
-    local task_id="$2"
-    local new_status="$3"
-
-    if [[ ! -f "$session_file" ]]; then
-        echo "ERROR: Session file not found: $session_file" >&2
-        return 1
-    fi
-
-    if ! grep -q "| $task_id |" "$session_file" 2>/dev/null; then
-        echo "WARNING: Task $task_id not found in session file" >&2
-        return 0
-    fi
-
-    # Update the status column for this task
-    sed -i '' "s/| $task_id |\\([^|]*\\)|\\([^|]*\\)| running |/| $task_id |\\1|\\2| $new_status |/" "$session_file"
-    echo "Updated task $task_id: $new_status"
-}
-
-# Remove completed and error tasks from session file
-bg_task_cleanup() {
-    local session_file="$1"
-
-    if [[ ! -f "$session_file" ]]; then
-        echo "ERROR: Session file not found: $session_file" >&2
-        return 1
-    fi
-
-    # Count tasks to remove
-    local completed_count
-    completed_count=$(_count_matches "| completed |" "$session_file")
-    local error_count
-    error_count=$(_count_matches "| error |" "$session_file")
-
-    if [[ "$completed_count" -gt 0 ]] || [[ "$error_count" -gt 0 ]]; then
-        sed -i '' '/| completed |/d' "$session_file"
-        sed -i '' '/| error |/d' "$session_file"
-        echo "Cleaned up $completed_count completed, $error_count errored tasks"
-    fi
-}
-
-# List active (running) background tasks
-bg_task_list() {
-    local session_file="$1"
-
-    if [[ ! -f "$session_file" ]]; then
-        echo "No session file"
-        return 0
-    fi
-
-    local running_tasks
-    running_tasks=$(grep "| running |" "$session_file" 2>/dev/null || true)
-
-    if [[ -n "$running_tasks" ]]; then
-        echo "$running_tasks"
-    else
-        echo "No active background tasks"
-    fi
-}
-
-# Check for active background tasks (returns 0 if tasks exist, 1 if none)
-# Useful for conditional logic in scripts
-bg_task_check() {
-    local session_file="$1"
-
-    if [[ ! -f "$session_file" ]]; then
-        return 1
-    fi
-
-    grep -q "| running |" "$session_file" 2>/dev/null
-}
-
-# Print summary of all background tasks
-bg_task_summary() {
-    local session_file="$1"
-
-    if [[ ! -f "$session_file" ]]; then
-        echo "No session file"
-        return 0
-    fi
-
-    local running
-    running=$(_count_matches "| running |" "$session_file")
-    local completed
-    completed=$(_count_matches "| completed |" "$session_file")
-    local errored
-    errored=$(_count_matches "| error |" "$session_file")
-
-    echo "Background tasks: $running running, $completed completed, $errored errored"
-}

package/pennyfarthing-dist/scripts/lib/checkpoint.sh

@@ -1,136 +0,0 @@
-#!/usr/bin/env zsh
-# Session checkpointing utilities
-# Dev: Fanny Price - "I was quiet, but I was not blind."
-
-# Source file locking utilities
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-# shellcheck source=file-lock.sh
-source "${SCRIPT_DIR}/file-lock.sh" 2>/dev/null || true
-
-# Checkpoint file location (evaluated dynamically)
-_get_checkpoint_file() {
-    echo "${PROJECT_ROOT:-.}/.session/checkpoints.log"
-}
-
-# checkpoint_save LABEL DATA
-# Save a checkpoint with timestamp
-#
-# Arguments:
-#   LABEL - Identifier for this checkpoint
-#   DATA  - Data to save (string)
-#
-# Format: ISO_TIMESTAMP|LABEL|DATA
-#
-# Example:
-#   checkpoint_save "story_phase" "dev"
-#   checkpoint_save "last_file" "src/main.go:42"
-#
-checkpoint_save() {
-    local label="$1"
-    local data="$2"
-    local timestamp
-    local checkpoint_file
-    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-    checkpoint_file=$(_get_checkpoint_file)
-
-    # Ensure directory exists
-    mkdir -p "$(dirname "$checkpoint_file")"
-
-    # Acquire exclusive lock, append checkpoint, release lock
-    if lock_acquire "$checkpoint_file" "exclusive" 5 2>/dev/null; then
-        echo "${timestamp}|${label}|${data}" >> "$checkpoint_file"
-        lock_release "$checkpoint_file"
-    else
-        # Fallback: append without lock (better than failing)
-        echo "${timestamp}|${label}|${data}" >> "$checkpoint_file"
-    fi
-}
-
-# checkpoint_restore LABEL
-# Restore the most recent checkpoint with given label
-#
-# Arguments:
-#   LABEL - Identifier to look up
-#
-# Returns:
-#   Outputs the data portion of the most recent matching checkpoint
-#   Empty if no match found
-#
-# Example:
-#   phase=$(checkpoint_restore "story_phase")
-#
-checkpoint_restore() {
-    local label="$1"
-    local checkpoint_file
-    checkpoint_file=$(_get_checkpoint_file)
-
-    if [[ ! -f "$checkpoint_file" ]]; then
-        return 0
-    fi
-
-    # Find entries with matching label, take the last one, extract data field
-    # Use || true to handle case where grep finds no matches
-    grep "|${label}|" "$checkpoint_file" 2>/dev/null | tail -1 | cut -d'|' -f3- || true
-}
-
-# checkpoint_list
-# List recent checkpoints (last 20)
-#
-# Example:
-#   checkpoint_list
-#
-checkpoint_list() {
-    local checkpoint_file
-    checkpoint_file=$(_get_checkpoint_file)
-
-    if [[ -f "$checkpoint_file" ]]; then
-        tail -20 "$checkpoint_file"
-    fi
-}
-
-# checkpoint_clear
-# Remove all checkpoints
-#
-# Example:
-#   checkpoint_clear
-#
-checkpoint_clear() {
-    local checkpoint_file
-    checkpoint_file=$(_get_checkpoint_file)
-    rm -f "$checkpoint_file"
-}
-
-# checkpoint_rotate MAX_LINES
-# Rotate checkpoint file to prevent unbounded growth
-#
-# Arguments:
-#   MAX_LINES - Maximum lines to keep (default: 1000)
-#
-# Example:
-#   checkpoint_rotate 500
-#
-checkpoint_rotate() {
-    local max_lines=${1:-1000}
-    local checkpoint_file
-    checkpoint_file=$(_get_checkpoint_file)
-
-    if [[ ! -f "$checkpoint_file" ]]; then
-        return 0
-    fi
-
-    # Acquire exclusive lock for rotation
-    if lock_acquire "$checkpoint_file" "exclusive" 5 2>/dev/null; then
-        local current_lines
-        current_lines=$(wc -l < "$checkpoint_file")
-
-        if ((current_lines > max_lines)); then
-            local temp_file
-            temp_file=$(mktemp)
-            tail -n "$max_lines" "$checkpoint_file" > "$temp_file"
-            mv "$temp_file" "$checkpoint_file"
-        fi
-        lock_release "$checkpoint_file"
-    fi
-}
-
-# Functions available when sourced