@pennyfarthing/core 10.1.0 → 10.2.0

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
 

package/pennyfarthing_scripts/tests/test_brownfield.py

@@ -12,37 +12,34 @@ Tests verify:
 7. CLI integration
 """
 
-import asyncio
 import subprocess
 import sys
 import tempfile
+from collections.abc import Generator
 from pathlib import Path
-from typing import Generator
-from unittest.mock import MagicMock, patch
 
 import pytest
 
 from pennyfarthing_scripts.brownfield import (
     DepthLevel,
-    ProjectType,
     DiscoveryResult,
+    ProjectType,
+    detect_architecture_patterns,
     detect_project_type,
     detect_tech_stack,
-    scan_directory_structure,
-    detect_architecture_patterns,
+    discover,
+    generate_ai_guidance_doc,
     generate_project_overview,
-    generate_tech_stack_doc,
     generate_source_tree_doc,
-    generate_ai_guidance_doc,
-    discover,
+    generate_tech_stack_doc,
+    scan_directory_structure,
 )
 from pennyfarthing_scripts.brownfield.discover import (
-    TechStackItem,
-    DirectoryNode,
     ArchitecturePattern,
+    DirectoryNode,
+    TechStackItem,
 )
 
-
 # =============================================================================
 # FIXTURES
 # =============================================================================
@@ -623,7 +620,7 @@ class TestDiscover:
         output_dir = temp_project_dir / "output"
         output_dir.mkdir()
 
-        result = await discover(node_project, output_dir=output_dir, depth=DepthLevel.DEEP)
+        await discover(node_project, output_dir=output_dir, depth=DepthLevel.DEEP)
 
         expected_files = [
             "project-overview.md",

package/pennyfarthing_scripts/tests/test_cli_modules.py

@@ -8,10 +8,6 @@ properly delegate to library modules.
 
 import subprocess
 import sys
-from typing import Any
-from unittest.mock import MagicMock, patch
-
-import pytest
 
 
 class TestJiraCLIModule:

package/pennyfarthing_scripts/tests/test_codemarkers.py

@@ -9,16 +9,13 @@ Tests cover: models, analyze engine, CLI, formatters.
 
 from __future__ import annotations
 
-import asyncio
 import json
 from dataclasses import asdict
 from pathlib import Path
-from typing import Any
-from unittest.mock import AsyncMock, MagicMock, patch
+from unittest.mock import AsyncMock, patch
 
 import pytest
 
-
 # ---------------------------------------------------------------------------
 # Models
 # ---------------------------------------------------------------------------
@@ -123,7 +120,9 @@ class TestCodeMarkersResultModel:
     def test_json_serializable(self) -> None:
         """Full result serializes to JSON via asdict."""
         from pennyfarthing_scripts.codemarkers.models import (
-            CodeMarker, CodeMarkersResult, MarkerSummary,
+            CodeMarker,
+            CodeMarkersResult,
+            MarkerSummary,
         )
 
         r = CodeMarkersResult(
@@ -534,7 +533,7 @@ class TestTableFormatter:
         ]
         out = format_marker_table(markers, top_n=5)
         # Header + separator + 5 data rows = 7 lines
-        lines = [l for l in out.strip().split("\n") if l.strip()]
+        lines = [line for line in out.strip().split("\n") if line.strip()]
         assert len(lines) <= 7
 
 
@@ -544,7 +543,9 @@ class TestJsonExport:
     def test_valid_json(self) -> None:
         from pennyfarthing_scripts.codemarkers.formatters import export_json
         from pennyfarthing_scripts.codemarkers.models import (
-            CodeMarker, CodeMarkersResult, MarkerSummary,
+            CodeMarker,
+            CodeMarkersResult,
+            MarkerSummary,
         )
 
         r = CodeMarkersResult(
@@ -587,6 +588,7 @@ class TestCLI:
     def test_cli_help(self) -> None:
         """codemarkers group shows help."""
         from click.testing import CliRunner
+
         from pennyfarthing_scripts.codemarkers.cli import codemarkers
 
         runner = CliRunner()
@@ -597,6 +599,7 @@ class TestCLI:
     def test_analyze_command_exists(self) -> None:
         """analyze subcommand is registered."""
         from click.testing import CliRunner
+
         from pennyfarthing_scripts.codemarkers.cli import codemarkers
 
         runner = CliRunner()
@@ -608,6 +611,7 @@ class TestCLI:
     def test_stale_command_exists(self) -> None:
         """stale subcommand is registered."""
         from click.testing import CliRunner
+
         from pennyfarthing_scripts.codemarkers.cli import codemarkers
 
         runner = CliRunner()
@@ -617,6 +621,7 @@ class TestCLI:
     def test_summary_command_exists(self) -> None:
         """summary subcommand is registered."""
         from click.testing import CliRunner
+
         from pennyfarthing_scripts.codemarkers.cli import codemarkers
 
         runner = CliRunner()
@@ -626,6 +631,7 @@ class TestCLI:
     def test_json_format_option(self) -> None:
         """--format json produces JSON output."""
         from click.testing import CliRunner
+
         from pennyfarthing_scripts.codemarkers.cli import codemarkers
 
         runner = CliRunner()
@@ -672,7 +678,6 @@ class TestModuleExports:
         from pennyfarthing_scripts.codemarkers import (
             CodeMarker,
             CodeMarkersResult,
-            MarkerSummary,
         )
         assert CodeMarker is not None
         assert CodeMarkersResult is not None