@pennyfarthing/core 7.5.0 → 7.6.0

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

@@ -0,0 +1,87 @@
+#!/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/bell-mode.json - { "enabled": 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
+
+BELL_MODE_CONFIG="$PROJECT_ROOT/.pennyfarthing/bell-mode.json"
+BELL_QUEUE_FILE="$PROJECT_ROOT/.pennyfarthing/bell-queue.json"
+
+# Check if bell mode is enabled
+if [[ ! -f "$BELL_MODE_CONFIG" ]]; then
+  exit 0
+fi
+
+ENABLED=$(cat "$BELL_MODE_CONFIG" 2>/dev/null | grep -o '"enabled"[[:space:]]*:[[:space:]]*true' || 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
+
+# Output the hook response JSON
+cat << EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "User feedback: $FIRST_MESSAGE_TEXT"
+  }
+}
+EOF
+
+# Remove the first message from the queue (for next invocation)
+# Use jq if available, otherwise leave queue management to the TypeScript side
+# Run in background and ignore errors to avoid blocking hook response
+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
+
+exit 0

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

@@ -0,0 +1,60 @@
+#!/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
+# 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.
+
+# 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
+    # 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
+    # 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.
+
+Required actions:
+1. Save checkpoint: Run checkpoint_save "{phase}" "{work_summary}"
+2. Update session file with current progress
+3. Commit any pending changes
+4. Hand off to next agent OR tell user to start fresh session
+
+DO NOT attempt further tool calls. This is a hard stop.
+
+To resume later: /continue-session (story 3-4)
+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,166 @@
+#!/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
+
+# 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
+}
+
+# Initialize paths
+PROJECT_ROOT="$(find_project_root 2>/dev/null || echo "")"
+if [[ -z "$PROJECT_ROOT" ]]; then
+    # Not in a pennyfarthing project, silently exit
+    exit 0
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+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,50 @@
+#!/bin/bash
+# pre-commit.sh - Git hook to enforce branch protection
+#
+# Prevents direct commits to protected branches (main, develop).
+# Exception: sprint/ folder commits allowed on develop for administrative tracking.
+#
+# 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
+
+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
+            exit 0
+        fi
+    fi
+
+    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
+
+exit 0

package/pennyfarthing-dist/scripts/hooks/pre-edit-check.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env zsh
+# Pre-edit hook: Verify edits don't touch protected files
+# Called by Claude Code before Edit/Write tool calls
+#
+# Input: JSON via stdin with tool_name, tool_input
+# Output: Exit 0 to allow, Exit 2 to block (stderr shown to Claude)
+
+set -euo pipefail
+
+# Read input from stdin
+input=$(cat)
+
+# Extract file path from tool input
+file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.path // ""')
+
+# Protected patterns (files that should never be edited automatically)
+protected_patterns=(
+    "*.env"
+    "*.pem"
+    "*.key"
+    "*credentials*"
+    "*secrets*"
+    ".git/*"
+    "node_modules/*"
+    "vendor/*"
+)
+
+# Pennyfarthing managed files protection
+# These are managed by `pennyfarthing update`, don't edit directly
+# EXCEPTION: If we ARE in the pennyfarthing library itself, allow edits
+is_pennyfarthing_lib=false
+if [[ -d "${CLAUDE_PROJECT_DIR:-$PWD}/pennyfarthing-dist" ]]; then
+    is_pennyfarthing_lib=true
+fi
+
+if [[ "$file_path" == *".claude/pennyfarthing/"* ]] && [[ "$is_pennyfarthing_lib" == "false" ]]; then
+    echo "BLOCKED: Cannot edit managed pennyfarthing files." >&2
+    echo "File: $file_path" >&2
+    echo "" >&2
+    echo "These files are managed by pennyfarthing and will be overwritten on update." >&2
+    echo "Instead:" >&2
+    echo "  - Put project-specific customizations in .claude/project/" >&2
+    echo "  - For framework changes, edit the pennyfarthing repo and run 'pennyfarthing update'" >&2
+    exit 2
+fi
+
+# Check if file matches any protected pattern
+for pattern in "${protected_patterns[@]}"; do
+    if [[ "$file_path" == $pattern ]]; then
+        echo "BLOCKED: Cannot edit protected file matching pattern: $pattern" >&2
+        echo "File: $file_path" >&2
+        exit 2
+    fi
+done
+
+# Additional check: warn on certain file types but allow
+warn_patterns=(
+    "*.md"
+    "*.json"
+)
+
+# For warnings, just log to stderr but allow (exit 0)
+for pattern in "${warn_patterns[@]}"; do
+    if [[ "$file_path" == $pattern ]]; then
+        # Could log warnings here if needed
+        :
+    fi
+done
+
+# Allow the edit
+exit 0

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

@@ -0,0 +1,54 @@
+#!/bin/bash
+# pre-push.sh - Git hook to remind about Jira sync before push
+#
+# Checks if sprint files were modified and reminds to sync to Jira.
+#
+# Installation:
+#   Installed to .git/hooks/pre-push by pennyfarthing init or doctor --fix
+#   Or symlink: ln -sf ../../pennyfarthing-dist/scripts/hooks/pre-push.sh .git/hooks/pre-push
+
+set -uo pipefail
+
+# 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
+        return 1
+    fi
+}
+
+PROJECT_ROOT="$(find_project_root 2>/dev/null || echo "")"
+if [[ -z "$PROJECT_ROOT" ]]; then
+    exit 0
+fi
+
+SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
+
+# Check if there are uncommitted changes to sprint file
+if git diff --name-only | grep -q "sprint/current-sprint.yaml"; then
+    echo "Warning: current-sprint.yaml has uncommitted changes"
+    echo "   Consider committing before pushing"
+    echo ""
+fi
+
+# Get the range of commits being pushed
+REMOTE="$1"
+URL="$2"
+
+while read local_ref local_sha remote_ref remote_sha; do
+    if [ "$local_sha" != "0000000000000000000000000000000000000000" ]; then
+        # Check if sprint file changed in this push
+        if git diff --name-only "$remote_sha..$local_sha" 2>/dev/null | grep -q "sprint/current-sprint.yaml"; then
+            echo "Sprint changes detected in push"
+            echo "   Reminder: Sync to Jira if story statuses changed"
+            echo ""
+        fi
+    fi
+done
+
+exit 0

package/pennyfarthing-dist/scripts/hooks/session-start.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env zsh
+# Session start hook: Initialize environment for Claude Code session
+# Called by Claude Code when a new session starts
+#
+# Uses CLAUDE_ENV_FILE to persist environment variables for the session.
+# Projects using pennyfarthing can add their own hooks for project-specific vars.
+#
+# Also validates previous session checkpoint to detect cross-session state changes.
+
+set -euo pipefail
+
+# Load shared functions
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/../lib/checkpoint.sh"
+
+# Read input from stdin (contains session_id, source, cwd, etc.)
+input=$(cat)
+session_id=$(echo "$input" | jq -r '.session_id // "unknown"')
+source_type=$(echo "$input" | jq -r '.source // "unknown"')
+
+# Ensure .session directory exists
+mkdir -p "$CLAUDE_PROJECT_DIR/.session"
+mkdir -p "$CLAUDE_PROJECT_DIR/.session/agents"
+
+# Note: Agent cleanup is handled by agent-session.sh (7-day TTL) to preserve multi-session state
+# DO NOT clear .session/agents/* here - it breaks parallel sessions
+
+# Create session log entry
+echo "$(date -Iseconds) | Session $source_type: $session_id" >> "$CLAUDE_PROJECT_DIR/.session/session-log.txt"
+
+# Validate previous session checkpoint (cross-session continuity)
+validate_checkpoint() {
+    local prev_state
+    prev_state=$(checkpoint_restore "session_state")
+
+    if [[ -z "$prev_state" ]]; then
+        # No previous checkpoint - fresh start
+        return 0
+    fi
+
+    # Parse checkpoint data (format: key=value;key=value;...)
+    local prev_sha prev_agent prev_story prev_phase prev_session
+    prev_sha=$(echo "$prev_state" | tr ';' '\n' | grep '^sha=' | cut -d= -f2)
+    prev_agent=$(echo "$prev_state" | tr ';' '\n' | grep '^agent=' | cut -d= -f2)
+    prev_story=$(echo "$prev_state" | tr ';' '\n' | grep '^story=' | cut -d= -f2)
+    prev_phase=$(echo "$prev_state" | tr ';' '\n' | grep '^phase=' | cut -d= -f2)
+    prev_session=$(echo "$prev_state" | tr ';' '\n' | grep '^session=' | cut -d= -f2)
+
+    # Get current git SHA
+    local current_sha=""
+    if command -v git &>/dev/null && git rev-parse --git-dir &>/dev/null; then
+        current_sha=$(git rev-parse --short HEAD 2>/dev/null || echo "")
+    fi
+
+    # Compare git state
+    if [[ -n "$prev_sha" && -n "$current_sha" && "$prev_sha" != "$current_sha" ]]; then
+        # Git state changed between sessions - write warning to session log
+        local warning="CROSS_SESSION_DRIFT: Git changed since last session (was: $prev_sha, now: $current_sha)"
+        if [[ -n "$prev_story" ]]; then
+            warning="$warning | Story: $prev_story"
+        fi
+        if [[ -n "$prev_agent" ]]; then
+            warning="$warning | Agent: $prev_agent"
+        fi
+        echo "$(date -Iseconds) | $warning" >> "$CLAUDE_PROJECT_DIR/.session/session-log.txt"
+
+        # Also write to a dedicated drift log for easy scanning
+        echo "$(date -Iseconds) | prev_sha=$prev_sha | current_sha=$current_sha | story=$prev_story | agent=$prev_agent | phase=$prev_phase" >> "$CLAUDE_PROJECT_DIR/.session/drift-log.txt"
+    fi
+}
+
+# Run checkpoint validation (don't fail if it errors)
+validate_checkpoint 2>/dev/null || true
+
+# Write environment variables to CLAUDE_ENV_FILE (persists for session)
+if [ -n "${CLAUDE_ENV_FILE:-}" ]; then
+    cat >> "$CLAUDE_ENV_FILE" << EOF
+# Pennyfarthing core environment
+export PROJECT_ROOT="$CLAUDE_PROJECT_DIR"
+export SESSION_ID="$session_id"
+EOF
+
+    # Auto-configure OTEL if Cyclist is running (Story 20-1)
+    PORT_FILE="$CLAUDE_PROJECT_DIR/.cyclist-port"
+    if [[ -f "$PORT_FILE" ]]; then
+        CYCLIST_PORT=$(cat "$PORT_FILE" 2>/dev/null)
+        if [[ "$CYCLIST_PORT" =~ ^[0-9]+$ ]]; then
+            cat >> "$CLAUDE_ENV_FILE" << EOF
+# OTEL auto-configuration for Cyclist (Story 20-1)
+export OTEL_EXPORTER_OTLP_PROTOCOL="http/json"
+export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:$CYCLIST_PORT"
+EOF
+        fi
+    fi
+fi
+
+exit 0