@pennyfarthing/core 10.1.0 → 10.2.0

package/pennyfarthing_scripts/preflight/finish.py

@@ -8,7 +8,6 @@ concurrent execution regardless of model behavior.
 import asyncio
 import json
 import re
-import sys
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any

package/pennyfarthing_scripts/pretooluse_hook.py

@@ -40,15 +40,14 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).parent))
 
 from hooks import (
-    find_project_root,
-    get_cyclist_port,
-    send_to_cyclist,
-    read_stdin_json,
-    output_hook_response,
     HookResponse,
-    load_settings,
-    is_cyclist_running,
+    find_project_root,
     get_context_state,
+    is_cyclist_running,
+    load_settings,
+    output_hook_response,
+    read_stdin_json,
+    send_to_cyclist,
 )
 
 

package/pennyfarthing_scripts/prime/cli.py

@@ -22,6 +22,10 @@ import argparse
 import json
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Any
 
 from pennyfarthing_scripts.common.config import get_project_root
 from pennyfarthing_scripts.prime.loader import (
@@ -42,7 +46,7 @@ from pennyfarthing_scripts.prime.persona import (
     load_persona,
 )
 from pennyfarthing_scripts.prime.session import cleanup_old_sessions, register_session
-from pennyfarthing_scripts.prime.tiers import ContextTier, tier_from_string, load_tier_components
+from pennyfarthing_scripts.prime.tiers import ContextTier, load_tier_components, tier_from_string
 from pennyfarthing_scripts.prime.workflow import check_redirect, detect_workflow_state
 
 

package/pennyfarthing_scripts/prime/loader.py

@@ -14,7 +14,6 @@ from __future__ import annotations
 
 import re
 from pathlib import Path
-from typing import Any
 
 from pennyfarthing_scripts.common.config import get_project_root
 
@@ -68,7 +67,7 @@ def load_sprint_context(project_root: Path | None = None) -> str | None:
         Formatted sprint summary, or None if no sprint data
     """
     # Import here to avoid circular imports
-    from pennyfarthing_scripts.sprint.loader import load_sprint, get_sprint_info
+    from pennyfarthing_scripts.sprint.loader import load_sprint
     from pennyfarthing_scripts.sprint.status import get_sprint_status
 
     root = project_root or get_project_root()
@@ -136,7 +135,7 @@ def _extract_session_parts(content: str) -> tuple[str, str]:
 
     # Header: everything before first ## heading
     header_lines = []
-    for i, line in enumerate(lines):
+    for line in lines:
         if line.startswith("## "):
             break
         header_lines.append(line)

package/pennyfarthing_scripts/prime/persona.py

@@ -14,11 +14,12 @@ import yaml
 from pennyfarthing_scripts.common.config import get_project_root, load_yaml_config
 from pennyfarthing_scripts.common.themes import (
     get_current_theme as _get_current_theme,
+)
+from pennyfarthing_scripts.common.themes import (
     resolve_theme_path,
 )
 from pennyfarthing_scripts.prime.models import CrewMember, Persona
 
-
 # Standard agent roles for crew manifest
 AGENT_ROLES = [
     "sm", "tea", "dev", "reviewer", "architect",

package/pennyfarthing_scripts/prime/tiers.py

@@ -35,21 +35,21 @@ def estimate_tokens(text: str) -> int:
     return max(1, len(text) // 4)
 
 
-from pennyfarthing_scripts.prime.loader import (
+from pennyfarthing_scripts.prime.loader import (  # noqa: E402
     load_agent_definition,
     load_behavior_guide,
     load_session_context,
     load_sidecars,
     load_sprint_context,
 )
-from pennyfarthing_scripts.prime.persona import (
+from pennyfarthing_scripts.prime.persona import (  # noqa: E402
     format_persona_compressed,
     get_crew_manifest,
     get_user_title,
     is_character_voice_enabled,
     load_persona,
 )
-from pennyfarthing_scripts.prime.workflow import detect_workflow_state
+from pennyfarthing_scripts.prime.workflow import detect_workflow_state  # noqa: E402
 
 
 class ContextTier(Enum):
@@ -78,7 +78,7 @@ def tier_from_string(value: str) -> ContextTier:
         return ContextTier(normalized)
     except ValueError:
         valid = ", ".join(t.value for t in ContextTier)
-        raise ValueError(f"Invalid tier '{value}'. Must be one of: {valid}")
+        raise ValueError(f"Invalid tier '{value}'. Must be one of: {valid}") from None
 
 
 def load_tier_components(

package/pennyfarthing_scripts/schema_validation_hook.py

@@ -29,12 +29,11 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).parent))
 
 from hooks import (
-    read_stdin_json,
-    output_hook_response,
     HookResponse,
+    output_hook_response,
+    read_stdin_json,
 )
 
-
 # =============================================================================
 # File Type Detection
 # =============================================================================

package/pennyfarthing_scripts/sprint/__init__.py

@@ -18,6 +18,16 @@ Usage:
 """
 
 # Re-export from loader for backwards compatibility
+# Import submodules to make them accessible
+# CLI entry point - import module, not function, so "from sprint import cli" gets the module
+from pennyfarthing_scripts.sprint import (
+    archive,
+    cli,
+    loader,
+    status,
+    work,
+)
+from pennyfarthing_scripts.sprint.cli import main
 from pennyfarthing_scripts.sprint.loader import (
     find_epic,
     find_story,
@@ -31,18 +41,6 @@ from pennyfarthing_scripts.sprint.loader import (
     load_sprint,
 )
 
-# Import submodules to make them accessible
-from pennyfarthing_scripts.sprint import (
-    archive,
-    loader,
-    status,
-    work,
-)
-
-# CLI entry point - import module, not function, so "from sprint import cli" gets the module
-from pennyfarthing_scripts.sprint import cli
-from pennyfarthing_scripts.sprint.cli import main
-
 __all__ = [
     # Loader functions
     "find_epic",

package/pennyfarthing_scripts/sprint/__main__.py

@@ -4,7 +4,7 @@ Entry point for python -m pennyfarthing_scripts.sprint
 
 import sys
 
-from pennyfarthing_scripts.sprint.cli import cli
+from pennyfarthing_scripts.sprint.cli import sprint
 
 if __name__ == "__main__":
-    sys.exit(cli())
+    sys.exit(sprint())

package/pennyfarthing_scripts/sprint/archive.py

@@ -4,7 +4,6 @@ Sprint story archiving.
 Provides functions for archiving completed stories.
 """
 
-from pathlib import Path
 from typing import Any
 
 from pennyfarthing_scripts.common.config import get_project_root

package/pennyfarthing_scripts/sprint/archive_epic.py

@@ -18,7 +18,6 @@ from pennyfarthing_scripts.sprint.yaml_io import (
     _read_yaml_file,
     _write_yaml_file,
     read_sprint,
-    write_sprint,
 )
 
 
@@ -252,13 +251,11 @@ def archive_epic(
 
     # Find the epic in merged data
     epic = None
-    epic_index = None
-    for i, e in enumerate(sprint_data["epics"]):
+    for e in sprint_data["epics"]:
         eid = str(e.get("id", ""))
         ejira = str(e.get("jira", ""))
         if eid == epic_id or ejira == epic_id:
             epic = e
-            epic_index = i
             break
 
     if not epic:

package/pennyfarthing_scripts/sprint/cli.py

@@ -150,7 +150,7 @@ def work(story_id: str | None, dry_run: bool):
         click.echo(f"Story: {story.get('id')}")
         click.echo(f"Title: {story.get('title')}")
         click.echo(f"Points: {story.get('points')}")
-        click.echo(f"Status: Available")
+        click.echo("Status: Available")
     else:
         error_msg = result.get("error") or result.get("reason")
         raise click.ClickException(f"Not available: {error_msg}")
@@ -334,12 +334,12 @@ def story_claim(story_id: str, claim: bool):
 
 
 # Register story-add as story.add
-from pennyfarthing_scripts.sprint.story_add import story_add_command
+from pennyfarthing_scripts.sprint.story_add import story_add_command  # noqa: E402
 
 story.add_command(story_add_command, "add")
 
 # Register story-update as story.update
-from pennyfarthing_scripts.sprint.story_update import story_update_command
+from pennyfarthing_scripts.sprint.story_update import story_update_command  # noqa: E402
 
 story.add_command(story_update_command, "update")
 
@@ -501,7 +501,6 @@ def epic_cancel(epic_id: str, jira: bool, dry_run: bool):
       pf sprint epic cancel epic-42 --jira
     """
     from pennyfarthing_scripts.common.config import get_project_root
-    from pennyfarthing_scripts.sprint.loader import load_sprint
     from pennyfarthing_scripts.sprint.yaml_io import read_sprint, write_sprint
 
     root = get_project_root()
@@ -583,7 +582,7 @@ def _cancel_epic_in_initiatives(epic_id: str, root, *, jira: bool, dry_run: bool
         init_name = init_data.get("name", init_file.stem)
         epics = init_data.get("epics", [])
 
-        for i, e in enumerate(epics):
+        for _i, e in enumerate(epics):
             matched = False
             epic_dict = None
 
@@ -663,6 +662,8 @@ def epic_archive(epic_id: str | None, dry_run: bool, jira: bool):
     # Lazy import
     from pennyfarthing_scripts.sprint.archive_epic import (
         archive_all_completed,
+    )
+    from pennyfarthing_scripts.sprint.archive_epic import (
         archive_epic as do_archive_epic,
     )
 
@@ -757,7 +758,6 @@ def epic_remove(epic_id: str, dry_run: bool):
       pf sprint epic remove epic-41
       pf sprint epic remove epic-41 --dry-run
     """
-    from pathlib import Path
 
     import yaml
 
@@ -886,20 +886,23 @@ def epic_promote(epic_id: str):
     new_epic_id = original_id
     existing_ids = {str(e.get("id", "")) for e in sprint_data["epics"] if isinstance(e, dict)}
 
+    # Normalize to numeric ID (ADR-0022: strip epic- prefix from values)
+    new_epic_id = new_epic_id.replace("epic-", "") if new_epic_id.startswith("epic-") else new_epic_id
+
     if new_epic_id in existing_ids:
         max_num = 0
         for eid in existing_ids:
-            if eid.startswith("epic-"):
-                try:
-                    max_num = max(max_num, int(eid.replace("epic-", "")))
-                except ValueError:
-                    pass
-        new_epic_id = f"epic-{max_num + 1}"
+            clean_eid = eid.replace("epic-", "") if eid.startswith("epic-") else eid
+            try:
+                max_num = max(max_num, int(clean_eid))
+            except ValueError:
+                pass
+        new_epic_id = str(max_num + 1)
         click.echo(f"Warning: Epic ID {original_id} already exists. Assigning new ID: {new_epic_id}")
 
     # Transform epic for current sprint
     old_id_num = original_id.replace("epic-", "")
-    new_id_num = new_epic_id.replace("epic-", "")
+    new_id_num = new_epic_id.replace("epic-", "") if new_epic_id.startswith("epic-") else new_epic_id
 
     epic_data["id"] = new_epic_id
     epic_data["status"] = "backlog"
@@ -928,6 +931,13 @@ def epic_promote(epic_id: str):
     click.echo(f"  Stories: {story_count}")
     click.echo("")
 
+    # Validate epic shard before writing (ADR-0022)
+    from pennyfarthing_scripts.sprint.validator import validate_epic_shard
+    validation = validate_epic_shard(dict(epic_data))
+    if not validation.valid:
+        error_msgs = "; ".join(e.message for e in validation.errors)
+        raise click.ClickException(f"Epic validation failed: {error_msgs}")
+
     # Append to sprint
     sprint_data["epics"].append(epic_data)
 
@@ -960,7 +970,6 @@ def epic_promote(epic_id: str):
         click.echo(f"Removed {original_id} from {source_init_file.name}")
     else:
         # Initiative is empty — remove shard and future.yaml reference
-        init_name = init_data.get("name", "")
         init_slug = source_init_file.stem.replace("initiative-", "")
         source_init_file.unlink()
         click.echo(f"Removed empty initiative shard: {source_init_file.name}")
@@ -987,7 +996,7 @@ def epic_promote(epic_id: str):
 
 
 # Register epic-add as epic.add
-from pennyfarthing_scripts.sprint.epic_add import epic_add_command
+from pennyfarthing_scripts.sprint.epic_add import epic_add_command  # noqa: E402
 
 epic.add_command(epic_add_command, "add")
 
@@ -1161,7 +1170,7 @@ def initiative_cancel(name: str, jira: bool, dry_run: bool):
         return
 
     # Cancel all epics
-    for i, e in enumerate(epics):
+    for _i, e in enumerate(epics):
         if isinstance(e, str):
             shard = _epic_shard_path(sprint_dir, e)
             if shard.exists():
@@ -1216,7 +1225,6 @@ def check(id: str):
 
     from pennyfarthing_scripts.sprint.loader import (
         find_epic,
-        get_all_stories,
         load_sprint,
     )
     from pennyfarthing_scripts.sprint.work import check_story, get_next_story
@@ -1328,10 +1336,10 @@ def _find_epic_for_story(data: dict | None, story_id: str) -> str:
 
 @sprint.command()
 def info():
-    """Output sprint info as JSON for Cyclist sidebar.
+    """Output sprint info as JSON.
 
     \b
-    Returns: {"remaining": N, "inProgress": N, "endDate": "YYYY-MM-DD"}
+    Returns sprint header fields plus computed story point totals.
     """
     import json
 
@@ -1340,8 +1348,6 @@ def info():
     sprint_data = get_sprint_info()
     stories = get_all_stories()
 
-    end_date = sprint_data.get("end_date")
-
     remaining = sum(
         s.get("points", 0) or 0
         for s in stories
@@ -1353,11 +1359,11 @@ def info():
         if s.get("status") == "in_progress"
     )
 
-    click.echo(json.dumps({
-        "remaining": remaining,
-        "inProgress": in_progress,
-        "endDate": str(end_date) if end_date else None,
-    }))
+    result = {str(k): str(v) if hasattr(v, 'isoformat') else v for k, v in sprint_data.items()}
+    result["remaining"] = remaining
+    result["inProgress"] = in_progress
+
+    click.echo(json.dumps(result))
 
 
 # --- Metrics command (replaces sprint-metrics.sh) ---
@@ -1783,7 +1789,7 @@ completed:
     click.echo(f"Created {archive_file}")
 
     click.echo("")
-    click.echo(f"New sprint initialized:")
+    click.echo("New sprint initialized:")
     click.echo(f"  Name: TO Sprint {sprint_yyww}")
     click.echo(f"  Jira ID: {jira_id}")
     click.echo(f"  Dates: {start_date} to {end_date}")
@@ -1854,7 +1860,7 @@ sprint.commands["epic-add"].hidden = True
 
 
 # Register validate command from validate_cmd module
-from pennyfarthing_scripts.sprint.validate_cmd import validate_command
+from pennyfarthing_scripts.sprint.validate_cmd import validate_command  # noqa: E402
 
 sprint.add_command(validate_command)
 

package/pennyfarthing_scripts/sprint/epic_add.py

@@ -14,11 +14,12 @@ from typing import Any
 import click
 from ruamel.yaml.comments import CommentedMap, CommentedSeq
 
+from pennyfarthing_scripts.sprint import validator as _shard_validator
 from pennyfarthing_scripts.sprint.yaml_io import (
     EPIC_KEY_ORDER,
+    _get_epic_ref,
     _read_yaml_file,
     _write_yaml_file,
-    _get_epic_ref,
 )
 
 
@@ -76,6 +77,12 @@ def add_epic(
         if key not in EPIC_KEY_ORDER:
             epic[key] = fields[key]
 
+    # Validate epic shard before writing
+    validation = _shard_validator.validate_epic_shard(dict(epic))
+    if not validation.valid:
+        error_msgs = "; ".join(e.message for e in validation.errors)
+        return {"success": False, "error": f"Epic validation failed: {error_msgs}"}
+
     # Determine the shard reference
     ref = _get_epic_ref(epic)
     shard_file = sprint_dir / f"epic-{ref}.yaml"

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(