feat(hud): breathing buddy face states (Wave 2-A)

The Buddy face now reacts to HUD phase / blocker state so the
status bar feels alive:

  Idle / Ready       -> ◕‿◕  (FACE_IDLE)
  Thinking / Planning-> ◔‿◔  (FACE_THINKING)
  Active / Executing -> ◕◡◕  (FACE_ACTIVE)
  Error / Blocked    -> ◕︵◕  (FACE_ERROR)
  Victory / Completed-> ◕ᴗ◕  (FACE_VICTORY)

Priority resolution:
  1. blocker_count > 0 always wins (error face)
  2. recent_event == "victory" beats phase
  3. Phase lookup (case-insensitive)
  4. Fallback to FACE_IDLE

hud_buddy.py extended:
- FACE_* constants for each state
- _PHASE_FACE_MAP for phase -> glyph lookup
- get_buddy_face(phase, *, blocker_count, recent_event) pure function
- select_face_from_state(hud_state) convenience dict wrapper
- __all__ exports updated

BUDDY_FACE is still canonically re-exported from tiny_actor_presets
(identity lock preserved).

29 new tests in test_hud_buddy.py cover:
- All 5 face constants distinct + non-empty
- All 6 phase mappings (ready/planning/executing/evaluating/cycling/completed)
- Case-insensitive phase, unknown phase, empty, None
- Priority: blocker beats phase, blocker beats victory
- Malformed blocker_count fall-through
- Victory event recognition (case-insensitive) + unknown event
- select_face_from_state (empty, None, planning, blocked, victory)
- __all__ public API coverage

158/158 pass.

Part of #1464 (Wave 0 statusbar refactor)

Author: JeremyDev87

packages/claude-code-plugin/hooks/lib/hud_buddy.py

@@ -1,17 +1,148 @@
-"""Buddy face re-export for CodingBuddy statusLine (#1326).
+"""Buddy face state engine for CodingBuddy statusLine (#1326, Wave 2-A).
 
-``BUDDY_FACE`` is canonically defined in
-``tiny_actor_presets.BUDDY_FACE`` and already covered by
-``tests/test_tiny_actor_presets.py`` for value/type assertions. This
-module re-exports it so statusLine helpers that conceptually belong to
-the HUD layer can depend on a ``hud_*`` module instead of reaching into
-``tiny_actor_presets``.
+``BUDDY_FACE`` is still canonically defined in
+``tiny_actor_presets.BUDDY_FACE`` and re-exported here for import
+clarity at the HUD layer. Wave 2-A adds a **state-aware** face
+picker so the Buddy appears to "breathe" as the session moves
+through its lifecycle phases:
 
-Wave 0 establishes the re-export only. Wave 2-A will extend this file
-with breathing Buddy face state logic (e.g., ``get_buddy_face(phase)``).
+- **Idle / Ready**       → ``◕‿◕`` — resting, calm
+- **Thinking / Planning** → ``◔‿◔`` — half-closed eyes, pondering
+- **Active / Executing** → ``◕◡◕`` — smiling, working
+- **Error / Blocked**    → ``◕︵◕`` — concerned, something broke
+- **Victory / Completed**→ ``◕ᴗ◕`` — beaming, success
+
+Priority rules:
+
+1. ``blocker_count > 0`` always wins (error face) regardless of phase.
+2. ``recent_event == "victory"`` wins over phase when set.
+3. Otherwise the phase mapping decides.
+4. Unknown/empty phase falls back to the canonical idle face.
+
+Primary entry points:
+
+- :data:`BUDDY_FACE` — canonical idle glyph (re-exported)
+- :data:`FACE_*` — individual state glyphs as constants
+- :func:`get_buddy_face` — state-to-glyph lookup
+- :func:`select_face_from_state` — HUD-state-dict convenience wrapper
 """
 from __future__ import annotations
 
-from tiny_actor_presets import BUDDY_FACE  # canonical SSoT
+from typing import Any, Dict, Optional
+
+from tiny_actor_presets import BUDDY_FACE  # canonical SSoT (idle face)
+
+# ------------------------------------------------------------------------
+# Face glyph constants
+# ------------------------------------------------------------------------
+
+#: Default / idle face — ``◕‿◕`` (U+25D5 U+203F U+25D5).
+FACE_IDLE: str = BUDDY_FACE
+
+#: Thinking face — ``◔‿◔`` (half-closed eyes).
+FACE_THINKING: str = "\u25d4\u203f\u25d4"
+
+#: Active face — ``◕◡◕`` (smiling, working).
+FACE_ACTIVE: str = "\u25d5\u25e1\u25d5"
+
+#: Error / blocked face — ``◕︵◕`` (concerned).
+FACE_ERROR: str = "\u25d5\ufe35\u25d5"
+
+#: Victory / completed face — ``◕ᴗ◕`` (beaming).
+FACE_VICTORY: str = "\u25d5\u1d17\u25d5"
+
+
+# ------------------------------------------------------------------------
+# Phase → face mapping
+# ------------------------------------------------------------------------
+
+_PHASE_FACE_MAP: Dict[str, str] = {
+    "ready": FACE_IDLE,
+    "planning": FACE_THINKING,
+    "executing": FACE_ACTIVE,
+    "evaluating": FACE_THINKING,
+    "cycling": FACE_ACTIVE,
+    "completed": FACE_VICTORY,
+}
+
+
+# ------------------------------------------------------------------------
+# Public API
+# ------------------------------------------------------------------------
+
+
+def get_buddy_face(
+    phase: Optional[str] = None,
+    *,
+    blocker_count: int = 0,
+    recent_event: Optional[str] = None,
+) -> str:
+    """Return the buddy face glyph for the given state.
+
+    Priority resolution (highest wins):
+
+    1. ``blocker_count > 0`` → :data:`FACE_ERROR`
+    2. ``recent_event == "victory"`` → :data:`FACE_VICTORY`
+    3. Phase lookup against :data:`_PHASE_FACE_MAP`
+    4. Fallback: :data:`FACE_IDLE`
+
+    Args:
+        phase: HUD state phase. One of
+            ``ready``, ``planning``, ``executing``, ``evaluating``,
+            ``cycling``, ``completed`` (case-insensitive). Unknown
+            or empty values fall back to the idle face.
+        blocker_count: Number of blockers detected. Any positive
+            value triggers the error face.
+        recent_event: Optional one-off event marker. Currently only
+            ``"victory"`` is recognised.
+
+    Returns:
+        A 3-character glyph string, never empty.
+    """
+    # (1) Error: blockers take precedence
+    try:
+        if int(blocker_count) > 0:
+            return FACE_ERROR
+    except (TypeError, ValueError):
+        pass  # ignore malformed counter, fall through
+
+    # (2) Victory event beats phase
+    if recent_event and recent_event.lower() == "victory":
+        return FACE_VICTORY
+
+    # (3) Phase mapping
+    if phase:
+        return _PHASE_FACE_MAP.get(phase.lower(), FACE_IDLE)
+
+    # (4) Fallback
+    return FACE_IDLE
+
+
+def select_face_from_state(hud_state: Dict[str, Any]) -> str:
+    """Convenience wrapper that extracts face inputs from a hud_state dict.
+
+    Reads:
+
+    - ``phase``         — HUD phase string
+    - ``blockerCount``  — integer blocker count (default 0)
+    - ``lastEvent``     — optional one-off event marker
+    """
+    if not hud_state:
+        return FACE_IDLE
+    return get_buddy_face(
+        phase=hud_state.get("phase"),
+        blocker_count=hud_state.get("blockerCount", 0) or 0,
+        recent_event=hud_state.get("lastEvent"),
+    )
+
 
-__all__ = ["BUDDY_FACE"]
+__all__ = [
+    "BUDDY_FACE",
+    "FACE_IDLE",
+    "FACE_THINKING",
+    "FACE_ACTIVE",
+    "FACE_ERROR",
+    "FACE_VICTORY",
+    "get_buddy_face",
+    "select_face_from_state",
+]

packages/claude-code-plugin/tests/test_hud_buddy.py

@@ -29,3 +29,171 @@ def test_reexport_identity_from_codingbuddy_hud():
     hud_main = importlib.import_module("codingbuddy-hud")
     assert hud_main.BUDDY_FACE is hud_buddy.BUDDY_FACE
     assert hud_main.BUDDY_FACE is CANONICAL_BUDDY_FACE
+
+
+# ========================= Wave 2-A: face state engine ======================
+
+
+def test_face_constants_defined():
+    """All five named faces are distinct non-empty strings."""
+    faces = {
+        hud_buddy.FACE_IDLE,
+        hud_buddy.FACE_THINKING,
+        hud_buddy.FACE_ACTIVE,
+        hud_buddy.FACE_ERROR,
+        hud_buddy.FACE_VICTORY,
+    }
+    assert len(faces) == 5
+    for face in faces:
+        assert face  # non-empty
+        assert len(face) >= 3  # 3-char glyphs
+
+
+def test_face_idle_matches_canonical_buddy():
+    """FACE_IDLE is the canonical buddy face."""
+    assert hud_buddy.FACE_IDLE is hud_buddy.BUDDY_FACE
+
+
+# --- get_buddy_face: phase mapping ---
+
+
+def test_get_face_ready_phase_is_idle():
+    assert hud_buddy.get_buddy_face("ready") == hud_buddy.FACE_IDLE
+
+
+def test_get_face_planning_phase_is_thinking():
+    assert hud_buddy.get_buddy_face("planning") == hud_buddy.FACE_THINKING
+
+
+def test_get_face_executing_phase_is_active():
+    assert hud_buddy.get_buddy_face("executing") == hud_buddy.FACE_ACTIVE
+
+
+def test_get_face_evaluating_phase_is_thinking():
+    assert hud_buddy.get_buddy_face("evaluating") == hud_buddy.FACE_THINKING
+
+
+def test_get_face_cycling_phase_is_active():
+    assert hud_buddy.get_buddy_face("cycling") == hud_buddy.FACE_ACTIVE
+
+
+def test_get_face_completed_phase_is_victory():
+    assert hud_buddy.get_buddy_face("completed") == hud_buddy.FACE_VICTORY
+
+
+def test_get_face_case_insensitive():
+    assert hud_buddy.get_buddy_face("PLANNING") == hud_buddy.FACE_THINKING
+    assert hud_buddy.get_buddy_face("Executing") == hud_buddy.FACE_ACTIVE
+
+
+def test_get_face_unknown_phase_falls_back_to_idle():
+    assert hud_buddy.get_buddy_face("waiting") == hud_buddy.FACE_IDLE
+    assert hud_buddy.get_buddy_face("unknown") == hud_buddy.FACE_IDLE
+
+
+def test_get_face_empty_phase_is_idle():
+    assert hud_buddy.get_buddy_face("") == hud_buddy.FACE_IDLE
+
+
+def test_get_face_none_phase_is_idle():
+    assert hud_buddy.get_buddy_face(None) == hud_buddy.FACE_IDLE
+
+
+# --- get_buddy_face: priority rules ---
+
+
+def test_blocker_count_beats_phase():
+    """Any positive blocker_count triggers the error face."""
+    assert (
+        hud_buddy.get_buddy_face("executing", blocker_count=1)
+        == hud_buddy.FACE_ERROR
+    )
+
+
+def test_blocker_count_zero_does_not_trigger():
+    assert (
+        hud_buddy.get_buddy_face("executing", blocker_count=0)
+        == hud_buddy.FACE_ACTIVE
+    )
+
+
+def test_blocker_count_beats_victory():
+    """Even a victory event yields error when blockers are present."""
+    assert (
+        hud_buddy.get_buddy_face(
+            "completed", blocker_count=3, recent_event="victory"
+        )
+        == hud_buddy.FACE_ERROR
+    )
+
+
+def test_blocker_count_malformed_ignored():
+    """Non-numeric blocker_count falls through to phase mapping."""
+    assert (
+        hud_buddy.get_buddy_face("planning", blocker_count="abc")  # type: ignore[arg-type]
+        == hud_buddy.FACE_THINKING
+    )
+
+
+def test_recent_event_victory_beats_phase():
+    """Victory event wins over phase when no blockers."""
+    assert (
+        hud_buddy.get_buddy_face("executing", recent_event="victory")
+        == hud_buddy.FACE_VICTORY
+    )
+
+
+def test_recent_event_case_insensitive():
+    assert (
+        hud_buddy.get_buddy_face("planning", recent_event="VICTORY")
+        == hud_buddy.FACE_VICTORY
+    )
+
+
+def test_recent_event_unknown_ignored():
+    assert (
+        hud_buddy.get_buddy_face("planning", recent_event="foobar")
+        == hud_buddy.FACE_THINKING
+    )
+
+
+# --- select_face_from_state ---
+
+
+def test_select_face_from_empty_state():
+    assert hud_buddy.select_face_from_state({}) == hud_buddy.FACE_IDLE
+
+
+def test_select_face_from_none_state():
+    assert hud_buddy.select_face_from_state(None) == hud_buddy.FACE_IDLE  # type: ignore[arg-type]
+
+
+def test_select_face_from_planning_state():
+    state = {"phase": "planning", "blockerCount": 0}
+    assert hud_buddy.select_face_from_state(state) == hud_buddy.FACE_THINKING
+
+
+def test_select_face_from_blocked_state():
+    state = {"phase": "executing", "blockerCount": 2}
+    assert hud_buddy.select_face_from_state(state) == hud_buddy.FACE_ERROR
+
+
+def test_select_face_from_victory_state():
+    state = {"phase": "completed", "blockerCount": 0, "lastEvent": "victory"}
+    assert hud_buddy.select_face_from_state(state) == hud_buddy.FACE_VICTORY
+
+
+def test_select_face_from_completed_state_without_victory_marker():
+    state = {"phase": "completed", "blockerCount": 0}
+    assert hud_buddy.select_face_from_state(state) == hud_buddy.FACE_VICTORY
+
+
+# --- __all__ exports ---
+
+
+def test_public_api_exported():
+    assert "BUDDY_FACE" in hud_buddy.__all__
+    assert "get_buddy_face" in hud_buddy.__all__
+    assert "select_face_from_state" in hud_buddy.__all__
+    for name in ("FACE_IDLE", "FACE_THINKING", "FACE_ACTIVE", "FACE_ERROR", "FACE_VICTORY"):
+        assert name in hud_buddy.__all__