@pennyfarthing/core 10.0.3 → 10.1.0

package/pennyfarthing_scripts/sprint/epic_add.py

@@ -0,0 +1,173 @@
+"""Sprint epic add command.
+
+Adds a new epic to the current sprint, creating a shard file
+and updating the index.
+
+Provides:
+- add_epic(sprint_path, epic_id, title, ...) -> dict
+- epic_add_command (Click command for CLI registration)
+"""
+
+from pathlib import Path
+from typing import Any
+
+import click
+from ruamel.yaml.comments import CommentedMap, CommentedSeq
+
+from pennyfarthing_scripts.sprint.yaml_io import (
+    EPIC_KEY_ORDER,
+    _read_yaml_file,
+    _write_yaml_file,
+    _get_epic_ref,
+)
+
+
+def add_epic(
+    sprint_path: Path,
+    epic_id: str,
+    title: str,
+    *,
+    priority: str = "P1",
+    status: str = "backlog",
+    repos: str = "pennyfarthing",
+    jira: str | None = None,
+    description: str | None = None,
+) -> dict[str, Any]:
+    """Add a new epic to the current sprint.
+
+    Creates a shard file for the epic and adds its reference to the index.
+
+    Args:
+        sprint_path: Path to sprint index YAML file
+        epic_id: Epic ID (e.g., "epic-85" or "MSSCI-14400")
+        title: Epic title
+        priority: Priority (default: P1)
+        status: Initial status (default: backlog)
+        repos: Repository scope (default: pennyfarthing)
+        jira: Optional Jira epic key
+        description: Optional epic description
+
+    Returns:
+        Dict with success status and epic_id or error
+    """
+    sprint_dir = sprint_path.parent
+
+    # Build epic as CommentedMap with canonical key ordering
+    epic = CommentedMap()
+    fields: dict[str, Any] = {
+        "id": epic_id,
+        "type": "epic",
+        "title": title,
+        "priority": priority,
+        "status": status,
+        "repos": repos,
+        "stories": CommentedSeq(),
+    }
+    if description is not None:
+        fields["description"] = description
+    if jira is not None:
+        fields["jira"] = jira
+
+    # Insert keys in EPIC_KEY_ORDER, then any extras
+    for key in EPIC_KEY_ORDER:
+        if key in fields:
+            epic[key] = fields[key]
+    for key in fields:
+        if key not in EPIC_KEY_ORDER:
+            epic[key] = fields[key]
+
+    # Determine the shard reference
+    ref = _get_epic_ref(epic)
+    shard_file = sprint_dir / f"epic-{ref}.yaml"
+
+    if shard_file.exists():
+        return {
+            "success": False,
+            "error": f"Epic shard file already exists: {shard_file.name}",
+        }
+
+    # Read current index
+    data = _read_yaml_file(sprint_path)
+    epics = data.get("epics", [])
+
+    # Check for duplicate refs
+    for existing in epics:
+        existing_str = str(existing) if isinstance(existing, str) else str(existing.get("id", ""))
+        if existing_str == ref or existing_str == epic_id:
+            return {
+                "success": False,
+                "error": f"Epic '{epic_id}' already exists in the sprint",
+            }
+
+    # Detect format: sharded (string refs) or monolithic (full dicts)
+    is_sharded = bool(epics) and isinstance(epics[0], str)
+
+    if is_sharded or not epics:
+        # Sharded format: write shard file and add string ref to index
+        _write_yaml_file(shard_file, epic)
+
+        if not isinstance(epics, CommentedSeq):
+            epics = CommentedSeq(epics)
+        epics.append(ref)
+        data["epics"] = epics
+        _write_yaml_file(sprint_path, data)
+    else:
+        # Monolithic format: add full epic dict to index
+        if not isinstance(epics, CommentedSeq):
+            epics = CommentedSeq(epics)
+        epics.append(epic)
+        data["epics"] = epics
+        _write_yaml_file(sprint_path, data)
+
+    return {
+        "success": True,
+        "epic_id": epic_id,
+        "ref": ref,
+        "shard_file": shard_file.name if is_sharded or not epics else None,
+    }
+
+
+@click.command("epic-add")
+@click.argument("epic_id", type=str)
+@click.argument("title", type=str)
+@click.option("--priority", type=click.Choice(["P0", "P1", "P2", "P3"]), default="P1")
+@click.option("--status", type=click.Choice(["backlog", "ready", "in_progress"]), default="backlog")
+@click.option("--repos", default="pennyfarthing")
+@click.option("--jira", "jira_id", type=str, default=None, help="Jira epic key (MSSCI-NNNNN)")
+@click.option("--description", "-d", type=str, default=None, help="Epic description")
+@click.option("--sprint-file", type=click.Path(), default=None, help="Path to sprint YAML file")
+def epic_add_command(
+    epic_id: str,
+    title: str,
+    priority: str,
+    status: str,
+    repos: str,
+    jira_id: str | None,
+    description: str | None,
+    sprint_file: str | None,
+) -> None:
+    """Add a new epic to the current sprint."""
+    if sprint_file is None:
+        from pennyfarthing_scripts.common.config import get_project_root
+        path = get_project_root() / "sprint" / "current-sprint.yaml"
+    else:
+        path = Path(sprint_file)
+
+    result = add_epic(
+        sprint_path=path,
+        epic_id=epic_id,
+        title=title,
+        priority=priority,
+        status=status,
+        repos=repos,
+        jira=jira_id,
+        description=description,
+    )
+
+    if result["success"]:
+        msg = f"Added epic {result['epic_id']}: {title}"
+        if result.get("shard_file"):
+            msg += f" ({result['shard_file']})"
+        click.echo(msg)
+    else:
+        raise click.ClickException(result["error"])

package/pennyfarthing_scripts/sprint/loader.py

@@ -2,6 +2,7 @@
 Sprint YAML parsing utilities for Pennyfarthing scripts.
 
 Provides access to sprint/current-sprint.yaml data.
+Supports sharded per-epic format (epic-{ref}.yaml shard files).
 """
 
 from pathlib import Path
@@ -10,9 +11,47 @@ from typing import Any
 from pennyfarthing_scripts.common.config import get_project_root, load_yaml_config
 
 
+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.
+
+    Args:
+        data: Sprint data with possible string refs in epics
+        sprint_dir: Directory containing the shard files
+
+    Returns:
+        Sprint data with full epic dicts
+    """
+    epics = data.get("epics", [])
+    if not epics or not isinstance(epics[0], str):
+        return data
+
+    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)
+
+    data["epics"] = merged_epics
+    return data
+
+
 def load_sprint(project_root: Path | None = None) -> dict[str, Any] | None:
     """Load sprint data from project root.
 
+    Supports both monolithic and sharded epic formats. When epics are
+    string references, the corresponding epic-{ref}.yaml files are
+    loaded and merged transparently.
+
     Args:
         project_root: Project root path (defaults to auto-detect)
 
@@ -20,8 +59,13 @@ def load_sprint(project_root: Path | None = None) -> dict[str, Any] | None:
         Sprint data as dict, or None if not found
     """
     root = project_root or get_project_root()
-    sprint_path = root / "sprint" / "current-sprint.yaml"
-    return load_yaml_config(sprint_path)
+    sprint_dir = root / "sprint"
+    sprint_path = sprint_dir / "current-sprint.yaml"
+    data = load_yaml_config(sprint_path)
+    if data is None:
+        return None
+
+    return _merge_epic_shards(data, sprint_dir)
 
 
 def find_epic(sprint_data: dict[str, Any], epic_num: str) -> dict[str, Any] | None:

package/pennyfarthing_scripts/sprint/story_add.py

@@ -5,6 +5,7 @@ Story: MSSCI-14256 - Sprint story add command
 This module provides:
 - generate_story_id(sprint_data, epic) -> str
 - add_story(sprint_path, epic_id, title, points, ...) -> dict
+- add_initiative_story(initiative_slug, title, points, ...) -> dict
 - story_add_command (Click command for CLI registration)
 """
 
@@ -144,44 +145,218 @@ def add_story(
     }
 
 
+def _generate_initiative_story_id(init_data: dict[str, Any], slug: str) -> str:
+    """Generate the next standalone story ID for an initiative.
+
+    Uses the pattern {slug-prefix}-{N} where slug-prefix is derived from
+    the initiative slug (e.g., "technical-debt" -> "td", "quality-scale" -> "qs").
+    Only counts existing stories that share the same prefix.
+
+    Args:
+        init_data: Initiative YAML data
+        slug: Initiative slug (e.g., "technical-debt")
+
+    Returns:
+        Next story ID string (e.g., "td-2")
+    """
+    # Build prefix from initiative slug initials
+    parts = slug.split("-")
+    prefix = "".join(p[0] for p in parts if p)
+
+    stories = init_data.get("standalone_stories", [])
+    max_seq = 0
+    for story in stories:
+        story_id = str(story.get("id", ""))
+        # Only count stories with matching prefix
+        if not story_id.startswith(f"{prefix}-"):
+            continue
+        suffix = story_id[len(prefix) + 1:]
+        try:
+            seq = int(suffix)
+            if seq > max_seq:
+                max_seq = seq
+        except ValueError:
+            pass
+
+    return f"{prefix}-{max_seq + 1}"
+
+
+def add_initiative_story(
+    initiative_slug: str,
+    title: str,
+    points: int,
+    *,
+    story_type: str | None = None,
+    priority: str = "P1",
+    workflow: str = "tdd",
+    jira: str | None = None,
+    repos: str = "pennyfarthing",
+) -> dict[str, Any]:
+    """Add a standalone story to an initiative YAML file.
+
+    Args:
+        initiative_slug: Initiative slug (e.g., "technical-debt")
+        title: Story title
+        points: Story points
+        story_type: Optional story type (feature, bug, chore, refactor)
+        priority: Priority (default: P1)
+        workflow: Workflow (default: tdd)
+        jira: Optional Jira key
+        repos: Repos (default: pennyfarthing)
+
+    Returns:
+        Dict with success status and story_id or error
+    """
+    from pennyfarthing_scripts.common.config import get_project_root
+
+    root = get_project_root()
+    init_path = root / "sprint" / f"initiative-{initiative_slug}.yaml"
+
+    if not init_path.exists():
+        available = [
+            f.stem.replace("initiative-", "")
+            for f in (root / "sprint").glob("initiative-*.yaml")
+        ]
+        return {
+            "success": False,
+            "error": f"Initiative '{initiative_slug}' not found. Available: {', '.join(sorted(available))}",
+        }
+
+    # Use ruamel.yaml to preserve block scalars and formatting
+    from ruamel.yaml import YAML as RuamelYAML
+
+    ryml = RuamelYAML()
+    ryml.preserve_quotes = True
+    ryml.default_flow_style = False
+    ryml.indent(mapping=2, sequence=4, offset=2)
+    ryml.width = 4096
+
+    with open(init_path) as f:
+        init_data = ryml.load(f)
+
+    if not init_data:
+        return {"success": False, "error": f"Empty initiative file: {init_path}"}
+
+    story_id = _generate_initiative_story_id(init_data, initiative_slug)
+
+    story: dict[str, Any] = {
+        "id": story_id,
+        "title": title,
+        "points": points,
+        "priority": priority,
+        "status": "backlog",
+        "repos": repos,
+        "workflow": workflow,
+    }
+    if jira is not None:
+        story["jira"] = jira
+    if story_type is not None:
+        story["type"] = story_type
+
+    if "standalone_stories" not in init_data:
+        init_data["standalone_stories"] = []
+    init_data["standalone_stories"].append(story)
+
+    # Update total_points
+    current_total = init_data.get("total_points", 0) or 0
+    init_data["total_points"] = current_total + points
+
+    with open(init_path, "w") as f:
+        ryml.dump(init_data, f)
+
+    return {
+        "success": True,
+        "story_id": story_id,
+    }
+
+
 @click.command("add")
-@click.argument("epic_id", type=str)
-@click.argument("title", type=str)
-@click.argument("points", type=int)
+@click.argument("epic_id", type=str, required=False)
+@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("--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)")
 def story_add_command(
-    epic_id: str,
-    title: str,
-    points: int,
+    epic_id: str | None,
+    title: str | None,
+    points: int | None,
     story_type: str,
     priority: str,
     workflow: str,
     jira_id: str | None,
     sprint_file: str | None,
+    initiative: str | None,
+    repos: str,
 ) -> None:
-    """Add a new story to an epic."""
-    if sprint_file is None:
-        from pennyfarthing_scripts.common.config import get_project_root
-        path = get_project_root() / "sprint" / "current-sprint.yaml"
-    else:
-        path = Path(sprint_file)
-
-    result = add_story(
-        sprint_path=path,
-        epic_id=epic_id,
-        title=title,
-        points=points,
-        story_type=story_type if story_type != "feature" else None,
-        priority=priority,
-        workflow=workflow,
-        jira=jira_id,
-    )
-
-    if result["success"]:
-        click.echo(f"Added story {result['story_id']}: {title} [{points}pts]")
+    """Add a new story to an epic or initiative.
+
+    \b
+    Epic mode (default):
+      pf sprint story add <EPIC_ID> <TITLE> <POINTS>
+
+    Initiative mode (--initiative):
+      pf sprint story add --initiative <SLUG> <TITLE> <POINTS>
+    """
+    if initiative:
+        # Initiative mode: first positional arg is title, second is points
+        # epic_id absorbs the title, title absorbs points (as str)
+        if epic_id is None:
+            raise click.ClickException("TITLE is required")
+        init_title = epic_id
+        if title is None:
+            raise click.ClickException("POINTS is required")
+        try:
+            init_points = int(title)
+        except ValueError:
+            raise click.ClickException(f"POINTS must be an integer, got '{title}'")
+
+        result = add_initiative_story(
+            initiative_slug=initiative,
+            title=init_title,
+            points=init_points,
+            story_type=story_type if story_type != "feature" else None,
+            priority=priority,
+            workflow=workflow,
+            jira=jira_id,
+            repos=repos,
+        )
+
+        if result["success"]:
+            click.echo(f"Added story {result['story_id']}: {init_title} [{init_points}pts] to initiative {initiative}")
+        else:
+            raise click.ClickException(result["error"])
     else:
-        raise click.ClickException(result["error"])
+        # Epic mode: all three positional args required
+        if epic_id is None:
+            raise click.ClickException("EPIC_ID is required")
+        if title is None:
+            raise click.ClickException("TITLE is required")
+        if points is None:
+            raise click.ClickException("POINTS is required")
+
+        if sprint_file is None:
+            from pennyfarthing_scripts.common.config import get_project_root
+            path = get_project_root() / "sprint" / "current-sprint.yaml"
+        else:
+            path = Path(sprint_file)
+
+        result = add_story(
+            sprint_path=path,
+            epic_id=epic_id,
+            title=title,
+            points=points,
+            story_type=story_type if story_type != "feature" else None,
+            priority=priority,
+            workflow=workflow,
+            jira=jira_id,
+        )
+
+        if result["success"]:
+            click.echo(f"Added story {result['story_id']}: {title} [{points}pts]")
+        else:
+            raise click.ClickException(result["error"])