@pennyfarthing/core 7.9.2 → 7.9.5

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

@@ -0,0 +1,266 @@
+#!/bin/bash
+# Jira vs YAML Reconciliation Report
+# Usage: .pennyfarthing/scripts/core/run.sh 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
+
+# PROJECT_ROOT should be set by run.sh, but find it if not
+if [[ -z "${PROJECT_ROOT:-}" ]]; then
+  d="$PWD"
+  while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
+    d="$(dirname "$d")"
+  done
+  PROJECT_ROOT="$d"
+fi
+
+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

@@ -0,0 +1,18 @@
+#!/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

@@ -0,0 +1,16 @@
+#!/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

@@ -0,0 +1,16 @@
+#!/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

@@ -0,0 +1,16 @@
+#!/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

@@ -0,0 +1,29 @@
+# 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

@@ -0,0 +1,177 @@
+#!/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

@@ -0,0 +1,136 @@
+#!/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