@pennyfarthing/core 11.2.1 → 11.2.2

package/pennyfarthing_scripts/sprint/loader.py

@@ -1,15 +1,23 @@
 """
 Sprint YAML parsing utilities for Pennyfarthing scripts.
 
-Provides access to sprint/current-sprint.yaml data.
-Supports sharded per-epic format (epic-{ref}.yaml shard files).
+Provides access to sprint data with support for:
+- Default sprint: sprint/current-sprint.yaml
+- Multi-sprint registry: sprint/sprints.yaml with per-user preference
+  stored in .pennyfarthing/config.local.yaml
+- Sharded per-epic format: epic-{ref}.yaml shard files
 """
 
 import warnings
 from pathlib import Path
 from typing import Any
 
-from pennyfarthing_scripts.common.config import get_project_root, load_yaml_config
+from pennyfarthing_scripts.common.config import (
+    get_project_root,
+    load_pennyfarthing_config,
+    load_yaml_config,
+    save_pennyfarthing_config_key,
+)
 
 
 def _merge_epic_shards(data: dict[str, Any], sprint_dir: Path) -> dict[str, Any]:
@@ -101,6 +109,12 @@ def _merge_epic_shards(data: dict[str, Any], sprint_dir: Path) -> dict[str, Any]
 def load_sprint(project_root: Path | None = None) -> dict[str, Any] | None:
     """Load sprint data from project root.
 
+    Resolution order:
+      1. Check .pennyfarthing/config.local.yaml for sprint.active preference
+      2. If set, look up the sprint in sprint/sprints.yaml registry
+      3. Load the referenced sprint file (resolved relative to sprint/)
+      4. If no preference or no registry, fall back to sprint/current-sprint.yaml
+
     Supports both monolithic and sharded epic formats. When epics are
     string references, the corresponding epic-{ref}.yaml files are
     loaded and merged transparently.
@@ -113,6 +127,30 @@ def load_sprint(project_root: Path | None = None) -> dict[str, Any] | None:
     """
     root = project_root or get_project_root()
     sprint_dir = root / "sprint"
+
+    # Check for per-user sprint preference
+    active_name = get_active_sprint_name(root)
+    if active_name:
+        registry = load_sprint_registry(root)
+        if registry:
+            sprints = registry.get("sprints", {})
+            sprint_entry = sprints.get(active_name)
+            if sprint_entry and sprint_entry.get("file"):
+                sprint_path = (sprint_dir / sprint_entry["file"]).resolve()
+                if sprint_path.exists():
+                    data = load_yaml_config(sprint_path)
+                    if data is not None:
+                        # Inject registry metadata for downstream consumers
+                        data["_registry"] = {
+                            "name": active_name,
+                            "type": sprint_entry.get("type", "project"),
+                            "context_root": sprint_entry.get("context_root"),
+                            "session_root": sprint_entry.get("session_root"),
+                            "docs": sprint_entry.get("docs", {}),
+                        }
+                        return _merge_epic_shards(data, sprint_path.parent)
+
+    # Default: load sprint/current-sprint.yaml
     sprint_path = sprint_dir / "current-sprint.yaml"
     data = load_yaml_config(sprint_path)
     if data is None:
@@ -121,6 +159,119 @@ def load_sprint(project_root: Path | None = None) -> dict[str, Any] | None:
     return _merge_epic_shards(data, sprint_dir)
 
 
+def load_sprint_registry(project_root: Path | None = None) -> dict[str, Any] | None:
+    """Load sprint registry from sprint/sprints.yaml.
+
+    The sprint registry indexes multiple parallel sprints (e.g., a main
+    project sprint and research spike sprints). Each entry maps a sprint
+    name to its YAML file path, type, and metadata.
+
+    Args:
+        project_root: Project root path (defaults to auto-detect)
+
+    Returns:
+        Registry data as dict, or None if no registry exists
+    """
+    root = project_root or get_project_root()
+    registry_path = root / "sprint" / "sprints.yaml"
+    return load_yaml_config(registry_path)
+
+
+def get_active_sprint_name(project_root: Path | None = None) -> str | None:
+    """Get the name of the currently active sprint.
+
+    Reads the per-user preference from .pennyfarthing/config.local.yaml
+    (sprint.active key). Returns None if no preference is set, meaning
+    the default sprint/current-sprint.yaml should be used.
+
+    Args:
+        project_root: Project root path (defaults to auto-detect)
+
+    Returns:
+        Active sprint name, or None if using the default sprint
+    """
+    root = project_root or get_project_root()
+    config = load_pennyfarthing_config(root)
+    sprint_config = config.get("sprint", {})
+    if isinstance(sprint_config, dict):
+        return sprint_config.get("active")
+    return None
+
+
+def switch_sprint(name: str, project_root: Path | None = None) -> dict[str, Any]:
+    """Switch the active sprint by updating the per-user preference.
+
+    Validates the sprint name against sprint/sprints.yaml, then writes
+    the selection to .pennyfarthing/config.local.yaml (gitignored,
+    per-user). Does not modify any shared repo files.
+
+    Use name "default" to clear the preference and revert to the
+    project's sprint/current-sprint.yaml.
+
+    Args:
+        name: Sprint name from the registry (e.g., "main", "ocsf-rs1")
+              or "default" to clear the preference
+        project_root: Project root path (defaults to auto-detect)
+
+    Returns:
+        Dict with 'success', 'message', and optional 'error' or 'sprint'
+    """
+    root = project_root or get_project_root()
+
+    # "default" clears the preference
+    if name == "default":
+        config = load_pennyfarthing_config(root)
+        sprint_config = config.get("sprint", {})
+        if isinstance(sprint_config, dict) and "active" in sprint_config:
+            del sprint_config["active"]
+            if not sprint_config:
+                save_pennyfarthing_config_key("sprint", {}, root)
+            else:
+                save_pennyfarthing_config_key("sprint", sprint_config, root)
+        return {
+            "success": True,
+            "message": "Cleared sprint preference — using default sprint/current-sprint.yaml",
+        }
+
+    registry = load_sprint_registry(root)
+
+    if registry is None:
+        return {"success": False, "error": "No sprint registry found (sprint/sprints.yaml)"}
+
+    sprints = registry.get("sprints", {})
+    if name not in sprints:
+        available = ", ".join(sprints.keys())
+        return {"success": False, "error": f"Unknown sprint: {name}. Available: {available}"}
+
+    sprint_entry = sprints[name]
+    sprint_file = sprint_entry.get("file")
+    if not sprint_file:
+        return {"success": False, "error": f"Sprint '{name}' has no file configured"}
+
+    # Verify the target sprint file exists
+    sprint_dir = root / "sprint"
+    target_path = (sprint_dir / sprint_file).resolve()
+    if not target_path.exists():
+        return {
+            "success": False,
+            "error": f"Sprint file not found: {sprint_file} (resolved to {target_path})",
+        }
+
+    # Write preference to config.local.yaml (per-user, gitignored)
+    config = load_pennyfarthing_config(root)
+    sprint_config = config.get("sprint", {})
+    if not isinstance(sprint_config, dict):
+        sprint_config = {}
+    sprint_config["active"] = name
+    save_pennyfarthing_config_key("sprint", sprint_config, root)
+
+    return {
+        "success": True,
+        "message": f"Switched to sprint: {name}",
+        "sprint": sprint_entry,
+    }
+
+
 def find_epic(sprint_data: dict[str, Any], epic_num: str) -> dict[str, Any] | None:
     """Find epic in sprint data (handles various ID formats).
 

package/pennyfarthing_scripts/sprint/story_update.py

@@ -30,6 +30,7 @@ def update_story(
     completed_date: str | None = None,
     started_date: str | None = None,
     workflow: str | None = None,
+    description: str | None = None,
     review_findings: str | None = None,
     review_verdict: str | None = None,
     dry_run: bool = False,
@@ -46,6 +47,7 @@ def update_story(
         completed_date: Completed date (ISO format)
         started_date: Started date (ISO format)
         workflow: Workflow type (tdd, trivial, bdd, agent-docs)
+        description: Story description text
         review_findings: Reviewer findings text
         review_verdict: Review verdict (approved, rejected, pending)
         dry_run: If True, report changes without writing
@@ -101,6 +103,8 @@ def update_story(
         story["started"] = started_date
     if workflow is not None:
         story["workflow"] = workflow
+    if description is not None:
+        story["description"] = description
     if review_findings is not None:
         story["review_findings"] = review_findings
     if review_verdict is not None:
@@ -166,6 +170,7 @@ def update_story(
 @click.option("--priority", default=None)
 @click.option("--started", "started_date", default=None)
 @click.option("--workflow", default=None)
+@click.option("--description", default=None, help="Story description text")
 @click.option("--review-findings", default=None, help="Reviewer findings text")
 @click.option("--review-verdict", type=click.Choice(["approved", "rejected", "pending"]), default=None)
 @click.option("--dry-run", is_flag=True)
@@ -179,6 +184,7 @@ def story_update_command(
     priority: str | None,
     started_date: str | None,
     workflow: str | None,
+    description: str | None,
     review_findings: str | None,
     review_verdict: str | None,
     dry_run: bool,
@@ -201,6 +207,7 @@ def story_update_command(
         completed_date=completed_date,
         started_date=started_date,
         workflow=workflow,
+        description=description,
         review_findings=review_findings,
         review_verdict=review_verdict,
         dry_run=dry_run,

package/pennyfarthing_scripts/tests/test_bikerack.py

@@ -5,14 +5,14 @@ Epic: 101 — BikeRack Mode (ADR-0024)
 
 Acceptance Criteria:
 - [AC1]  `pf bikerack start` starts WheelHub background with IS_BIKERACK=1
-- [AC2]  Polls for .wheelhub-port file (100ms interval, 5s timeout)
+- [AC2]  Polls for .bikerack-port file (100ms interval, 5s timeout)
 - [AC3]  Sets exactly 5 OTEL env vars from discovered port (Rule 5)
 - [AC4]  Uses exec (not spawn) for Claude CLI (CE-4)
 - [AC5]  trap EXIT registered before exec to kill WheelHub PID (Rule 8)
 - [AC6]  Writes .wheelhub-pid after spawning WheelHub
 - [AC7]  `pf bikerack stop` reads PID, sends SIGTERM, deletes files
 - [AC8]  `pf bikerack status` shows running state (PID, port, uptime)
-- [AC9]  Error if already running (.wheelhub-port exists with live PID)
+- [AC9]  Error if already running (.bikerack-port exists with live PID)
 - [AC10] Exit code 1 if WheelHub fails to start, 2 if already running
 - [AC11] Prints dashboard URL on startup
 - [AC12] `just bikerack` works as alias
@@ -101,7 +101,7 @@ class TestStartWheelHub:
 
 
 # ---------------------------------------------------------------------------
-# AC2: Polls for .wheelhub-port file (100ms interval, 5s timeout)
+# AC2: Polls for .bikerack-port file (100ms interval, 5s timeout)
 # ---------------------------------------------------------------------------
 
 
@@ -110,7 +110,7 @@ class TestPortFilePolling:
 
     def test_returns_port_when_file_exists(self, tmp_path: Path) -> None:
         """poll_for_port_file should return port number from file."""
-        port_file = tmp_path / ".wheelhub-port"
+        port_file = tmp_path / ".bikerack-port"
         port_file.write_text("2898")
 
         result = poll_for_port_file(tmp_path)
@@ -125,7 +125,7 @@ class TestPortFilePolling:
 
     def test_waits_for_file_to_appear(self, tmp_path: Path) -> None:
         """poll_for_port_file should poll until file appears."""
-        port_file = tmp_path / ".wheelhub-port"
+        port_file = tmp_path / ".bikerack-port"
 
         # Simulate file appearing after short delay
         call_count = [0]
@@ -160,7 +160,7 @@ class TestPortFilePolling:
 
     def test_reads_integer_port(self, tmp_path: Path) -> None:
         """poll_for_port_file should parse port as integer."""
-        port_file = tmp_path / ".wheelhub-port"
+        port_file = tmp_path / ".bikerack-port"
         port_file.write_text("3000\n")  # Trailing newline should be handled
 
         result = poll_for_port_file(tmp_path)
@@ -340,8 +340,8 @@ class TestCleanupRegistration:
                 assert kill_args[1] == signal.SIGTERM
 
     def test_cleanup_removes_port_file(self, tmp_path: Path) -> None:
-        """Registered cleanup should delete .wheelhub-port file."""
-        port_file = tmp_path / ".wheelhub-port"
+        """Registered cleanup should delete .bikerack-port file."""
+        port_file = tmp_path / ".bikerack-port"
         port_file.write_text("2898")
 
         cleanup_func = None
@@ -363,7 +363,7 @@ class TestCleanupRegistration:
             except (ProcessLookupError, OSError):
                 pass
 
-        assert not port_file.exists(), ".wheelhub-port should be deleted by cleanup"
+        assert not port_file.exists(), ".bikerack-port should be deleted by cleanup"
 
     def test_cleanup_removes_pid_file(self, tmp_path: Path) -> None:
         """Registered cleanup should delete .wheelhub-pid file."""
@@ -443,7 +443,7 @@ class TestStopBikeRack:
     def test_sends_sigterm_to_pid(self, tmp_path: Path) -> None:
         """stop_bikerack should send SIGTERM to the WheelHub PID."""
         # Setup: create port and pid files
-        (tmp_path / ".wheelhub-port").write_text("2898")
+        (tmp_path / ".bikerack-port").write_text("2898")
         (tmp_path / ".wheelhub-pid").write_text("12345")
 
         with patch("pennyfarthing_scripts.bikerack.launcher.os.kill") as mock_kill:
@@ -453,8 +453,8 @@ class TestStopBikeRack:
                 mock_kill.assert_called_with(12345, signal.SIGTERM)
 
     def test_deletes_port_file(self, tmp_path: Path) -> None:
-        """stop_bikerack should delete .wheelhub-port."""
-        port_file = tmp_path / ".wheelhub-port"
+        """stop_bikerack should delete .bikerack-port."""
+        port_file = tmp_path / ".bikerack-port"
         port_file.write_text("2898")
         (tmp_path / ".wheelhub-pid").write_text("12345")
 
@@ -466,7 +466,7 @@ class TestStopBikeRack:
 
     def test_deletes_pid_file(self, tmp_path: Path) -> None:
         """stop_bikerack should delete .wheelhub-pid."""
-        (tmp_path / ".wheelhub-port").write_text("2898")
+        (tmp_path / ".bikerack-port").write_text("2898")
         pid_file = tmp_path / ".wheelhub-pid"
         pid_file.write_text("12345")
 
@@ -478,7 +478,7 @@ class TestStopBikeRack:
 
     def test_returns_success_dict(self, tmp_path: Path) -> None:
         """stop_bikerack should return {success: True, pid: N, message: str}."""
-        (tmp_path / ".wheelhub-port").write_text("2898")
+        (tmp_path / ".bikerack-port").write_text("2898")
         (tmp_path / ".wheelhub-pid").write_text("12345")
 
         with patch("pennyfarthing_scripts.bikerack.launcher.os.kill"):
@@ -506,7 +506,7 @@ class TestStatus:
 
     def test_returns_running_state(self, tmp_path: Path) -> None:
         """get_status should detect running BikeRack."""
-        (tmp_path / ".wheelhub-port").write_text("2898")
+        (tmp_path / ".bikerack-port").write_text("2898")
         (tmp_path / ".wheelhub-pid").write_text("12345")
 
         with patch("pennyfarthing_scripts.bikerack.launcher.is_process_alive", return_value=True):
@@ -524,7 +524,7 @@ class TestStatus:
 
     def test_includes_dashboard_url(self, tmp_path: Path) -> None:
         """get_status should include dashboard URL when running."""
-        (tmp_path / ".wheelhub-port").write_text("2898")
+        (tmp_path / ".bikerack-port").write_text("2898")
         (tmp_path / ".wheelhub-pid").write_text("12345")
 
         with patch("pennyfarthing_scripts.bikerack.launcher.is_process_alive", return_value=True):
@@ -534,7 +534,7 @@ class TestStatus:
 
     def test_detects_stale_pid(self, tmp_path: Path) -> None:
         """get_status should detect stale PID (file exists, process dead)."""
-        (tmp_path / ".wheelhub-port").write_text("2898")
+        (tmp_path / ".bikerack-port").write_text("2898")
         (tmp_path / ".wheelhub-pid").write_text("99999")
 
         with patch("pennyfarthing_scripts.bikerack.launcher.is_process_alive", return_value=False):
@@ -544,7 +544,7 @@ class TestStatus:
 
 
 # ---------------------------------------------------------------------------
-# AC9: Error if already running (.wheelhub-port exists with live PID)
+# AC9: Error if already running (.bikerack-port exists with live PID)
 # ---------------------------------------------------------------------------
 
 
@@ -553,7 +553,7 @@ class TestAlreadyRunning:
 
     def test_detects_running_instance(self, tmp_path: Path) -> None:
         """is_already_running should return True when port file + live PID."""
-        (tmp_path / ".wheelhub-port").write_text("2898")
+        (tmp_path / ".bikerack-port").write_text("2898")
         (tmp_path / ".wheelhub-pid").write_text("12345")
 
         with patch("pennyfarthing_scripts.bikerack.launcher.is_process_alive", return_value=True):
@@ -573,7 +573,7 @@ class TestAlreadyRunning:
 
     def test_not_running_when_stale_pid(self, tmp_path: Path) -> None:
         """is_already_running should return False when PID is dead (stale)."""
-        (tmp_path / ".wheelhub-port").write_text("2898")
+        (tmp_path / ".bikerack-port").write_text("2898")
         (tmp_path / ".wheelhub-pid").write_text("99999")
 
         with patch("pennyfarthing_scripts.bikerack.launcher.is_process_alive", return_value=False):
@@ -583,7 +583,7 @@ class TestAlreadyRunning:
 
     def test_cleans_stale_files(self, tmp_path: Path) -> None:
         """is_already_running should clean up stale files when PID is dead."""
-        port_file = tmp_path / ".wheelhub-port"
+        port_file = tmp_path / ".bikerack-port"
         pid_file = tmp_path / ".wheelhub-pid"
         port_file.write_text("2898")
         pid_file.write_text("99999")
@@ -605,7 +605,7 @@ class TestExitCodes:
 
     def test_exit_code_2_when_already_running(self, tmp_path: Path) -> None:
         """Start should raise SystemExit(2) when already running."""
-        (tmp_path / ".wheelhub-port").write_text("2898")
+        (tmp_path / ".bikerack-port").write_text("2898")
         (tmp_path / ".wheelhub-pid").write_text("12345")
 
         with patch("pennyfarthing_scripts.bikerack.launcher.is_process_alive", return_value=True):
@@ -736,8 +736,8 @@ class TestCleanupFiles:
     """Utility: cleanup_files removes port and PID files."""
 
     def test_removes_port_file(self, tmp_path: Path) -> None:
-        """cleanup_files should remove .wheelhub-port."""
-        port_file = tmp_path / ".wheelhub-port"
+        """cleanup_files should remove .bikerack-port."""
+        port_file = tmp_path / ".bikerack-port"
         port_file.write_text("2898")
 
         cleanup_files(tmp_path)
@@ -764,7 +764,7 @@ class TestReadPortFile:
 
     def test_reads_port(self, tmp_path: Path) -> None:
         """read_port_file should return port as integer."""
-        (tmp_path / ".wheelhub-port").write_text("2898")
+        (tmp_path / ".bikerack-port").write_text("2898")
 
         result = read_port_file(tmp_path)
 
@@ -778,7 +778,7 @@ class TestReadPortFile:
 
     def test_handles_trailing_whitespace(self, tmp_path: Path) -> None:
         """read_port_file should handle trailing newlines/spaces."""
-        (tmp_path / ".wheelhub-port").write_text("2898\n")
+        (tmp_path / ".bikerack-port").write_text("2898\n")
 
         result = read_port_file(tmp_path)
 

package/pennyfarthing_scripts/tests/test_dialogue_manager.py

@@ -19,7 +19,6 @@ from __future__ import annotations
 
 from pathlib import Path
 
-import pytest
 from click.testing import CliRunner
 
 from pennyfarthing_scripts.consultation.dialogue_manager import (