@pennyfarthing/core 10.0.1 → 10.0.2

package/pennyfarthing-dist/scripts/workflow/complete-step.py

@@ -0,0 +1,304 @@
+#!/usr/bin/env python3
+"""
+complete-step.py - Complete the current step of a stepped workflow
+
+Usage: python complete-step.py [name] [--step N]
+
+Advances session state: increments current step, updates steps completed,
+recalculates completion percentage, and marks workflow as completed when
+all steps are done.
+
+If no name provided, detects from active session.
+If --step N provided, completes that specific step instead of current step.
+"""
+
+import argparse
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:
+    print("Error: PyYAML required. Install with: pip install pyyaml", file=sys.stderr)
+    sys.exit(1)
+
+
+def find_project_root() -> Path:
+    """Find project root by looking for .pennyfarthing directory."""
+    # Honor explicit PROJECT_ROOT override
+    import os
+    override = os.environ.get("PROJECT_ROOT")
+    if override:
+        return Path(override)
+
+    current = Path.cwd()
+    while current != current.parent:
+        if (current / ".pennyfarthing").is_dir():
+            return current
+        current = current.parent
+    print("Error: Could not find .pennyfarthing/ directory", file=sys.stderr)
+    print("Are you in a Pennyfarthing-enabled project?", file=sys.stderr)
+    sys.exit(1)
+
+
+def parse_session_field(content: str, field: str) -> str:
+    """Extract a field value from session markdown."""
+    pattern = rf"^- \*\*{re.escape(field)}:\*\*\s*(.+)$"
+    match = re.search(pattern, content, re.MULTILINE)
+    return match.group(1).strip() if match else ""
+
+
+def find_session_file(session_dir: Path, workflow_name: str | None) -> tuple[Path, str]:
+    """Find session file and determine workflow name.
+
+    Returns (session_path, workflow_name).
+    """
+    if workflow_name:
+        session_file = session_dir / f"{workflow_name}-workflow-session.md"
+        if not session_file.exists():
+            print(f"Error: No session found for workflow '{workflow_name}'", file=sys.stderr)
+            print(f"\nUse `/workflow start {workflow_name}` to begin.", file=sys.stderr)
+            sys.exit(1)
+        return session_file, workflow_name
+
+    # Auto-detect from session directory
+    sessions = list(session_dir.glob("*-workflow-session.md"))
+    if not sessions:
+        print("Error: No active workflow session found.", file=sys.stderr)
+        print("\nUsage: complete-step.py [name] [--step N]", file=sys.stderr)
+        sys.exit(1)
+
+    session_file = sorted(sessions)[0]
+    content = session_file.read_text()
+
+    # Try to extract workflow name from content
+    wf_match = re.search(r"^\*\*Workflow:\*\*\s*(.+)$", content, re.MULTILINE)
+    if wf_match:
+        name = wf_match.group(1).strip()
+    else:
+        # Derive from filename
+        name = session_file.stem.replace("-workflow-session", "")
+
+    return session_file, name
+
+
+def find_workflow_file(workflows_dir: Path, workflow_name: str) -> Path:
+    """Find workflow YAML definition."""
+    flat = workflows_dir / f"{workflow_name}.yaml"
+    if flat.exists():
+        return flat
+
+    nested = workflows_dir / workflow_name / "workflow.yaml"
+    if nested.exists():
+        return nested
+
+    print(f"Error: Workflow definition '{workflow_name}' not found", file=sys.stderr)
+    sys.exit(1)
+
+
+def count_steps(steps_path: Path) -> int:
+    """Count step files in a directory."""
+    return len([
+        f for f in steps_path.iterdir()
+        if f.is_file() and re.match(r"step-\d+", f.name) and f.suffix == ".md"
+    ])
+
+
+def parse_steps_completed(value: str) -> list[int]:
+    """Parse steps completed array from string like '[1, 2, 3]'."""
+    if not value or value == "[]":
+        return []
+    # Extract numbers from the bracket notation
+    return [int(n) for n in re.findall(r"\d+", value)]
+
+
+def format_steps_completed(steps: list[int]) -> str:
+    """Format steps list as bracket notation."""
+    if not steps:
+        return "[]"
+    return "[" + ", ".join(str(s) for s in steps) + "]"
+
+
+def find_next_step_file(steps_path: Path, step_number: int) -> Path | None:
+    """Find step file for a given step number."""
+    padded = f"{step_number:02d}"
+    matches = sorted([
+        f for f in steps_path.iterdir()
+        if f.is_file()
+        and (f.name.startswith(f"step-{padded}") or f.name.startswith(f"step-{step_number}-"))
+        and f.suffix == ".md"
+    ])
+    return matches[0] if matches else None
+
+
+def strip_frontmatter(content: str) -> str:
+    """Remove YAML frontmatter from step file content."""
+    if not content.startswith("---"):
+        return content
+    # Find the closing ---
+    end = content.find("---", 3)
+    if end == -1:
+        return content
+    return content[end + 3:].lstrip("\n")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Complete the current step of a stepped workflow"
+    )
+    parser.add_argument("name", nargs="?", default=None,
+                        help="Workflow name (auto-detects from session if omitted)")
+    parser.add_argument("--step", type=int, default=None, dest="step_override",
+                        help="Complete a specific step number instead of current step")
+    args = parser.parse_args()
+
+    project_root = find_project_root()
+    workflows_dir = project_root / ".pennyfarthing" / "workflows"
+    session_dir = project_root / ".session"
+
+    # Find session file
+    session_file, workflow_name = find_session_file(session_dir, args.name)
+    content = session_file.read_text()
+
+    # Parse session state
+    current_step_str = parse_session_field(content, "Current Step") or "1"
+    current_step = int(current_step_str)
+    mode = parse_session_field(content, "Mode") or "create"
+    status = parse_session_field(content, "Status") or "in_progress"
+    steps_completed_str = parse_session_field(content, "Steps Completed") or "[]"
+
+    # Check if already completed
+    if status == "completed":
+        print(f"# Workflow Already Completed: {workflow_name}")
+        print()
+        print("This workflow has already been completed.")
+        print()
+        print("To start a new session, delete the session file:")
+        print("```bash")
+        print(f'rm "{session_file}"')
+        print("```")
+        print()
+        print(f"Then run `/workflow start {workflow_name}`")
+        return 0
+
+    # Determine which step to complete
+    completing_step = args.step_override if args.step_override is not None else current_step
+
+    # Find workflow file and resolve steps path
+    workflow_file = find_workflow_file(workflows_dir, workflow_name)
+    workflow_dir = workflow_file.parent
+
+    with open(workflow_file) as f:
+        wf_data = yaml.safe_load(f)
+
+    wf = wf_data.get("workflow", {})
+
+    # Resolve steps path based on mode
+    modes = wf.get("modes", {})
+    mode_path = modes.get(mode)
+    if mode_path and mode_path != "null":
+        steps_path_str = mode_path
+    else:
+        steps_path_str = wf.get("steps", {}).get("path", ".")
+
+    # Resolve relative path
+    if steps_path_str.startswith("./"):
+        steps_path = workflow_dir / steps_path_str[2:]
+    elif not Path(steps_path_str).is_absolute():
+        steps_path = project_root / steps_path_str
+    else:
+        steps_path = Path(steps_path_str)
+
+    # Count total steps
+    step_count = count_steps(steps_path)
+
+    # Update Steps Completed array
+    steps_completed = parse_steps_completed(steps_completed_str)
+    if completing_step not in steps_completed:
+        steps_completed.append(completing_step)
+    new_steps_completed = format_steps_completed(steps_completed)
+
+    # Calculate new current step
+    next_step = completing_step + 1
+
+    # Count completed and calculate percentage
+    completed_count = len(steps_completed)
+    completion_pct = (completed_count * 100 // step_count) if step_count > 0 else 0
+
+    # Determine new status
+    new_status = "completed" if completed_count >= step_count else "in_progress"
+
+    # Update timestamp
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    # Update session file content
+    content = re.sub(
+        r"^- \*\*Current Step:\*\*.*$",
+        f"- **Current Step:** {next_step}",
+        content, flags=re.MULTILINE
+    )
+    content = re.sub(
+        r"^- \*\*Steps Completed:\*\*.*$",
+        f"- **Steps Completed:** {new_steps_completed}",
+        content, flags=re.MULTILINE
+    )
+    content = re.sub(
+        r"^- \*\*Last Updated:\*\*.*$",
+        f"- **Last Updated:** {now}",
+        content, flags=re.MULTILINE
+    )
+    content = re.sub(
+        r"^- \*\*Status:\*\*.*$",
+        f"- **Status:** {new_status}",
+        content, flags=re.MULTILINE
+    )
+    content = re.sub(
+        r"^- Completion:.*$",
+        f"- Completion: {completion_pct}%",
+        content, flags=re.MULTILINE
+    )
+
+    # Write updated session file
+    session_file.write_text(content)
+
+    # Output result
+    if new_status == "completed":
+        print(f"# Workflow Complete: {workflow_name}")
+        print()
+        print(f"All {step_count} steps completed!")
+        print()
+        print(f"**Final Progress:** {completion_pct}%")
+        print(f"**Steps Completed:** {new_steps_completed}")
+        print()
+        print(f"Session updated: {session_file}")
+    else:
+        print(f"# Step {completing_step} Complete")
+        print()
+        print(f"**Progress:** Step {next_step} of {step_count} ({completion_pct}% complete)")
+        print(f"**Steps Completed:** {new_steps_completed}")
+        print()
+        print("---")
+        print()
+        print(f"## Step {next_step} of {step_count}")
+        print()
+
+        # Find and output next step file
+        next_step_file = find_next_step_file(steps_path, next_step)
+        if next_step_file:
+            step_content = next_step_file.read_text()
+            print(strip_frontmatter(step_content))
+
+        print()
+        print("---")
+        print()
+        print("**Controls:**")
+        print("- `C` - Continue to next step")
+        print("- `/workflow status` - Check progress")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,154 @@
+#!/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
+
+# Find project root
+source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
+
+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)
+# Also handle markdown link format: [MSSCI-12721](https://...)
+JIRA_KEY=$(grep -E '\*\*Jira:\*\*' "$SESSION_FILE" | sed 's/.*\*\*Jira:\*\* //' | sed 's/\[//' | sed 's/\].*//' | 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"

package/pennyfarthing-dist/scripts/workflow/fix-session-phase.sh

@@ -0,0 +1,222 @@
+#!/bin/bash
+# Fix session file phase tracking when handoffs didn't update properly
+# Usage: fix-session-phase.sh <story-id> <target-phase> [--dry-run]
+#
+# Example: fix-session-phase.sh 56-1 review
+#          fix-session-phase.sh MSSCI-12190 approved --dry-run
+#
+# This script detects the current phase, validates the target phase is reachable,
+# and updates the session file's Workflow Tracking section:
+# - Updates **Phase:** field to target phase
+# - Adds missing rows to Phase History table
+# - Adds missing rows to Handoff History table
+#
+# Valid phases for TDD workflow: setup → red → green → review → approved → finish
+# Valid phases for trivial workflow: setup → implement → review → approved → finish
+
+set -euo pipefail
+
+STORY_ID="${1:-}"
+TARGET_PHASE="${2:-}"
+DRY_RUN=false
+
+# Parse options
+for arg in "$@"; do
+  case $arg in
+    --dry-run)
+      DRY_RUN=true
+      ;;
+  esac
+done
+
+if [[ -z "$STORY_ID" ]] || [[ -z "$TARGET_PHASE" ]]; then
+  echo "Usage: fix-session-phase.sh <story-id> <target-phase> [--dry-run]"
+  echo ""
+  echo "Arguments:"
+  echo "  story-id      Story ID (e.g., 56-1 or MSSCI-12190)"
+  echo "  target-phase  Target phase to set (e.g., review, approved, finish)"
+  echo ""
+  echo "Options:"
+  echo "  --dry-run     Show what would be done without executing"
+  echo ""
+  echo "Examples:"
+  echo "  fix-session-phase.sh 56-1 review          # Update to review phase"
+  echo "  fix-session-phase.sh 56-1 approved        # Update to approved phase"
+  echo "  fix-session-phase.sh 56-1 finish --dry-run # Preview finish update"
+  exit 1
+fi
+
+# Find project root
+source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
+
+# Try multiple session file naming patterns
+SESSION_FILE=""
+STORY_ID_LOWER=$(echo "$STORY_ID" | tr '[:upper:]' '[:lower:]')
+for pattern in "${STORY_ID}-session.md" "${STORY_ID_LOWER}-session.md"; do
+  if [[ -f "$PROJECT_ROOT/.session/$pattern" ]]; then
+    SESSION_FILE="$PROJECT_ROOT/.session/$pattern"
+    break
+  fi
+done
+
+# Also try without the epic prefix (e.g., MSSCI-12190 might be in 56-1-session.md)
+if [[ -z "$SESSION_FILE" ]]; then
+  # Search for session files containing this story ID
+  found=$(grep -l "Jira:.*$STORY_ID\|ID:.*$STORY_ID" "$PROJECT_ROOT/.session/"*-session.md 2>/dev/null | head -1 || echo "")
+  if [[ -n "$found" ]]; then
+    SESSION_FILE="$found"
+  fi
+fi
+
+if [[ -z "$SESSION_FILE" ]] || [[ ! -f "$SESSION_FILE" ]]; then
+  echo "Error: Session file not found for story $STORY_ID"
+  echo "Searched in: $PROJECT_ROOT/.session/"
+  exit 1
+fi
+
+echo "Session file: $SESSION_FILE"
+
+# Extract current state
+CURRENT_PHASE=$(grep -E '^\*\*Phase:\*\*' "$SESSION_FILE" | sed 's/\*\*Phase:\*\* //' | tr -d ' ' || echo "unknown")
+WORKFLOW=$(grep -E '^\*\*Workflow:\*\*' "$SESSION_FILE" | head -1 | sed 's/\*\*Workflow:\*\* //' | tr -d ' ' || echo "tdd")
+PHASE_STARTED=$(grep -E '^\*\*Phase Started:\*\*' "$SESSION_FILE" | sed 's/\*\*Phase Started:\*\* //' | tr -d ' ' || echo "")
+
+echo "Current phase: $CURRENT_PHASE"
+echo "Target phase: $TARGET_PHASE"
+echo "Workflow: $WORKFLOW"
+
+# Define valid phase sequences
+case "$WORKFLOW" in
+  tdd)
+    PHASES=("setup" "red" "green" "review" "approved" "finish")
+    AGENTS=("sm" "tea" "dev" "reviewer" "sm" "sm")
+    GATES=("manual" "tests_fail" "tests_pass" "approval" "complete" "")
+    ;;
+  trivial)
+    PHASES=("setup" "implement" "review" "approved" "finish")
+    AGENTS=("sm" "dev" "reviewer" "sm" "sm")
+    GATES=("manual" "tests_pass" "approval" "complete" "")
+    ;;
+  *)
+    echo "Warning: Unknown workflow '$WORKFLOW', assuming TDD"
+    PHASES=("setup" "red" "green" "review" "approved" "finish")
+    AGENTS=("sm" "tea" "dev" "reviewer" "sm" "sm")
+    GATES=("manual" "tests_fail" "tests_pass" "approval" "complete" "")
+    ;;
+esac
+
+# Find indices
+CURRENT_IDX=-1
+TARGET_IDX=-1
+for i in "${!PHASES[@]}"; do
+  if [[ "${PHASES[$i]}" == "$CURRENT_PHASE" ]]; then
+    CURRENT_IDX=$i
+  fi
+  if [[ "${PHASES[$i]}" == "$TARGET_PHASE" ]]; then
+    TARGET_IDX=$i
+  fi
+done
+
+if [[ $CURRENT_IDX -eq -1 ]]; then
+  echo "Error: Current phase '$CURRENT_PHASE' not found in $WORKFLOW workflow"
+  echo "Valid phases: ${PHASES[*]}"
+  exit 1
+fi
+
+if [[ $TARGET_IDX -eq -1 ]]; then
+  echo "Error: Target phase '$TARGET_PHASE' not found in $WORKFLOW workflow"
+  echo "Valid phases: ${PHASES[*]}"
+  exit 1
+fi
+
+if [[ $TARGET_IDX -le $CURRENT_IDX ]]; then
+  echo "Error: Target phase '$TARGET_PHASE' is not ahead of current phase '$CURRENT_PHASE'"
+  echo "Phase sequence: ${PHASES[*]}"
+  exit 1
+fi
+
+# Calculate what transitions are needed
+echo ""
+echo "Transitions needed:"
+NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+TRANSITIONS=()
+
+for ((i=CURRENT_IDX; i<TARGET_IDX; i++)); do
+  FROM_PHASE="${PHASES[$i]}"
+  TO_PHASE="${PHASES[$((i+1))]}"
+  FROM_AGENT="${AGENTS[$i]}"
+  TO_AGENT="${AGENTS[$((i+1))]}"
+  GATE="${GATES[$((i+1))]}"
+
+  echo "  $FROM_PHASE ($FROM_AGENT) → $TO_PHASE ($TO_AGENT) [gate: $GATE]"
+  TRANSITIONS+=("$FROM_PHASE|$TO_PHASE|$FROM_AGENT|$TO_AGENT|$GATE")
+done
+
+if [[ "$DRY_RUN" == "true" ]]; then
+  echo ""
+  echo "[DRY RUN] Would update session file with:"
+  echo "  - **Phase:** $TARGET_PHASE"
+  echo "  - **Phase Started:** $NOW"
+  echo "  - Phase History: close out $CURRENT_PHASE, add intermediate phases"
+  echo "  - Handoff History: add ${#TRANSITIONS[@]} handoff(s)"
+  exit 0
+fi
+
+echo ""
+echo "Updating session file..."
+
+# Build the Phase History additions
+PHASE_HISTORY_ADDITIONS=""
+HANDOFF_HISTORY_ADDITIONS=""
+PREV_END="$NOW"
+
+for transition in "${TRANSITIONS[@]}"; do
+  IFS='|' read -r FROM_PHASE TO_PHASE FROM_AGENT TO_AGENT GATE <<< "$transition"
+
+  # Add phase history row (close out the FROM phase)
+  # We'll use NOW for ended time since we don't know actual times
+  PHASE_HISTORY_ADDITIONS+="| $FROM_PHASE | - | $NOW | - |\n"
+
+  # Add handoff history row
+  HANDOFF_HISTORY_ADDITIONS+="| $FROM_AGENT | $TO_AGENT | $GATE | PASSED | $NOW |\n"
+done
+
+# Update the **Phase:** line
+sed -i.bak "s/^\*\*Phase:\*\*.*/\*\*Phase:\*\* $TARGET_PHASE/" "$SESSION_FILE"
+
+# Update the **Phase Started:** line
+sed -i.bak "s/^\*\*Phase Started:\*\*.*/\*\*Phase Started:\*\* $NOW/" "$SESSION_FILE"
+
+# Close out the current phase in Phase History (update the row that has "| - | - |" at the end)
+# This is tricky - we need to find the row for current phase and add end time
+# For now, we'll add a note about manual review needed
+
+# Add handoff history rows before the "## Story Context" section
+if [[ -n "$HANDOFF_HISTORY_ADDITIONS" ]]; then
+  # Find the last handoff history row and add after it
+  # The handoff history table ends before a blank line or next section
+
+  # Use awk to insert after the last handoff history row
+  awk -v additions="$HANDOFF_HISTORY_ADDITIONS" '
+    /^\| .* \| .* \| .* \| .* \| .*\|$/ && /PASSED|FAILED/ {
+      last_handoff = NR
+      last_handoff_line = $0
+    }
+    {
+      print
+      if (NR == last_handoff && additions != "") {
+        printf "%s", additions
+      }
+    }
+  ' "$SESSION_FILE" > "$SESSION_FILE.tmp" && mv "$SESSION_FILE.tmp" "$SESSION_FILE"
+fi
+
+# Clean up backup
+rm -f "$SESSION_FILE.bak"
+
+echo ""
+echo "✓ Session file updated"
+echo "  Phase: $CURRENT_PHASE → $TARGET_PHASE"
+echo "  Handoffs added: ${#TRANSITIONS[@]}"
+echo ""
+echo "Note: Phase History end times set to now. Review and adjust if needed."