@pennyfarthing/core 10.4.0 → 11.0.0-alpha.0

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

@@ -5,7 +5,8 @@
 #
 # For the pennyfarthing framework repo and orchestrator repos that inline it.
 # End-user projects use `pennyfarthing init` which copies hooks from node_modules.
-# This script creates symlinks so hook changes in pennyfarthing-dist/ take effect immediately.
+# This script creates .d/ directories with symlinks so hook changes in
+# pennyfarthing-dist/ take effect immediately.
 
 set -euo pipefail
 
@@ -15,6 +16,10 @@ source "$SCRIPT_DIR/../lib/find-root.sh"
 HOOKS_SOURCE="$PROJECT_ROOT/pennyfarthing-dist/scripts/hooks"
 HOOKS_DEST="$PROJECT_ROOT/.git/hooks"
 
+DISPATCHER_MARKER="pennyfarthing-dispatcher"
+PF_PREFIX="10"
+MIGRATED_PREFIX="50"
+
 # Check we're in a repo with pennyfarthing-dist (framework or orchestrator)
 if [[ ! -d "$PROJECT_ROOT/pennyfarthing-dist" ]]; then
     echo "Error: This script requires pennyfarthing-dist/ at the project root"
@@ -29,11 +34,25 @@ if [[ ! -d "$PROJECT_ROOT/.git" ]]; then
     exit 1
 fi
 
-echo "Installing git hooks for dogfooding..."
+echo "Installing git hooks with .d/ dispatcher pattern..."
 echo "  Source: pennyfarthing-dist/scripts/hooks/"
 echo "  Dest:   .git/hooks/"
 echo ""
 
+# Shared dispatcher template — single source of truth
+DISPATCHER_TEMPLATE="$PROJECT_ROOT/pennyfarthing-dist/scripts/hooks/dispatcher-template.sh"
+
+if [[ ! -f "$DISPATCHER_TEMPLATE" ]]; then
+    echo "Error: dispatcher-template.sh not found at $DISPATCHER_TEMPLATE"
+    exit 1
+fi
+
+# Generate a dispatcher script for a given hook name
+generate_dispatcher() {
+    local hook_name="$1"
+    sed "s/__HOOK_NAME__/${hook_name}/g" "$DISPATCHER_TEMPLATE"
+}
+
 # Define hooks to install
 HOOKS=(
     "pre-commit.sh:pre-commit"
@@ -47,35 +66,79 @@ for hook_pair in "${HOOKS[@]}"; do
 
     source_path="$HOOKS_SOURCE/$source_file"
     dest_path="$HOOKS_DEST/$dest_name"
+    d_dir="$HOOKS_DEST/${dest_name}.d"
+    pf_hook_name="${PF_PREFIX}-pennyfarthing-${dest_name}.sh"
+    pf_hook_path="${d_dir}/${pf_hook_name}"
 
     if [[ ! -f "$source_path" ]]; then
         echo "  SKIP $dest_name (source not found)"
         continue
     fi
 
-    # Create relative symlink
-    # From .git/hooks/ we need to go ../../pennyfarthing-dist/scripts/hooks/
-    relative_path="../../pennyfarthing-dist/scripts/hooks/$source_file"
+    # Create .d/ directory
+    mkdir -p "$d_dir"
 
-    if [[ -L "$dest_path" ]]; then
-        # Already a symlink - check if it points to our file
-        current_target=$(readlink "$dest_path")
-        if [[ "$current_target" == "$relative_path" ]]; then
-            echo "  OK   $dest_name (already installed)"
-            continue
+    # Handle existing hook at the dest path
+    if [[ -e "$dest_path" ]]; then
+        if [[ -f "$dest_path" ]] && grep -q "$DISPATCHER_MARKER" "$dest_path" 2>/dev/null; then
+            echo "  OK   $dest_name dispatcher (already installed)"
+        elif [[ -L "$dest_path" ]]; then
+            # Old-style symlink — migrate to .d/ pattern
+            rm "$dest_path"
+            generate_dispatcher "$dest_name" > "$dest_path"
+            chmod 755 "$dest_path"
+            echo "  UPD  $dest_name → dispatcher"
+        elif [[ -f "$dest_path" ]]; then
+            existing_content="$(cat "$dest_path")"
+            if echo "$existing_content" | grep -q "pennyfarthing"; then
+                # Old pennyfarthing single-file hook — replace with dispatcher
+                generate_dispatcher "$dest_name" > "$dest_path"
+                chmod 755 "$dest_path"
+                echo "  UPD  $dest_name → dispatcher (was single-file pf hook)"
+            else
+                # Non-pennyfarthing hook — migrate into .d/
+                migrated_name="${MIGRATED_PREFIX}-migrated-${dest_name}.sh"
+                migrated_path="${d_dir}/${migrated_name}"
+                if [[ ! -f "$migrated_path" ]]; then
+                    mv "$dest_path" "$migrated_path"
+                    chmod 755 "$migrated_path"
+                    echo "  MIG  $dest_name → ${dest_name}.d/${migrated_name}"
+                fi
+                generate_dispatcher "$dest_name" > "$dest_path"
+                chmod 755 "$dest_path"
+                echo "  NEW  $dest_name dispatcher"
+            fi
         fi
-        # Different symlink - remove and recreate
-        rm "$dest_path"
-    elif [[ -f "$dest_path" ]]; then
-        # Regular file - backup first
-        backup_path="${dest_path}.backup"
-        mv "$dest_path" "$backup_path"
-        echo "  BACK $dest_name -> ${dest_name}.backup"
+    else
+        # No existing hook — install fresh dispatcher
+        generate_dispatcher "$dest_name" > "$dest_path"
+        chmod 755 "$dest_path"
+        echo "  NEW  $dest_name dispatcher"
     fi
 
-    ln -sf "$relative_path" "$dest_path"
-    echo "  NEW  $dest_name -> $relative_path"
+    # Symlink pennyfarthing hook into .d/ (framework dev — symlink for live edits)
+    # From .git/hooks/{hook}.d/ we need ../../.../pennyfarthing-dist/scripts/hooks/
+    relative_path="../../../pennyfarthing-dist/scripts/hooks/$source_file"
+
+    if [[ -L "$pf_hook_path" ]]; then
+        current_target=$(readlink "$pf_hook_path")
+        if [[ "$current_target" == "$relative_path" ]]; then
+            echo "  OK   ${dest_name}.d/${pf_hook_name} (already linked)"
+        else
+            rm "$pf_hook_path"
+            ln -sf "$relative_path" "$pf_hook_path"
+            echo "  UPD  ${dest_name}.d/${pf_hook_name} → $relative_path"
+        fi
+    elif [[ -f "$pf_hook_path" ]]; then
+        # Regular file — replace with symlink for dev
+        rm "$pf_hook_path"
+        ln -sf "$relative_path" "$pf_hook_path"
+        echo "  UPD  ${dest_name}.d/${pf_hook_name} → $relative_path (was copy)"
+    else
+        ln -sf "$relative_path" "$pf_hook_path"
+        echo "  NEW  ${dest_name}.d/${pf_hook_name} → $relative_path"
+    fi
 done
 
 echo ""
-echo "Done. Verify with: ls -la .git/hooks/ | grep -v sample"
+echo "Done. Verify with: ls -la .git/hooks/*.d/"

package/pennyfarthing-dist/scripts/hooks/dispatcher-template.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# pennyfarthing-dispatcher: Git hook dispatcher for __HOOK_NAME__
+# Runs all executable scripts in __HOOK_NAME__.d/ in sorted order.
+# Installed by pennyfarthing — do not edit manually.
+
+set -uo pipefail
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK_NAME="__HOOK_NAME__"
+D_DIR="${HOOK_DIR}/${HOOK_NAME}.d"
+
+# If .d/ directory doesn't exist or is empty, exit successfully
+if [[ ! -d "${D_DIR}" ]]; then
+  exit 0
+fi
+
+# Capture stdin for hooks that receive input (e.g., pre-push)
+STDIN_DATA=""
+if [[ ! -t 0 ]]; then
+  STDIN_DATA="$(cat /dev/stdin)"
+fi
+
+# Run each executable script in sorted order
+for hook_script in $(ls "${D_DIR}/" 2>/dev/null | sort); do
+  script_path="${D_DIR}/${hook_script}"
+
+  # Skip non-executable files
+  if [[ ! -x "${script_path}" ]]; then
+    continue
+  fi
+
+  # Run the hook, forwarding arguments and stdin
+  if [[ -n "${STDIN_DATA}" ]]; then
+    echo "${STDIN_DATA}" | "${script_path}" "$@"
+  else
+    "${script_path}" "$@"
+  fi
+
+  exit_code=$?
+  if [[ ${exit_code} -ne 0 ]]; then
+    exit ${exit_code}
+  fi
+done
+
+exit 0

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

@@ -5,7 +5,8 @@
 # 1. Prevents direct commits to protected branches (main, develop)
 #    Exception: sprint/ folder commits allowed on develop
 # 2. Validates agent files when pennyfarthing-dist/agents/*.md is modified
-# 3. Validates sprint YAML files when sprint/*.yaml is modified
+# 3. Validates file references when pennyfarthing-dist/ files are modified (warn only)
+# 4. Validates sprint YAML files when sprint/*.yaml is modified
 #
 # Installation:
 #   End-user projects: pennyfarthing init (copies to .git/hooks/)
@@ -109,7 +110,31 @@ if [[ -n "$AGENT_FILES" ]]; then
 fi
 
 # =============================================================================
-# Check 3: Sprint YAML Validation
+# Check 3: File Reference Validation (warn only)
+# =============================================================================
+
+DIST_FILES=$(echo "$STAGED_FILES" | grep "^pennyfarthing-dist/" || true)
+SCRIPT_FILES=$(echo "$STAGED_FILES" | grep "^scripts/validate-refs" || true)
+
+if [[ -n "$DIST_FILES" || -n "$SCRIPT_FILES" ]]; then
+    VALIDATE_REFS="$PROJECT_ROOT/scripts/validate-refs.js"
+
+    if [[ -f "$VALIDATE_REFS" ]] && command -v node &>/dev/null; then
+        echo "Running file reference validation..."
+        if ! node "$VALIDATE_REFS" 2>&1; then
+            echo ""
+            echo "WARNING: File reference issues detected (see above)"
+            echo "CI will fail on these — fix before pushing."
+            echo ""
+        else
+            echo "✓ File reference validation passed"
+            echo ""
+        fi
+    fi
+fi
+
+# =============================================================================
+# Check 4: Sprint YAML Validation
 # =============================================================================
 
 SPRINT_YAML_FILES=$(git diff --cached --name-only -- 'sprint/*.yaml' 'sprint/archive/*.yaml' 2>/dev/null \

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

@@ -1,97 +1,33 @@
-#!/usr/bin/env zsh
-# Session start hook: Initialize environment for Claude Code session
-# Called by Claude Code when a new session starts
+#!/usr/bin/env bash
 #
-# Uses CLAUDE_ENV_FILE to persist environment variables for the session.
-# Projects using pennyfarthing can add their own hooks for project-specific vars.
+# Session Start Hook - Shell wrapper for Python implementation
 #
-# Also validates previous session checkpoint to detect cross-session state changes.
+# Initializes environment for Claude Code session:
+# - Session directory setup and logging
+# - Checkpoint validation (cross-session drift)
+# - WheelHub auto-start
+# - OTEL auto-configuration
+#
+# Input (stdin): JSON with session_id, source, cwd, etc.
+# Output: Writes to CLAUDE_ENV_FILE
 
 set -euo pipefail
 
-# Load shared functions
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-source "$SCRIPT_DIR/../lib/checkpoint.sh"
-
-# Read input from stdin (contains session_id, source, cwd, etc.)
-input=$(cat)
-session_id=$(echo "$input" | jq -r '.session_id // "unknown"')
-source_type=$(echo "$input" | jq -r '.source // "unknown"')
-
-# Ensure .session directory exists
-mkdir -p "$CLAUDE_PROJECT_DIR/.session"
-mkdir -p "$CLAUDE_PROJECT_DIR/.session/agents"
-
-# Note: Agent cleanup is handled by agent-session.sh (7-day TTL) to preserve multi-session state
-# DO NOT clear .session/agents/* here - it breaks parallel sessions
-
-# Create session log entry
-echo "$(date -Iseconds) | Session $source_type: $session_id" >> "$CLAUDE_PROJECT_DIR/.session/session-log.txt"
-
-# Validate previous session checkpoint (cross-session continuity)
-validate_checkpoint() {
-    local prev_state
-    prev_state=$(checkpoint_restore "session_state")
-
-    if [[ -z "$prev_state" ]]; then
-        # No previous checkpoint - fresh start
-        return 0
-    fi
-
-    # Parse checkpoint data (format: key=value;key=value;...)
-    local prev_sha prev_agent prev_story prev_phase prev_session
-    prev_sha=$(echo "$prev_state" | tr ';' '\n' | grep '^sha=' | cut -d= -f2)
-    prev_agent=$(echo "$prev_state" | tr ';' '\n' | grep '^agent=' | cut -d= -f2)
-    prev_story=$(echo "$prev_state" | tr ';' '\n' | grep '^story=' | cut -d= -f2)
-    prev_phase=$(echo "$prev_state" | tr ';' '\n' | grep '^phase=' | cut -d= -f2)
-    prev_session=$(echo "$prev_state" | tr ';' '\n' | grep '^session=' | cut -d= -f2)
-
-    # Get current git SHA
-    local current_sha=""
-    if command -v git &>/dev/null && git rev-parse --git-dir &>/dev/null; then
-        current_sha=$(git rev-parse --short HEAD 2>/dev/null || echo "")
-    fi
-
-    # Compare git state
-    if [[ -n "$prev_sha" && -n "$current_sha" && "$prev_sha" != "$current_sha" ]]; then
-        # Git state changed between sessions - write warning to session log
-        local warning="CROSS_SESSION_DRIFT: Git changed since last session (was: $prev_sha, now: $current_sha)"
-        if [[ -n "$prev_story" ]]; then
-            warning="$warning | Story: $prev_story"
-        fi
-        if [[ -n "$prev_agent" ]]; then
-            warning="$warning | Agent: $prev_agent"
-        fi
-        echo "$(date -Iseconds) | $warning" >> "$CLAUDE_PROJECT_DIR/.session/session-log.txt"
-
-        # Also write to a dedicated drift log for easy scanning
-        echo "$(date -Iseconds) | prev_sha=$prev_sha | current_sha=$current_sha | story=$prev_story | agent=$prev_agent | phase=$prev_phase" >> "$CLAUDE_PROJECT_DIR/.session/drift-log.txt"
-    fi
-}
-
-# Run checkpoint validation (don't fail if it errors)
-validate_checkpoint 2>/dev/null || true
-
-# Write environment variables to CLAUDE_ENV_FILE (persists for session)
-if [ -n "${CLAUDE_ENV_FILE:-}" ]; then
-    cat >> "$CLAUDE_ENV_FILE" << EOF
-# Pennyfarthing core environment
-export PROJECT_ROOT="$CLAUDE_PROJECT_DIR"
-export SESSION_ID="$session_id"
-EOF
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+source "$SCRIPT_DIR/../lib/find-root.sh"
+
+# Set PYTHONPATH for pennyfarthing_scripts
+PENNYFARTHING_SCRIPTS=""
+if [[ -d "$PROJECT_ROOT/pennyfarthing" ]]; then
+    # Dogfooding: framework inlined in orchestrator
+    PENNYFARTHING_SCRIPTS="$PROJECT_ROOT/pennyfarthing"
+elif [[ -d "$PROJECT_ROOT/node_modules/@pennyfarthing/core" ]]; then
+    # Normal install
+    PENNYFARTHING_SCRIPTS="$PROJECT_ROOT/node_modules/@pennyfarthing/core"
+fi
 
-    # Auto-configure OTEL if Cyclist is running (Story 20-1)
-    PORT_FILE="$CLAUDE_PROJECT_DIR/.cyclist-port"
-    if [[ -f "$PORT_FILE" ]]; then
-        CYCLIST_PORT=$(cat "$PORT_FILE" 2>/dev/null)
-        if [[ "$CYCLIST_PORT" =~ ^[0-9]+$ ]]; then
-            cat >> "$CLAUDE_ENV_FILE" << EOF
-# OTEL auto-configuration for Cyclist (Story 20-1)
-export OTEL_EXPORTER_OTLP_PROTOCOL="http/json"
-export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:$CYCLIST_PORT"
-EOF
-        fi
-    fi
+if [[ -n "$PENNYFARTHING_SCRIPTS" ]]; then
+    export PYTHONPATH="$PENNYFARTHING_SCRIPTS:${PYTHONPATH:-}"
 fi
 
-exit 0
+python3 -m pennyfarthing_scripts.session_start_hook

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

@@ -32,5 +32,5 @@ Core logic lives in `pennyfarthing_scripts/jira/`:
 
 ## Ownership
 
-- **Primary users:** SM agent, `/jira` skill
+- **Primary users:** SM agent, `/pf-jira` skill
 - **Maintained by:** Core Pennyfarthing team

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

@@ -2,16 +2,18 @@
 """
 Individual Portrait Generator for Pennyfarthing Themes
 
-Generates 10 individual portraits per theme using Stable Diffusion SDXL on M3 Max (MPS).
-Reads visual prompts from theme YAML files in two locations:
-  - Built-in: pennyfarthing-dist/personas/themes/
-  - Custom:   .claude/pennyfarthing/themes/ (takes precedence)
+Generates individual portraits per theme using Stable Diffusion SDXL on M3 Max (MPS).
+Reads visual prompts from theme YAML files in three locations:
+  - Package:  packages/themes-*/themes/ (output to packages/themes-*/portraits/)
+  - Built-in: pennyfarthing-dist/personas/themes/ (output to pennyfarthing-dist/personas/portraits/)
+  - Custom:   .claude/pennyfarthing/themes/ (takes precedence, output to built-in portraits dir)
 
-Output: pennyfarthing-dist/personas/portraits/{theme}/{slug}-{OCEAN}.png (512x512px each)
+Output: {portraits-dir}/{theme}/{slug}-{OCEAN}.png (512x512px each)
 
 Usage:
     python3 scripts/generate-portraits.py [--dry-run] [--theme THEME]
     python3 scripts/generate-portraits.py --theme gilligans-island --dry-run
+    python3 scripts/generate-portraits.py --role ba --skip-existing
 """
 
 import argparse
@@ -77,7 +79,8 @@ def _find_project_root() -> Path:
 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"
+BUILTIN_OUTPUT_DIR = PROJECT_ROOT / "pennyfarthing-dist" / "personas" / "portraits"
+PACKAGES_DIR = PROJECT_ROOT / "packages"
 MODEL_ID = "stabilityai/stable-diffusion-xl-base-1.0"
 
 # SDXL generates at 1024x1024, we'll resize to 512x512
@@ -272,46 +275,64 @@ def main():
     parser.add_argument("--output-dir", type=str, help="Output to different directory (default: pennyfarthing-dist/personas/portraits)")
     args = parser.parse_args()
 
-    # Determine output directory
-    output_base = Path(args.output_dir) if args.output_dir else OUTPUT_DIR
-
-    # Find theme files from both built-in and custom directories
-    # Custom themes take precedence over built-in themes with same name
-    theme_map = {}
-
-    # First add built-in themes
+    # Determine output directory override
+    output_override = Path(args.output_dir) if args.output_dir else None
+
+    # Find theme files from package, built-in, and custom directories
+    # Each entry tracks its own output directory
+    # Priority: custom > built-in > package (later entries override earlier)
+    theme_map: dict[str, dict] = {}
+
+    # 1. Package themes (packages/themes-*/themes/ -> packages/themes-*/portraits/)
+    pkg_sources = []
+    if PACKAGES_DIR.exists():
+        for pkg_dir in sorted(PACKAGES_DIR.glob("themes-*")):
+            themes_dir = pkg_dir / "themes"
+            portraits_dir = pkg_dir / "portraits"
+            if themes_dir.exists():
+                pkg_sources.append(themes_dir)
+                for tf in themes_dir.glob("*.yaml"):
+                    theme_map[tf.stem] = {"path": tf, "output_dir": portraits_dir}
+
+    # 2. Built-in themes (override packages if same name)
     if BUILTIN_THEMES_DIR.exists():
         for tf in BUILTIN_THEMES_DIR.glob("*.yaml"):
-            theme_map[tf.stem] = tf
+            theme_map[tf.stem] = {"path": tf, "output_dir": BUILTIN_OUTPUT_DIR}
 
-    # Then add/override with custom themes
+    # 3. Custom themes (override everything)
     if CUSTOM_THEMES_DIR.exists():
         for tf in CUSTOM_THEMES_DIR.glob("*.yaml"):
-            theme_map[tf.stem] = tf
+            theme_map[tf.stem] = {"path": tf, "output_dir": BUILTIN_OUTPUT_DIR}
 
-    theme_files = sorted(theme_map.values(), key=lambda p: p.stem)
+    theme_entries = sorted(theme_map.values(), key=lambda e: e["path"].stem)
 
     if args.theme:
         if args.theme in theme_map:
-            theme_files = [theme_map[args.theme]]
+            theme_entries = [theme_map[args.theme]]
         else:
             print(f"Theme '{args.theme}' not found")
             print(f"  Searched: {BUILTIN_THEMES_DIR}")
+            for src in pkg_sources:
+                print(f"  Searched: {src}")
             print(f"  Searched: {CUSTOM_THEMES_DIR}")
             sys.exit(1)
 
     print(f"Theme sources:")
     print(f"  Built-in: {BUILTIN_THEMES_DIR}")
+    for src in pkg_sources:
+        print(f"  Package:  {src}")
     print(f"  Custom:   {CUSTOM_THEMES_DIR}")
-    print(f"Found {len(theme_files)} themes")
-    print(f"Output: {output_base}/{{theme}}/{{slug}}-{{OCEAN}}.png")
+    print(f"Found {len(theme_entries)} themes")
 
     if args.dry_run:
         print(f"\nCLIP token limit: {CLIP_MAX_TOKENS} tokens")
         print(f"Tokenizer: {'CLIP (accurate)' if HAS_CLIP_TOKENIZER else 'word estimate (fallback)'}")
-        print("\nDry run - portraits to generate:")
+        roles_to_show = [args.role] if args.role else ROLES
+        print(f"\nDry run - portraits to generate (roles: {', '.join(roles_to_show)}):")
         truncation_warnings = []
-        for tf in theme_files:
+        for entry in theme_entries:
+            tf = entry["path"]
+            output_base = output_override or entry["output_dir"]
             parsed = parse_theme_file(tf)
             theme_dir = output_base / parsed["theme"]
             char_count = len(parsed["characters"])
@@ -319,7 +340,8 @@ def main():
             style_display = style_desc if style_desc else "(default woodcut)"
             print(f"\n  {parsed['theme']}/ ({char_count} characters with visual)")
             print(f"    Style: {style_display}")
-            for role in ROLES:
+            print(f"    Output: {output_base}")
+            for role in roles_to_show:
                 if role in parsed["characters"]:
                     char = parsed["characters"][role]
                     out_path = theme_dir / char["filename"]
@@ -362,8 +384,10 @@ def main():
     truncated = []
     start_time = datetime.now()
 
-    total_themes = len(theme_files)
-    for theme_idx, tf in enumerate(theme_files, 1):
+    total_themes = len(theme_entries)
+    for theme_idx, entry in enumerate(theme_entries, 1):
+        tf = entry["path"]
+        output_base = output_override or entry["output_dir"]
         parsed = parse_theme_file(tf)
         theme = parsed["theme"]
         theme_dir = output_base / theme