@pennyfarthing/core 11.1.1 → 11.2.1

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/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/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/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()

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",
+]