@pennyfarthing/core 10.1.0 → 10.2.0

package/pennyfarthing-dist/scripts/hooks/bell-mode-hook.sh

@@ -1,25 +1,27 @@
 #!/bin/bash
 #
-# Bell Mode PostToolUse Hook (Story MSSCI-12275)
+# PostToolUse Hook — Bell Mode + Tandem Injection
 #
-# This hook is called by Claude Code after each tool execution.
-# When bell mode is enabled and there are queued messages, it returns
-# the first queued message as additionalContext to be injected into
-# Claude's next API call.
+# Called by Claude Code after each tool execution. Handles two independent
+# injection systems:
 #
-# Configuration files:
-#   .pennyfarthing/config.local.yaml - workflow.bell_mode: true/false
-#   .pennyfarthing/bell-queue.json - [{ "text": "...", "images": [...] }, ...]
+# 1. Bell queue (Cyclist only) — injects queued user messages when Cyclist
+#    is running and bell_mode is enabled. In CLI sessions this is a no-op.
+# 2. Tandem observations (always active) — injects backseat agent observations
+#    when tandem observation files exist. No configuration required.
+#
+# Bell queue takes precedence: if a queued message exists, tandem is
+# deferred to the next hook invocation.
 #
 # Output format (when injecting):
 #   {
 #     "hookSpecificOutput": {
 #       "hookEventName": "PostToolUse",
-#       "additionalContext": "User feedback: <message>"
+#       "additionalContext": "<message>"
 #     }
 #   }
 #
-# Output when disabled or queue empty: (nothing - exit 0)
+# Output when nothing to inject: (nothing - exit 0)
 
 # Find project root (walk up to find .pennyfarthing)
 PROJECT_ROOT="$PWD"
@@ -31,76 +33,151 @@ while [[ "$PROJECT_ROOT" != "/" ]]; do
 done
 
 if [[ ! -d "$PROJECT_ROOT/.pennyfarthing" ]]; then
-  # No .pennyfarthing directory found - exit silently
   exit 0
 fi
 
 CONFIG_LOCAL_YAML="$PROJECT_ROOT/.pennyfarthing/config.local.yaml"
 BELL_QUEUE_FILE="$PROJECT_ROOT/.pennyfarthing/bell-queue.json"
 
-# Check if bell mode is enabled in config.local.yaml
-if [[ ! -f "$CONFIG_LOCAL_YAML" ]]; then
-  exit 0
+# Detect Cyclist — bell queue is a Cyclist-only feature
+IS_CYCLIST=false
+CYCLIST_PORT=""
+PORT_FILE="$PROJECT_ROOT/.cyclist-port"
+if [[ -f "$PORT_FILE" ]]; then
+  CYCLIST_PORT=$(cat "$PORT_FILE" 2>/dev/null)
+  if [[ -n "$CYCLIST_PORT" ]] && [[ "$CYCLIST_PORT" =~ ^[0-9]+$ ]]; then
+    IS_CYCLIST=true
+  fi
 fi
 
-# Parse YAML to check workflow.bell_mode - look for "bell_mode: true"
-# This handles both "bell_mode: true" and "  bell_mode: true" (indented under workflow)
-ENABLED=$(grep -E '^\s*bell_mode:\s*true' "$CONFIG_LOCAL_YAML" 2>/dev/null || true)
-if [[ -z "$ENABLED" ]]; then
-  exit 0
+# --- Bell queue check (Cyclist only, requires bell_mode: true) ---
+# Takes precedence over tandem injection when active.
+
+if [[ "$IS_CYCLIST" == "true" ]] && [[ -f "$CONFIG_LOCAL_YAML" ]]; then
+  BELL_ENABLED=$(grep -E '^\s*bell_mode:\s*true' "$CONFIG_LOCAL_YAML" 2>/dev/null || true)
+
+  if [[ -n "$BELL_ENABLED" ]] && [[ -f "$BELL_QUEUE_FILE" ]]; then
+    QUEUE_CONTENT=$(cat "$BELL_QUEUE_FILE" 2>/dev/null)
+    if [[ -n "$QUEUE_CONTENT" ]] && [[ "$QUEUE_CONTENT" != "[]" ]]; then
+      FIRST_MESSAGE_TEXT=$(echo "$QUEUE_CONTENT" | sed -n 's/.*"text"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
+
+      if [[ -n "$FIRST_MESSAGE_TEXT" ]]; then
+        cat << EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "User feedback: $FIRST_MESSAGE_TEXT"
+  }
+}
+EOF
+
+        # Dequeue and notify Cyclist in background
+        (
+          if command -v jq &> /dev/null; then
+            jq 'if length > 0 then .[1:] else [] end' "$BELL_QUEUE_FILE" > "$BELL_QUEUE_FILE.tmp" 2>/dev/null && mv "$BELL_QUEUE_FILE.tmp" "$BELL_QUEUE_FILE"
+          fi
+
+          curl -s -X POST "http://localhost:$CYCLIST_PORT/api/bell-consumed" \
+            -H "Content-Type: application/json" \
+            -d "{\"text\": \"$FIRST_MESSAGE_TEXT\"}" \
+            >/dev/null 2>&1 || true
+        ) &
+
+        exit 0
+      fi
+    fi
+  fi
 fi
 
-# Check if queue file exists and has messages
-if [[ ! -f "$BELL_QUEUE_FILE" ]]; then
+# --- Tandem observation injection ---
+# Always active. No configuration required.
+# Checks .session/*-tandem-*.md files for new observations via mtime comparison.
+
+SESSION_DIR="$PROJECT_ROOT/.session"
+if [[ ! -d "$SESSION_DIR" ]]; then
   exit 0
 fi
 
-# Read queue and check if non-empty
-QUEUE_CONTENT=$(cat "$BELL_QUEUE_FILE" 2>/dev/null)
-if [[ -z "$QUEUE_CONTENT" ]] || [[ "$QUEUE_CONTENT" == "[]" ]]; then
+# Find tandem observation files
+TANDEM_FILES=$(find "$SESSION_DIR" -maxdepth 1 -name "*-tandem-*.md" 2>/dev/null)
+if [[ -z "$TANDEM_FILES" ]]; then
   exit 0
 fi
 
-# Extract first message text using simple parsing
-# The queue format is: [{"text":"...","images":[...]}, ...]
-FIRST_MESSAGE_TEXT=$(echo "$QUEUE_CONTENT" | sed -n 's/.*"text"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
+# Check each tandem file for new content
+for TANDEM_FILE in $TANDEM_FILES; do
+  # Extract agent name from filename: *-tandem-{agent}.md
+  AGENT=$(echo "$TANDEM_FILE" | sed -n 's/.*-tandem-\([a-zA-Z_]*\)\.md$/\1/p')
+  if [[ -z "$AGENT" ]]; then
+    continue
+  fi
 
-if [[ -z "$FIRST_MESSAGE_TEXT" ]]; then
-  exit 0
-fi
+  # Get file mtime (portable: stat -f %m on macOS, stat -c %Y on Linux)
+  if [[ "$(uname)" == "Darwin" ]]; then
+    FILE_MTIME=$(stat -f %m "$TANDEM_FILE" 2>/dev/null)
+  else
+    FILE_MTIME=$(stat -c %Y "$TANDEM_FILE" 2>/dev/null)
+  fi
+  if [[ -z "$FILE_MTIME" ]]; then
+    continue
+  fi
 
-# Get Cyclist port (if running)
-CYCLIST_PORT=""
-PORT_FILE="$PROJECT_ROOT/.cyclist-port"
-if [[ -f "$PORT_FILE" ]]; then
-  CYCLIST_PORT=$(cat "$PORT_FILE" 2>/dev/null)
-fi
+  # Compare with saved mtime sidecar
+  MTIME_SIDECAR="$SESSION_DIR/.tandem-mtime-$AGENT"
+  SAVED_MTIME="0"
+  if [[ -f "$MTIME_SIDECAR" ]]; then
+    SAVED_MTIME=$(cat "$MTIME_SIDECAR" 2>/dev/null)
+  fi
+
+  if [[ "$FILE_MTIME" == "$SAVED_MTIME" ]]; then
+    continue
+  fi
+
+  # Read tandem file and extract latest observation
+  CONTENT=$(cat "$TANDEM_FILE" 2>/dev/null)
+  if [[ -z "$CONTENT" ]]; then
+    continue
+  fi
 
-# Output the hook response JSON
-cat << EOF
+  # Extract persona from header: **Observer:** agent (Persona Name)
+  PERSONA=$(echo "$CONTENT" | sed -n 's/.*\*\*Observer:\*\*[[:space:]]*[a-zA-Z_]*[[:space:]]*(\([^)]*\)).*/\1/p' | head -1)
+  if [[ -z "$PERSONA" ]]; then
+    PERSONA="Unknown"
+  fi
+
+  # Extract latest observation text (last ## [HH:MM] Observation block)
+  # Get text between last observation header and trailing ---
+  OBS_TEXT=$(echo "$CONTENT" | awk '
+    /^## \[[0-9]+:[0-9]+\] Observation/ { found=1; text=""; next }
+    found && /^---/ { next }
+    found && /^\*\*Trigger:\*\*/ { next }
+    found { text = text (text ? "\n" : "") $0 }
+    END { if (text) print text }
+  ' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+
+  if [[ -z "$OBS_TEXT" ]]; then
+    # Update mtime even if no parseable observation
+    echo "$FILE_MTIME" > "$MTIME_SIDECAR"
+    continue
+  fi
+
+  # Format as [Tandem] prefix and output
+  TANDEM_MSG="[Tandem] $PERSONA: $OBS_TEXT"
+
+  cat << EOF
 {
   "hookSpecificOutput": {
     "hookEventName": "PostToolUse",
-    "additionalContext": "User feedback: $FIRST_MESSAGE_TEXT"
+    "additionalContext": "$TANDEM_MSG"
   }
 }
 EOF
 
-# Remove the first message from the queue and notify Cyclist
-# Run in background to avoid blocking hook response
-(
-  # Dequeue using jq if available
-  if command -v jq &> /dev/null; then
-    jq 'if length > 0 then .[1:] else [] end' "$BELL_QUEUE_FILE" > "$BELL_QUEUE_FILE.tmp" 2>/dev/null && mv "$BELL_QUEUE_FILE.tmp" "$BELL_QUEUE_FILE"
-  fi
+  # Save mtime sidecar
+  echo "$FILE_MTIME" > "$MTIME_SIDECAR"
 
-  # Notify Cyclist browser to dequeue and display the message
-  if [[ -n "$CYCLIST_PORT" ]] && [[ "$CYCLIST_PORT" =~ ^[0-9]+$ ]]; then
-    curl -s -X POST "http://localhost:$CYCLIST_PORT/api/bell-consumed" \
-      -H "Content-Type: application/json" \
-      -d "{\"text\": \"$FIRST_MESSAGE_TEXT\"}" \
-      >/dev/null 2>&1 || true
-  fi
-) &
+  # Only inject one tandem observation per hook invocation
+  exit 0
+done
 
 exit 0

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

@@ -47,7 +47,7 @@ extract_story_id() {
 
 # update_story_status STORY_ID NEW_STATUS
 # Update story status in sprint YAML and add completed date
-# Uses yq for YAML manipulation
+# Handles both inline stories in current-sprint.yaml and sharded epic files
 update_story_status() {
     local story_id="$1"
     local new_status="${2:-done}"
@@ -58,23 +58,33 @@ update_story_status() {
         return 1
     fi
 
-    # Check if yq is available
     if ! command -v yq &>/dev/null; then
         echo "Warning: yq not found, cannot update sprint YAML" >&2
         return 1
     fi
 
-    # Extract epic and story numbers
-    local epic_num="${story_id%%-*}"
-    local story_num="${story_id#*-}"
+    local sprint_dir
+    sprint_dir="$(dirname "$SPRINT_FILE")"
 
-    # Update status and add completed date using yq
+    # Try inline stories in current-sprint.yaml first
     yq eval -i "
-        (.epics[] | select(.id == \"$epic_num\") | .stories[] | select(.id == \"$story_num\")).status = \"$new_status\" |
-        (.epics[] | select(.id == \"$epic_num\") | .stories[] | select(.id == \"$story_num\")).completed = \"$completed_date\"
-    " "$SPRINT_FILE"
+        (.stories[] | select(.id == \"$story_id\")).status = \"$new_status\" |
+        (.stories[] | select(.id == \"$story_id\")).completed = \"$completed_date\"
+    " "$SPRINT_FILE" 2>/dev/null
+
+    # Also try each epic shard file
+    for shard in "$sprint_dir"/epic-*.yaml; do
+        [[ -f "$shard" ]] || continue
+        if yq eval ".stories[] | select(.id == \"$story_id\")" "$shard" 2>/dev/null | grep -q "$story_id"; then
+            yq eval -i "
+                (.stories[] | select(.id == \"$story_id\")).status = \"$new_status\" |
+                (.stories[] | select(.id == \"$story_id\")).completed = \"$completed_date\"
+            " "$shard"
+            return $?
+        fi
+    done
 
-    return $?
+    return 0
 }
 
 # log_reconciliation STORY_ID MESSAGE

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

@@ -134,6 +134,39 @@ if [ -n "$config_file" ] && [ -n "$agent_name" ]; then
 fi
 theme_display="$character_display"
 
+# Tandem indicator: detect active backseat agent from observation files
+# Files: .session/{storyId}-tandem-{partner}.md (created by backseat spawn, cleaned on finish)
+tandem_partner=""
+tandem_partner_display=""
+if [ -d "$PROJECT_ROOT/.session" ]; then
+    tandem_file=$(find "$PROJECT_ROOT/.session" -maxdepth 1 -name "*-tandem-*.md" -print 2>/dev/null | head -1)
+    if [ -n "$tandem_file" ]; then
+        # Extract partner name from filename: {storyId}-tandem-{partner}.md
+        tandem_partner=$(basename "$tandem_file" | sed -n 's/.*-tandem-\([a-zA-Z_-]*\)\.md$/\1/p')
+        if [ -n "$tandem_partner" ] && [ -n "$theme_file" ] && [ -f "$theme_file" ]; then
+            # Look up partner's character name from theme
+            partner_full=$(yq ".agents.${tandem_partner}.character" "$theme_file" 2>/dev/null)
+            if [ -n "$partner_full" ] && [ "$partner_full" != "null" ]; then
+                partner_clean=$(echo "$partner_full" | sed 's/ *([^)]*)//g' | xargs)
+                partner_clean=$(echo "$partner_clean" | sed -E 's/^(Captain|Lieutenant|Dr\.|Doc|Mr\.|Mrs\.|Ms\.|Admiral|Commander|Chief|Ensign|Translator|Agent|Colonel|Major|Sergeant|Professor|Lord|Lady|Sir|The) +//i')
+                partner_wc=$(echo "$partner_clean" | wc -w | tr -d ' ')
+                if [ "$partner_wc" -eq 1 ]; then
+                    tandem_partner_display="$partner_clean"
+                else
+                    tandem_partner_display=$(echo "$partner_clean" | awk '{print $NF}')
+                fi
+            fi
+            # Fallback to agent abbreviation if no theme character
+            if [ -z "$tandem_partner_display" ]; then
+                tandem_partner_display=$(get_agent_abbrev "$tandem_partner")
+            fi
+        elif [ -n "$tandem_partner" ]; then
+            # No theme file — use abbreviation
+            tandem_partner_display=$(get_agent_abbrev "$tandem_partner")
+        fi
+    fi
+fi
+
 # ANSI colors
 RESET=$'\033[0m'
 DIM=$'\033[2m'
@@ -214,20 +247,29 @@ repo_fmt=$(printf "%-14s" "$dir_name")
 branch_fmt=$(printf "%-12s" "${branch}${branch_dirty}")
 model_fmt=$(printf "%-10s" "$model")
 
-# Build agent display: [ROLE] Theme (role in reverse text with color)
+# Build tandem suffix: "+ Partner" when backseat agent is active
+tandem_suffix=""
+tandem_suffix_len=0
+if [ -n "$tandem_partner_display" ]; then
+    partner_color=$(get_agent_color "$tandem_partner")
+    tandem_suffix=" ${DIM}+${RESET} ${partner_color}${tandem_partner_display}${RESET}"
+    tandem_suffix_len=$((3 + ${#tandem_partner_display}))  # " + " + name
+fi
+
+# Build agent display: [ROLE] Theme (+ Partner) (role in reverse text with color)
 if [ -n "$agent_abbrev" ]; then
     agent_color=$(get_agent_color "$agent_name")
     # Role in reverse text with color, then theme
     if [ -n "$theme_display" ]; then
-        agent_section="${agent_color}${REVERSE} ${agent_abbrev} ${RESET} ${DIM}${theme_display}${RESET}"
-        # Pad to ~20 chars visual width (abbrev ~3 + spaces ~2 + theme ~10 = ~15, pad to 20)
-        pad_len=$((18 - ${#agent_abbrev} - ${#theme_display}))
+        agent_section="${agent_color}${REVERSE} ${agent_abbrev} ${RESET} ${DIM}${theme_display}${RESET}${tandem_suffix}"
+        # Pad to ~20 chars visual width (abbrev ~3 + spaces ~2 + theme ~10 + tandem = ~15+, pad to 20)
+        pad_len=$((18 - ${#agent_abbrev} - ${#theme_display} - tandem_suffix_len))
         [ "$pad_len" -lt 0 ] && pad_len=0
         padding=$(printf "%${pad_len}s" "")
         agent_section="${agent_section}${padding}"
     else
-        agent_section="${agent_color}${REVERSE} ${agent_abbrev} ${RESET}"
-        pad_len=$((17 - ${#agent_abbrev}))
+        agent_section="${agent_color}${REVERSE} ${agent_abbrev} ${RESET}${tandem_suffix}"
+        pad_len=$((17 - ${#agent_abbrev} - tandem_suffix_len))
         [ "$pad_len" -lt 0 ] && pad_len=0
         padding=$(printf "%${pad_len}s" "")
         agent_section="${agent_section}${padding}"
@@ -235,8 +277,8 @@ if [ -n "$agent_abbrev" ]; then
 else
     # No agent - just show theme if available
     if [ -n "$theme_display" ]; then
-        agent_section="${DIM}${theme_display}${RESET}"
-        pad_len=$((20 - ${#theme_display}))
+        agent_section="${DIM}${theme_display}${RESET}${tandem_suffix}"
+        pad_len=$((20 - ${#theme_display} - tandem_suffix_len))
         [ "$pad_len" -lt 0 ] && pad_len=0
         padding=$(printf "%${pad_len}s" "")
         agent_section="${agent_section}${padding}"

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

@@ -6,7 +6,7 @@ Scripts for workflow mechanics, phase transitions, and quality gates.
 
 | Script | Purpose |
 |--------|---------|
-| `finish-story.sh` | Story completion workflow (archive, PR merge, Jira transition) |
+| `finish-story.sh` | **DEPRECATED** — forwards to `pf sprint story finish` |
 | `fix-session-phase.sh` | Repair session file phase state |
 | `check.sh` | Quality gates runner (lint, type check, tests) |
 | `list-workflows.sh` | List available workflows |
@@ -18,7 +18,7 @@ Scripts for workflow mechanics, phase transitions, and quality gates.
 ## Usage
 
 ```bash
-.pennyfarthing/scripts/workflow/finish-story.sh MSSCI-12345
+pf sprint story finish MSSCI-12345
 .pennyfarthing/scripts/workflow/start-workflow.sh prd --mode create
 ```
 

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

@@ -1,199 +1,20 @@
 #!/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
+# DEPRECATED: Use `pf sprint story finish` instead.
 #
-# Prerequisites:
-# - Session file exists at .session/{story-id}-session.md
-# - PR is approved and mergeable
-# - Reviewer has approved (phase: finish in session)
+# This shell script had a bug where yq paths targeted .epics[].stories[]
+# but the sprint YAML uses sharded epic files with .stories[] at root.
+# The Python implementation (pennyfarthing_scripts.sprint.story_finish)
+# correctly handles sharded YAML via read_sprint/write_sprint.
 #
-# 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. Archive completed epics (if last story in epic was just finished)
-# 6. Clean up local branch and session file
+# Usage: finish-story.sh <story-id> [--dry-run]
 
 set -euo pipefail
 
-STORY_ID="${1:-}"
-DRY_RUN=false
+echo "DEPRECATED: finish-story.sh is deprecated. Forwarding to 'pf sprint story finish'." >&2
 
-# Parse options
+ARGS=()
 for arg in "$@"; do
-  case $arg in
-    --dry-run)
-      DRY_RUN=true
-      shift
-      ;;
-  esac
+  ARGS+=("$arg")
 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
-
-# Find project root
-source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
-
-SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
-ARCHIVE_DIR="$PROJECT_ROOT/sprint/archive"
-
-# Ensure archive directory exists
-mkdir -p "$ARCHIVE_DIR"
-
-# Resolve session file: prefer Jira key, fall back to numeric story ID
-SESSION_FILE="$PROJECT_ROOT/.session/${STORY_ID}-session.md"
-if [[ ! -f "$SESSION_FILE" ]]; then
-  # Look up Jira key from sprint YAML and try that
-  _JIRA_LOOKUP=$(pf sprint story field "$STORY_ID" jira 2>/dev/null || echo "")
-  if [[ -n "$_JIRA_LOOKUP" && "$_JIRA_LOOKUP" != "null" ]]; then
-    ALT_SESSION="$PROJECT_ROOT/.session/${_JIRA_LOOKUP}-session.md"
-    if [[ -f "$ALT_SESSION" ]]; then
-      SESSION_FILE="$ALT_SESSION"
-    fi
-  fi
-fi
-
-# Also try the reverse: if called with Jira key, try numeric ID
-if [[ ! -f "$SESSION_FILE" ]]; then
-  # List session files and look for one containing the story ID
-  for f in "$PROJECT_ROOT/.session/"*-session.md; do
-    [[ -f "$f" ]] || continue
-    if grep -q "$STORY_ID" "$f" 2>/dev/null; then
-      SESSION_FILE="$f"
-      break
-    fi
-  done
-fi
-
-# Validate session file exists
-if [[ ! -f "$SESSION_FILE" ]]; then
-  echo "Error: Session file not found for story $STORY_ID"
-  echo "Looked for: $PROJECT_ROOT/.session/${STORY_ID}-session.md"
-  [[ -n "${_JIRA_LOOKUP:-}" ]] && echo "Also tried: $PROJECT_ROOT/.session/${_JIRA_LOOKUP}-session.md"
-  exit 1
-fi
-
-# Extract metadata from session file
-# Try **Jira:** field first (handle both "**Jira:**" and "- **Jira:**", markdown link format)
-JIRA_KEY=$(grep -E '\*\*Jira:\*\*' "$SESSION_FILE" | sed 's/.*\*\*Jira:\*\* //' | sed 's/\[//' | sed 's/\].*//' | tr -d ' ' || echo "")
-
-# Fallback: extract MSSCI key from **ID:** field (format: "MSSCI-14459 (81-2)" or just "MSSCI-14459")
-if [[ -z "$JIRA_KEY" || "$JIRA_KEY" == "null" ]]; then
-  JIRA_KEY=$(grep -E '\*\*ID:\*\*' "$SESSION_FILE" | grep -oE 'MSSCI-[0-9]+' | head -1 || echo "")
-fi
-
-# Fallback: if STORY_ID itself is a Jira key, use it directly
-if [[ -z "$JIRA_KEY" || "$JIRA_KEY" == "null" ]]; then
-  if [[ "$STORY_ID" =~ ^MSSCI-[0-9]+$ ]]; then
-    JIRA_KEY="$STORY_ID"
-  fi
-fi
-
-# Fallback: look up Jira key from sprint YAML via pf CLI
-if [[ -z "$JIRA_KEY" || "$JIRA_KEY" == "null" ]]; then
-  JIRA_KEY=$(pf sprint story field "$STORY_ID" jira 2>/dev/null || 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
-
-# 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: 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. Archive any completed epics"
-  echo "  6. Delete local branch: $BRANCH"
-  echo "  7. 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: Archive completed epics
-echo "5. Archiving completed epics..."
-pf sprint epic archive 2>/dev/null && echo "   → Checked for completed epics" || echo "   → No epics to archive"
-
-# Step 6: Clean up git
-echo "6. 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 7: Remove session file
-echo "7. 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"
+exec pf sprint story finish "${ARGS[@]}"

package/pennyfarthing-dist/skills/skill-registry.schema.json

@@ -98,6 +98,14 @@
           "type": "array",
           "items": { "type": "string" },
           "description": "Tools this skill is allowed to use. If omitted, all tools are allowed. Use to restrict read-only skills from writing."
+        },
+        "deprecated": {
+          "type": "boolean",
+          "description": "Whether this skill is deprecated"
+        },
+        "redirect": {
+          "type": "string",
+          "description": "Skill name to redirect to when deprecated"
         }
       },
       "required": ["name", "description", "category", "tags"],

package/pennyfarthing-dist/skills/skill-registry.yaml

@@ -386,7 +386,7 @@ skills:
     anti_patterns:
       - Don't switch workflows mid-story unless requirements fundamentally changed
     related_skills: [sprint]
-    keywords: [tdd, trivial, agent-docs, bdd, architecture, bikelane, stepped, phased]
+    keywords: [tdd, tdd-tandem, trivial, agent-docs, bdd, bdd-tandem, architecture, bikelane, stepped, phased]
 
   yq:
     name: yq