@pennyfarthing/core 11.3.3 → 11.3.4

package/pennyfarthing-dist/pf/validate/adapters/workflow.py

@@ -0,0 +1,403 @@
+"""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 pf.validate import ValidateReport
+
+# Known workflow types
+VALID_TYPES = {"phased", "stepped", "procedural"}
+
+# Known tandem modes for phase tandem blocks
+VALID_TANDEM_MODES = {"consultation"}
+
+# Valid model values for tandem partner spawning
+VALID_TANDEM_MODELS = {"sonnet", "haiku"}
+
+# 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()
+    next_refs: list[tuple[str, str]] = []  # (phase_name, next_target)
+
+    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}'"
+                )
+
+        # Tandem validation
+        tandem = phase.get("tandem")
+        if tandem is not None:
+            label = phase_name or i
+            if not isinstance(tandem, dict):
+                errors.append(
+                    f"Phase '{label}' tandem must be a mapping"
+                )
+            else:
+                # partner is required
+                partner = tandem.get("partner")
+                if not partner:
+                    errors.append(
+                        f"Phase '{label}' tandem missing required field: partner"
+                    )
+                else:
+                    # Cross-reference partner against known agents
+                    warnings.extend(
+                        _check_agent_ref(
+                            partner, agent_stems, f"phase '{label}' tandem partner"
+                        )
+                    )
+
+                # mode validation (optional for backward compat)
+                mode = tandem.get("mode")
+                if mode is not None and mode not in VALID_TANDEM_MODES:
+                    errors.append(
+                        f"Phase '{label}' tandem has invalid mode: '{mode}' "
+                        f"(must be one of: {', '.join(sorted(VALID_TANDEM_MODES))})"
+                    )
+
+                # model validation (optional)
+                model = tandem.get("model")
+                if model is not None and model not in VALID_TANDEM_MODELS:
+                    warnings.append(
+                        f"Phase '{label}' tandem has unknown model: '{model}' "
+                        f"(expected one of: {', '.join(sorted(VALID_TANDEM_MODELS))})"
+                    )
+
+                # token_budget validation (must be positive integer)
+                token_budget = tandem.get("token_budget")
+                if token_budget is not None:
+                    if not isinstance(token_budget, int) or isinstance(token_budget, bool):
+                        errors.append(
+                            f"Phase '{label}' tandem token_budget must be a positive integer"
+                        )
+                    elif token_budget <= 0:
+                        errors.append(
+                            f"Phase '{label}' tandem token_budget must be a positive integer"
+                        )
+
+                # triggers validation (must be list)
+                triggers = tandem.get("triggers")
+                if triggers is not None and not isinstance(triggers, list):
+                    errors.append(
+                        f"Phase '{label}' tandem triggers must be a list"
+                    )
+
+        # next: directive (optional, must be string)
+        next_target = phase.get("next")
+        if next_target is not None:
+            if not isinstance(next_target, str):
+                errors.append(
+                    f"Phase '{phase_name or i}' next must be a string"
+                )
+            elif phase_name:
+                next_refs.append((phase_name, next_target))
+
+    # Cross-validate next: references point to existing phase names
+    for source_phase, target_phase in next_refs:
+        if target_phase not in seen_names:
+            errors.append(
+                f"Phase '{source_phase}' next references unknown phase: "
+                f"'{target_phase}'"
+            )
+
+    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-dist/pf/validate/cli.py

@@ -0,0 +1,164 @@
+"""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 pf.common.config import get_project_root
+from pf.common.output import error, header, info, success, warn
+from pf.validate import ValidateReport
+
+VALIDATORS = {
+    "sprint": "pf.validate.adapters.sprint",
+    "schema": "pf.validate.adapters.schema",
+    "agent": "pf.validate.adapters.agent",
+    "workflow": "pf.validate.adapters.workflow",
+    "skill-command": "pf.validate.adapters.skill_command",
+    "tandem-awareness": "pf.validate.adapters.tandem_awareness",
+}
+
+
+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)
+      skill-command      - Skill registry and command files (prefix, deprecated, cross-ref)
+      tandem-awareness   - Agent tandem consultation sections (ADR-0012 pairings)
+    """
+    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)
+
+
+@validate.command("skill-command")
+@click.pass_context
+def validate_skill_command(ctx):
+    """Validate skill registry and command files (prefix, deprecated, cross-ref)."""
+    report = _run_validator("skill-command", fix=ctx.obj["fix"], strict=ctx.obj["strict"])
+    _print_reports([report])
+    if not report.success:
+        raise SystemExit(1)
+
+
+@validate.command("tandem-awareness")
+@click.pass_context
+def validate_tandem_awareness(ctx):
+    """Validate agent tandem consultation sections (ADR-0012 pairings, roles)."""
+    report = _run_validator("tandem-awareness", fix=ctx.obj["fix"], strict=ctx.obj["strict"])
+    _print_reports([report])
+    if not report.success:
+        raise SystemExit(1)

package/pennyfarthing-dist/pf/welcome_hook.py

@@ -0,0 +1,10 @@
+"""
+Backward-compatibility shim — welcome hook moved to hooks/session_start.py.
+
+This file will be removed in a future version.
+"""
+
+from pf.hooks.session_start import main  # noqa: F401
+
+if __name__ == "__main__":
+    main()

package/pennyfarthing-dist/pf/workflow/__init__.py

@@ -0,0 +1,40 @@
+"""
+Workflow package — scale levels, phase ownership, and workflow CLI commands.
+
+Re-exports all public symbols for backward compatibility with
+`from pf.workflow import ...`.
+"""
+
+from pf.workflow.scale import (
+    SCALE_LEVELS,
+    detect_scale_level,
+    determine_scale_level,
+    get_required_artifacts,
+    get_scale_level_info,
+    get_workflow_for_scale_level,
+    scale_level_from_story_count,
+)
+from pf.workflow.state import (
+    TDD_PHASE_OWNERS,
+    TRIVIAL_PHASE_OWNERS,
+    WORKFLOW_PHASES,
+    get_phase_owner,
+    get_workflow_state,
+)
+
+__all__ = [
+    # Scale
+    "SCALE_LEVELS",
+    "detect_scale_level",
+    "determine_scale_level",
+    "get_required_artifacts",
+    "get_scale_level_info",
+    "get_workflow_for_scale_level",
+    "scale_level_from_story_count",
+    # State
+    "TDD_PHASE_OWNERS",
+    "TRIVIAL_PHASE_OWNERS",
+    "WORKFLOW_PHASES",
+    "get_phase_owner",
+    "get_workflow_state",
+]