@pennyfarthing/core 7.9.5 → 8.0.0

package/pennyfarthing-dist/scripts/README.md

@@ -6,7 +6,7 @@ Scripts are organized into categorical subdirectories. **Full paths are required
 
 ```
 scripts/
-├── core/       # Essential scripts (run.sh, agent-session.sh)
+├── core/       # Essential scripts (agent-session.sh)
 ├── workflow/   # Workflow mechanics (finish-story.sh, check.sh)
 ├── sprint/     # Sprint YAML operations (sprint-status.sh)
 ├── story/      # Story operations (create-story.sh)
@@ -22,14 +22,14 @@ scripts/
 
 ## Usage
 
-All scripts are invoked via `run.sh` with **full category paths**:
+Scripts are invoked directly with **full category paths**:
 
 ```bash
 # From project root
-.pennyfarthing/scripts/core/run.sh core/agent-session.sh start sm
-.pennyfarthing/scripts/core/run.sh sprint/sprint-status.sh
-.pennyfarthing/scripts/core/run.sh jira/jira-claim-story.sh MSSCI-12345
-.pennyfarthing/scripts/core/run.sh workflow/finish-story.sh MSSCI-12345
+.pennyfarthing/scripts/core/agent-session.sh start sm
+.pennyfarthing/scripts/sprint/sprint-status.sh
+.pennyfarthing/scripts/jira/jira-claim-story.sh MSSCI-12345
+.pennyfarthing/scripts/workflow/finish-story.sh MSSCI-12345
 ```
 
 ## Distributed Scripts

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

@@ -6,18 +6,17 @@ Essential scripts required for all Pennyfarthing operations.
 
 | Script | Purpose |
 |--------|---------|
-| `run.sh` | Bootstrap script - finds PROJECT_ROOT and dispatches to other scripts |
 | `agent-session.sh` | Agent persona loading and session management |
 | `check-context.sh` | Context usage checker for monitoring token limits |
 | `prime.sh` | Context loading for agent activation |
 
 ## Usage
 
-These scripts are invoked via `run.sh`:
+These scripts are invoked directly:
 
 ```bash
-.pennyfarthing/scripts/core/run.sh core/agent-session.sh start sm
-.pennyfarthing/scripts/core/run.sh core/check-context.sh --human
+.pennyfarthing/scripts/core/agent-session.sh start sm
+.pennyfarthing/scripts/core/check-context.sh --human
 ```
 
 ## Ownership

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

@@ -2,7 +2,7 @@
 # Start an agent with phase check
 # If the current story's phase belongs to a different agent, emit handoff marker instead
 #
-# Usage: phase-check-start.sh <agent>
+# Usage: .pennyfarthing/scripts/core/phase-check-start.sh <agent>
 # Example: phase-check-start.sh dev
 
 set -euo pipefail
@@ -14,16 +14,11 @@ if [[ -z "$AGENT" ]]; then
   exit 1
 fi
 
-# Find project root
-if [[ -z "${PROJECT_ROOT:-}" ]]; then
-  d="$PWD"
-  while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
-    d="$(dirname "$d")"
-  done
-  PROJECT_ROOT="$d"
-fi
+# Self-locate and set up PROJECT_ROOT
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+source "$SCRIPT_DIR/../lib/find-root.sh"
 
-SCRIPT_DIR="$PROJECT_ROOT/.pennyfarthing/scripts/core"
+SCRIPTS_DIR="$SCRIPT_DIR/.."
 SESSION_DIR="$PROJECT_ROOT/.session"
 
 # Find active session file
@@ -31,7 +26,7 @@ SESSION_FILE=$(find "$SESSION_DIR" -maxdepth 1 -name "*-session.md" 2>/dev/null
 
 if [[ -z "$SESSION_FILE" || ! -f "$SESSION_FILE" ]]; then
   # No session - just start the agent normally
-  exec "$SCRIPT_DIR/run.sh" core/agent-session.sh start "$AGENT"
+  exec "$SCRIPTS_DIR/core/agent-session.sh" start "$AGENT"
 fi
 
 # Extract workflow and phase from session (handles multiple formats)
@@ -42,7 +37,7 @@ PHASE=$(grep -E "\*\*Phase\*?\*?:" "$SESSION_FILE" 2>/dev/null | head -1 | sed '
 
 if [[ -z "$WORKFLOW" ]]; then
   # Can't determine workflow - start normally
-  exec "$SCRIPT_DIR/run.sh" core/agent-session.sh start "$AGENT"
+  exec "$SCRIPTS_DIR/core/agent-session.sh" start "$AGENT"
 fi
 
 # If no Phase field, try to infer from status patterns
@@ -66,22 +61,22 @@ if [[ -z "$PHASE" ]]; then
     PHASE="green"  # TEA done, Dev's turn
   else
     # Can't determine phase - start normally
-    exec "$SCRIPT_DIR/run.sh" core/agent-session.sh start "$AGENT"
+    exec "$SCRIPTS_DIR/core/agent-session.sh" start "$AGENT"
   fi
 fi
 
 # Get the owner of this phase
-OWNER=$("$SCRIPT_DIR/run.sh" workflow/phase-owner.sh "$WORKFLOW" "$PHASE" 2>/dev/null || echo "")
+OWNER=$("$SCRIPTS_DIR/workflow/phase-owner.sh" "$WORKFLOW" "$PHASE" 2>/dev/null || echo "")
 
 if [[ -z "$OWNER" ]]; then
   # Phase owner lookup failed - start normally
-  exec "$SCRIPT_DIR/run.sh" core/agent-session.sh start "$AGENT"
+  exec "$SCRIPTS_DIR/core/agent-session.sh" start "$AGENT"
 fi
 
 # Check if this agent owns the phase
 if [[ "$OWNER" == "$AGENT" ]]; then
   # Correct agent - start normally
-  exec "$SCRIPT_DIR/run.sh" core/agent-session.sh start "$AGENT"
+  exec "$SCRIPTS_DIR/core/agent-session.sh" start "$AGENT"
 fi
 
 # Wrong agent! Output the handoff marker and info
@@ -92,4 +87,4 @@ echo "Phase owner: $OWNER (you requested: $AGENT)"
 echo ""
 
 # Generate and output the handoff marker
-"$SCRIPT_DIR/handoff-marker.sh" "$OWNER"
+"$SCRIPTS_DIR/core/handoff-marker.sh" "$OWNER"

package/pennyfarthing-dist/scripts/cyclist/is-cyclist.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # Check if running inside Cyclist visual terminal
-# Usage: .pennyfarthing/scripts/core/run.sh cyclist/is-cyclist.sh
+# Usage: .pennyfarthing/scripts/cyclist/is-cyclist.sh
 #
 # Exit codes:
 #   0 - Running in Cyclist

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

@@ -15,8 +15,8 @@ Scripts for Git operations, branching, and release management.
 ## Usage
 
 ```bash
-.pennyfarthing/scripts/core/run.sh git/create-feature-branches.sh feat/my-feature
-.pennyfarthing/scripts/core/run.sh git/release.sh
+.pennyfarthing/scripts/git/create-feature-branches.sh feat/my-feature
+.pennyfarthing/scripts/git/release.sh
 ```
 
 ## Ownership

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

@@ -8,21 +8,9 @@
 
 set -euo pipefail
 
-# Find project root
-find_project_root() {
-    local dir="$PWD"
-    while [[ ! -d "$dir/.pennyfarthing" ]] && [[ "$dir" != "/" ]]; do
-        dir="$(dirname "$dir")"
-    done
-    if [[ -d "$dir/.pennyfarthing" ]]; then
-        echo "$dir"
-    else
-        echo "Error: Not in a Pennyfarthing project" >&2
-        exit 1
-    fi
-}
-
-PROJECT_ROOT="$(find_project_root)"
+# Self-locate and set up PROJECT_ROOT
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+source "$SCRIPT_DIR/../lib/find-root.sh"
 HOOKS_SOURCE="$PROJECT_ROOT/pennyfarthing-dist/scripts/hooks"
 HOOKS_DEST="$PROJECT_ROOT/.git/hooks"
 

package/pennyfarthing-dist/scripts/git/release.sh

@@ -19,7 +19,7 @@ set -e
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
-# Use exported PROJECT_ROOT from run.sh, or detect it
+# Use exported PROJECT_ROOT from find-root.sh, or detect it
 if [[ -z "${PROJECT_ROOT:-}" ]]; then
     _dir="$PWD"
     while [[ ! -d "$_dir/.pennyfarthing" ]] && [[ "$_dir" != "/" ]]; do

package/pennyfarthing-dist/scripts/health/drift-detection.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # Drift Detection - Analyze archived sessions for agent behavior drift
-# Usage: .pennyfarthing/scripts/core/run.sh health/drift-detection.sh [--verbose] [--path /additional/path]
+# Usage: .pennyfarthing/scripts/health/drift-detection.sh [--verbose] [--path /additional/path]
 #
 # Checks:
 # 1. Reviewer: Substantive comments present (not just "LGTM")

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

@@ -21,7 +21,7 @@ Git hooks and Claude Code hooks.
 Git hooks are installed via:
 
 ```bash
-.pennyfarthing/scripts/core/run.sh git/install-git-hooks.sh
+.pennyfarthing/scripts/git/install-git-hooks.sh
 ```
 
 Claude hooks are configured in `.claude/settings.json`.

package/pennyfarthing-dist/scripts/hooks/post-merge.sh

@@ -14,18 +14,9 @@
 
 set -uo pipefail
 
-# Find project root by looking for .claude/ marker
-find_project_root() {
-    local dir="$PWD"
-    while [[ ! -d "$dir/.pennyfarthing" ]] && [[ "$dir" != "/" ]]; do
-        dir="$(dirname "$dir")"
-    done
-    if [[ -d "$dir/.pennyfarthing" ]]; then
-        echo "$dir"
-    else
-        return 1
-    fi
-}
+# Self-locate and set up PROJECT_ROOT
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd -P)"
+source "$SCRIPT_DIR/../lib/find-root.sh"
 
 # Initialize paths
 PROJECT_ROOT="$(find_project_root 2>/dev/null || echo "")"

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

@@ -9,21 +9,9 @@
 
 set -uo pipefail
 
-# Find project root
-find_project_root() {
-    local dir="$PWD"
-    while [[ ! -d "$dir/.pennyfarthing" ]] && [[ "$dir" != "/" ]]; do
-        dir="$(dirname "$dir")"
-    done
-    if [[ -d "$dir/.pennyfarthing" ]]; then
-        echo "$dir"
-    else
-        return 1
-    fi
-}
-
-PROJECT_ROOT="$(find_project_root 2>/dev/null || echo "")"
-if [[ -z "$PROJECT_ROOT" ]]; then
+# Self-locate and set up PROJECT_ROOT
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd -P)"
+if ! source "$SCRIPT_DIR/../lib/find-root.sh" 2>/dev/null; then
     exit 0
 fi
 

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

@@ -26,8 +26,8 @@ Core logic lives in `pennyfarthing_scripts/jira/`:
 ## Usage
 
 ```bash
-.pennyfarthing/scripts/core/run.sh jira/jira-claim-story.sh MSSCI-12345
-.pennyfarthing/scripts/core/run.sh jira/jira-reconcile.sh
+.pennyfarthing/scripts/jira/jira-claim-story.sh MSSCI-12345
+.pennyfarthing/scripts/jira/jira-reconcile.sh
 ```
 
 ## Ownership

package/pennyfarthing-dist/scripts/jira/create-jira-epic.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # Create a Jira epic and its child stories from sprint YAML
-# Usage: .pennyfarthing/scripts/core/run.sh create-jira-epic.sh <epic-id> [--dry-run]
+# Usage: .pennyfarthing/scripts/jira/create-jira-epic.sh <epic-id> [--dry-run]
 
 set -euo pipefail
 

package/pennyfarthing-dist/scripts/jira/create-jira-story.sh

@@ -14,7 +14,7 @@ if [[ -z "$EPIC_JIRA_KEY" || -z "$STORY_ID" ]]; then
   exit 1
 fi
 
-# PROJECT_ROOT should be set by run.sh, but find it if not
+# PROJECT_ROOT should be set by find-root.sh, but find it if not
 if [[ -z "${PROJECT_ROOT:-}" ]]; then
   d="$PWD"
   while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do

package/pennyfarthing-dist/scripts/jira/jira-reconcile.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # Jira vs YAML Reconciliation Report
-# Usage: .pennyfarthing/scripts/core/run.sh jira/jira-reconcile.sh [--fix]
+# Usage: .pennyfarthing/scripts/jira/jira-reconcile.sh [--fix]
 #
 # Compares sprint YAML against Jira to find:
 # - Status mismatches
@@ -13,7 +13,7 @@
 
 set -euo pipefail
 
-# PROJECT_ROOT should be set by run.sh, but find it if not
+# PROJECT_ROOT should be set by find-root.sh, but find it if not
 if [[ -z "${PROJECT_ROOT:-}" ]]; then
   d="$PWD"
   while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do

package/pennyfarthing-dist/scripts/lib/find-root.sh

@@ -1,35 +1,55 @@
-#!/usr/bin/env zsh
-# Shared utility: Find project root by .pennyfarthing/ marker
+#!/usr/bin/env bash
+# Shared utility: Find project root via BASH_SOURCE self-location
 #
-# DEPRECATED: Scripts invoked via run.sh already have PROJECT_ROOT set.
-# This file is kept for backwards compatibility with scripts that may be
-# run directly (not via run.sh).
+# Core principle: Scripts derive paths from their own location, not from $PWD.
+# A script in pennyfarthing-dist/scripts/<category>/ is always 3 levels below
+# the package root. This works regardless of where the user invoked it from.
 #
-# When run.sh executes a script, it sets PROJECT_ROOT before exec'ing,
-# so sourcing this file is a no-op (line 12 skips if already set).
-#
-# For new scripts: Just assume PROJECT_ROOT is set by the caller (run.sh).
+# Usage:
+#   SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+#   source "$SCRIPT_DIR/../lib/find-root.sh"
+#   # PROJECT_ROOT is now set
 
-# Skip if PROJECT_ROOT is already set (e.g., by run.sh or CLAUDE_PROJECT_DIR)
-if [ -z "${PROJECT_ROOT:-}" ]; then
-    # Prefer SCRIPT_DIR (stable, set by caller) over PWD (may not be in project)
-    if [ -n "${SCRIPT_DIR:-}" ]; then
-        _find_root_dir="$SCRIPT_DIR"
-    else
-        _find_root_dir="$PWD"
-    fi
+# Require SCRIPT_DIR to be set by caller
+if [[ -z "${SCRIPT_DIR:-}" ]]; then
+    echo "Error: SCRIPT_DIR must be set before sourcing find-root.sh" >&2
+    echo "Add this before sourcing:" >&2
+    echo '  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"' >&2
+    exit 1
+fi
+
+# Allow explicit override via PENNYFARTHING_ROOT (avoids conflict with orchestrator's PROJECT_ROOT)
+if [[ -n "${PENNYFARTHING_ROOT:-}" ]]; then
+    PROJECT_ROOT="$PENNYFARTHING_ROOT"
+    export PROJECT_ROOT
+    return 0 2>/dev/null || exit 0
+fi
+
+# Resolve SCRIPT_DIR (follow symlinks to real location)
+_real_script_dir="$(cd "$SCRIPT_DIR" && pwd -P)"
 
-    while [[ ! -d "$_find_root_dir/.pennyfarthing" ]] && [[ "$_find_root_dir" != "/" ]]; do
-        _find_root_dir="$(dirname "$_find_root_dir")"
-    done
+# Derive package root from script location
+# Scripts in pennyfarthing-dist/scripts/lib/ are 3 levels deep
+# Scripts in pennyfarthing-dist/scripts/<category>/ are also 3 levels deep
+if [[ "$_real_script_dir" == */pennyfarthing-dist/scripts/* ]]; then
+    # Extract everything before /pennyfarthing-dist/scripts/
+    _pkg_root="${_real_script_dir%/pennyfarthing-dist/scripts/*}"
 
-    if [[ -d "$_find_root_dir/.pennyfarthing" ]]; then
-        PROJECT_ROOT="$_find_root_dir"
+    # Determine context: framework dev or consumer?
+    if [[ -d "$_pkg_root/pennyfarthing-dist" && ! -L "$_pkg_root/pennyfarthing-dist" ]]; then
+        # Framework context: package root IS project root
+        PROJECT_ROOT="$_pkg_root"
+    elif [[ "$_pkg_root" == */node_modules/* ]]; then
+        # Consumer context: walk up from node_modules to project
+        PROJECT_ROOT="${_pkg_root%/node_modules/*}"
     else
-        echo "Error: Could not find project root (no .pennyfarthing/ directory found)" >&2
-        exit 1
+        PROJECT_ROOT="$_pkg_root"
     fi
-    unset _find_root_dir
+else
+    echo "Error: Script not in expected location (pennyfarthing-dist/scripts/...)" >&2
+    echo "SCRIPT_DIR=$_real_script_dir" >&2
+    exit 1
 fi
 
+unset _real_script_dir _pkg_root
 export PROJECT_ROOT

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

@@ -29,8 +29,8 @@ Uncategorized utilities and one-off scripts.
 ## Usage
 
 ```bash
-.pennyfarthing/scripts/core/run.sh misc/doctor-dogfood.sh
-.pennyfarthing/scripts/core/run.sh misc/run-ci.sh
+.pennyfarthing/scripts/misc/doctor-dogfood.sh
+.pennyfarthing/scripts/misc/run-ci.sh
 ```
 
 ## Ownership

package/pennyfarthing-dist/scripts/misc/backlog.sh

@@ -5,23 +5,9 @@
 
 set -euo pipefail
 
-SCRIPT_DIR="${0:A:h}"
-PROJECT_ROOT="${SCRIPT_DIR}/../.."
-
-# Find project root by looking for .pennyfarthing directory
-find_project_root() {
-    local dir="$PWD"
-    while [[ "$dir" != "/" ]]; do
-        if [[ -d "$dir/.pennyfarthing" ]]; then
-            echo "$dir"
-            return 0
-        fi
-        dir="$(dirname "$dir")"
-    done
-    echo "$PWD"
-}
-
-PROJECT_ROOT="$(find_project_root)"
+# Self-locate and set up PROJECT_ROOT
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd -P)"
+source "$SCRIPT_DIR/../lib/find-root.sh"
 SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
 
 if [[ ! -f "$SPRINT_FILE" ]]; then

package/pennyfarthing-dist/scripts/misc/generate-skill-docs.sh

@@ -17,36 +17,10 @@
 
 set -euo pipefail
 
-# Find project root
-# Priority 1: .pennyfarthing/ (orchestrator/consumer repos)
-# Priority 2: pennyfarthing-dist/ (framework repo itself)
-find_project_root() {
-  local dir="$PWD"
-  # First try .pennyfarthing/
-  while [[ ! -d "$dir/.pennyfarthing" ]] && [[ "$dir" != "/" ]]; do
-    dir="$(dirname "$dir")"
-  done
-  if [[ -d "$dir/.pennyfarthing" ]]; then
-    echo "$dir"
-    return
-  fi
-  # Fall back to pennyfarthing-dist/ for framework repo
-  dir="$PWD"
-  while [[ ! -d "$dir/pennyfarthing-dist" ]] && [[ "$dir" != "/" ]]; do
-    dir="$(dirname "$dir")"
-  done
-  if [[ -d "$dir/pennyfarthing-dist" ]]; then
-    echo "$dir"
-    return
-  fi
-  echo ""
-}
-
-PROJECT_ROOT="$(find_project_root)"
-if [[ -z "$PROJECT_ROOT" ]]; then
-  echo "Error: Cannot find project root (no .pennyfarthing or pennyfarthing-dist directory found)" >&2
-  exit 1
-fi
+# Self-locate: derive PROJECT_ROOT from this script's position
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+source "$SCRIPT_DIR/../lib/find-root.sh"
+# PROJECT_ROOT is now set
 
 # Default paths
 REGISTRY_PATH="${PROJECT_ROOT}/pennyfarthing-dist/skills/skill-registry.yaml"

package/pennyfarthing-dist/scripts/misc/log-skill-usage.sh

@@ -6,7 +6,7 @@
 #   {"ts":"2026-01-11T10:30:45Z","skill":"testing","agent":"dev","session":"abc123"}
 #
 # Environment:
-#   PROJECT_ROOT - Set by run.sh bootstrap (required)
+#   PROJECT_ROOT - Set by find-root.sh (required)
 
 set -euo pipefail
 

package/pennyfarthing-dist/scripts/misc/run-ci.sh

@@ -84,16 +84,9 @@ else
     NC=''
 fi
 
-# Find project root
-find_project_root() {
-    local dir="$PWD"
-    while [[ ! -d "$dir/.pennyfarthing" ]] && [[ "$dir" != "/" ]]; do
-        dir="$(dirname "$dir")"
-    done
-    echo "$dir"
-}
-
-PROJECT_ROOT="$(find_project_root)"
+# Self-locate and set up PROJECT_ROOT
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+source "$SCRIPT_DIR/../lib/find-root.sh"
 cd "$PROJECT_ROOT" || exit 1
 
 # Detection functions

package/pennyfarthing-dist/scripts/misc/skill-usage-report.sh

@@ -9,7 +9,7 @@
 #   - Weekly breakdown (optional)
 #
 # Environment:
-#   PROJECT_ROOT - Set by run.sh bootstrap (required)
+#   PROJECT_ROOT - Set by find-root.sh (required)
 
 set -uo pipefail
 

package/pennyfarthing-dist/scripts/misc/uninstall.sh

@@ -100,7 +100,6 @@ MANAGED_PATHS=(
     "scripts/hooks"
     "scripts/lib"
     "scripts/misc"
-    "scripts/run.sh"
 )
 
 # Project paths that can be removed with --all (but preserve archives)

package/pennyfarthing-dist/scripts/portraits/generate-portraits.py

@@ -56,8 +56,25 @@ except Exception:
 
 
 # Configuration
-SCRIPT_DIR = Path(__file__).parent
-PROJECT_ROOT = SCRIPT_DIR.parent
+SCRIPT_DIR = Path(__file__).parent.resolve()
+
+# Find PROJECT_ROOT by walking up until we find pennyfarthing-dist at the expected level
+# Script lives at: {PROJECT_ROOT}/pennyfarthing-dist/scripts/portraits/generate-portraits.py
+def _find_project_root() -> Path:
+    """Find project root by looking for pennyfarthing-dist or .git marker."""
+    current = SCRIPT_DIR
+    # Walk up from portraits/ -> scripts/ -> pennyfarthing-dist/ -> PROJECT_ROOT
+    for _ in range(5):  # Safety limit
+        # Check if this looks like the project root
+        if (current / "pennyfarthing-dist" / "personas" / "themes").exists():
+            return current
+        if (current / ".git").exists() and (current / "pennyfarthing-dist").exists():
+            return current
+        current = current.parent
+    # Fallback: assume old structure (script in {root}/scripts/portraits/)
+    return SCRIPT_DIR.parent.parent
+
+PROJECT_ROOT = _find_project_root()
 BUILTIN_THEMES_DIR = PROJECT_ROOT / "pennyfarthing-dist" / "personas" / "themes"
 CUSTOM_THEMES_DIR = PROJECT_ROOT / ".claude" / "pennyfarthing" / "themes"
 OUTPUT_DIR = PROJECT_ROOT / "pennyfarthing-dist" / "personas" / "portraits"

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

@@ -19,8 +19,8 @@ Scripts for sprint YAML operations and sprint management.
 ## Usage
 
 ```bash
-.pennyfarthing/scripts/core/run.sh sprint/sprint-status.sh
-.pennyfarthing/scripts/core/run.sh sprint/available-stories.sh
+.pennyfarthing/scripts/sprint/sprint-status.sh
+.pennyfarthing/scripts/sprint/available-stories.sh
 ```
 
 ## Ownership

package/pennyfarthing-dist/scripts/sprint/archive-story.sh

@@ -1,9 +1,9 @@
 #!/bin/bash
 # Archive a completed story from current-sprint.yaml to the sprint archive
-# Usage: .pennyfarthing/scripts/core/run.sh sprint/archive-story.sh <story-id> [pr-number] [--apply]
+# Usage: .pennyfarthing/scripts/sprint/archive-story.sh <story-id> [pr-number] [--apply]
 #
-# Example: .pennyfarthing/scripts/core/run.sh sprint/archive-story.sh MSSCI-11945 368
-#          .pennyfarthing/scripts/core/run.sh sprint/archive-story.sh MSSCI-11945 368 --apply
+# Example: .pennyfarthing/scripts/sprint/archive-story.sh MSSCI-11945 368
+#          .pennyfarthing/scripts/sprint/archive-story.sh MSSCI-11945 368 --apply
 #
 # Options:
 #   --apply    Also remove story from current-sprint.yaml (atomic operation)
@@ -40,7 +40,7 @@ if [[ -z "$STORY_ID" ]]; then
   exit 1
 fi
 
-# PROJECT_ROOT should be set by run.sh, but find it if not
+# PROJECT_ROOT should be set by find-root.sh, but find it if not
 if [[ -z "${PROJECT_ROOT:-}" ]]; then
   d="$PWD"
   while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
@@ -133,7 +133,7 @@ if $APPLY_FLAG; then
 else
   echo ""
   echo "To also remove from $SPRINT_FILE, re-run with --apply:"
-  echo "  .pennyfarthing/scripts/core/run.sh sprint/archive-story.sh $STORY_ID ${PR_NUMBER:-<pr>} --apply"
+  echo "  .pennyfarthing/scripts/sprint/archive-story.sh $STORY_ID ${PR_NUMBER:-<pr>} --apply"
   echo ""
   echo "Or manually: yq eval -i 'del(.epics[].stories[] | select(.id == \"$STORY_ID\"))' $SPRINT_FILE"
 fi

package/pennyfarthing-dist/scripts/sprint/available-stories.sh

@@ -1,12 +1,12 @@
 #!/bin/bash
 # Display available stories grouped by epic with Jira context
-# Usage: .pennyfarthing/scripts/core/run.sh sprint/available-stories.sh
+# Usage: .pennyfarthing/scripts/sprint/available-stories.sh
 #
 # Shows backlog stories with epic context, points, and workflow
 
 set -euo pipefail
 
-# PROJECT_ROOT should be set by run.sh, but find it if not
+# PROJECT_ROOT should be set by find-root.sh, but find it if not
 if [[ -z "${PROJECT_ROOT:-}" ]]; then
   d="$PWD"
   while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do

package/pennyfarthing-dist/scripts/sprint/check-story.sh

@@ -18,7 +18,7 @@ if [[ -z "$ID" ]]; then
   exit 1
 fi
 
-# PROJECT_ROOT should be set by run.sh
+# PROJECT_ROOT should be set by find-root.sh
 if [[ -z "${PROJECT_ROOT:-}" ]]; then
   d="$PWD"
   while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do