@pennyfarthing/core 11.2.1 → 11.3.1

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

@@ -181,7 +181,7 @@ The `gate.file` value is resolved by the gate file discovery algorithm (project-
 Validate gate files before use:
 
 ```bash
-pf gate validate path/to/gate-file.md
+pf.sh gate validate path/to/gate-file.md
 ```
 
 The validator checks:
@@ -215,7 +215,7 @@ Gate 'tests-pass' is valid
 
 6. **Add recovery steps.** The `recovery` array in failed results gives the agent a clear path to fix issues and retry.
 
-7. **Test with the validator.** Run `pf gate validate` on your gate file before referencing it in a workflow.
+7. **Test with the validator.** Run `pf.sh gate validate` on your gate file before referencing it in a workflow.
 
 ## Related
 

package/pennyfarthing-dist/guides/gates.md

@@ -15,7 +15,12 @@ Gates live in `pennyfarthing-dist/gates/` and are referenced by workflow YAML fi
 | **tests-pass** | `gates/tests-pass.md` | Verify all tests pass, working tree clean, correct branch | Dev → Reviewer transitions |
 | **tests-fail** | `gates/tests-fail.md` | Verify tests are RED (failing) with AC coverage | TEA → Dev transitions |
 | **approval** | `gates/approval.md` | Verify reviewer has issued explicit APPROVED verdict | Reviewer → SM transitions |
-| **confidence-sm** | `gates/confidence-sm.md` | Check if user instruction to SM is ambiguous | SM entry gate |
+| **confidence** | `gates/confidence.md` | Check if user instruction is ambiguous | Any agent entry gate |
+| **dev-exit** | `gates/dev-exit.md` | Composite: tests-pass + no debug code | Dev → Reviewer transitions |
+| **sm-setup-exit** | `gates/sm-setup-exit.md` | Session file, fields, context, branch created | SM → next agent transitions |
+| **merge-ready** | `gates/merge-ready.md` | No open non-draft PRs | SM new work gate |
+| **release-ready** | `gates/release-ready.md` | Composite: tests-pass + build, version, changelog | DevOps pre-deploy |
+| **reviewer-preflight-check** | `gates/reviewer-preflight-check.md` | Composite: tests-pass + code smells, error boundaries | Reviewer preflight |
 
 ## Gate File Format
 
@@ -78,14 +83,14 @@ Agents interact with gates through the handoff CLI during their exit sequence:
 
 ```
 1. Agent writes assessment to session file
-2. pf handoff resolve-gate {story-id} {workflow} {phase}
+2. pf.sh handoff resolve-gate {story-id} {workflow} {phase}
    → Reads workflow YAML, finds gate for current phase
    → Returns RESOLVE_RESULT: {status: ready|skip|blocked, gate_file: ...}
 3. If ready → spawn Haiku subagent with gate file → GATE_RESULT
 4. If GATE_RESULT.status == fail → fix issues, retry (max 3)
 5. If GATE_RESULT.status == pass → continue to complete-phase
-6. pf handoff complete-phase {story-id} {workflow} {from} {to} {gate-type}
-7. pf handoff marker {next-agent}
+6. pf.sh handoff complete-phase {story-id} {workflow} {from} {to} {gate-type}
+7. pf.sh handoff marker {next-agent}
 ```
 
 If a phase has no `gate:` block, `resolve-gate` returns `status: skip` and the agent proceeds directly to `complete-phase`.
@@ -96,7 +101,7 @@ Extended evaluation criteria can live in `gates/evaluations/`:
 
 | File | Purpose |
 |------|---------|
-| `evaluations/confidence-sm.md` | Detailed rubric for SM confidence scoring |
+| `evaluations/confidence-sm.md` | Historical evaluation of SM confidence gate (led to agent-agnostic `confidence` gate) |
 
 ## Creating Custom Gates
 

package/pennyfarthing-dist/guides/handoff-cli.md

@@ -1,7 +1,7 @@
 # Handoff CLI
 
 <info>
-Python CLI for managing workflow phase transitions. Agents use `pf handoff` to resolve gates, complete phase transitions, and generate handoff markers during their exit protocol.
+Python CLI for managing workflow phase transitions. Agents use `pf.sh handoff` to resolve gates, complete phase transitions, and generate handoff markers during their exit protocol.
 </info>
 
 ## Commands
@@ -11,7 +11,7 @@ Python CLI for managing workflow phase transitions. Agents use `pf handoff` to r
 Check whether the current phase has a gate and what state it's in.
 
 ```bash
-pf handoff resolve-gate STORY_ID WORKFLOW PHASE
+pf.sh handoff resolve-gate STORY_ID WORKFLOW PHASE
 ```
 
 **Arguments:**
@@ -39,7 +39,7 @@ RESOLVE_RESULT:
 Atomically update the session file to record a phase transition.
 
 ```bash
-pf handoff complete-phase STORY_ID WORKFLOW FROM_PHASE TO_PHASE GATE_TYPE
+pf.sh handoff complete-phase STORY_ID WORKFLOW FROM_PHASE TO_PHASE GATE_TYPE
 ```
 
 **Arguments:**
@@ -66,8 +66,8 @@ Updates the session file: `**Phase:**` line, timestamps, and phase history table
 Generate an environment-aware handoff marker block.
 
 ```bash
-pf handoff marker NEXT_AGENT
-pf handoff marker --error "Tests failing"
+pf.sh handoff marker NEXT_AGENT
+pf.sh handoff marker --error "Tests failing"
 ```
 
 **Arguments:**
@@ -88,14 +88,14 @@ The handoff CLI is used in sequence during agent exit:
 
 ```
 1. Write assessment to session file
-2. pf handoff resolve-gate {story-id} {workflow} {phase}
+2. pf.sh handoff resolve-gate {story-id} {workflow} {phase}
    ├── blocked → report error, STOP
    ├── skip → jump to step 4
    └── ready → spawn gate subagent → GATE_RESULT
        ├── fail → fix issues, retry (max 3)
        └── pass → continue
-3. pf handoff complete-phase {story-id} {workflow} {from} {to} {gate-type}
-4. pf handoff marker {next-agent} → emit marker → EXIT
+3. pf.sh handoff complete-phase {story-id} {workflow} {from} {to} {gate-type}
+4. pf.sh handoff marker {next-agent} → emit marker → EXIT
 ```
 
 See `guides/gates.md` for gate file format and evaluation details.

package/pennyfarthing-dist/guides/hooks.md

@@ -16,18 +16,18 @@ Hooks are commands that Claude Code runs at specific events:
 
 ### SessionStart Hooks
 
-#### pf hooks session-start
+#### pf.sh hooks session-start
 
-**Location:** `pf hooks session-start`
+**Location:** `pf.sh hooks session-start`
 
 Initializes the Pennyfarthing environment:
 - Creates `.session/` directory structure
 - Clears stale agent state from previous sessions
 - Sets `PROJECT_ROOT` and `SESSION_ID` environment variables
 
-#### pf hooks session-stop
+#### pf.sh hooks session-stop
 
-**Location:** `pf hooks session-stop`
+**Location:** `pf.sh hooks session-stop`
 
 Cleans up session state when Claude Code exits.
 
@@ -44,66 +44,66 @@ Project-specific environment setup. Edit this file to:
 
 **Location:** `.pennyfarthing/scripts/hooks/otel-auto-config.sh`
 
-Auto-configures OTEL telemetry for Cyclist web mode. Checks for a `.wheelhub-port` file and sets `OTEL_EXPORTER_OTLP_PROTOCOL` and `OTEL_EXPORTER_OTLP_ENDPOINT` to route Claude Code telemetry to the running Cyclist/BikeRack server.
+Auto-configures OTEL telemetry for Cyclist web mode. Checks for a `.bikerack-port` file and sets `OTEL_EXPORTER_OTLP_PROTOCOL` and `OTEL_EXPORTER_OTLP_ENDPOINT` to route Claude Code telemetry to the running Cyclist/BikeRack server.
 
-#### pf hooks session-start (welcome)
+#### pf.sh hooks session-start (welcome)
 
-**Location:** `pf hooks session-start`
+**Location:** `pf.sh hooks session-start`
 
-Welcome display is now folded into `pf hooks session-start`. In CLI mode, shows ASCII art. In Cyclist mode, sends a WebSocket message to display the logo. Runs once per session (lock file guard).
+Welcome display is now folded into `pf.sh hooks session-start`. In CLI mode, shows ASCII art. In Cyclist mode, sends a WebSocket message to display the logo. Runs once per session (lock file guard).
 
 ### PreToolUse Hooks
 
-#### pf hooks pre-edit-check
+#### pf.sh hooks pre-edit-check
 
-**Location:** `pf hooks pre-edit-check`
+**Location:** `pf.sh hooks pre-edit-check`
 
 Protects sensitive files from accidental edits:
 - Blocks: `.env`, `.pem`, `.key`, credentials, secrets
 - Blocks: `.git/`, `node_modules/`, `vendor/`
 - Blocks: `.pennyfarthing/*` (managed files)
 
-#### pf hooks cyclist-pretooluse
+#### pf.sh hooks cyclist-pretooluse
 
-**Location:** `pf hooks cyclist-pretooluse`
+**Location:** `pf.sh hooks cyclist-pretooluse`
 
 Cyclist-specific pre-tool validation. Runs additional safety checks when operating inside Cyclist.
 
-#### pf hooks context-warning
+#### pf.sh hooks context-warning
 
-**Location:** `pf hooks context-warning`
+**Location:** `pf.sh hooks context-warning`
 
 Warns agents when context usage is high. Outputs a warning at 60% usage and a critical warning at 85%. Never blocks — warning only (always exits 0).
 
-#### pf hooks context-breaker
+#### pf.sh hooks context-breaker
 
-**Location:** `pf hooks context-breaker`
+**Location:** `pf.sh hooks context-breaker`
 
-Hard stop when context reaches 80% (configurable via `CRITICAL_THRESHOLD`). Unlike `pf hooks context-warning`, this **blocks tool execution** (exit 2). Auto-saves the active agent to a checkpoint so `/pf-session continue` can restore it with FULL tier context.
+Hard stop when context reaches 80% (configurable via `CRITICAL_THRESHOLD`). Unlike `pf.sh hooks context-warning`, this **blocks tool execution** (exit 2). Auto-saves the active agent to a checkpoint so `/pf-session continue` can restore it with FULL tier context.
 
-#### pf hooks schema-validation
+#### pf.sh hooks schema-validation
 
-**Location:** `pf hooks schema-validation`
+**Location:** `pf.sh hooks schema-validation`
 
 Validates file writes against XML schema rules for agent definitions, workflow files, and other structured content.
 
-#### pf hooks sprint-yaml
+#### pf.sh hooks sprint-yaml
 
-**Location:** `pf hooks sprint-yaml`
+**Location:** `pf.sh hooks sprint-yaml`
 
 Validates sprint YAML files on write to prevent structural corruption.
 
 ### PostToolUse Hooks
 
-#### pf hooks bell-mode
+#### pf.sh hooks bell-mode
 
-**Location:** `pf hooks bell-mode`
+**Location:** `pf.sh hooks bell-mode`
 
 Bell mode message injection. Checks the bell mode queue and injects queued messages into the agent's context at the next tool execution. Also handles tandem observation injection.
 
-#### pf hooks reflector-check
+#### pf.sh hooks reflector-check
 
-**Location:** `pf hooks reflector-check`
+**Location:** `pf.sh hooks reflector-check`
 
 Stop hook enforcing that every agent turn ends with a CYCLIST marker. Detects questions, handoff phrases, and validates marker presence. Blocks turns without valid markers in Cyclist mode.
 
@@ -133,7 +133,7 @@ Hooks are configured in `.claude/settings.local.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "pf hooks session-start"
+            "command": "pf.sh hooks session-start"
           }
         ]
       }
@@ -144,7 +144,7 @@ Hooks are configured in `.claude/settings.local.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "pf hooks pre-edit-check"
+            "command": "pf.sh hooks pre-edit-check"
           }
         ]
       }

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`.