@pennyfarthing/core 11.3.2 → 11.3.4

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

@@ -0,0 +1,2021 @@
+"""
+Sprint CLI - Click-based CLI for sprint operations.
+
+Usage:
+    pf sprint [COMMAND] [ARGS]...
+
+Commands:
+    status      Show sprint status
+    backlog     Show available stories
+    use         Switch active sprint (multi-sprint projects)
+    list        Show registered sprints from sprint/sprints.yaml
+    active      Show which sprint is currently active
+    work        Start work on a story
+    archive     Archive a completed story
+    story       Story subcommands (show, add, update, size, template, finish, claim)
+    epic        Epic subcommands (show, add, promote, archive, cancel, import, remove)
+    initiative  Initiative subcommands (show, cancel)
+"""
+
+import click
+
+
+@click.group()
+def sprint():
+    """Sprint status and story operations.
+
+    \b
+    Commands:
+      status   - Show sprint status
+      backlog  - Show available stories
+      use      - Switch active sprint (multi-sprint projects)
+      list     - Show registered sprints
+      active   - Show which sprint is active
+      story    - Story operations (show, add, update, size, template, finish, claim)
+      epic     - Epic operations (show, add, promote, archive, cancel, import, remove)
+      initiative - Initiative operations (show, cancel)
+      work     - Start work on a story
+      archive  - Archive a completed story
+    """
+    pass
+
+
+@sprint.command()
+@click.argument("filter", required=False, type=click.Choice(
+    ["backlog", "todo", "in-progress", "review", "done"],
+    case_sensitive=False,
+))
+def status(filter: str | None):
+    """Show sprint status.
+
+    \b
+    Arguments:
+      FILTER  - Optional status filter (backlog, in-progress, done, etc.)
+    """
+    # Lazy import to maintain startup performance
+    from pf.sprint.status import format_status, get_sprint_status
+
+    sprint_status = get_sprint_status(filter)
+    click.echo(format_status(sprint_status))
+
+
+@sprint.command()
+def backlog():
+    """Show available stories grouped by epic.
+
+    Shows stories with backlog, ready, or planning status.
+    Output is grouped by epic with a markdown table per epic.
+    """
+    from pf.sprint.loader import load_sprint
+
+    data = load_sprint()
+    if not data or "epics" not in data:
+        click.echo("No sprint data available")
+        return
+
+    sprint_info = data.get("sprint", {})
+    click.echo(f"# Available Stories - {sprint_info.get('name', 'Unknown Sprint')}")
+    click.echo("")
+
+    available_statuses = {"backlog", "ready", "planning"}
+    total_count = 0
+    total_points = 0
+
+    for epic in data["epics"]:
+        if not isinstance(epic, dict):
+            continue
+
+        stories = [
+            s for s in epic.get("stories", [])
+            if s.get("status") in available_statuses
+        ]
+        if not stories:
+            continue
+
+        click.echo(f"### {epic.get('title', 'Unknown Epic')}")
+        if epic.get("description"):
+            desc = epic["description"].strip().split("\n")[0][:200]
+            click.echo(f"*{desc}*")
+        click.echo("")
+        click.echo("| ID | Title | Pts | Pri | Status | Assigned | Workflow |")
+        click.echo("|----|-------|-----|-----|--------|----------|----------|")
+
+        for s in stories:
+            title = s.get("title", "?")
+            if len(title) > 40:
+                title = title[:37] + "..."
+            sid = s.get("id", "?")
+            pts = s.get("points", "?")
+            pri = s.get("priority", "P2")
+            stat = s.get("status", "backlog")
+            wf = s.get("workflow", "tdd")
+            assigned = s.get("assigned_to", "")
+            if assigned:
+                parts = assigned.split("@")[0].split(".")
+                if len(parts) >= 2:
+                    assigned = f"{parts[0][0].upper()}. {parts[-1].capitalize()}"
+            click.echo(f"| {sid} | {title} | {pts} | {pri} | {stat} | {assigned} | {wf} |")
+            total_count += 1
+            total_points += s.get("points", 0) or 0
+
+        click.echo("")
+
+    click.echo("---")
+    click.echo(f"**Total available:** {total_count} stories, {total_points} points")
+
+
+@sprint.command("use")
+@click.argument("name")
+def sprint_use(name: str):
+    """Switch the active sprint (per-user preference).
+
+    \b
+    Validates the sprint name against sprint/sprints.yaml, then saves
+    the preference to .pennyfarthing/config.local.yaml. Does not modify
+    any shared repo files. Use "default" to clear the preference.
+
+    \b
+    Arguments:
+      NAME  - Sprint name from the registry, or "default" to clear
+
+    \b
+    Examples:
+      pf sprint use main       # Switch to main project sprint
+      pf sprint use ocsf-rs1   # Switch to OCSF research spike
+      pf sprint use default    # Clear preference, use sprint/current-sprint.yaml
+    """
+    # Lazy import
+    from pf.sprint.loader import switch_sprint
+
+    result = switch_sprint(name)
+    if result["success"]:
+        entry = result.get("sprint", {})
+        click.echo(result["message"])
+        if entry.get("description"):
+            click.echo(f"  {entry['description']}")
+        if entry.get("type"):
+            click.echo(f"  Type: {entry['type']}")
+        if entry.get("repos"):
+            click.echo(f"  Repos: {', '.join(entry['repos'])}")
+    else:
+        raise click.ClickException(result["error"])
+
+
+@sprint.command("list")
+def sprint_list():
+    """Show all registered sprints from the sprint registry.
+
+    \b
+    Reads sprint/sprints.yaml and displays each registered sprint
+    with its type, description, and whether it is currently active
+    for this user (based on .pennyfarthing/config.local.yaml).
+    """
+    # Lazy import
+    from pf.sprint.loader import get_active_sprint_name, load_sprint_registry
+
+    registry = load_sprint_registry()
+    if registry is None:
+        click.echo("No sprint registry found (sprint/sprints.yaml)")
+        click.echo("This project uses a single sprint.")
+        return
+
+    active = get_active_sprint_name()
+    sprints = registry.get("sprints", {})
+
+    if not sprints:
+        click.echo("Sprint registry is empty.")
+        return
+
+    click.echo("Registered Sprints:")
+    click.echo("")
+
+    for name, entry in sprints.items():
+        marker = "*" if name == active else " "
+        desc = entry.get("description", "")
+        sprint_type = entry.get("type", "project")
+        repos = ", ".join(entry.get("repos", []))
+        click.echo(f"  {marker} {name:<16} [{sprint_type}] {desc}")
+        if repos:
+            click.echo(f"    Repos: {repos}")
+
+    click.echo("")
+    if active:
+        click.echo(f"Active: {active} (per-user preference)")
+    else:
+        click.echo("Active: default (sprint/current-sprint.yaml)")
+    click.echo("Switch: pf sprint use <name>")
+
+
+@sprint.command("active")
+def sprint_active():
+    """Show which sprint is currently active for this user.
+
+    \b
+    Reads the per-user preference from .pennyfarthing/config.local.yaml
+    and displays the active sprint name and metadata. If no preference
+    is set, reports the default sprint/current-sprint.yaml.
+    """
+    # Lazy import
+    from pf.sprint.loader import get_active_sprint_name, load_sprint_registry
+
+    active = get_active_sprint_name()
+    if not active:
+        click.echo("default (sprint/current-sprint.yaml)")
+        click.echo("  No per-user sprint preference set.")
+        click.echo("  Set one with: pf sprint use <name>")
+        return
+
+    registry = load_sprint_registry()
+    if registry:
+        sprints = registry.get("sprints", {})
+        entry = sprints.get(active, {})
+        sprint_type = entry.get("type", "project")
+        desc = entry.get("description", "")
+        click.echo(f"{active} ({sprint_type})")
+        if desc:
+            click.echo(f"  {desc}")
+    else:
+        click.echo(f"{active}")
+        click.echo("  (no sprint registry found to look up metadata)")
+
+
+@sprint.command()
+@click.argument("story_id", required=False)
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def work(story_id: str | None, dry_run: bool):
+    """Start work on a story.
+
+    \b
+    Arguments:
+      STORY_ID  - Story ID to work on, or 'next' for highest priority
+    """
+    # Lazy import
+    from pf.sprint.loader import get_stories_by_status
+    from pf.sprint.work import check_story, get_next_story
+
+    if not story_id:
+        # Show backlog
+        stories = get_stories_by_status("backlog")
+        click.echo(f"Available stories: {len(stories)}")
+        for story in stories[:10]:
+            click.echo(f"  {story.get('id')}: {story.get('title')} [{story.get('points', '?')}pts]")
+        return
+
+    if story_id == "next":
+        result = get_next_story()
+    else:
+        result = check_story(story_id)
+
+    if result.get("available"):
+        story = result.get("story", {})
+        click.echo(f"Story: {story.get('id')}")
+        click.echo(f"Title: {story.get('title')}")
+        click.echo(f"Points: {story.get('points')}")
+        click.echo("Status: Available")
+    else:
+        error_msg = result.get("error") or result.get("reason")
+        raise click.ClickException(f"Not available: {error_msg}")
+
+
+@sprint.command()
+@click.argument("story_id")
+@click.argument("pr_number", required=False)
+@click.option("--apply", is_flag=True, help="Also remove from current-sprint.yaml")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def archive(story_id: str, pr_number: str | None, apply: bool, dry_run: bool):
+    """Archive a completed story.
+
+    \b
+    Arguments:
+      STORY_ID   - Story ID to archive
+      PR_NUMBER  - Optional PR number if merged via PR
+    """
+    # Lazy import
+    from pf.sprint.archive import archive_story
+
+    result = archive_story(
+        story_id,
+        pr_number=pr_number,
+        dry_run=dry_run,
+        apply=apply,
+    )
+
+    if result.get("success"):
+        if result.get("dry_run"):
+            click.echo(f"[DRY-RUN] {result.get('message')}")
+        else:
+            click.echo(result.get("message"))
+    else:
+        raise click.ClickException(f"Failed: {result.get('error')}")
+
+
+# --- Story subgroup ---
+
+@sprint.group()
+def story():
+    """Story operations (show, add, update, size, template, finish, claim)."""
+    pass
+
+
+@story.command("show")
+@click.argument("story_id")
+@click.option("--json", "output_json", is_flag=True, help="Output as JSON")
+def story_show(story_id: str, output_json: bool):
+    """Show details for a specific story.
+
+    \b
+    Arguments:
+      STORY_ID  - Story ID (e.g., MSSCI-12664 or 67-1)
+    """
+    # Lazy import
+    from pf.sprint.loader import get_story_by_id
+
+    story_data = get_story_by_id(story_id)
+
+    if not story_data:
+        raise click.ClickException(f"Story not found: {story_id}")
+
+    if output_json:
+        import json
+
+        click.echo(json.dumps(story_data, indent=2))
+    else:
+        click.echo(f"Story: {story_data.get('id', story_id)}")
+        click.echo(f"Title: {story_data.get('title', 'N/A')}")
+        click.echo(f"Points: {story_data.get('points', 'N/A')}")
+        click.echo(f"Status: {story_data.get('status', 'N/A')}")
+        if story_data.get("priority"):
+            click.echo(f"Priority: {story_data.get('priority')}")
+        if story_data.get("workflow"):
+            click.echo(f"Workflow: {story_data.get('workflow')}")
+        if story_data.get("jira"):
+            click.echo(f"Jira: {story_data.get('jira')}")
+        if story_data.get("description"):
+            click.echo(f"Description: {story_data.get('description')}")
+
+
+@story.command("size")
+@click.argument("points", required=False, type=int)
+def story_size(points: int | None):
+    """Display story sizing guidelines.
+
+    \b
+    Arguments:
+      POINTS  - Optional specific point value to show guidance for
+    """
+    from pf.story.size import format_size_info, get_sizing_guidelines
+
+    guidelines = get_sizing_guidelines(points)
+    click.echo(format_size_info(guidelines))
+
+
+@story.command("template")
+@click.argument("template_type", required=False)
+def story_template(template_type: str | None):
+    """Display story templates by type.
+
+    \b
+    Arguments:
+      TYPE  - Template type (feature, bug, refactor, chore)
+    """
+    from pf.story.template import get_all_templates, get_template
+
+    if template_type:
+        template = get_template(template_type)
+        if template:
+            click.echo(f"Type: {template['type']}")
+            click.echo(f"Description: {template['description']}")
+            click.echo("")
+            click.echo("Template:")
+            click.echo(template["template"])
+        else:
+            raise click.ClickException(f"Unknown template type: {template_type}")
+    else:
+        click.echo("Available templates:")
+        for name, template in get_all_templates().items():
+            click.echo(f"  {name}: {template['description']}")
+
+
+@story.command("finish")
+@click.argument("story_id")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without executing")
+def story_finish(story_id: str, dry_run: bool):
+    """Complete a story: archive session, merge PR, transition Jira, update sprint YAML.
+
+    \b
+    Arguments:
+      STORY_ID  - Story ID (e.g., 83-2)
+    """
+    from pf.common.config import get_project_root
+    from pf.sprint.story_finish import finish_story
+
+    root = get_project_root()
+    result = finish_story(root, story_id, dry_run=dry_run)
+
+    if not result["success"]:
+        raise click.ClickException(result["error"])
+
+    if result.get("dry_run"):
+        click.echo(f"[DRY RUN] Finish story {story_id} ({result.get('jira_key', '?')})")
+        for step in result.get("steps", []):
+            click.echo(f"  {step['step']}. {step['action']}")
+        return
+
+    click.echo(f"=== Story {story_id} Complete ===")
+    jira_key = result.get("jira_key")
+    if jira_key:
+        click.echo(f"Jira: https://1898andco.atlassian.net/browse/{jira_key}")
+    for step in result.get("steps", []):
+        warning = step.get("warning", "")
+        error = step.get("error", "")
+        suffix = f" (warning: {warning})" if warning else f" (error: {error})" if error else ""
+        click.echo(f"  {step['step']}. {step['action']}{suffix}")
+
+
+@story.command("claim")
+@click.argument("story_id")
+@click.option("--claim/--unclaim", default=True, help="Claim or unclaim the story")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def story_claim(story_id: str, claim: bool, dry_run: bool):
+    """Claim or unclaim a story in Jira.
+
+    \b
+    Arguments:
+      STORY_ID  - Story ID / Jira key to claim
+    """
+    if dry_run:
+        action = "claim" if claim else "unclaim"
+        click.echo(f"[DRY-RUN] Would {action} {story_id}")
+        return
+    from pf.jira.claim import claim_issue, unclaim_issue
+
+    if claim:
+        result = claim_issue(story_id)
+    else:
+        result = unclaim_issue(story_id)
+
+    if result.get("success"):
+        click.echo(result.get("message", f"{'Claimed' if claim else 'Unclaimed'} {story_id}"))
+    else:
+        raise click.ClickException(result.get("error", "Unknown error"))
+
+
+# Register story-add as story.add
+from pf.sprint.story_add import story_add_command  # noqa: E402
+
+story.add_command(story_add_command, "add")
+
+# Register story-update as story.update
+from pf.sprint.story_update import story_update_command  # noqa: E402
+
+story.add_command(story_update_command, "update")
+
+
+# --- Epic subgroup ---
+
+@sprint.group()
+def epic():
+    """Epic operations (show, add, promote, archive, cancel, import, remove)."""
+    pass
+
+
+@epic.command("show")
+@click.argument("epic_id")
+@click.option("--json", "output_json", is_flag=True, help="Output as JSON")
+def epic_show(epic_id: str, output_json: bool):
+    """Show details for a specific epic.
+
+    Searches both the current sprint and future initiative shards.
+
+    \b
+    Arguments:
+      EPIC_ID  - Epic ID (e.g., epic-42 or MSSCI-14298)
+
+    \b
+    Examples:
+      pf sprint epic show MSSCI-14298
+      pf sprint epic show epic-42
+      pf sprint epic show epic-42 --json
+    """
+    import json as json_mod
+
+    from pf.common.config import get_project_root
+    from pf.sprint.loader import load_sprint
+
+    root = get_project_root()
+    epic_data = None
+    source = None
+
+    # 1. Search current sprint
+    sprint_data = load_sprint(root)
+    if sprint_data and "epics" in sprint_data:
+        for e in sprint_data["epics"]:
+            if isinstance(e, dict):
+                eid = str(e.get("id", ""))
+                ejira = str(e.get("jira", ""))
+                if epic_id in (eid, ejira, eid.replace("epic-", ""), f"epic-{epic_id}"):
+                    epic_data = e
+                    source = "current sprint"
+                    break
+
+    # 2. Search future initiative shards
+    if not epic_data:
+        epic_data, source = _find_epic_in_initiatives(epic_id, root)
+
+    if not epic_data:
+        raise click.ClickException(f"Epic not found: {epic_id}")
+
+    if output_json:
+        # Convert to plain dict for JSON serialization
+        click.echo(json_mod.dumps(dict(epic_data), indent=2, default=str))
+    else:
+        click.echo(f"Epic: {epic_data.get('id', epic_id)}")
+        click.echo(f"Title: {epic_data.get('title', 'N/A')}")
+        click.echo(f"Status: {epic_data.get('status', 'N/A')}")
+        click.echo(f"Points: {epic_data.get('points', 'N/A')}")
+        click.echo(f"Source: {source}")
+        if epic_data.get("priority"):
+            click.echo(f"Priority: {epic_data.get('priority')}")
+        if epic_data.get("jira"):
+            click.echo(f"Jira: {epic_data.get('jira')}")
+        if epic_data.get("repos"):
+            click.echo(f"Repos: {epic_data.get('repos')}")
+        if epic_data.get("description"):
+            click.echo(f"Description: {epic_data.get('description').rstrip()}")
+
+        stories = epic_data.get("stories", [])
+        if stories:
+            click.echo(f"\nStories ({len(stories)}):")
+            for s in stories:
+                sid = s.get("id", "?")
+                stitle = s.get("title", "?")
+                spts = s.get("points", "?")
+                sstat = s.get("status", "?")
+                click.echo(f"  {sid}: {stitle} [{spts}pts] ({sstat})")
+
+
+def _epic_shard_path(sprint_dir, ref: str):
+    """Resolve an epic shard file path from a ref string.
+
+    Handles both 'epic-42' and 'MSSCI-12792' style refs.
+    The file naming convention is epic-{ref}.yaml, but refs that
+    already start with 'epic-' should not be double-prefixed.
+    """
+    if ref.startswith("epic-"):
+        return sprint_dir / f"{ref}.yaml"
+    return sprint_dir / f"epic-{ref}.yaml"
+
+
+def _epic_ref_matches(ref: str, epic_id: str) -> bool:
+    """Check if an initiative epic ref matches the requested epic_id."""
+    # Normalize both to compare without prefix
+    ref_bare = ref.replace("epic-", "") if ref.startswith("epic-") else ref
+    id_bare = epic_id.replace("epic-", "") if epic_id.startswith("epic-") else epic_id
+    return ref_bare == id_bare or ref == epic_id
+
+
+def _find_epic_in_initiatives(epic_id: str, root):
+    """Search initiative shard files for an epic by ID.
+
+    Returns (epic_dict, source_string) or (None, None).
+    """
+    import yaml
+
+    sprint_dir = root / "sprint"
+    for init_file in sorted(sprint_dir.glob("initiative-*.yaml")):
+        with open(init_file) as f:
+            init_data = yaml.safe_load(f.read())
+        if not init_data:
+            continue
+
+        init_name = init_data.get("name", init_file.stem)
+        epics = init_data.get("epics", [])
+        for e in epics:
+            if isinstance(e, str):
+                if _epic_ref_matches(e, epic_id):
+                    shard = _epic_shard_path(sprint_dir, e)
+                    if shard.exists():
+                        with open(shard) as sf:
+                            epic_data = yaml.safe_load(sf.read())
+                        if epic_data:
+                            return epic_data, f"initiative: {init_name}"
+            elif isinstance(e, dict):
+                eid = str(e.get("id", ""))
+                if _epic_ref_matches(eid, epic_id):
+                    return e, f"initiative: {init_name}"
+
+    return None, None
+
+
+@epic.command("cancel")
+@click.argument("epic_id")
+@click.option("--jira", is_flag=True, help="Also cancel the epic in Jira")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def epic_cancel(epic_id: str, jira: bool, dry_run: bool):
+    """Cancel an epic and all its stories.
+
+    Sets the epic status to 'canceled' and all stories to 'canceled'.
+    Searches both the current sprint and future initiative shards.
+
+    \b
+    Arguments:
+      EPIC_ID  - Epic ID (e.g., epic-42 or MSSCI-14298)
+
+    \b
+    Examples:
+      pf sprint epic cancel epic-42 --dry-run
+      pf sprint epic cancel epic-42
+      pf sprint epic cancel epic-42 --jira
+    """
+    from pf.common.config import get_project_root
+    from pf.sprint.yaml_io import read_sprint, write_sprint
+
+    root = get_project_root()
+    sprint_dir = root / "sprint"
+    sprint_path = sprint_dir / "current-sprint.yaml"
+
+    # 1. Try current sprint
+    sprint_data = read_sprint(sprint_path) if sprint_path.exists() else None
+    found_in_sprint = False
+    if sprint_data and "epics" in sprint_data:
+        for e in sprint_data["epics"]:
+            if not isinstance(e, dict):
+                continue
+            eid = str(e.get("id", ""))
+            ejira = str(e.get("jira", ""))
+            if epic_id in (eid, ejira, eid.replace("epic-", ""), f"epic-{epic_id}"):
+                found_in_sprint = True
+                jira_key = e.get("jira")
+                stories = e.get("stories", [])
+                story_count = len(stories)
+
+                click.echo(f"Epic: {eid}")
+                click.echo(f"Title: {e.get('title', 'N/A')}")
+                click.echo(f"Stories: {story_count}")
+
+                if jira_key and not jira:
+                    click.echo(f"\nWarning: Epic has Jira key {jira_key} -- pass --jira to also cancel in Jira")
+
+                if dry_run:
+                    click.echo(f"\n[DRY-RUN] Would cancel {eid} and {story_count} stories")
+                    return
+
+                e["status"] = "canceled"
+                for s in stories:
+                    s["status"] = "canceled"
+
+                write_sprint(sprint_path, sprint_data)
+                click.echo(f"\nCanceled {eid} and {story_count} stories in current sprint")
+
+                if jira and jira_key:
+                    _transition_jira(jira_key, "Cancelled")
+                    click.echo(f"Transitioned Jira {jira_key} to Cancelled")
+                return
+
+    # 2. Try initiative shards
+    if not found_in_sprint:
+        _cancel_epic_in_initiatives(epic_id, root, jira=jira, dry_run=dry_run)
+
+
+def _transition_jira(jira_key: str, status: str) -> bool:
+    """Transition a Jira issue to the given status."""
+    import subprocess
+
+    try:
+        result = subprocess.run(
+            ["jira", "issue", "move", jira_key, status],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        return result.returncode == 0
+    except Exception:
+        return False
+
+
+def _cancel_epic_in_initiatives(epic_id: str, root, *, jira: bool, dry_run: bool):
+    """Find and cancel an epic in initiative shard files."""
+    import yaml
+
+    sprint_dir = root / "sprint"
+
+    for init_file in sorted(sprint_dir.glob("initiative-*.yaml")):
+        with open(init_file) as f:
+            raw = f.read()
+        init_data = yaml.safe_load(raw)
+        if not init_data:
+            continue
+
+        init_name = init_data.get("name", init_file.stem)
+        epics = init_data.get("epics", [])
+
+        for _i, e in enumerate(epics):
+            matched = False
+            epic_dict = None
+
+            if isinstance(e, str):
+                if _epic_ref_matches(e, epic_id):
+                    shard = _epic_shard_path(sprint_dir, e)
+                    if shard.exists():
+                        with open(shard) as sf:
+                            epic_dict = yaml.safe_load(sf.read())
+                        matched = True
+            elif isinstance(e, dict):
+                eid = str(e.get("id", ""))
+                if _epic_ref_matches(eid, epic_id):
+                    epic_dict = e
+                    matched = True
+
+            if not matched or not epic_dict:
+                continue
+
+            jira_key = epic_dict.get("jira")
+            stories = epic_dict.get("stories", [])
+            story_count = len(stories)
+
+            click.echo(f"Epic: {epic_dict.get('id', epic_id)}")
+            click.echo(f"Title: {epic_dict.get('title', 'N/A')}")
+            click.echo(f"Initiative: {init_name}")
+            click.echo(f"Stories: {story_count}")
+
+            if jira_key and not jira:
+                click.echo(f"\nWarning: Epic has Jira key {jira_key} -- pass --jira to also cancel in Jira")
+
+            if dry_run:
+                click.echo(f"\n[DRY-RUN] Would cancel {epic_dict.get('id', epic_id)} and {story_count} stories")
+                return
+
+            epic_dict["status"] = "canceled"
+            for s in stories:
+                s["status"] = "canceled"
+
+            # Write back — either shard file or inline in initiative
+            if isinstance(e, str):
+                shard = _epic_shard_path(sprint_dir, e)
+                with open(shard, "w") as sf:
+                    yaml.dump(dict(epic_dict), sf, default_flow_style=False, sort_keys=False)
+            else:
+                with open(init_file, "w") as f:
+                    yaml.dump(init_data, f, default_flow_style=False, sort_keys=False)
+
+            click.echo(f"\nCanceled {epic_dict.get('id', epic_id)} and {story_count} stories")
+
+            if jira and jira_key:
+                _transition_jira(jira_key, "Cancelled")
+                click.echo(f"Transitioned Jira {jira_key} to Cancelled")
+            return
+
+    raise click.ClickException(f"Epic not found: {epic_id}")
+
+
+@epic.command("archive")
+@click.argument("epic_id", required=False)
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+@click.option("--jira", is_flag=True, help="Also update Jira epic status to Done")
+def epic_archive(epic_id: str | None, dry_run: bool, jira: bool):
+    """Archive completed epics.
+
+    \b
+    Arguments:
+      EPIC_ID  - Epic ID to archive (omit to scan all completed epics)
+
+    \b
+    Examples:
+      pf sprint epic archive                    # Scan and archive all completed
+      pf sprint epic archive --dry-run          # Preview what would be archived
+      pf sprint epic archive epic-64            # Archive specific epic
+      pf sprint epic archive epic-64 --jira     # Archive and update Jira
+    """
+    # Lazy import
+    from pf.sprint.archive_epic import (
+        archive_all_completed,
+    )
+    from pf.sprint.archive_epic import (
+        archive_epic as do_archive_epic,
+    )
+
+    if epic_id:
+        result = do_archive_epic(epic_id, dry_run=dry_run, update_jira=jira)
+    else:
+        result = archive_all_completed(dry_run=dry_run, update_jira=jira)
+
+    if result.get("success"):
+        if dry_run:
+            click.echo(f"[DRY-RUN] {result.get('message')}")
+            if "archived" in result:
+                for r in result["archived"]:
+                    e = r.get("epic", {})
+                    eid = e.get("id") if e else r.get("epic_id")
+                    stories = len(e.get("stories", [])) if e else r.get("stories_archived", 0)
+                    click.echo(f"  Would archive: {eid} ({stories} stories)")
+        else:
+            click.echo(result.get("message"))
+            if "archived" in result:
+                for r in result["archived"]:
+                    click.echo(f"  ✓ {r.get('epic_id')}: {r.get('stories_archived')} stories")
+            if result.get("stories_archived"):
+                click.echo(f"  ✓ {result.get('epic_id')}: {result.get('stories_archived')} stories")
+    else:
+        error_msg = result.get("error", "Unknown error")
+        if result.get("incomplete_stories"):
+            error_msg += f"\n  Incomplete: {', '.join(result['incomplete_stories'])}"
+        raise click.ClickException(error_msg)
+
+
+@epic.command("import")
+@click.argument("epics_file")
+@click.argument("initiative_name", required=False)
+@click.option("--marker", default="imported", help="Marker tag for stories (default: imported)")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def epic_import(epics_file: str, initiative_name: str | None, marker: str, dry_run: bool):
+    """Import BMAD epics-and-stories output to future.yaml.
+
+    \b
+    Arguments:
+      EPICS_FILE       - Path to markdown file from epics-and-stories workflow
+      INITIATIVE_NAME  - Name for the initiative (optional, extracted from file)
+
+    \b
+    Examples:
+      pf sprint epic import docs/planning/my-feature-epics.md
+      pf sprint epic import docs/planning/my-feature-epics.md "My Feature" --marker my-feature
+      pf sprint epic import docs/planning/my-feature-epics.md --dry-run
+    """
+    # Lazy import
+    from pf.sprint.import_epic import import_epic as do_import
+
+    result = do_import(
+        epics_file,
+        initiative_name=initiative_name,
+        marker=marker,
+        dry_run=dry_run,
+    )
+
+    if result.get("success"):
+        if dry_run:
+            click.echo(f"[DRY-RUN] {result.get('message')}")
+            click.echo(f"  Epics: {result.get('epics_count')}")
+            click.echo(f"  Stories: {result.get('stories_count')}")
+            click.echo(f"  Points: {result.get('total_points')}")
+            click.echo(f"  Epic numbers: epic-{result.get('start_epic_num')} to epic-{result.get('next_epic_num') - 1}")
+            click.echo("")
+            click.echo("YAML Preview:")
+            click.echo("-" * 60)
+            click.echo(result.get("yaml_preview"))
+            click.echo("-" * 60)
+        else:
+            click.echo(f"✓ {result.get('message')}")
+            click.echo(f"  Next available epic number: {result.get('next_epic_num')}")
+    else:
+        raise click.ClickException(result.get("error", "Unknown error"))
+
+
+@epic.command("remove")
+@click.argument("epic_id")
+@click.option("--dry-run", is_flag=True, help="Show what would be removed without making changes")
+def epic_remove(epic_id: str, dry_run: bool):
+    """Remove an epic from future.yaml (for cancelled pre-Jira epics).
+
+    \b
+    Arguments:
+      EPIC_ID  - Epic ID to remove (e.g., epic-41)
+
+    \b
+    Examples:
+      pf sprint epic remove epic-41
+      pf sprint epic remove epic-41 --dry-run
+    """
+
+    import yaml
+
+    from pf.common.config import get_project_root
+
+    future_path = get_project_root() / "sprint" / "future.yaml"
+    if not future_path.exists():
+        raise click.ClickException(f"File not found: {future_path}")
+
+    with open(future_path) as f:
+        data = yaml.safe_load(f.read())
+
+    if not data or "future" not in data or "initiatives" not in data["future"]:
+        raise click.ClickException("Invalid future.yaml structure")
+
+    # Find the epic
+    found = False
+    for init in data["future"]["initiatives"]:
+        epics = init.get("epics", [])
+        for e in epics:
+            if e.get("id") == epic_id:
+                found = True
+                story_count = len(e.get("stories", []))
+                click.echo(f"Found epic in initiative '{init.get('name', 'unknown')}':")
+                click.echo(f"  ID: {epic_id}")
+                click.echo(f"  Title: {e.get('title', 'unknown')}")
+                click.echo(f"  Points: {e.get('points', '?')}")
+                click.echo(f"  Stories: {story_count}")
+
+                if dry_run:
+                    click.echo(f"\n[DRY-RUN] Would remove {epic_id} from future.yaml")
+                    return
+
+                # Remove using yq to preserve comments and formatting
+                import subprocess as sp
+
+                result = sp.run(
+                    [
+                        "yq", "eval", "-i",
+                        f'del(.future.initiatives[].epics[] | select(.id == "{epic_id}"))',
+                        str(future_path),
+                    ],
+                    capture_output=True,
+                    text=True,
+                )
+                if result.returncode != 0:
+                    raise click.ClickException(f"yq failed: {result.stderr}")
+
+                click.echo(f"\n✓ Removed {epic_id} from future.yaml")
+                return
+
+    if not found:
+        raise click.ClickException(
+            f"Epic {epic_id} not found in future.yaml"
+        )
+
+
+@epic.command("promote")
+@click.argument("epic_id")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def epic_promote(epic_id: str, dry_run: bool):
+    """Move an epic from future initiatives to current-sprint.yaml.
+
+    Detects ID collisions and assigns new IDs if needed.
+    Automatically removes the epic from its initiative shard after promotion.
+
+    \b
+    Arguments:
+      EPIC_ID  - Epic ID (e.g., epic-41 or 41)
+
+    \b
+    Examples:
+      pf sprint epic promote epic-41
+      pf sprint epic promote 41
+    """
+    import copy
+
+    import yaml
+
+    from pf.common.config import get_project_root
+
+    root = get_project_root()
+    sprint_dir = root / "sprint"
+    sprint_file = sprint_dir / "current-sprint.yaml"
+
+    if not sprint_file.exists():
+        raise click.ClickException(f"Sprint file not found: {sprint_file}")
+
+    # Find the epic in initiative shards
+    epic_data = None
+    source_init_file = None
+    source_ref = None
+
+    for init_file in sorted(sprint_dir.glob("initiative-*.yaml")):
+        with open(init_file) as f:
+            init_data = yaml.safe_load(f.read())
+        if not init_data:
+            continue
+        for e in init_data.get("epics", []):
+            edata = _resolve_epic_ref(e, sprint_dir)
+            if not edata:
+                continue
+            eid = str(edata.get("id", ""))
+            if _epic_ref_matches(eid, epic_id):
+                epic_data = copy.deepcopy(edata)
+                source_init_file = init_file
+                source_ref = e
+                break
+        if epic_data:
+            break
+
+    if not epic_data:
+        raise click.ClickException(f"Epic {epic_id} not found in future initiatives")
+
+    # Load current sprint
+    with open(sprint_file) as f:
+        sprint_data = yaml.safe_load(f.read())
+
+    if not sprint_data:
+        raise click.ClickException(f"Invalid sprint file: {sprint_file}")
+
+    if "epics" not in sprint_data:
+        sprint_data["epics"] = []
+
+    # Check for ID collision
+    original_id = str(epic_data.get("id", epic_id))
+    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:
+            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-", "") if new_epic_id.startswith("epic-") else new_epic_id
+
+    epic_data["id"] = new_epic_id
+    epic_data["status"] = "backlog"
+    if not epic_data.get("title", "").startswith("Epic:"):
+        epic_data["title"] = f"Epic: {epic_data.get('title', 'Unknown')}"
+
+    for s in epic_data.get("stories", []):
+        sid = str(s.get("id", ""))
+        if sid.startswith(f"{old_id_num}-"):
+            s["id"] = sid.replace(f"{old_id_num}-", f"{new_id_num}-", 1)
+        s["status"] = "backlog"
+        s.setdefault("repos", "pennyfarthing")
+        s.setdefault("workflow", "tdd")
+        s.setdefault("priority", "P2")
+        s.setdefault("acceptance_criteria", [])
+
+    story_count = len(epic_data.get("stories", []))
+
+    click.echo("")
+    click.echo("Promoting epic to current sprint:")
+    click.echo(f"  Original ID: {original_id}")
+    if new_epic_id != original_id:
+        click.echo(f"  New ID: {new_epic_id}")
+    click.echo(f"  Title: {epic_data.get('title')}")
+    click.echo(f"  Points: {epic_data.get('points', 0)}")
+    click.echo(f"  Stories: {story_count}")
+    click.echo("")
+
+    if dry_run:
+        click.echo(f"\n[DRY-RUN] Would promote {original_id} ({story_count} stories) to current sprint")
+        return
+
+    # Validate epic shard before writing (ADR-0022)
+    from pf.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)
+
+    from pf.sprint.yaml_io import write_sprint
+    write_sprint(sprint_file, sprint_data)
+    click.echo(f"Added epic to {sprint_file}")
+
+    # Remove from initiative shard
+    with open(source_init_file) as f:
+        init_data = yaml.safe_load(f.read())
+
+    if isinstance(source_ref, str):
+        # String ref — remove from initiative list (shard file is kept for current sprint)
+        init_data["epics"] = [e for e in init_data.get("epics", []) if e != source_ref]
+    else:
+        # Inline dict — remove matching entry
+        init_data["epics"] = [
+            e for e in init_data.get("epics", [])
+            if not (isinstance(e, dict) and _epic_ref_matches(str(e.get("id", "")), epic_id))
+        ]
+
+    remaining_epics = init_data.get("epics", [])
+    if remaining_epics:
+        # Initiative still has epics — update shard in place
+        with open(source_init_file, "w") as f:
+            yaml.dump(init_data, f, default_flow_style=False, sort_keys=False)
+        click.echo(f"Removed {original_id} from {source_init_file.name}")
+    else:
+        # Initiative is empty — remove shard and future.yaml reference
+        init_slug = source_init_file.stem.replace("initiative-", "")
+        source_init_file.unlink()
+        click.echo(f"Removed empty initiative shard: {source_init_file.name}")
+
+        # Remove from future.yaml
+        future_file = sprint_dir / "future.yaml"
+        if future_file.exists():
+            with open(future_file) as f:
+                future_data = yaml.safe_load(f.read()) or {}
+            future_inits = future_data.get("future", {}).get("initiatives", [])
+            if init_slug in future_inits:
+                future_inits.remove(init_slug)
+                with open(future_file, "w") as f:
+                    yaml.dump(future_data, f, default_flow_style=False, sort_keys=False)
+                click.echo(f"Removed '{init_slug}' from future.yaml")
+
+    click.echo("")
+    click.echo("Promotion complete!")
+    click.echo("")
+    click.echo("Next steps:")
+    click.echo(f"  1. Review the epic: pf sprint epic show {new_epic_id}")
+    click.echo(f"  2. Create Jira epic: pf jira create epic {new_epic_id}")
+    click.echo(f"  3. Start work: /sprint work {new_id_num}-1")
+
+
+# Register epic-add as epic.add
+from pf.sprint.epic_add import epic_add_command  # noqa: E402
+
+epic.add_command(epic_add_command, "add")
+
+# Register epic-update as epic.update
+from pf.sprint.epic_update import epic_update_command  # noqa: E402
+
+epic.add_command(epic_update_command, "update")
+
+
+# --- Initiative subgroup ---
+
+@sprint.group()
+def initiative():
+    """Initiative operations (show, cancel)."""
+    pass
+
+
+@initiative.command("show")
+@click.argument("name")
+@click.option("--json", "output_json", is_flag=True, help="Output as JSON")
+def initiative_show(name: str, output_json: bool):
+    """Show details for a specific initiative.
+
+    \b
+    Arguments:
+      NAME  - Initiative slug (e.g., benchmark-reliability, technical-debt)
+
+    \b
+    Examples:
+      pf sprint initiative show benchmark-reliability
+      pf sprint initiative show technical-debt --json
+    """
+    import json as json_mod
+
+    import yaml
+
+    from pf.common.config import get_project_root
+
+    root = get_project_root()
+    init_file = root / "sprint" / f"initiative-{name}.yaml"
+
+    if not init_file.exists():
+        raise click.ClickException(f"Initiative not found: {name}\n  Expected: {init_file}")
+
+    with open(init_file) as f:
+        init_data = yaml.safe_load(f.read())
+
+    if not init_data:
+        raise click.ClickException(f"Empty initiative file: {init_file}")
+
+    if output_json:
+        click.echo(json_mod.dumps(init_data, indent=2, default=str))
+        return
+
+    click.echo(f"Initiative: {init_data.get('name', name)}")
+    click.echo(f"Status: {init_data.get('status', 'N/A')}")
+    if init_data.get("total_points"):
+        click.echo(f"Total Points: {init_data.get('total_points')}")
+    if init_data.get("blocked_by"):
+        click.echo(f"Blocked By: {init_data.get('blocked_by')}")
+    if init_data.get("description"):
+        click.echo(f"Description: {init_data.get('description').rstrip()}")
+
+    epics = init_data.get("epics", [])
+    if epics:
+        click.echo(f"\nEpics ({len(epics)}):")
+        sprint_dir = root / "sprint"
+        for e in epics:
+            if isinstance(e, str):
+                # String ref — try to load shard for details
+                shard = _epic_shard_path(sprint_dir, e)
+                if shard.exists():
+                    with open(shard) as sf:
+                        edata = yaml.safe_load(sf.read())
+                    if edata:
+                        etitle = edata.get("title", "?")
+                        epts = edata.get("points", "?")
+                        estat = edata.get("status", "?")
+                        click.echo(f"  {edata.get('id', e)}: {etitle} [{epts}pts] ({estat})")
+                        continue
+                click.echo(f"  {e} (shard not found)")
+            elif isinstance(e, dict):
+                eid = e.get("id", "?")
+                etitle = e.get("title", "?")
+                epts = e.get("points", "?")
+                estat = e.get("status", "?")
+                click.echo(f"  {eid}: {etitle} [{epts}pts] ({estat})")
+
+    standalone_stories = init_data.get("standalone_stories", [])
+    if standalone_stories:
+        click.echo(f"\nStandalone Stories ({len(standalone_stories)}):")
+        for s in standalone_stories:
+            sid = s.get("id", "?")
+            stitle = s.get("title", "?")
+            spts = s.get("points", "?")
+            sstat = s.get("status", "?")
+            click.echo(f"  {sid}: {stitle} [{spts}pts] ({sstat})")
+
+
+@initiative.command("cancel")
+@click.argument("name")
+@click.option("--jira", is_flag=True, help="Also cancel epics in Jira")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def initiative_cancel(name: str, jira: bool, dry_run: bool):
+    """Cancel an initiative and all its epics/stories.
+
+    Sets the initiative status to 'canceled' and cancels all epics and stories
+    within it.
+
+    \b
+    Arguments:
+      NAME  - Initiative slug (e.g., benchmark-reliability, technical-debt)
+
+    \b
+    Examples:
+      pf sprint initiative cancel technical-debt --dry-run
+      pf sprint initiative cancel technical-debt
+      pf sprint initiative cancel technical-debt --jira
+    """
+    import yaml
+
+    from pf.common.config import get_project_root
+
+    root = get_project_root()
+    sprint_dir = root / "sprint"
+    init_file = sprint_dir / f"initiative-{name}.yaml"
+
+    if not init_file.exists():
+        raise click.ClickException(f"Initiative not found: {name}\n  Expected: {init_file}")
+
+    with open(init_file) as f:
+        init_data = yaml.safe_load(f.read())
+
+    if not init_data:
+        raise click.ClickException(f"Empty initiative file: {init_file}")
+
+    init_name = init_data.get("name", name)
+    epics = init_data.get("epics", [])
+    standalone_stories = init_data.get("standalone_stories", [])
+
+    # Collect Jira keys for warning
+    jira_keys = []
+    epic_count = 0
+    story_count = 0
+
+    for e in epics:
+        if isinstance(e, str):
+            shard = _epic_shard_path(sprint_dir, e)
+            if shard.exists():
+                with open(shard) as sf:
+                    edata = yaml.safe_load(sf.read())
+                if edata:
+                    epic_count += 1
+                    if edata.get("jira"):
+                        jira_keys.append(edata["jira"])
+                    story_count += len(edata.get("stories", []))
+        elif isinstance(e, dict):
+            epic_count += 1
+            if e.get("jira"):
+                jira_keys.append(e["jira"])
+            story_count += len(e.get("stories", []))
+
+    story_count += len(standalone_stories)
+
+    click.echo(f"Initiative: {init_name}")
+    click.echo(f"Epics: {epic_count}")
+    click.echo(f"Stories: {story_count}")
+
+    if jira_keys and not jira:
+        click.echo(f"\nWarning: {len(jira_keys)} epic(s) have Jira keys -- pass --jira to also cancel in Jira")
+        for k in jira_keys:
+            click.echo(f"  {k}")
+
+    if dry_run:
+        click.echo(f"\n[DRY-RUN] Would cancel initiative '{init_name}' ({epic_count} epics, {story_count} stories)")
+        return
+
+    # Cancel all epics
+    for _i, e in enumerate(epics):
+        if isinstance(e, str):
+            shard = _epic_shard_path(sprint_dir, e)
+            if shard.exists():
+                with open(shard) as sf:
+                    edata = yaml.safe_load(sf.read())
+                if edata:
+                    edata["status"] = "canceled"
+                    for s in edata.get("stories", []):
+                        s["status"] = "canceled"
+                    with open(shard, "w") as sf:
+                        yaml.dump(edata, sf, default_flow_style=False, sort_keys=False)
+                    if jira and edata.get("jira"):
+                        _transition_jira(edata["jira"], "Cancelled")
+        elif isinstance(e, dict):
+            e["status"] = "canceled"
+            for s in e.get("stories", []):
+                s["status"] = "canceled"
+            if jira and e.get("jira"):
+                _transition_jira(e["jira"], "Cancelled")
+
+    # Cancel standalone stories
+    for s in standalone_stories:
+        s["status"] = "canceled"
+
+    # Update initiative status
+    init_data["status"] = "canceled"
+
+    with open(init_file, "w") as f:
+        yaml.dump(init_data, f, default_flow_style=False, sort_keys=False)
+
+    click.echo(f"\nCanceled initiative '{init_name}' ({epic_count} epics, {story_count} stories)")
+    if jira and jira_keys:
+        click.echo(f"Transitioned {len(jira_keys)} Jira epic(s) to Cancelled")
+
+
+# --- Check command (replaces check-story.sh) ---
+
+@sprint.command()
+@click.argument("id")
+def check(id: str):
+    """Check story/epic availability. Returns JSON.
+
+    \b
+    Arguments:
+      ID  - Story ID, epic ID, or 'next' for highest priority
+
+    \b
+    Returns JSON with type, details, and availability:
+      type: "story" | "epic" | "next" | "not_found"
+    """
+    import json
+
+    from pf.sprint.loader import (
+        find_epic,
+        load_sprint,
+    )
+    from pf.sprint.work import check_story, get_next_story
+
+    data = load_sprint()
+
+    if id == "next":
+        result = get_next_story()
+        if result.get("available"):
+            story = result["story"]
+            # Find parent epic
+            epic_id = _find_epic_for_story(data, story.get("id", ""))
+            out = {
+                "type": "next",
+                "story": {
+                    "id": story.get("id"),
+                    "title": story.get("title"),
+                    "points": story.get("points", 0),
+                    "priority": story.get("priority", "P2"),
+                    "workflow": story.get("workflow", "tdd"),
+                    "repos": story.get("repos", "pennyfarthing"),
+                    "epic_id": epic_id,
+                    "acceptance_criteria": story.get("acceptance_criteria", []),
+                },
+            }
+        else:
+            out = {"type": "next", "story": None, "message": "No available stories in backlog"}
+        click.echo(json.dumps(out, indent=2))
+        return
+
+    # Check if it's an epic
+    if data:
+        epic = find_epic(data, id)
+        if epic:
+            available_statuses = {"backlog", "ready", "planning"}
+            available = [
+                s for s in epic.get("stories", [])
+                if s.get("status") in available_statuses
+            ]
+            # Sort by priority
+            priority_order = {"P0": 0, "P1": 1, "P2": 2, "P3": 3}
+            available.sort(key=lambda s: priority_order.get(s.get("priority", "P2"), 2))
+
+            first = available[0] if available else None
+            out = {
+                "type": "epic",
+                "id": str(epic.get("id", id)),
+                "title": epic.get("title", "Unknown"),
+                "available_stories": len(available),
+            }
+            if first:
+                out["first_story"] = {
+                    "id": first.get("id"),
+                    "title": first.get("title"),
+                    "points": first.get("points", 0),
+                    "workflow": first.get("workflow", "tdd"),
+                    "repos": first.get("repos", "pennyfarthing"),
+                    "acceptance_criteria": first.get("acceptance_criteria", []),
+                }
+            else:
+                out["first_story"] = None
+                out["message"] = "No available stories in this epic"
+            click.echo(json.dumps(out, indent=2))
+            return
+
+    # Check if it's a story
+    result = check_story(id)
+    story = result.get("story")
+    if story:
+        epic_id = _find_epic_for_story(data, story.get("id", ""))
+        out = {
+            "type": "story",
+            "id": story.get("id", id),
+            "title": story.get("title", "Unknown"),
+            "points": story.get("points", 0),
+            "workflow": story.get("workflow", "tdd"),
+            "status": story.get("status", "backlog"),
+            "assigned_to": story.get("assigned_to", ""),
+            "epic_id": epic_id,
+            "repos": story.get("repos", "pennyfarthing"),
+            "available": result.get("available", False),
+            "acceptance_criteria": story.get("acceptance_criteria", []),
+        }
+        click.echo(json.dumps(out, indent=2))
+        return
+
+    # Not found
+    click.echo(json.dumps({
+        "type": "not_found",
+        "id": id,
+        "message": "Story or epic not found in current sprint",
+    }, indent=2))
+
+
+def _find_epic_for_story(data: dict | None, story_id: str) -> str:
+    """Find the parent epic ID for a story."""
+    if not data or "epics" not in data:
+        return ""
+    for epic in data["epics"]:
+        if not isinstance(epic, dict):
+            continue
+        for s in epic.get("stories", []):
+            if s.get("id") == story_id:
+                return str(epic.get("id", ""))
+    return ""
+
+
+# --- Info command (replaces sprint-info.sh) ---
+
+@sprint.command()
+def info():
+    """Output sprint info as JSON.
+
+    \b
+    Returns sprint header fields plus computed story point totals.
+    """
+    import json
+
+    from pf.sprint.loader import get_all_stories, get_sprint_info
+
+    sprint_data = get_sprint_info()
+    stories = get_all_stories()
+
+    remaining = sum(
+        s.get("points", 0) or 0
+        for s in stories
+        if s.get("status") in ("backlog", "planning", "ready", None)
+    )
+    in_progress = sum(
+        s.get("points", 0) or 0
+        for s in stories
+        if s.get("status") == "in_progress"
+    )
+
+    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) ---
+
+@sprint.command()
+@click.option("--json", "output_json", is_flag=True, help="Output in JSON format")
+def metrics(output_json: bool):
+    """Display sprint metrics and progress.
+
+    Shows points, stories, timeline, and velocity tracking.
+    """
+    import json
+    from datetime import date, datetime
+
+    from pf.sprint.loader import get_all_stories, get_sprint_info
+
+    sprint_data = get_sprint_info()
+    stories = get_all_stories()
+
+    if not sprint_data:
+        click.echo("No sprint data available")
+        return
+
+    sprint_name = sprint_data.get("name", "Unknown")
+    goal = sprint_data.get("goal", "")
+    start_date_str = sprint_data.get("start_date", "")
+    end_date_str = sprint_data.get("end_date", "")
+
+    # Count stories/points by status
+    done_stories = [s for s in stories if s.get("status") in ("done", "completed")]
+    wip_stories = [s for s in stories if s.get("status") == "in_progress"]
+    backlog_stories = [s for s in stories if s.get("status") in ("backlog", "planning", "ready", None)]
+
+    done_pts = sum(s.get("points", 0) or 0 for s in done_stories)
+    wip_pts = sum(s.get("points", 0) or 0 for s in wip_stories)
+    backlog_pts = sum(s.get("points", 0) or 0 for s in backlog_stories)
+    total_pts = done_pts + wip_pts + backlog_pts
+
+    # Date calculations
+    today = date.today()
+    try:
+        start_date = datetime.strptime(str(start_date_str), "%Y-%m-%d").date()
+        end_date = datetime.strptime(str(end_date_str), "%Y-%m-%d").date()
+    except (ValueError, TypeError):
+        start_date = today
+        end_date = today
+
+    total_days = (end_date - start_date).days or 1
+    days_elapsed = max(0, (today - start_date).days)
+    days_remaining = max(0, (end_date - today).days)
+
+    pct_complete = (done_pts * 100 // total_pts) if total_pts > 0 else 0
+    pct_time = (days_elapsed * 100 // total_days) if total_days > 0 else 0
+
+    velocity_target = sprint_data.get("velocity_target", total_pts)
+    expected_pts = (velocity_target * days_elapsed // total_days) if total_days > 0 else 0
+
+    if output_json:
+        click.echo(json.dumps({
+            "sprint": sprint_name,
+            "dates": {
+                "start": str(start_date_str),
+                "end": str(end_date_str),
+                "today": str(today),
+            },
+            "points": {
+                "total": total_pts,
+                "completed": done_pts,
+                "in_progress": wip_pts,
+                "backlog": backlog_pts,
+                "velocity_target": velocity_target,
+            },
+            "stories": {
+                "total": len(stories),
+                "done": len(done_stories),
+                "in_progress": len(wip_stories),
+                "backlog": len(backlog_stories),
+            },
+            "progress": {
+                "percent_complete": pct_complete,
+                "percent_time": pct_time,
+                "days_elapsed": days_elapsed,
+                "days_remaining": days_remaining,
+                "total_days": total_days,
+            },
+            "velocity": {
+                "expected_points": expected_pts,
+                "actual_points": done_pts,
+                "on_track": done_pts >= expected_pts,
+            },
+        }, indent=2))
+        return
+
+    # Human-readable output
+    click.echo("")
+    click.echo(f"  Sprint: {sprint_name}")
+    click.echo(f"  Goal: {goal}")
+    click.echo("")
+    click.echo(f"  Timeline: {start_date_str} to {end_date_str} (Day {days_elapsed}/{total_days}, {days_remaining} remaining)")
+    click.echo("")
+    click.echo(f"  Points:  {done_pts} done / {wip_pts} WIP / {backlog_pts} backlog = {total_pts} total ({pct_complete}%)")
+    click.echo(f"  Stories: {len(done_stories)} done / {len(wip_stories)} WIP / {len(backlog_stories)} backlog = {len(stories)} total")
+    click.echo("")
+    click.echo(f"  Velocity: {done_pts}/{expected_pts} expected ({velocity_target} target)")
+    if done_pts >= expected_pts:
+        click.echo("  Status: On track")
+    else:
+        click.echo("  Status: Behind schedule")
+
+
+# --- Story field command (replaces get-story-field.sh) ---
+
+@story.command("field")
+@click.argument("story_id")
+@click.argument("field_name")
+def story_field(story_id: str, field_name: str):
+    """Get a field value from a story.
+
+    \b
+    Arguments:
+      STORY_ID    - Story ID (e.g., 79-1 or MSSCI-12345)
+      FIELD_NAME  - Field to extract (e.g., workflow, status, points)
+
+    Returns the field value or "null" if not found.
+    """
+    from pf.sprint.loader import get_story_by_id, get_story_field, load_sprint
+
+    # Default values for common fields
+    defaults = {
+        "workflow": "tdd",
+        "status": "backlog",
+        "repos": "pennyfarthing",
+    }
+
+    # Try get_story_field first (works with epic-story format like "79-1")
+    data = load_sprint()
+    if data:
+        value = get_story_field(data, story_id, field_name)
+        if value is not None:
+            click.echo(str(value))
+            return
+
+    # Fallback: try direct story lookup (works with Jira keys)
+    story = get_story_by_id(story_id)
+    if story:
+        value = story.get(field_name)
+        if value is not None:
+            click.echo(str(value))
+            return
+
+    # Return default or null
+    click.echo(defaults.get(field_name, "null"))
+
+
+# --- Epic field command (replaces get-epic-field.sh) ---
+
+@epic.command("field")
+@click.argument("epic_id")
+@click.argument("field_name")
+def epic_field(epic_id: str, field_name: str):
+    """Get a field value from an epic.
+
+    \b
+    Arguments:
+      EPIC_ID     - Epic ID (e.g., epic-79 or 79)
+      FIELD_NAME  - Field to extract (e.g., jira, title, status)
+
+    Returns the field value or "null" if not found.
+    """
+    from pf.sprint.loader import find_epic, load_sprint
+
+    data = load_sprint()
+    if not data:
+        click.echo("null")
+        return
+
+    epic = find_epic(data, epic_id)
+    if not epic:
+        click.echo("null")
+        return
+
+    value = epic.get(field_name)
+    if value is not None:
+        click.echo(str(value).rstrip())
+    else:
+        click.echo("null")
+
+
+# --- Future command (replaces list-future.sh) ---
+
+@sprint.command()
+@click.argument("epic_id", required=False)
+def future(epic_id: str | None):
+    """Show future work initiatives and epics.
+
+    \b
+    Arguments:
+      EPIC_ID  - Optional epic ID to show detailed stories (e.g., epic-55)
+
+    \b
+    Examples:
+      pf sprint future                  # Show all initiatives
+      pf sprint future epic-55          # Show stories for specific epic
+    """
+    import yaml
+
+    from pf.common.config import get_project_root
+
+    root = get_project_root()
+    sprint_dir = root / "sprint"
+
+    init_files = sorted(sprint_dir.glob("initiative-*.yaml"))
+    if not init_files:
+        click.echo("No future initiatives found.")
+        return
+
+    # If specific epic requested, show detailed view
+    if epic_id:
+        _show_future_epic_detail(epic_id, init_files, sprint_dir)
+        return
+
+    # Default: show initiative summary
+    click.echo("# Future Work - Available for Promotion")
+    click.echo("")
+
+    total_epics = 0
+    total_points = 0
+
+    for init_file in init_files:
+        with open(init_file) as f:
+            init_data = yaml.safe_load(f.read())
+        if not init_data:
+            continue
+
+        init_name = init_data.get("name", init_file.stem)
+        init_status = init_data.get("status", "planning")
+        blocked_by = init_data.get("blocked_by")
+        init_points = init_data.get("total_points", 0)
+
+        if init_status == "ready":
+            status_tag = "[READY]"
+        elif blocked_by:
+            status_tag = "[BLOCKED]"
+        else:
+            status_tag = f"[{init_status}]"
+
+        click.echo(f"## {init_name} {status_tag}")
+        click.echo(f"**Total:** {init_points} points")
+        if blocked_by:
+            click.echo(f"**Blocked:** {blocked_by}")
+        click.echo("")
+
+        click.echo("| Epic | Title | Pts | Pri | Status |")
+        click.echo("|------|-------|-----|-----|--------|")
+
+        epics = init_data.get("epics", [])
+        for e in epics:
+            edata = _resolve_epic_ref(e, sprint_dir)
+            if not edata:
+                continue
+            eid = edata.get("id", "?")
+            etitle = edata.get("title", "?")
+            if len(etitle) > 40:
+                etitle = etitle[:37] + "..."
+            epts = edata.get("points", "?")
+            epri = edata.get("priority", "P2")
+            estat = edata.get("status", "planning")
+            click.echo(f"| {eid} | {etitle} | {epts} | {epri} | {estat} |")
+            total_epics += 1
+            total_points += edata.get("points", 0) or 0
+
+        click.echo("")
+
+    click.echo("---")
+    click.echo(f"**Summary:** {total_epics} epics, {total_points} points total")
+    click.echo("")
+    click.echo("To see epic details: `pf sprint future epic-55`")
+    click.echo("To promote an epic: `pf sprint epic promote epic-55`")
+
+
+def _resolve_epic_ref(ref, sprint_dir) -> dict | None:
+    """Resolve an epic reference (string ref or inline dict) to a dict."""
+    import yaml
+
+    if isinstance(ref, dict):
+        return ref
+    if isinstance(ref, str):
+        shard = _epic_shard_path(sprint_dir, ref)
+        if shard.exists():
+            with open(shard) as f:
+                return yaml.safe_load(f.read())
+    return None
+
+
+def _show_future_epic_detail(epic_id: str, init_files, sprint_dir):
+    """Show detailed view of a specific future epic."""
+    import yaml
+
+    for init_file in init_files:
+        with open(init_file) as f:
+            init_data = yaml.safe_load(f.read())
+        if not init_data:
+            continue
+
+        for e in init_data.get("epics", []):
+            edata = _resolve_epic_ref(e, sprint_dir)
+            if not edata:
+                continue
+            eid = str(edata.get("id", ""))
+            if epic_id not in (eid, eid.replace("epic-", ""), f"epic-{epic_id}"):
+                continue
+
+            click.echo(f"# Epic Details: {eid}")
+            click.echo("")
+            click.echo(f"**Title:** {edata.get('title', '?')}")
+            click.echo(f"**Points:** {edata.get('points', '?')} | **Priority:** {edata.get('priority', 'P2')} | **Status:** {edata.get('status', 'planning')}")
+            click.echo("")
+            desc = edata.get("description", "No description")
+            if desc:
+                click.echo("**Description:**")
+                for line in str(desc).strip().split("\n")[:5]:
+                    click.echo(line)
+                click.echo("")
+
+            stories = edata.get("stories", [])
+            if stories:
+                click.echo("## Stories")
+                click.echo("")
+                click.echo("| ID | Title | Pts | Pri | Status |")
+                click.echo("|----|-------|-----|-----|--------|")
+                for s in stories:
+                    stitle = s.get("title", "?")
+                    if len(stitle) > 45:
+                        stitle = stitle[:42] + "..."
+                    click.echo(f"| {s.get('id', '?')} | {stitle} | {s.get('points', '?')} | {s.get('priority', 'P1')} | {s.get('status', 'planning')} |")
+                click.echo("")
+
+            click.echo("---")
+            click.echo(f"To promote this epic: `pf sprint epic promote {eid}`")
+            return
+
+    raise click.ClickException(f"Epic {epic_id} not found in future initiatives")
+
+
+# --- New sprint command (replaces new-sprint.sh) ---
+
+@sprint.command("new")
+@click.argument("sprint_yyww")
+@click.argument("jira_id", type=int)
+@click.argument("start_date")
+@click.argument("end_date")
+@click.argument("goal")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def new_sprint(sprint_yyww: str, jira_id: int, start_date: str, end_date: str, goal: str, dry_run: bool):
+    """Initialize a new sprint.
+
+    \b
+    Arguments:
+      SPRINT_YYWW  Sprint identifier in YYWW format (e.g., 2607)
+      JIRA_ID      Jira sprint ID number (e.g., 278)
+      START_DATE   Sprint start date YYYY-MM-DD
+      END_DATE     Sprint end date YYYY-MM-DD
+      GOAL         Sprint goal (quoted string)
+
+    \b
+    Examples:
+      pf sprint new 2607 278 2026-02-16 2026-03-01 "Performance and polish"
+    """
+    from pf.common.config import get_project_root
+
+    root = get_project_root()
+    sprint_file = root / "sprint" / "current-sprint.yaml"
+    archive_file = root / "sprint" / "archive" / f"sprint-{sprint_yyww}-completed.yaml"
+
+    # Warn if current sprint is active
+    if sprint_file.exists():
+        import yaml
+
+        with open(sprint_file) as f:
+            existing = yaml.safe_load(f.read())
+        if existing and existing.get("sprint", {}).get("status") == "active":
+            click.echo("Warning: Current sprint is still active!")
+            click.echo("Current sprint file will be overwritten.")
+            if not click.confirm("Continue?"):
+                click.echo("Aborted.")
+                return
+
+    if dry_run:
+        click.echo(f"[DRY-RUN] Would initialize sprint TO Sprint {sprint_yyww}")
+        click.echo(f"  Jira ID: {jira_id}")
+        click.echo(f"  Dates: {start_date} to {end_date}")
+        click.echo(f"  Goal: {goal}")
+        return
+
+    # Create sprint file using write_sprint for consistency
+    from pf.sprint.yaml_io import write_sprint
+
+    sprint_data = {
+        "sprint": {
+            "name": f"TO Sprint {sprint_yyww}",
+            "jira_sprint_id": jira_id,
+            "jira_sprint_name": f"TO Sprint {sprint_yyww}",
+            "goal": goal,
+            "start_date": start_date,
+            "end_date": end_date,
+            "status": "active",
+        },
+        "epics": [],
+    }
+    write_sprint(sprint_file, sprint_data)
+    click.echo(f"Created {sprint_file}")
+
+    # Create archive file
+    from datetime import date
+
+    archive_content = f"""# Sprint TO Sprint {sprint_yyww} - Completed Stories
+# Jira Sprint ID: {jira_id}
+# Archived: {date.today()}
+
+sprint:
+  name: "TO Sprint {sprint_yyww}"
+  jira_sprint_id: {jira_id}
+  jira_sprint_name: "TO Sprint {sprint_yyww}"
+  goal: {goal}
+
+completed:
+  # Completed stories will be appended here by pf sprint archive
+"""
+    archive_file.parent.mkdir(parents=True, exist_ok=True)
+    archive_file.write_text(archive_content)
+    click.echo(f"Created {archive_file}")
+
+    click.echo("")
+    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}")
+    click.echo(f"  Goal: {goal}")
+    click.echo("")
+    click.echo("Next steps:")
+    click.echo("  1. Add epics: pf sprint epic promote <epic-id>")
+    click.echo("  2. Check status: pf sprint status")
+
+
+# --- Standalone command ---
+
+@sprint.command()
+@click.argument("title", required=False)
+@click.argument("points", required=False, type=int)
+def standalone(title: str | None, points: int | None):
+    """Wrap current changes into a standalone Jira story, branch, PR, and merge.
+
+    This is an agent-executed workflow. Use /standalone to run it interactively.
+    """
+    click.echo("The standalone command is an agent-executed workflow.")
+    click.echo("Use /standalone to run it interactively with full agent support.")
+
+
+# --- Backwards compatibility aliases (hidden) ---
+
+# Hidden alias: sprint story-add -> sprint story add
+sprint.add_command(story_add_command, "story-add")
+sprint.commands["story-add"].hidden = True
+
+# Hidden alias: sprint story-update -> sprint story update
+sprint.add_command(story_update_command, "story-update")
+sprint.commands["story-update"].hidden = True
+
+# Hidden alias: sprint archive-epic -> sprint epic archive
+@sprint.command("archive-epic", hidden=True)
+@click.argument("epic_id", required=False)
+@click.option("--dry-run", is_flag=True)
+@click.option("--jira", is_flag=True)
+def archive_epic_compat(epic_id, dry_run, jira):
+    """(Deprecated) Use 'sprint epic archive' instead."""
+    ctx = click.get_current_context()
+    ctx.invoke(epic_archive, epic_id=epic_id, dry_run=dry_run, jira=jira)
+
+# Hidden alias: sprint import-epic -> sprint epic import
+@sprint.command("import-epic", hidden=True)
+@click.argument("epics_file")
+@click.argument("initiative_name", required=False)
+@click.option("--marker", default="imported")
+@click.option("--dry-run", is_flag=True)
+def import_epic_compat(epics_file, initiative_name, marker, dry_run):
+    """(Deprecated) Use 'sprint epic import' instead."""
+    ctx = click.get_current_context()
+    ctx.invoke(epic_import, epics_file=epics_file, initiative_name=initiative_name, marker=marker, dry_run=dry_run)
+
+# Hidden alias: sprint remove-epic -> sprint epic remove
+@sprint.command("remove-epic", hidden=True)
+@click.argument("epic_id")
+@click.option("--dry-run", is_flag=True)
+def remove_epic_compat(epic_id, dry_run):
+    """(Deprecated) Use 'sprint epic remove' instead."""
+    ctx = click.get_current_context()
+    ctx.invoke(epic_remove, epic_id=epic_id, dry_run=dry_run)
+
+# Hidden alias: sprint epic-add -> sprint epic add
+sprint.add_command(epic_add_command, "epic-add")
+sprint.commands["epic-add"].hidden = True
+
+
+# Register validate command from validate_cmd module
+from pf.sprint.validate_cmd import validate_command  # noqa: E402
+
+sprint.add_command(validate_command)
+
+
+# For backwards compatibility when running as module
+def main(args: list[str] | None = None) -> int:
+    """Entry point for backwards compatibility."""
+    try:
+        sprint(args)
+        return 0
+    except SystemExit as e:
+        return e.code if isinstance(e.code, int) else 0
+
+
+if __name__ == "__main__":
+    sprint()