@pennyfarthing/core 11.2.0 → 11.2.1

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

package/pennyfarthing_scripts/workflow/cli.py

@@ -90,17 +90,18 @@ def workflow_phase_check(workflow_name: str, phase: str):
 @workflow.command("handoff")
 @click.argument("next_agent")
 def workflow_handoff(next_agent: str):
-    """Emit a handoff marker for Cyclist.
+    """Emit an environment-aware handoff marker.
+
+    Delegates to generate_marker() which detects Cyclist, relay mode,
+    and context usage to choose the appropriate marker type.
 
     \b
     Arguments:
       NEXT_AGENT  - The agent to hand off to (tea, dev, reviewer, etc.)
     """
-    click.echo("---")
-    click.echo("AGENT_COMMAND:")
-    click.echo(f'  marker: "<!-- CYCLIST:HANDOFF:/{next_agent} -->"')
-    click.echo(f'  fallback: "Run `/{next_agent}` to continue"')
-    click.echo("---")
+    from pennyfarthing_scripts.handoff.marker import generate_marker
+
+    click.echo(generate_marker(next_agent))
 
 
 # ---------------------------------------------------------------------------

package/pennyfarthing_scripts/workflow/team_lifecycle.py

@@ -0,0 +1,257 @@
+"""
+Phase-scoped Team Lifecycle for Story 86-10.
+
+Manages the lifecycle of native Agent Teams within workflow phases.
+When a workflow phase has a `team:` config block, the lead agent creates
+a team at phase start, spawns teammates, and cleans up before handoff.
+
+Python port of packages/core/dist/workflow/team-lifecycle.js.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+# =============================================================================
+# In-memory registries
+# =============================================================================
+
+_active_teams: dict[str, dict[str, Any]] = {}
+"""Active teams keyed by story_id."""
+
+_sidecar_locks: dict[str, dict[str, Any]] = {}
+"""Sidecar locks keyed by file path."""
+
+
+def _reset_for_testing() -> None:
+    """Reset all in-memory state. For testing only."""
+    _active_teams.clear()
+    _sidecar_locks.clear()
+
+
+async def create_team(
+    phase: dict[str, Any],
+    story_id: str,
+    adapter: Any | None = None,
+) -> dict[str, Any]:
+    """Create a phase-scoped team.
+
+    If phase has no team config, returns success with no handle (no-op).
+    If phase has team config, creates team and returns handle.
+    """
+    if not phase.get("team"):
+        return {"success": True}
+
+    team_name = f"{story_id}-{phase['name']}"
+
+    # Clean up existing team for same story
+    existing = _active_teams.get(story_id)
+    if existing and adapter:
+        try:
+            await adapter.delete_team(existing["teamName"])
+        except Exception:
+            pass
+        del _active_teams[story_id]
+
+    handle: dict[str, Any] = {
+        "teamName": team_name,
+        "storyId": story_id,
+        "phase": phase["name"],
+        "teammates": [],
+        "createdAt": datetime.now(timezone.utc).isoformat(),
+    }
+
+    if adapter:
+        try:
+            await adapter.create_team({"teamName": team_name})
+        except Exception as exc:
+            return {"success": False, "error": str(exc)}
+
+    _active_teams[story_id] = handle
+    return {"success": True, "data": handle}
+
+
+async def spawn_teammates(
+    handle: dict[str, Any],
+    config: dict[str, Any],
+    story_id: str,
+    phase: dict[str, Any],
+    adapter: Any | None = None,
+) -> dict[str, Any]:
+    """Spawn all teammates for a team based on workflow YAML config."""
+    teammates: list[dict[str, Any]] = []
+
+    for member in config["teammates"]:
+        teammate: dict[str, Any] = {
+            "agent": member["agent"],
+            "task": member["task"],
+            "status": "spawned",
+        }
+        if adapter:
+            try:
+                await adapter.spawn_teammate({
+                    "teamName": handle["teamName"],
+                    "agent": member["agent"],
+                    "prompt": f'pf agent start "{member["agent"]}"',
+                    "model": config.get("model"),
+                })
+            except Exception:
+                teammate["status"] = "crashed"
+        teammates.append(teammate)
+
+    handle["teammates"] = teammates
+
+    # Update registry
+    if handle.get("storyId") in _active_teams:
+        _active_teams[handle["storyId"]] = handle
+
+    return {"success": True, "data": teammates}
+
+
+async def shutdown_all_teammates(
+    handle: dict[str, Any],
+    adapter: Any | None = None,
+) -> dict[str, Any]:
+    """Shut down all active teammates in a team."""
+    shutdown_count = 0
+
+    for teammate in handle["teammates"]:
+        if teammate["status"] in ("shutdown", "crashed"):
+            continue
+        if adapter:
+            try:
+                await adapter.shutdown_teammate({
+                    "teamName": handle["teamName"],
+                    "agent": teammate["agent"],
+                })
+            except Exception:
+                pass  # Graceful degradation — swallow adapter errors
+        teammate["status"] = "shutdown"
+        shutdown_count += 1
+
+    return {"success": True, "data": {"shutdownCount": shutdown_count}}
+
+
+async def cleanup_team(
+    handle: dict[str, Any],
+    adapter: Any | None = None,
+) -> dict[str, Any]:
+    """Clean up a team entirely (TeamDelete). Must run before pf handoff."""
+    if adapter:
+        try:
+            await adapter.delete_team(handle["teamName"])
+        except Exception:
+            pass
+
+    _active_teams.pop(handle.get("storyId", ""), None)
+    return {"success": True, "data": {"cleaned": True}}
+
+
+def check_gate_on_task_completed(
+    handle: dict[str, Any],
+    phase: dict[str, Any],
+) -> dict[str, Any]:
+    """Check gate condition when a TaskCompleted event fires."""
+    if not phase.get("gate"):
+        return {"passed": True, "gate": "none"}
+
+    gate_type = phase["gate"].get("type", "unknown")
+    has_active = any(t["status"] == "active" for t in handle["teammates"])
+
+    if has_active:
+        return {"passed": False, "gate": gate_type, "reason": "Teammates still active"}
+
+    return {"passed": True, "gate": gate_type}
+
+
+def check_gate_on_teammate_idle(
+    handle: dict[str, Any],
+    teammate: dict[str, Any],
+    phase: dict[str, Any],
+) -> dict[str, Any]:
+    """Check gate condition when a TeammateIdle event fires."""
+    if not phase.get("gate"):
+        return {"passed": True, "gate": "none"}
+
+    gate_type = phase["gate"].get("type", "unknown")
+
+    if teammate["status"] == "crashed":
+        return {"passed": False, "gate": gate_type, "reason": "Teammate crashed"}
+
+    return {"passed": True, "gate": gate_type}
+
+
+def generate_team_summary(handle: dict[str, Any]) -> dict[str, Any]:
+    """Generate a team activity summary for the session file audit trail."""
+    return {
+        "teamName": handle["teamName"],
+        "storyId": handle["storyId"],
+        "phase": handle["phase"],
+        "members": [
+            {"agent": t["agent"], "status": t["status"], "task": t["task"]}
+            for t in handle["teammates"]
+        ],
+        "cleanShutdown": all(t["status"] == "shutdown" for t in handle["teammates"]),
+    }
+
+
+def acquire_sidecar_lock(
+    file_path: str,
+    story_id: str,
+    timeout: int = 5000,
+) -> dict[str, Any]:
+    """Acquire an exclusive lock for sidecar file writing."""
+    existing = _sidecar_locks.get(file_path)
+    if existing:
+        if existing["storyId"] == story_id:
+            return {"success": True, "data": existing}
+        return {"success": False, "error": f"Lock held by story {existing['storyId']}"}
+
+    lock: dict[str, Any] = {
+        "lockPath": f"{file_path}.lock",
+        "storyId": story_id,
+        "acquiredAt": datetime.now(timezone.utc).isoformat(),
+    }
+    _sidecar_locks[file_path] = lock
+    return {"success": True, "data": lock}
+
+
+def release_sidecar_lock(lock: dict[str, Any]) -> dict[str, Any]:
+    """Release a sidecar file lock."""
+    for path, held in list(_sidecar_locks.items()):
+        if held["lockPath"] == lock["lockPath"]:
+            del _sidecar_locks[path]
+            break
+    return {"success": True}
+
+
+def get_active_team(story_id: str) -> dict[str, Any] | None:
+    """Get the active team for a story, if any."""
+    return _active_teams.get(story_id)
+
+
+def update_session_with_summary(
+    session_path: str | Path,
+    summary: dict[str, Any],
+) -> dict[str, Any]:
+    """Write team activity summary to session file for audit trail."""
+    path = Path(session_path)
+    content = path.read_text() if path.exists() else ""
+
+    lines = [
+        "\n## Team Activity Summary\n",
+        f"**Team:** {summary['teamName']}",
+        f"**Phase:** {summary['phase']}",
+        f"**Clean Shutdown:** {'Yes' if summary.get('cleanShutdown') else 'No'}\n",
+        "| Agent | Status | Task |",
+        "|-------|--------|------|",
+    ]
+    for member in summary.get("members", []):
+        lines.append(f"| {member['agent']} | {member['status']} | {member['task']} |")
+
+    content += "\n".join(lines) + "\n"
+    path.write_text(content)
+    return {"success": True}

package/packages/core/dist/scripts/theme-detail.test.d.ts

@@ -1,10 +0,0 @@
-/**
- * Story 13-5: Theme Detail Page Tests
- *
- * Tests for the theme detail page with team spider chart,
- * agent grid with ProfileCards, and profile links.
- *
- * Run with: npm test
- */
-export {};
-//# sourceMappingURL=theme-detail.test.d.ts.map