@pennyfarthing/core 7.0.2 → 7.4.1

package/pennyfarthing-dist/scripts/theme/compute-theme-tiers.sh

@@ -0,0 +1,203 @@
+#!/usr/bin/env bash
+# compute-theme-tiers.sh - Compute tier rankings from job-fair results and update theme files
+#
+# Usage: compute-theme-tiers.sh [--dry-run] [--verbose]
+#
+# Reads all summary.yaml files from internal/results/job-fair/
+# For each theme, extracts all character×role scores from the matrix
+# Computes delta vs baseline for each role, then averages across all roles
+# Assigns tier based on overall performance vs control baseline
+#
+# Tier criteria (based on mean delta from control):
+#   S: delta >= +10 (elite - consistently beats control)
+#   A: delta >= 0   (excellent - matches or beats control)
+#   B: delta >= -10 (strong - slightly below control)
+#   C: delta >= -20 (good - notably below control)
+#   D: delta < -20  (below average)
+#   U: no data      (unbenchmarked)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+JOB_FAIR_DIR="$PROJECT_ROOT/internal/results/job-fair"
+THEMES_DIR="$PROJECT_ROOT/pennyfarthing-dist/personas/themes"
+
+DRY_RUN=false
+VERBOSE=false
+
+for arg in "$@"; do
+    case $arg in
+        --dry-run) DRY_RUN=true ;;
+        --verbose) VERBOSE=true ;;
+    esac
+done
+
+if [[ "$DRY_RUN" == "true" ]]; then
+    echo "DRY RUN - no changes will be made"
+    echo ""
+fi
+
+# Check dependencies
+if ! command -v yq &> /dev/null; then
+    echo "Error: yq is required but not installed"
+    exit 1
+fi
+
+# Temporary files for aggregation
+THEME_DATA=$(mktemp)
+THEME_AGG=$(mktemp)
+trap "rm -f $THEME_DATA $THEME_AGG" EXIT
+
+# Process all job-fair summary.yaml files
+# Extract theme name, compute mean score and delta vs baselines
+echo "Scanning job-fair results..."
+
+find "$JOB_FAIR_DIR" -name "summary.yaml" -type f | while read -r f; do
+    theme=$(yq '.theme' "$f" 2>/dev/null | grep -v "^null$" || true)
+    [[ -z "$theme" ]] && continue
+
+    # Extract baselines as "role:mean" pairs
+    baselines=$(yq '.baselines | to_entries | .[] | .key + ":" + (.value.mean | tostring)' "$f" 2>/dev/null || true)
+    [[ -z "$baselines" ]] && continue
+
+    # Extract all matrix scores as "role:mean" pairs (flatten character dimension)
+    # Matrix format: character: { role: {mean: X, n: Y} }
+    scores=$(yq '.matrix | to_entries | .[] | .value | to_entries | .[] | .key + ":" + (.value.mean | tostring)' "$f" 2>/dev/null || true)
+    [[ -z "$scores" ]] && continue
+
+    # Use awk to compute per-role averages and deltas, then overall mean
+    echo "$theme" "$(echo "$baselines" | tr '\n' '|')" "$(echo "$scores" | tr '\n' '|')"
+done | awk '
+{
+    theme = $1
+
+    # Parse baselines (field 2)
+    n_base = split($2, base_pairs, "|")
+    for (i = 1; i <= n_base; i++) {
+        if (base_pairs[i] == "") continue
+        split(base_pairs[i], kv, ":")
+        baseline[kv[1]] = kv[2]
+    }
+
+    # Parse scores (field 3) and accumulate by role
+    delete role_sum
+    delete role_count
+    n_scores = split($3, score_pairs, "|")
+    for (i = 1; i <= n_scores; i++) {
+        if (score_pairs[i] == "") continue
+        split(score_pairs[i], kv, ":")
+        role = kv[1]
+        score = kv[2]
+        role_sum[role] += score
+        role_count[role]++
+    }
+
+    # Compute delta for each role, then average
+    total_delta = 0
+    total_score = 0
+    n_roles = 0
+    for (role in role_sum) {
+        role_mean = role_sum[role] / role_count[role]
+        if (role in baseline) {
+            delta = role_mean - baseline[role]
+            total_delta += delta
+            total_score += role_mean
+            n_roles++
+        }
+    }
+
+    if (n_roles > 0) {
+        mean_delta = total_delta / n_roles
+        mean_score = total_score / n_roles
+        print theme, n_scores, mean_score, mean_delta
+    }
+}
+' > "$THEME_DATA"
+
+summary_count=$(wc -l < "$THEME_DATA" | tr -d ' ')
+echo "Found $summary_count themes with job-fair results"
+echo ""
+
+# Aggregate by theme (in case multiple job-fair runs exist for same theme)
+# Take the most recent (last) result for each theme
+awk '
+{
+    theme = $1
+    n = $2
+    score = $3
+    delta = $4
+    # Keep last occurrence (most recent)
+    data[theme] = n "|" score "|" delta
+}
+END {
+    for (theme in data) {
+        split(data[theme], parts, "|")
+        n = parts[1]
+        score = parts[2]
+        delta = parts[3]
+
+        # Assign tier based on mean delta
+        if (delta >= 10) tier = "S"
+        else if (delta >= 0) tier = "A"
+        else if (delta >= -10) tier = "B"
+        else if (delta >= -20) tier = "C"
+        else tier = "D"
+
+        printf "%s|%d|%.2f|%.2f|%s\n", theme, n, score, delta, tier
+    }
+}
+' "$THEME_DATA" | sort -t'|' -k4 -rn > "$THEME_AGG"
+
+# Print results
+echo "Theme Performance Summary"
+echo "========================="
+echo ""
+printf "%-25s %6s %8s %8s %4s\n" "Theme" "Runs" "Mean" "Delta" "Tier"
+printf "%-25s %6s %8s %8s %4s\n" "-------------------------" "------" "--------" "--------" "----"
+
+updated=0
+unchanged=0
+
+while IFS='|' read -r theme n score delta tier; do
+    printf "%-25s %6d %8.2f %+8.2f %4s\n" "$theme" "$n" "$score" "$delta" "$tier"
+
+    # Update theme file
+    theme_file="$THEMES_DIR/${theme}.yaml"
+    if [[ -f "$theme_file" ]]; then
+        current_tier=$(grep -E "^  tier:" "$theme_file" 2>/dev/null | sed 's/.*tier:[[:space:]]*//' || echo "U")
+
+        if [[ "$current_tier" != "$tier" ]]; then
+            if [[ "$DRY_RUN" == "true" ]]; then
+                [[ "$VERBOSE" == "true" ]] && echo "  Would update: $current_tier → $tier"
+            else
+                sed -i '' "s/^  tier:.*/  tier: $tier/" "$theme_file"
+                [[ "$VERBOSE" == "true" ]] && echo "  Updated: $current_tier → $tier"
+            fi
+            updated=$((updated + 1))
+        else
+            unchanged=$((unchanged + 1))
+        fi
+    else
+        [[ "$VERBOSE" == "true" ]] && echo "  Warning: No theme file for $theme"
+    fi
+done < "$THEME_AGG"
+
+echo ""
+
+# Count themes by tier
+echo "Tier Distribution:"
+for t in S A B C D; do
+    count=$(grep -c "|$t$" "$THEME_AGG" 2>/dev/null || echo 0)
+    echo "  $t: $count themes"
+done
+
+# Count unbenchmarked themes
+benchmarked=$(wc -l < "$THEME_AGG" | tr -d ' ')
+total_themes=$(ls "$THEMES_DIR"/*.yaml 2>/dev/null | wc -l | tr -d ' ')
+unbenchmarked=$((total_themes - benchmarked))
+echo "  U: $unbenchmarked themes (unbenchmarked)"
+
+echo ""
+echo "Summary: $updated updated, $unchanged unchanged"

package/pennyfarthing-dist/scripts/theme/list-themes.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# list-themes.sh - List all available persona themes
+#
+# Usage: list-themes.sh [--current-only]
+#
+# Options:
+#   --current-only  Only show the current theme name
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+THEMES_DIR="$PROJECT_ROOT/pennyfarthing-dist/personas/themes"
+CONFIG_FILE="$PROJECT_ROOT/.pennyfarthing/config.local.yaml"
+
+# Get current theme from config
+get_current_theme() {
+    if [[ -f "$CONFIG_FILE" ]]; then
+        grep -E "^theme:" "$CONFIG_FILE" 2>/dev/null | sed 's/theme:[[:space:]]*//' || echo ""
+    else
+        echo ""
+    fi
+}
+
+CURRENT_THEME=$(get_current_theme)
+
+# Handle --current-only flag
+if [[ "${1:-}" == "--current-only" ]]; then
+    if [[ -n "$CURRENT_THEME" ]]; then
+        echo "$CURRENT_THEME"
+    else
+        echo "No theme set"
+        exit 1
+    fi
+    exit 0
+fi
+
+# Extract all theme data in one grep + format with awk (fast path)
+# Single grep call across all files, awk handles formatting
+grep -H "^  tier:" "$THEMES_DIR"/*.yaml 2>/dev/null | \
+    sed 's|.*/||; s|\.yaml:.*tier:[[:space:]]*| |' | \
+    sort | \
+    awk -v current="$CURRENT_THEME" '
+    {
+        theme = $1
+        tier = $2 ? $2 : "U"
+        if (theme == current) {
+            themes[NR] = "*" theme " [" tier "]"
+        } else {
+            themes[NR] = theme " [" tier "]"
+        }
+        count++
+    }
+    END {
+        # Print header
+        print "**" count " themes available.** Current: **" (current ? current : "none") "**"
+        print ""
+
+        # Print in 3 columns
+        col_width = 28
+        col = 0
+        for (i = 1; i <= count; i++) {
+            printf "%-" col_width "s", themes[i]
+            col++
+            if (col == 3) {
+                print ""
+                col = 0
+            }
+        }
+        if (col > 0) print ""
+    }
+'

package/pennyfarthing-dist/scripts/theme/update-theme-tiers.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env zsh
+# update-theme-tiers.sh - Update tier field in theme YAML files based on THEME-TIERS.md
+#
+# Usage: update-theme-tiers.sh [--dry-run]
+
+set -euo pipefail
+
+SCRIPT_DIR="${0:A:h}"
+PROJECT_ROOT="${SCRIPT_DIR:h:h}"
+
+THEMES_DIR="$PROJECT_ROOT/pennyfarthing-dist/personas/themes"
+TIERS_DOC="$PROJECT_ROOT/docs/THEME-TIERS.md"
+
+DRY_RUN=false
+if [[ "${1:-}" == "--dry-run" ]]; then
+    DRY_RUN=true
+    echo "DRY RUN - no changes will be made"
+    echo ""
+fi
+
+# Extract theme-to-tier mapping from THEME-TIERS.md
+typeset -A TIER_MAP
+
+current_tier=""
+while IFS= read -r line; do
+    # Detect tier section headers
+    if [[ "$line" =~ "^## S-Tier" ]]; then
+        current_tier="S"
+    elif [[ "$line" =~ "^## A-Tier" ]]; then
+        current_tier="A"
+    elif [[ "$line" =~ "^## B-Tier" ]]; then
+        current_tier="B"
+    elif [[ "$line" =~ "^## C-Tier" ]]; then
+        current_tier="C"
+    elif [[ "$line" =~ "^## D-Tier" ]]; then
+        current_tier="D"
+    elif [[ "$line" =~ "^## U-Tier" ]]; then
+        current_tier="U"
+    elif [[ "$line" =~ "^## (Role-by-Role|Recommendations|OCEAN|Data|See)" ]]; then
+        # Stop parsing at these sections
+        break
+    fi
+
+    # Extract theme names from table rows (| **theme** | or | theme |)
+    if [[ -n "$current_tier" && "$line" =~ '^\|[[:space:]]*\*?\*?([a-z0-9-]+)\*?\*?[[:space:]]*\|' ]]; then
+        theme_name="${match[1]}"
+        # Skip header rows
+        if [[ "$theme_name" != "Theme" && "$theme_name" != "---" ]]; then
+            TIER_MAP[$theme_name]="$current_tier"
+        fi
+    fi
+done < "$TIERS_DOC"
+
+echo "Parsed ${#TIER_MAP[@]} theme tiers from THEME-TIERS.md"
+echo ""
+
+# Update each theme file
+updated=0
+skipped=0
+unchanged=0
+
+for theme_file in "$THEMES_DIR"/*.yaml; do
+    [[ -f "$theme_file" ]] || continue
+
+    theme_name="${theme_file:t:r}"
+    new_tier="${TIER_MAP[$theme_name]:-U}"  # Default to U (unbenchmarked) if not found
+
+    # Get current tier from file
+    current_tier=$(grep -E "^  tier:" "$theme_file" 2>/dev/null | sed 's/.*tier:[[:space:]]*//' || echo "")
+
+    if [[ "$current_tier" == "$new_tier" ]]; then
+        unchanged=$((unchanged + 1))
+        continue
+    fi
+
+    if [[ "$DRY_RUN" == "true" ]]; then
+        echo "Would update $theme_name: ${current_tier:-<none>} → $new_tier"
+        updated=$((updated + 1))
+    else
+        # Use sed to update the tier field
+        if [[ -n "$current_tier" ]]; then
+            sed -i '' "s/^  tier:.*/  tier: $new_tier/" "$theme_file"
+        else
+            # Add tier field after user_title line
+            sed -i '' "/^  user_title:/a\\
+  tier: $new_tier" "$theme_file"
+        fi
+        echo "Updated $theme_name: ${current_tier:-<none>} → $new_tier"
+        updated=$((updated + 1))
+    fi
+done
+
+echo ""
+echo "Summary:"
+echo "  Updated: $updated"
+echo "  Unchanged: $unchanged"
+echo "  Skipped: $skipped"

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

@@ -0,0 +1,28 @@
+# Workflow Scripts
+
+Scripts for workflow mechanics, phase transitions, and quality gates.
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `finish-story.sh` | Story completion workflow (archive, PR merge, Jira transition) |
+| `fix-session-phase.sh` | Repair session file phase state |
+| `check.sh` | Quality gates runner (lint, type check, tests) |
+| `list-workflows.sh` | List available workflows |
+| `show-workflow.sh` | Show workflow details |
+| `start-workflow.sh` | Start a stepped workflow |
+| `resume-workflow.sh` | Resume from last completed step |
+| `workflow-status.sh` | Show workflow progress |
+
+## Usage
+
+```bash
+.pennyfarthing/scripts/core/run.sh workflow/finish-story.sh MSSCI-12345
+.pennyfarthing/scripts/core/run.sh workflow/start-workflow.sh prd --mode create
+```
+
+## Ownership
+
+- **Primary users:** SM agent, `/workflow` skill
+- **Maintained by:** Core Pennyfarthing team

package/pennyfarthing-dist/scripts/workflow/finish-story.sh

@@ -0,0 +1,159 @@
+#!/bin/bash
+# Finish a story: archive, merge PR, transition Jira, update sprint YAML
+# Usage: finish-story.sh <story-id> [--dry-run]
+#
+# Example: finish-story.sh MSSCI-12052
+#          finish-story.sh MSSCI-12052 --dry-run
+#
+# Prerequisites:
+# - Session file exists at .session/{story-id}-session.md
+# - PR is approved and mergeable
+# - Reviewer has approved (phase: finish in session)
+#
+# This script performs:
+# 1. Archive session file to sprint/archive/{jira-key}-session.md
+# 2. Squash merge PR and delete remote branch
+# 3. Transition Jira to Done
+# 4. Update sprint YAML (status: done, completed date)
+# 5. Clean up local branch and session file
+
+set -euo pipefail
+
+STORY_ID="${1:-}"
+DRY_RUN=false
+
+# Parse options
+for arg in "$@"; do
+  case $arg in
+    --dry-run)
+      DRY_RUN=true
+      shift
+      ;;
+  esac
+done
+
+if [[ -z "$STORY_ID" ]]; then
+  echo "Usage: finish-story.sh <story-id> [--dry-run]"
+  echo ""
+  echo "Options:"
+  echo "  --dry-run    Show what would be done without executing"
+  exit 1
+fi
+
+# PROJECT_ROOT should be set by run.sh, but find it if not
+if [[ -z "${PROJECT_ROOT:-}" ]]; then
+  d="$PWD"
+  while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do
+    d="$(dirname "$d")"
+  done
+  PROJECT_ROOT="$d"
+fi
+
+SESSION_FILE="$PROJECT_ROOT/.session/${STORY_ID}-session.md"
+SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
+ARCHIVE_DIR="$PROJECT_ROOT/sprint/archive"
+
+# Ensure archive directory exists
+mkdir -p "$ARCHIVE_DIR"
+
+# Validate session file exists
+if [[ ! -f "$SESSION_FILE" ]]; then
+  echo "Error: Session file not found: $SESSION_FILE"
+  exit 1
+fi
+
+# Extract metadata from session file (handle both "**Jira:**" and "- **Jira:**" formats)
+JIRA_KEY=$(grep -E '\*\*Jira:\*\*' "$SESSION_FILE" | sed 's/.*\*\*Jira:\*\* //' | tr -d ' ' || echo "")
+# Extract branch - strip any trailing annotations like "(pushed)"
+BRANCH=$(grep -E '\*\*Branch:\*\*' "$SESSION_FILE" | sed 's/.*\*\*Branch:\*\* //' | sed 's/ *(.*//' | tr -d ' ' || echo "")
+
+# Try to get PR number from session file first (format: **PR:** #422 - title)
+PR_NUMBER=$(grep -E '\*\*PR:\*\*' "$SESSION_FILE" | sed 's/.*#\([0-9]*\).*/\1/' || echo "")
+
+# Fallback: try to get Jira key from sprint YAML if not in session
+if [[ -z "$JIRA_KEY" || "$JIRA_KEY" == "null" ]]; then
+  JIRA_KEY=$(yq ".epics[].stories[] | select(.id == \"$STORY_ID\") | .jira // \"\"" "$SPRINT_FILE" 2>/dev/null | head -1 || echo "")
+fi
+
+if [[ -z "$JIRA_KEY" || "$JIRA_KEY" == "null" ]]; then
+  echo "Error: Could not determine Jira key for story $STORY_ID"
+  echo "Check session file or sprint YAML for jira: field"
+  exit 1
+fi
+
+# Fallback: get PR number from GitHub if not in session file
+if [[ -z "$PR_NUMBER" ]] && [[ -n "$BRANCH" ]]; then
+  PR_NUMBER=$(gh pr list --head "$BRANCH" --json number --jq '.[0].number' 2>/dev/null || echo "")
+fi
+
+TODAY=$(date +%Y-%m-%d)
+
+echo "=== Finish Story: $STORY_ID ==="
+echo "Jira Key: $JIRA_KEY"
+echo "Branch: ${BRANCH:-none}"
+echo "PR: ${PR_NUMBER:-none}"
+echo ""
+
+if $DRY_RUN; then
+  echo "[DRY RUN] Would perform:"
+  echo "  1. Archive session → $ARCHIVE_DIR/${JIRA_KEY}-session.md"
+  if [[ -n "$PR_NUMBER" ]]; then
+    echo "  2. Merge PR #$PR_NUMBER (squash, delete branch)"
+  else
+    echo "  2. No PR to merge"
+  fi
+  echo "  3. Transition $JIRA_KEY to Done"
+  echo "  4. Update sprint YAML (status: done, completed: $TODAY)"
+  echo "  5. Delete local branch: $BRANCH"
+  echo "  6. Remove session file"
+  exit 0
+fi
+
+# Step 1: Archive session file
+echo "1. Archiving session file..."
+cp "$SESSION_FILE" "$ARCHIVE_DIR/${JIRA_KEY}-session.md"
+echo "   → $ARCHIVE_DIR/${JIRA_KEY}-session.md"
+
+# Step 2: Merge PR (if exists)
+if [[ -n "$PR_NUMBER" ]]; then
+  echo "2. Merging PR #$PR_NUMBER..."
+  gh pr merge "$PR_NUMBER" --squash --delete-branch || {
+    echo "   Warning: PR merge failed (may already be merged)"
+  }
+else
+  echo "2. No PR found for branch $BRANCH (skipping merge)"
+fi
+
+# Step 3: Transition Jira to Done
+echo "3. Transitioning Jira to Done..."
+jira issue move "$JIRA_KEY" "Done" 2>/dev/null || {
+  echo "   Warning: Jira transition failed (may already be Done)"
+}
+
+# Step 4: Update sprint YAML
+echo "4. Updating sprint YAML..."
+# Update status to done
+yq eval -i "(.epics[].stories[] | select(.id == \"$STORY_ID\")).status = \"done\"" "$SPRINT_FILE"
+# Add completed date
+yq eval -i "(.epics[].stories[] | select(.id == \"$STORY_ID\")).completed = \"$TODAY\"" "$SPRINT_FILE"
+# Remove assigned_to (no longer in progress)
+yq eval -i "del((.epics[].stories[] | select(.id == \"$STORY_ID\")).assigned_to)" "$SPRINT_FILE"
+echo "   → status: done, completed: $TODAY"
+
+# Step 5: Clean up git
+echo "5. Cleaning up git..."
+git checkout develop 2>/dev/null || git checkout main 2>/dev/null || true
+git pull origin "$(git branch --show-current)" 2>/dev/null || true
+
+if [[ -n "$BRANCH" ]]; then
+  git branch -d "$BRANCH" 2>/dev/null || echo "   Local branch already deleted"
+fi
+
+# Step 6: Remove session file
+echo "6. Removing session file..."
+rm "$SESSION_FILE"
+
+echo ""
+echo "=== Story $STORY_ID Complete ==="
+echo "Archived: sprint/archive/${JIRA_KEY}-session.md"
+echo "Jira: https://1898andco.atlassian.net/browse/$JIRA_KEY"