@pennyfarthing/core 11.2.1 → 11.2.2

package/pennyfarthing-dist/guides/prime.md

@@ -53,7 +53,7 @@ Prime selects a context tier based on session state to manage token overhead:
 
 ```bash
 # From agent commands (via pf CLI)
-pf agent start "<agent>" --quiet
+pf.sh agent start "<agent>" --quiet
 
 # TypeScript API (from Cyclist)
 getPrimeContext(agentName, projectDir)
@@ -63,7 +63,7 @@ getPrimeContextJson(agentName, projectDir, tier)  # JSON for Cyclist
 
 ## Integration Points
 
-- **Agent commands** (`/sm`, `/dev`, `/tea`) invoke prime on activation
+- **Agent commands** (`/pf-sm`, `/pf-dev`, `/pf-tea`) invoke prime on activation
 - **TirePump** calls prime to reload agent context after clearing
 - **Cyclist** uses JSON output for context display and token tracking
 

package/pennyfarthing-dist/guides/reflector.md

@@ -41,7 +41,7 @@ Marker pattern: /<!--\s*CYCLIST:(\w+)(?::([^>]+?))?\s*-->/gi
 | `packages/cyclist/src/public/components/QuickActions.tsx` | Renders action buttons from detected markers |
 | `packages/cyclist/src/public/hooks/useMarkerActions.ts` | Detects markers, builds action metadata |
 | `pennyfarthing-dist/scripts/hooks/question_reflector_check.py` | Stop hook — enforces marker presence |
-| `pf hooks reflector-check` | CLI entry point for stop hook |
+| `pf.sh hooks reflector-check` | CLI entry point for stop hook |
 
 ## Enforcement Hook
 

package/pennyfarthing-dist/guides/skill-schema.md

@@ -146,7 +146,7 @@ args: "[arg1|arg2]"       # Optional: argument summary
 **Example:**
 ```xml
 <run>
-pf sprint status [filter]
+pf.sh sprint status [filter]
 </run>
 ```
 
@@ -195,7 +195,7 @@ pf sprint status [filter]
 **Example:**
 ```xml
 <example>
-pf sprint check MSSCI-12038
+pf.sh sprint check MSSCI-12038
 # Returns: {"type": "story", "available": true, "title": "...", ...}
 </example>
 ```
@@ -292,7 +292,7 @@ Never manually edit sprint YAML. Use the provided commands.
 Add a new story to an epic.
 
 <run>
-pf sprint story add <epic-id> "<title>" <points>
+pf.sh sprint story add <epic-id> "<title>" <points>
 </run>
 
 <args>
@@ -304,7 +304,7 @@ pf sprint story add <epic-id> "<title>" <points>
 </args>
 
 <example>
-pf sprint story add epic-76 "Add user authentication" 3
+pf.sh sprint story add epic-76 "Add user authentication" 3
 </example>
 
 <output>
@@ -322,7 +322,7 @@ After creating, use `/pf-sprint story size` for sizing guidelines.
 Complete a story after PR merge.
 
 <run>
-pf sprint story finish <story-id>
+pf.sh sprint story finish <story-id>
 </run>
 
 <args>
@@ -332,7 +332,7 @@ pf sprint story finish <story-id>
 </args>
 
 <example>
-pf sprint story finish MSSCI-12052
+pf.sh sprint story finish MSSCI-12052
 # Archives story, updates Jira, cleans session files
 </example>
 

package/pennyfarthing-dist/guides/tandem-protocol.md

@@ -13,7 +13,7 @@ Primary Agent (Opus)          Backseat Agent (Haiku, background)
      │                              │   .session/{story}-tandem-{partner}.md
      │                              │
      ├── PostToolUse hook fires ────┤
-     │   pf hooks bell-mode detects │
+     │   pf.sh hooks bell-mode detects │
      │   new observation, injects   │
      │   "[Tandem] Character: ..."  │
      │                              │
@@ -163,8 +163,8 @@ For active, synchronous agent-to-agent questions (as opposed to passive observat
 | `observation-writer.ts` | Built | TypeScript API for observation file I/O |
 | `file-watch.ts` | Built | File system change detection |
 | `tool-watch.ts` | Built | Tool call log monitoring |
-| `pf hooks bell-mode` | Built | PostToolUse hook with tandem injection |
+| `pf.sh hooks bell-mode` | Built | PostToolUse hook with tandem injection |
 | `bellmode_hook.py` | Built | Python implementation of bell mode hook |
-| `pf hooks statusline` | Built | CLI statusline with tandem indicator |
+| `pf.sh hooks statusline` | Built | CLI statusline with tandem indicator |
 | `tandem-backseat.md` | Built | Backseat agent prompt template |
 | `agent-behavior.md` | Built | Shared agent behavior with tandem protocol |

package/pennyfarthing-dist/guides/workflow-schema.md

@@ -253,5 +253,5 @@ Error: workflow.triggers.points min (10) cannot be greater than max (5)
 
 - Story 31-2: Workflow loader and validator
 - Story 31-3: Story-to-workflow routing engine
-- Story 31-5: /workflow skill for listing and switching
+- Story 31-5: /pf-workflow skill for listing and switching
 - Story MSSCI-11710: Permission presets by workflow

package/pennyfarthing-dist/guides/worktree-mode.md

@@ -86,8 +86,8 @@ Ports are stored in the session file and passed to agents.
 | Command | Purpose |
 |---------|---------|
 | `/pf-session parallel` | Start a new parallel work session |
-| `pf git worktree list` | Show active worktrees |
-| `pf git worktree remove <name>` | Clean up a worktree |
+| `pf.sh git worktree list` | Show active worktrees |
+| `pf.sh git worktree remove <name>` | Clean up a worktree |
 
 ## TDD Flow in Worktrees
 
@@ -104,7 +104,7 @@ Agents use worktree paths from session file for all operations.
 When story is complete, SM archives the session and the worktree can be removed:
 
 ```bash
-pf git worktree remove wt-5-3a
+pf.sh git worktree remove wt-5-3a
 ```
 
 This removes:

package/pennyfarthing-dist/guides/xml-tags.md

@@ -124,7 +124,7 @@ Tags used by agents participating in the TDD workflow cycle (SM, TEA, Dev, Revie
 
 **Purpose:** Verify agent owns the current workflow phase before proceeding. Prevents agents from acting on stories they shouldn't own.
 
-**Usage:** SM, TEA, Dev, Reviewer - runs `pf workflow phase-check` on activation to determine correct owner.
+**Usage:** SM, TEA, Dev, Reviewer - runs `pf.sh workflow phase-check` on activation to determine correct owner.
 
 ```markdown
 <phase-check>
@@ -132,10 +132,10 @@ Tags used by agents participating in the TDD workflow cycle (SM, TEA, Dev, Revie
 
 Read `**Workflow:**` and `**Phase:**` from session. Query:
 ```bash
-OWNER=$(pf workflow phase-check {workflow} {phase})
+OWNER=$("$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh workflow phase-check {workflow} {phase})
 ```
 
-**If OWNER != "dev":** Run `pf handoff marker $OWNER`, output result, tell user.
+**If OWNER != "dev":** Run `pf.sh handoff marker $OWNER`, output result, tell user.
 </phase-check>
 ```
 
@@ -150,9 +150,9 @@ OWNER=$(pf workflow phase-check {workflow} {phase})
 ## MANDATORY: Complete Before Exiting
 
 - [ ] Write Assessment to session file
-- [ ] Run `pf handoff resolve-gate` — verify gate status
-- [ ] Run `pf handoff complete-phase` — atomic session update
-- [ ] Run `pf handoff marker {next_agent}` — emit marker and EXIT
+- [ ] Run `pf.sh handoff resolve-gate` — verify gate status
+- [ ] Run `pf.sh handoff complete-phase` — atomic session update
+- [ ] Run `pf.sh handoff marker {next_agent}` — emit marker and EXIT
 </handoff-gate>
 ```
 
@@ -448,7 +448,7 @@ Tags used in skill files (`skills/{name}/SKILL.md`) for command documentation.
 
 ```markdown
 <run>
-pf sprint status [filter]
+pf.sh sprint status [filter]
 </run>
 ```
 
@@ -474,7 +474,7 @@ pf sprint status [filter]
 
 ```markdown
 <example>
-pf sprint check MSSCI-12038
+pf.sh sprint check MSSCI-12038
 # Returns: {"type": "story", "available": true}
 </example>
 ```

package/pennyfarthing-dist/scripts/README.md

@@ -8,10 +8,10 @@ Scripts are organized into categorical subdirectories. **Full paths are required
 scripts/
 ├── core/       # Essential scripts (agent-session.sh)
 ├── workflow/   # Workflow mechanics (finish-story.sh, check.sh)
-├── sprint/     # Sprint YAML operations (migrated to pf sprint CLI)
+├── sprint/     # Sprint YAML operations (migrated to pf.sh sprint CLI)
 ├── story/      # Story operations (create-story.sh)
 ├── jira/       # Jira integration (jira-claim-story.sh)
-├── git/        # Git operations (deprecated shims → pf git CLI)
+├── git/        # Git operations (deprecated shims → pf.sh git CLI)
 ├── theme/      # Theme operations (list-themes.sh)
 ├── test/       # Test infrastructure (test-setup.sh)
 ├── lib/        # Shared bash libraries (common.sh, logging.sh)
@@ -27,9 +27,9 @@ Scripts are invoked directly with **full category paths**:
 ```bash
 # From project root
 .pennyfarthing/scripts/core/agent-session.sh start sm
-pf sprint status
+pf.sh sprint status
 .pennyfarthing/scripts/jira/jira-claim-story.sh MSSCI-12345
-pf sprint story finish MSSCI-12345
+pf.sh sprint story finish MSSCI-12345
 ```
 
 ## Distributed Scripts

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

@@ -232,11 +232,8 @@ case "$1" in
       PRIME_ARGS+=(--no-persona)
     fi
 
-    if command -v pf &>/dev/null; then
-      pf prime "${PRIME_ARGS[@]}"
-    else
-      python3 -m pennyfarthing_scripts.prime "${PRIME_ARGS[@]}"
-    fi
+    source "$SCRIPT_DIR/../lib/run-pf.sh"
+    run_pf prime "${PRIME_ARGS[@]}"
     ;;
   stop)
     # Use provided session ID, fall back to SESSION_ID env var

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

@@ -156,7 +156,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/.wheelhub-port').exists()
+    is_cyclist = os.environ.get('CYCLIST') == '1' 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/pf.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Wrapper: run `pf` CLI via uv run — no global pf install needed.
+# Usage: "$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh <command> [args...]
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
+exec_pf "$@"

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

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

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

@@ -1,28 +1,5 @@
 #!/usr/bin/env bash
 # prime.sh - Load essential project context at agent activation
 # Usage: prime.sh [--minimal] [--full] [--quiet] [--agent <name>]
-#
-# Uses the `pf` CLI (installed via uv/pipx during pennyfarthing init).
-# Falls back to python3 -m with PYTHONPATH if pf is not available.
-
-# Prefer pf CLI if available
-if command -v pf &>/dev/null; then
-    exec pf prime "$@"
-fi
-
-# Fallback: find pennyfarthing_scripts via PYTHONPATH
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
-PACKAGE_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd -P)"
-
-if [[ ! -d "$PACKAGE_ROOT/pennyfarthing_scripts" ]]; then
-    PROJECT_ROOT="$PWD"
-    while [[ ! -d "$PROJECT_ROOT/.pennyfarthing" ]] && [[ "$PROJECT_ROOT" != "/" ]]; do
-        PROJECT_ROOT="$(dirname "$PROJECT_ROOT")"
-    done
-    if [[ -d "$PROJECT_ROOT/node_modules/@pennyfarthing/core/pennyfarthing_scripts" ]]; then
-        PACKAGE_ROOT="$PROJECT_ROOT/node_modules/@pennyfarthing/core"
-    fi
-fi
-
-export PYTHONPATH="${PACKAGE_ROOT}:${PYTHONPATH:-}"
-exec python3 -m pennyfarthing_scripts.prime "$@"
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
+exec_pf prime "$@"

package/pennyfarthing-dist/scripts/git/README.md

@@ -4,29 +4,29 @@ Scripts for Git operations, branching, and worktree management.
 
 ## CLI Commands (preferred)
 
-All git operations are available via the `pf git` CLI:
+All git operations are available via the `pf.sh git` CLI:
 
 | Command | Purpose |
 |---------|---------|
-| `pf git status [--brief]` | Show git status across all repos |
-| `pf git branches <name> [--repos all\|api\|ui]` | Create feature branches in repos |
-| `pf git worktree create <name> <branch>` | Create worktrees for parallel work |
-| `pf git worktree remove <name>` | Remove worktree and clean up |
-| `pf git worktree list` | List all active worktrees |
-| `pf git worktree status` | Show detailed worktree status |
-| `pf git install-hooks` | Install git hooks with .d/ dispatcher |
-| `pf git cleanup` | Organize changes into commits/branches |
+| `pf.sh git status [--brief]` | Show git status across all repos |
+| `pf.sh git branches <name> [--repos all\|api\|ui]` | Create feature branches in repos |
+| `pf.sh git worktree create <name> <branch>` | Create worktrees for parallel work |
+| `pf.sh git worktree remove <name>` | Remove worktree and clean up |
+| `pf.sh git worktree list` | List all active worktrees |
+| `pf.sh git worktree status` | Show detailed worktree status |
+| `pf.sh git install-hooks` | Install git hooks with .d/ dispatcher |
+| `pf.sh git cleanup` | Organize changes into commits/branches |
 
 ## Legacy Scripts (deprecated shims)
 
-These scripts now forward to `pf git` commands:
+These scripts now forward to `pf.sh git` commands:
 
 | Script | Forwards to |
 |--------|-------------|
-| `git-status-all.sh` | `pf git status` |
-| `create-feature-branches.sh` | `pf git branches` |
-| `worktree-manager.sh` | `pf git worktree` |
-| `install-git-hooks.sh` | `pf git install-hooks` |
+| `git-status-all.sh` | `pf.sh git status` |
+| `create-feature-branches.sh` | `pf.sh git branches` |
+| `worktree-manager.sh` | `pf.sh git worktree` |
+| `install-git-hooks.sh` | `pf.sh git install-hooks` |
 | `release.sh` | Release workflow (use `/pf-workflow start release`) |
 
 ## Ownership

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

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

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

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

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

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

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

@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
 # DEPRECATED: Use `pf git worktree` instead.
-# This shim forwards to the Python CLI.
-set -e
-echo "DEPRECATED: worktree-manager.sh — use 'pf git worktree' instead" >&2
-exec pf git worktree "$@"
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
+exec_pf git worktree "$@"

package/pennyfarthing-dist/scripts/hooks/README.md

@@ -6,22 +6,22 @@ Git hooks and Claude Code hooks.
 
 | Script | Purpose |
 |--------|---------|
-| `pf hooks context-breaker` | Claude hook: halt at context limit |
-| `pf hooks context-warning` | Claude hook: warn on high context |
+| `pf.sh hooks context-breaker` | Claude hook: halt at context limit |
+| `pf.sh hooks context-warning` | Claude hook: warn on high context |
 | `otel-auto-config.sh` | Claude hook: configure OTEL |
 | `post-merge.sh` | Git hook: post-merge actions |
 | `pre-commit.sh` | Git hook: branch protection, agent validation, sprint YAML validation |
-| `pf hooks pre-edit-check` | Claude hook: validate before edit |
+| `pf.sh hooks pre-edit-check` | Claude hook: validate before edit |
 | `pre-push.sh` | Git hook: pre-push validation |
-| `pf hooks session-start` | Claude hook: session start |
-| `pf hooks session-stop` | Claude hook: session stop |
+| `pf.sh hooks session-start` | Claude hook: session start |
+| `pf.sh hooks session-stop` | Claude hook: session stop |
 
 ## Installation
 
 Git hooks are installed via:
 
 ```bash
-pf git install-hooks
+pf.sh git install-hooks
 ```
 
 Claude hooks are configured in `.claude/settings.json`.

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

@@ -1,4 +1,4 @@
 #!/usr/bin/env bash
-# DEPRECATED: This script is a shim. Logic has moved to Python.
-# Use: pf hooks bell-mode
-exec pf hooks bell-mode
+# 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

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

@@ -1,4 +1,4 @@
 #!/usr/bin/env bash
-# DEPRECATED: This script is a shim. Logic has moved to Python.
-# Use: pf hooks context-breaker
-exec pf hooks context-breaker
+# 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

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

@@ -1,4 +1,4 @@
 #!/usr/bin/env bash
-# DEPRECATED: This script is a shim. Logic has moved to Python.
-# Use: pf hooks context-warning
-exec pf hooks context-warning
+# 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

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

@@ -1,4 +1,4 @@
 #!/usr/bin/env bash
-# DEPRECATED: This script is a shim. Logic has moved to Python.
-# Use: pf hooks cyclist-pretooluse
-exec pf hooks cyclist-pretooluse
+# 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

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

@@ -1,7 +1,7 @@
 #!/bin/bash
 # otel-auto-config.sh - Auto-configure OTEL for Cyclist web mode (Story 20-1)
 #
-# This hook checks for a .wheelhub-port file in the project directory.
+# This hook checks for a .bikerack-port file in the project directory.
 # If found, it sets the OTEL environment variables to connect Claude Code
 # telemetry to the running Cyclist server.
 #
@@ -9,15 +9,15 @@
 #   source /path/to/otel-auto-config.sh
 #
 # Prerequisites:
-#   - Cyclist must be running in web mode (writes .wheelhub-port file)
+#   - Cyclist must be running in web mode (writes .bikerack-port file)
 #   - CLAUDE_PROJECT_DIR must be set (standard in Claude Code environment)
 
 # Determine project directory
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
 
-# Read port from .wheelhub-port (used by both Cyclist and BikeRack)
+# Read port from .bikerack-port (used by both Cyclist and BikeRack)
 PORT=""
-PORT_FILE="$PROJECT_DIR/.wheelhub-port"
+PORT_FILE="$PROJECT_DIR/.bikerack-port"
 if [[ -f "$PORT_FILE" ]]; then
   PORT=$(cat "$PORT_FILE" 2>/dev/null)
   # Validate port is a number
@@ -28,6 +28,7 @@ fi
 
 # Configure OTEL if a valid port was found
 if [[ -n "$PORT" ]]; then
+  export CLAUDE_CODE_ENABLE_TELEMETRY=1
   export OTEL_EXPORTER_OTLP_PROTOCOL="http/json"
   export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:$PORT"
 

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

@@ -134,7 +134,8 @@ fi
 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$' \
-    | grep -v 'sprint/context/archived/' || true)
+    | grep -v 'sprint/context/archived/' \
+    | grep -v 'sprints\.yaml$' || true)
 
 if [[ -n "$SPRINT_YAML_FILES" ]]; then
     echo "Sprint YAML files staged for commit:"

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

@@ -1,4 +1,4 @@
 #!/usr/bin/env bash
-# DEPRECATED: This script is a shim. Logic has moved to Python.
-# Use: pf hooks pre-edit-check
-exec pf hooks pre-edit-check
+# 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 pre-edit-check

package/pennyfarthing-dist/scripts/hooks/question-reflector-check.sh

@@ -1,4 +1,4 @@
 #!/usr/bin/env bash
-# DEPRECATED: This script is a shim. Logic has moved to Python.
-# Use: pf hooks reflector-check
-exec pf hooks reflector-check
+# 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 reflector-check

package/pennyfarthing-dist/scripts/hooks/schema-validation.sh

@@ -1,4 +1,4 @@
 #!/usr/bin/env bash
-# DEPRECATED: This script is a shim. Logic has moved to Python.
-# Use: pf hooks schema-validation
-exec pf hooks schema-validation
+# 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 schema-validation

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

@@ -1,4 +1,4 @@
 #!/usr/bin/env bash
-# DEPRECATED: This script is a shim. Logic has moved to Python.
-# Use: pf hooks session-start
-exec pf hooks session-start
+# Shim: delegates to Python CLI via uv run — no global pf install needed.
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
+exec_pf hooks session-start

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

@@ -1,4 +1,4 @@
 #!/usr/bin/env bash
-# DEPRECATED: This script is a shim. Logic has moved to Python.
-# Use: pf hooks session-stop
-exec pf hooks session-stop
+# Shim: delegates to Python CLI via uv run — no global pf install needed.
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
+exec_pf hooks session-stop

package/pennyfarthing-dist/scripts/hooks/sprint-yaml-validation.sh

@@ -1,4 +1,4 @@
 #!/usr/bin/env bash
-# DEPRECATED: This script is a shim. Logic has moved to Python.
-# Use: pf hooks sprint-yaml
-exec pf hooks sprint-yaml
+# Shim: delegates to Python CLI via uv run — no global pf install needed.
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
+exec_pf hooks sprint-yaml

package/pennyfarthing-dist/scripts/hooks/welcome-hook.sh

@@ -1,5 +1,4 @@
 #!/usr/bin/env bash
-# DEPRECATED: This script is a shim. Logic has moved to Python.
-# Welcome is now part of session-start.
-# Use: pf hooks session-start
-exec pf hooks session-start
+# Shim: delegates to Python CLI via uv run — no global pf install needed.
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
+exec_pf hooks session-start

package/pennyfarthing-dist/scripts/lib/env.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Resolve CLAUDE_PROJECT_DIR in any context (hooks, Bash tool, subshells).
+#
+# Claude Code sets CLAUDE_PROJECT_DIR for hook execution but NOT for the
+# Bash tool environment.  This script fills the gap by walking up from PWD
+# to find .pennyfarthing/, mirroring find-root.sh's fallback strategy.
+#
+# Usage:
+#   source .pennyfarthing/scripts/lib/env.sh   # relative (Bash tool)
+#   source "$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/lib/env.sh"  # hooks (already set)
+#
+# After sourcing, CLAUDE_PROJECT_DIR is exported and safe to use.
+
+if [[ -z "${CLAUDE_PROJECT_DIR:-}" ]]; then
+  _d="$PWD"
+  while [[ ! -d "$_d/.pennyfarthing" ]] && [[ "$_d" != "/" ]]; do
+    _d="$(dirname "$_d")"
+  done
+  if [[ -d "$_d/.pennyfarthing" ]]; then
+    # Guard against nested .pennyfarthing (e.g., inlined child repo).
+    # If the found dir sits inside a parent that also has .pennyfarthing/,
+    # prefer the parent (outermost project root).
+    _parent="$(dirname "$_d")"
+    while [[ "$_parent" != "/" ]]; do
+      if [[ -d "$_parent/.pennyfarthing" ]]; then
+        _d="$_parent"
+      fi
+      _parent="$(dirname "$_parent")"
+    done
+    unset _parent
+    export CLAUDE_PROJECT_DIR="$_d"
+  fi
+  unset _d
+fi

package/pennyfarthing-dist/scripts/lib/run-pf.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Shared utility: Run the `pf` CLI via uv run — no global install needed.
+#
+# Resolution order for pyproject.toml:
+# 1. Dogfooding: $PROJECT_ROOT/pennyfarthing/pyproject.toml (inlined repo)
+# 2. Consumer:   $PROJECT_ROOT/pyproject.toml (project declares dependency)
+#
+# Usage from hook shims:
+#   source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
+#   exec_pf hooks session-start
+
+# Resolve PROJECT_ROOT if not already set
+_lib_dir="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd -P)"
+source "$_lib_dir/find-root.sh"
+
+# Find the pyproject.toml that provides pennyfarthing-scripts
+_pf_project=""
+if [[ -f "$PROJECT_ROOT/pennyfarthing/pyproject.toml" ]]; then
+    # Dogfooding: inlined framework repo
+    _pf_project="$PROJECT_ROOT/pennyfarthing"
+elif [[ -f "$PROJECT_ROOT/pyproject.toml" ]]; then
+    # Consumer: project-level pyproject.toml with pennyfarthing-scripts dep
+    _pf_project="$PROJECT_ROOT"
+fi
+
+if [[ -z "$_pf_project" ]]; then
+    echo "Error: No pyproject.toml found for pennyfarthing-scripts" >&2
+    echo "Expected: $PROJECT_ROOT/pennyfarthing/pyproject.toml (dogfooding)" >&2
+    echo "      or: $PROJECT_ROOT/pyproject.toml (consumer)" >&2
+    exit 1
+fi
+
+run_pf() {
+    uv run --project "$_pf_project" pf "$@"
+}
+
+exec_pf() {
+    exec uv run --project "$_pf_project" pf "$@"
+}