@pennyfarthing/core 11.1.0 → 11.2.0

package/pennyfarthing_scripts/workflow/helpers.py

@@ -0,0 +1,241 @@
+"""
+Shared helpers for workflow commands.
+
+Extracted from complete-step.py and bash scripts. Provides common
+functions for session parsing, workflow file resolution, and step management.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import yaml
+
+from pennyfarthing_scripts.common.config import get_project_root
+
+
+def get_workflows_dir(project_root: Path | None = None) -> Path:
+    """Get the workflows directory path."""
+    root = project_root or get_project_root()
+    return root / ".pennyfarthing" / "workflows"
+
+
+def get_session_dir(project_root: Path | None = None) -> Path:
+    """Get the session directory path."""
+    root = project_root or get_project_root()
+    return root / ".session"
+
+
+def find_workflow_file(workflows_dir: Path, workflow_name: str) -> Path | None:
+    """Find workflow YAML definition.
+
+    Supports both flat (name.yaml) and nested (name/workflow.yaml) layouts.
+
+    Returns:
+        Path to the workflow file, or None if not found.
+    """
+    flat = workflows_dir / f"{workflow_name}.yaml"
+    if flat.exists():
+        return flat
+
+    nested = workflows_dir / workflow_name / "workflow.yaml"
+    if nested.exists():
+        return nested
+
+    return None
+
+
+def load_workflow_data(workflow_file: Path) -> dict:
+    """Load and parse workflow YAML file.
+
+    Returns:
+        Parsed YAML data dict.
+    """
+    with open(workflow_file) as f:
+        return yaml.safe_load(f) or {}
+
+
+def get_workflow_type(workflow_data: dict) -> str:
+    """Get workflow type from parsed YAML data.
+
+    Returns:
+        'phased', 'stepped', or 'procedural'
+    """
+    wf = workflow_data.get("workflow", {})
+    wf_type = wf.get("type", "phased")
+    has_steps = wf.get("steps") is not None
+    if has_steps or wf_type == "stepped":
+        return "stepped"
+    return wf_type
+
+
+def resolve_steps_path(
+    workflow_data: dict,
+    workflow_dir: Path,
+    mode: str | None,
+    project_root: Path,
+) -> Path:
+    """Resolve the steps directory path from workflow data.
+
+    Handles mode-specific paths, relative paths, and absolute paths.
+
+    Args:
+        workflow_data: Parsed workflow YAML
+        workflow_dir: Directory containing the workflow.yaml file
+        mode: Active mode (create, validate, edit) or None
+        project_root: Project root directory
+
+    Returns:
+        Resolved absolute Path to steps directory
+    """
+    wf = workflow_data.get("workflow", {})
+
+    # Try mode-specific path first
+    if mode:
+        modes = wf.get("modes", {})
+        mode_path = modes.get(mode)
+        if mode_path and mode_path != "null":
+            return _resolve_path(mode_path, workflow_dir, project_root)
+
+    # Try default mode
+    default_mode = wf.get("modes", {}).get("default")
+    if default_mode:
+        modes = wf.get("modes", {})
+        mode_path = modes.get(default_mode)
+        if mode_path and mode_path != "null":
+            return _resolve_path(mode_path, workflow_dir, project_root)
+
+    # Fall back to steps.path
+    steps_path_str = wf.get("steps", {}).get("path", ".")
+    return _resolve_path(steps_path_str, workflow_dir, project_root)
+
+
+def _resolve_path(path_str: str, workflow_dir: Path, project_root: Path) -> Path:
+    """Resolve a path string relative to workflow dir or project root."""
+    if path_str.startswith("./"):
+        return workflow_dir / path_str[2:]
+    elif not Path(path_str).is_absolute():
+        return project_root / path_str
+    else:
+        return Path(path_str)
+
+
+def count_steps(steps_path: Path) -> int:
+    """Count step files in a directory."""
+    if not steps_path.is_dir():
+        return 0
+    return len([
+        f for f in steps_path.iterdir()
+        if f.is_file() and re.match(r"step-\d+", f.name) and f.suffix == ".md"
+    ])
+
+
+def find_step_file(steps_path: Path, step_number: int) -> Path | None:
+    """Find step file for a given step number.
+
+    Handles naming variants: step-01.md, step-01-name.md, step-1-name.md
+    """
+    padded = f"{step_number:02d}"
+    matches = sorted([
+        f for f in steps_path.iterdir()
+        if f.is_file()
+        and (f.name.startswith(f"step-{padded}") or f.name.startswith(f"step-{step_number}-"))
+        and f.suffix == ".md"
+    ])
+    return matches[0] if matches else None
+
+
+def strip_frontmatter(content: str) -> str:
+    """Remove YAML frontmatter from step file content."""
+    if not content.startswith("---"):
+        return content
+    end = content.find("---", 3)
+    if end == -1:
+        return content
+    return content[end + 3:].lstrip("\n")
+
+
+def parse_session_field(content: str, field: str) -> str:
+    """Extract a field value from session markdown.
+
+    Matches lines like: - **Field:** value
+    """
+    pattern = rf"^- \*\*{re.escape(field)}:\*\*\s*(.+)$"
+    match = re.search(pattern, content, re.MULTILINE)
+    return match.group(1).strip() if match else ""
+
+
+def find_workflow_session(
+    session_dir: Path, workflow_name: str | None
+) -> tuple[Path, str] | None:
+    """Find workflow session file and determine workflow name.
+
+    Args:
+        session_dir: Path to .session/ directory
+        workflow_name: Explicit workflow name, or None to auto-detect
+
+    Returns:
+        Tuple of (session_path, workflow_name), or None if not found
+    """
+    if workflow_name:
+        session_file = session_dir / f"{workflow_name}-workflow-session.md"
+        if session_file.exists():
+            return session_file, workflow_name
+        return None
+
+    # Auto-detect from session directory
+    sessions = sorted(session_dir.glob("*-workflow-session.md"))
+    if not sessions:
+        return None
+
+    session_file = sessions[0]
+    content = session_file.read_text()
+
+    # Try to extract workflow name from content
+    wf_match = re.search(r"^\*\*Workflow:\*\*\s*(.+)$", content, re.MULTILINE)
+    if wf_match:
+        name = wf_match.group(1).strip()
+    else:
+        name = session_file.stem.replace("-workflow-session", "")
+
+    return session_file, name
+
+
+def parse_steps_completed(value: str) -> list[int]:
+    """Parse steps completed array from string like '[1, 2, 3]'."""
+    if not value or value == "[]":
+        return []
+    return [int(n) for n in re.findall(r"\d+", value)]
+
+
+def format_steps_completed(steps: list[int]) -> str:
+    """Format steps list as bracket notation."""
+    if not steps:
+        return "[]"
+    return "[" + ", ".join(str(s) for s in steps) + "]"
+
+
+def find_story_session(session_dir: Path, story_id: str) -> Path | None:
+    """Find a story session file by story ID.
+
+    Handles various naming patterns: 56-1-session.md, MSSCI-12190-session.md
+    Also searches file content for matching Jira/ID fields.
+    """
+    # Try direct filename match
+    story_id_lower = story_id.lower()
+    for pattern in [f"{story_id}-session.md", f"{story_id_lower}-session.md"]:
+        candidate = session_dir / pattern
+        if candidate.exists():
+            return candidate
+
+    # Search file contents for matching story ID
+    for session_file in session_dir.glob("*-session.md"):
+        try:
+            content = session_file.read_text()
+            if f"Jira:** {story_id}" in content or f"ID:** {story_id}" in content:
+                return session_file
+        except OSError:
+            continue
+
+    return None

package/pennyfarthing_scripts/{workflow.py → workflow/scale.py}

@@ -181,107 +181,3 @@ def get_scale_level_info(level: int) -> dict[str, Any]:
         return {"level": level, "scope": "unknown", "stories_min": 0,
                 "stories_max": 0, "workflow": "prd", "artifacts": []}
     return SCALE_LEVELS[level].copy()
-
-
-# Phase ownership mapping for TDD workflow
-# Canonical YAML names: setup, red, green, review, finish
-TDD_PHASE_OWNERS: dict[str, str] = {
-    "setup": "sm",
-    "red": "tea",
-    "green": "dev",
-    "review": "reviewer",
-    "finish": "sm",
-}
-
-# Phase ownership mapping for trivial workflow (no TEA)
-# Canonical YAML names: setup, implement, review, finish
-TRIVIAL_PHASE_OWNERS: dict[str, str] = {
-    "setup": "sm",
-    "implement": "dev",
-    "review": "reviewer",
-    "finish": "sm",
-}
-
-# All workflow phase mappings
-WORKFLOW_PHASES: dict[str, dict[str, str]] = {
-    "tdd": TDD_PHASE_OWNERS,
-    "trivial": TRIVIAL_PHASE_OWNERS,
-    "bdd": TDD_PHASE_OWNERS,  # BDD uses same phases as TDD
-}
-
-
-def get_phase_owner(workflow: str, phase: str) -> str:
-    """Get the agent that owns a workflow phase.
-
-    Args:
-        workflow: Workflow name (tdd, trivial, bdd)
-        phase: Phase name (setup, red, implement, review, approved)
-
-    Returns:
-        Agent name (sm, tea, dev, reviewer)
-    """
-    phases = WORKFLOW_PHASES.get(workflow, TDD_PHASE_OWNERS)
-    return phases.get(phase, "sm")
-
-
-def get_workflow_state() -> dict[str, Any]:
-    """Get current workflow state from session files.
-
-    Scans .session/ directory for active session files and extracts
-    workflow state information.
-
-    Returns:
-        Dict with state, story_id, workflow, phase fields
-    """
-    from pathlib import Path
-
-    # Look for session files in .session/
-    session_dir = Path(".session")
-    if not session_dir.exists():
-        return {"state": "EMPTY_BACKLOG_STATE"}
-
-    # Find session files (pattern: *-session.md)
-    session_files = list(session_dir.glob("*-session.md"))
-
-    # Filter out workflow session files and archived files
-    story_sessions = [
-        f for f in session_files
-        if not f.name.startswith("prd-")
-        and not f.name.startswith("architecture-")
-        and not f.name.startswith("research-")
-        and "workflow" not in f.name.lower()
-    ]
-
-    if not story_sessions:
-        return {"state": "NEW_WORK_STATE"}
-
-    # Read the most recent session file
-    session_file = max(story_sessions, key=lambda f: f.stat().st_mtime)
-    content = session_file.read_text()
-
-    # Extract fields from markdown format
-    # Session files use list format: "- **Field:** value"
-    # Also handle direct format: "**Field:** value"
-    result: dict[str, Any] = {"state": "IN_PROGRESS_STATE"}
-
-    for line in content.split("\n"):
-        # Strip leading "- " for list items
-        stripped = line.lstrip("- ").strip()
-
-        if stripped.startswith("**Story:**"):
-            result["story_id"] = stripped.replace("**Story:**", "").strip()
-        elif stripped.startswith("**Jira:**"):
-            result["story_id"] = stripped.replace("**Jira:**", "").strip()
-        elif stripped.startswith("**ID:**"):
-            # Also check **ID:** field (used in Story Details section)
-            if "story_id" not in result:
-                result["story_id"] = stripped.replace("**ID:**", "").strip()
-        elif stripped.startswith("**Type:**"):
-            # Workflow section uses **Type:** not **Workflow:**
-            result["workflow"] = stripped.replace("**Type:**", "").strip()
-        elif stripped.startswith("**Workflow:**"):
-            result["workflow"] = stripped.replace("**Workflow:**", "").strip()
-        elif stripped.startswith("**Phase:**"):
-            result["phase"] = stripped.replace("**Phase:**", "").strip()
-
-    return result

package/pennyfarthing_scripts/workflow/state.py

@@ -0,0 +1,112 @@
+"""
+Workflow phase ownership and state detection.
+
+Maps workflow phases to their owning agents and provides session
+state detection from .session/ files.
+"""
+
+from typing import Any
+
+
+# Phase ownership mapping for TDD workflow
+# Canonical YAML names: setup, red, green, review, finish
+TDD_PHASE_OWNERS: dict[str, str] = {
+    "setup": "sm",
+    "red": "tea",
+    "green": "dev",
+    "review": "reviewer",
+    "finish": "sm",
+}
+
+# Phase ownership mapping for trivial workflow (no TEA)
+# Canonical YAML names: setup, implement, review, finish
+TRIVIAL_PHASE_OWNERS: dict[str, str] = {
+    "setup": "sm",
+    "implement": "dev",
+    "review": "reviewer",
+    "finish": "sm",
+}
+
+# All workflow phase mappings
+WORKFLOW_PHASES: dict[str, dict[str, str]] = {
+    "tdd": TDD_PHASE_OWNERS,
+    "trivial": TRIVIAL_PHASE_OWNERS,
+    "bdd": TDD_PHASE_OWNERS,  # BDD uses same phases as TDD
+}
+
+
+def get_phase_owner(workflow: str, phase: str) -> str:
+    """Get the agent that owns a workflow phase.
+
+    Args:
+        workflow: Workflow name (tdd, trivial, bdd)
+        phase: Phase name (setup, red, implement, review, approved)
+
+    Returns:
+        Agent name (sm, tea, dev, reviewer)
+    """
+    phases = WORKFLOW_PHASES.get(workflow, TDD_PHASE_OWNERS)
+    return phases.get(phase, "sm")
+
+
+def get_workflow_state() -> dict[str, Any]:
+    """Get current workflow state from session files.
+
+    Scans .session/ directory for active session files and extracts
+    workflow state information.
+
+    Returns:
+        Dict with state, story_id, workflow, phase fields
+    """
+    from pathlib import Path
+
+    # Look for session files in .session/
+    session_dir = Path(".session")
+    if not session_dir.exists():
+        return {"state": "EMPTY_BACKLOG_STATE"}
+
+    # Find session files (pattern: *-session.md)
+    session_files = list(session_dir.glob("*-session.md"))
+
+    # Filter out workflow session files and archived files
+    story_sessions = [
+        f for f in session_files
+        if not f.name.startswith("prd-")
+        and not f.name.startswith("architecture-")
+        and not f.name.startswith("research-")
+        and "workflow" not in f.name.lower()
+    ]
+
+    if not story_sessions:
+        return {"state": "NEW_WORK_STATE"}
+
+    # Read the most recent session file
+    session_file = max(story_sessions, key=lambda f: f.stat().st_mtime)
+    content = session_file.read_text()
+
+    # Extract fields from markdown format
+    # Session files use list format: "- **Field:** value"
+    # Also handle direct format: "**Field:** value"
+    result: dict[str, Any] = {"state": "IN_PROGRESS_STATE"}
+
+    for line in content.split("\n"):
+        # Strip leading "- " for list items
+        stripped = line.lstrip("- ").strip()
+
+        if stripped.startswith("**Story:**"):
+            result["story_id"] = stripped.replace("**Story:**", "").strip()
+        elif stripped.startswith("**Jira:**"):
+            result["story_id"] = stripped.replace("**Jira:**", "").strip()
+        elif stripped.startswith("**ID:**"):
+            # Also check **ID:** field (used in Story Details section)
+            if "story_id" not in result:
+                result["story_id"] = stripped.replace("**ID:**", "").strip()
+        elif stripped.startswith("**Type:**"):
+            # Workflow section uses **Type:** not **Workflow:**
+            result["workflow"] = stripped.replace("**Type:**", "").strip()
+        elif stripped.startswith("**Workflow:**"):
+            result["workflow"] = stripped.replace("**Workflow:**", "").strip()
+        elif stripped.startswith("**Phase:**"):
+            result["phase"] = stripped.replace("**Phase:**", "").strip()
+
+    return result

package/scripts/README.md

@@ -0,0 +1,41 @@
+# Meta Scripts
+
+**These scripts are NOT distributed to users.** They are for Pennyfarthing framework development only.
+
+## Contents
+
+| Script | Purpose |
+|--------|---------|
+| `deploy.sh` | Release Pennyfarthing (version bump, tag, push, GitHub release) |
+| `cyclist-debug.mjs` | Debug Cyclist connection |
+| `handoff-cli.{sh,js}` | Test handoff flow |
+| `verify-visual-mapping.js` | Verify theme visual mappings |
+| `migrate-assets-to-slug.sh` | One-time migration script |
+| `resize-portraits.sh` | Resize portrait images |
+| `resolve-portrait.mjs` | Portrait resolution logic |
+| `validate-refs.js` | Validate internal references |
+
+> Benchmark scripts have been moved to `packages/benchmark/`.
+
+## Usage
+
+Run from pennyfarthing repo root:
+
+```bash
+# Release a new version
+./scripts/deploy.sh --dry-run patch
+./scripts/deploy.sh patch
+```
+
+## Where Should My Script Go?
+
+**Put it here if:**
+- It's for framework development/CI only
+- Users should NOT have access to it
+- It uses GPU/heavy dependencies (keep in meta, not distributed)
+
+**Put it in `pennyfarthing-dist/scripts/` if:**
+- Users need it for their workflows
+- It's part of the sprint/story/jira tooling
+
+See `CLAUDE.md` for the full decision tree.

package/pennyfarthing-dist/skills/pf-workflow/scripts/list-workflows.sh

@@ -1,91 +0,0 @@
-#!/bin/bash
-# List all available workflows with type indicators
-# Usage: .pennyfarthing/scripts/workflow/list-workflows.sh
-#    or: Invoked with PROJECT_ROOT already set
-#
-# MSSCI-12083: Added type, steps, and modes columns
-
-set -euo pipefail
-
-# PROJECT_ROOT should be set by find-root.sh, but find it if not
-if [[ -z "${PROJECT_ROOT:-}" ]]; then
-  d="$PWD"
-  while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do
-    d="$(dirname "$d")"
-  done
-  PROJECT_ROOT="$d"
-fi
-
-WORKFLOWS_DIR="$PROJECT_ROOT/.pennyfarthing/workflows"
-
-if [[ ! -d "$WORKFLOWS_DIR" ]]; then
-  echo "Error: Workflows directory not found at $WORKFLOWS_DIR"
-  exit 1
-fi
-
-if ! command -v yq &> /dev/null; then
-  echo "Error: yq is required but not installed"
-  echo "Install with: brew install yq"
-  exit 1
-fi
-
-echo "# Available Workflows"
-echo ""
-echo "| Workflow | Type | Default | Steps/Phases | Modes | Description |"
-echo "|----------|------|---------|--------------|-------|-------------|"
-
-for f in "$WORKFLOWS_DIR"/*.yaml; do
-  [[ -f "$f" ]] || continue
-
-  name=$(yq eval '.workflow.name' "$f")
-  desc=$(yq eval '.workflow.description' "$f" | head -1)
-  is_default=$(yq eval '.workflow.triggers.default // false' "$f")
-
-  # Detect workflow type (stepped vs phased)
-  # Stepped workflows have .workflow.type == "stepped" or .workflow.steps
-  workflow_type=$(yq eval '.workflow.type // "phased"' "$f")
-  has_steps=$(yq eval '.workflow.steps != null' "$f")
-
-  if [[ "$has_steps" == "true" ]] || [[ "$workflow_type" == "stepped" ]]; then
-    type_col="stepped"
-    # Count step files if steps.path is defined
-    steps_path=$(yq eval '.workflow.steps.path // ""' "$f")
-    steps_pattern=$(yq eval '.workflow.steps.pattern // "step-*.md"' "$f")
-    if [[ -n "$steps_path" ]] && [[ -d "$PROJECT_ROOT/$steps_path" ]]; then
-      step_count=$(find "$PROJECT_ROOT/$steps_path" -name "$steps_pattern" 2>/dev/null | wc -l | tr -d ' ')
-      steps_col="${step_count} steps"
-    else
-      steps_col="-"
-    fi
-  else
-    type_col="phased"
-    # Count phases for phased workflows
-    phase_count=$(yq eval '.workflow.phases | length' "$f")
-    steps_col="${phase_count} phases"
-  fi
-
-  # Default column
-  if [[ "$is_default" == "true" ]]; then
-    default_col="yes"
-  else
-    default_col="no"
-  fi
-
-  # Modes column (for tri-modal workflows)
-  modes=$(yq eval '.workflow.modes.available // []' "$f")
-  if [[ "$modes" != "[]" ]] && [[ "$modes" != "null" ]]; then
-    # Format as comma-separated list
-    modes_col=$(yq eval '.workflow.modes.available | join(",")' "$f")
-  else
-    modes_col="-"
-  fi
-
-  echo "| $name | $type_col | $default_col | $steps_col | $modes_col | $desc |"
-done
-
-echo ""
-echo "**Legend:**"
-echo "- **phased**: Agent-driven workflow (SM → TEA → Dev → Reviewer)"
-echo "- **stepped**: Step-by-step guided workflow with progressive disclosure"
-echo ""
-echo "Use \`/workflow show <name>\` for workflow details."