@pennyfarthing/core 9.2.0 → 9.3.0

package/pennyfarthing_scripts/migration/cli.py

@@ -1,304 +0,0 @@
-"""
-Migration CLI - Click-based CLI for XML schema migration tools.
-
-Usage:
-    pf migration [COMMAND] [ARGS]...
-    python -m pennyfarthing_scripts.migration [COMMAND] [ARGS]...
-
-Commands:
-    session   Migrate session files to XML format
-    skill     Audit skill files for required tags
-    step      Audit workflow step files
-    validate  Validate files against XML schemas
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-import click
-
-from pennyfarthing_scripts.common.output import error, info, success, warn
-
-
-def _find_project_root() -> Path:
-    """Find project root by looking for .pennyfarthing directory."""
-    cwd = Path.cwd()
-
-    # Walk up looking for .pennyfarthing
-    for parent in [cwd, *cwd.parents]:
-        if (parent / ".pennyfarthing").exists():
-            return parent
-
-    # Fall back to cwd
-    return cwd
-
-
-@click.group()
-def migration():
-    """XML schema migration tools.
-
-    \b
-    Commands:
-      session   - Migrate session files to XML format
-      skill     - Audit skill files for required tags
-      step      - Audit workflow step files
-      validate  - Validate files against schemas
-    """
-    pass
-
-
-@migration.command()
-@click.argument("file", required=False, type=click.Path(exists=True))
-@click.option("--dry-run", is_flag=True, help="Show what would be done without writing")
-@click.option("--all", "convert_all", is_flag=True, help="Convert all session files")
-def session(file: str | None, dry_run: bool, convert_all: bool):
-    """Migrate session files to XML format.
-
-    \b
-    Arguments:
-      FILE  - Specific session file to convert (optional)
-
-    \b
-    Examples:
-      pf migration session --dry-run .session/archive/MSSCI-12142-session.md
-      pf migration session --all --dry-run
-      pf migration session --all
-    """
-    from pennyfarthing_scripts.migration.session import (
-        convert_session_file,
-        find_session_files,
-    )
-
-    root = _find_project_root()
-
-    if file:
-        file_path = Path(file)
-        result = convert_session_file(file_path, dry_run=dry_run)
-
-        if result.get("skipped"):
-            info(f"{file_path.name}: Already in XML format")
-        elif result.get("success"):
-            if dry_run:
-                click.echo(f"\n=== Would convert {file_path.name} to: ===\n")
-                click.echo(result.get("content"))
-                click.echo("\n=== End ===")
-            else:
-                success(f"Converted: {file_path.name}")
-        else:
-            error(result.get("message", "Conversion failed"))
-            raise click.Abort()
-
-    elif convert_all:
-        files = find_session_files(root)
-        if not files:
-            warn("No session files found")
-            return
-
-        info(f"Found {len(files)} session files")
-        converted = 0
-        skipped = 0
-
-        for file_path in files:
-            result = convert_session_file(file_path, dry_run=dry_run)
-
-            if result.get("skipped"):
-                skipped += 1
-            elif result.get("success"):
-                converted += 1
-                if dry_run:
-                    info(f"Would convert: {file_path.name}")
-                else:
-                    success(f"Converted: {file_path.name}")
-            else:
-                error(f"Failed: {file_path.name} - {result.get('message')}")
-
-        click.echo("")
-        info(f"Summary: {converted} converted, {skipped} already XML")
-
-    else:
-        # Show available files
-        files = find_session_files(root)
-        if not files:
-            warn("No session files found")
-            return
-
-        info(f"Session files found: {len(files)}")
-        for f in files[:10]:
-            click.echo(f"  {f.relative_to(root)}")
-        if len(files) > 10:
-            click.echo(f"  ... and {len(files) - 10} more")
-        click.echo("")
-        info("Use --all to convert all, or specify a file path")
-
-
-@migration.command()
-@click.argument("skill_name", required=False)
-@click.option("--report", is_flag=True, help="Generate detailed report")
-def skill(skill_name: str | None, report: bool):
-    """Audit skill files for required XML tags.
-
-    \b
-    Arguments:
-      SKILL_NAME  - Specific skill to audit (optional)
-
-    \b
-    Examples:
-      pf migration skill --report
-      pf migration skill sprint
-    """
-    from pennyfarthing_scripts.migration.skill import audit_skills
-
-    root = _find_project_root()
-    results = audit_skills(root, skill_name=skill_name)
-
-    if results["summary"].get("error"):
-        error(results["summary"]["error"])
-        raise click.Abort()
-
-    # Print results
-    for result in results["results"]:
-        if result.status == "OK":
-            success(f"{result.skill_name}: All tags present")
-        elif result.status == "PARTIAL":
-            warn(f"{result.skill_name}: Missing recommended: {', '.join(result.missing_recommended)}")
-        else:
-            error(f"{result.skill_name}: Missing required: {', '.join(result.missing_required)}")
-
-        if report and (result.missing_required or result.missing_recommended):
-            click.echo(f"    Present: {', '.join(result.present_tags)}")
-
-    # Print summary
-    summary = results["summary"]
-    click.echo("")
-    info("=== Summary ===")
-    click.echo(f"  Total:       {summary['total']}")
-    click.echo(f"  Valid:       {summary['valid']}")
-    click.echo(f"  Partial:     {summary['partial']}")
-    click.echo(f"  Needs work:  {summary['needs_update']}")
-
-    if summary["needs_update"] > 0:
-        click.echo("")
-        info("Skills needing updates:")
-        for result in results["results"]:
-            if not result.is_valid:
-                click.echo(f"  - {result.skill_name}")
-
-
-@migration.command()
-@click.argument("workflow_name", required=False)
-@click.option("--report", is_flag=True, help="Generate detailed report")
-def step(workflow_name: str | None, report: bool):
-    """Audit workflow step files for required XML tags.
-
-    \b
-    Arguments:
-      WORKFLOW_NAME  - Specific workflow to audit (optional)
-
-    \b
-    Examples:
-      pf migration step --report
-      pf migration step architecture
-    """
-    from pennyfarthing_scripts.migration.step import audit_workflow_steps
-
-    root = _find_project_root()
-    results = audit_workflow_steps(root, workflow_name=workflow_name)
-
-    # Print results by workflow
-    for workflow in results["workflows"]:
-        info(f"Workflow: {workflow.workflow_name} ({workflow.total_steps} steps)")
-
-        for result in workflow.step_results:
-            if result.status == "OK":
-                if report:
-                    success(f"  {result.step_name}: OK")
-            elif result.status == "PARTIAL":
-                warn(f"  {result.step_name}: Missing recommended: {', '.join(result.missing_recommended)}")
-            else:
-                error(f"  {result.step_name}: Missing required: {', '.join(result.missing_required)}")
-
-    # Print summary
-    summary = results["summary"]
-    click.echo("")
-    info("=== Summary ===")
-    click.echo(f"  Workflows:   {summary['total_workflows']}")
-    click.echo(f"  Step files:  {summary['total_files']}")
-    click.echo(f"  Valid:       {summary['valid']}")
-    click.echo(f"  Needs work:  {summary['needs_update']}")
-
-    if summary["needs_update"] > 0:
-        click.echo("")
-        info("Workflows with missing required tags:")
-        for workflow in results["workflows"]:
-            if workflow.needs_update > 0:
-                click.echo(f"  - {workflow.workflow_name} ({workflow.needs_update} files)")
-
-
-@migration.command()
-@click.option(
-    "--type",
-    "file_type",
-    type=click.Choice(["session", "skill", "step", "all"]),
-    default="all",
-    help="Type of files to validate",
-)
-@click.option("--strict", is_flag=True, help="Treat warnings as errors")
-def validate(file_type: str, strict: bool):
-    """Validate files against XML schemas.
-
-    \b
-    Examples:
-      pf migration validate
-      pf migration validate --type skill
-      pf migration validate --strict
-    """
-    from pennyfarthing_scripts.migration.validate import validate_all
-
-    root = _find_project_root()
-    summary = validate_all(root, file_type=file_type, strict=strict)
-
-    # Print results
-    for result in summary.results:
-        rel_path = result.file_path.relative_to(root) if root in result.file_path.parents else result.file_path
-        if result.status == "PASS":
-            success(f"{rel_path}")
-        elif result.status == "WARN":
-            warn(f"{rel_path}")
-            for w in result.warnings:
-                click.echo(f"    - {w}")
-        else:
-            error(f"{rel_path}")
-            for e in result.errors:
-                click.echo(f"    - {e}")
-
-    # Print summary
-    click.echo("")
-    info("=== Summary ===")
-    click.echo(f"  Passed:   {summary.passed}")
-    click.echo(f"  Warnings: {summary.warnings}")
-    click.echo(f"  Errors:   {summary.errors}")
-
-    if not summary.success:
-        raise click.Abort()
-
-    if strict and summary.warnings > 0:
-        error("Warnings treated as errors in strict mode")
-        raise click.Abort()
-
-
-# Alias for backwards compatibility
-cli = migration
-
-
-def main(args: list[str] | None = None) -> int:
-    """Entry point."""
-    try:
-        migration(args)
-        return 0
-    except SystemExit as e:
-        return e.code if isinstance(e.code, int) else 0
-
-
-if __name__ == "__main__":
-    migration()

package/pennyfarthing_scripts/migration/session.py

@@ -1,384 +0,0 @@
-"""
-Session file migration tools.
-
-Converts session files from markdown format to XML format
-per guides/session-schema.md.
-"""
-
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass, field
-from datetime import date
-from pathlib import Path
-from typing import Literal
-
-
-@dataclass
-class AcceptanceCriterion:
-    """An acceptance criterion."""
-
-    id: int
-    description: str
-    status: Literal["pending", "in-progress", "done", "blocked"] = "pending"
-
-
-@dataclass
-class WorkLogEntry:
-    """A work log entry."""
-
-    agent: str
-    date: str
-    content: str
-    phase: str | None = None
-
-
-@dataclass
-class ReviewAssessment:
-    """A reviewer assessment."""
-
-    agent: str = "reviewer"
-    verdict: Literal["approved", "rejected", "needs-work"] = "approved"
-    content: str = ""
-
-
-@dataclass
-class SessionFile:
-    """Parsed session file data."""
-
-    story_id: str
-    workflow: str = "tdd"
-    jira: str = ""
-    epic: str = ""
-    points: int = 0
-    started: str = ""
-    phase: str = "setup"
-    next_agent: str = "sm"
-    handoff_ready: bool = False
-    acceptance_criteria: list[AcceptanceCriterion] = field(default_factory=list)
-    context: str = ""
-    work_log: list[WorkLogEntry] = field(default_factory=list)
-    assessment: ReviewAssessment | None = None
-
-    def to_xml(self) -> str:
-        """Convert to XML format."""
-        lines = [f'<session story="{self.story_id}" workflow="{self.workflow}">']
-
-        # Meta section
-        lines.append("  <meta>")
-        lines.append(f"    <jira>{self.jira or self.story_id}</jira>")
-        if self.epic:
-            lines.append(f"    <epic>{self.epic}</epic>")
-        if self.points:
-            lines.append(f"    <points>{self.points}</points>")
-        lines.append(f"    <started>{self.started or date.today().isoformat()}</started>")
-        lines.append("  </meta>")
-        lines.append("")
-
-        # Status
-        handoff = "true" if self.handoff_ready else "false"
-        lines.append(
-            f'  <status phase="{self.phase}" next-agent="{self.next_agent}" '
-            f'handoff-ready="{handoff}"/>'
-        )
-        lines.append("")
-
-        # Acceptance criteria
-        lines.append("  <acceptance-criteria>")
-        for ac in self.acceptance_criteria:
-            lines.append(f'    <ac id="{ac.id}" status="{ac.status}">{ac.description}</ac>')
-        lines.append("  </acceptance-criteria>")
-        lines.append("")
-
-        # Context
-        lines.append("  <context>")
-        if self.context:
-            for line in self.context.strip().split("\n"):
-                lines.append(f"    {line}")
-        else:
-            lines.append(f"    See: .session/context-story-{self.story_id}.md")
-        lines.append("  </context>")
-        lines.append("")
-
-        # Work log
-        lines.append("  <work-log>")
-        for entry in self.work_log:
-            phase_attr = f' phase="{entry.phase}"' if entry.phase else ""
-            lines.append(f'    <entry agent="{entry.agent}" date="{entry.date}"{phase_attr}>')
-            for line in entry.content.strip().split("\n"):
-                lines.append(f"      {line}")
-            lines.append("    </entry>")
-
-        # Assessment (if present)
-        if self.assessment:
-            lines.append(
-                f'    <assessment agent="{self.assessment.agent}" '
-                f'verdict="{self.assessment.verdict}">'
-            )
-            for line in self.assessment.content.strip().split("\n"):
-                lines.append(f"      {line}")
-            lines.append("    </assessment>")
-
-        lines.append("  </work-log>")
-        lines.append("</session>")
-
-        return "\n".join(lines)
-
-
-def _extract_field(content: str, label: str) -> str:
-    """Extract a field value from markdown **Label:** value format."""
-    pattern = rf"\*\*{re.escape(label)}:\*\*\s*(.+?)(?:\n|$)"
-    match = re.search(pattern, content)
-    if match:
-        return match.group(1).strip()
-    return ""
-
-
-def _normalize_phase(phase: str) -> str:
-    """Normalize phase value."""
-    phase = phase.lower()
-    # Remove suffixes
-    phase = re.sub(r"-complete$", "", phase)
-    phase = re.sub(r"^dev-", "", phase)
-    phase = re.sub(r"^review-", "", phase)
-    # Map common values
-    if phase in ("approved", "finished"):
-        phase = "finish"
-    elif phase in ("implementing", "implementation"):
-        phase = "green"
-    return phase
-
-
-def _normalize_agent(agent: str) -> str:
-    """Normalize agent name."""
-    agent = agent.lower()
-    # Remove parenthetical persona names
-    agent = re.sub(r"\s*\([^)]+\)", "", agent)
-    # Take first word only
-    agent = agent.split()[0] if agent else "sm"
-    return agent
-
-
-def _parse_acceptance_criteria(content: str) -> list[AcceptanceCriterion]:
-    """Parse acceptance criteria from markdown checkboxes."""
-    criteria = []
-
-    # Find AC section
-    ac_section = re.search(
-        r"## Acceptance Criteria\n(.+?)(?=\n##|\Z)", content, re.DOTALL
-    )
-    if not ac_section:
-        return criteria
-
-    section_text = ac_section.group(1)
-
-    # Pattern 1: - [x] AC1: Description
-    pattern1 = re.compile(r"^\s*-\s*\[([xX\s])\]\s*AC(\d+):?\s*(.+)$", re.MULTILINE)
-    for match in pattern1.finditer(section_text):
-        checked = match.group(1).lower() == "x"
-        ac_id = int(match.group(2))
-        desc = match.group(3).strip()
-        status = "done" if checked else "pending"
-        criteria.append(AcceptanceCriterion(id=ac_id, description=desc, status=status))
-
-    # If no ACs found, try pattern 2: - [x] Description (auto-number)
-    if not criteria:
-        pattern2 = re.compile(r"^\s*-\s*\[([xX\s])\]\s*(.+)$", re.MULTILINE)
-        for i, match in enumerate(pattern2.finditer(section_text), start=1):
-            checked = match.group(1).lower() == "x"
-            desc = match.group(2).strip()
-            status = "done" if checked else "pending"
-            criteria.append(AcceptanceCriterion(id=i, description=desc, status=status))
-
-    return criteria
-
-
-def _parse_work_log(content: str) -> tuple[list[WorkLogEntry], ReviewAssessment | None]:
-    """Parse work log entries from markdown."""
-    entries = []
-    assessment = None
-
-    # Find work log section
-    log_section = re.search(r"## Work Log\n(.+?)(?=\n## [^W]|\Z)", content, re.DOTALL)
-    if not log_section:
-        return entries, assessment
-
-    section_text = log_section.group(1)
-
-    # Split by agent headers (### Agent Name (Date) or ### Agent Action (Date))
-    header_pattern = re.compile(
-        r"^###\s+(\w+)(?:\s+\w+)?\s+\((\d{4}-\d{2}-\d{2})\)", re.MULTILINE
-    )
-
-    matches = list(header_pattern.finditer(section_text))
-
-    for i, match in enumerate(matches):
-        agent = match.group(1).lower()
-        entry_date = match.group(2)
-
-        # Get content until next header or end
-        start = match.end()
-        end = matches[i + 1].start() if i + 1 < len(matches) else len(section_text)
-        entry_content = section_text[start:end].strip()
-
-        # Determine phase from header context
-        phase = None
-        header_text = match.group(0).lower()
-        if "red" in header_text:
-            phase = "red"
-        elif "green" in header_text or "implementation" in header_text:
-            phase = "green"
-        elif "refactor" in header_text:
-            phase = "refactor"
-
-        # Check if this is a reviewer assessment
-        if agent == "reviewer" and "verdict" in entry_content.lower():
-            verdict = "approved"
-            if "rejected" in entry_content.lower():
-                verdict = "rejected"
-            elif "needs-work" in entry_content.lower() or "needs work" in entry_content.lower():
-                verdict = "needs-work"
-            assessment = ReviewAssessment(
-                agent="reviewer", verdict=verdict, content=entry_content
-            )
-        else:
-            entries.append(
-                WorkLogEntry(
-                    agent=agent, date=entry_date, content=entry_content, phase=phase
-                )
-            )
-
-    return entries, assessment
-
-
-def _extract_context(content: str) -> str:
-    """Extract technical context section."""
-    # Find context section
-    context_section = re.search(
-        r"## Technical Context\n(.+?)(?=\n##|\Z)", content, re.DOTALL
-    )
-    if context_section:
-        return context_section.group(1).strip()
-    return ""
-
-
-def parse_markdown_session(content: str, filename: str) -> SessionFile:
-    """Parse a markdown session file into structured data.
-
-    Args:
-        content: File content
-        filename: Filename (used to extract story ID)
-
-    Returns:
-        SessionFile with parsed data
-    """
-    # Extract story ID from filename
-    story_id = filename.replace("-session.md", "")
-
-    # Extract fields
-    jira = _extract_field(content, "Jira")
-    epic = _extract_field(content, "Epic")
-    # Clean epic - take just the ID, not description
-    if epic:
-        epic = epic.split()[0] if " " in epic else epic
-
-    points_str = _extract_field(content, "Points")
-    points = int(points_str) if points_str.isdigit() else 0
-
-    workflow = _extract_field(content, "Workflow").lower() or "tdd"
-    started = _extract_field(content, "Started")
-
-    # Status fields (may appear twice - get last occurrence)
-    all_phases = re.findall(r"\*\*Current Phase:\*\*\s*(.+?)(?:\n|$)", content)
-    phase = _normalize_phase(all_phases[-1]) if all_phases else "setup"
-
-    all_next = re.findall(r"\*\*Next Agent:\*\*\s*(.+?)(?:\n|$)", content)
-    next_agent = _normalize_agent(all_next[-1]) if all_next else "sm"
-
-    all_handoff = re.findall(r"\*\*Handoff Ready:\*\*\s*(.+?)(?:\n|$)", content)
-    handoff_ready = bool(all_handoff and all_handoff[-1].lower().startswith("y"))
-
-    # Parse sections
-    acceptance_criteria = _parse_acceptance_criteria(content)
-    context = _extract_context(content)
-    work_log, assessment = _parse_work_log(content)
-
-    return SessionFile(
-        story_id=story_id,
-        workflow=workflow,
-        jira=jira,
-        epic=epic,
-        points=points,
-        started=started,
-        phase=phase,
-        next_agent=next_agent,
-        handoff_ready=handoff_ready,
-        acceptance_criteria=acceptance_criteria,
-        context=context,
-        work_log=work_log,
-        assessment=assessment,
-    )
-
-
-def is_xml_format(content: str) -> bool:
-    """Check if content is already in XML format."""
-    return "<session story=" in content
-
-
-def convert_session_file(
-    file_path: Path, *, dry_run: bool = False
-) -> dict[str, str | bool]:
-    """Convert a session file from markdown to XML format.
-
-    Args:
-        file_path: Path to session file
-        dry_run: If True, return converted content without writing
-
-    Returns:
-        Dict with 'success', 'message', and optionally 'content' (for dry_run)
-    """
-    if not file_path.exists():
-        return {"success": False, "message": f"File not found: {file_path}"}
-
-    content = file_path.read_text()
-
-    # Skip if already XML
-    if is_xml_format(content):
-        return {"success": True, "message": "Already in XML format", "skipped": True}
-
-    # Parse and convert
-    session = parse_markdown_session(content, file_path.name)
-    xml_content = session.to_xml()
-
-    if dry_run:
-        return {
-            "success": True,
-            "message": "Would convert to XML",
-            "content": xml_content,
-            "dry_run": True,
-        }
-
-    # Write converted content
-    file_path.write_text(xml_content)
-    return {"success": True, "message": f"Converted: {file_path.name}"}
-
-
-def find_session_files(root: Path) -> list[Path]:
-    """Find all session files in a project.
-
-    Args:
-        root: Project root directory
-
-    Returns:
-        List of session file paths
-    """
-    session_dir = root / ".session"
-    files = []
-
-    if session_dir.exists():
-        files.extend(session_dir.glob("*-session.md"))
-        archive_dir = session_dir / "archive"
-        if archive_dir.exists():
-            files.extend(archive_dir.glob("*-session.md"))
-
-    return sorted(files)