@pennyfarthing/core 10.0.1 → 10.0.2

package/pennyfarthing-dist/scripts/hooks/bell-mode-hook.sh

@@ -0,0 +1,106 @@
+#!/bin/bash
+#
+# Bell Mode PostToolUse Hook (Story MSSCI-12275)
+#
+# This hook is called by Claude Code after each tool execution.
+# When bell mode is enabled and there are queued messages, it returns
+# the first queued message as additionalContext to be injected into
+# Claude's next API call.
+#
+# Configuration files:
+#   .pennyfarthing/config.local.yaml - workflow.bell_mode: true/false
+#   .pennyfarthing/bell-queue.json - [{ "text": "...", "images": [...] }, ...]
+#
+# Output format (when injecting):
+#   {
+#     "hookSpecificOutput": {
+#       "hookEventName": "PostToolUse",
+#       "additionalContext": "User feedback: <message>"
+#     }
+#   }
+#
+# Output when disabled or queue empty: (nothing - exit 0)
+
+# Find project root (walk up to find .pennyfarthing)
+PROJECT_ROOT="$PWD"
+while [[ "$PROJECT_ROOT" != "/" ]]; do
+  if [[ -d "$PROJECT_ROOT/.pennyfarthing" ]]; then
+    break
+  fi
+  PROJECT_ROOT="$(dirname "$PROJECT_ROOT")"
+done
+
+if [[ ! -d "$PROJECT_ROOT/.pennyfarthing" ]]; then
+  # No .pennyfarthing directory found - exit silently
+  exit 0
+fi
+
+CONFIG_LOCAL_YAML="$PROJECT_ROOT/.pennyfarthing/config.local.yaml"
+BELL_QUEUE_FILE="$PROJECT_ROOT/.pennyfarthing/bell-queue.json"
+
+# Check if bell mode is enabled in config.local.yaml
+if [[ ! -f "$CONFIG_LOCAL_YAML" ]]; then
+  exit 0
+fi
+
+# Parse YAML to check workflow.bell_mode - look for "bell_mode: true"
+# This handles both "bell_mode: true" and "  bell_mode: true" (indented under workflow)
+ENABLED=$(grep -E '^\s*bell_mode:\s*true' "$CONFIG_LOCAL_YAML" 2>/dev/null || true)
+if [[ -z "$ENABLED" ]]; then
+  exit 0
+fi
+
+# Check if queue file exists and has messages
+if [[ ! -f "$BELL_QUEUE_FILE" ]]; then
+  exit 0
+fi
+
+# Read queue and check if non-empty
+QUEUE_CONTENT=$(cat "$BELL_QUEUE_FILE" 2>/dev/null)
+if [[ -z "$QUEUE_CONTENT" ]] || [[ "$QUEUE_CONTENT" == "[]" ]]; then
+  exit 0
+fi
+
+# Extract first message text using simple parsing
+# The queue format is: [{"text":"...","images":[...]}, ...]
+FIRST_MESSAGE_TEXT=$(echo "$QUEUE_CONTENT" | sed -n 's/.*"text"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
+
+if [[ -z "$FIRST_MESSAGE_TEXT" ]]; then
+  exit 0
+fi
+
+# Get Cyclist port (if running)
+CYCLIST_PORT=""
+PORT_FILE="$PROJECT_ROOT/.cyclist-port"
+if [[ -f "$PORT_FILE" ]]; then
+  CYCLIST_PORT=$(cat "$PORT_FILE" 2>/dev/null)
+fi
+
+# Output the hook response JSON
+cat << EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "User feedback: $FIRST_MESSAGE_TEXT"
+  }
+}
+EOF
+
+# Remove the first message from the queue and notify Cyclist
+# Run in background to avoid blocking hook response
+(
+  # Dequeue using jq if available
+  if command -v jq &> /dev/null; then
+    jq 'if length > 0 then .[1:] else [] end' "$BELL_QUEUE_FILE" > "$BELL_QUEUE_FILE.tmp" 2>/dev/null && mv "$BELL_QUEUE_FILE.tmp" "$BELL_QUEUE_FILE"
+  fi
+
+  # Notify Cyclist browser to dequeue and display the message
+  if [[ -n "$CYCLIST_PORT" ]] && [[ "$CYCLIST_PORT" =~ ^[0-9]+$ ]]; then
+    curl -s -X POST "http://localhost:$CYCLIST_PORT/api/bell-consumed" \
+      -H "Content-Type: application/json" \
+      -d "{\"text\": \"$FIRST_MESSAGE_TEXT\"}" \
+      >/dev/null 2>&1 || true
+  fi
+) &
+
+exit 0

package/pennyfarthing-dist/scripts/hooks/context-circuit-breaker.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env zsh
+# Context circuit breaker hook: Block tool execution at 85% context usage
+# Called by Claude Code before tool calls (PreToolUse)
+#
+# Input: JSON via stdin with tool_name, tool_input, session_id
+# Output: Exit 0 to allow, Exit 2 to block (stderr shown to Claude)
+#
+# This hook provides a hard stop when context is critically high,
+# unlike context-warning.sh which only warns.
+#
+# When triggered, automatically saves the active agent to a checkpoint
+# so /continue-session can restore it with FULL tier.
+
+# Read stdin to get session_id (required by hook protocol)
+INPUT=$(cat)
+
+# Script location for sibling script references
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Get context percentage from check-context.sh
+CONTEXT_SCRIPT="$SCRIPT_DIR/../check-context.sh"
+if [[ ! -x "$CONTEXT_SCRIPT" ]]; then
+    # graceful degradation: if check-context.sh not found, allow the tool
+    exit 0
+fi
+
+# Run check-context.sh and parse output
+eval "$("$CONTEXT_SCRIPT" 2>/dev/null)" 2>/dev/null
+
+# graceful degradation: if we can't get context, allow the tool
+if [[ -z "$CONTEXT_PERCENT" ]] || [[ "$CONTEXT_PERCENT" == "null" ]]; then
+    exit 0
+fi
+
+# Load critical threshold (default 80%)
+CRITICAL_THRESHOLD="${CRITICAL_THRESHOLD:-80}"
+
+# Check if at or above critical threshold
+if [[ "$CONTEXT_PERCENT" -ge "$CRITICAL_THRESHOLD" ]] 2>/dev/null; then
+    # Auto-save active agent to checkpoint before blocking
+    # This allows /continue-session to restore with FULL tier
+    source "$SCRIPT_DIR/../lib/checkpoint.sh" 2>/dev/null || true
+
+    # Get session_id from input JSON
+    SESSION_ID=""
+    if command -v jq &>/dev/null && [[ -n "$INPUT" ]]; then
+        SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+    fi
+
+    # Look up active agent for this session
+    ACTIVE_AGENT=""
+    AGENT_FILE="${CLAUDE_PROJECT_DIR:-.}/.session/agents/${SESSION_ID}"
+    if [[ -n "$SESSION_ID" && -f "$AGENT_FILE" ]]; then
+        ACTIVE_AGENT=$(cat "$AGENT_FILE" 2>/dev/null)
+    fi
+
+    # Save agent checkpoint if we found one
+    if [[ -n "$ACTIVE_AGENT" ]]; then
+        checkpoint_save "circuit_breaker_agent" "$ACTIVE_AGENT" 2>/dev/null || true
+    fi
+
+    # Send error message to stderr (Claude will see this)
+    cat >&2 << EOF
+CONTEXT CIRCUIT BREAKER TRIGGERED
+
+Context usage: ${CONTEXT_PERCENT}% - CRITICAL (threshold: ${CRITICAL_THRESHOLD}%)
+
+Tool execution BLOCKED. You must stop and hand off.
+EOF
+
+    # Include agent info if available
+    if [[ -n "$ACTIVE_AGENT" ]]; then
+        cat >&2 << EOF
+
+Active agent saved: ${ACTIVE_AGENT}
+The agent will be restored with FULL context when you run /continue-session.
+EOF
+    fi
+
+    cat >&2 << EOF
+
+Required actions:
+1. Commit any pending changes
+2. Tell user to start fresh session with /continue-session
+
+DO NOT attempt further tool calls. This is a hard stop.
+
+To resume later: /continue-session
+EOF
+    # Exit 2 blocks the tool execution
+    exit 2
+fi
+
+# Below threshold: allow the tool
+exit 0

package/pennyfarthing-dist/scripts/hooks/context-warning.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env zsh
+# Context warning hook: Warn agent when context usage is high
+# Called by Claude Code before tool calls (PreToolUse)
+#
+# Input: JSON via stdin with tool_name, tool_input
+# Output: Warning message to stdout if context > 60%
+# Always exits 0 (warning only, never blocks)
+
+# Read and discard stdin (required by hook protocol)
+cat > /dev/null
+
+# Script location for sibling script references
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Get context percentage from check-context.sh
+CONTEXT_SCRIPT="$SCRIPT_DIR/../check-context.sh"
+if [[ ! -x "$CONTEXT_SCRIPT" ]]; then
+    exit 0  # Can't check, allow silently
+fi
+
+# Run check-context.sh and parse output
+eval "$("$CONTEXT_SCRIPT" 2>/dev/null)" 2>/dev/null
+
+# Check if we got a valid percentage
+if [[ -z "$CONTEXT_PERCENT" ]] || [[ "$CONTEXT_PERCENT" == "null" ]]; then
+    exit 0  # Can't determine, allow silently
+fi
+
+# Load thresholds from settings (defaults match check-context.sh)
+WARNING_THRESHOLD="${WARNING_THRESHOLD:-60}"
+CRITICAL_THRESHOLD="${CRITICAL_THRESHOLD:-85}"
+
+# Output warning if above threshold
+if [[ "$CONTEXT_PERCENT" -ge "$CRITICAL_THRESHOLD" ]] 2>/dev/null; then
+    cat << EOF
+
+---
+CONTEXT WARNING: ${CONTEXT_PERCENT}% (CRITICAL)
+
+Context usage is critically high. Recommended actions:
+1. Complete current task immediately
+2. Commit any pending changes
+3. Hand off to next agent or ask user to start fresh session
+
+Do NOT start new subtasks. Wrap up and hand off.
+---
+
+EOF
+elif [[ "$CONTEXT_PERCENT" -ge "$WARNING_THRESHOLD" ]] 2>/dev/null; then
+    cat << EOF
+
+---
+CONTEXT WARNING: ${CONTEXT_PERCENT}%
+
+Context usage is high. Consider:
+- Wrapping up current task soon
+- Preparing for handoff to next agent
+- Avoiding large file reads or complex operations
+---
+
+EOF
+fi
+
+# Always allow the tool (we're warning, not blocking)
+exit 0

package/pennyfarthing-dist/scripts/hooks/otel-auto-config.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# otel-auto-config.sh - Auto-configure OTEL for Cyclist web mode (Story 20-1)
+#
+# This hook checks for a .cyclist-port file in the project directory.
+# If found, it sets the OTEL environment variables to connect Claude Code
+# telemetry to the running Cyclist server.
+#
+# Usage: Source this script early in Claude Code startup to enable auto-config.
+#   source /path/to/otel-auto-config.sh
+#
+# Prerequisites:
+#   - Cyclist must be running in web mode (writes .cyclist-port file)
+#   - CLAUDE_PROJECT_DIR must be set (standard in Claude Code environment)
+
+# Determine project directory
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+PORT_FILE="$PROJECT_DIR/.cyclist-port"
+
+# Check if port file exists
+if [[ -f "$PORT_FILE" ]]; then
+  # Read the port number
+  PORT=$(cat "$PORT_FILE" 2>/dev/null)
+
+  # Validate port is a number
+  if [[ "$PORT" =~ ^[0-9]+$ ]]; then
+    # Set OTEL environment variables
+    export OTEL_EXPORTER_OTLP_PROTOCOL="http/json"
+    export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:$PORT"
+
+    # Optional: Log for debugging (can be silenced by setting CYCLIST_QUIET=1)
+    if [[ -z "$CYCLIST_QUIET" ]]; then
+      echo "[otel-auto-config] Configured OTEL to http://localhost:$PORT" >&2
+    fi
+  fi
+fi

package/pennyfarthing-dist/scripts/hooks/post-merge.sh

@@ -0,0 +1,150 @@
+#!/bin/bash
+# post-merge.sh - Git hook for automatic sprint YAML updates after PR merge
+# Story 8-1: Git Hook for PR Merge Detection
+#
+# This hook runs after git pull or git merge operations, detecting when a
+# story branch is merged and automatically updating the sprint YAML status.
+#
+# Installation:
+#   Installed to .git/hooks/post-merge by pennyfarthing init or doctor --fix
+#
+# Dependencies:
+#   - yq (for YAML manipulation)
+#   - sprint-common.sh (for shared sprint functions)
+
+set -uo pipefail
+
+# Self-locate (resolve symlink first for .git/hooks/ symlinks)
+REAL_SCRIPT="$(readlink -f "${BASH_SOURCE[0]:-$0}" 2>/dev/null || realpath "${BASH_SOURCE[0]:-$0}" 2>/dev/null || echo "${BASH_SOURCE[0]:-$0}")"
+source "$(dirname "$REAL_SCRIPT")/../lib/find-root.sh"
+
+# PROJECT_ROOT is now set by find-root.sh
+SESSION_DIR="$PROJECT_ROOT/.session"
+SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
+
+# Source sprint-common.sh for shared functions
+SPRINT_COMMON="$PROJECT_ROOT/.pennyfarthing/scripts/sprint/sprint-common.sh"
+if [[ -f "$SPRINT_COMMON" ]]; then
+    # shellcheck source=/dev/null
+    source "$SPRINT_COMMON"
+fi
+
+# 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 for non-matching branches
+extract_story_id() {
+    local branch="$1"
+
+    # Match pattern: feat/EPIC-STORY-description or feat/EPIC-STORY
+    if [[ "$branch" =~ ^feat/([0-9]+-[0-9]+) ]]; then
+        echo "${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
+update_story_status() {
+    local story_id="$1"
+    local new_status="${2:-done}"
+    local completed_date
+    completed_date=$(date +%Y-%m-%d)
+
+    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
+log_reconciliation() {
+    local story_id="$1"
+    local message="${2:-Merge detected}"
+    local timestamp
+    timestamp=$(date +"%Y-%m-%d %H:%M:%S")
+
+    # Ensure session directory exists
+    mkdir -p "$SESSION_DIR"
+
+    local log_file="$SESSION_DIR/reconciliation.log"
+
+    echo "[$timestamp] Story $story_id: $message" >> "$log_file"
+}
+
+# Main hook logic
+main() {
+    # Get the current branch after merge
+    local current_branch
+    current_branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+
+    # Only process if we're on develop or main (after a PR merge)
+    if [[ "$current_branch" != "develop" && "$current_branch" != "main" ]]; then
+        exit 0
+    fi
+
+    # Get the branches that were just merged
+    # The reflog shows what was merged: the previous HEAD and the merged commit
+    local merged_refs
+    merged_refs=$(git reflog -1 --format='%gs' 2>/dev/null)
+
+    # Check if this was a merge operation
+    if [[ ! "$merged_refs" =~ merge ]]; then
+        # Could be a pull with fast-forward - check for merged branches
+        # Look at recently merged branches by checking merge commits
+        :
+    fi
+
+    # Find recently merged feature branches by examining merge commits
+    local merge_commits
+    merge_commits=$(git log --merges --oneline -10 --since="5 minutes ago" 2>/dev/null)
+
+    # Extract branch names from merge commits
+    while IFS= read -r commit_line; do
+        # Parse "Merge pull request #X from user/feat/X-Y-description"
+        # or "Merge branch 'feat/X-Y-description'"
+        local branch_name=""
+
+        if [[ "$commit_line" =~ feat/([0-9]+-[0-9]+[a-zA-Z0-9-]*) ]]; then
+            branch_name="feat/${BASH_REMATCH[1]}"
+        fi
+
+        if [[ -n "$branch_name" ]]; then
+            local story_id
+            story_id=$(extract_story_id "$branch_name")
+
+            if [[ -n "$story_id" ]]; then
+                # Update sprint YAML
+                if update_story_status "$story_id" "done"; then
+                    log_reconciliation "$story_id" "Status updated to 'done' after merge (branch: $branch_name)"
+                else
+                    log_reconciliation "$story_id" "Failed to update status (branch: $branch_name)"
+                fi
+            fi
+        fi
+    done <<< "$merge_commits"
+}
+
+# Only run main when executed directly (not when sourced for testing)
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    main "$@"
+fi

package/pennyfarthing-dist/scripts/hooks/pre-commit.sh

@@ -0,0 +1,190 @@
+#!/bin/bash
+# pre-commit.sh - Git hook to enforce branch protection and agent validation
+#
+# Checks:
+# 1. Prevents direct commits to protected branches (main, develop)
+#    Exception: sprint/ folder commits allowed on develop
+# 2. Validates agent files when pennyfarthing-dist/agents/*.md is modified
+# 3. Validates sprint YAML files when sprint/*.yaml is modified
+#
+# Installation:
+#   Installed to .git/hooks/pre-commit by pennyfarthing init or doctor --fix
+#   Or symlink: ln -sf ../../pennyfarthing-dist/scripts/hooks/pre-commit.sh .git/hooks/pre-commit
+
+set -uo pipefail
+
+# Find project root
+# Try find-root.sh via symlink resolution first, then fall back to .git location
+REAL_SCRIPT="$(readlink -f "${BASH_SOURCE[0]:-$0}" 2>/dev/null || realpath "${BASH_SOURCE[0]:-$0}" 2>/dev/null || echo "${BASH_SOURCE[0]:-$0}")"
+FIND_ROOT="$(dirname "$REAL_SCRIPT")/../lib/find-root.sh"
+if [[ -f "$FIND_ROOT" ]]; then
+    source "$FIND_ROOT"
+else
+    # Running as a copy in .git/hooks/ — derive PROJECT_ROOT from git dir
+    PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../.." && pwd)"
+    export PROJECT_ROOT
+fi
+
+# =============================================================================
+# Check 1: Branch Protection
+# =============================================================================
+
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+PROTECTED_BRANCHES="^(main|develop)$"
+
+if [[ $BRANCH =~ $PROTECTED_BRANCHES ]]; then
+    # Special case: Allow sprint/ folder commits on develop branch
+    if [[ $BRANCH == "develop" ]]; then
+        STAGED_FILES=$(git diff --cached --name-only)
+        NON_SPRINT_FILES=$(echo "$STAGED_FILES" | grep -v "^sprint/")
+
+        # If all staged files are in sprint/, allow the commit
+        if [ -z "$NON_SPRINT_FILES" ] && [ -n "$STAGED_FILES" ]; then
+            # Continue to agent validation check
+            :
+        else
+            echo ""
+            echo "COMMIT BLOCKED"
+            echo ""
+            echo "You are trying to commit directly to: $BRANCH"
+            echo "This violates the git workflow rules."
+            echo ""
+            echo "Protected branches: main, develop"
+            echo ""
+            echo "What to do:"
+            echo "1. Create a feature branch:"
+            echo "   git checkout -b <type>/<epic-story>-<description>"
+            echo ""
+            echo "2. Example:"
+            echo "   git checkout -b feat/8-2-add-authentication"
+            echo ""
+            echo "3. Then commit your changes on the feature branch"
+            echo ""
+            echo "Exception: Sprint tracking files (sprint/*) can be committed to develop"
+            echo ""
+            exit 1
+        fi
+    else
+        echo ""
+        echo "COMMIT BLOCKED - Cannot commit directly to $BRANCH"
+        echo ""
+        exit 1
+    fi
+fi
+
+# =============================================================================
+# Check 2: Agent File Validation
+# =============================================================================
+
+STAGED_FILES=$(git diff --cached --name-only 2>/dev/null || true)
+AGENT_FILES=$(echo "$STAGED_FILES" | grep "^pennyfarthing-dist/agents/.*\.md$" || true)
+
+if [[ -n "$AGENT_FILES" ]]; then
+    echo "Agent files staged for commit:"
+    echo "$AGENT_FILES" | sed 's/^/  /'
+    echo ""
+
+    VALIDATOR="$PROJECT_ROOT/pennyfarthing-dist/scripts/validation/validate-agent-schema.sh"
+
+    if [[ -x "$VALIDATOR" ]]; then
+        echo "Running agent schema validation..."
+        echo ""
+
+        if ! "$VALIDATOR"; then
+            echo ""
+            echo "COMMIT BLOCKED - Agent validation failed"
+            echo ""
+            echo "Fix the validation errors above and try again."
+            echo "Run 'just validate-agents -v' for detailed output."
+            echo ""
+            exit 1
+        fi
+
+        echo ""
+        echo "✓ Agent validation passed"
+    else
+        echo "Warning: Agent validator not found at $VALIDATOR"
+        echo "Skipping agent validation."
+    fi
+fi
+
+# =============================================================================
+# Check 3: Sprint YAML Validation
+# =============================================================================
+
+SPRINT_YAML_FILES=$(git diff --cached --name-only -- 'sprint/*.yaml' 'sprint/archive/*.yaml' 2>/dev/null \
+    | grep -v 'sprint-template\.yaml$' \
+    | grep -v 'sprint/completed\.yaml$' || true)
+
+if [[ -n "$SPRINT_YAML_FILES" ]]; then
+    echo "Sprint YAML files staged for commit:"
+    echo "$SPRINT_YAML_FILES" | sed 's/^/  /'
+    echo ""
+
+    # Find python3
+    PYTHON=""
+    if command -v python3 &>/dev/null; then
+        PYTHON="python3"
+    elif command -v python &>/dev/null; then
+        PYTHON="python"
+    fi
+
+    if [[ -z "$PYTHON" ]]; then
+        echo "Warning: Python not found, skipping sprint YAML validation."
+    else
+        echo "Running sprint YAML validation..."
+
+        # Set PYTHONPATH to include pennyfarthing source
+        PYTHONPATH_ORIG="${PYTHONPATH:-}"
+        if [[ -d "$PROJECT_ROOT/pennyfarthing" ]]; then
+            export PYTHONPATH="$PROJECT_ROOT/pennyfarthing${PYTHONPATH_ORIG:+:$PYTHONPATH_ORIG}"
+        fi
+
+        VALIDATION_FAILED=0
+        while IFS= read -r yaml_file; do
+            FULL_PATH="$PROJECT_ROOT/$yaml_file"
+            if [[ ! -f "$FULL_PATH" ]]; then
+                echo "  Warning: $yaml_file not found (deleted?), skipping"
+                continue
+            fi
+            if ! $PYTHON -c "
+import sys
+from pathlib import Path
+from pennyfarthing_scripts.sprint.validate_cmd import validate_sprint_yaml
+result = validate_sprint_yaml(Path(sys.argv[1]))
+if result.errors:
+    for e in result.errors:
+        line = f' (line {e.line})' if e.line else ''
+        print(f'  ERROR [{e.category}]{line}: {e.message}', file=sys.stderr)
+if result.format_issues:
+    for f in result.format_issues:
+        print(f'  FORMAT: {f.message}', file=sys.stderr)
+sys.exit(0 if result.valid else 1)
+" "$FULL_PATH"; then
+                VALIDATION_FAILED=1
+            fi
+        done <<< "$SPRINT_YAML_FILES"
+
+        # Restore PYTHONPATH
+        if [[ -n "$PYTHONPATH_ORIG" ]]; then
+            export PYTHONPATH="$PYTHONPATH_ORIG"
+        else
+            unset PYTHONPATH
+        fi
+
+        if [[ $VALIDATION_FAILED -eq 1 ]]; then
+            echo ""
+            echo "COMMIT BLOCKED - Sprint YAML validation failed"
+            echo ""
+            echo "Fix: Review errors above, then run:"
+            echo "  python3 -m pennyfarthing_scripts.sprint.validate_cmd --fix <file>"
+            echo ""
+            exit 1
+        fi
+
+        echo "✓ Sprint YAML validation passed"
+        echo ""
+    fi
+fi
+
+exit 0