@pennyfarthing/core 10.1.0 → 10.3.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

@@ -7,21 +7,15 @@
 | Script | Purpose |
 |--------|---------|
 | `deploy.sh` | Release Pennyfarthing (version bump, tag, push, GitHub release) |
-| `benchmark-runner.{sh,js}` | Run persona benchmarks |
-| `job-fair-*.sh` | Job Fair character evaluations |
-| `aggregate-benchmark-stats.{sh,js}` | Aggregate benchmark results |
-| `solo-runner.sh` | Run single agent on a scenario |
-| `parallel-benchmark.sh` | Parallel benchmark execution |
-| `consolidate-job-fair.sh` | Consolidate Job Fair results |
-| `convert-jobfair-to-benchmarks.sh` | Format conversion |
-| `generate-leaderboard.sh` | Build leaderboard from benchmarks |
-| `regenerate-summaries.sh` | Regenerate benchmark summaries |
 | `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
 
@@ -31,12 +25,6 @@ Run from pennyfarthing repo root:
 # Release a new version
 ./scripts/deploy.sh --dry-run patch
 ./scripts/deploy.sh patch
-
-# Run benchmarks
-./scripts/benchmark-runner.sh --theme mash --agent sm
-
-# Job Fair
-./scripts/job-fair-runner.sh mash
 ```
 
 ## Where Should My Script Go?

package/pennyfarthing-dist/commands/benchmark-control.md

@@ -1,69 +0,0 @@
----
-description: Create control baseline for a scenario (shortcut for /benchmark control <agent>)
-argument-hint: <agent> [--scenario <name>] [--runs N]
----
-
-# Benchmark Control
-
-<purpose>
-Shortcut to run `/benchmark` with the `control` theme. Creates or extends a control baseline for comparing other personas against.
-
-This is equivalent to running:
-```
-/benchmark control <agent> [--scenario <name>] [--runs N]
-```
-
-Default: 10 runs for statistically meaningful baseline data.
-</purpose>
-
-<critical-integrity-requirements>
-**See `/benchmark` for full integrity requirements.**
-
-Baselines are saved to `internal/results/baselines/{scenario}/{agent}/` with:
-- Individual runs in `runs/*.json` with proof-of-work
-- Summary statistics in `summary.yaml` (mean, std_dev, CI)
-- Timestamp validation (runs must take 30+ seconds each)
-
-Control theme runs must include all proof fields. NO FABRICATION.
-</critical-integrity-requirements>
-
-<usage>
-```
-# Pick scenario interactively
-/benchmark-control sm
-/benchmark-control reviewer
-
-# Specify scenario directly
-/benchmark-control reviewer --scenario order-service
-/benchmark-control dev --scenario tdd-shopping-cart --runs 15
-```
-
-**Arguments:**
-- `agent` - The agent role (e.g., `sm`, `dev`, `reviewer`, `architect`)
-- `--scenario` - (Optional) Scenario name. If omitted, shows matching scenarios.
-- `--runs N` - Number of runs (default: 10 for baselines, max: 20)
-</usage>
-
-<on-invoke>
-The user invoked this command with: $ARGUMENTS
-
-**This is a shortcut.** Translate the arguments and invoke `/benchmark`:
-
-1. Prepend `control` as the theme
-2. Pass through all other arguments
-
-**Examples:**
-- `/benchmark-control sm` → `/benchmark control sm` (runs control:sm)
-- `/benchmark-control reviewer --scenario order-service` → `/benchmark control reviewer --scenario order-service` (runs control:reviewer)
-- `/benchmark-control dev --runs 15` → `/benchmark control dev --runs 15` (runs control:dev)
-
-**Default runs override:** If `--runs` is not specified, default to 10 (instead of 4) since baselines need more data.
-
-Now execute the equivalent `/benchmark` command with the translated arguments.
-</on-invoke>
-
-<reference>
-- Main command: `.claude/project/commands/benchmark.md`
-- Baselines location: `internal/results/baselines/{scenario}/{role}/`
-- Results README: `internal/results/README.md`
-</reference>