@pennyfarthing/core 7.5.0 → 7.6.0

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

@@ -0,0 +1,58 @@
+#!/usr/bin/env zsh
+# Session stop hook: Save checkpoint for cross-session continuity
+# Called by Claude Code when a session ends
+#
+# Writes session state to checkpoint:
+#   - Active agent (from .session/agents/)
+#   - Current story (from .session/*-session.md)
+#   - Workflow phase (from session file)
+#   - Git SHA (current HEAD)
+#   - Session ID
+#
+# Next session can validate this against current git state.
+
+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, etc.)
+input=$(cat)
+session_id=$(echo "$input" | jq -r '.session_id // "unknown"')
+
+# Get current agent for this session
+agent=""
+agent_file="$PROJECT_ROOT/.session/agents/$session_id"
+if [[ -f "$agent_file" ]]; then
+    agent=$(cat "$agent_file")
+fi
+
+# Find active story from session files
+story=""
+phase=""
+session_file=$(find "$PROJECT_ROOT/.session" -maxdepth 1 -name "*-session.md" -type f 2>/dev/null | head -1)
+if [[ -n "$session_file" && -f "$session_file" ]]; then
+    # Extract story ID from filename (e.g., 8-3-session.md -> 8-3)
+    story=$(basename "$session_file" | sed 's/-session\.md$//')
+
+    # Extract phase from session file (look for "Phase:" line)
+    phase=$(grep -i "^- Phase:" "$session_file" 2>/dev/null | head -1 | sed 's/.*Phase:[[:space:]]*//' | cut -d' ' -f1 || echo "")
+fi
+
+# Get current git SHA
+git_sha=""
+if command -v git &>/dev/null && git rev-parse --git-dir &>/dev/null; then
+    git_sha=$(git rev-parse --short HEAD 2>/dev/null || echo "")
+fi
+
+# Build checkpoint data (semicolon-separated key=value pairs)
+checkpoint_data="agent=${agent};story=${story};phase=${phase};sha=${git_sha};session=${session_id}"
+
+# Save checkpoint
+checkpoint_save "session_state" "$checkpoint_data"
+
+# Log session end
+echo "$(date -Iseconds) | Session end: $session_id (agent=$agent, story=$story)" >> "$PROJECT_ROOT/.session/session-log.txt"
+
+exit 0

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

@@ -0,0 +1,33 @@
+# Jira Scripts
+
+Scripts for Jira integration, synchronization, and story management.
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `jira-lib.sh` | Shared Jira bash utilities (library) |
+| `jira-lib.mjs` | Shared Jira JavaScript utilities (library) |
+| `jira-claim-story.sh` | Claim a story (assign and move to In Progress) |
+| `jira-reconcile.sh` | Reconcile Jira with sprint YAML |
+| `jira-sync.sh` | Sync story to Jira |
+| `jira-sync.mjs` | Sync story to Jira (JavaScript) |
+| `jira-sync-story.sh` | Sync individual story |
+| `jira-sync-story.mjs` | Sync individual story (JavaScript) |
+| `create-jira-epic.sh` | Create Jira epic with stories |
+| `create-jira-story.sh` | Create individual Jira story |
+| `sync-epic-jira.sh` | Sync epic to Jira |
+| `sync-epic-to-jira.sh` | Sync epic to Jira (alternate) |
+| `jira-bidirectional-sync.mjs` | Bidirectional sync between YAML and Jira |
+
+## Usage
+
+```bash
+.pennyfarthing/scripts/core/run.sh jira/jira-claim-story.sh MSSCI-12345
+.pennyfarthing/scripts/core/run.sh jira/jira-reconcile.sh
+```
+
+## Ownership
+
+- **Primary users:** SM agent, `/jira` skill
+- **Maintained by:** Core Pennyfarthing team

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

@@ -0,0 +1,101 @@
+#!/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]
+
+set -euo pipefail
+
+EPIC_ID="${1:-}"
+DRY_RUN=false
+
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=true ;;
+  esac
+done
+
+if [[ -z "$EPIC_ID" ]]; then
+  echo "Usage: create-jira-epic.sh <epic-id> [--dry-run]"
+  exit 1
+fi
+
+# Find project root
+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"
+SCRIPTS_DIR="$PROJECT_ROOT/.pennyfarthing/scripts"
+JIRA_PROJECT="${JIRA_PROJECT_KEY:-MSSCI}"
+PROJECT_LABEL="${PROJECT_LABEL:-${PROJECT_NAME:-pennyfarthing}}"
+
+# Find epic (by id or jira key)
+EPIC_DATA=$(yq -o json ".epics[] | select(.id == \"$EPIC_ID\" or .jira == \"$EPIC_ID\")" "$SPRINT_FILE" 2>/dev/null || echo "")
+
+if [[ -z "$EPIC_DATA" || "$EPIC_DATA" == "null" ]]; then
+  echo "Error: Epic $EPIC_ID not found"
+  yq '.epics[].id' "$SPRINT_FILE" 2>/dev/null
+  exit 1
+fi
+
+EPIC_TITLE=$(echo "$EPIC_DATA" | yq -r '.title // "Unknown"' | sed 's/^Epic: //')
+EPIC_JIRA=$(echo "$EPIC_DATA" | yq -r '.jira // ""')
+
+echo ""
+echo "Epic: $EPIC_TITLE"
+echo "Dry run: $DRY_RUN"
+echo ""
+
+# Create epic if needed
+if [[ -n "$EPIC_JIRA" && "$EPIC_JIRA" != "null" ]]; then
+  echo "Epic already exists: $EPIC_JIRA"
+  JIRA_EPIC_KEY="$EPIC_JIRA"
+else
+  if [[ "$DRY_RUN" == "true" ]]; then
+    echo "[DRY RUN] Would create epic: $EPIC_TITLE"
+    JIRA_EPIC_KEY="MSSCI-XXXXX"
+  else
+    EPIC_DESCRIPTION=$(echo "$EPIC_DATA" | yq -r '.description // ""')
+    EPIC_OUTPUT=$(echo "" | jira issue create \
+      --project "$JIRA_PROJECT" \
+      --type Epic \
+      --summary "$EPIC_TITLE" \
+      --body "$EPIC_DESCRIPTION" \
+      --label "$PROJECT_LABEL" \
+      --no-input 2>&1) || {
+        echo "Error: $EPIC_OUTPUT"
+        exit 1
+      }
+
+    JIRA_EPIC_KEY=$(echo "$EPIC_OUTPUT" | grep -oE 'MSSCI-[0-9]+' | head -1)
+    echo "Created epic: $JIRA_EPIC_KEY"
+
+    yq eval -i "(.epics[] | select(.id == \"$EPIC_ID\")).jira = \"$JIRA_EPIC_KEY\"" "$SPRINT_FILE"
+  fi
+fi
+
+echo ""
+echo "Creating stories..."
+echo ""
+
+# Get story IDs that need Jira keys
+STORY_IDS=$(yq -r "(.epics[] | select(.jira == \"$JIRA_EPIC_KEY\" or .id == \"$EPIC_ID\")).stories[] | select(.jira == null or .jira == \"\") | .id" "$SPRINT_FILE" 2>/dev/null || echo "")
+
+if [[ -z "$STORY_IDS" ]]; then
+  echo "All stories already have Jira keys"
+else
+  for STORY_ID in $STORY_IDS; do
+    if [[ "$DRY_RUN" == "true" ]]; then
+      TITLE=$(yq -r "(.epics[] | select(.jira == \"$JIRA_EPIC_KEY\" or .id == \"$EPIC_ID\")).stories[] | select(.id == \"$STORY_ID\") | .title" "$SPRINT_FILE")
+      echo "[DRY RUN] Would create: $STORY_ID - $TITLE"
+    else
+      "$SCRIPTS_DIR/jira/create-jira-story.sh" "$JIRA_EPIC_KEY" "$STORY_ID"
+    fi
+  done
+fi
+
+echo ""
+echo "Done. View epic: jira issue view $JIRA_EPIC_KEY"

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

@@ -0,0 +1,97 @@
+#!/bin/bash
+# Create a single Jira story from sprint YAML
+# Usage: create-jira-story.sh <epic-jira-key> <story-id>
+#
+# Example: create-jira-story.sh MSSCI-12077 MSSCI-12066
+
+set -euo pipefail
+
+EPIC_JIRA_KEY="${1:-}"
+STORY_ID="${2:-}"
+
+if [[ -z "$EPIC_JIRA_KEY" || -z "$STORY_ID" ]]; then
+  echo "Usage: create-jira-story.sh <epic-jira-key> <story-id>"
+  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"
+JIRA_PROJECT="${JIRA_PROJECT_KEY:-MSSCI}"
+PROJECT_LABEL="${PROJECT_LABEL:-${PROJECT_NAME:-pennyfarthing}}"
+SPRINT_JIRA_ID=$(yq '.sprint.jira_sprint_id' "$SPRINT_FILE" 2>/dev/null || echo "")
+
+# Get story data
+STORY_DATA=$(yq -o json "(.epics[] | select(.jira == \"$EPIC_JIRA_KEY\")).stories[] | select(.id == \"$STORY_ID\")" "$SPRINT_FILE" 2>/dev/null || echo "")
+
+if [[ -z "$STORY_DATA" || "$STORY_DATA" == "null" ]]; then
+  echo "Error: Story $STORY_ID not found under epic $EPIC_JIRA_KEY"
+  exit 1
+fi
+
+STORY_TITLE=$(echo "$STORY_DATA" | yq -r '.title // "Untitled"')
+STORY_DESCRIPTION=$(echo "$STORY_DATA" | yq -r '.description // ""')
+STORY_POINTS=$(echo "$STORY_DATA" | yq -r '.points // 0')
+STORY_PRIORITY=$(echo "$STORY_DATA" | yq -r '.priority // "P2"')
+STORY_JIRA=$(echo "$STORY_DATA" | yq -r '.jira // ""')
+
+# Check if already has Jira key
+if [[ -n "$STORY_JIRA" && "$STORY_JIRA" != "null" ]]; then
+  echo "SKIP: $STORY_ID already has Jira key: $STORY_JIRA"
+  exit 0
+fi
+
+# Map priority
+case "$STORY_PRIORITY" in
+  P0) JIRA_PRIORITY="Highest" ;;
+  P1) JIRA_PRIORITY="High" ;;
+  P2) JIRA_PRIORITY="Medium" ;;
+  P3) JIRA_PRIORITY="Low" ;;
+  *) JIRA_PRIORITY="Medium" ;;
+esac
+
+# Create story
+STORY_OUTPUT=$(echo "" | jira issue create \
+  --project "$JIRA_PROJECT" \
+  --type Story \
+  --summary "$STORY_TITLE" \
+  --body "$STORY_DESCRIPTION" \
+  --parent "$EPIC_JIRA_KEY" \
+  --priority "$JIRA_PRIORITY" \
+  --label "$PROJECT_LABEL" \
+  --no-input 2>&1) || {
+    echo "Error creating story: $STORY_OUTPUT"
+    exit 1
+  }
+
+STORY_JIRA_KEY=$(echo "$STORY_OUTPUT" | grep -oE 'MSSCI-[0-9]+' | head -1)
+
+if [[ -z "$STORY_JIRA_KEY" ]]; then
+  echo "Error: Could not extract Jira key from output"
+  exit 1
+fi
+
+echo "Created: $STORY_JIRA_KEY ($STORY_TITLE)"
+
+# Update story points
+if [[ "$STORY_POINTS" -gt 0 ]]; then
+  jira issue edit "$STORY_JIRA_KEY" --custom "customfield_10031=$STORY_POINTS" --no-input 2>/dev/null || true
+fi
+
+# Add to sprint
+if [[ -n "$SPRINT_JIRA_ID" && "$SPRINT_JIRA_ID" != "null" ]]; then
+  jira sprint add "$SPRINT_JIRA_ID" "$STORY_JIRA_KEY" 2>/dev/null || true
+fi
+
+# Update sprint YAML
+yq eval -i "((.epics[] | select(.jira == \"$EPIC_JIRA_KEY\")).stories[] | select(.id == \"$STORY_ID\")).id = \"$STORY_JIRA_KEY\"" "$SPRINT_FILE"
+yq eval -i "((.epics[] | select(.jira == \"$EPIC_JIRA_KEY\")).stories[] | select(.id == \"$STORY_JIRA_KEY\")).jira = \"$STORY_JIRA_KEY\"" "$SPRINT_FILE"
+
+echo "Updated sprint YAML"

package/pennyfarthing-dist/scripts/jira/jira-bidirectional-sync.mjs

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+/**
+ * jira-bidirectional-sync.mjs - Bidirectional sync between sprint YAML and Jira
+ *
+ * Story: MSSCI-11842
+ *
+ * Usage: node jira-bidirectional-sync.mjs [options]
+ *
+ * Options:
+ *   --dry-run       Show changes without applying
+ *   --yaml-wins     Prefer YAML values on conflict (default: Jira wins)
+ *   --status        Sync status field
+ *   --points        Sync story points
+ *   --all           Sync all fields (status + points)
+ *   --sprint <id>   Target specific sprint (default: current)
+ */
+
+import {
+  mapStatusToJira,
+  mapJiraToStatus,
+  extractJiraKey
+} from './jira-lib.mjs';
+
+/**
+ * Parse CLI arguments
+ * @param {string[]} argv - Command line arguments (without node and script path)
+ * @returns {object} Parsed arguments
+ */
+export function parseCliArgs(argv) {
+  const args = {
+    dryRun: false,
+    yamlWins: false,
+    syncStatus: false,
+    syncPoints: false,
+    sprintId: null
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    switch (arg) {
+      case '--dry-run':
+        args.dryRun = true;
+        break;
+      case '--yaml-wins':
+        args.yamlWins = true;
+        break;
+      case '--status':
+        args.syncStatus = true;
+        break;
+      case '--points':
+        args.syncPoints = true;
+        break;
+      case '--all':
+        args.syncStatus = true;
+        args.syncPoints = true;
+        break;
+      case '--sprint':
+        args.sprintId = argv[++i];
+        break;
+    }
+  }
+
+  return args;
+}
+
+/**
+ * Generate a sync plan comparing YAML and Jira stories
+ *
+ * @param {Array} yamlStories - Stories from sprint YAML [{id, status, points, ...}]
+ * @param {Array} jiraStories - Stories from Jira [{key, fields: {status: {name}, customfield_10031, ...}}]
+ * @param {object} options - Sync options
+ * @param {boolean} options.syncStatus - Whether to sync status field
+ * @param {boolean} options.syncPoints - Whether to sync points field
+ * @param {string} options.direction - 'yaml-to-jira', 'jira-to-yaml', or 'bidirectional'
+ * @param {boolean} options.yamlWins - If true, YAML wins conflicts (default: Jira wins)
+ * @param {boolean} options.reportMissing - If true, include detailed reports for missing stories
+ * @param {Date} options.lastSyncTime - Last sync timestamp for conflict detection
+ * @returns {object} Sync plan with changes, yamlOnly, jiraOnly, both, conflicts, reports
+ */
+export function generateSyncPlan(yamlStories, jiraStories, options = {}) {
+  const {
+    syncStatus = false,
+    syncPoints = false,
+    direction = 'bidirectional',
+    yamlWins = false,
+    reportMissing = false,
+    lastSyncTime = null
+  } = options;
+
+  // Build lookup maps
+  const yamlByKey = new Map();
+  for (const story of yamlStories) {
+    yamlByKey.set(story.id, story);
+  }
+
+  const jiraByKey = new Map();
+  for (const story of jiraStories) {
+    jiraByKey.set(story.key, story);
+  }
+
+  // Categorize stories
+  const yamlKeys = new Set(yamlStories.map(s => s.id));
+  const jiraKeys = new Set(jiraStories.map(s => s.key));
+
+  const yamlOnly = [...yamlKeys].filter(k => !jiraKeys.has(k));
+  const jiraOnly = [...jiraKeys].filter(k => !yamlKeys.has(k));
+  const both = [...yamlKeys].filter(k => jiraKeys.has(k));
+
+  // Generate changes for stories in both systems
+  const changes = [];
+  const conflicts = [];
+
+  for (const key of both) {
+    const yamlStory = yamlByKey.get(key);
+    const jiraStory = jiraByKey.get(key);
+
+    const yamlStatus = yamlStory.status;
+    const jiraStatus = jiraStory.fields?.status?.name;
+    const yamlPoints = yamlStory.points;
+    const jiraPoints = jiraStory.fields?.customfield_10031;
+
+    // Normalize statuses for comparison
+    const normalizedYamlStatus = mapStatusToJira(yamlStatus);
+    const normalizedJiraStatus = jiraStatus;
+
+    // Check status differences
+    if (syncStatus && normalizedYamlStatus !== normalizedJiraStatus) {
+      // Determine action based on direction and yamlWins flag
+      let action;
+      let targetStatus;
+
+      if (direction === 'yaml-to-jira') {
+        action = 'update-jira';
+        targetStatus = normalizedYamlStatus;
+      } else if (direction === 'jira-to-yaml') {
+        action = 'update-yaml';
+        targetStatus = mapJiraToStatus(jiraStatus);
+      } else {
+        // Bidirectional - use yamlWins flag to determine winner
+        if (yamlWins) {
+          action = 'update-jira';
+          targetStatus = normalizedYamlStatus;
+        } else {
+          action = 'update-yaml';
+          targetStatus = mapJiraToStatus(jiraStatus);
+        }
+      }
+
+      changes.push({
+        key,
+        field: 'status',
+        action,
+        yamlStatus,
+        jiraStatus,
+        targetStatus
+      });
+    }
+
+    // Check points differences
+    if (syncPoints && yamlPoints !== jiraPoints) {
+      let action;
+      let targetPoints;
+
+      if (direction === 'yaml-to-jira') {
+        action = 'update-jira';
+        targetPoints = yamlPoints;
+      } else if (direction === 'jira-to-yaml') {
+        action = 'update-yaml';
+        targetPoints = jiraPoints;
+      } else {
+        // Bidirectional - use yamlWins flag
+        if (yamlWins) {
+          action = 'update-jira';
+          targetPoints = yamlPoints;
+        } else {
+          action = 'update-yaml';
+          targetPoints = jiraPoints;
+        }
+      }
+
+      changes.push({
+        key,
+        field: 'points',
+        action,
+        yamlPoints,
+        jiraPoints,
+        targetPoints
+      });
+    }
+  }
+
+  // Build result
+  const plan = {
+    changes,
+    yamlOnly,
+    jiraOnly,
+    both,
+    conflicts
+  };
+
+  // Add reports if requested
+  if (reportMissing) {
+    plan.reports = {
+      yamlOnly: yamlOnly.map(key => ({
+        key,
+        story: yamlByKey.get(key),
+        recommendation: 'Create in Jira'
+      })),
+      jiraOnly: jiraOnly.map(key => ({
+        key,
+        story: jiraByKey.get(key),
+        recommendation: 'Import to YAML'
+      }))
+    };
+  }
+
+  return plan;
+}
+
+/**
+ * Execute a sync plan
+ *
+ * @param {object} plan - Sync plan from generateSyncPlan
+ * @param {object} options - Execution options
+ * @param {boolean} options.dryRun - If true, don't apply changes
+ * @returns {Promise<object>} Execution result
+ */
+export async function executeSyncPlan(plan, options = {}) {
+  const { dryRun = false } = options;
+
+  const result = {
+    dryRun,
+    wouldApply: plan.changes,
+    applied: 0,
+    yamlModified: false,
+    jiraApiCalls: 0
+  };
+
+  if (dryRun) {
+    // In dry-run mode, don't apply any changes
+    return result;
+  }
+
+  // Apply changes (actual implementation would go here)
+  for (const change of plan.changes) {
+    if (change.action === 'update-yaml') {
+      // TODO: Update YAML file
+      result.yamlModified = true;
+    } else if (change.action === 'update-jira') {
+      // TODO: Call Jira API
+      result.jiraApiCalls++;
+    }
+    result.applied++;
+  }
+
+  return result;
+}
+
+/**
+ * Format sync plan as human-readable string
+ *
+ * @param {object} plan - Sync plan from generateSyncPlan
+ * @returns {string} Human-readable output
+ */
+export function formatSyncPlan(plan) {
+  const lines = [];
+
+  lines.push('='.repeat(60));
+  lines.push('Bidirectional Sync Plan');
+  lines.push('='.repeat(60));
+  lines.push('');
+
+  // Summary
+  lines.push(`Stories in YAML only: ${plan.yamlOnly.length}`);
+  lines.push(`Stories in Jira only: ${plan.jiraOnly.length}`);
+  lines.push(`Stories in both: ${plan.both.length}`);
+  lines.push(`Changes to apply: ${plan.changes.length}`);
+  lines.push('');
+
+  // YAML-only stories
+  if (plan.yamlOnly.length > 0) {
+    lines.push('--- YAML Only (not in Jira) ---');
+    for (const key of plan.yamlOnly) {
+      lines.push(`  ${key}`);
+    }
+    lines.push('');
+  }
+
+  // Jira-only stories
+  if (plan.jiraOnly.length > 0) {
+    lines.push('--- Jira Only (not in YAML) ---');
+    for (const key of plan.jiraOnly) {
+      lines.push(`  ${key}`);
+    }
+    lines.push('');
+  }
+
+  // Changes
+  if (plan.changes.length > 0) {
+    lines.push('--- Changes ---');
+    for (const change of plan.changes) {
+      const direction = change.action === 'update-yaml' ? 'Jira → YAML' : 'YAML → Jira';
+      if (change.field === 'status') {
+        lines.push(`  ${change.key}: status ${direction}`);
+        lines.push(`    YAML: ${change.yamlStatus} | Jira: ${change.jiraStatus} → ${change.targetStatus}`);
+      } else if (change.field === 'points') {
+        lines.push(`  ${change.key}: points ${direction}`);
+        lines.push(`    YAML: ${change.yamlPoints} | Jira: ${change.jiraPoints} → ${change.targetPoints}`);
+      }
+    }
+    lines.push('');
+  }
+
+  // Conflicts
+  if (plan.conflicts && plan.conflicts.length > 0) {
+    lines.push('--- Conflicts (manual resolution needed) ---');
+    for (const conflict of plan.conflicts) {
+      lines.push(`  ${conflict.key}: ${conflict.field}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('='.repeat(60));
+
+  return lines.join('\n');
+}