@pennyfarthing/core 10.0.3 → 10.1.0

package/pennyfarthing_scripts/sprint/story_finish.py

@@ -0,0 +1,211 @@
+"""Finish a completed story: archive, merge PR, update Jira, update YAML.
+
+Replaces finish-story.sh with native Python that correctly handles
+sharded epic YAML files via read_sprint/write_sprint.
+
+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)
+  5. Archive completed epics
+  6. Git cleanup (checkout develop, pull, delete local branch)
+  7. Remove session file
+"""
+
+import re
+import shutil
+import subprocess
+from datetime import date
+from pathlib import Path
+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*(.*)")
+
+
+def _parse_session(session_path: Path) -> dict[str, str]:
+    """Extract metadata fields from a session markdown file.
+
+    Parses lines like ``**Jira:** MSSCI-14467`` and
+    ``**PR:** #748 - title`` into a dict.
+    """
+    fields: dict[str, str] = {}
+    if not session_path.exists():
+        return fields
+    for line in session_path.read_text().splitlines():
+        m = SESSION_FIELD_RE.search(line)
+        if m:
+            key = m.group(1).strip().lower()
+            value = m.group(2).strip()
+            fields[key] = value
+    return fields
+
+
+def _extract_jira_key(fields: dict[str, str]) -> str | None:
+    """Get Jira key from session fields, handling markdown link format."""
+    raw = fields.get("jira", "")
+    # Strip markdown link: [MSSCI-14467](https://...)
+    raw = re.sub(r"\[([^\]]+)\].*", r"\1", raw).strip()
+    if re.match(r"^MSSCI-\d+$", raw):
+        return raw
+    return None
+
+
+def _extract_pr_number(fields: dict[str, str]) -> str | None:
+    """Get PR number from session fields like ``#748 - title``."""
+    raw = fields.get("pr", "")
+    m = re.search(r"#(\d+)", raw)
+    return m.group(1) if m else None
+
+
+def _extract_branch(fields: dict[str, str]) -> str | None:
+    """Get branch name, stripping trailing annotations like ``(pushed)``."""
+    raw = fields.get("branch", "")
+    return re.sub(r"\s*\(.*\)\s*$", "", raw).strip() or None
+
+
+def _run(cmd: list[str], **kwargs: Any) -> subprocess.CompletedProcess[str]:
+    """Run a subprocess with sane defaults."""
+    return subprocess.run(cmd, capture_output=True, text=True, **kwargs)
+
+
+def finish_story(
+    project_root: Path,
+    story_id: str,
+    *,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Finish a story: archive, merge, update Jira, update YAML, clean up.
+
+    Args:
+        project_root: Project root directory.
+        story_id: Story ID (e.g., "83-2").
+        dry_run: If True, report what would happen without side-effects.
+
+    Returns:
+        Result dict ``{success, data?, error?, steps?}``.
+    """
+    session_path = project_root / ".session" / f"{story_id}-session.md"
+    sprint_path = project_root / "sprint" / "current-sprint.yaml"
+    archive_dir = project_root / "sprint" / "archive"
+    archive_dir.mkdir(parents=True, exist_ok=True)
+
+    # --- Validate session ---
+    if not session_path.exists():
+        return {"success": False, "error": f"Session file not found: {session_path}"}
+
+    fields = _parse_session(session_path)
+    jira_key = _extract_jira_key(fields)
+    branch = _extract_branch(fields)
+    pr_number = _extract_pr_number(fields)
+
+    # Fallback: resolve Jira key from sprint YAML
+    if not jira_key:
+        try:
+            data = read_sprint(sprint_path)
+            parts = story_id.split("-")
+            if len(parts) >= 2:
+                epic = find_epic(data, parts[0])
+                story = find_story(epic, story_id) if epic else None
+                if story:
+                    jira_key = story.get("jira")
+        except Exception:
+            pass
+
+    if not jira_key:
+        return {"success": False, "error": f"Could not determine Jira key for {story_id}"}
+
+    # Fallback: resolve PR from GitHub if not in session
+    if not pr_number and branch:
+        result = _run(["gh", "pr", "list", "--head", branch, "--json", "number", "--jq", ".[0].number"])
+        if result.returncode == 0 and result.stdout.strip():
+            pr_number = result.stdout.strip()
+
+    today = date.today().isoformat()
+    steps: list[dict[str, Any]] = []
+
+    if dry_run:
+        steps.append({"step": 1, "action": f"Archive session → {archive_dir / f'{jira_key}-session.md'}"})
+        if pr_number:
+            steps.append({"step": 2, "action": f"Merge PR #{pr_number} (squash, delete branch)"})
+        else:
+            steps.append({"step": 2, "action": "No PR to merge"})
+        steps.append({"step": 3, "action": f"Transition {jira_key} to Done"})
+        steps.append({"step": 4, "action": f"Update sprint YAML (status: done, completed: {today})"})
+        steps.append({"step": 5, "action": "Archive completed epics"})
+        steps.append({"step": 6, "action": f"Delete local branch: {branch}"})
+        steps.append({"step": 7, "action": "Remove session file"})
+        return {"success": True, "dry_run": True, "jira_key": jira_key, "steps": steps}
+
+    # --- Step 1: Archive session ---
+    archive_dest = archive_dir / f"{jira_key}-session.md"
+    shutil.copy2(session_path, archive_dest)
+    steps.append({"step": 1, "action": "archive_session", "dest": str(archive_dest)})
+
+    # --- Step 2: Merge PR ---
+    if pr_number:
+        result = _run(["gh", "pr", "merge", pr_number, "--squash", "--delete-branch"])
+        if result.returncode == 0:
+            steps.append({"step": 2, "action": "merge_pr", "pr": pr_number})
+        else:
+            steps.append({"step": 2, "action": "merge_pr", "pr": pr_number, "warning": "Already merged or failed"})
+    else:
+        steps.append({"step": 2, "action": "merge_pr", "skipped": True})
+
+    # --- Step 3: Transition Jira ---
+    result = _run(["jira", "issue", "move", jira_key, "Done"])
+    if result.returncode == 0:
+        steps.append({"step": 3, "action": "jira_done", "key": jira_key})
+    else:
+        steps.append({"step": 3, "action": "jira_done", "key": jira_key, "warning": "Already Done or failed"})
+
+    # --- Step 4: Update sprint YAML ---
+    try:
+        data = read_sprint(sprint_path)
+        parts = story_id.split("-")
+        if len(parts) < 2:
+            steps.append({"step": 4, "action": "yaml_update", "error": f"Invalid story ID: {story_id}"})
+        else:
+            epic = find_epic(data, parts[0])
+            story = find_story(epic, story_id) if epic else None
+            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:
+                steps.append({"step": 4, "action": "yaml_update", "warning": f"Story {story_id} not found in YAML"})
+    except Exception as exc:
+        steps.append({"step": 4, "action": "yaml_update", "error": str(exc)})
+
+    # --- Step 5: Archive completed epics ---
+    result = _run(
+        ["python", "-m", "pennyfarthing_scripts.cli", "sprint", "epic", "archive"],
+        cwd=str(project_root),
+    )
+    steps.append({"step": 5, "action": "archive_epics", "ran": True})
+
+    # --- Step 6: Git cleanup ---
+    _run(["git", "checkout", "develop"], cwd=str(project_root))
+    _run(["git", "pull", "origin", "develop"], cwd=str(project_root))
+    if branch:
+        _run(["git", "branch", "-d", branch], cwd=str(project_root))
+    steps.append({"step": 6, "action": "git_cleanup", "branch": branch})
+
+    # --- Step 7: Remove session file ---
+    if session_path.exists():
+        session_path.unlink()
+    steps.append({"step": 7, "action": "remove_session"})
+
+    return {
+        "success": True,
+        "story_id": story_id,
+        "jira_key": jira_key,
+        "steps": steps,
+    }

package/pennyfarthing_scripts/sprint/validate_cmd.py

@@ -15,7 +15,14 @@ from pathlib import Path
 import click
 import yaml
 
-from pennyfarthing_scripts.sprint.validator import validate_full_sprint, validate_future
+from pennyfarthing_scripts.sprint.validator import (
+    REQUIRED_INITIATIVE_FIELDS,
+    VALID_INITIATIVE_STATUSES,
+    ValidationResult,
+    validate_epic,
+    validate_full_sprint,
+    validate_future,
+)
 from pennyfarthing_scripts.sprint.yaml_io import (
     EPIC_KEY_ORDER,
     SPRINT_KEY_ORDER,
@@ -142,6 +149,25 @@ def check_format_drift(path: Path) -> list[FormatIssue]:
     return issues
 
 
+def _validate_initiative_shard(data: dict) -> ValidationResult:
+    """Validate a standalone initiative shard file (initiative-*.yaml)."""
+    result = ValidationResult(valid=True)
+    if not isinstance(data, dict):
+        result.add_error("Initiative shard must be a mapping", "")
+        return result
+    for field_name in REQUIRED_INITIATIVE_FIELDS:
+        if field_name not in data:
+            result.add_error(f"Missing required field: {field_name}", field_name)
+    if "status" in data:
+        status = data["status"]
+        if status and status not in VALID_INITIATIVE_STATUSES:
+            result.add_error(
+                f"Invalid initiative status '{status}'. Must be one of: {', '.join(sorted(VALID_INITIATIVE_STATUSES))}",
+                "status",
+            )
+    return result
+
+
 def validate_sprint_yaml(path: Path, fix: bool = False) -> ValidateResult:
     """Validate a sprint YAML file for syntax, schema, and format issues.
 
@@ -204,8 +230,21 @@ def validate_sprint_yaml(path: Path, fix: bool = False) -> ValidateResult:
         return result
 
     # Step 2: Schema validation — detect file type and use appropriate validator
+    #
+    # Shard files (epic-*.yaml, initiative-*.yaml) are standalone fragments
+    # that don't have the full sprint/future structure. Validate their
+    # internal structure only — the index files handle cross-references.
+    is_epic_shard = path.name.startswith("epic-") and path.name.endswith(".yaml")
+    is_initiative_shard = path.name.startswith("initiative-") and path.name.endswith(".yaml")
     is_future = path.name == "future.yaml" or "future" in data
-    if is_future:
+
+    if is_epic_shard:
+        # Epic shard: validate as a single epic (has id, title, stories)
+        schema_result = validate_epic(data, set(), 0)
+    elif is_initiative_shard:
+        # Initiative shard: validate as a single initiative (has name, status)
+        schema_result = _validate_initiative_shard(data)
+    elif is_future:
         schema_result = validate_future(data)
     else:
         schema_result = validate_full_sprint(data)
@@ -218,13 +257,13 @@ def validate_sprint_yaml(path: Path, fix: bool = False) -> ValidateResult:
             category="schema",
         ))
 
-    # Step 3: Format drift detection (sprint files only — future.yaml has different structure)
-    if not is_future:
+    # Step 3: Format drift detection (sprint files only — shards and future.yaml have different structure)
+    if not is_future and not is_epic_shard and not is_initiative_shard:
         format_issues = check_format_drift(path)
         result.format_issues = format_issues
 
     # Step 4: Fix if requested (only format issues, not schema; sprint files only)
-    if fix and not is_future and path.exists():
+    if fix and not is_future and not is_epic_shard and not is_initiative_shard and path.exists():
         try:
             canon_data = read_sprint(path)
             write_sprint(path, canon_data)

package/pennyfarthing_scripts/sprint/validator.py

@@ -65,7 +65,7 @@ class ValidationResult:
 # =============================================================================
 
 VALID_SPRINT_STATUSES = {"active", "closed"}
-VALID_STORY_STATUSES = {"backlog", "ready", "in_progress", "done", "canceled"}
+VALID_STORY_STATUSES = {"backlog", "ready", "in_progress", "done", "canceled", "planning"}
 JIRA_KEY_PATTERN = re.compile(r"^MSSCI-\d{5}$")
 ISO_DATE_PATTERN = re.compile(r"^\d{4}-\d{2}-\d{2}$")
 
@@ -87,7 +87,7 @@ REQUIRED_FUTURE_EPIC_FIELDS = {"id", "title", "points"}
 # Required fields for future.yaml story (what promote-epic.sh transforms)
 REQUIRED_FUTURE_STORY_FIELDS = {"id", "title", "points"}
 
-VALID_INITIATIVE_STATUSES = {"ready", "planning", "blocked", "research_complete", "backlog", "complete"}
+VALID_INITIATIVE_STATUSES = {"ready", "planning", "blocked", "research_complete", "backlog", "complete", "canceled"}
 
 
 # =============================================================================
@@ -282,10 +282,13 @@ def validate_full_sprint(data: dict[str, Any]) -> ValidationResult:
     sprint_result = validate_sprint(data)
     result.merge(sprint_result)
 
-    # Validate epics
+    # Validate epics (skip if sharded — epics are string refs to shard files)
     if "epics" in data:
         all_story_ids: set[str] = set()
         for idx, epic in enumerate(data["epics"]):
+            # Sharded format: epics are string refs, not dicts
+            if isinstance(epic, str):
+                continue
             epic_result = validate_epic(epic, all_story_ids, idx)
             result.merge(epic_result)
 
@@ -349,6 +352,9 @@ def validate_future(data: dict[str, Any]) -> ValidationResult:
         return result
 
     for i, initiative in enumerate(initiatives):
+        # Sharded format: initiatives are string slugs, not dicts
+        if isinstance(initiative, str):
+            continue
         if not isinstance(initiative, dict):
             result.add_error(f"Initiative must be a mapping", f"future.initiatives[{i}]")
             continue
@@ -503,6 +509,10 @@ def validate_sprint_file(file_path: Path) -> ValidationResult:
         )
         return result
 
+    # Merge sharded epic files if present
+    from pennyfarthing_scripts.sprint.loader import _merge_epic_shards
+    data = _merge_epic_shards(data, file_path.parent)
+
     # Validate loaded data
     return validate_full_sprint(data)
 

package/pennyfarthing_scripts/sprint/work.py

@@ -35,6 +35,20 @@ def check_story(story_id: str) -> dict[str, Any]:
     status = story.get("status", "backlog")
     assigned = story.get("assigned_to")
 
+    # Check if assigned to someone else
+    if assigned:
+        from pennyfarthing_scripts.jira.client import get_current_user_email
+
+        current_user = get_current_user_email()
+        if assigned != current_user:
+            return {
+                "available": False,
+                "type": "story",
+                "story": story,
+                "reason": f"Assigned to {assigned}",
+                "assigned_to": assigned,
+            }
+
     # Check if already in progress
     if status == "in_progress":
         return {
@@ -54,6 +68,16 @@ def check_story(story_id: str) -> dict[str, Any]:
             "reason": "Already completed",
         }
 
+    # Check if canceled
+    if status == "canceled":
+        return {
+            "available": False,
+            "type": "story",
+            "story": story,
+            "reason": "Story is canceled",
+        }
+
+    # Available statuses: backlog, ready, planning
     return {
         "available": True,
         "type": "story",
@@ -67,10 +91,23 @@ def check_story(story_id: str) -> dict[str, Any]:
 def get_next_story() -> dict[str, Any]:
     """Get the highest priority available story.
 
+    Considers stories with backlog, ready, or planning status.
+    Excludes stories assigned to other users.
+
     Returns:
         Dict with next story details or error
     """
-    backlog = get_stories_by_status("backlog")
+    from pennyfarthing_scripts.jira.client import get_current_user_email
+    from pennyfarthing_scripts.sprint.loader import get_all_stories
+
+    current_user = get_current_user_email()
+    all_stories = get_all_stories()
+    available_statuses = {"backlog", "ready", "planning"}
+    backlog = [
+        s for s in all_stories
+        if s.get("status") in available_statuses
+        and (not s.get("assigned_to") or s.get("assigned_to") == current_user)
+    ]
 
     if not backlog:
         return {
@@ -78,11 +115,14 @@ def get_next_story() -> dict[str, Any]:
             "error": "No stories in backlog",
         }
 
-    # Sort by priority (P0 > P1 > P2 > P3)
+    # Sort by priority (P0 > P1 > P2 > P3), preferring own assignments
     priority_order = {"P0": 0, "P1": 1, "P2": 2, "P3": 3}
     sorted_stories = sorted(
         backlog,
-        key=lambda s: priority_order.get(s.get("priority", "P2"), 2),
+        key=lambda s: (
+            0 if s.get("assigned_to") == current_user else 1,
+            priority_order.get(s.get("priority", "P2"), 2),
+        ),
     )
 
     next_story = sorted_stories[0]

package/pennyfarthing_scripts/sprint/yaml_io.py

@@ -4,13 +4,14 @@ Deterministic YAML I/O for sprint data.
 Story: MSSCI-14254 - Core yaml_io module with deterministic serialization
 
 Provides:
-- read_sprint(path) -> CommentedMap (preserves ordering/comments)
-- write_sprint(path, data) -> atomic write
+- read_sprint(path) -> CommentedMap (preserves ordering/comments, merges shards)
+- write_sprint(path, data) -> atomic write (shard-aware)
 - canonical_dump(data) -> deterministic YAML string
 """
 
 import io
 import os
+import re
 from collections.abc import Mapping
 from pathlib import Path
 from typing import Any
@@ -19,6 +20,8 @@ from ruamel.yaml import YAML
 from ruamel.yaml.comments import CommentedMap, CommentedSeq
 from ruamel.yaml.scalarstring import LiteralScalarString
 
+JIRA_PATTERN = re.compile(r"^MSSCI-\d{5}$")
+
 
 # Canonical key ordering derived from sprint-template.yaml
 SPRINT_KEY_ORDER: list[str] = [
@@ -52,11 +55,11 @@ def _make_yaml() -> YAML:
     return yml
 
 
-def read_sprint(path: Path) -> CommentedMap:
-    """Read sprint YAML file preserving ordering and comments.
+def _read_yaml_file(path: Path) -> CommentedMap:
+    """Read a single YAML file preserving ordering and comments.
 
     Args:
-        path: Path to sprint YAML file
+        path: Path to YAML file
 
     Returns:
         CommentedMap with preserved ordering and comments
@@ -81,6 +84,44 @@ def read_sprint(path: Path) -> CommentedMap:
     return data
 
 
+def read_sprint(path: Path) -> CommentedMap:
+    """Read sprint YAML file, merging sharded epic files.
+
+    When the epics list contains string references (sharded format),
+    loads each epic-{ref}.yaml shard file and replaces the strings
+    with full epic CommentedMaps.
+
+    Args:
+        path: Path to sprint YAML index file
+
+    Returns:
+        CommentedMap with full epic data merged in
+
+    Raises:
+        FileNotFoundError: If path doesn't exist
+        ValueError: If YAML is malformed or empty
+    """
+    data = _read_yaml_file(path)
+
+    epics = data.get("epics", [])
+    if not epics or not isinstance(epics[0], str):
+        return data
+
+    sprint_dir = path.parent
+    merged_epics = CommentedSeq()
+    for ref in epics:
+        if isinstance(ref, str):
+            shard_file = sprint_dir / f"epic-{ref}.yaml"
+            if shard_file.exists():
+                epic_data = _read_yaml_file(shard_file)
+                merged_epics.append(epic_data)
+        else:
+            merged_epics.append(ref)
+
+    data["epics"] = merged_epics
+    return data
+
+
 def _sort_mapping(data: CommentedMap, key_order: list[str]) -> CommentedMap:
     """Reorder keys in a CommentedMap according to key_order.
 
@@ -228,18 +269,25 @@ def canonical_dump(data: Any) -> str:
     return result
 
 
-def write_sprint(path: Path, data: Any) -> None:
-    """Write sprint data to YAML file atomically.
+def _get_epic_ref(epic: Mapping) -> str:
+    """Get the canonical reference ID for an epic shard file.
 
-    Uses temp file + os.replace() for atomic writes on POSIX.
+    Mirrors the logic in migrate-to-shards.py: prefer Jira key, fall back to ID.
+    """
+    jira = epic.get("jira")
+    epic_id = str(epic.get("id", ""))
 
-    Args:
-        path: Destination path
-        data: Sprint data (CommentedMap or dict)
+    if jira and JIRA_PATTERN.match(str(jira)):
+        return str(jira)
+    if JIRA_PATTERN.match(epic_id):
+        return epic_id
+    return epic_id
 
-    Raises:
-        TypeError: If data is not a valid mapping type
-        OSError: If write fails
+
+def _write_yaml_file(path: Path, data: Any) -> None:
+    """Write data to a single YAML file atomically.
+
+    Uses temp file + os.replace() for atomic writes on POSIX.
     """
     if not isinstance(data, Mapping):
         raise TypeError(f"Expected mapping type, got {type(data).__name__}")
@@ -252,7 +300,68 @@ def write_sprint(path: Path, data: Any) -> None:
             f.write(output)
         os.replace(tmp_path, path)
     except Exception:
-        # Clean up temp file if it exists
         if tmp_path.exists():
             tmp_path.unlink()
         raise
+
+
+def _is_sharded_on_disk(path: Path) -> bool:
+    """Check if the on-disk index file uses sharded epic references."""
+    if not path.exists():
+        return False
+    yml = _make_yaml()
+    try:
+        with open(path) as f:
+            on_disk = yml.load(f)
+    except Exception:
+        return False
+    if on_disk is None or not isinstance(on_disk, Mapping):
+        return False
+    epics = on_disk.get("epics", [])
+    return bool(epics) and isinstance(epics[0], str)
+
+
+def write_sprint(path: Path, data: Any) -> None:
+    """Write sprint data to YAML file(s) atomically.
+
+    If the on-disk index uses sharded format (epics as string refs),
+    writes each epic to its shard file and the index with string refs.
+    Otherwise writes the full data to a single file.
+
+    Args:
+        path: Destination path (the index file)
+        data: Sprint data (CommentedMap or dict)
+
+    Raises:
+        TypeError: If data is not a valid mapping type
+        OSError: If write fails
+    """
+    if not isinstance(data, Mapping):
+        raise TypeError(f"Expected mapping type, got {type(data).__name__}")
+
+    if not _is_sharded_on_disk(path):
+        _write_yaml_file(path, data)
+        return
+
+    # Sharded write: each epic goes to its own file
+    sprint_dir = path.parent
+    epic_refs = CommentedSeq()
+
+    for epic in data.get("epics", []):
+        if isinstance(epic, Mapping):
+            ref = _get_epic_ref(epic)
+            shard_file = sprint_dir / f"epic-{ref}.yaml"
+            _write_yaml_file(shard_file, epic)
+            epic_refs.append(ref)
+        else:
+            epic_refs.append(epic)
+
+    # Write index with string refs instead of full epic dicts
+    index = CommentedMap()
+    for key in data:
+        if key == "epics":
+            index["epics"] = epic_refs
+        else:
+            index[key] = data[key]
+
+    _write_yaml_file(path, index)