@pennyfarthing/core 10.4.0 → 11.0.0

package/pennyfarthing_scripts/session_start_hook.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""Session start hook — initialize environment for Claude Code session.
+
+Handles:
+1. Session directory setup and logging
+2. Checkpoint validation (cross-session drift detection)
+3. WheelHub auto-start (ensure BikeRack server is running)
+4. OTEL auto-configuration via CLAUDE_ENV_FILE
+
+Called by Claude Code SessionStart hook via shell wrapper.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def _read_input() -> dict:
+    """Read JSON from stdin (hook protocol)."""
+    raw = sys.stdin.read()
+    try:
+        return json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        return {}
+
+
+def _setup_session_dir(project_dir: Path, session_id: str, source_type: str) -> None:
+    """Ensure .session directory exists and log session start."""
+    session_dir = project_dir / ".session"
+    session_dir.mkdir(parents=True, exist_ok=True)
+    (session_dir / "agents").mkdir(exist_ok=True)
+
+    from datetime import UTC, datetime
+
+    timestamp = datetime.now(UTC).isoformat()
+    log_file = session_dir / "session-log.txt"
+    with open(log_file, "a") as f:
+        f.write(f"{timestamp} | Session {source_type}: {session_id}\n")
+
+
+def _validate_checkpoint(project_dir: Path) -> None:
+    """Validate previous session checkpoint for cross-session drift detection."""
+    try:
+        import subprocess
+
+        script_dir = Path(__file__).resolve().parent.parent
+        checkpoint_lib = script_dir / "pennyfarthing-dist" / "scripts" / "lib" / "checkpoint.sh"
+
+        if not checkpoint_lib.exists():
+            return
+
+        result = subprocess.run(
+            ["bash", "-c", f'source "{checkpoint_lib}" && checkpoint_restore session_state'],
+            capture_output=True,
+            text=True,
+            cwd=str(project_dir),
+            timeout=5,
+        )
+
+        prev_state = result.stdout.strip()
+        if not prev_state:
+            return
+
+        # Parse checkpoint data
+        fields = {}
+        for part in prev_state.split(";"):
+            if "=" in part:
+                k, v = part.split("=", 1)
+                fields[k] = v
+
+        prev_sha = fields.get("sha", "")
+        if not prev_sha:
+            return
+
+        # Get current git SHA
+        result = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"],
+            capture_output=True,
+            text=True,
+            cwd=str(project_dir),
+            timeout=5,
+        )
+        current_sha = result.stdout.strip()
+        if not current_sha or current_sha == prev_sha:
+            return
+
+        # Log drift
+        from datetime import UTC, datetime
+
+        timestamp = datetime.now(UTC).isoformat()
+        session_dir = project_dir / ".session"
+
+        warning = f"CROSS_SESSION_DRIFT: Git changed (was: {prev_sha}, now: {current_sha})"
+        if fields.get("story"):
+            warning += f" | Story: {fields['story']}"
+        if fields.get("agent"):
+            warning += f" | Agent: {fields['agent']}"
+
+        with open(session_dir / "session-log.txt", "a") as f:
+            f.write(f"{timestamp} | {warning}\n")
+
+        drift_entry = f"{timestamp} | prev_sha={prev_sha} | current_sha={current_sha}"
+        for key in ("story", "agent", "phase"):
+            if fields.get(key):
+                drift_entry += f" | {key}={fields[key]}"
+        with open(session_dir / "drift-log.txt", "a") as f:
+            f.write(drift_entry + "\n")
+
+    except Exception:
+        pass
+
+
+def _ensure_wheelhub(project_dir: Path) -> int | None:
+    """Auto-start WheelHub if not already running. Returns port or None."""
+    from pennyfarthing_scripts.bikerack.launcher import (
+        is_already_running,
+        poll_for_port_file,
+        start_wheelhub,
+        write_pid_file,
+    )
+
+    # Skip if full Cyclist is running
+    cyclist_port_file = project_dir / ".cyclist-port"
+    if cyclist_port_file.exists():
+        try:
+            return int(cyclist_port_file.read_text().strip())
+        except (ValueError, OSError):
+            return None
+
+    # Check if BikeRack WheelHub is already running
+    running, _pid, port = is_already_running(project_dir)
+    if running:
+        return port
+
+    # Start WheelHub
+    try:
+        proc = start_wheelhub(project_dir)
+        write_pid_file(project_dir, proc.pid)
+        return poll_for_port_file(project_dir)
+    except Exception:
+        return None
+
+
+def _write_env_file(project_dir: Path, session_id: str, otel_port: int | None) -> None:
+    """Write environment variables to CLAUDE_ENV_FILE."""
+    env_file = os.environ.get("CLAUDE_ENV_FILE")
+    if not env_file:
+        return
+
+    lines = [
+        "# Pennyfarthing core environment",
+        f'export PROJECT_ROOT="{project_dir}"',
+        f'export SESSION_ID="{session_id}"',
+    ]
+
+    if otel_port is not None:
+        lines.extend([
+            "# OTEL auto-configuration for Cyclist/WheelHub",
+            'export OTEL_EXPORTER_OTLP_PROTOCOL="http/json"',
+            f'export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:{otel_port}"',
+        ])
+
+    with open(env_file, "a") as f:
+        f.write("\n".join(lines) + "\n")
+
+
+def main() -> None:
+    """Entry point for SessionStart hook."""
+    try:
+        input_data = _read_input()
+        session_id = input_data.get("session_id", "unknown")
+        source_type = input_data.get("source", "unknown")
+
+        project_dir = Path(os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd()))
+
+        _setup_session_dir(project_dir, session_id, source_type)
+        _validate_checkpoint(project_dir)
+
+        otel_port = _ensure_wheelhub(project_dir)
+        _write_env_file(project_dir, session_id, otel_port)
+
+    except Exception:
+        pass
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/pennyfarthing_scripts/sprint/archive_epic.py

@@ -98,6 +98,99 @@ completed_stories:
     return archive_path
 
 
+def migrate_completed_archive(archive_path: Path) -> dict[str, Any]:
+    """Migrate a monolithic completed archive to index+shard format.
+
+    Extracts inlined stories from completed_stories, groups them by epic,
+    writes per-epic shard files to the archive directory, and removes
+    migrated stories from the index (keeping only orphans).
+
+    Args:
+        archive_path: Path to the sprint archive YAML file
+
+    Returns:
+        Dict with migration results {success, shards_created, stories_migrated}
+    """
+    archive_dir = archive_path.parent
+    data = _load_archive_file(archive_path)
+    epic_refs = set(data["completed_epics"])
+
+    # Group stories by epic ref
+    epic_stories: dict[str, list[dict[str, Any]]] = {}
+    orphans: list[dict[str, Any]] = []
+    for story in data["completed_stories"]:
+        epic = story.get("epic", "")
+        if epic in epic_refs:
+            epic_stories.setdefault(epic, []).append(story)
+        else:
+            orphans.append(story)
+
+    # Write per-epic shard files
+    shards_created = 0
+    stories_migrated = 0
+    for epic_ref, stories in epic_stories.items():
+        shard_path = archive_dir / f"epic-{epic_ref}.yaml"
+        if shard_path.exists():
+            existing = _read_yaml_file(shard_path)
+            existing_ids = {s["id"] for s in existing.get("stories", [])}
+            merged = list(existing.get("stories", []))
+            for s in stories:
+                if s["id"] not in existing_ids:
+                    merged.append(s)
+            existing["stories"] = merged
+            _write_yaml_file(shard_path, existing)
+        else:
+            shard_data = {
+                "jira": epic_ref,
+                "status": "done",
+                "stories": stories,
+            }
+            _write_yaml_file(shard_path, shard_data)
+            shards_created += 1
+        stories_migrated += len(stories)
+
+    # Update the index: keep only orphans
+    data["completed_stories"] = orphans
+    _write_archive_file(archive_path, data)
+
+    return {
+        "success": True,
+        "shards_created": shards_created,
+        "stories_migrated": stories_migrated,
+    }
+
+
+def load_archive(archive_path: Path) -> dict[str, Any]:
+    """Load the archive index and merge stories from shard files.
+
+    Like load_sprint() for the active sprint, this reads the index file
+    and merges stories from per-epic shard files in the same directory.
+
+    Args:
+        archive_path: Path to the sprint archive YAML file
+
+    Returns:
+        Unified archive dict with all completed_stories from shards + orphans
+    """
+    data = _load_archive_file(archive_path)
+    archive_dir = archive_path.parent
+
+    # Collect stories from shards
+    all_stories: list[dict[str, Any]] = []
+    for epic_ref in data["completed_epics"]:
+        shard_path = archive_dir / f"epic-{epic_ref}.yaml"
+        if shard_path.exists():
+            shard = _read_yaml_file(shard_path)
+            all_stories.extend(shard.get("stories", []))
+
+    # Add orphans from index
+    all_stories.extend(data["completed_stories"])
+
+    result = dict(data)
+    result["completed_stories"] = all_stories
+    return result
+
+
 def _load_archive_file(archive_path: Path) -> dict[str, Any]:
     """Load the sprint archive file, handling both old and new formats.
 
@@ -329,13 +422,28 @@ def archive_epic(
             context_moved = ctx_name
             break
 
-    # 3. Add epic ref to sprint completed file
+    # 3. Add epic ref and completed stories to sprint completed file
     archive_path = ensure_archive_file(root)
     archive_data = _load_archive_file(archive_path)
 
     # Add ref if not already present
     if epic_ref not in archive_data["completed_epics"]:
         archive_data["completed_epics"].append(epic_ref)
+
+    # Add each completed story to completed_stories list
+    existing_ids = {s.get("id") for s in archive_data["completed_stories"]}
+    epic_jira_ref = epic.get("jira", epic_ref)
+    for story in epic.get("stories", []):
+        story_id = story.get("id", "")
+        if story_id and story_id not in existing_ids:
+            archive_data["completed_stories"].append({
+                "id": story_id,
+                "epic": epic_jira_ref,
+                "title": story.get("title", ""),
+                "points": story.get("points", 0),
+                "completed": story.get("completed", date.today().isoformat()),
+            })
+
     _write_archive_file(archive_path, archive_data)
 
     # 4. Remove epic from current-sprint.yaml index

package/pennyfarthing_scripts/sprint/cli.py

@@ -301,8 +301,9 @@ def story_finish(story_id: str, dry_run: bool):
         return
 
     click.echo(f"=== Story {story_id} Complete ===")
-    jira_key = result.get("jira_key", "")
-    click.echo(f"Jira: https://1898andco.atlassian.net/browse/{jira_key}")
+    jira_key = result.get("jira_key")
+    if jira_key:
+        click.echo(f"Jira: https://1898andco.atlassian.net/browse/{jira_key}")
     for step in result.get("steps", []):
         warning = step.get("warning", "")
         error = step.get("error", "")
@@ -313,13 +314,18 @@ def story_finish(story_id: str, dry_run: bool):
 @story.command("claim")
 @click.argument("story_id")
 @click.option("--claim/--unclaim", default=True, help="Claim or unclaim the story")
-def story_claim(story_id: str, claim: bool):
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def story_claim(story_id: str, claim: bool, dry_run: bool):
     """Claim or unclaim a story in Jira.
 
     \b
     Arguments:
       STORY_ID  - Story ID / Jira key to claim
     """
+    if dry_run:
+        action = "claim" if claim else "unclaim"
+        click.echo(f"[DRY-RUN] Would {action} {story_id}")
+        return
     from pennyfarthing_scripts.jira.claim import claim_issue, unclaim_issue
 
     if claim:
@@ -817,7 +823,8 @@ def epic_remove(epic_id: str, dry_run: bool):
 
 @epic.command("promote")
 @click.argument("epic_id")
-def epic_promote(epic_id: str):
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def epic_promote(epic_id: str, dry_run: bool):
     """Move an epic from future initiatives to current-sprint.yaml.
 
     Detects ID collisions and assigns new IDs if needed.
@@ -931,6 +938,10 @@ def epic_promote(epic_id: str):
     click.echo(f"  Stories: {story_count}")
     click.echo("")
 
+    if dry_run:
+        click.echo(f"\n[DRY-RUN] Would promote {original_id} ({story_count} stories) to current sprint")
+        return
+
     # Validate epic shard before writing (ADR-0022)
     from pennyfarthing_scripts.sprint.validator import validate_epic_shard
     validation = validate_epic_shard(dict(epic_data))
@@ -950,11 +961,8 @@ def epic_promote(epic_id: str):
         init_data = yaml.safe_load(f.read())
 
     if isinstance(source_ref, str):
-        # String ref — remove from list and delete shard file
+        # String ref — remove from initiative list (shard file is kept for current sprint)
         init_data["epics"] = [e for e in init_data.get("epics", []) if e != source_ref]
-        shard = _epic_shard_path(sprint_dir, source_ref)
-        if shard.exists():
-            shard.unlink()
     else:
         # Inline dict — remove matching entry
         init_data["epics"] = [
@@ -1000,6 +1008,11 @@ from pennyfarthing_scripts.sprint.epic_add import epic_add_command  # noqa: E402
 
 epic.add_command(epic_add_command, "add")
 
+# Register epic-update as epic.update
+from pennyfarthing_scripts.sprint.epic_update import epic_update_command  # noqa: E402
+
+epic.add_command(epic_update_command, "update")
+
 
 # --- Initiative subgroup ---
 
@@ -1716,7 +1729,8 @@ def _show_future_epic_detail(epic_id: str, init_files, sprint_dir):
 @click.argument("start_date")
 @click.argument("end_date")
 @click.argument("goal")
-def new_sprint(sprint_yyww: str, jira_id: int, start_date: str, end_date: str, goal: str):
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def new_sprint(sprint_yyww: str, jira_id: int, start_date: str, end_date: str, goal: str, dry_run: bool):
     """Initialize a new sprint.
 
     \b
@@ -1750,6 +1764,13 @@ def new_sprint(sprint_yyww: str, jira_id: int, start_date: str, end_date: str, g
                 click.echo("Aborted.")
                 return
 
+    if dry_run:
+        click.echo(f"[DRY-RUN] Would initialize sprint TO Sprint {sprint_yyww}")
+        click.echo(f"  Jira ID: {jira_id}")
+        click.echo(f"  Dates: {start_date} to {end_date}")
+        click.echo(f"  Goal: {goal}")
+        return
+
     # Create sprint file using write_sprint for consistency
     from pennyfarthing_scripts.sprint.yaml_io import write_sprint
 

package/pennyfarthing_scripts/sprint/epic_add.py

@@ -137,12 +137,13 @@ def add_epic(
 @click.command("epic-add")
 @click.argument("epic_id", type=str)
 @click.argument("title", type=str)
-@click.option("--priority", type=click.Choice(["P0", "P1", "P2", "P3"]), default="P1")
+@click.option("--priority", type=click.Choice(["p0", "p1", "p2", "p3"], case_sensitive=False), default="p1")
 @click.option("--status", type=click.Choice(["backlog", "ready", "in_progress"]), default="backlog")
 @click.option("--repos", default="pennyfarthing")
 @click.option("--jira", "jira_id", type=str, default=None, help="Jira epic key (MSSCI-NNNNN)")
 @click.option("--description", "-d", type=str, default=None, help="Epic description")
 @click.option("--sprint-file", type=click.Path(), default=None, help="Path to sprint YAML file")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
 def epic_add_command(
     epic_id: str,
     title: str,
@@ -152,8 +153,13 @@ def epic_add_command(
     jira_id: str | None,
     description: str | None,
     sprint_file: str | None,
+    dry_run: bool,
 ) -> None:
     """Add a new epic to the current sprint."""
+    if dry_run:
+        click.echo(f"[DRY-RUN] Would add epic {epic_id}: {title}")
+        return
+
     if sprint_file is None:
         from pennyfarthing_scripts.common.config import get_project_root
         path = get_project_root() / "sprint" / "current-sprint.yaml"

package/pennyfarthing_scripts/sprint/epic_update.py

@@ -0,0 +1,148 @@
+"""Sprint epic update command.
+
+Provides:
+- update_epic(sprint_path, epic_id, ...) -> dict
+- epic_update_command (Click command for CLI registration)
+"""
+
+from pathlib import Path
+from typing import Any
+
+import click
+
+from pennyfarthing_scripts.sprint.loader import find_epic
+from pennyfarthing_scripts.sprint.yaml_io import read_sprint, write_sprint
+
+VALID_EPIC_STATUSES = {"backlog", "in_progress", "done", "canceled"}
+
+
+def update_epic(
+    sprint_path: Path,
+    epic_id: str,
+    *,
+    status: str | None = None,
+    priority: str | None = None,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Update fields on an epic in the sprint YAML.
+
+    Args:
+        sprint_path: Path to sprint YAML file
+        epic_id: Epic ID (e.g., "103" or "MSSCI-14951")
+        status: New status value
+        priority: New priority value
+        dry_run: If True, report changes without writing
+
+    Returns:
+        Dict with success status and optional error
+    """
+    if status is not None and status not in VALID_EPIC_STATUSES:
+        return {
+            "success": False,
+            "error": f"Invalid status '{status}'. Must be one of: {', '.join(sorted(VALID_EPIC_STATUSES))}",
+        }
+
+    data = read_sprint(sprint_path)
+
+    epic = find_epic(data, epic_id)
+    if epic is None:
+        return {
+            "success": False,
+            "error": f"Epic '{epic_id}' not found in sprint",
+        }
+
+    changes = {}
+
+    if status is not None:
+        old = epic.get("status")
+        epic["status"] = status
+        changes["status"] = f"{old} -> {status}"
+
+    if priority is not None:
+        old = epic.get("priority")
+        epic["priority"] = priority
+        changes["priority"] = f"{old} -> {priority}"
+
+    if not changes:
+        return {
+            "success": False,
+            "error": "No fields to update. Pass --status or --priority.",
+        }
+
+    if dry_run:
+        return {
+            "success": True,
+            "dry_run": True,
+            "epic_id": str(epic.get("id", epic_id)),
+            "changes": changes,
+        }
+
+    write_sprint(sprint_path, data)
+
+    return {
+        "success": True,
+        "epic_id": str(epic.get("id", epic_id)),
+        "changes": changes,
+    }
+
+
+@click.command("update")
+@click.argument("epic_id")
+@click.option(
+    "--status",
+    type=click.Choice(sorted(VALID_EPIC_STATUSES)),
+    help="New epic status",
+)
+@click.option("--priority", help="New priority (e.g., P0, P1)")
+@click.option("--dry-run", is_flag=True, help="Show changes without writing")
+@click.option(
+    "--sprint-file",
+    type=click.Path(),
+    default=None,
+    help="Path to sprint YAML file",
+)
+def epic_update_command(
+    epic_id: str,
+    status: str | None,
+    priority: str | None,
+    dry_run: bool,
+    sprint_file: str | None,
+) -> None:
+    """Update an epic's fields by ID.
+
+    \b
+    Arguments:
+      EPIC_ID  - Epic ID (e.g., 103, epic-103, or MSSCI-14951)
+
+    \b
+    Examples:
+      pf sprint epic update 103 --status in_progress
+      pf sprint epic update MSSCI-14951 --status in_progress
+      pf sprint epic update 103 --priority P0 --dry-run
+    """
+    if sprint_file is None:
+        from pennyfarthing_scripts.common.config import get_project_root
+
+        path = get_project_root() / "sprint" / "current-sprint.yaml"
+    else:
+        path = Path(sprint_file)
+
+    result = update_epic(
+        sprint_path=path,
+        epic_id=epic_id,
+        status=status,
+        priority=priority,
+        dry_run=dry_run,
+    )
+
+    if result["success"]:
+        if result.get("dry_run"):
+            click.echo(f"[DRY-RUN] Would update epic {result['epic_id']}:")
+            for field, change in result.get("changes", {}).items():
+                click.echo(f"  {field}: {change}")
+        else:
+            click.echo(f"Updated epic {result['epic_id']}:")
+            for field, change in result.get("changes", {}).items():
+                click.echo(f"  {field}: {change}")
+    else:
+        raise click.ClickException(result["error"])