@pennyfarthing/core 7.0.2 → 7.4.1

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

@@ -0,0 +1,266 @@
+#!/bin/bash
+# Jira vs YAML Reconciliation Report
+# Usage: .pennyfarthing/scripts/core/run.sh jira/jira-reconcile.sh [--fix]
+#
+# Compares sprint YAML against Jira to find:
+# - Status mismatches
+# - Missing Jira keys
+# - Orphan issues (in Jira but not YAML)
+# - Sprint membership discrepancies
+#
+# Options:
+#   --fix    Apply recommended fixes automatically (where safe)
+
+set -euo pipefail
+
+# 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
+
+SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
+FIX_MODE="${1:-}"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Check dependencies
+if ! command -v yq &> /dev/null; then
+  echo "Error: yq is required but not installed"
+  echo "Install with: brew install yq"
+  exit 1
+fi
+
+if ! command -v jira &> /dev/null; then
+  echo "Error: jira CLI is required but not installed"
+  echo "Install with: brew install ankitpokhrel/jira/jira"
+  exit 1
+fi
+
+if [[ ! -f "$SPRINT_FILE" ]]; then
+  echo "Error: Sprint file not found at $SPRINT_FILE"
+  exit 1
+fi
+
+# Get sprint info
+SPRINT_NAME=$(yq eval '.sprint.name' "$SPRINT_FILE")
+SPRINT_ID=$(yq eval '.sprint.jira_sprint_id' "$SPRINT_FILE")
+
+echo "# Jira vs YAML Reconciliation Report"
+echo ""
+echo "**Sprint:** $SPRINT_NAME (Jira Sprint ID: $SPRINT_ID)"
+echo "**Generated:** $(date '+%Y-%m-%d %H:%M')"
+echo ""
+
+# Track issues
+STATUS_MISMATCHES=()
+MISSING_JIRA=()
+ORPHAN_ISSUES=()
+NOT_IN_SPRINT=()
+
+echo "## Checking YAML Stories Against Jira..."
+echo ""
+
+# Extract all stories from YAML and check against Jira
+while IFS=$'\t' read -r yaml_id jira_key yaml_status title; do
+  # Skip if no jira key
+  if [[ "$jira_key" == "null" ]] || [[ -z "$jira_key" ]]; then
+    MISSING_JIRA+=("$yaml_id|$title|$yaml_status")
+    continue
+  fi
+
+  # Get Jira status - use sed to remove the key prefix
+  jira_status=$(jira issue list --jql "project=MSSCI AND key=$jira_key" --plain --columns key,status --no-headers 2>/dev/null | sed "s/^$jira_key[[:space:]]*//" | xargs || echo "NOT_FOUND")
+
+  if [[ "$jira_status" == "NOT_FOUND" ]] || [[ -z "$jira_status" ]]; then
+    echo -e "${RED}[!]${NC} $jira_key not found in Jira"
+    continue
+  fi
+
+  # Normalize statuses for comparison
+  jira_norm=$(echo "$jira_status" | tr '[:upper:]' '[:lower:]' | tr ' ' '_')
+
+  # Check for mismatches
+  mismatch=false
+  case "$yaml_status" in
+    done)
+      [[ "$jira_norm" != "done" ]] && mismatch=true
+      ;;
+    ready|backlog)
+      [[ "$jira_norm" != "to_do" ]] && mismatch=true
+      ;;
+    in_progress)
+      [[ "$jira_norm" != "in_progress" ]] && mismatch=true
+      ;;
+  esac
+
+  if [[ "$mismatch" == "true" ]]; then
+    STATUS_MISMATCHES+=("$jira_key|$yaml_status|$jira_status")
+  fi
+done < <(yq -r '.epics[].stories[]? | [.id, .jira, .status, .title] | @tsv' "$SPRINT_FILE" 2>/dev/null)
+
+echo ""
+echo "## Checking Jira Sprint Against YAML..."
+echo ""
+
+# Get all issues in the Jira sprint and check if they're in YAML
+# Skip canceled issues - they're not relevant
+while read -r jira_key; do
+  # Check if in YAML (by id or jira field)
+  in_yaml=$(yq -r ".epics[].stories[]? | select(.id == \"$jira_key\" or .jira == \"$jira_key\") | .id" "$SPRINT_FILE" 2>/dev/null | head -1)
+
+  if [[ -z "$in_yaml" ]]; then
+    # Get more info about the orphan
+    status=$(jira issue list --jql "project=MSSCI AND key=$jira_key" --plain --columns key,status --no-headers 2>/dev/null | sed "s/^$jira_key[[:space:]]*//" | xargs || echo "Unknown")
+
+    # Skip canceled issues
+    if [[ "$status" == "Canceled" ]]; then
+      continue
+    fi
+
+    summary=$(jira issue list --jql "project=MSSCI AND key=$jira_key" --plain --columns key,summary --no-headers 2>/dev/null | sed "s/^$jira_key[[:space:]]*//" | xargs || echo "Unknown")
+    ORPHAN_ISSUES+=("$jira_key|$status|$summary")
+  fi
+done < <(jira issue list --jql "project=MSSCI AND labels=pennyfarthing AND sprint=$SPRINT_ID AND status != Canceled" --plain --columns key --no-headers 2>/dev/null)
+
+echo ""
+echo "## Checking for Issues Not in Sprint..."
+echo ""
+
+# Get done issues not in sprint
+while read -r jira_key; do
+  # Check if it should be in current sprint (exists in YAML)
+  in_yaml=$(yq -r ".epics[].stories[]? | select(.id == \"$jira_key\" or .jira == \"$jira_key\") | .id" "$SPRINT_FILE" 2>/dev/null | head -1)
+
+  if [[ -n "$in_yaml" ]]; then
+    summary=$(jira issue list --jql "project=MSSCI AND key=$jira_key" --plain --columns summary --no-headers 2>/dev/null | xargs || echo "Unknown")
+    NOT_IN_SPRINT+=("$jira_key|$summary")
+  fi
+done < <(jira issue list --jql "project=MSSCI AND labels=pennyfarthing AND sprint is EMPTY AND status != Canceled" --plain --columns key --no-headers 2>/dev/null)
+
+# Output Report
+echo ""
+echo "---"
+echo ""
+echo "# Summary"
+echo ""
+
+# Status Mismatches
+echo "## Status Mismatches (${#STATUS_MISMATCHES[@]})"
+echo ""
+if [[ ${#STATUS_MISMATCHES[@]} -eq 0 ]]; then
+  echo -e "${GREEN}No status mismatches found.${NC}"
+else
+  echo "| Jira Key | YAML Status | Jira Status | Action |"
+  echo "|----------|-------------|-------------|--------|"
+  for item in "${STATUS_MISMATCHES[@]}"; do
+    IFS='|' read -r key yaml jira <<< "$item"
+    echo "| $key | $yaml | $jira | Update YAML or Jira |"
+  done
+fi
+echo ""
+
+# Missing Jira Keys
+echo "## YAML Stories Missing Jira Key (${#MISSING_JIRA[@]})"
+echo ""
+if [[ ${#MISSING_JIRA[@]} -eq 0 ]]; then
+  echo -e "${GREEN}All YAML stories have Jira keys.${NC}"
+else
+  echo "| YAML ID | Title | Status | Action |"
+  echo "|---------|-------|--------|--------|"
+  for item in "${MISSING_JIRA[@]}"; do
+    IFS='|' read -r id title status <<< "$item"
+    echo "| $id | ${title:0:40} | $status | Create Jira issue |"
+  done
+fi
+echo ""
+
+# Orphan Issues
+echo "## Jira Issues Not in YAML (${#ORPHAN_ISSUES[@]})"
+echo ""
+if [[ ${#ORPHAN_ISSUES[@]} -eq 0 ]]; then
+  echo -e "${GREEN}All sprint issues are tracked in YAML.${NC}"
+else
+  echo "| Jira Key | Status | Summary | Action |"
+  echo "|----------|--------|---------|--------|"
+  for item in "${ORPHAN_ISSUES[@]}"; do
+    IFS='|' read -r key status summary <<< "$item"
+    if [[ "$status" == "Done" ]]; then
+      echo "| $key | $status | ${summary:0:40} | Info: Completed (not in current YAML) |"
+    else
+      echo "| $key | $status | ${summary:0:40} | Add to YAML or remove from sprint |"
+    fi
+  done
+  echo ""
+  echo "*Note: Done issues not in YAML are historical - they count toward sprint velocity but aren't actively tracked.*"
+fi
+echo ""
+
+# Not in Sprint
+echo "## YAML Stories Not in Jira Sprint (${#NOT_IN_SPRINT[@]})"
+echo ""
+if [[ ${#NOT_IN_SPRINT[@]} -eq 0 ]]; then
+  echo -e "${GREEN}All YAML stories are in Jira sprint.${NC}"
+else
+  echo "| Jira Key | Summary | Action |"
+  echo "|----------|---------|--------|"
+  for item in "${NOT_IN_SPRINT[@]}"; do
+    IFS='|' read -r key summary <<< "$item"
+    echo "| $key | ${summary:0:50} | Add to sprint $SPRINT_ID |"
+  done
+fi
+echo ""
+
+# Epic check
+echo "## Epic Sync Check"
+echo ""
+echo "| YAML Epic ID | Jira Field | Status |"
+echo "|--------------|------------|--------|"
+while IFS=$'\t' read -r epic_id jira_key title; do
+  if [[ "$jira_key" == "null" ]] || [[ -z "$jira_key" ]]; then
+    echo -e "| $epic_id | ${RED}MISSING${NC} | $title |"
+  else
+    echo "| $epic_id | $jira_key | $title |"
+  fi
+done < <(yq -r '.epics[] | [.id, .jira, .title] | @tsv' "$SPRINT_FILE" 2>/dev/null)
+echo ""
+
+# Total counts
+total_issues=$((${#STATUS_MISMATCHES[@]} + ${#MISSING_JIRA[@]} + ${#ORPHAN_ISSUES[@]} + ${#NOT_IN_SPRINT[@]}))
+
+echo "---"
+echo ""
+if [[ $total_issues -eq 0 ]]; then
+  echo -e "${GREEN}Sync Status: CLEAN${NC} - No discrepancies found!"
+else
+  echo -e "${YELLOW}Sync Status: $total_issues issue(s) found${NC}"
+  echo ""
+  echo "Run with --fix to apply automatic fixes where possible."
+fi
+
+# Fix mode
+if [[ "$FIX_MODE" == "--fix" ]]; then
+  echo ""
+  echo "## Applying Fixes..."
+  echo ""
+
+  # Add stories to sprint
+  for item in "${NOT_IN_SPRINT[@]}"; do
+    IFS='|' read -r key summary <<< "$item"
+    echo "Adding $key to sprint $SPRINT_ID..."
+    jira sprint add "$SPRINT_ID" "$key" 2>/dev/null && echo "  Done" || echo "  Failed"
+  done
+
+  echo ""
+  echo "Fix mode completed. Manual review still needed for:"
+  echo "- Status mismatches (requires decision on which source is correct)"
+  echo "- Missing Jira keys (requires creating new issues)"
+  echo "- Orphan issues (requires adding to YAML or removing from sprint)"
+fi

package/pennyfarthing-dist/scripts/{utils/jira → jira}/jira-sync-story.mjs

@@ -5,8 +5,8 @@
  * Usage: node jira-sync-story.mjs <story_key> [--transition] [--points] [--comment "message"]
  *
  * Options:
- *   --transition   Transition story to match Conductor status
- *   --points       Sync story points from Conductor to Jira
+ *   --transition   Transition story to match Pennyfarthing status
+ *   --points       Sync story points from Pennyfarthing to Jira
  *   --comment      Add a comment to the story
  */
 
@@ -93,8 +93,8 @@ if (!story) {
   process.exit(1);
 }
 
-// Get story details from Conductor
-const conductorStatus = story.status || 'backlog';
+// Get story details from Pennyfarthing
+const PennyfarthingStatus = story.status || 'backlog';
 const storyJira = story.jira;
 const storyBranch = story.branch;
 const storyPr = story.pr;
@@ -131,15 +131,15 @@ const jiraPoints = getStoryPoints(jiraKey, issueJson);
 console.log(`   Summary: ${jiraSummary}`);
 console.log(`   Jira Status: ${jiraStatus}`);
 console.log(`   Assignee: ${jiraAssignee}`);
-console.log(`   Conductor Status: ${conductorStatus}`);
-if (storyPoints) console.log(`   Conductor Points: ${storyPoints}`);
+console.log(`   Pennyfarthing Status: ${PennyfarthingStatus}`);
+if (storyPoints) console.log(`   Pennyfarthing Points: ${storyPoints}`);
 if (jiraPoints) console.log(`   Jira Points: ${jiraPoints}`);
 if (storyBranch) console.log(`   Branch: ${storyBranch}`);
 if (storyPr) console.log(`   PR: ${storyPr}`);
 console.log('');
 
-// Map Conductor status to target Jira status
-const targetJiraStatus = mapStatusToJira(conductorStatus);
+// Map Pennyfarthing status to target Jira status
+const targetJiraStatus = mapStatusToJira(PennyfarthingStatus);
 
 // Transition if requested
 if (doTransition) {
@@ -186,13 +186,13 @@ if (commentText) {
 if (doTransition && !commentText) {
   let autoComment = null;
 
-  if (conductorStatus === 'in-progress' && storyBranch) {
-    autoComment = `**Development Started**\n\nBranch: \`${storyBranch}\`\n\nSynced from Conductor`;
-  } else if (conductorStatus === 'review' && storyPr) {
-    autoComment = `**Ready for Review**\n\nPR: ${storyPr}\n\nSynced from Conductor`;
-  } else if (conductorStatus === 'done') {
+  if (PennyfarthingStatus === 'in-progress' && storyBranch) {
+    autoComment = `**Development Started**\n\nBranch: \`${storyBranch}\`\n\nSynced from Pennyfarthing`;
+  } else if (PennyfarthingStatus === 'review' && storyPr) {
+    autoComment = `**Ready for Review**\n\nPR: ${storyPr}\n\nSynced from Pennyfarthing`;
+  } else if (PennyfarthingStatus === 'done') {
     const today = new Date().toISOString().split('T')[0];
-    autoComment = `**Completed**\n\nSynced from Conductor on ${today}`;
+    autoComment = `**Completed**\n\nSynced from Pennyfarthing on ${today}`;
   }
 
   if (autoComment) {

package/pennyfarthing-dist/scripts/{utils/jira → jira}/jira-sync.mjs

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 /**
- * jira-sync.mjs - Sync Conductor Epic to Jira
+ * jira-sync.mjs - Sync Pennyfarthing Epic to Jira
  *
  * Usage: node jira-sync.mjs <epic_number> [--dry-run] [--transition] [--points]
  *
  * Options:
  *   --dry-run      Show what would be done without making changes
- *   --transition   Transition Jira issues to match Conductor status
- *   --points       Sync story points from Conductor to Jira
+ *   --transition   Transition Jira issues to match Pennyfarthing status
+ *   --points       Sync story points from Pennyfarthing to Jira
  */
 
 import {
@@ -154,7 +154,7 @@ for (const story of stories) {
   const targetStatus = mapStatusToJira(storyStatus);
 
   console.log(`  Jira Status: ${jiraStatus} (target: ${targetStatus})`);
-  if (storyPoints) console.log(`  Points: Conductor=${storyPoints}, Jira=${jiraPoints || 'unset'}`);
+  if (storyPoints) console.log(`  Points: Pennyfarthing=${storyPoints}, Jira=${jiraPoints || 'unset'}`);
 
   // Transition if requested
   if (doTransition) {

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

@@ -0,0 +1,104 @@
+#!/bin/bash
+# Sync an epic and its stories to Jira
+# Usage: .pennyfarthing/scripts/core/run.sh sync-epic-jira.sh <epic-id> [--dry-run] [--transition] [--points] [--all]
+#
+# Example: .pennyfarthing/scripts/core/run.sh sync-epic-jira.sh MSSCI-11952
+# Example: .pennyfarthing/scripts/core/run.sh sync-epic-jira.sh MSSCI-11952 --all
+#
+# This script syncs status and story points from sprint YAML to Jira.
+# It wraps the existing jira-sync.mjs for better integration with /sprint skill.
+
+set -euo pipefail
+
+EPIC_ID="${1:-}"
+
+if [[ -z "$EPIC_ID" ]]; then
+  echo "Usage: sync-epic-jira.sh <epic-id> [options]"
+  echo ""
+  echo "Syncs an epic and its stories from sprint YAML to Jira."
+  echo ""
+  echo "Options:"
+  echo "  --dry-run      Show what would be done without making changes"
+  echo "  --transition   Transition Jira issues to match sprint YAML status"
+  echo "  --points       Sync story points from sprint YAML to Jira"
+  echo "  --all          Equivalent to --transition --points"
+  echo ""
+  echo "Examples:"
+  echo "  sync-epic-jira.sh MSSCI-11952              # Show sync status"
+  echo "  sync-epic-jira.sh MSSCI-11952 --dry-run    # Preview changes"
+  echo "  sync-epic-jira.sh MSSCI-11952 --all        # Sync status and points"
+  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
+
+SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
+
+if [[ ! -f "$SPRINT_FILE" ]]; then
+  echo "Error: Sprint file not found at $SPRINT_FILE"
+  exit 1
+fi
+
+if ! command -v yq &> /dev/null; then
+  echo "Error: yq is required but not installed"
+  echo "Install with: brew install yq"
+  exit 1
+fi
+
+# Check if epic exists in sprint YAML
+EPIC_EXISTS=$(yq ".epics[] | select(.id == \"$EPIC_ID\") | .id" "$SPRINT_FILE" 2>/dev/null || echo "")
+
+if [[ -z "$EPIC_EXISTS" ]]; then
+  echo "Error: Epic $EPIC_ID not found in $SPRINT_FILE"
+  echo ""
+  echo "Available epics:"
+  yq '.epics[].id' "$SPRINT_FILE" 2>/dev/null || echo "  None found"
+  exit 1
+fi
+
+# Extract epic number for jira-sync.mjs compatibility
+# jira-sync.mjs expects epic number (e.g., 35) not full ID
+# But it also accepts Jira keys directly
+# Let's check if this is a Jira key (MSSCI-XXXXX) or local ID
+
+# Pass through to jira-sync.mjs with remaining arguments
+JIRA_SYNC_SCRIPT="$PROJECT_ROOT/.pennyfarthing/scripts/utils/jira/jira-sync.mjs"
+
+if [[ ! -f "$JIRA_SYNC_SCRIPT" ]]; then
+  # Try alternate location
+  JIRA_SYNC_SCRIPT="$PROJECT_ROOT/pennyfarthing-dist/scripts/utils/jira/jira-sync.mjs"
+fi
+
+if [[ ! -f "$JIRA_SYNC_SCRIPT" ]]; then
+  echo "Error: jira-sync.mjs not found"
+  exit 1
+fi
+
+# Build arguments for jira-sync.mjs
+shift  # Remove epic-id from arguments
+SYNC_ARGS=("$EPIC_ID")
+
+# Handle --all flag
+for arg in "$@"; do
+  case "$arg" in
+    --all)
+      SYNC_ARGS+=("--transition" "--points")
+      ;;
+    *)
+      SYNC_ARGS+=("$arg")
+      ;;
+  esac
+done
+
+echo "Syncing epic $EPIC_ID to Jira..."
+echo ""
+
+# Run jira-sync.mjs
+exec node "$JIRA_SYNC_SCRIPT" "${SYNC_ARGS[@]}"

package/pennyfarthing-dist/scripts/{utils → jira}/sync-epic-to-jira.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env zsh
-# Sync Conductor Epic to Jira MSSCI Project using jira
+# Sync Pennyfarthing Epic to Jira MSSCI Project using jira
 # Usage: ./scripts/sync-epic-to-jira.sh <epic_number> [--dry-run] [--with-comments]
 #
 # Prerequisites:

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

@@ -0,0 +1,29 @@
+# Library Scripts
+
+Shared bash libraries sourced by other scripts.
+
+## Libraries
+
+| Script | Purpose |
+|--------|---------|
+| `common.sh` | Common utilities (colors, logging basics) |
+| `logging.sh` | Structured logging functions |
+| `retry.sh` | Retry logic with exponential backoff |
+| `checkpoint.sh` | Checkpointing for long-running operations |
+| `file-lock.sh` | File locking utilities |
+| `background-tasks.sh` | Background task management |
+| `find-root.sh` | Project root finder |
+
+## Usage
+
+These are sourced by other scripts, not run directly:
+
+```bash
+source "$SCRIPTS_DIR/lib/common.sh"
+source "$SCRIPTS_DIR/lib/logging.sh"
+```
+
+## Ownership
+
+- **Primary users:** All scripts
+- **Maintained by:** Core Pennyfarthing team

package/pennyfarthing-dist/scripts/{utils → lib}/background-tasks.sh

@@ -2,7 +2,7 @@
 # Background task tracking utilities for session files
 #
 # Usage:
-#   source $CLAUDE_PROJECT_DIR/scripts/utils/background-tasks.sh
+#   source $CLAUDE_PROJECT_DIR/scripts/lib/background-tasks.sh
 #
 # Functions:
 #   bg_task_add <session_file> <task_id> <subagent_type> <description>

package/pennyfarthing-dist/scripts/{utils → lib}/common.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env zsh
 # Common utility functions for Pennyfarthing scripts
-# Source this file: source "${SCRIPT_DIR}/utils/common.sh"
+# Source this file: source "${SCRIPT_DIR}/lib/common.sh"
 #
 # Provides:
 #   - Output helpers: success, info, warn, error

package/pennyfarthing-dist/scripts/{utils → lib}/find-root.sh

@@ -1,12 +1,14 @@
 #!/usr/bin/env zsh
 # Shared utility: Find project root by .claude/ marker
-# Source this file to get PROJECT_ROOT set correctly
 #
-# Usage: source "$(dirname "$0")/utils/find-root.sh"
-#    or: source "$SCRIPT_DIR/utils/find-root.sh"
+# 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).
 #
-# After sourcing, PROJECT_ROOT will be set to the project root directory.
-# Uses SCRIPT_DIR if available (preferred), falls back to PWD.
+# 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).
 
 # Skip if PROJECT_ROOT is already set (e.g., by run.sh or CLAUDE_PROJECT_DIR)
 if [ -z "${PROJECT_ROOT:-}" ]; then

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

@@ -0,0 +1,44 @@
+# Miscellaneous Scripts
+
+Uncategorized utilities and one-off scripts.
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `deploy.sh` | Deployment script |
+| `doctor-dogfood.sh` | Health check for dogfooding setup |
+| `run-ci.sh` | Run CI locally |
+| `statusline.sh` | Status line configuration |
+| `uninstall.sh` | Uninstall Pennyfarthing from project |
+| `backlog.sh` | Backlog operations |
+| `repo-utils.sh` | Multi-repo utilities |
+| `repo-scan.sh` | Repository scanner |
+| `add-short-names.mjs` | Add short names to themes |
+| `migrate-bmad-workflow.mjs` | BMAD workflow migration |
+| `migrate-bmad-workflow.sh` | BMAD migration wrapper |
+| `find-related-work.sh` | Find related work items |
+| `check-status.sh` | Status checking utilities |
+| `session-cleanup.sh` | Clean up old sessions |
+| `generate-skill-docs.sh` | Generate skill documentation |
+| `log-skill-usage.sh` | Log skill invocations |
+| `skill-usage-report.sh` | Generate skill usage reports |
+| `run-timestamp.sh` | Timestamp utility |
+| `validate-subagent-frontmatter.sh` | Validate subagent YAML frontmatter |
+
+## Usage
+
+```bash
+.pennyfarthing/scripts/core/run.sh misc/doctor-dogfood.sh
+.pennyfarthing/scripts/core/run.sh misc/run-ci.sh
+```
+
+## Ownership
+
+- **Primary users:** Various
+- **Maintained by:** Core Pennyfarthing team
+
+## Note
+
+Scripts here may be candidates for moving to more specific categories
+as the codebase evolves.