@pennyfarthing/core 10.0.2 → 10.0.5

package/pennyfarthing_scripts/prime/workflow.py

@@ -0,0 +1,277 @@
+"""
+Workflow state detection for Prime v2.
+
+Detects current workflow state by analyzing:
+- Active session files in .session/
+- Session headers for phase and workflow
+- Sprint backlog for available stories
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from pennyfarthing_scripts.common.config import get_project_root
+from pennyfarthing_scripts.prime.models import WorkflowState, WorkflowStatus
+
+
+def find_active_session(project_root: Path) -> Path | None:
+    """Find the active session file.
+
+    Looks in .session/ for *-session.md files, excluding context-*.md.
+    Returns the most recently modified session file.
+
+    Args:
+        project_root: Project root path
+
+    Returns:
+        Path to active session file, or None if not found
+    """
+    session_dir = project_root / ".session"
+    if not session_dir.is_dir():
+        return None
+
+    # Find *-session.md files (not context-*)
+    session_files = [
+        f for f in session_dir.glob("*-session.md")
+        if not f.name.startswith("context-")
+    ]
+
+    if not session_files:
+        return None
+
+    # Return the most recently modified one
+    return max(session_files, key=lambda f: f.stat().st_mtime)
+
+
+def parse_session_header(session_path: Path) -> dict[str, Any]:
+    """Parse session file header to extract metadata.
+
+    Looks for key: value patterns throughout the session file header sections.
+    Extracts workflow, phase, story_id, status from:
+    - ## Story Context section
+    - ## Workflow Phase section
+
+    Args:
+        session_path: Path to session file
+
+    Returns:
+        Dict with extracted metadata (workflow, phase, story_id, status)
+    """
+    content = session_path.read_text()
+    lines = content.split("\n")
+
+    result: dict[str, Any] = {}
+
+    # Extract story ID from filename (e.g., MSSCI-12419-session.md -> MSSCI-12419)
+    filename = session_path.stem
+    if filename.endswith("-session"):
+        result["story_id"] = filename[:-8]  # Remove "-session"
+
+    # Track which sections we're in (we care about Story Context and Workflow Phase)
+    in_relevant_section = True  # Start True to capture content before any ##
+
+    for line in lines:
+        # Track section headers
+        if line.startswith("## "):
+            # We care about Story Context and Workflow Phase sections
+            section_name = line[3:].strip().lower()
+            in_relevant_section = (
+                "story context" in section_name or
+                "workflow phase" in section_name or
+                "branch" in section_name
+            )
+            # Stop at assessment sections (too far down)
+            if "assessment" in section_name:
+                break
+            continue
+
+        # Only parse lines in relevant sections
+        if not in_relevant_section:
+            continue
+
+        # Look for key-value patterns
+        # Format is "**Key:** Value" (colon inside the bold)
+        # e.g., "- **Workflow:** tdd" or "- **Current Phase:** green"
+        match = re.search(r"\*\*([^*:]+):\*\*\s*(.+)", line)
+        if match:
+            key = match.group(1).lower().strip()
+            value = match.group(2).strip()
+
+            if key == "workflow":
+                result["workflow"] = value.lower()
+            elif key == "current phase":
+                # Extract phase name, handling "(APPROVED)" suffix
+                phase_match = re.match(r"(\w+)(?:\s*\(([^)]+)\))?", value)
+                if phase_match:
+                    result["phase"] = phase_match.group(1).lower()
+                    if phase_match.group(2):
+                        result["phase_status"] = phase_match.group(2).lower()
+            elif key == "id" and "story_id" not in result:
+                result["story_id"] = value
+            elif key == "status":
+                result["status"] = value.lower()
+
+    return result
+
+
+def get_phase_owner(workflow: str, phase: str, project_root: Path) -> str | None:
+    """Look up the agent that owns a workflow phase.
+
+    Reads the workflow YAML and finds the agent for the given phase.
+
+    Args:
+        workflow: Workflow name (tdd, trivial, bdd, etc.)
+        phase: Phase name (setup, red, green, review, finish)
+        project_root: Project root path
+
+    Returns:
+        Agent name (sm, tea, dev, reviewer), or None if not found
+    """
+    workflow_path = project_root / "pennyfarthing-dist" / "workflows" / f"{workflow}.yaml"
+
+    if not workflow_path.exists():
+        # Fallback to symlinked location
+        workflow_path = project_root / ".pennyfarthing" / "workflows" / f"{workflow}.yaml"
+        if not workflow_path.exists():
+            return None
+
+    try:
+        data = yaml.safe_load(workflow_path.read_text())
+        phases = data.get("workflow", {}).get("phases", [])
+
+        for p in phases:
+            if p.get("name") == phase:
+                return p.get("agent")
+
+        return None
+    except Exception:
+        return None
+
+
+def get_backlog_count(project_root: Path) -> int:
+    """Count stories in backlog, ready, or planning status.
+
+    Args:
+        project_root: Project root path
+
+    Returns:
+        Number of stories available for work
+    """
+    # Import here to avoid circular imports
+    from pennyfarthing_scripts.sprint.loader import load_sprint
+
+    sprint = load_sprint(project_root)
+    if not sprint or "epics" not in sprint:
+        return 0
+
+    count = 0
+    for epic in sprint["epics"]:
+        if not isinstance(epic, dict):
+            continue  # Skip string refs (defensive)
+        for story in epic.get("stories", []):
+            status = story.get("status", "").lower()
+            if status in ("backlog", "ready", "planning"):
+                count += 1
+
+    return count
+
+
+def detect_workflow_state(project_root: Path | None = None) -> WorkflowStatus:
+    """Detect the current workflow state.
+
+    Returns one of:
+    - FINISH_STATE: Session exists with phase=approved or review-approved
+    - IN_PROGRESS_STATE: Session exists with active phase
+    - NEW_WORK_STATE: No session and backlog has stories
+    - EMPTY_BACKLOG_STATE: No session and backlog is empty
+
+    Args:
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        WorkflowStatus with detected state and metadata
+    """
+    root = project_root or get_project_root()
+    session_file = find_active_session(root)
+
+    if session_file:
+        header = parse_session_header(session_file)
+        story_id = header.get("story_id")
+        workflow = header.get("workflow", "tdd")
+        phase = header.get("phase")
+        phase_status = header.get("phase_status", "")
+
+        # Check for finish state
+        if phase in ("approved", "review-approved", "finish"):
+            return WorkflowStatus(
+                state=WorkflowState.FINISH_STATE,
+                story_id=story_id,
+                phase=phase,
+                phase_owner="sm",
+                workflow=workflow,
+                session_file=str(session_file),
+            )
+
+        # Check if phase is approved (e.g., "REVIEW (APPROVED)")
+        if phase_status == "approved":
+            return WorkflowStatus(
+                state=WorkflowState.FINISH_STATE,
+                story_id=story_id,
+                phase=phase,
+                phase_owner="sm",
+                workflow=workflow,
+                session_file=str(session_file),
+            )
+
+        # In progress state - look up phase owner
+        owner = get_phase_owner(workflow, phase, root) if phase else None
+
+        return WorkflowStatus(
+            state=WorkflowState.IN_PROGRESS_STATE,
+            story_id=story_id,
+            phase=phase,
+            phase_owner=owner,
+            workflow=workflow,
+            session_file=str(session_file),
+        )
+
+    # No active session - check backlog
+    backlog_count = get_backlog_count(root)
+
+    if backlog_count > 0:
+        return WorkflowStatus(
+            state=WorkflowState.NEW_WORK_STATE,
+            backlog_count=backlog_count,
+        )
+
+    return WorkflowStatus(
+        state=WorkflowState.EMPTY_BACKLOG_STATE,
+    )
+
+
+def check_redirect(workflow_status: WorkflowStatus, agent_name: str) -> tuple[str, str] | None:
+    """Check if the activated agent should redirect to another agent.
+
+    Returns redirect info if:
+    - IN_PROGRESS_STATE and agent_name != phase_owner
+
+    Args:
+        workflow_status: Current workflow status
+        agent_name: Name of the activated agent
+
+    Returns:
+        Tuple of (target_agent, reason) if redirect needed, None otherwise
+    """
+    if workflow_status.state == WorkflowState.IN_PROGRESS_STATE:
+        if workflow_status.phase_owner and workflow_status.phase_owner != agent_name:
+            return (
+                workflow_status.phase_owner,
+                f"Phase '{workflow_status.phase}' is owned by '{workflow_status.phase_owner}'",
+            )
+
+    return None

package/pennyfarthing_scripts/schema_validation_hook.py

@@ -0,0 +1,306 @@
+#!/usr/bin/env python3
+"""
+XML Schema Validation Hook for PreToolUse.
+
+Validates session, skill, and workflow step files on Write/Edit operations.
+Blocks the tool call if validation fails, providing immediate feedback.
+
+Usage in settings.json:
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Write|Edit",
+      "hooks": [{
+        "type": "command",
+        "command": "python3 -m pennyfarthing_scripts.schema_validation_hook"
+      }]
+    }]
+  }
+}
+
+Story: XML Schema Migration Tools
+"""
+
+import re
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent))
+
+from hooks import (
+    read_stdin_json,
+    output_hook_response,
+    HookResponse,
+)
+
+
+# =============================================================================
+# File Type Detection
+# =============================================================================
+
+
+def is_session_file(file_path: str) -> bool:
+    """Check if path is a session file."""
+    return file_path.endswith("-session.md") and ".session/" in file_path
+
+
+def is_skill_file(file_path: str) -> bool:
+    """Check if path is a skill SKILL.md file."""
+    return file_path.endswith("/SKILL.md") and "/skills/" in file_path
+
+
+def is_step_file(file_path: str) -> bool:
+    """Check if path is a workflow step file."""
+    path = Path(file_path)
+    return (
+        path.name.startswith("step-")
+        and path.name.endswith(".md")
+        and "/workflows/" in file_path
+        and "/steps/" in file_path
+    )
+
+
+def get_file_type(file_path: str) -> str | None:
+    """Detect file type from path."""
+    if is_session_file(file_path):
+        return "session"
+    elif is_skill_file(file_path):
+        return "skill"
+    elif is_step_file(file_path):
+        return "step"
+    return None
+
+
+# =============================================================================
+# Content-Based Validation (inline to avoid import issues)
+# =============================================================================
+
+# Skill required tags
+SKILL_REQUIRED_TAGS = ["run", "output"]
+
+# Workflow step required tags
+STEP_REQUIRED_TAGS = ["purpose", "instructions", "output"]
+
+# Step meta required fields
+STEP_META_FIELDS = ["step", "workflow", "agent", "next"]
+
+
+def _has_tag(content: str, tag: str) -> bool:
+    """Check if content contains a specific XML tag."""
+    return f"<{tag}>" in content or f"<{tag} " in content
+
+
+def validate_session_content(content: str) -> list[str]:
+    """Validate session file content.
+
+    Args:
+        content: File content to validate
+
+    Returns:
+        List of error messages (empty if valid)
+    """
+    errors = []
+
+    # Check for XML format indicator
+    if "<session" not in content:
+        # Old markdown format - warn but don't block during migration
+        return []
+
+    # Validate <session> root with attributes
+    if not re.search(r'<session\s+story="[^"]+"', content):
+        errors.append("Missing story attribute on <session>")
+
+    if not re.search(r'<session[^>]+workflow="[^"]+"', content):
+        errors.append("Missing workflow attribute on <session>")
+
+    # Validate <meta> section
+    if not _has_tag(content, "meta"):
+        errors.append("Missing <meta> section")
+    else:
+        if "<jira>" not in content:
+            errors.append("Missing <jira> in <meta>")
+        if "<started>" not in content:
+            errors.append("Missing <started> in <meta>")
+
+    # Validate <status> element
+    if not _has_tag(content, "status"):
+        errors.append("Missing <status> element")
+    else:
+        if 'phase="' not in content:
+            errors.append("Missing phase attribute on <status>")
+
+    return errors
+
+
+def validate_skill_content(content: str) -> list[str]:
+    """Validate skill file content.
+
+    Args:
+        content: File content to validate
+
+    Returns:
+        List of error messages (empty if valid)
+    """
+    errors = []
+
+    # Check YAML frontmatter
+    if not content.startswith("---\n"):
+        errors.append("Missing YAML frontmatter")
+    else:
+        parts = content.split("---", 2)
+        if len(parts) >= 2:
+            frontmatter = parts[1]
+            if "name:" not in frontmatter:
+                errors.append("Missing 'name' in frontmatter")
+            if "description:" not in frontmatter:
+                errors.append("Missing 'description' in frontmatter")
+
+    # Check required tags
+    for tag in SKILL_REQUIRED_TAGS:
+        if not _has_tag(content, tag):
+            errors.append(f"Missing <{tag}> tag (required)")
+
+    return errors
+
+
+def validate_step_content(content: str) -> list[str]:
+    """Validate workflow step file content.
+
+    Args:
+        content: File content to validate
+
+    Returns:
+        List of error messages (empty if valid)
+    """
+    errors = []
+
+    # Check required tags
+    for tag in STEP_REQUIRED_TAGS:
+        if not _has_tag(content, tag):
+            errors.append(f"Missing <{tag}> tag")
+
+    # Check step-meta fields if tag exists
+    if _has_tag(content, "step-meta"):
+        meta_match = re.search(r"<step-meta>(.+?)</step-meta>", content, re.DOTALL)
+        if meta_match:
+            meta_content = meta_match.group(1)
+            for field_name in STEP_META_FIELDS:
+                if f"{field_name}:" not in meta_content:
+                    errors.append(f"Missing '{field_name}' in step-meta")
+
+    return errors
+
+
+def validate_content(file_path: str, content: str) -> list[str]:
+    """Validate content based on file type.
+
+    Args:
+        file_path: Path to file being written
+        content: Content being written
+
+    Returns:
+        List of error messages (empty if valid)
+    """
+    file_type = get_file_type(file_path)
+
+    if file_type == "session":
+        return validate_session_content(content)
+    elif file_type == "skill":
+        return validate_skill_content(content)
+    elif file_type == "step":
+        return validate_step_content(content)
+
+    return []
+
+
+# =============================================================================
+# Hook Entry Point
+# =============================================================================
+
+
+def main() -> None:
+    """Main entry point for schema validation hook."""
+    try:
+        # Read tool data from Claude Code
+        tool_data = read_stdin_json()
+
+        tool_name = tool_data.get("tool_name", "")
+        tool_input = tool_data.get("tool_input", {})
+
+        # Only process Write and Edit tools
+        if tool_name not in ("Write", "Edit"):
+            output_hook_response(HookResponse(
+                event_name="PreToolUse",
+                decision="allow",
+                reason="Not a Write/Edit operation",
+            ))
+            sys.exit(0)
+
+        # Get file path
+        file_path = tool_input.get("file_path", "")
+        if not file_path:
+            output_hook_response(HookResponse(
+                event_name="PreToolUse",
+                decision="allow",
+                reason="No file path",
+            ))
+            sys.exit(0)
+
+        # Check if this is a file we care about
+        file_type = get_file_type(file_path)
+        if not file_type:
+            output_hook_response(HookResponse(
+                event_name="PreToolUse",
+                decision="allow",
+                reason="Not a session/skill/step file",
+            ))
+            sys.exit(0)
+
+        # Get content to validate
+        # For Write: use 'content'
+        # For Edit: we need to simulate the edit result
+        if tool_name == "Write":
+            content = tool_input.get("content", "")
+        else:
+            # Edit operation - we can't easily validate without reading the file
+            # For now, allow Edits and validate on Write only
+            output_hook_response(HookResponse(
+                event_name="PreToolUse",
+                decision="allow",
+                reason="Edit operations validated post-hoc",
+            ))
+            sys.exit(0)
+
+        # Validate content
+        errors = validate_content(file_path, content)
+
+        if errors:
+            # Block the write
+            error_msg = f"Schema validation failed for {file_type} file:\n"
+            error_msg += "\n".join(f"  - {e}" for e in errors)
+            error_msg += f"\n\nFile: {file_path}"
+
+            output_hook_response(HookResponse(
+                event_name="PreToolUse",
+                decision="deny",
+                reason=error_msg,
+            ))
+            sys.exit(0)
+
+        # Validation passed
+        output_hook_response(HookResponse(
+            event_name="PreToolUse",
+            decision="allow",
+            reason=f"Schema validation passed for {file_type} file",
+        ))
+        sys.exit(0)
+
+    except Exception as e:
+        # On error, allow to avoid blocking legitimate work
+        print(f"[schema-validation-hook] Error: {e}", file=sys.stderr)
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/pennyfarthing_scripts/sprint/__init__.py

@@ -0,0 +1,66 @@
+"""
+Sprint management package for Pennyfarthing scripts.
+
+This package provides:
+- loader: Sprint YAML loading and parsing
+- status: Sprint status operations
+- work: Work session management
+- archive: Story archiving
+
+Usage:
+    # Use the loader module
+    from pennyfarthing_scripts.sprint import load_sprint, find_epic
+    sprint_data = load_sprint()
+    epic = find_epic(sprint_data, "63")
+
+    # Use CLI
+    python -m pennyfarthing_scripts.sprint <subcommand> [args]
+"""
+
+# Re-export from loader for backwards compatibility
+from pennyfarthing_scripts.sprint.loader import (
+    find_epic,
+    find_story,
+    get_all_stories,
+    get_epic_by_id,
+    get_sprint_info,
+    get_stories_by_status,
+    get_story_by_id,
+    get_story_field,
+    load_current_sprint,
+    load_sprint,
+)
+
+# Import submodules to make them accessible
+from pennyfarthing_scripts.sprint import (
+    archive,
+    loader,
+    status,
+    work,
+)
+
+# CLI entry point - import module, not function, so "from sprint import cli" gets the module
+from pennyfarthing_scripts.sprint import cli
+from pennyfarthing_scripts.sprint.cli import main
+
+__all__ = [
+    # Loader functions
+    "find_epic",
+    "find_story",
+    "get_all_stories",
+    "get_epic_by_id",
+    "get_sprint_info",
+    "get_stories_by_status",
+    "get_story_by_id",
+    "get_story_field",
+    "load_current_sprint",
+    "load_sprint",
+    # Submodules
+    "archive",
+    "loader",
+    "status",
+    "work",
+    # CLI
+    "cli",
+    "main",
+]

package/pennyfarthing_scripts/sprint/__main__.py

@@ -0,0 +1,10 @@
+"""
+Entry point for python -m pennyfarthing_scripts.sprint
+"""
+
+import sys
+
+from pennyfarthing_scripts.sprint.cli import cli
+
+if __name__ == "__main__":
+    sys.exit(cli())