@pennyfarthing/core 11.1.0 → 11.2.0

package/pennyfarthing_scripts/tests/test_handoff_cli.py

@@ -295,21 +295,26 @@ class TestResolveGateReady:
 
 
 class TestResolveGateBlocked:
-    """AC1 + AC5: resolve-gate returns 'blocked' when no assessment."""
+    """AC1 + AC5: resolve-gate no longer blocks on missing assessment.
 
-    def test_missing_assessment_returns_blocked(
+    Assessment guard moved to complete_phase to prevent race conditions
+    where agents call resolve-gate before writing their assessment.
+    """
+
+    def test_missing_assessment_resolve_gate_still_ready(
         self, project: Path, session_without_assessment: Path
     ) -> None:
-        """AC1: Missing assessment section → status: blocked."""
+        """resolve-gate returns ready regardless of assessment (guard moved to complete-phase)."""
         result = resolve_gate("105-1", "tdd", "green", project_root=project)
-        assert result["status"] == "blocked"
+        assert result["status"] == "ready"
 
-    def test_blocked_has_assessment_found_false(
+    def test_missing_assessment_complete_phase_blocks(
         self, project: Path, session_without_assessment: Path
     ) -> None:
-        """AC1: Blocked result should have assessment_found: False."""
-        result = resolve_gate("105-1", "tdd", "green", project_root=project)
-        assert result["assessment_found"] is False
+        """complete-phase blocks when no assessment found in session file."""
+        result = complete_phase("105-1", "tdd", "green", "review", "tests_pass", project)
+        assert result["status"] == "error"
+        assert "assessment" in result["error"].lower()
 
     def test_blocked_exit_code_one(self, runner: CliRunner) -> None:
         """AC5: Exit code 1 when gate resolves to blocked."""
@@ -383,10 +388,10 @@ class TestResolveGateErrors:
         result = resolve_gate("105-1", "tdd", "nonexistent", project_root=project)
         assert result["status"] == "error" or result.get("error") is not None
 
-    def test_missing_session_file_returns_blocked(self, project: Path) -> None:
-        """AC1: No session file → blocked (can't check assessment)."""
+    def test_missing_session_file_resolve_gate_ready(self, project: Path) -> None:
+        """resolve-gate returns ready even without session file (guard moved to complete-phase)."""
         result = resolve_gate("105-1", "tdd", "green", project_root=project)
-        assert result["status"] in ("blocked", "error")
+        assert result["status"] == "ready"
 
 
 class TestResolveGateOutputContract:

package/pennyfarthing_scripts/tests/test_workflow_check.py

@@ -24,9 +24,8 @@ from click.testing import CliRunner
 from pennyfarthing_scripts.cli import cli
 from pennyfarthing_scripts.workflow import get_workflow_state
 
-# Mock path: since cli.py does `from pennyfarthing_scripts.workflow import get_workflow_state`
-# inside the command function, we mock at the source module
-MOCK_PATH = "pennyfarthing_scripts.workflow.get_workflow_state"
+# Mock path: workflow.cli imports from workflow.state, so mock at the source module
+MOCK_PATH = "pennyfarthing_scripts.workflow.state.get_workflow_state"
 
 
 class TestWorkflowCheckCLI:

package/pennyfarthing_scripts/validate/adapters/tandem_awareness.py

@@ -0,0 +1,254 @@
+"""Tandem awareness validator adapter.
+
+Validates that agent definitions include proper tandem consultation sections
+per ADR-0012 and the tandem-consultation protocol.
+
+Story: MSSCI-14499 (86-4)
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from pennyfarthing_scripts.validate import ValidateReport
+
+# Regex to extract <tandem-consultation> section content
+_TANDEM_RE = re.compile(
+    r"<tandem-consultation>(.*?)</tandem-consultation>", re.DOTALL
+)
+
+# Regex to extract role from heading: ## Tandem Consultation (Leader + Partner)
+_HEADING_RE = re.compile(r"##\s+Tandem Consultation\s*\(([^)]+)\)")
+
+# Required response format fields for partner agents
+_PARTNER_FIELDS = {
+    "Recommendation": "**Recommendation:**",
+    "Rationale": "**Rationale:**",
+    "Watch-Out-For": "**Watch-Out-For:**",
+    "Confidence": "**Confidence:**",
+}
+
+# ADR-0012 high-value pairings (leader, partner) — directional
+ADR_0012_PAIRINGS: list[tuple[str, str]] = [
+    ("dev", "architect"),
+    ("dev", "tea"),
+    ("reviewer", "architect"),
+    ("dev", "devops"),
+]
+
+
+def _extract_tandem_section(content: str) -> str | None:
+    """Extract content between <tandem-consultation> tags."""
+    m = _TANDEM_RE.search(content)
+    return m.group(1) if m else None
+
+
+def classify_tandem_roles(
+    agents_dir: Path,
+) -> tuple[list[Path], list[Path]]:
+    """Classify agent files into leaders and partners based on tandem sections.
+
+    Classification is based on the heading within the tandem-consultation section:
+    - "(Leader)" → leader only
+    - "(Partner)" → partner only
+    - "(Leader + Partner)" → both
+
+    Returns:
+        (leaders, partners) — two lists of Path objects. An agent may appear in both.
+    """
+    leaders: list[Path] = []
+    partners: list[Path] = []
+
+    for f in sorted(agents_dir.glob("*.md")):
+        if f.name == "README.md":
+            continue
+
+        content = f.read_text()
+        section = _extract_tandem_section(content)
+        if section is None:
+            continue
+
+        # Match heading like "## Tandem Consultation (Leader + Partner)"
+        heading = _HEADING_RE.search(section)
+        if heading:
+            role = heading.group(1)
+            if "Leader" in role:
+                leaders.append(f)
+            if "Partner" in role:
+                partners.append(f)
+
+    return leaders, partners
+
+
+def validate_leader_tandem(path: Path) -> tuple[list[str], list[str]]:
+    """Validate leader tandem consultation section content.
+
+    Returns:
+        (errors, warnings) — two lists of message strings.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+    content = path.read_text()
+    section = _extract_tandem_section(content)
+
+    if section is None:
+        errors.append("Missing <tandem-consultation> section")
+        return errors, warnings
+
+    stripped = section.strip()
+    if not stripped:
+        errors.append("Empty <tandem-consultation> section — no content")
+        return errors, warnings
+
+    # Workflow phase check — must reference tandem.mode
+    if "tandem.mode" not in section:
+        errors.append(
+            "Leader section must reference workflow phase availability (tandem.mode)"
+        )
+
+    # Request format template (recommended)
+    if "request format" not in section.lower():
+        warnings.append("Missing request format template in leader section")
+
+    # Graceful degradation guidance (recommended)
+    section_lower = section.lower()
+    if not any(term in section_lower for term in ("fail", "degrad", "solo")):
+        warnings.append(
+            "Missing graceful degradation guidance (what to do if consultation fails)"
+        )
+
+    return errors, warnings
+
+
+def validate_partner_tandem(path: Path) -> tuple[list[str], list[str]]:
+    """Validate partner tandem consultation response guidance.
+
+    Returns:
+        (errors, warnings) — two lists of message strings.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+    content = path.read_text()
+    section = _extract_tandem_section(content)
+
+    if section is None:
+        errors.append("Missing <tandem-consultation> section")
+        return errors, warnings
+
+    # Check for required response format fields
+    missing = [
+        name for name, marker in _PARTNER_FIELDS.items() if marker not in section
+    ]
+    if missing:
+        errors.append(
+            f"Partner response format missing required fields: {', '.join(missing)}"
+        )
+
+    return errors, warnings
+
+
+def validate_pairings_documented(
+    leader_names: set[str],
+    partner_names: set[str],
+    pairings: list[tuple[str, str]],
+) -> tuple[list[tuple[str, str]], list[tuple[str, str]]]:
+    """Check which ADR-0012 pairings are covered by agent tandem sections.
+
+    Directional check: verifies the leader agent is classified as a leader
+    and the partner agent is classified as a partner.
+
+    Returns:
+        (covered, missing) — two lists of (leader, partner) tuples.
+    """
+    covered: list[tuple[str, str]] = []
+    missing: list[tuple[str, str]] = []
+
+    for leader, partner in pairings:
+        if leader in leader_names and partner in partner_names:
+            covered.append((leader, partner))
+        else:
+            missing.append((leader, partner))
+
+    return covered, missing
+
+
+def run(
+    root: Path, *, fix: bool = False, strict: bool = False
+) -> ValidateReport:
+    """Validate agent tandem awareness sections."""
+    report = ValidateReport(validator="tandem-awareness")
+    agents_dir = root / "pennyfarthing-dist" / "agents"
+
+    if not agents_dir.is_dir():
+        report.details.append("[ERROR] agents directory not found")
+        report.errors += 1
+        return report
+
+    leaders, partners = classify_tandem_roles(agents_dir)
+
+    for path in leaders:
+        file_errors, file_warnings = validate_leader_tandem(path)
+
+        for e in file_errors:
+            report.errors += 1
+            report.details.append(f"[ERROR] {path.name}: {e}")
+
+        for w in file_warnings:
+            if strict:
+                report.errors += 1
+                report.details.append(f"[ERROR] {path.name}: {w}")
+            else:
+                report.warnings += 1
+                report.details.append(f"[WARN] {path.name}: {w}")
+
+        if not file_errors:
+            report.passed += 1
+
+    for path in partners:
+        file_errors, file_warnings = validate_partner_tandem(path)
+
+        for e in file_errors:
+            report.errors += 1
+            report.details.append(f"[ERROR] {path.name}: {e}")
+
+        for w in file_warnings:
+            if strict:
+                report.errors += 1
+                report.details.append(f"[ERROR] {path.name}: {w}")
+            else:
+                report.warnings += 1
+                report.details.append(f"[WARN] {path.name}: {w}")
+
+        if not file_errors:
+            report.passed += 1
+
+    # Validate ADR-0012 pairings (directional)
+    leader_names = {f.stem for f in leaders}
+    partner_names = {f.stem for f in partners}
+    covered, missing_pairings = validate_pairings_documented(
+        leader_names, partner_names, ADR_0012_PAIRINGS
+    )
+    for leader_name, partner_name in missing_pairings:
+        report.errors += 1
+        report.details.append(
+            f"[ERROR] ADR-0012 pairing {leader_name}\u2192{partner_name} not covered "
+            f"(leader or partner missing tandem section with correct role)"
+        )
+    if covered:
+        report.passed += 1
+
+    # Detect agents with tandem section but no matching heading
+    classified_stems = leader_names | partner_names
+    for f in sorted(agents_dir.glob("*.md")):
+        if f.name == "README.md":
+            continue
+        content = f.read_text()
+        if _extract_tandem_section(content) is not None and f.stem not in classified_stems:
+            report.warnings += 1
+            report.details.append(
+                f"[WARN] {f.name}: has <tandem-consultation> section but no "
+                f"matching '## Tandem Consultation (Role)' heading"
+            )
+
+    return report

package/pennyfarthing_scripts/validate/cli.py

@@ -22,6 +22,7 @@ VALIDATORS = {
     "agent": "pennyfarthing_scripts.validate.adapters.agent",
     "workflow": "pennyfarthing_scripts.validate.adapters.workflow",
     "skill-command": "pennyfarthing_scripts.validate.adapters.skill_command",
+    "tandem-awareness": "pennyfarthing_scripts.validate.adapters.tandem_awareness",
 }
 
 
@@ -83,11 +84,12 @@ def validate(ctx, fix: bool, strict: bool):
 
     \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)
+      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
@@ -150,3 +152,13 @@ def validate_skill_command(ctx):
     _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_scripts/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 pennyfarthing_scripts.workflow import ...`.
+"""
+
+from pennyfarthing_scripts.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 pennyfarthing_scripts.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",
+]