@pennyfarthing/core 10.0.5 → 10.2.0

package/pennyfarthing_scripts/validate/adapters/workflow.py

@@ -0,0 +1,320 @@
+"""Workflow YAML schema validator adapter.
+
+Validates workflow definition files in pennyfarthing-dist/workflows/.
+Checks common fields, variant-specific structure (phased/stepped/procedural),
+and cross-references agent names against agent definitions.
+
+Story: MSSCI-14709 (91-11)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from pennyfarthing_scripts.validate import ValidateReport
+
+# Known workflow types
+VALID_TYPES = {"phased", "stepped", "procedural"}
+
+# Known gate types for phased workflows
+VALID_GATE_TYPES = {
+    "tests_pass",
+    "tests_fail",
+    "approval",
+    "manual",
+    "validation",
+    "design_review",
+    "quality_pass",
+}
+
+
+def discover_workflow_files(workflows_dir: Path) -> list[Path]:
+    """Discover all workflow YAML files.
+
+    Finds root-level *.yaml files and subdirectory workflow.yaml files.
+    Excludes non-workflow YAML (e.g., templates).
+
+    Returns:
+        Sorted list of Path objects for workflow YAML files.
+    """
+    files: list[Path] = []
+
+    if not workflows_dir.is_dir():
+        return files
+
+    # Root-level *.yaml files
+    for f in sorted(workflows_dir.glob("*.yaml")):
+        files.append(f)
+
+    # Subdirectory workflow.yaml files
+    for f in sorted(workflows_dir.glob("*/workflow.yaml")):
+        files.append(f)
+
+    return files
+
+
+def _get_agent_stems(agents_dir: Path) -> set[str]:
+    """Get set of agent file stems from agents directory."""
+    if not agents_dir.is_dir():
+        return set()
+    return {f.stem for f in agents_dir.glob("*.md") if f.name != "README.md"}
+
+
+def _check_agent_ref(
+    agent_name: str, agent_stems: set[str], context: str
+) -> list[str]:
+    """Check if an agent reference exists. Returns warnings for unknown agents."""
+    warnings: list[str] = []
+    if agent_name and agent_name not in agent_stems:
+        warnings.append(
+            f"Agent '{agent_name}' referenced in {context} not found in agents/"
+        )
+    return warnings
+
+
+def validate_common(data: dict, path: Path) -> tuple[list[str], list[str]]:
+    """Validate common fields present in all workflow types.
+
+    Returns:
+        (errors, warnings) — two lists of message strings.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    if "name" not in data:
+        errors.append("Missing required field: name")
+
+    wtype = data.get("type")
+    if wtype is not None and wtype not in VALID_TYPES:
+        errors.append(
+            f"Invalid type '{wtype}' (must be one of: {', '.join(sorted(VALID_TYPES))})"
+        )
+
+    if "description" not in data:
+        warnings.append("Missing recommended field: description")
+
+    return errors, warnings
+
+
+def validate_phased(
+    data: dict, path: Path, agents_dir: Path
+) -> tuple[list[str], list[str]]:
+    """Validate phased workflow structure.
+
+    Returns:
+        (errors, warnings) — two lists of message strings.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+    agent_stems = _get_agent_stems(agents_dir)
+
+    phases = data.get("phases")
+
+    if phases is None:
+        errors.append("Missing required field: phases")
+        return errors, warnings
+
+    if not isinstance(phases, list):
+        errors.append("Field 'phases' must be a list")
+        return errors, warnings
+
+    if len(phases) == 0:
+        errors.append("Field 'phases' must not be empty")
+        return errors, warnings
+
+    seen_names: set[str] = set()
+
+    for i, phase in enumerate(phases):
+        if not isinstance(phase, dict):
+            errors.append(f"Phase {i} must be a mapping")
+            continue
+
+        phase_name = phase.get("name")
+        if not phase_name:
+            errors.append(f"Phase {i} missing required field: name")
+        else:
+            if phase_name in seen_names:
+                warnings.append(f"Duplicate phase name: '{phase_name}'")
+            seen_names.add(phase_name)
+
+        agent = phase.get("agent")
+        if not agent:
+            errors.append(
+                f"Phase {i}{' (' + phase_name + ')' if phase_name else ''} "
+                f"missing required field: agent"
+            )
+        else:
+            warnings.extend(
+                _check_agent_ref(agent, agent_stems, f"phase '{phase_name or i}'")
+            )
+
+        # Gate validation
+        gate = phase.get("gate")
+        if gate and isinstance(gate, dict):
+            gate_type = gate.get("type")
+            if gate_type is None:
+                errors.append(
+                    f"Phase '{phase_name or i}' gate missing required field: type"
+                )
+            elif gate_type not in VALID_GATE_TYPES:
+                warnings.append(
+                    f"Phase '{phase_name or i}' has unknown gate type: "
+                    f"'{gate_type}'"
+                )
+
+    return errors, warnings
+
+
+def validate_stepped(
+    data: dict, path: Path, agents_dir: Path
+) -> tuple[list[str], list[str]]:
+    """Validate stepped workflow structure.
+
+    Returns:
+        (errors, warnings) — two lists of message strings.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+    agent_stems = _get_agent_stems(agents_dir)
+
+    agent = data.get("agent")
+    if not agent:
+        errors.append("Missing required field: agent")
+    else:
+        warnings.extend(_check_agent_ref(agent, agent_stems, "workflow"))
+
+    steps = data.get("steps")
+    if steps is None:
+        errors.append("Missing required field: steps")
+        return errors, warnings
+
+    if not isinstance(steps, dict):
+        errors.append("Field 'steps' must be a mapping")
+        return errors, warnings
+
+    if "path" not in steps:
+        errors.append("Missing required field: steps.path")
+
+    if "pattern" not in steps:
+        errors.append("Missing required field: steps.pattern")
+
+    return errors, warnings
+
+
+def validate_procedural(
+    data: dict, path: Path, agents_dir: Path
+) -> tuple[list[str], list[str]]:
+    """Validate procedural workflow structure.
+
+    Returns:
+        (errors, warnings) — two lists of message strings.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+    agent_stems = _get_agent_stems(agents_dir)
+
+    agent = data.get("agent")
+    if not agent:
+        errors.append("Missing required field: agent")
+    else:
+        warnings.extend(_check_agent_ref(agent, agent_stems, "workflow"))
+
+    if "instructions" not in data and "checklist" not in data:
+        warnings.append(
+            "Missing recommended field: instructions or checklist"
+        )
+
+    return errors, warnings
+
+
+def run(root: Path, *, fix: bool = False, strict: bool = False) -> ValidateReport:
+    """Validate all workflow definition files."""
+    report = ValidateReport(validator="workflow")
+    workflows_dir = root / "pennyfarthing-dist" / "workflows"
+
+    if not workflows_dir.is_dir():
+        report.details.append("[ERROR] workflows directory not found")
+        report.errors += 1
+        return report
+
+    agents_dir = root / "pennyfarthing-dist" / "agents"
+    files = discover_workflow_files(workflows_dir)
+
+    for path in files:
+        try:
+            content = path.read_text()
+            raw = yaml.safe_load(content)
+        except yaml.YAMLError:
+            report.errors += 1
+            report.details.append(f"[ERROR] {path.name}: YAML parse error")
+            continue
+
+        if not isinstance(raw, dict) or "workflow" not in raw:
+            report.errors += 1
+            report.details.append(
+                f"[ERROR] {path.name}: Missing 'workflow' top-level key"
+            )
+            continue
+
+        data = raw["workflow"]
+
+        if not isinstance(data, dict):
+            report.errors += 1
+            report.details.append(
+                f"[ERROR] {path.name}: 'workflow' must be a mapping"
+            )
+            continue
+
+        file_errors: list[str] = []
+        file_warnings: list[str] = []
+
+        # Common validation
+        common_errors, common_warnings = validate_common(data, path)
+        file_errors.extend(common_errors)
+        file_warnings.extend(common_warnings)
+
+        # Variant-specific validation
+        wtype = data.get("type", "phased")
+
+        if wtype == "phased":
+            variant_errors, variant_warnings = validate_phased(
+                data, path, agents_dir
+            )
+        elif wtype == "stepped":
+            variant_errors, variant_warnings = validate_stepped(
+                data, path, agents_dir
+            )
+        elif wtype == "procedural":
+            variant_errors, variant_warnings = validate_procedural(
+                data, path, agents_dir
+            )
+        else:
+            variant_errors, variant_warnings = [], []
+
+        file_errors.extend(variant_errors)
+        file_warnings.extend(variant_warnings)
+
+        # Determine display name (use parent/name for subdirectory workflows)
+        if path.name == "workflow.yaml":
+            display = f"{path.parent.name}/{path.name}"
+        else:
+            display = path.name
+
+        for e in file_errors:
+            report.errors += 1
+            report.details.append(f"[ERROR] {display}: {e}")
+
+        for w in file_warnings:
+            if strict:
+                report.errors += 1
+                report.details.append(f"[ERROR] {display}: {w}")
+            else:
+                report.warnings += 1
+                report.details.append(f"[WARN] {display}: {w}")
+
+        if not file_errors:
+            report.passed += 1
+
+    return report

package/pennyfarthing_scripts/validate/cli.py

@@ -0,0 +1,141 @@
+"""Validate CLI — top-level validation command.
+
+Usage:
+    pf validate              # Run all validators
+    pf validate sprint       # Sprint YAML only
+    pf validate schema       # XML schema only
+    pf validate --fix        # Auto-fix where supported
+    pf validate --strict     # Treat warnings as errors
+"""
+
+from __future__ import annotations
+
+import click
+
+from pennyfarthing_scripts.common.config import get_project_root
+from pennyfarthing_scripts.common.output import error, header, info, success, warn
+from pennyfarthing_scripts.validate import ValidateReport
+
+VALIDATORS = {
+    "sprint": "pennyfarthing_scripts.validate.adapters.sprint",
+    "schema": "pennyfarthing_scripts.validate.adapters.schema",
+    "agent": "pennyfarthing_scripts.validate.adapters.agent",
+    "workflow": "pennyfarthing_scripts.validate.adapters.workflow",
+    "skill-command": "pennyfarthing_scripts.validate.adapters.skill_command",
+}
+
+
+def _run_validator(name: str, *, fix: bool, strict: bool) -> ValidateReport:
+    """Run a single validator by name."""
+    import importlib
+
+    mod = importlib.import_module(VALIDATORS[name])
+    root = get_project_root()
+    return mod.run(root, fix=fix, strict=strict)
+
+
+def _print_reports(reports: list[ValidateReport]) -> None:
+    """Print validation reports with color output."""
+    for report in reports:
+        header(f"Validator: {report.validator}", char="-", width=50)
+
+        if report.details:
+            for line in report.details:
+                if "[ERROR]" in line or "[SYNTAX]" in line or "[SCHEMA]" in line:
+                    error(line)
+                elif "[WARN]" in line or "[FORMAT]" in line:
+                    warn(line)
+                else:
+                    click.echo(f"  {line}", err=True)
+
+        parts = [f"{report.passed} passed"]
+        if report.warnings:
+            parts.append(f"{report.warnings} warnings")
+        if report.errors:
+            parts.append(f"{report.errors} errors")
+        if report.fixed:
+            parts.append("(fixed)")
+
+        summary_line = ", ".join(parts)
+        if report.success:
+            success(f"{report.validator}: {summary_line}")
+        else:
+            error(f"{report.validator}: {summary_line}")
+
+    click.echo("", err=True)
+    total_errors = sum(r.errors for r in reports)
+    total_warnings = sum(r.warnings for r in reports)
+    total_passed = sum(r.passed for r in reports)
+
+    info(f"Total: {total_passed} passed, {total_warnings} warnings, {total_errors} errors")
+
+
+@click.group(invoke_without_command=True)
+@click.option("--fix", is_flag=True, help="Auto-fix format issues where supported")
+@click.option("--strict", is_flag=True, help="Treat warnings as errors")
+@click.pass_context
+def validate(ctx, fix: bool, strict: bool):
+    """Run project validators.
+
+    \b
+    With no subcommand, runs ALL validators.
+    Specify a validator name to run only that one.
+
+    \b
+    Validators:
+      sprint   - Sprint YAML (epics, initiatives, future, current-sprint)
+      schema   - XML schema (sessions, skills, workflow steps)
+      agent    - Agent definitions (required sections, model values, subagent refs)
+      workflow - Workflow definitions (phased/stepped/procedural structure)
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["fix"] = fix
+    ctx.obj["strict"] = strict
+
+    if ctx.invoked_subcommand is None:
+        reports = []
+        for name in VALIDATORS:
+            reports.append(_run_validator(name, fix=fix, strict=strict))
+        _print_reports(reports)
+        if any(not r.success for r in reports):
+            raise SystemExit(1)
+
+
+@validate.command("sprint")
+@click.pass_context
+def validate_sprint(ctx):
+    """Validate sprint YAML files (auto-discovers all files in sprint/)."""
+    report = _run_validator("sprint", fix=ctx.obj["fix"], strict=ctx.obj["strict"])
+    _print_reports([report])
+    if not report.success:
+        raise SystemExit(1)
+
+
+@validate.command("schema")
+@click.pass_context
+def validate_schema(ctx):
+    """Validate XML schema files (sessions, skills, workflow steps)."""
+    report = _run_validator("schema", fix=ctx.obj["fix"], strict=ctx.obj["strict"])
+    _print_reports([report])
+    if not report.success:
+        raise SystemExit(1)
+
+
+@validate.command("agent")
+@click.pass_context
+def validate_agent(ctx):
+    """Validate agent definition files (required sections, model values, refs)."""
+    report = _run_validator("agent", fix=ctx.obj["fix"], strict=ctx.obj["strict"])
+    _print_reports([report])
+    if not report.success:
+        raise SystemExit(1)
+
+
+@validate.command("workflow")
+@click.pass_context
+def validate_workflow(ctx):
+    """Validate workflow definitions (phased/stepped/procedural structure)."""
+    report = _run_validator("workflow", fix=ctx.obj["fix"], strict=ctx.obj["strict"])
+    _print_reports([report])
+    if not report.success:
+        raise SystemExit(1)

package/pennyfarthing_scripts/welcome_hook.py

@@ -22,12 +22,11 @@ sys.path.insert(0, str(Path(__file__).parent))
 
 from hooks import (
     find_project_root,
-    send_to_cyclist,
-    load_settings,
     is_cyclist_running,
+    load_settings,
+    send_to_cyclist,
 )
 
-
 # Once-per-session guard
 _welcome_shown_file: Path | None = None
 

package/pennyfarthing_scripts/workflow.py

@@ -12,8 +12,8 @@ Story: MSSCI-12416 - Define Scale Levels
 Epic: MSSCI-12415 - Scale Adaptation and Brownfield Support
 """
 
-from typing import Any
 import re
+from typing import Any
 
 # Scale level definitions with keywords, thresholds, and metadata
 SCALE_LEVELS: dict[int, dict[str, Any]] = {
@@ -32,7 +32,7 @@ SCALE_LEVELS: dict[int, dict[str, Any]] = {
         "keywords": ["simple", "basic", "small", "add", "minor"],
         "stories_min": 1,
         "stories_max": 10,
-        "workflow": "quick-spec",
+        "workflow": "prd",
         "artifacts": ["tech-spec"],
     },
     2: {
@@ -124,7 +124,7 @@ def get_workflow_for_scale_level(level: int) -> str:
         level: Scale level 0-4
 
     Returns:
-        Workflow name (trivial, quick-spec, or prd)
+        Workflow name (trivial or prd)
     """
     if level not in SCALE_LEVELS:
         return "prd"  # Safe default for unknown levels

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/agents/workflow-status-check.md

@@ -1,96 +0,0 @@
----
-name: workflow-status-check
-description: Determine workflow state using sprint scripts
-tools: Bash, Read
-model: haiku
----
-
-<info>
-Universal entry point telling agents: what work exists, what phase, and whether to activate.
-Uses `/sprint` skill scripts for deterministic output.
-</info>
-
-<arguments>
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `CALLING_AGENT` | Yes | Agent requesting status check (e.g., "SM", "Architect", "PM") |
-</arguments>
-
----
-
-## Execution
-
-Run the sprint status script and parse output:
-
-```bash
-pf sprint status
-```
-
-Then check for active sessions:
-
-```bash
-if ls .session/*-session.md 1>/dev/null 2>&1; then
-  for f in .session/*-session.md; do head -30 "$f"; done
-else
-  echo "No active sessions"
-fi
-```
-
----
-
-## State Determination
-
-| State | Condition |
-|-------|-----------|
-| `FINISH_STATE` | Session exists with Phase=approved OR Status=approved |
-| `IN_PROGRESS_STATE` | Phased workflow session with active phase (setup/red/green/implement/review) |
-| `STEPPED_WORKFLOW_STATE` | Stepped workflow session (workflow type = stepped) |
-| `NEW_WORK_STATE` | No sessions AND sprint has backlog/ready stories |
-| `EMPTY_BACKLOG_STATE` | No sessions AND sprint has NO backlog/ready stories |
-
-**Detecting workflow type from session:**
-```bash
-# Read workflow name from session
-WORKFLOW=$(grep '^\*\*Workflow:\*\*' .session/*-session.md | head -1 | sed 's/.*: //')
-# Check if stepped
-.pennyfarthing/scripts/workflow/get-workflow-type.sh "$WORKFLOW"
-```
-
-**Important:** Sprints are fixed two-week periods (kanban-style). Never suggest closing a sprint early or starting sprint planning when backlog is empty. The correct response to `EMPTY_BACKLOG_STATE` is to suggest promoting stories from `future.yaml`.
-
----
-
-<output>
-## Output Format
-
-Return a `STATUS_CHECK_RESULT` block:
-
-### Success
-```
-STATUS_CHECK_RESULT:
-  status: success
-  state: {FINISH_STATE|IN_PROGRESS_STATE|NEW_WORK_STATE|EMPTY_BACKLOG_STATE}
-  story_id: {ID or null}
-  phase: {current phase or null}
-  phase_owner: {agent name or null}
-  sprint_number: {N}
-  backlog_count: {N}
-
-  next_steps:
-    - FINISH_STATE: "Proceed to Finish Flow - spawn sm-finish with PHASE=preflight"
-    - IN_PROGRESS_STATE: "Report phase owner '{phase_owner}' should continue. Run handoff-marker.sh {phase_owner}"
-    - STEPPED_WORKFLOW_STATE: "Stepped workflow in progress. Tell user to run /workflow resume or /workflow status"
-    - NEW_WORK_STATE: "Present available stories to user. Await selection, then spawn sm-setup MODE=setup"
-    - EMPTY_BACKLOG_STATE: "Report backlog empty. Suggest promoting from future.yaml"
-```
-
-### Active Session Details (if IN_PROGRESS_STATE)
-```
-  session:
-    story_id: {ID}
-    title: "{title}"
-    workflow: {workflow}
-    phase: {phase}
-    branch: {branch}
-```
-</output>