@pennyfarthing/core 11.2.0 → 11.2.2

package/pennyfarthing_scripts/tests/test_workflow_list_team.py

@@ -0,0 +1,147 @@
+"""Tests for Story 86-15 AC4: workflow list shows team-enabled workflows with indicator.
+
+Story: 86-15 — Team-enabled workflow templates
+Epic: 86 — Agent Collaboration: Tandem to Teams
+
+Acceptance Criteria:
+- [AC4] /workflow list shows team-enabled workflows with indicator
+
+The `pf workflow list` command should visually distinguish team-enabled
+workflows from regular and tandem workflows. When a workflow has `team:`
+blocks on any phase, the output must include an indicator.
+
+These tests verify the CLI output format. Tests should fail until
+both the workflow templates (tdd-team.yaml, bdd-team.yaml) and the
+workflow list team indicator are implemented.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+import yaml
+from click.testing import CliRunner
+
+from pennyfarthing_scripts.cli import cli
+
+
+class TestWorkflowListTeamIndicator:
+    """Tests for team indicator in workflow list output (AC4)."""
+
+    @pytest.fixture
+    def runner(self) -> CliRunner:
+        return CliRunner()
+
+    def test_workflow_list_shows_team_workflows(self, runner: CliRunner) -> None:
+        """AC4: workflow list should include tdd-team and bdd-team."""
+        result = runner.invoke(cli, ["workflow", "list"])
+        assert result.exit_code == 0
+        assert "tdd-team" in result.output, "tdd-team workflow should appear in list"
+        assert "bdd-team" in result.output, "bdd-team workflow should appear in list"
+
+    def test_workflow_list_has_team_indicator_for_tdd_team(
+        self, runner: CliRunner
+    ) -> None:
+        """AC4: tdd-team should have a team indicator in workflow list."""
+        result = runner.invoke(cli, ["workflow", "list"])
+        assert result.exit_code == 0
+
+        # Find the tdd-team row in the markdown table
+        tdd_team_line = None
+        for line in result.output.splitlines():
+            if "tdd-team" in line and "|" in line:
+                tdd_team_line = line
+                break
+
+        assert tdd_team_line is not None, "tdd-team should appear as a table row"
+
+        # The row should have a team indicator — could be a column value,
+        # emoji, or tag that distinguishes it from non-team workflows
+        line_lower = tdd_team_line.lower()
+        assert (
+            "team" in line_lower
+        ), "tdd-team row should contain a 'team' indicator"
+
+    def test_workflow_list_has_team_indicator_for_bdd_team(
+        self, runner: CliRunner
+    ) -> None:
+        """AC4: bdd-team should have a team indicator in workflow list."""
+        result = runner.invoke(cli, ["workflow", "list"])
+        assert result.exit_code == 0
+
+        bdd_team_line = None
+        for line in result.output.splitlines():
+            if "bdd-team" in line and "|" in line:
+                bdd_team_line = line
+                break
+
+        assert bdd_team_line is not None, "bdd-team should appear as a table row"
+
+        line_lower = bdd_team_line.lower()
+        assert (
+            "team" in line_lower
+        ), "bdd-team row should contain a 'team' indicator"
+
+    def test_non_team_workflows_lack_team_indicator(
+        self, runner: CliRunner
+    ) -> None:
+        """AC4: Regular workflows should NOT have team indicator."""
+        result = runner.invoke(cli, ["workflow", "list"])
+        assert result.exit_code == 0
+
+        for line in result.output.splitlines():
+            if "|" not in line:
+                continue
+            # Skip header, separator, and team workflows
+            if "tdd-team" in line or "bdd-team" in line:
+                continue
+            if "Workflow" in line or "---" in line:
+                continue
+
+            # Check columns (split by |)
+            cols = [c.strip() for c in line.split("|")]
+            name_col = cols[1] if len(cols) > 1 else ""
+
+            # tdd-tandem and bdd-tandem are tandem, not team
+            if "tandem" in name_col:
+                continue
+
+            # Plain workflows like tdd, trivial, bdd should not show team
+            # in their mode/indicator columns (but "team" might appear
+            # in description text, which is fine — we check indicator columns)
+            # The name itself (e.g., "tdd") doesn't contain "team", confirming
+            # no false positives in the name column
+
+
+class TestWorkflowListTeamColumnOrTag:
+    """Verify the team indicator mechanism in workflow list."""
+
+    @pytest.fixture
+    def runner(self) -> CliRunner:
+        return CliRunner()
+
+    def test_workflow_list_distinguishes_team_from_tandem(
+        self, runner: CliRunner
+    ) -> None:
+        """Team workflows should be distinguishable from tandem workflows."""
+        result = runner.invoke(cli, ["workflow", "list"])
+        assert result.exit_code == 0
+
+        tdd_team_line = None
+        tdd_tandem_line = None
+        for line in result.output.splitlines():
+            if "tdd-team" in line and "|" in line:
+                tdd_team_line = line
+            elif "tdd-tandem" in line and "|" in line:
+                tdd_tandem_line = line
+
+        assert tdd_team_line is not None, "tdd-team should be in the list"
+        assert tdd_tandem_line is not None, "tdd-tandem should be in the list"
+
+        # They should have different indicators — team vs tandem
+        # At minimum, the descriptions should be distinct
+        assert tdd_team_line != tdd_tandem_line, (
+            "tdd-team and tdd-tandem should have different rows"
+        )

package/pennyfarthing_scripts/validate/adapters/team_mode.py

@@ -0,0 +1,323 @@
+"""Team-mode protocol validator adapter.
+
+Validates that agent definitions include proper team-mode sections
+for Claude Code native Agent Teams integration.
+
+Story: MSSCI-15109 (86-14)
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from pennyfarthing_scripts.validate import ValidateReport
+
+# Regex to extract <team-mode> section content
+_TEAM_MODE_RE = re.compile(r"<team-mode>(.*?)</team-mode>", re.DOTALL)
+
+# Required topics in the behavior guide's <team-mode> section
+_BEHAVIOR_GUIDE_TOPICS = {
+    "team_creation": ["TeamCreate", "team creation", "create team"],
+    "spawning": ["spawn", "Task tool", "teammate"],
+    "sendmessage": ["SendMessage"],
+    "cleanup": ["cleanup", "TeamDelete", "shut down", "shutdown"],
+}
+
+# Required lead agent topics
+_LEAD_TOPICS = {
+    "phase_entry": ["phase entry", "phase start", "on phase"],
+    "spawn_per_yaml": ["spawn", "teammates", "workflow YAML", "YAML"],
+    "shutdown_before_exit": ["shut down", "shutdown", "before exit", "before handoff"],
+}
+
+# Required teammate awareness topics
+_TEAMMATE_TOPICS = {
+    "identity": ["teammate", "not lead", "not the lead"],
+    "sendmessage": ["SendMessage"],
+    "idle": ["idle", "go idle"],
+    "shutdown_response": ["shutdown", "shutdown_response", "shutdown request"],
+}
+
+
+def extract_team_mode_section(content: str) -> str | None:
+    """Extract content between <team-mode> tags."""
+    m = _TEAM_MODE_RE.search(content)
+    return m.group(1) if m else None
+
+
+def validate_behavior_guide_team_mode(
+    path: Path,
+) -> tuple[list[str], list[str]]:
+    """Validate the behavior guide has a <team-mode> section with required topics.
+
+    Returns:
+        (errors, warnings) — two lists of message strings.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+    content = path.read_text()
+    section = extract_team_mode_section(content)
+
+    if section is None:
+        errors.append("Missing <team-mode> section in behavior guide")
+        return errors, warnings
+
+    stripped = section.strip()
+    if not stripped:
+        errors.append("Empty <team-mode> section — no content")
+        return errors, warnings
+
+    # Check required topics
+    for topic_name, keywords in _BEHAVIOR_GUIDE_TOPICS.items():
+        if not any(kw.lower() in section.lower() for kw in keywords):
+            errors.append(
+                f"<team-mode> section missing required topic: {topic_name} "
+                f"(expected one of: {', '.join(keywords)})"
+            )
+
+    return errors, warnings
+
+
+def validate_lead_agent_team_mode(
+    path: Path,
+) -> tuple[list[str], list[str]]:
+    """Validate lead agent has team-mode behavior section.
+
+    Returns:
+        (errors, warnings) — two lists of message strings.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+    content = path.read_text()
+    section = extract_team_mode_section(content)
+
+    if section is None:
+        errors.append(f"Missing <team-mode> section in lead agent {path.name}")
+        return errors, warnings
+
+    stripped = section.strip()
+    if not stripped:
+        errors.append(f"Empty <team-mode> section in lead agent {path.name}")
+        return errors, warnings
+
+    section_lower = section.lower()
+
+    # Must reference lead role
+    if "lead" not in section_lower:
+        errors.append("Lead agent <team-mode> section must reference 'lead' role")
+
+    # Check lead-specific topics
+    for topic_name, keywords in _LEAD_TOPICS.items():
+        if not any(kw.lower() in section_lower for kw in keywords):
+            warnings.append(
+                f"Lead agent <team-mode> missing topic: {topic_name} "
+                f"(expected one of: {', '.join(keywords)})"
+            )
+
+    return errors, warnings
+
+
+def validate_teammate_awareness(
+    content: str,
+) -> tuple[list[str], list[str]]:
+    """Validate teammate behavior content in team-mode section.
+
+    Returns:
+        (errors, warnings) — two lists of message strings.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+    section = extract_team_mode_section(content)
+
+    if section is None:
+        errors.append("Missing <team-mode> section for teammate awareness")
+        return errors, warnings
+
+    section_lower = section.lower()
+
+    # Check teammate-specific topics
+    for topic_name, keywords in _TEAMMATE_TOPICS.items():
+        if not any(kw.lower() in section_lower for kw in keywords):
+            errors.append(
+                f"Teammate awareness missing topic: {topic_name} "
+                f"(expected one of: {', '.join(keywords)})"
+            )
+
+    return errors, warnings
+
+
+def validate_exit_protocol_team_branch(
+    content: str,
+) -> tuple[list[str], list[str]]:
+    """Validate exit protocol has team-mode cleanup branch.
+
+    Returns:
+        (errors, warnings) — two lists of message strings.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    # Look for team cleanup in exit protocol section
+    # The exit protocol is in <agent-exit-protocol> tags
+    exit_re = re.compile(
+        r"<agent-exit-protocol>(.*?)</agent-exit-protocol>", re.DOTALL
+    )
+    exit_match = exit_re.search(content)
+
+    if exit_match is None:
+        errors.append("Missing <agent-exit-protocol> section")
+        return errors, warnings
+
+    exit_content = exit_match.group(1).lower()
+
+    # Must reference team cleanup
+    team_cleanup_terms = ["team", "teamdelete", "cleanup team", "shut down teammate"]
+    if not any(term in exit_content for term in team_cleanup_terms):
+        errors.append(
+            "Exit protocol missing team-mode branch "
+            "(must reference team cleanup before handoff)"
+        )
+
+    return errors, warnings
+
+
+def validate_communication_protocols(
+    content: str,
+) -> tuple[list[str], list[str]]:
+    """Validate that reflector markers and SendMessage are properly documented.
+
+    Reflector markers for inter-phase handoff (unchanged).
+    SendMessage for intra-phase teammate communication (new).
+
+    Returns:
+        (errors, warnings) — two lists of message strings.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    # Reflector section must still exist
+    if "<critical>" not in content or "CYCLIST" not in content:
+        errors.append("Reflector/CYCLIST marker section missing — must remain for inter-phase handoff")
+
+    # Team-mode section must reference SendMessage for intra-phase
+    section = extract_team_mode_section(content)
+    if section is not None:
+        if "SendMessage" not in section:
+            errors.append(
+                "<team-mode> must reference SendMessage for intra-phase communication"
+            )
+        # Should distinguish inter-phase (markers) from intra-phase (SendMessage)
+        if "inter-phase" not in section.lower() and "intra-phase" not in section.lower():
+            warnings.append(
+                "<team-mode> should distinguish inter-phase (markers) "
+                "from intra-phase (SendMessage) communication"
+            )
+
+    return errors, warnings
+
+
+def classify_team_mode_agents(
+    agents_dir: Path,
+) -> tuple[list[Path], list[Path]]:
+    """Classify agent files into lead agents and all agents with team-mode.
+
+    Lead agents are those whose <team-mode> section mentions 'lead'.
+
+    Returns:
+        (lead_agents, all_team_mode_agents)
+    """
+    leads: list[Path] = []
+    all_tm: list[Path] = []
+
+    for f in sorted(agents_dir.glob("*.md")):
+        if f.name == "README.md":
+            continue
+
+        content = f.read_text()
+        section = extract_team_mode_section(content)
+        if section is None:
+            continue
+
+        all_tm.append(f)
+        if "lead" in section.lower():
+            leads.append(f)
+
+    return leads, all_tm
+
+
+def run(
+    root: Path, *, fix: bool = False, strict: bool = False
+) -> ValidateReport:
+    """Validate agent team-mode protocol sections."""
+    report = ValidateReport(validator="team-mode")
+
+    # Validate behavior guide
+    guides_dir = root / "pennyfarthing-dist" / "guides"
+    behavior_guide = guides_dir / "agent-behavior.md"
+    if behavior_guide.is_file():
+        file_errors, file_warnings = validate_behavior_guide_team_mode(behavior_guide)
+        for e in file_errors:
+            report.errors += 1
+            report.details.append(f"[ERROR] agent-behavior.md: {e}")
+        for w in file_warnings:
+            if strict:
+                report.errors += 1
+                report.details.append(f"[ERROR] agent-behavior.md: {w}")
+            else:
+                report.warnings += 1
+                report.details.append(f"[WARN] agent-behavior.md: {w}")
+        if not file_errors:
+            report.passed += 1
+
+        # Validate exit protocol team branch
+        guide_content = behavior_guide.read_text()
+        exit_errors, exit_warnings = validate_exit_protocol_team_branch(guide_content)
+        for e in exit_errors:
+            report.errors += 1
+            report.details.append(f"[ERROR] agent-behavior.md exit: {e}")
+        for w in exit_warnings:
+            if strict:
+                report.errors += 1
+                report.details.append(f"[ERROR] agent-behavior.md exit: {w}")
+            else:
+                report.warnings += 1
+                report.details.append(f"[WARN] agent-behavior.md exit: {w}")
+
+        # Validate communication protocol distinction
+        comm_errors, comm_warnings = validate_communication_protocols(guide_content)
+        for e in comm_errors:
+            report.errors += 1
+            report.details.append(f"[ERROR] agent-behavior.md comm: {e}")
+        for w in comm_warnings:
+            if strict:
+                report.errors += 1
+                report.details.append(f"[ERROR] agent-behavior.md comm: {w}")
+            else:
+                report.warnings += 1
+                report.details.append(f"[WARN] agent-behavior.md comm: {w}")
+    else:
+        report.errors += 1
+        report.details.append("[ERROR] agent-behavior.md guide not found")
+
+    # Validate lead agents
+    agents_dir = root / "pennyfarthing-dist" / "agents"
+    if agents_dir.is_dir():
+        for agent_name in ("dev", "reviewer"):
+            agent_path = agents_dir / f"{agent_name}.md"
+            if agent_path.is_file():
+                lead_errors, lead_warnings = validate_lead_agent_team_mode(agent_path)
+                for e in lead_errors:
+                    report.errors += 1
+                    report.details.append(f"[ERROR] {agent_name}.md: {e}")
+                for w in lead_warnings:
+                    if strict:
+                        report.errors += 1
+                        report.details.append(f"[ERROR] {agent_name}.md: {w}")
+                    else:
+                        report.warnings += 1
+                        report.details.append(f"[WARN] {agent_name}.md: {w}")
+                if not lead_errors:
+                    report.passed += 1
+
+    return report

package/pennyfarthing_scripts/validate/adapters/workflow.py

@@ -131,6 +131,7 @@ def validate_phased(
         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):
@@ -228,6 +229,24 @@ def validate_phased(
                         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
 
 

package/pennyfarthing_scripts/welcome_hook.py

@@ -1,156 +1,10 @@
-#!/usr/bin/env python3
 """
-Welcome Hook (Python)
+Backward-compatibility shim — welcome hook moved to hooks/session_start.py.
 
-Display a friendly welcome message on session start.
-
-For CLI: Displays ASCII art of a penny-farthing bicycle
-For Cyclist: Sends WebSocket message to display logo and welcome
-
-Called by Claude Code SessionStart hook.
-
-Story: MSSCI-12409 - Hook consistency and WheelHub consolidation
+This file will be removed in a future version.
 """
 
-import json
-import os
-import sys
-from pathlib import Path
-
-# Add parent directory to path for imports
-sys.path.insert(0, str(Path(__file__).parent))
-
-from hooks import (
-    find_project_root,
-    is_cyclist_running,
-    load_settings,
-    send_to_cyclist,
-)
-
-# Once-per-session guard
-_welcome_shown_file: Path | None = None
-
-
-def get_welcome_lock_path(project_root: Path) -> Path:
-    """Get path to welcome shown lock file."""
-    session_id = os.environ.get("CLAUDE_SESSION_ID", str(os.getpid()))
-    session_dir = project_root / ".session"
-    session_dir.mkdir(parents=True, exist_ok=True)
-    return session_dir / f".welcome-shown-{session_id}"
-
-
-def was_welcome_shown(project_root: Path) -> bool:
-    """Check if welcome was already shown for this session."""
-    lock_path = get_welcome_lock_path(project_root)
-    return lock_path.exists()
-
-
-def mark_welcome_shown(project_root: Path) -> None:
-    """Mark welcome as shown for this session."""
-    lock_path = get_welcome_lock_path(project_root)
-    lock_path.touch()
-
-
-def get_project_name(project_root: Path) -> str:
-    """Get project name from package.json or directory name."""
-    package_json = project_root / "package.json"
-    if package_json.exists():
-        try:
-            with open(package_json) as f:
-                data = json.load(f)
-                name = data.get("name")
-                if name:
-                    return name
-        except (json.JSONDecodeError, OSError):
-            pass
-
-    return project_root.name
-
-
-def get_theme(project_root: Path) -> str | None:
-    """Get current theme from settings."""
-    settings = load_settings(project_root)
-    return settings.theme
-
-
-def display_cli_welcome(project_name: str, theme: str | None) -> None:
-    """Display ASCII art welcome for CLI mode."""
-    print("""
-       ___
-      /   \\
-     |     |     Welcome to
-     |     |    ╔═══════════════════════════════════╗
-      \\___/     ║   ╔═╗╔═╗╔╗╔╔╗╔╦═╗╔═╗╔═╗╔═╗╦╔═╗   ║
-        ║       ║   ╠═╝║╣ ║║║║║║ ╠╣ ╠═╣╠╦╝ ║ ╠═╣   ║
-        ║       ║   ╩  ╚═╝╝╚╝╝╚╝╩  ╩ ╩╩╚═ ╩ ╩ ╩   ║
-      ╔═╩═╗     ╚═══════════════════════════════════╝
-     /     \\
-    │   O   │   Agent-powered development with style
-     \\     /
-      ╚═══╝
-""")
-
-    if project_name:
-        print(f"    Project: {project_name}")
-    if theme:
-        print(f"    Theme:   {theme}")
-    print()
-
-
-def send_cyclist_welcome(project_root: Path, project_name: str, theme: str | None) -> None:
-    """Send welcome message to Cyclist via WebSocket API."""
-    try:
-        send_to_cyclist(
-            endpoint="/api/welcome",
-            data={
-                "project": project_name or "",
-                "theme": theme or "",
-            },
-            project_root=project_root,
-            timeout=5,
-        )
-    except Exception:
-        # Ignore errors - don't block hook
-        pass
-
-
-def main() -> None:
-    """Main entry point for SessionStart welcome hook."""
-    try:
-        # Read and discard stdin (required by hook protocol)
-        sys.stdin.read()
-
-        # Find project root
-        project_root = find_project_root()
-        if not project_root:
-            sys.exit(0)
-
-        # Check if welcome was already shown for this session
-        if was_welcome_shown(project_root):
-            sys.exit(0)
-
-        # Mark welcome as shown
-        mark_welcome_shown(project_root)
-
-        # Get project info
-        project_name = get_project_name(project_root)
-        theme = get_theme(project_root)
-
-        # Check if running in Cyclist
-        if is_cyclist_running(project_root):
-            # Send welcome via WebSocket API
-            send_cyclist_welcome(project_root, project_name, theme)
-        else:
-            # CLI mode - display ASCII art
-            display_cli_welcome(project_name, theme)
-
-        sys.exit(0)
-
-    except Exception as e:
-        # On error, exit silently
-        print(f"[welcome-hook] Error: {e}", file=sys.stderr)
-        sys.exit(0)
-
+from pennyfarthing_scripts.hooks.session_start import main  # noqa: F401
 
 if __name__ == "__main__":
     main()