@pennyfarthing/core 10.1.0 → 10.3.0

package/pennyfarthing_scripts/sprint/import_epic.py

@@ -10,9 +10,7 @@ from datetime import date
 from pathlib import Path
 from typing import Any
 
-import yaml
-
-from pennyfarthing_scripts.common.config import get_project_root, load_yaml_config
+from pennyfarthing_scripts.common.config import get_project_root
 
 
 def parse_epics_markdown(content: str) -> dict[str, Any]:
@@ -195,13 +193,13 @@ def generate_initiative_yaml(
     today = date.today().isoformat()
 
     lines = [
-        f"    # ==========================================================================",
+        "    # ==========================================================================",
         f"    # {initiative_name.upper()}",
         f"    # Imported from: {source_file}",
         f"    # Date: {today}",
-        f"    # ==========================================================================",
+        "    # ==========================================================================",
         f'    - name: "{initiative_name}"',
-        f"      description: |",
+        "      description: |",
     ]
 
     # Add description lines with proper indentation
@@ -210,10 +208,10 @@ def generate_initiative_yaml(
 
     lines.extend(
         [
-            f"      status: ready",
-            f"      blocked_by: null",
+            "      status: ready",
+            "      blocked_by: null",
             f"      total_points: {parsed['total_points']}",
-            f"      epics:",
+            "      epics:",
         ]
     )
 
@@ -228,14 +226,14 @@ def generate_initiative_yaml(
             [
                 f"        - id: epic-{current_epic_num}",
                 f'          title: "{epic["title"]}"',
-                f"          description: |",
+                "          description: |",
                 f"            {epic.get('description', epic['title'])}",
                 f"          points: {epic_points}",
-                f"          priority: P1",
+                "          priority: P1",
                 f'          marker: "{marker}"',
-                f"          repos: pennyfarthing",
-                f"          status: planning",
-                f"          stories:",
+                "          repos: pennyfarthing",
+                "          status: planning",
+                "          stories:",
             ]
         )
 
@@ -247,12 +245,12 @@ def generate_initiative_yaml(
                 [
                     f'            - id: "{story_id}"',
                     f'              title: "{title}"',
-                    f"              description: |",
+                    "              description: |",
                     f"                {story.get('description', title)}",
                     f"              points: {story.get('points', 1)}",
-                    f"              priority: P0",
-                    f"              status: planning",
-                    f"              repos: pennyfarthing",
+                    "              priority: P0",
+                    "              status: planning",
+                    "              repos: pennyfarthing",
                 ]
             )
 
@@ -304,6 +302,32 @@ def import_epic(
     # Get next epic number
     start_epic_num = get_next_epic_number(root)
 
+    # Validate each parsed epic before writing (ADR-0022)
+    from pennyfarthing_scripts.sprint.validator import validate_epic_shard
+
+    epic_num = start_epic_num
+    for epic in parsed["epics"]:
+        # Build a shard-like dict for validation
+        shard_dict = {
+            "id": str(epic_num),
+            "title": epic.get("title", ""),
+            "status": "planning",
+            "stories": [
+                {
+                    "id": f"{epic_num}-{s['num']}",
+                    "title": s.get("title", ""),
+                    "points": s.get("points", 1),
+                    "status": "planning",
+                }
+                for s in epic.get("stories", [])
+            ],
+        }
+        validation = validate_epic_shard(shard_dict)
+        if not validation.valid:
+            error_msgs = "; ".join(e.message for e in validation.errors)
+            return {"success": False, "error": f"Epic {epic_num} validation failed: {error_msgs}"}
+        epic_num += 1
+
     # Generate YAML
     relative_path = str(epics_path.relative_to(root)) if epics_path.is_relative_to(root) else str(epics_path)
     new_yaml, next_epic_num = generate_initiative_yaml(

package/pennyfarthing_scripts/sprint/loader.py

@@ -5,6 +5,7 @@ Provides access to sprint/current-sprint.yaml data.
 Supports sharded per-epic format (epic-{ref}.yaml shard files).
 """
 
+import warnings
 from pathlib import Path
 from typing import Any
 
@@ -40,6 +41,11 @@ def _merge_epic_shards(data: dict[str, Any], sprint_dir: Path) -> dict[str, Any]
             epic_data = load_yaml_config(epic_file)
             if epic_data is not None:
                 merged_epics.append(epic_data)
+        else:
+            warnings.warn(
+                f"Sprint epic ref '{ref}' not found: {epic_file}",
+                stacklevel=2,
+            )
 
     data["epics"] = merged_epics
     return data

package/pennyfarthing_scripts/sprint/status.py

@@ -6,7 +6,7 @@ Provides functions for getting and displaying sprint status.
 
 from typing import Any
 
-from pennyfarthing_scripts.sprint.loader import get_all_stories, get_sprint_info, load_sprint
+from pennyfarthing_scripts.sprint.loader import get_all_stories, get_sprint_info
 
 
 def get_sprint_status(filter_status: str | None = None) -> dict[str, Any]:
@@ -99,7 +99,6 @@ def main(args: list[str] | None = None) -> int:
         Exit code
     """
     import argparse
-    import sys
 
     parser = argparse.ArgumentParser(description="Show sprint status")
     parser.add_argument(

package/pennyfarthing_scripts/sprint/story_add.py

@@ -312,8 +312,8 @@ def story_add_command(
             raise click.ClickException("POINTS is required")
         try:
             init_points = int(title)
-        except ValueError:
-            raise click.ClickException(f"POINTS must be an integer, got '{title}'")
+        except ValueError as err:
+            raise click.ClickException(f"POINTS must be an integer, got '{title}'") from err
 
         result = add_initiative_story(
             initiative_slug=initiative,

package/pennyfarthing_scripts/sprint/story_finish.py

@@ -7,7 +7,7 @@ Steps:
   1. Archive session file to sprint/archive/{jira-key}-session.md
   2. Squash merge PR via gh (handle already-merged)
   3. Transition Jira to Done
-  4. Update sprint YAML (status: done, completed date, remove assigned_to)
+  4. Update sprint YAML (status: done, completed date)
   5. Archive completed epics
   6. Git cleanup (checkout develop, pull, delete local branch)
   7. Remove session file
@@ -16,6 +16,7 @@ Steps:
 import re
 import shutil
 import subprocess
+import sys
 from datetime import date
 from pathlib import Path
 from typing import Any
@@ -23,7 +24,6 @@ from typing import Any
 from pennyfarthing_scripts.sprint.loader import find_epic, find_story
 from pennyfarthing_scripts.sprint.yaml_io import read_sprint, write_sprint
 
-
 SESSION_FIELD_RE = re.compile(r"\*\*(\w[\w\s]*):\*\*\s*(.*)")
 
 
@@ -175,8 +175,6 @@ def finish_story(
             if story:
                 story["status"] = "done"
                 story["completed"] = today
-                if "assigned_to" in story:
-                    del story["assigned_to"]
                 write_sprint(sprint_path, data)
                 steps.append({"step": 4, "action": "yaml_update", "status": "done", "completed": today})
             else:
@@ -186,7 +184,7 @@ def finish_story(
 
     # --- Step 5: Archive completed epics ---
     result = _run(
-        ["python", "-m", "pennyfarthing_scripts.cli", "sprint", "epic", "archive"],
+        [sys.executable, "-m", "pennyfarthing_scripts.cli", "sprint", "epic", "archive"],
         cwd=str(project_root),
     )
     steps.append({"step": 5, "action": "archive_epics", "ran": True})

package/pennyfarthing_scripts/sprint/story_update.py

@@ -7,6 +7,7 @@ This module provides:
 - story_update_command (Click command for CLI registration)
 """
 
+import subprocess
 from datetime import date
 from pathlib import Path
 from typing import Any
@@ -95,9 +96,6 @@ def update_story(
 
     # Auto-cleanup rules
     if status == "done":
-        # Remove assigned_to
-        if "assigned_to" in story:
-            del story["assigned_to"]
         # Auto-set completed if not explicitly provided
         if completed_date is None and "completed" not in story:
             story["completed"] = date.today().isoformat()
@@ -108,6 +106,16 @@ def update_story(
         # Auto-set started if not already present
         if "started" not in story:
             story["started"] = date.today().isoformat()
+        # Auto-set assignee from current Jira user if not already assigned
+        if "assigned_to" not in story and assigned_to is None:
+            try:
+                result = subprocess.run(
+                    ["jira", "me"], capture_output=True, text=True
+                )
+                if result.returncode == 0 and result.stdout.strip():
+                    story["assigned_to"] = result.stdout.strip()
+            except Exception:
+                pass
 
     # Validate after mutation
     result = validate_full_sprint(data)

package/pennyfarthing_scripts/sprint/validate_cmd.py

@@ -28,7 +28,6 @@ from pennyfarthing_scripts.sprint.yaml_io import (
     SPRINT_KEY_ORDER,
     STORY_KEY_ORDER,
     TOP_KEY_ORDER,
-    canonical_dump,
     read_sprint,
     write_sprint,
 )

package/pennyfarthing_scripts/sprint/validator.py

@@ -78,6 +78,10 @@ REQUIRED_STORY_FIELDS = {"id", "title", "status", "points"}
 # Required fields for epic
 REQUIRED_EPIC_FIELDS = {"id", "title"}
 
+# Required fields for epic shard files (write-time validation, ADR-0022)
+REQUIRED_EPIC_SHARD_FIELDS = {"id", "title", "status", "stories"}
+REQUIRED_SHARD_STORY_FIELDS = {"id", "title", "points", "status"}
+
 # Required fields for future.yaml initiative
 REQUIRED_INITIATIVE_FIELDS = {"name", "status"}
 
@@ -235,6 +239,15 @@ def validate_epic(epic: dict[str, Any], all_story_ids: set[str], epic_index: int
                 f"{base_path}.{field_name}",
             )
 
+    # Reject non-string IDs (YAML parses bare integers like `id: 87` as int,
+    # which crashes Cyclist's sprint-data.ts — epicId.match() fails on non-strings)
+    if "id" in epic and not isinstance(epic["id"], str):
+        result.add_error(
+            f"Epic ID must be a string, got {type(epic['id']).__name__} ({epic['id']!r}). "
+            "Quote it in YAML (e.g., id: \"87\" not id: 87)",
+            f"{base_path}.id",
+        )
+
     # Validate stories if present
     if "stories" in epic:
         seen_in_epic: set[str] = set()
@@ -262,6 +275,95 @@ def validate_epic(epic: dict[str, Any], all_story_ids: set[str], epic_index: int
     return result
 
 
+def validate_epic_shard(epic: dict[str, Any]) -> ValidationResult:
+    """Validate an epic shard dict before writing to disk.
+
+    Enforces stricter requirements than validate_epic() since shards
+    are standalone files that must be self-contained.
+
+    Validates:
+    - Required fields present (id, title, status, stories)
+    - stories is a list
+    - Each story has required fields (id, title, points, status)
+    - No duplicate story IDs within the epic
+    - jira key follows MSSCI-NNNNN pattern if present
+
+    Args:
+        epic: Epic shard dict to validate
+
+    Returns:
+        ValidationResult with any errors found
+    """
+    result = ValidationResult(valid=True)
+
+    # Check required shard fields
+    for field_name in REQUIRED_EPIC_SHARD_FIELDS:
+        if field_name not in epic:
+            result.add_error(
+                f"Missing required field: {field_name}",
+                f"epic.{field_name}",
+            )
+
+    # Reject non-string IDs (YAML parses bare integers like `id: 87` as int,
+    # which crashes Cyclist's sprint-data.ts checkEpicContext — epicId.match() fails)
+    if "id" in epic and not isinstance(epic["id"], str):
+        result.add_error(
+            f"Epic ID must be a string, got {type(epic['id']).__name__} ({epic['id']!r}). "
+            "Quote it in YAML (e.g., id: \"87\" not id: 87)",
+            "epic.id",
+        )
+
+    # Reject epic- prefix in ID (ADR-0022: reference prefix should not be baked into value)
+    if "id" in epic:
+        epic_id_val = str(epic["id"])
+        if epic_id_val.startswith("epic-"):
+            result.add_error(
+                f"Epic ID '{epic_id_val}' starts with 'epic-' prefix. "
+                "Use the numeric ID (e.g., '94' not 'epic-94')",
+                "epic.id",
+            )
+
+    # Validate jira key format if present
+    if "jira" in epic:
+        jira_key = str(epic["jira"])
+        if not JIRA_KEY_PATTERN.match(jira_key):
+            result.add_error(
+                f"Invalid Jira key format '{jira_key}'. Expected MSSCI-NNNNN",
+                "epic.jira",
+            )
+
+    # Validate stories field
+    if "stories" in epic:
+        stories = epic["stories"]
+        if not isinstance(stories, list):
+            result.add_error(
+                "'stories' must be a list",
+                "epic.stories",
+            )
+        else:
+            seen_ids: set[str] = set()
+            epic_id = epic.get("id", "epic")
+            for idx, story in enumerate(stories):
+                story_id = story.get("id")
+                if story_id:
+                    if story_id in seen_ids:
+                        result.add_error(
+                            f"Duplicate story ID '{story_id}' within epic",
+                            f"epic.stories[{idx}].id",
+                        )
+                    seen_ids.add(story_id)
+
+                # Check required story fields
+                for field_name in REQUIRED_SHARD_STORY_FIELDS:
+                    if field_name not in story:
+                        result.add_error(
+                            f"Missing required field: {field_name}",
+                            f"{epic_id}.stories[{idx}].{field_name}",
+                        )
+
+    return result
+
+
 def validate_full_sprint(data: dict[str, Any]) -> ValidationResult:
     """Validate complete sprint YAML including all epics and stories.
 
@@ -356,7 +458,7 @@ def validate_future(data: dict[str, Any]) -> ValidationResult:
         if isinstance(initiative, str):
             continue
         if not isinstance(initiative, dict):
-            result.add_error(f"Initiative must be a mapping", f"future.initiatives[{i}]")
+            result.add_error("Initiative must be a mapping", f"future.initiatives[{i}]")
             continue
 
         base_path = f"future.initiatives[{i}]"
@@ -433,13 +535,15 @@ def validate_future(data: dict[str, Any]) -> ValidationResult:
     return result
 
 
-def validate_sprint_file(file_path: Path) -> ValidationResult:
+def validate_sprint_file(file_path: Path, *, strict: bool = False) -> ValidationResult:
     """Validate a sprint YAML file from disk.
 
-    Loads the file and validates its contents.
+    Loads the file and validates its contents. In strict mode, loader
+    warnings (e.g., unresolvable shard refs) are promoted to errors.
 
     Args:
         file_path: Path to sprint YAML file
+        strict: If True, treat loader warnings as validation errors
 
     Returns:
         ValidationResult with any errors (including load errors)
@@ -509,12 +613,22 @@ def validate_sprint_file(file_path: Path) -> ValidationResult:
         )
         return result
 
-    # Merge sharded epic files if present
+    # Merge sharded epic files if present, capturing warnings in strict mode
     from pennyfarthing_scripts.sprint.loader import _merge_epic_shards
-    data = _merge_epic_shards(data, file_path.parent)
+    if strict:
+        import warnings as _warnings
+        with _warnings.catch_warnings(record=True) as caught:
+            _warnings.simplefilter("always")
+            data = _merge_epic_shards(data, file_path.parent)
+        for w in caught:
+            result.add_error(str(w.message), str(file_path))
+    else:
+        data = _merge_epic_shards(data, file_path.parent)
 
     # Validate loaded data
-    return validate_full_sprint(data)
+    full_result = validate_full_sprint(data)
+    result.merge(full_result)
+    return result
 
 
 def format_validation_errors(result: ValidationResult) -> str:

package/pennyfarthing_scripts/sprint/work.py

@@ -7,11 +7,8 @@ Provides functions for starting and managing work on stories.
 from typing import Any
 
 from pennyfarthing_scripts.sprint.loader import (
-    find_epic,
-    find_story,
     get_stories_by_status,
     get_story_by_id,
-    load_sprint,
 )
 
 
@@ -220,7 +217,7 @@ def main(args: list[str] | None = None) -> int:
         print(f"Story: {story.get('id')}")
         print(f"Title: {story.get('title')}")
         print(f"Points: {story.get('points')}")
-        print(f"Status: Available")
+        print("Status: Available")
         return 0
     else:
         print(f"Not available: {result.get('error') or result.get('reason')}", file=sys.stderr)

package/pennyfarthing_scripts/sprint/yaml_io.py

@@ -272,7 +272,9 @@ def canonical_dump(data: Any) -> str:
 def _get_epic_ref(epic: Mapping) -> str:
     """Get the canonical reference ID for an epic shard file.
 
-    Mirrors the logic in migrate-to-shards.py: prefer Jira key, fall back to ID.
+    Priority: Jira key > numeric ID extracted from epic-N > raw ID.
+    Strips 'epic-' prefix from IDs to prevent double-prefix filenames
+    (e.g., epic-epic-94.yaml). See ADR-0022.
     """
     jira = epic.get("jira")
     epic_id = str(epic.get("id", ""))
@@ -281,7 +283,13 @@ def _get_epic_ref(epic: Mapping) -> str:
         return str(jira)
     if JIRA_PATTERN.match(epic_id):
         return epic_id
-    return epic_id
+
+    # Strip epic- prefix to prevent double-prefix filenames
+    # e.g., "epic-94" -> "94" so file becomes "epic-94.yaml" not "epic-epic-94.yaml"
+    stripped = epic_id
+    while stripped.startswith("epic-"):
+        stripped = stripped[5:]
+    return stripped or epic_id
 
 
 def _write_yaml_file(path: Path, data: Any) -> None:

package/pennyfarthing_scripts/story/__init__.py

@@ -15,6 +15,20 @@ Usage:
 """
 
 # Re-export common functions
+# Import submodules
+# CLI entry point - import module, not function, so "from story import cli" gets the module
+from pennyfarthing_scripts.story import (
+    cli,
+    create,
+    size,
+    template,
+)
+from pennyfarthing_scripts.story.cli import main
+from pennyfarthing_scripts.story.create import (
+    create_story,
+    generate_story_yaml,
+    validate_points,
+)
 from pennyfarthing_scripts.story.size import (
     SIZING_GUIDELINES,
     format_size_info,
@@ -26,22 +40,6 @@ from pennyfarthing_scripts.story.template import (
     get_all_templates,
     get_template,
 )
-from pennyfarthing_scripts.story.create import (
-    create_story,
-    generate_story_yaml,
-    validate_points,
-)
-
-# Import submodules
-from pennyfarthing_scripts.story import (
-    create,
-    size,
-    template,
-)
-
-# CLI entry point - import module, not function, so "from story import cli" gets the module
-from pennyfarthing_scripts.story import cli
-from pennyfarthing_scripts.story.cli import main
 
 __all__ = [
     # Size

package/pennyfarthing_scripts/story/size.py

@@ -6,7 +6,6 @@ Provides guidelines and helpers for sizing stories.
 
 from typing import Any
 
-
 # Sizing guidelines
 SIZING_GUIDELINES = {
     1: {

package/pennyfarthing_scripts/story/template.py

@@ -6,7 +6,6 @@ Provides templates for different story types.
 
 from typing import Any
 
-
 # Story templates
 TEMPLATES = {
     "feature": {

package/pennyfarthing_scripts/swebench.py

@@ -19,7 +19,6 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
-
 # Default cache location for SWE-bench data
 DEFAULT_CACHE_PATH = "/tmp/swebench_all.json"
 
@@ -108,7 +107,7 @@ def load_swebench_data(cache_path: str | Path = DEFAULT_CACHE_PATH) -> list[dict
         FileNotFoundError: If cache file doesn't exist
         json.JSONDecodeError: If cache file is invalid JSON
     """
-    with open(cache_path, "r") as f:
+    with open(cache_path) as f:
         return json.load(f)
 
 

package/pennyfarthing_scripts/tests/conftest.py

@@ -3,10 +3,9 @@
 Story 63-9: Reorganize pennyfarthing_scripts into fan-out CLI pattern.
 """
 
-import os
 import sys
+from collections.abc import Generator
 from pathlib import Path
-from typing import Generator
 
 import pytest