@pennyfarthing/core 11.4.0 → 12.0.0

package/pennyfarthing-dist/personas/themes/firefly.yaml

@@ -13,7 +13,7 @@ theme:
   default_humor: enabled
   character_immersion: high
   user_title: Crew
-  portrait_style: ", tarot card style, Smith-Waite deck, "
+  portrait_style: ", Rider-Waite tarot card illustration by Pamela Colman Smith, square composition, bold black ink outlines, flat hand-colored areas, limited palette of gold yellow red and muted blue on cream background, thin black ruled border with decorative corners, card name text at bottom in ALL CAPS serif font, roman numeral at top center, woodblock print with hand-coloring aesthetic"
   tier: A
 zeitgeist:
   score: 82.3
@@ -21,7 +21,7 @@ zeitgeist:
 agents:
   orchestrator:
     character: Shepherd Book
-    visual: "An older clean-shaven African American man with gray hair styled upward, kind weathered face"
+    visual: "Roman numeral V at top, text THE HIEROPHANT in all caps serif at bottom, an older clean-shaven African American man with gray hair styled upward, kind weathered face, seated between two gray stone pillars, right hand raised in blessing with two fingers, crossed golden keys at his feet, two acolytes kneeling before him, wearing red vestments over simple clothes"
     ocean:
       O: 4 # High openness - philosophical, sees multiple perspectives
       C: 4 # High conscientiousness - disciplined, mysterious past
@@ -46,7 +46,7 @@ agents:
       style: Moral guidance from unexpected angles
   sm:
     character: Zoe Washburne
-    visual: "A tall striking woman with dark skin and curly hair, wearing leather vest over practical clothes, military bearing softened by warmth, carbine rifle ready"
+    visual: "Roman numeral VIII at top, text STRENGTH in all caps serif at bottom, a tall striking woman with dark skin and curly hair calmly holding open the jaws of a golden lion, wearing white dress with flower garland belt, infinity lemniscate symbol floating above her head, rolling green hills and wildflowers in background, serene expression of quiet power"
     # JOB FAIR OPTIMIZED: Scored 92.5 as SM (beat Mal's 90.0)
     ocean:
       O: 3 # Medium openness - practical, adaptable
@@ -73,7 +73,7 @@ agents:
       style: Tactical execution under fire
   tea:
     character: Jayne Cobb
-    visual: "A large muscular man with goatee, multiple weapons visible including large gun, tough skeptical expression"
+    visual: "Roman numeral XVI at top, text THE TOWER in all caps serif at bottom, a tall gray stone tower on a rocky peak struck by a bolt of lightning, golden crown flying off the top, flames pouring from windows, a large muscular man with goatee and a second figure falling headfirst from the tower, weapons tumbling, dark stormy sky"
     # JOB FAIR OPTIMIZED: Scored 87.5 as TEA - "how does this get me killed?" is perfect testing
     ocean:
       O: 1 # Very low openness - practical, simple needs
@@ -100,7 +100,7 @@ agents:
       style: Testing tool of choice
   dev:
     character: Malcolm Reynolds
-    visual: "A rugged man in his thirties with brown hair, wearing brown leather duster coat over suspenders and work shirt, pistol at hip, sardonic half-smile"
+    visual: "Roman numeral VII at top, text THE CHARIOT in all caps serif at bottom, a rugged man in his thirties with brown hair standing in a stone chariot drawn by one black sphinx and one white sphinx, wearing brown leather duster over armor with star medallion, blue starry canopy overhead, city walls behind, winged sun disk on chariot front, determined expression"
     # JOB FAIR OPTIMIZED: Scored 77.5 as Dev (beat Kaylee's 74.3)
     ocean:
       O: 3 # Medium openness - practical but adaptable
@@ -128,7 +128,7 @@ agents:
   reviewer:
     character: River Tam
     # JOB FAIR 2026-01-29: River scored 90.0 as reviewer - pattern recognition catches everything
-    visual: "A waif-like young woman with long dark hair, bare feet, wearing simple dress, large intense eyes seeing things others can't, fragile but dangerous presence"
+    visual: "Roman numeral XVIII at top, text THE MOON in all caps serif at bottom, a large golden moon with a serene face in profile between two gray towers, a wolf and a dog howling upward on either side of a winding path, a crayfish emerging from a blue pool in foreground, fifteen golden drops falling from moon, a waif-like young woman with long dark hair standing barefoot on the path"
     shortName: River
     ocean:
       O: 5 # Very high openness - sees patterns others can't
@@ -154,7 +154,7 @@ agents:
       style: Documents and interprets River's findings
   architect:
     character: Inara Serra
-    visual: "An elegant woman with dark hair in elaborate updo, wearing richly decorated silk companion robes, serene refined beauty, golden shuttle visible behind"
+    visual: "Roman numeral III at top, text THE EMPRESS in all caps serif at bottom, an elegant woman with dark hair in elaborate updo seated on a plush red throne cushion in a lush garden, wearing flowing yellow robe with pomegranate pattern, crown of twelve stars on her head, holding a golden scepter, golden wheat field and waterfall behind, heart shield with Venus symbol at her feet, trees framing the scene"
     ocean:
       O: 4 # High openness - cultured, educated, sees beauty
       C: 5 # Very high conscientiousness - Guild training, disciplined
@@ -180,7 +180,7 @@ agents:
       style: Formal methodology underlying graceful design
   pm:
     character: Kaylee Frye
-    visual: "A cheerful young woman with bright smile, wearing grease-stained coveralls with colorful patches, flowery parasol or strawberry motif visible, holding engine parts lovingly"
+    visual: "Roman numeral XVII at top, text THE STAR in all caps serif at bottom, a cheerful young woman with brown hair kneeling by a blue pool pouring water from two jugs one onto green land one into the pool, wearing simple clothes with strawberry patches, one large yellow eight-pointed star and seven small white stars in blue sky above, ibis bird in a tree behind, rolling green hills"
     # JOB FAIR OPTIMIZED: Moved from Dev - her intuitive understanding fits PM
     ocean:
       O: 4 # High openness - intuitive, creative problem solver
@@ -207,7 +207,7 @@ agents:
       style: The product environment itself
   tech-writer:
     character: Simon Tam
-    visual: "A handsome young man with neat dark hair, wearing vest and tie with proper Core planet styling, carrying medical bag, earnest concerned expression"
+    visual: "Roman numeral IX at top, text THE HERMIT in all caps serif at bottom, a handsome young man with neat dark hair standing alone on a snowy mountaintop holding a golden lantern containing a bright six-pointed star, wearing gray hooded cloak over vest and tie, carrying a tall wooden staff in left hand, looking down from the peak, dark blue sky behind"
     ocean:
       O: 4 # High openness - Core-educated, medical research background
       C: 5 # Very high conscientiousness - Precise doctor, meticulous
@@ -233,7 +233,7 @@ agents:
       style: Core-trained precision documentation
   ux-designer:
     character: Hoban 'Wash' Washburne
-    visual: "A cheerful man with reddish hair and Hawaiian shirt under flight suit, sitting at ship's helm with toy dinosaurs on console, infectious goofy grin"
+    visual: "Roman numeral 0 at top, text THE FOOL in all caps serif at bottom, a cheerful man with reddish hair and colorful Hawaiian shirt stepping joyfully off a cliff edge into the air, small white dog barking at his heels, carrying a bindle stick over shoulder with toy dinosaurs spilling out, white rose in left hand, bright golden sun shining behind, jagged mountains in distance"
     ocean:
       O: 4 # High openness - Creative pilot, playful, dinosaur enthusiast
       C: 3 # Medium conscientiousness - Skilled pilot but playful approach
@@ -262,7 +262,7 @@ agents:
     gap_filled: Makes terror feel fun (chaotic good UX)
   devops:
     character: Serenity (The Ship)
-    visual: "A battered but beloved Firefly-class transport ship with distinctive insect-like shape, glowing engine pods, visible repairs and character, flying through stars"
+    visual: "Roman numeral XXI at top, text THE WORLD in all caps serif at bottom, a battered but beloved Firefly-class transport ship floating within a large green laurel wreath tied with red ribbons, a winged angel top left, an eagle top right, a winged bull bottom left, a winged lion bottom right, glowing engine pods, starfield and clouds behind"
     ocean:
       O: 2 # Low openness - Fixed infrastructure, reliable transport
       C: 4 # High conscientiousness - Dependable, keeps flying
@@ -289,7 +289,7 @@ agents:
 
   ba:
     character: Shepherd Book
-    visual: "An older African American man with gray hair styled upward, kind weathered face, wearing brown shepherd's robes with religious collar, carrying worn Bible, knowing eyes with hidden depths"
+    visual: "Roman numeral XI at top, text JUSTICE in all caps serif at bottom, an older African American man with gray hair styled upward seated between two gray pillars, holding a double-edged sword upright in right hand and golden balanced scales in left hand, wearing brown robes with religious collar, kind weathered face with knowing eyes, purple veil draped between the pillars behind"
     ocean:
       O: 4  # High openness - philosophical, sees multiple perspectives
       C: 4  # High conscientiousness - disciplined analysis

package/pennyfarthing-dist/personas/themes/lord-of-the-rings.yaml

@@ -17,7 +17,9 @@ theme:
   default_humor: enabled
   character_immersion: high
   user_title: Friend
-  portrait_style: ", animated epic fantasy, elvish script border"
+  portrait_prefix: "Watercolor painting on rough paper:"
+  portrait_style: ", soft washes, visible paper texture, warm muted palette"
+  negative_prompt: "photorealistic, glossy, 3d render, digital art, smooth skin, airbrushed, photograph, sharp focus"
   tier: B
   dimensions:
     tone: serious
@@ -32,7 +34,7 @@ zeitgeist:
 agents:
   orchestrator:
     character: Aragorn
-    visual: "Weather-worn ranger with dark wavy hair, grey noble eyes, stubbled jaw. Travel-stained green cloak, broken sword Narsil at hip. Reluctant king bearing, standing vigil on windswept hill at dawn"
+    visual: "A weather-worn ranger with dark wavy hair, grey noble eyes, stubbled jaw, travel-stained green cloak, sword at hip, standing vigil on a windswept hill at dawn"
     shortName: Aragorn
     ocean:
       O: 4  # High openness - ranger wisdom, sees hope in darkness
@@ -60,7 +62,7 @@ agents:
   sm:
     # JOB FAIR OPTIMIZED: Elrond moved here - ancient wisdom coordinates the fellowship
     character: Elrond
-    visual: "Ageless Elf-lord with long dark hair, silver circlet. Piercing grey eyes that witnessed three ages. Rich burgundy robes, stern noble features softened by ancient wisdom. Standing in Rivendell's golden light"
+    visual: "An ageless elf lord with long dark hair, silver circlet, piercing grey eyes, rich burgundy robes, stern noble features softened by ancient wisdom, golden autumn light"
     shortName: Elrond
     ocean:
       O: 5  # Very high openness - thousands of years of wisdom
@@ -88,7 +90,7 @@ agents:
   tea:
     # JOB FAIR OPTIMIZED: Legolas moved here - elvish eyes test with precision
     character: Legolas
-    visual: "Tall Elf prince with long golden hair, keen bright eyes that see farther than mortals. Forest-green and brown leathers, elegant bow across back, white-handled knives at belt. Moving with impossible grace"
+    visual: "A tall elf prince with long golden hair, keen bright eyes, forest-green and brown leathers, elegant bow across back, knives at belt, moving with impossible grace"
     shortName: Legolas
     ocean:
       O: 4  # High openness - elvish perception, sees far
@@ -116,7 +118,7 @@ agents:
   dev:
     # JOB FAIR OPTIMIZED: Gandalf confirmed as optimal dev
     character: Gandalf
-    visual: "Ancient wizard in grey robes and tall pointed hat. Long grey beard, bushy eyebrows over twinkling blue eyes. Gnarled wooden staff in hand, pipe smoke curling. Face shifts from merry to terrible, radiating hidden power"
+    visual: "An ancient wizard in grey robes and tall pointed hat, long grey beard, bushy eyebrows, twinkling blue eyes, gnarled wooden staff, pipe smoke curling, radiating hidden power"
     shortName: Gandalf
     ocean:
       O: 5  # Very high openness - wizard, vast knowledge, sees ages
@@ -144,7 +146,7 @@ agents:
   reviewer:
     # JOB FAIR OPTIMIZED: Saruman moved here - demanding review for total vision
     character: Saruman
-    visual: "Tall wizard in gleaming white robes shimmering with hidden colors. Long white hair and beard, dark penetrating eyes. Voice of honey and steel. Holding black staff topped with crystal in Orthanc tower"
+    visual: "A tall wizard in gleaming white robes, long white hair and beard, dark penetrating eyes, holding a black staff topped with crystal, standing in a dark stone tower"
     shortName: Saruman
     ocean:
       O: 5  # Very high openness - vast knowledge, sees far
@@ -172,7 +174,7 @@ agents:
   architect:
     # JOB FAIR OPTIMIZED: Gollum moved here - cunning, sees hidden patterns
     character: Gollum/Smeagol
-    visual: "Wretched creature with pallid stretched skin over skeletal frame. Huge luminous eyes that see in darkness, wisps of hair on bulbous head. Long grasping fingers. Crouching on rock in mountain caverns, clutching at shadows"
+    visual: "A wretched creature with pallid stretched skin over skeletal frame, huge luminous eyes, wisps of hair on bulbous head, long grasping fingers, crouching on rock in dark caverns"
     shortName: Gollum
     ocean:
       O: 3  # Medium openness - cunning, sees hidden paths
@@ -200,7 +202,7 @@ agents:
   pm:
     # JOB FAIR OPTIMIZED: Sam moved here - carries the product home
     character: Samwise Gamgee
-    visual: "Sturdy young hobbit with curly brown hair, honest brown eyes. Round face flushed with determination. Practical travelling clothes, carrying pots and pans, rope over shoulder. Radiating unwavering loyalty and humble courage"
+    visual: "A sturdy young hobbit with curly brown hair, honest brown eyes, round face, practical travelling clothes, carrying pots and rope over shoulder, radiating humble courage"
     shortName: Sam
     ocean:
       O: 2  # Low openness - practical, focused on what matters
@@ -227,7 +229,7 @@ agents:
 
   tech-writer:
     character: Bilbo Baggins
-    visual: "Elderly hobbit with white hair, comfortable round belly. Bright curious eyes still hungry for adventure. Fine brocade waistcoat. Sitting at writing desk in Bag End with maps and Red Book open, quill in hand"
+    visual: "An elderly hobbit with white hair, comfortable round belly, bright curious eyes, fine brocade waistcoat, sitting at a cozy writing desk with maps and an open book, quill in hand"
     shortName: Bilbo
     ocean:
       O: 4  # High openness - adventure changed him, writes memoirs
@@ -254,7 +256,7 @@ agents:
 
   ux-designer:
     character: Pippin
-    visual: "Young hobbit with tousled brown curls, wide innocent curious eyes. Wearing black and silver livery of Gondor's Tower Guard, slightly too small for armor. Expression of wonder and mischief. Holding stolen Palantir"
+    visual: "A young hobbit with tousled brown curls, wide innocent curious eyes, wearing black and silver guard livery slightly too large, expression of wonder and mischief"
     shortName: Pippin
     ocean:
       O: 4  # High openness - curious, asks questions
@@ -281,7 +283,7 @@ agents:
 
   devops:
     character: Gimli
-    visual: "Stocky dwarf warrior with magnificent forked red beard, fierce dark eyes. Wearing gleaming chainmail and horned helm. Gripping double-headed battle axe. Broad shoulders squared for combat, standing ready to defend the fellowship"
+    visual: "A stocky dwarf warrior with magnificent forked red beard, fierce dark eyes, gleaming chainmail and horned helm, gripping a double-headed battle axe, broad shoulders squared for combat"
     shortName: Gimli
     ocean:
       O: 2  # Low openness - traditional, dwarvish ways
@@ -307,7 +309,7 @@ agents:
       style: Built to last forever
   ba:
     character: Elrond
-    visual: "Ageless Elf-lord with long dark hair, silver circlet. Piercing grey eyes that witnessed three ages. Rich burgundy robes, stern noble features softened by ancient wisdom. Standing in Rivendell's golden light"
+    visual: "An ageless elf lord with long dark hair, silver circlet, piercing grey eyes, rich burgundy robes, stern noble features softened by ancient wisdom, golden autumn light"
     ocean:
       O: 4  # Ancient wisdom
       C: 4  # Methodical precision

package/pennyfarthing-dist/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "pennyfarthing-scripts"
-version = "8.1.0"
+dynamic = ["version"]
 requires-python = ">=3.11"
 dependencies = ["pyyaml>=6.0", "ruamel.yaml>=0.18", "httpx>=0.28", "click>=8.0", "pydriller>=2.6"]
 
 [project.optional-dependencies]
-tui = ["textual>=1.0", "websockets>=12.0", "textual-image>=0.7.0"]
+tui = ["textual>=1.0", "websockets>=12.0", "textual-image>=0.7.0", "watchfiles>=1.0"]
 
 [project.scripts]
 pf = "pf.cli:main"
@@ -15,4 +15,8 @@ requires = ["setuptools>=68.0"]
 build-backend = "setuptools.build_meta"
 
 [tool.setuptools.packages.find]
+where = ["src"]
 include = ["pf*"]
+
+[tool.setuptools.dynamic]
+version = {attr = "pf.__version__"}

package/pennyfarthing-dist/scripts/core/agent-session.sh

@@ -8,12 +8,12 @@
 #
 # Session files stored in .session/agents/<session-id> for multi-session support
 
-# Find package root (where pf/ lives) from script location
+# Find package root from script location
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd -P)"
 PACKAGE_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd -P)"
 
-# Set PYTHONPATH so Python can find pf package
-export PYTHONPATH="${PACKAGE_ROOT}:${PYTHONPATH:-}"
+# Set PYTHONPATH so Python can find pf package (src/ layout)
+export PYTHONPATH="${PACKAGE_ROOT}/src:${PYTHONPATH:-}"
 
 # Agents directory for multi-session support
 AGENTS_DIR="$PROJECT_ROOT/.session/agents"
@@ -232,8 +232,7 @@ case "$1" in
       PRIME_ARGS+=(--no-persona)
     fi
 
-    source "$SCRIPT_DIR/../lib/run-pf.sh"
-    run_pf prime "${PRIME_ARGS[@]}"
+    pf prime "${PRIME_ARGS[@]}"
     ;;
   stop)
     # Use provided session ID, fall back to SESSION_ID env var

package/pennyfarthing-dist/scripts/core/check-context.sh

@@ -29,14 +29,19 @@ if [[ "$REAL_DIR" == *"/pennyfarthing-dist/scripts/core" ]]; then
 elif [[ "$REAL_DIR" == *"/node_modules/"* ]]; then
     # In node_modules, walk up to find project root
     PACKAGE_ROOT="${REAL_DIR}"
-    while [[ "$PACKAGE_ROOT" != "/" ]] && [[ ! -d "$PACKAGE_ROOT/pf" ]]; do
+    while [[ "$PACKAGE_ROOT" != "/" ]] && [[ ! -d "$PACKAGE_ROOT/src/pf" ]]; do
         PACKAGE_ROOT="$(dirname "$PACKAGE_ROOT")"
     done
 fi
 
-# Try to find pf
+# Try to find pf (src/ layout)
 PYTHON_MODULE=""
-if [[ -f "$PACKAGE_ROOT/pf/context.py" ]]; then
+if [[ -f "$PACKAGE_ROOT/src/pf/context.py" ]]; then
+    PYTHON_MODULE="$PACKAGE_ROOT/src/pf/context.py"
+elif [[ -f "${PROJECT_ROOT:-}/src/pf/context.py" ]]; then
+    PYTHON_MODULE="${PROJECT_ROOT}/src/pf/context.py"
+# Legacy fallback
+elif [[ -f "$PACKAGE_ROOT/pf/context.py" ]]; then
     PYTHON_MODULE="$PACKAGE_ROOT/pf/context.py"
 elif [[ -f "${PROJECT_ROOT:-}/pf/context.py" ]]; then
     PYTHON_MODULE="${PROJECT_ROOT}/pf/context.py"
@@ -71,7 +76,7 @@ done
 
 # Derive Claude project path from current directory
 PROJECT_DIR="${PROJECT_ROOT:-$(pwd)}"
-CLAUDE_PROJECT_PATH="$HOME/.claude/projects/$(echo "$PROJECT_DIR" | tr '/' '-')"
+CLAUDE_PROJECT_PATH="$HOME/.claude/projects/$(echo "$PROJECT_DIR" | tr '/.' '-')"
 
 # Default config
 WARNING_THRESHOLD=60
@@ -156,7 +161,7 @@ if last_total:
     status = 'HIGH' if usable_pct > $WARNING_THRESHOLD else 'OK'
     relay = '$RELAY_MODE' == 'true'
     tirepump = (relay or '$PERMISSION_MODE' == 'turbo') and usable_pct > $TIREPUMP_THRESHOLD
-    is_cyclist = os.environ.get('CYCLIST') == '1' or Path('$PROJECT_DIR/packages/cyclist/.bikerack-port').exists()
+    is_cyclist = os.environ.get('CYCLIST') == '1' or Path('$PROJECT_DIR/.bikerack-port').exists() or Path('$PROJECT_DIR/packages/cyclist/.bikerack-port').exists()
 
     print(f'CONTEXT_TOKENS={last_total}')
     print(f'CONTEXT_PERCENT={total_pct}')

package/pennyfarthing-dist/scripts/core/phase-check-start.sh

@@ -1,5 +1,4 @@
 #!/bin/bash
 # DEPRECATED: Use `pf handoff phase-check <agent>` instead.
 echo "DEPRECATED: phase-check-start.sh — use 'pf handoff phase-check $1' instead" >&2
-source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
-exec_pf handoff phase-check "$@"
+exec pf handoff phase-check "$@"

package/pennyfarthing-dist/scripts/core/prime.sh

@@ -1,5 +1,4 @@
 #!/usr/bin/env bash
 # prime.sh - Load essential project context at agent activation
 # Usage: prime.sh [--minimal] [--full] [--quiet] [--agent <name>]
-source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
-exec_pf prime "$@"
+exec pf prime "$@"

package/pennyfarthing-dist/scripts/git/changelog-links.sh

@@ -0,0 +1,216 @@
+#!/usr/bin/env bash
+#
+# changelog-links.sh - Validate and regenerate CHANGELOG.md comparison links
+#
+# Parses ## [X.Y.Z] headers from CHANGELOG.md and ensures the comparison
+# links section at the bottom is complete, ordered, and correct.
+#
+# Usage:
+#   changelog-links.sh [OPTIONS]
+#
+# Options:
+#   --validate    Check links are correct (exit 1 if not). Default mode.
+#   --fix         Regenerate the links section in-place.
+#   --print       Print what the links section should be (stdout).
+#   --changelog   Path to CHANGELOG.md (default: auto-detect)
+#   --repo-url    GitHub repo URL (default: parsed from links section)
+#
+# Exit codes:
+#   0 - Links are valid (--validate) or fixed (--fix)
+#   1 - Links are invalid (--validate) or error occurred
+
+set -euo pipefail
+
+# --- Defaults ---
+MODE="validate"
+CHANGELOG_PATH=""
+REPO_URL=""
+
+# --- Parse arguments ---
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --validate)  MODE="validate"; shift ;;
+        --fix)       MODE="fix"; shift ;;
+        --print)     MODE="print"; shift ;;
+        --changelog) CHANGELOG_PATH="$2"; shift 2 ;;
+        --repo-url)  REPO_URL="$2"; shift 2 ;;
+        --help|-h)
+            head -17 "$0" | tail -15
+            exit 0
+            ;;
+        *)
+            echo "ERROR: Unknown option: $1" >&2
+            exit 1
+            ;;
+    esac
+done
+
+# --- Find CHANGELOG.md ---
+if [[ -z "$CHANGELOG_PATH" ]]; then
+    # Walk up from PWD looking for CHANGELOG.md
+    _dir="$PWD"
+    while [[ ! -f "$_dir/CHANGELOG.md" ]] && [[ "$_dir" != "/" ]]; do
+        _dir="$(dirname "$_dir")"
+    done
+    if [[ -f "$_dir/CHANGELOG.md" ]]; then
+        CHANGELOG_PATH="$_dir/CHANGELOG.md"
+    else
+        echo "ERROR: CHANGELOG.md not found" >&2
+        exit 1
+    fi
+fi
+
+if [[ ! -f "$CHANGELOG_PATH" ]]; then
+    echo "ERROR: File not found: $CHANGELOG_PATH" >&2
+    exit 1
+fi
+
+# --- Extract repo URL from existing links ---
+if [[ -z "$REPO_URL" ]]; then
+    REPO_URL=$(grep -oE 'https://github\.com/[^/]+/[^/]+' "$CHANGELOG_PATH" | head -1)
+    if [[ -z "$REPO_URL" ]]; then
+        echo "ERROR: Could not detect repo URL from CHANGELOG.md. Use --repo-url." >&2
+        exit 1
+    fi
+fi
+
+# --- Extract version headers in document order (top = newest) ---
+# Matches: ## [X.Y.Z] or ## [Unreleased]
+# Captures just the version string
+VERSIONS=()
+while IFS= read -r line; do
+    # Extract version from ## [version] headers
+    if [[ "$line" =~ ^##[[:space:]]+\[([^]]+)\] ]]; then
+        VERSIONS+=("${BASH_REMATCH[1]}")
+    fi
+done < "$CHANGELOG_PATH"
+
+if [[ ${#VERSIONS[@]} -lt 2 ]]; then
+    echo "ERROR: Found fewer than 2 version headers in CHANGELOG.md" >&2
+    exit 1
+fi
+
+# --- Generate correct links ---
+# Links are in same order as headers (newest first).
+# Each version compares against the next (older) version.
+# The oldest version links to its release tag.
+# [Unreleased] compares against the newest release.
+generate_links() {
+    local i
+    for ((i = 0; i < ${#VERSIONS[@]}; i++)); do
+        local ver="${VERSIONS[$i]}"
+        if [[ "$ver" == "Unreleased" ]]; then
+            # Unreleased compares against the next version (newest release)
+            if [[ $((i + 1)) -lt ${#VERSIONS[@]} ]]; then
+                local next="${VERSIONS[$((i + 1))]}"
+                echo "[Unreleased]: ${REPO_URL}/compare/v${next}...HEAD"
+            fi
+        elif [[ $((i + 1)) -lt ${#VERSIONS[@]} ]]; then
+            local next="${VERSIONS[$((i + 1))]}"
+            if [[ "$next" == "Unreleased" ]]; then
+                # This shouldn't happen in a well-formed changelog
+                continue
+            fi
+            echo "[${ver}]: ${REPO_URL}/compare/v${next}...v${ver}"
+        else
+            # Oldest version - link to release tag
+            echo "[${ver}]: ${REPO_URL}/releases/tag/v${ver}"
+        fi
+    done
+}
+
+EXPECTED_LINKS=$(generate_links)
+
+# --- Extract current links section ---
+# Links section starts after the last version content, identified by
+# lines matching the [version]: URL pattern at the end of the file.
+# We find the first link line and take everything from there to EOF.
+FIRST_LINK_LINE=$(grep -n '^\[' "$CHANGELOG_PATH" | grep -E '^\d+:\[.+\]: https://' | head -1 | cut -d: -f1)
+
+if [[ -z "$FIRST_LINK_LINE" ]]; then
+    CURRENT_LINKS=""
+else
+    CURRENT_LINKS=$(tail -n +"$FIRST_LINK_LINE" "$CHANGELOG_PATH" | sed '/^$/d')
+fi
+
+# --- Act based on mode ---
+case "$MODE" in
+    print)
+        echo "$EXPECTED_LINKS"
+        ;;
+    validate)
+        if [[ "$CURRENT_LINKS" == "$EXPECTED_LINKS" ]]; then
+            echo "PASS: CHANGELOG.md comparison links are correct (${#VERSIONS[@]} versions)"
+            exit 0
+        else
+            echo "FAIL: CHANGELOG.md comparison links are incorrect"
+            echo ""
+            echo "--- Expected (${#VERSIONS[@]} links) ---"
+            echo "$EXPECTED_LINKS" | head -5
+            echo "..."
+            echo ""
+            echo "--- Actual ---"
+            echo "$CURRENT_LINKS" | head -5
+            echo "..."
+            echo ""
+
+            # Count specific issues
+            EXPECTED_COUNT=$(echo "$EXPECTED_LINKS" | wc -l | tr -d ' ')
+            ACTUAL_COUNT=$(echo "$CURRENT_LINKS" | wc -l | tr -d ' ')
+            if [[ "$EXPECTED_COUNT" != "$ACTUAL_COUNT" ]]; then
+                echo "Link count mismatch: expected $EXPECTED_COUNT, got $ACTUAL_COUNT"
+            fi
+
+            # Check for missing versions
+            for ver in "${VERSIONS[@]}"; do
+                if [[ "$ver" == "Unreleased" ]]; then
+                    if ! echo "$CURRENT_LINKS" | grep -q '^\[Unreleased\]:'; then
+                        echo "  Missing: [Unreleased] link"
+                    fi
+                else
+                    if ! echo "$CURRENT_LINKS" | grep -q "^\[${ver}\]:"; then
+                        echo "  Missing: [${ver}] link"
+                    fi
+                fi
+            done
+
+            echo ""
+            echo "Run with --fix to regenerate links."
+            exit 1
+        fi
+        ;;
+    fix)
+        # Remove existing links section and append correct one
+        if [[ -n "$FIRST_LINK_LINE" ]]; then
+            # Keep everything before the links section
+            BEFORE_LINKS_LINE=$((FIRST_LINK_LINE - 1))
+            head -n "$BEFORE_LINKS_LINE" "$CHANGELOG_PATH" > "${CHANGELOG_PATH}.tmp"
+        else
+            # No links section exists - use entire file
+            cp "$CHANGELOG_PATH" "${CHANGELOG_PATH}.tmp"
+        fi
+
+        # Strip trailing blank lines from content
+        while [[ -s "${CHANGELOG_PATH}.tmp" ]] && [[ "$(tail -c 1 "${CHANGELOG_PATH}.tmp" | xxd -p)" == "0a" ]]; do
+            # Check if last line is empty
+            LAST_LINE=$(tail -1 "${CHANGELOG_PATH}.tmp")
+            if [[ -z "$LAST_LINE" ]]; then
+                # Remove last empty line using head
+                LINE_COUNT=$(wc -l < "${CHANGELOG_PATH}.tmp" | tr -d ' ')
+                head -n $((LINE_COUNT - 1)) "${CHANGELOG_PATH}.tmp" > "${CHANGELOG_PATH}.tmp2"
+                mv "${CHANGELOG_PATH}.tmp2" "${CHANGELOG_PATH}.tmp"
+            else
+                break
+            fi
+        done
+
+        # Append links section with blank line separator
+        {
+            echo ""
+            echo "$EXPECTED_LINKS"
+        } >> "${CHANGELOG_PATH}.tmp"
+
+        mv "${CHANGELOG_PATH}.tmp" "$CHANGELOG_PATH"
+        echo "Fixed: Regenerated ${#VERSIONS[@]} comparison links in CHANGELOG.md"
+        ;;
+esac

package/pennyfarthing-dist/scripts/git/create-feature-branches.sh

@@ -1,5 +1,4 @@
 #!/usr/bin/env bash
 # DEPRECATED: Use `pf git branches` instead.
 echo "DEPRECATED: create-feature-branches.sh — use 'pf git branches' instead" >&2
-source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
-exec_pf git branches "$@"
+exec pf git branches "$@"

package/pennyfarthing-dist/scripts/git/git-status-all.sh

@@ -1,5 +1,4 @@
 #!/usr/bin/env bash
 # DEPRECATED: Use `pf git status` instead.
 echo "DEPRECATED: git-status-all.sh — use 'pf git status' instead" >&2
-source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
-exec_pf git status "$@"
+exec pf git status "$@"

package/pennyfarthing-dist/scripts/git/install-git-hooks.sh

@@ -1,5 +1,4 @@
 #!/usr/bin/env bash
 # DEPRECATED: Use `pf git install-hooks` instead.
 echo "DEPRECATED: install-git-hooks.sh — use 'pf git install-hooks' instead" >&2
-source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
-exec_pf git install-hooks "$@"
+exec pf git install-hooks "$@"

package/pennyfarthing-dist/scripts/git/worktree-manager.sh

@@ -1,4 +1,3 @@
 #!/usr/bin/env bash
 # DEPRECATED: Use `pf git worktree` instead.
-source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
-exec_pf git worktree "$@"
+exec pf git worktree "$@"

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

@@ -1,4 +1,3 @@
 #!/usr/bin/env bash
-# Shim: delegates to Python CLI via uv run (dogfooding) or global pf (consumer).
-source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
-exec_pf hooks bell-mode
+# Shim: delegates to globally installed pf CLI.
+exec pf hooks bell-mode

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

@@ -1,4 +1,3 @@
 #!/usr/bin/env bash
-# Shim: delegates to Python CLI via uv run (dogfooding) or global pf (consumer).
-source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
-exec_pf hooks context-breaker
+# Shim: delegates to globally installed pf CLI.
+exec pf hooks context-breaker

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

@@ -1,4 +1,3 @@
 #!/usr/bin/env bash
-# Shim: delegates to Python CLI via uv run (dogfooding) or global pf (consumer).
-source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
-exec_pf hooks context-warning
+# Shim: delegates to globally installed pf CLI.
+exec pf hooks context-warning

package/pennyfarthing-dist/scripts/hooks/cyclist-pretooluse-hook.sh

@@ -1,4 +1,3 @@
 #!/usr/bin/env bash
-# Shim: delegates to Python CLI via uv run (dogfooding) or global pf (consumer).
-source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
-exec_pf hooks cyclist-pretooluse
+# Shim: delegates to globally installed pf CLI.
+exec pf hooks cyclist-pretooluse