@pennyfarthing/core 10.4.0 → 11.0.0

package/pennyfarthing_scripts/sprint/loader.py

@@ -19,6 +19,10 @@ def _merge_epic_shards(data: dict[str, Any], sprint_dir: Path) -> dict[str, Any]
     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.
+
     Args:
         data: Sprint data with possible string refs in epics
         sprint_dir: Directory containing the shard files
@@ -30,6 +34,9 @@ def _merge_epic_shards(data: dict[str, Any], sprint_dir: Path) -> dict[str, Any]
     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):
@@ -41,12 +48,38 @@ 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)
+                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,
             )
 
+    # 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
+        # Warn but don't merge
+        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_scripts/sprint/story_add.py

@@ -275,12 +275,13 @@ def add_initiative_story(
 @click.argument("title", type=str, required=False)
 @click.argument("points", type=int, required=False)
 @click.option("--type", "story_type", type=click.Choice(["feature", "bug", "chore", "refactor"]), default="feature")
-@click.option("--priority", type=click.Choice(["P0", "P1", "P2", "P3"]), default="P1")
+@click.option("--priority", type=click.Choice(["p0", "p1", "p2", "p3"], case_sensitive=False), default="p1")
 @click.option("--workflow", type=click.Choice(["tdd", "trivial", "bdd"]), default="tdd")
 @click.option("--jira", "jira_id", type=str, default=None)
 @click.option("--sprint-file", type=click.Path(), default=None, help="Path to sprint YAML file")
 @click.option("--initiative", type=str, default=None, help="Add as standalone story to initiative (e.g., technical-debt)")
 @click.option("--repos", type=str, default="pennyfarthing", help="Repos (default: pennyfarthing)")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
 def story_add_command(
     epic_id: str | None,
     title: str | None,
@@ -292,6 +293,7 @@ def story_add_command(
     sprint_file: str | None,
     initiative: str | None,
     repos: str,
+    dry_run: bool,
 ) -> None:
     """Add a new story to an epic or initiative.
 
@@ -315,6 +317,10 @@ def story_add_command(
         except ValueError as err:
             raise click.ClickException(f"POINTS must be an integer, got '{title}'") from err
 
+        if dry_run:
+            click.echo(f"[DRY-RUN] Would add story to initiative {initiative}: {init_title} [{init_points}pts]")
+            return
+
         result = add_initiative_story(
             initiative_slug=initiative,
             title=init_title,
@@ -339,6 +345,10 @@ def story_add_command(
         if points is None:
             raise click.ClickException("POINTS is required")
 
+        if dry_run:
+            click.echo(f"[DRY-RUN] Would add story to epic {epic_id}: {title} [{points}pts]")
+            return
+
         if sprint_file is None:
             from pennyfarthing_scripts.common.config import get_project_root
             path = get_project_root() / "sprint" / "current-sprint.yaml"

package/pennyfarthing_scripts/sprint/story_finish.py

@@ -116,9 +116,6 @@ def finish_story(
         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"])
@@ -127,14 +124,18 @@ def finish_story(
 
     today = date.today().isoformat()
     steps: list[dict[str, Any]] = []
+    archive_name = f"{jira_key}-session.md" if jira_key else f"{story_id}-session.md"
 
     if dry_run:
-        steps.append({"step": 1, "action": f"Archive session → {archive_dir / f'{jira_key}-session.md'}"})
+        steps.append({"step": 1, "action": f"Archive session → {archive_dir / archive_name}"})
         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"})
+        if jira_key:
+            steps.append({"step": 3, "action": f"Transition {jira_key} to Done"})
+        else:
+            steps.append({"step": 3, "action": "Skip Jira transition (no key)"})
         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}"})
@@ -142,7 +143,7 @@ def finish_story(
         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"
+    archive_dest = archive_dir / archive_name
     shutil.copy2(session_path, archive_dest)
     steps.append({"step": 1, "action": "archive_session", "dest": str(archive_dest)})
 
@@ -157,11 +158,14 @@ def finish_story(
         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})
+    if jira_key:
+        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"})
     else:
-        steps.append({"step": 3, "action": "jira_done", "key": jira_key, "warning": "Already Done or failed"})
+        steps.append({"step": 3, "action": "jira_done", "skipped": True, "warning": "No Jira key available"})
 
     # --- Step 4: Update sprint YAML ---
     try:

package/pennyfarthing_scripts/sprint/story_update.py

@@ -29,6 +29,7 @@ def update_story(
     assigned_to: str | None = None,
     completed_date: str | None = None,
     started_date: str | None = None,
+    workflow: str | None = None,
     dry_run: bool = False,
 ) -> dict[str, Any]:
     """Update fields on a story in the sprint YAML.
@@ -42,6 +43,7 @@ def update_story(
         assigned_to: New assignee
         completed_date: Completed date (ISO format)
         started_date: Started date (ISO format)
+        workflow: Workflow type (tdd, trivial, bdd, agent-docs)
         dry_run: If True, report changes without writing
 
     Returns:
@@ -93,6 +95,8 @@ def update_story(
         story["completed"] = completed_date
     if started_date is not None:
         story["started"] = started_date
+    if workflow is not None:
+        story["workflow"] = workflow
 
     # Auto-cleanup rules
     if status == "done":
@@ -148,6 +152,7 @@ def update_story(
 @click.option("--points", type=int, default=None)
 @click.option("--priority", default=None)
 @click.option("--started", "started_date", default=None)
+@click.option("--workflow", default=None)
 @click.option("--dry-run", is_flag=True)
 @click.option("--sprint-file", type=click.Path(), default=None, help="Path to sprint YAML file")
 def story_update_command(
@@ -158,6 +163,7 @@ def story_update_command(
     points: int | None,
     priority: str | None,
     started_date: str | None,
+    workflow: str | None,
     dry_run: bool,
     sprint_file: str | None,
 ) -> None:
@@ -177,6 +183,7 @@ def story_update_command(
         assigned_to=assigned_to,
         completed_date=completed_date,
         started_date=started_date,
+        workflow=workflow,
         dry_run=dry_run,
     )
 

package/pennyfarthing_scripts/sprint/validate_cmd.py

@@ -28,6 +28,7 @@ from pennyfarthing_scripts.sprint.yaml_io import (
     SPRINT_KEY_ORDER,
     STORY_KEY_ORDER,
     TOP_KEY_ORDER,
+    _canonicalize,
     read_sprint,
     write_sprint,
 )
@@ -264,7 +265,7 @@ def validate_sprint_yaml(path: Path, fix: bool = False) -> ValidateResult:
     # Step 4: Fix if requested (only format issues, not schema; sprint files only)
     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)
+            canon_data = _canonicalize(read_sprint(path))
             write_sprint(path, canon_data)
             result.fixed = True
         except (FileNotFoundError, ValueError):

package/pennyfarthing_scripts/sprint/yaml_io.py

@@ -91,6 +91,10 @@ def read_sprint(path: Path) -> CommentedMap:
     loads each epic-{ref}.yaml shard file and replaces the strings
     with full epic CommentedMaps.
 
+    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.
+
     Args:
         path: Path to sprint YAML index file
 
@@ -108,6 +112,10 @@ def read_sprint(path: Path) -> CommentedMap:
         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):
@@ -115,9 +123,41 @@ def read_sprint(path: Path) -> CommentedMap:
             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,
+        )
+
     data["epics"] = merged_epics
     return data
 
@@ -161,12 +201,30 @@ def _canonicalize(data: Any) -> Any:
     if not isinstance(data, Mapping):
         return data
 
-    # Determine which key order to use based on context
-    # Top level
-    result = _sort_mapping(
-        data if isinstance(data, CommentedMap) else _to_commented_map(data),
-        TOP_KEY_ORDER,
-    )
+    cm = data if isinstance(data, CommentedMap) else _to_commented_map(data)
+
+    # Detect epic shard: has 'stories' + 'id' but no 'sprint'/'epics' top-level keys
+    is_epic_shard = "stories" in cm and "id" in cm and "sprint" not in cm and "epics" not in cm
+
+    if is_epic_shard:
+        result = _sort_mapping(cm, EPIC_KEY_ORDER)
+        # Reorder stories within the epic
+        if "stories" in result and isinstance(result["stories"], (list, CommentedSeq)):
+            new_stories = CommentedSeq()
+            for story in result["stories"]:
+                if isinstance(story, Mapping):
+                    story_cm = (
+                        story if isinstance(story, CommentedMap) else _to_commented_map(story)
+                    )
+                    new_stories.append(_sort_mapping(story_cm, STORY_KEY_ORDER))
+                else:
+                    new_stories.append(story)
+            result["stories"] = new_stories
+        result = _ensure_block_scalars(result)
+        return result
+
+    # Full sprint document: sort top-level keys
+    result = _sort_mapping(cm, TOP_KEY_ORDER)
 
     # Reorder sprint section
     if "sprint" in result and isinstance(result["sprint"], Mapping):

package/pennyfarthing_scripts/tests/test_archive_epic.py

@@ -0,0 +1,185 @@
+"""Tests for epic archiving — completed stories written to sprint completed file.
+
+Story: 91-29 - Bug: archive_epic does not populate completed_stories
+"""
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from pennyfarthing_scripts.sprint.archive_epic import (
+    _load_archive_file,
+    _write_archive_file,
+    archive_epic,
+    is_epic_complete,
+)
+from pennyfarthing_scripts.sprint.yaml_io import _make_yaml, _write_yaml_file
+
+
+@pytest.fixture
+def sprint_tree(tmp_path: Path) -> Path:
+    """Create a minimal sprint directory structure with one completed epic."""
+    sprint_dir = tmp_path / "sprint"
+    sprint_dir.mkdir()
+    (sprint_dir / "archive").mkdir()
+    (sprint_dir / "context").mkdir()
+
+    # current-sprint.yaml index referencing one epic
+    _make_yaml()
+    index = {
+        "sprint": {
+            "name": "TO Sprint 2699",
+            "number": 2699,
+            "jira_sprint_id": 999,
+            "jira_sprint_name": "TO Sprint 2699",
+            "goal": "Test sprint",
+            "start_date": "2026-02-01",
+            "end_date": "2026-02-15",
+            "status": "active",
+        },
+        "epics": ["MSSCI-99999"],
+        "stories": [],
+    }
+    sprint_path = sprint_dir / "current-sprint.yaml"
+    _write_yaml_file(sprint_path, index)
+
+    # Epic shard with 3 completed stories
+    epic_data: dict[str, Any] = {
+        "id": "epic-50",
+        "type": "epic",
+        "title": "Test Epic",
+        "status": "backlog",
+        "jira": "MSSCI-99999",
+        "stories": [
+            {
+                "id": "50-1",
+                "jira": "MSSCI-99901",
+                "title": "First story",
+                "points": 2,
+                "status": "done",
+                "completed": "2026-02-10",
+            },
+            {
+                "id": "50-2",
+                "jira": "MSSCI-99902",
+                "title": "Second story",
+                "points": 3,
+                "status": "done",
+                "completed": "2026-02-11",
+            },
+            {
+                "id": "50-3",
+                "jira": "MSSCI-99903",
+                "title": "Third story",
+                "points": 1,
+                "status": "done",
+                "completed": "2026-02-12",
+            },
+        ],
+    }
+    _write_yaml_file(sprint_dir / "epic-MSSCI-99999.yaml", epic_data)
+
+    # Pre-create the completed file (ensure_archive_file needs load_sprint
+    # which needs project root detection — easier to pre-create)
+    completed = {
+        "sprint": index["sprint"],
+        "completed_epics": [],
+        "completed_stories": [],
+    }
+    _write_archive_file(sprint_dir / "archive" / "sprint-2699-completed.yaml", completed)
+
+    return tmp_path
+
+
+def test_archive_epic_writes_completed_stories(sprint_tree: Path) -> None:
+    """Archiving an epic should write all its stories to completed_stories."""
+    result = archive_epic("epic-50", project_root=sprint_tree)
+
+    assert result["success"] is True
+    assert result["stories_archived"] == 3
+    assert result["total_points"] == 6
+
+    # Load the completed file and verify stories were written
+    archive_path = sprint_tree / "sprint" / "archive" / "sprint-2699-completed.yaml"
+    archive_data = _load_archive_file(archive_path)
+
+    assert "MSSCI-99999" in archive_data["completed_epics"]
+
+    story_ids = [s["id"] for s in archive_data["completed_stories"]]
+    assert "50-1" in story_ids
+    assert "50-2" in story_ids
+    assert "50-3" in story_ids
+
+    # Verify story fields
+    story_1 = next(s for s in archive_data["completed_stories"] if s["id"] == "50-1")
+    assert story_1["epic"] == "MSSCI-99999"
+    assert story_1["title"] == "First story"
+    assert story_1["points"] == 2
+    assert story_1["completed"] == "2026-02-10"
+
+
+def test_archive_epic_no_duplicate_stories(sprint_tree: Path) -> None:
+    """If stories already exist in completed_stories, don't duplicate them."""
+    # Pre-populate one story
+    archive_path = sprint_tree / "sprint" / "archive" / "sprint-2699-completed.yaml"
+    archive_data = _load_archive_file(archive_path)
+    archive_data["completed_stories"].append({
+        "id": "50-1",
+        "epic": "MSSCI-99999",
+        "title": "First story",
+        "points": 2,
+        "completed": "2026-02-10",
+    })
+    _write_archive_file(archive_path, archive_data)
+
+    # Now archive the epic
+    result = archive_epic("epic-50", project_root=sprint_tree)
+    assert result["success"] is True
+
+    # Reload and check — 50-1 should appear only once
+    archive_data = _load_archive_file(archive_path)
+    story_ids = [s["id"] for s in archive_data["completed_stories"]]
+    assert story_ids.count("50-1") == 1
+    assert len(story_ids) == 3  # 50-1, 50-2, 50-3
+
+
+def test_is_epic_complete_all_done() -> None:
+    """Epic with all stories done should be complete."""
+    epic = {
+        "status": "backlog",
+        "stories": [
+            {"id": "1-1", "status": "done"},
+            {"id": "1-2", "status": "done"},
+        ],
+    }
+    complete, incomplete = is_epic_complete(epic)
+    assert complete is True
+    assert incomplete == []
+
+
+def test_is_epic_complete_with_canceled() -> None:
+    """Canceled stories count as complete."""
+    epic = {
+        "status": "backlog",
+        "stories": [
+            {"id": "1-1", "status": "done"},
+            {"id": "1-2", "status": "canceled"},
+        ],
+    }
+    complete, incomplete = is_epic_complete(epic)
+    assert complete is True
+
+
+def test_is_epic_complete_with_remaining() -> None:
+    """Epic with in_progress stories is not complete."""
+    epic = {
+        "status": "backlog",
+        "stories": [
+            {"id": "1-1", "status": "done"},
+            {"id": "1-2", "status": "in_progress"},
+        ],
+    }
+    complete, incomplete = is_epic_complete(epic)
+    assert complete is False
+    assert "1-2" in incomplete