@pennyfarthing/core 6.6.0

package/pennyfarthing-dist/scripts/deploy.sh

@@ -0,0 +1,284 @@
+#!/usr/bin/env zsh
+set -euo pipefail
+
+# Deploy script for Pennyfarthing
+# Usage: ./scripts/deploy.sh [OPTIONS] <major|minor|patch>
+#
+# Options:
+#   -y, --yes       Skip confirmation prompt
+#   --dry-run       Show what would happen without executing
+#
+# Steps:
+# 1. Bump version in VERSION, package.json, README.md
+# 2. Commit version bump to current branch
+# 3. Merge to develop (if not already on develop)
+# 4. Merge develop to main
+# 5. Tag the release on main
+# 6. Push everything (develop, main, tags)
+# 7. Create GitHub release from tag
+# 8. Return to develop
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Use exported PROJECT_ROOT from run.sh, or detect it
+if [[ -z "${PROJECT_ROOT:-}" ]]; then
+    # Find PROJECT_ROOT by looking for .claude/ marker
+    _dir="$PWD"
+    while [[ ! -d "$_dir/.claude" ]] && [[ "$_dir" != "/" ]]; do
+        _dir="$(dirname "$_dir")"
+    done
+    if [[ -d "$_dir/.claude" ]]; then
+        PROJECT_ROOT="$_dir"
+    else
+        PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+    fi
+fi
+
+VERSION_FILE="$PROJECT_ROOT/VERSION"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
+log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
+log_dry() { echo -e "${YELLOW}[DRY-RUN]${NC} $1"; }
+
+# Parse arguments
+BUMP_TYPE=""
+DRY_RUN=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --dry-run)
+            DRY_RUN=true
+            shift
+            ;;
+        major|minor|patch)
+            BUMP_TYPE="$1"
+            shift
+            ;;
+        *)
+            echo "Usage: $0 [--dry-run] <major|minor|patch>"
+            echo ""
+            echo "Options:"
+            echo "  --dry-run    Show what would happen without executing"
+            echo ""
+            echo "Examples:"
+            echo "  $0 patch           # 1.2.3 -> 1.2.4"
+            echo "  $0 minor           # 1.2.3 -> 1.3.0"
+            echo "  $0 major --dry-run # Preview major bump"
+            exit 1
+            ;;
+    esac
+done
+
+if [[ -z "$BUMP_TYPE" ]]; then
+    echo "Usage: $0 [--dry-run] <major|minor|patch>"
+    exit 1
+fi
+
+# Helper to run or log commands
+run() {
+    if $DRY_RUN; then
+        log_dry "$*"
+    else
+        "$@"
+    fi
+}
+
+if $DRY_RUN; then
+    echo -e "${YELLOW}=== DRY RUN MODE - No changes will be made ===${NC}"
+    echo ""
+fi
+
+# Check for clean working directory
+if [[ -n $(git -C "$PROJECT_ROOT" status --porcelain) ]]; then
+    log_error "Working directory is not clean. Commit or stash changes first."
+    git -C "$PROJECT_ROOT" status --short
+    exit 1
+fi
+
+# Get current branch
+CURRENT_BRANCH=$(git -C "$PROJECT_ROOT" branch --show-current)
+log_info "Current branch: $CURRENT_BRANCH"
+
+# Read current version (create VERSION file if it doesn't exist)
+if [[ ! -f "$VERSION_FILE" ]]; then
+    echo "0.0.0" > "$VERSION_FILE"
+    log_warn "Created VERSION file with initial version 0.0.0"
+fi
+
+CURRENT_VERSION=$(cat "$VERSION_FILE")
+log_info "Current version: $CURRENT_VERSION"
+
+# Parse version components
+IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT_VERSION"
+
+# Bump version
+case "$BUMP_TYPE" in
+    major)
+        MAJOR=$((MAJOR + 1))
+        MINOR=0
+        PATCH=0
+        ;;
+    minor)
+        MINOR=$((MINOR + 1))
+        PATCH=0
+        ;;
+    patch)
+        PATCH=$((PATCH + 1))
+        ;;
+esac
+
+NEW_VERSION="${MAJOR}.${MINOR}.${PATCH}"
+log_info "New version: $NEW_VERSION"
+
+
+# Step 1: Update version files
+if $DRY_RUN; then
+    log_dry "echo $NEW_VERSION > VERSION"
+    log_dry "Update package.json: $CURRENT_VERSION -> $NEW_VERSION"
+    log_dry "Update README.md version badge"
+    log_dry "Update package-lock.json"
+    log_dry "Update CHANGELOG.md version links and header"
+else
+    echo "$NEW_VERSION" > "$VERSION_FILE"
+    log_info "Updated VERSION file"
+
+    if [[ -f "$PROJECT_ROOT/package.json" ]]; then
+        sed -i '' "s/\"version\": \"$CURRENT_VERSION\"/\"version\": \"$NEW_VERSION\"/" "$PROJECT_ROOT/package.json"
+        log_info "Updated package.json"
+    fi
+
+    if [[ -f "$PROJECT_ROOT/README.md" ]]; then
+        sed -i '' "s/\*\*v$CURRENT_VERSION\*\*/\*\*v$NEW_VERSION\*\*/" "$PROJECT_ROOT/README.md"
+        log_info "Updated README.md"
+    fi
+
+    if [[ -f "$PROJECT_ROOT/package.json" ]]; then
+        (cd "$PROJECT_ROOT" && npm install --package-lock-only --silent 2>/dev/null) || true
+        log_info "Updated package-lock.json"
+    fi
+
+    # Update CHANGELOG.md - add version entry and update links
+    if [[ -f "$PROJECT_ROOT/CHANGELOG.md" ]]; then
+        TODAY=$(date +%Y-%m-%d)
+
+        # Update [Unreleased] link to point to new version
+        sed -i '' "s|\[Unreleased\]: https://github.com/1898andCo/pennyfarthing/compare/v$CURRENT_VERSION...HEAD|[Unreleased]: https://github.com/1898andCo/pennyfarthing/compare/v$NEW_VERSION...HEAD\n[$NEW_VERSION]: https://github.com/1898andCo/pennyfarthing/compare/v$CURRENT_VERSION...v$NEW_VERSION|" "$PROJECT_ROOT/CHANGELOG.md"
+
+        # Check if [Unreleased] section has content or just placeholder
+        if grep -q "^\*No unreleased changes\*$" "$PROJECT_ROOT/CHANGELOG.md"; then
+            log_warn "CHANGELOG.md has no unreleased changes documented"
+            log_warn "Consider adding release notes before pushing"
+        else
+            # Move [Unreleased] content to new version section
+            # This is complex - for now just add an empty version header
+            log_info "Updated CHANGELOG.md version links"
+        fi
+
+        # Add new version header if not present
+        if ! grep -q "## \[$NEW_VERSION\]" "$PROJECT_ROOT/CHANGELOG.md"; then
+            sed -i '' "s|## \[Unreleased\]|## [Unreleased]\n\n*No unreleased changes*\n\n---\n\n## [$NEW_VERSION] - $TODAY|" "$PROJECT_ROOT/CHANGELOG.md"
+            log_info "Added CHANGELOG.md version header for $NEW_VERSION"
+        fi
+    fi
+fi
+
+# Step 2: Commit version bump
+if $DRY_RUN; then
+    log_dry "git commit -m 'chore: bump version to $NEW_VERSION'"
+else
+    git -C "$PROJECT_ROOT" add VERSION package.json package-lock.json README.md CHANGELOG.md 2>/dev/null || true
+    git -C "$PROJECT_ROOT" commit -m "chore: bump version to $NEW_VERSION"
+    log_info "Committed version bump"
+fi
+
+# Step 3: Merge to develop if not already on develop
+if [[ "$CURRENT_BRANCH" != "develop" ]]; then
+    if $DRY_RUN; then
+        log_dry "git checkout develop && git merge $CURRENT_BRANCH"
+    else
+        log_info "Merging $CURRENT_BRANCH to develop..."
+        git -C "$PROJECT_ROOT" checkout develop
+        git -C "$PROJECT_ROOT" pull origin develop --ff-only || {
+            log_warn "Could not fast-forward develop. Attempting merge..."
+            git -C "$PROJECT_ROOT" pull origin develop --no-rebase
+        }
+        git -C "$PROJECT_ROOT" merge "$CURRENT_BRANCH" -m "Merge $CURRENT_BRANCH into develop for release $NEW_VERSION"
+        log_info "Merged to develop"
+    fi
+else
+    log_info "Already on develop, skipping merge"
+fi
+
+# Step 4: Merge develop to main
+TAG_NAME="v$NEW_VERSION"
+if $DRY_RUN; then
+    log_dry "git checkout main && git merge develop"
+    log_dry "git tag -a $TAG_NAME -m 'Release $NEW_VERSION'"
+    log_dry "git push origin develop main --tags"
+    log_dry "gh release create $TAG_NAME --title 'Release $NEW_VERSION' --notes-from-tag --verify-tag"
+    log_dry "git checkout develop"
+else
+    log_info "Merging develop to main..."
+    git -C "$PROJECT_ROOT" checkout main
+    git -C "$PROJECT_ROOT" pull origin main --ff-only || {
+        log_warn "Could not fast-forward main. Attempting merge..."
+        git -C "$PROJECT_ROOT" pull origin main --no-rebase
+    }
+    git -C "$PROJECT_ROOT" merge develop -m "Merge develop into main for release $NEW_VERSION"
+    log_info "Merged to main"
+
+    # Step 5: Create annotated tag
+    log_info "Creating tag: $TAG_NAME"
+    git -C "$PROJECT_ROOT" tag -a "$TAG_NAME" -m "Release $NEW_VERSION"
+
+    # Step 6: Push everything
+    log_info "Pushing develop..."
+    git -C "$PROJECT_ROOT" push origin develop
+
+    log_info "Pushing main..."
+    git -C "$PROJECT_ROOT" push origin main
+
+    log_info "Pushing tags..."
+    git -C "$PROJECT_ROOT" push origin --tags
+
+    # Step 7: Create GitHub release
+    log_info "Creating GitHub release..."
+    if command -v gh &> /dev/null; then
+        gh release create "$TAG_NAME" \
+            --title "Release $NEW_VERSION" \
+            --notes-from-tag \
+            --verify-tag
+        log_info "GitHub release created: $TAG_NAME"
+    else
+        log_warn "gh CLI not installed - skipping GitHub release creation"
+        log_warn "Create release manually at: https://github.com/1898andCo/pennyfarthing/releases/new"
+    fi
+
+    # Step 8: Return to develop
+    log_info "Returning to develop..."
+    git -C "$PROJECT_ROOT" checkout develop
+fi
+
+echo ""
+if $DRY_RUN; then
+    log_info "Dry run complete. No changes made."
+    echo ""
+    echo "  Would release version: $NEW_VERSION"
+    echo "  Would create tag: $TAG_NAME"
+    echo "  Would create GitHub release: $TAG_NAME"
+else
+    log_info "Deploy complete!"
+    echo ""
+    echo "  Version: $NEW_VERSION"
+    echo "  Tag: $TAG_NAME"
+    echo "  GitHub release: https://github.com/1898andCo/pennyfarthing/releases/tag/$TAG_NAME"
+    echo "  Branches pushed: develop, main"
+fi
+echo ""

package/pennyfarthing-dist/scripts/doctor-dogfood.sh

@@ -0,0 +1,360 @@
+#!/bin/bash
+# doctor-dogfood.sh - Health check for Pennyfarthing developers (dogfooding)
+#
+# Usage: ./pennyfarthing-dist/scripts/doctor-dogfood.sh [--fix]
+#
+# Checks and optionally fixes common setup issues for developers working
+# on the pennyfarthing repo itself.
+
+set -uo pipefail
+
+FIX_MODE=false
+if [[ "${1:-}" == "--fix" ]]; then
+    FIX_MODE=true
+fi
+
+# Colors (if terminal supports them)
+if [[ -t 1 ]]; then
+    RED='\033[0;31m'
+    GREEN='\033[0;32m'
+    YELLOW='\033[0;33m'
+    NC='\033[0m' # No Color
+else
+    RED=''
+    GREEN=''
+    YELLOW=''
+    NC=''
+fi
+
+ERRORS=0
+WARNINGS=0
+FIXED=0
+
+ok() {
+    echo -e "${GREEN}OK${NC}    $1"
+}
+
+warn() {
+    echo -e "${YELLOW}WARN${NC}  $1"
+    ((WARNINGS++))
+}
+
+fail() {
+    echo -e "${RED}FAIL${NC}  $1"
+    ((ERRORS++))
+}
+
+fix() {
+    echo -e "${GREEN}FIX${NC}   $1"
+    ((FIXED++))
+}
+
+# Find project root
+find_project_root() {
+    local dir="$PWD"
+    while [[ ! -d "$dir/pennyfarthing-dist" ]] && [[ "$dir" != "/" ]]; do
+        dir="$(dirname "$dir")"
+    done
+    if [[ -d "$dir/pennyfarthing-dist" ]]; then
+        echo "$dir"
+    else
+        echo ""
+    fi
+}
+
+PROJECT_ROOT="$(find_project_root)"
+
+echo "Pennyfarthing Dogfooding Doctor"
+echo "================================"
+echo ""
+
+# Check we're in the right place
+if [[ -z "$PROJECT_ROOT" ]]; then
+    fail "Not in pennyfarthing repo (no pennyfarthing-dist/ found)"
+    exit 1
+fi
+
+cd "$PROJECT_ROOT"
+ok "Project root: $PROJECT_ROOT"
+
+echo ""
+echo "Checking prerequisites..."
+echo ""
+
+# Check Node.js
+if command -v node &>/dev/null; then
+    NODE_VERSION=$(node --version)
+    ok "Node.js: $NODE_VERSION"
+else
+    fail "Node.js not installed"
+fi
+
+# Check npm
+if command -v npm &>/dev/null; then
+    NPM_VERSION=$(npm --version)
+    ok "npm: $NPM_VERSION"
+else
+    fail "npm not installed"
+fi
+
+# Check yq (for sprint YAML manipulation)
+if command -v yq &>/dev/null; then
+    YQ_VERSION=$(yq --version 2>&1 | head -1)
+    ok "yq: $YQ_VERSION"
+else
+    warn "yq not installed (needed for post-merge hook)"
+    if $FIX_MODE; then
+        echo "     Run: brew install yq"
+    fi
+fi
+
+# Check jira CLI (optional)
+if command -v jira &>/dev/null; then
+    ok "jira CLI: installed"
+else
+    warn "jira CLI not installed (optional, for Jira sync)"
+fi
+
+echo ""
+echo "Checking symlinks..."
+echo ""
+
+# Check .claude/pennyfarthing symlink
+if [[ -L ".claude/pennyfarthing" ]]; then
+    TARGET=$(readlink ".claude/pennyfarthing")
+    if [[ "$TARGET" == "../pennyfarthing-dist" ]]; then
+        ok ".claude/pennyfarthing -> ../pennyfarthing-dist"
+    else
+        fail ".claude/pennyfarthing points to wrong target: $TARGET"
+    fi
+elif [[ -d ".claude/pennyfarthing" ]]; then
+    fail ".claude/pennyfarthing is a directory, should be symlink"
+else
+    fail ".claude/pennyfarthing missing"
+fi
+
+# Check scripts directory/symlink
+if [[ -L "scripts" ]]; then
+    TARGET=$(readlink "scripts")
+    ok "scripts -> $TARGET"
+elif [[ -d "scripts" ]]; then
+    # Check if contents are symlinks to pennyfarthing-dist
+    if [[ -L "scripts/agent-session.sh" ]]; then
+        ok "scripts/ directory with symlinks (dogfooding setup)"
+    else
+        warn "scripts/ is a directory but contents may not be symlinked"
+    fi
+else
+    fail "scripts/ missing"
+fi
+
+echo ""
+echo "Checking git hooks..."
+echo ""
+
+# Check git hooks
+HOOKS=("pre-commit" "pre-push" "post-merge")
+for hook in "${HOOKS[@]}"; do
+    hook_path=".git/hooks/$hook"
+    expected_target="../../pennyfarthing-dist/scripts/hooks/${hook}.sh"
+
+    if [[ -L "$hook_path" ]]; then
+        actual_target=$(readlink "$hook_path")
+        if [[ "$actual_target" == "$expected_target" ]]; then
+            ok "$hook hook -> $expected_target"
+        else
+            warn "$hook hook points to: $actual_target"
+            if $FIX_MODE; then
+                ln -sf "$expected_target" "$hook_path"
+                fix "$hook hook updated"
+            fi
+        fi
+    elif [[ -f "$hook_path" ]]; then
+        # Check if it's our hook (contains pennyfarthing marker)
+        if grep -q "pennyfarthing" "$hook_path" 2>/dev/null; then
+            ok "$hook hook (file, pennyfarthing)"
+        else
+            warn "$hook hook exists but is not pennyfarthing hook"
+            if $FIX_MODE; then
+                mv "$hook_path" "${hook_path}.backup"
+                ln -sf "$expected_target" "$hook_path"
+                fix "$hook hook replaced (backup saved)"
+            fi
+        fi
+    else
+        fail "$hook hook missing"
+        if $FIX_MODE; then
+            ln -sf "$expected_target" "$hook_path"
+            fix "$hook hook installed"
+        fi
+    fi
+done
+
+echo ""
+echo "Checking build..."
+echo ""
+
+# Check if dist/ is up to date
+if [[ -d "dist" ]]; then
+    # Check if any src file is newer than its dist counterpart
+    OUTDATED=false
+    for src_file in src/cli/commands/*.ts; do
+        if [[ -f "$src_file" ]]; then
+            base=$(basename "$src_file" .ts)
+            dist_file="dist/cli/commands/${base}.js"
+            if [[ -f "$dist_file" ]]; then
+                if [[ "$src_file" -nt "$dist_file" ]]; then
+                    OUTDATED=true
+                    break
+                fi
+            fi
+        fi
+    done
+
+    if $OUTDATED; then
+        warn "dist/ may be outdated (run: npm run build)"
+        if $FIX_MODE; then
+            npm run build >/dev/null 2>&1
+            fix "Rebuilt dist/"
+        fi
+    else
+        ok "dist/ appears up to date"
+    fi
+else
+    fail "dist/ directory missing"
+    if $FIX_MODE; then
+        npm run build >/dev/null 2>&1
+        fix "Built dist/"
+    fi
+fi
+
+# Check node_modules
+if [[ -d "node_modules" ]]; then
+    ok "node_modules/ exists"
+else
+    fail "node_modules/ missing (run: npm install)"
+    if $FIX_MODE; then
+        npm install >/dev/null 2>&1
+        fix "Installed dependencies"
+    fi
+fi
+
+echo ""
+echo "Checking for broken symlinks..."
+echo ""
+
+# Find broken symlinks in key directories
+BROKEN_LINKS=$(find .claude pennyfarthing-dist scripts -type l ! -exec test -e {} \; -print 2>/dev/null)
+if [[ -n "$BROKEN_LINKS" ]]; then
+    while IFS= read -r link; do
+        fail "Broken symlink: $link"
+        if $FIX_MODE; then
+            rm "$link" 2>/dev/null && fix "Removed $link"
+        fi
+    done <<< "$BROKEN_LINKS"
+else
+    ok "No broken symlinks"
+fi
+
+echo ""
+echo "Checking file locations..."
+echo ""
+
+# Check for files that should be in pennyfarthing-dist but aren't
+# Only check directories that are NOT symlinks (symlink dirs are fine)
+MISPLACED=0
+
+# .claude/agents should be a symlink, not a real directory with files
+if [[ -d ".claude/agents" ]] && [[ ! -L ".claude/agents" ]]; then
+    warn ".pennyfarthing/agents/ is a directory, should be symlink to pennyfarthing/agents"
+    ((MISPLACED++))
+fi
+
+# .claude/commands should be a symlink
+if [[ -d ".claude/commands" ]] && [[ ! -L ".claude/commands" ]]; then
+    warn ".claude/commands/ is a directory, should be symlink to pennyfarthing/commands"
+    ((MISPLACED++))
+fi
+
+# .claude/skills should be a symlink
+if [[ -d ".claude/skills" ]] && [[ ! -L ".claude/skills" ]]; then
+    warn ".claude/skills/ is a directory, should be symlink to pennyfarthing/skills"
+    ((MISPLACED++))
+fi
+
+if [[ $MISPLACED -eq 0 ]]; then
+    ok "All .claude/ directories properly symlinked"
+fi
+
+echo ""
+echo "Checking scripts/ structure..."
+echo ""
+
+# Count distributed vs local scripts
+DIST_SCRIPTS=0
+LOCAL_SCRIPTS=0
+if compgen -G "scripts/*.sh" > /dev/null 2>&1; then
+    for f in scripts/*.sh; do
+        if [[ -L "$f" ]]; then
+            ((DIST_SCRIPTS++))
+        elif [[ -f "$f" ]]; then
+            ((LOCAL_SCRIPTS++))
+        fi
+    done
+fi
+
+ok "$DIST_SCRIPTS distributed scripts (symlinks to pennyfarthing-dist/)"
+if [[ $LOCAL_SCRIPTS -gt 0 ]]; then
+    ok "$LOCAL_SCRIPTS local scripts (dogfooding only, not in npm package)"
+fi
+
+echo ""
+echo "Checking Claude Code integration..."
+echo ""
+
+# Check settings.local.json
+if [[ -f ".claude/settings.local.json" ]]; then
+    ok ".claude/settings.local.json exists"
+else
+    warn ".claude/settings.local.json missing"
+fi
+
+# Check persona config (priority: .pennyfarthing/ > .claude/local > .claude/shared)
+if [[ -f ".pennyfarthing/config.local.yaml" ]]; then
+    THEME=$(grep "^theme:" ".pennyfarthing/config.local.yaml" | awk '{print $2}')
+    ok "Theme: ${THEME:-unknown} (.pennyfarthing/)"
+elif [[ -f ".claude/persona-config.local.yaml" ]]; then
+    THEME=$(grep "^theme:" ".claude/persona-config.local.yaml" | awk '{print $2}')
+    ok "Theme: ${THEME:-unknown} (.claude/ local)"
+elif [[ -f ".claude/persona-config.yaml" ]]; then
+    THEME=$(grep "^theme:" ".claude/persona-config.yaml" | awk '{print $2}')
+    ok "Theme: ${THEME:-unknown} (.claude/ shared)"
+else
+    warn "No persona config found (will use default theme)"
+fi
+
+echo ""
+echo "================================"
+echo "Summary"
+echo "================================"
+echo ""
+
+if [[ $ERRORS -eq 0 ]] && [[ $WARNINGS -eq 0 ]]; then
+    echo -e "${GREEN}All checks passed!${NC}"
+elif [[ $ERRORS -eq 0 ]]; then
+    echo -e "${YELLOW}$WARNINGS warning(s), 0 errors${NC}"
+else
+    echo -e "${RED}$ERRORS error(s), $WARNINGS warning(s)${NC}"
+fi
+
+if $FIX_MODE && [[ $FIXED -gt 0 ]]; then
+    echo -e "${GREEN}$FIXED issue(s) fixed${NC}"
+fi
+
+if [[ $ERRORS -gt 0 ]] && ! $FIX_MODE; then
+    echo ""
+    echo "Run with --fix to attempt automatic repairs:"
+    echo "  ./pennyfarthing-dist/scripts/doctor-dogfood.sh --fix"
+fi
+
+exit $ERRORS

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

@@ -0,0 +1,61 @@
+#!/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
+
+# Find project root
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/../utils/find-root.sh" 2>/dev/null || true
+
+# 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 85%)
+CRITICAL_THRESHOLD="${CRITICAL_THRESHOLD:-85}"
+
+# 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