@pennyfarthing/core 11.2.1 → 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/workflow/cli.py

@@ -16,6 +16,8 @@ Usage:
 
 from __future__ import annotations
 
+from datetime import UTC
+
 import click
 
 
@@ -141,7 +143,6 @@ def workflow_list_cmd():
 
     Shows a markdown table with type, phases/steps, modes, and descriptions.
     """
-    import yaml as yaml_mod
 
     from pennyfarthing_scripts.workflow.helpers import (
         count_steps,
@@ -353,7 +354,7 @@ def workflow_start_cmd(name: str, mode: str | None):
     Arguments:
       NAME  - Workflow name (e.g., architecture, release)
     """
-    from datetime import datetime, timezone
+    from datetime import datetime
 
     from pennyfarthing_scripts.common.config import get_project_root
     from pennyfarthing_scripts.workflow.helpers import (
@@ -444,7 +445,7 @@ def workflow_start_cmd(name: str, mode: str | None):
         return
 
     # Create session file
-    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    now = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
     wf_agent = wf.get("agent", "pm")
     wf_desc = wf.get("description", "-")
 
@@ -516,7 +517,7 @@ def workflow_resume_cmd(name: str | None):
     Arguments:
       NAME  - Workflow name (auto-detects from active session if omitted)
     """
-    from datetime import datetime, timezone
+    from datetime import datetime
 
     from pennyfarthing_scripts.common.config import get_project_root
     from pennyfarthing_scripts.workflow.helpers import (
@@ -601,7 +602,7 @@ def workflow_resume_cmd(name: str | None):
         raise SystemExit(1)
 
     # Update last updated timestamp
-    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    now = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
     import re
 
     updated_content = re.sub(
@@ -788,7 +789,7 @@ def workflow_fix_phase_cmd(story_id: str, target_phase: str, dry_run: bool):
       TARGET_PHASE  - Target phase to set (e.g., review, approved, finish)
     """
     import re
-    from datetime import datetime, timezone
+    from datetime import datetime
 
     from pennyfarthing_scripts.common.config import get_project_root
     from pennyfarthing_scripts.workflow.helpers import (
@@ -849,17 +850,17 @@ def workflow_fix_phase_cmd(story_id: str, target_phase: str, dry_run: bool):
     # Find indices
     try:
         current_idx = phases.index(current_phase)
-    except ValueError:
+    except ValueError as err:
         click.echo(f"Error: Current phase '{current_phase}' not found in {workflow_name} workflow", err=True)
         click.echo(f"Valid phases: {', '.join(phases)}", err=True)
-        raise SystemExit(1)
+        raise SystemExit(1) from err
 
     try:
         target_idx = phases.index(target_phase)
-    except ValueError:
+    except ValueError as err:
         click.echo(f"Error: Target phase '{target_phase}' not found in {workflow_name} workflow", err=True)
         click.echo(f"Valid phases: {', '.join(phases)}", err=True)
-        raise SystemExit(1)
+        raise SystemExit(1) from err
 
     if target_idx <= current_idx:
         click.echo(f"Error: Target phase '{target_phase}' is not ahead of current phase '{current_phase}'", err=True)
@@ -867,7 +868,7 @@ def workflow_fix_phase_cmd(story_id: str, target_phase: str, dry_run: bool):
         raise SystemExit(1)
 
     # Calculate transitions
-    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    now = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
     click.echo("")
     click.echo("Transitions needed:")
 
@@ -909,7 +910,7 @@ def workflow_fix_phase_cmd(story_id: str, target_phase: str, dry_run: bool):
 
     # Build handoff history additions
     handoff_lines = []
-    for from_phase, to_phase, from_agent, to_agent, gate in transitions:
+    for _from_phase, _to_phase, from_agent, to_agent, gate in transitions:
         handoff_lines.append(f"| {from_agent} | {to_agent} | {gate} | PASSED | {now} |")
 
     # Insert handoff rows after the last PASSED/FAILED row
@@ -951,7 +952,7 @@ def workflow_complete_step_cmd(name: str | None, step_override: int | None):
       NAME  - Workflow name (auto-detects from session if omitted)
     """
     import re
-    from datetime import datetime, timezone
+    from datetime import datetime
 
     from pennyfarthing_scripts.common.config import get_project_root
     from pennyfarthing_scripts.workflow.helpers import (
@@ -1036,7 +1037,7 @@ def workflow_complete_step_cmd(name: str | None, step_override: int | None):
     new_status = "completed" if completed_count >= step_count else "in_progress"
 
     # Update session file
-    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    now = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
 
     content = re.sub(
         r"^- \*\*Current Step:\*\*.*$",

package/pennyfarthing_scripts/workflow/state.py

@@ -7,7 +7,6 @@ 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] = {

package/pennyfarthing_scripts/workflow/team_lifecycle.py

@@ -10,11 +10,10 @@ Python port of packages/core/dist/workflow/team-lifecycle.js.
 
 from __future__ import annotations
 
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
 
-
 # =============================================================================
 # In-memory registries
 # =============================================================================
@@ -61,7 +60,7 @@ async def create_team(
         "storyId": story_id,
         "phase": phase["name"],
         "teammates": [],
-        "createdAt": datetime.now(timezone.utc).isoformat(),
+        "createdAt": datetime.now(UTC).isoformat(),
     }
 
     if adapter:
@@ -213,7 +212,7 @@ def acquire_sidecar_lock(
     lock: dict[str, Any] = {
         "lockPath": f"{file_path}.lock",
         "storyId": story_id,
-        "acquiredAt": datetime.now(timezone.utc).isoformat(),
+        "acquiredAt": datetime.now(UTC).isoformat(),
     }
     _sidecar_locks[file_path] = lock
     return {"success": True, "data": lock}