@pennyfarthing/core 11.3.8 → 11.5.0-alpha.0

package/pennyfarthing-dist/pf/sprint/cli.py

@@ -273,7 +273,7 @@ def work(story_id: str | None, dry_run: bool):
         click.echo(f"Points: {story.get('points')}")
         click.echo("Status: Available")
     else:
-        error_msg = result.get("error") or result.get("reason")
+        error_msg = result.get("error")
         raise click.ClickException(f"Not available: {error_msg}")
 
 

package/pennyfarthing-dist/pf/sprint/loader.py

@@ -8,7 +8,6 @@ Provides access to sprint data with support for:
 - Sharded per-epic format: epic-{ref}.yaml shard files
 """
 
-import warnings
 from pathlib import Path
 from typing import Any
 
@@ -23,13 +22,9 @@ from pf.common.config import (
 def _merge_epic_shards(data: dict[str, Any], sprint_dir: Path) -> dict[str, Any]:
     """Merge sharded epic files into the sprint data structure.
 
-    When the epics list contains strings (shard references like "MSSCI-14298"
-    or "epic-40"), load each epic-{ref}.yaml and replace the string with
-    the full epic dict.
-
-    Also discovers unindexed shard files on disk (epic-*.yaml files not
-    referenced in the epics list) and appends them so orphan shards are
-    never invisible to the CLI.
+    Thin wrapper around shard_merge.merge_epic_shards() that uses
+    load_yaml_config as the file loader. Kept as a named function
+    for any external importers (e.g. validator.py).
 
     Args:
         data: Sprint data with possible string refs in epics
@@ -38,72 +33,9 @@ def _merge_epic_shards(data: dict[str, Any], sprint_dir: Path) -> dict[str, Any]
     Returns:
         Sprint data with full epic dicts
     """
-    epics = data.get("epics", [])
-    if not epics or not isinstance(epics[0], str):
-        return data
-
-    # Track loaded epic identities to prevent duplicates
-    loaded_shard_files: set[Path] = set()
-    loaded_epic_ids: set[str] = set()
-    merged_epics = []
-    for ref in epics:
-        if not isinstance(ref, str):
-            merged_epics.append(ref)
-            continue
-
-        epic_file = sprint_dir / f"epic-{ref}.yaml"
-        if epic_file.exists():
-            epic_data = load_yaml_config(epic_file)
-            if epic_data is not None:
-                merged_epics.append(epic_data)
-                loaded_shard_files.add(epic_file.resolve())
-                # Track both id and jira key (normalized) for dedup
-                eid = str(epic_data.get("id", "")).replace("epic-", "")
-                if eid:
-                    loaded_epic_ids.add(eid)
-                jira_key = str(epic_data.get("jira", ""))
-                if jira_key:
-                    loaded_epic_ids.add(jira_key)
-        else:
-            warnings.warn(
-                f"Sprint epic ref '{ref}' not found: {epic_file}",
-                stacklevel=2,
-            )
-
-    # Collect epic refs owned by initiatives so we don't warn about them.
-    initiative_refs: set[str] = set()
-    for init_file in sorted(sprint_dir.glob("initiative-*.yaml")):
-        init_data = load_yaml_config(init_file)
-        if init_data and isinstance(init_data, dict):
-            for ref in init_data.get("epics", []):
-                if isinstance(ref, str):
-                    initiative_refs.add(ref)
-                    # Also add normalized form (strip "epic-" prefix)
-                    initiative_refs.add(ref.replace("epic-", ""))
-
-    # Log unindexed shard files on disk (but do NOT auto-merge —
-    # orphan shards may belong to future initiatives).
-    for shard_file in sorted(sprint_dir.glob("epic-*.yaml")):
-        if shard_file.resolve() in loaded_shard_files:
-            continue
-        epic_data = load_yaml_config(shard_file)
-        if epic_data is None or not isinstance(epic_data, dict) or "id" not in epic_data:
-            continue
-        eid = str(epic_data.get("id", "")).replace("epic-", "")
-        jira_key = str(epic_data.get("jira", ""))
-        if eid in loaded_epic_ids or (jira_key and jira_key in loaded_epic_ids):
-            continue
-        # Skip shards owned by initiatives (not orphans)
-        if eid in initiative_refs or jira_key in initiative_refs:
-            continue
-        # Warn only about truly orphaned shards
-        warnings.warn(
-            f"Unindexed shard {shard_file.name} (epic {eid}) not in epics list — skipping",
-            stacklevel=2,
-        )
-
-    data["epics"] = merged_epics
-    return data
+    from pf.sprint.shard_merge import merge_epic_shards
+
+    return merge_epic_shards(data, sprint_dir, load_file=load_yaml_config)
 
 
 def load_sprint(project_root: Path | None = None) -> dict[str, Any] | None:

package/pennyfarthing-dist/pf/sprint/shard_merge.py

@@ -0,0 +1,126 @@
+"""Canonical shard merging for sprint YAML files.
+
+Provides a single merge_epic_shards() implementation used by both:
+- yaml_io.py (ruamel.yaml, preserves comments/ordering)
+- loader.py (yaml.safe_load, plain dicts)
+
+The caller passes a `load_file` callable so each consumer keeps
+its preferred YAML library.
+"""
+
+import warnings
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Any
+
+
+def merge_epic_shards(
+    data: Any,
+    sprint_dir: Path,
+    *,
+    load_file: Callable[[Path], Any],
+    make_list: Callable[[], Any] | None = None,
+) -> Any:
+    """Merge sharded epic files into sprint data.
+
+    When the epics list contains string references (e.g. "MSSCI-14298"
+    or "epic-40"), loads each epic-{ref}.yaml shard and replaces the
+    string with the full epic data.
+
+    Also detects unindexed shard files on disk. Shards owned by
+    initiatives (initiative-*.yaml) are silently skipped; truly
+    orphaned shards emit a warning.
+
+    Args:
+        data: Sprint data with possible string refs in epics.
+        sprint_dir: Directory containing shard files.
+        load_file: Callable that reads a YAML file and returns parsed data.
+            For ruamel.yaml callers this returns CommentedMap;
+            for yaml.safe_load callers this returns plain dicts.
+        make_list: Optional callable returning an empty list-like container.
+            Defaults to ``list``. Pass ``CommentedSeq`` for ruamel.yaml.
+
+    Returns:
+        Sprint data with full epic dicts merged in.
+    """
+    epics = data.get("epics", [])
+    if not epics or not isinstance(epics[0], str):
+        return data
+
+    if make_list is None:
+        make_list = list
+
+    loaded_shard_files: set[Path] = set()
+    loaded_epic_ids: set[str] = set()
+    merged_epics = make_list()
+
+    for ref in epics:
+        if not isinstance(ref, str):
+            merged_epics.append(ref)
+            continue
+
+        shard_file = sprint_dir / f"epic-{ref}.yaml"
+        if shard_file.exists():
+            try:
+                epic_data = load_file(shard_file)
+            except Exception:
+                warnings.warn(
+                    f"Failed to load shard {shard_file.name}",
+                    stacklevel=2,
+                )
+                continue
+
+            if epic_data is None:
+                continue
+
+            merged_epics.append(epic_data)
+            loaded_shard_files.add(shard_file.resolve())
+
+            eid = str(epic_data.get("id", "")).replace("epic-", "")
+            if eid:
+                loaded_epic_ids.add(eid)
+            jira_key = str(epic_data.get("jira", ""))
+            if jira_key:
+                loaded_epic_ids.add(jira_key)
+        else:
+            warnings.warn(
+                f"Sprint epic ref '{ref}' not found: {shard_file}",
+                stacklevel=2,
+            )
+
+    # Collect epic refs owned by initiatives so we don't warn about them.
+    initiative_refs: set[str] = set()
+    for init_file in sorted(sprint_dir.glob("initiative-*.yaml")):
+        try:
+            init_data = load_file(init_file)
+        except Exception:
+            continue
+        if init_data and isinstance(init_data, Mapping):
+            for ref in init_data.get("epics", []):
+                if isinstance(ref, str):
+                    initiative_refs.add(ref)
+                    initiative_refs.add(ref.replace("epic-", ""))
+
+    # Warn about truly orphaned shard files (not in index, not in initiatives).
+    for shard_file in sorted(sprint_dir.glob("epic-*.yaml")):
+        if shard_file.resolve() in loaded_shard_files:
+            continue
+        try:
+            epic_data = load_file(shard_file)
+        except Exception:
+            continue
+        if epic_data is None or not isinstance(epic_data, Mapping) or "id" not in epic_data:
+            continue
+        eid = str(epic_data.get("id", "")).replace("epic-", "")
+        jira_key = str(epic_data.get("jira", ""))
+        if eid in loaded_epic_ids or (jira_key and jira_key in loaded_epic_ids):
+            continue
+        if eid in initiative_refs or jira_key in initiative_refs:
+            continue
+        warnings.warn(
+            f"Unindexed shard {shard_file.name} (epic {eid}) not in epics list — skipping",
+            stacklevel=2,
+        )
+
+    data["epics"] = merged_epics
+    return data

package/pennyfarthing-dist/pf/sprint/story_finish.py

@@ -133,10 +133,14 @@ def finish_story(
     )
 
     if dry_run:
+        from pf.common.pr_config import get_pr_merge_mode
+
         steps.append({"step": 1, "action": f"Archive session → {archive_dir / archive_name}"})
         if dialogue_path.exists():
             steps.append({"step": "1b", "action": f"Archive dialogue → {archive_dir / dialogue_archive_name}"})
-        if pr_number:
+        if pr_number and get_pr_merge_mode() == "human":
+            steps.append({"step": 2, "action": f"PR #{pr_number} — waiting for human review and merge"})
+        elif 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"})
@@ -162,7 +166,15 @@ def finish_story(
         steps.append({"step": "1b", "action": "archive_dialogue", "dest": str(dialogue_dest)})
 
     # --- Step 2: Merge PR ---
-    if pr_number:
+    from pf.common.pr_config import get_pr_merge_mode
+
+    pr_merge_mode = get_pr_merge_mode()
+    if pr_number and pr_merge_mode == "human":
+        steps.append({
+            "step": 2, "action": "merge_pr", "pr": pr_number,
+            "mode": "human", "message": f"PR #{pr_number} ready for human review and merge",
+        })
+    elif 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})
@@ -173,8 +185,10 @@ def finish_story(
 
     # --- Step 3: Transition Jira ---
     if jira_key:
-        result = _run(["jira", "issue", "move", jira_key, "Done"])
-        if result.returncode == 0:
+        from pf.jira.client import get_client
+
+        jira_result = get_client().transition_sync(jira_key, "Done")
+        if jira_result.get("success"):
             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"})

package/pennyfarthing-dist/pf/sprint/validator.py

@@ -66,11 +66,11 @@ class ValidationResult:
 
 VALID_SPRINT_STATUSES = {"active", "closed"}
 VALID_STORY_STATUSES = {"backlog", "ready", "in_progress", "done", "canceled", "planning"}
-JIRA_KEY_PATTERN = re.compile(r"^MSSCI-\d{5}$")
+JIRA_KEY_PATTERN = re.compile(r"^[A-Z][A-Z0-9_]+-\d+(\s*/\s*[A-Z][A-Z0-9_]+-\d+)*$")
 ISO_DATE_PATTERN = re.compile(r"^\d{4}-\d{2}-\d{2}$")
 
 # Required fields for sprint section
-REQUIRED_SPRINT_FIELDS = {"number", "jira_sprint_id", "goal", "start_date", "end_date", "status"}
+REQUIRED_SPRINT_FIELDS = {"goal", "start_date", "end_date", "status"}
 
 # Required fields for story
 REQUIRED_STORY_FIELDS = {"id", "title", "status", "points"}
@@ -103,7 +103,7 @@ def validate_sprint(data: dict[str, Any]) -> ValidationResult:
     """Validate sprint-level structure and fields.
 
     Validates:
-    - Required fields present (number, jira_sprint_id, goal, start_date, end_date, status)
+    - Required fields present (goal, start_date, end_date, status)
     - status is valid value (active, closed)
     - dates are ISO format
 
@@ -159,7 +159,7 @@ def validate_story(story: dict[str, Any], epic_id: str, story_index: int = 0) ->
     - Required fields present (id, title, status, points)
     - status is valid value (backlog, ready, in_progress, done, canceled)
     - points is numeric
-    - jira key follows pattern MSSCI-NNNNN if present
+    - jira key follows PROJECT-NUMBER pattern if present
     - branch follows convention if present
 
     Args:
@@ -204,7 +204,7 @@ def validate_story(story: dict[str, Any], epic_id: str, story_index: int = 0) ->
         jira_key = str(story["jira"])
         if not JIRA_KEY_PATTERN.match(jira_key):
             result.add_error(
-                f"Invalid Jira key format '{jira_key}'. Expected MSSCI-NNNNN",
+                f"Invalid Jira key format '{jira_key}'. Expected PROJECT-NUMBER format (e.g., DPGD-17, MSSCI-12345)",
                 f"{base_path}.jira",
             )
 
@@ -286,7 +286,7 @@ def validate_epic_shard(epic: dict[str, Any]) -> ValidationResult:
     - 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
+    - jira key follows PROJECT-NUMBER pattern if present
 
     Args:
         epic: Epic shard dict to validate
@@ -328,7 +328,7 @@ def validate_epic_shard(epic: dict[str, Any]) -> ValidationResult:
         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",
+                f"Invalid Jira key format '{jira_key}'. Expected PROJECT-NUMBER format (e.g., DPGD-17, MSSCI-12345)",
                 "epic.jira",
             )
 

package/pennyfarthing-dist/pf/sprint/yaml_io.py

@@ -36,7 +36,7 @@ EPIC_KEY_ORDER: list[str] = [
 
 STORY_KEY_ORDER: list[str] = [
     "id", "jira", "title", "description", "points", "priority",
-    "status", "in_sprint", "assigned_to", "started", "repos",
+    "refs", "status", "in_sprint", "assigned_to", "started", "repos",
     "workflow", "acceptance_criteria", "completed", "pr",
     "delivered_in", "notes",
 ]
@@ -107,59 +107,14 @@ def read_sprint(path: Path) -> CommentedMap:
     """
     data = _read_yaml_file(path)
 
-    epics = data.get("epics", [])
-    if not epics or not isinstance(epics[0], str):
-        return data
-
-    sprint_dir = path.parent
-
-    # Track loaded epic identities to prevent duplicates
-    loaded_shard_files: set[Path] = set()
-    loaded_epic_ids: set[str] = set()
-    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)
-                loaded_shard_files.add(shard_file.resolve())
-                # Track both id and jira key (normalized) for dedup
-                eid = str(epic_data.get("id", "")).replace("epic-", "")
-                if eid:
-                    loaded_epic_ids.add(eid)
-                jira_key = str(epic_data.get("jira", ""))
-                if jira_key:
-                    loaded_epic_ids.add(jira_key)
-        else:
-            merged_epics.append(ref)
-
-    # Log unindexed shard files on disk (but do NOT auto-merge them —
-    # orphan shards may belong to future initiatives and should not be
-    # pulled into the current sprint automatically).
-    for shard_file in sorted(sprint_dir.glob("epic-*.yaml")):
-        if shard_file.resolve() in loaded_shard_files:
-            continue
-        try:
-            epic_data = _read_yaml_file(shard_file)
-        except (FileNotFoundError, ValueError):
-            continue
-        if not isinstance(epic_data, Mapping) or "id" not in epic_data:
-            continue
-        eid = str(epic_data.get("id", "")).replace("epic-", "")
-        jira_key = str(epic_data.get("jira", ""))
-        if eid in loaded_epic_ids or (jira_key and jira_key in loaded_epic_ids):
-            continue
-        # Warn but don't merge — these are intentionally excluded
-        import sys
-        print(
-            f"  NOTE: Unindexed shard {shard_file.name} (epic {eid}) "
-            f"not in epics list — skipping",
-            file=sys.stderr,
-        )
+    from pf.sprint.shard_merge import merge_epic_shards
 
-    data["epics"] = merged_epics
-    return data
+    return merge_epic_shards(
+        data,
+        path.parent,
+        load_file=_read_yaml_file,
+        make_list=CommentedSeq,
+    )
 
 
 def _sort_mapping(data: CommentedMap, key_order: list[str]) -> CommentedMap: