@pennyfarthing/core 11.0.0 → 11.1.0

package/pennyfarthing-dist/workflows/2party-tdd.yaml

@@ -53,6 +53,7 @@ workflow:
         Present findings to user. User decides what to add/change.
         Update the story description with agreed refinements.
       gate:
+        file: gates/approval
         type: approval
         condition: User reviewed dev-perspective gaps and decided on each item
 
@@ -73,6 +74,7 @@ workflow:
         Present findings to user. User decides what to add/change.
         Update the story description with agreed refinements.
       gate:
+        file: gates/approval
         type: approval
         condition: User reviewed tea-perspective gaps and decided on each item
 
@@ -93,6 +95,7 @@ workflow:
 
         Fix any remaining issues, then hand off to TEA.
       gate:
+        file: gates/approval
         type: approval
         condition: Story passes quality check and is ready for TEA
 
@@ -122,6 +125,7 @@ workflow:
         In the TEA Assessment handoff, list what quality gates Dev
         should expect to pass beyond the functional tests.
       gate:
+        file: gates/tests-fail
         type: tests_fail
         condition: All acceptance criteria have test coverage, including quality gate check
 
@@ -154,6 +158,7 @@ workflow:
 
         Reviewer should only receive code that is verified clean.
       gate:
+        file: gates/quality-pass
         type: quality_pass
         condition: >
           All project quality gates pass locally — tests, lint, format,
@@ -181,6 +186,7 @@ workflow:
         - Set review_verdict: approved in story
         - DO NOT merge the PR — hand off to SM for finish phase
       gate:
+        file: gates/approval
         type: approval
         condition: Code review passed, no blocking issues
 
@@ -194,6 +200,7 @@ workflow:
         from the story. Write failing tests for each testable finding.
         Commit RED tests. Hand off to Dev.
       gate:
+        file: gates/tests-fail
         type: tests_fail
         condition: New tests cover reviewer findings
 
@@ -227,6 +234,7 @@ workflow:
         If verification fails, hand back to Dev with specifics.
         If verification passes, hand off to Reviewer for re-review.
       gate:
+        file: gates/quality-pass
         type: quality_pass
         condition: >
           All project quality gates pass. Each review finding verified
@@ -255,6 +263,7 @@ workflow:
         5. Only after user approves: create PR (draft by default,
            or per user pr_mode preference in pennyfarthing config)
       gate:
+        file: gates/approval
         type: approval
         condition: User has reviewed and approved PR content before submission
 
@@ -315,6 +324,7 @@ workflow:
 
         Present decisions to user. User has final say on every item.
       gate:
+        file: gates/approval
         type: approval
         condition: User has decided on every external review comment
 
@@ -340,6 +350,7 @@ workflow:
 
         Commit fixes. Push branch. Present all draft replies to user.
       gate:
+        file: gates/approval
         type: approval
         condition: >
           User has approved every draft reply. Fixes pass quality

package/pennyfarthing-dist/workflows/agent-docs.yaml

@@ -28,6 +28,7 @@ workflow:
       input: [audit_report, proposed_changes]
       output: [updated_files]
       gate:
+        file: gates/validation
         type: validation
         condition: Agent files parse correctly, no broken references
 
@@ -36,6 +37,7 @@ workflow:
       input: [updated_files]
       output: [approval]
       gate:
+        file: gates/approval
         type: approval
         condition: |
           Documentation quality review:

package/pennyfarthing-dist/workflows/bdd-tandem.yaml

@@ -21,6 +21,7 @@ workflow:
       input: [session_file, story_context]
       output: [design_spec, user_flows, wireframes, behavior_scenarios]
       gate:
+        file: gates/design-review
         type: design_review
         condition: UX spec defines user flows and acceptance behaviors
       tandem:
@@ -32,6 +33,7 @@ workflow:
       input: [design_spec, behavior_scenarios, story_context]
       output: [failing_tests]
       gate:
+        file: gates/tests-fail
         type: tests_fail
         condition: Behavior scenarios have test coverage
 
@@ -40,6 +42,7 @@ workflow:
       input: [failing_tests, design_spec, story_context]
       output: [implementation, passing_tests]
       gate:
+        file: gates/tests-pass
         type: tests_pass
         condition: All tests passing, UX spec implemented
       tandem:
@@ -51,6 +54,7 @@ workflow:
       input: [implementation, passing_tests, design_spec]
       output: [approval]
       gate:
+        file: gates/approval
         type: approval
         condition: Code review approved, UX requirements met
       tandem:

package/pennyfarthing-dist/workflows/bdd.yaml

@@ -19,6 +19,7 @@ workflow:
       input: [session_file, story_context]
       output: [design_spec, user_flows, wireframes, behavior_scenarios]
       gate:
+        file: gates/design-review
         type: design_review
         condition: UX spec defines user flows and acceptance behaviors
 
@@ -27,6 +28,7 @@ workflow:
       input: [design_spec, behavior_scenarios, story_context]
       output: [failing_tests]
       gate:
+        file: gates/tests-fail
         type: tests_fail
         condition: Behavior scenarios have test coverage
 
@@ -35,6 +37,7 @@ workflow:
       input: [failing_tests, design_spec, story_context]
       output: [implementation, passing_tests]
       gate:
+        file: gates/tests-pass
         type: tests_pass
         condition: All tests passing, UX spec implemented
 
@@ -43,6 +46,7 @@ workflow:
       input: [implementation, passing_tests, design_spec]
       output: [approval]
       gate:
+        file: gates/approval
         type: approval
         condition: Code review approved, UX requirements met
 

package/pennyfarthing-dist/workflows/git-cleanup/steps/step-05-complete.md

@@ -62,7 +62,7 @@ git -C {repo_path} branch --merged develop | grep -v "develop\|main" | xargs -r
 To run git-cleanup again:
 
 ```
-/git-cleanup
+/pf-git cleanup
 ```
 
 Or for a quick status check across all repos:

package/pennyfarthing-dist/workflows/tdd-tandem.yaml

@@ -21,6 +21,7 @@ workflow:
       input: [session_file, story_context]
       output: [failing_tests]
       gate:
+        file: gates/tests-fail
         type: tests_fail
         condition: All acceptance criteria have test coverage
       tandem:
@@ -32,6 +33,7 @@ workflow:
       input: [failing_tests, story_context]
       output: [implementation, passing_tests]
       gate:
+        file: gates/tests-pass
         type: tests_pass
         condition: All tests passing, no skipped tests
       tandem:
@@ -43,6 +45,7 @@ workflow:
       input: [implementation, passing_tests]
       output: [approval]
       gate:
+        file: gates/approval
         type: approval
         condition: Code review approved, no blocking issues
       tandem:

package/pennyfarthing-dist/workflows/tdd.yaml

@@ -19,6 +19,7 @@ workflow:
       input: [session_file, story_context]
       output: [failing_tests]
       gate:
+        file: gates/tests-fail
         type: tests_fail
         condition: All acceptance criteria have test coverage
 
@@ -27,6 +28,7 @@ workflow:
       input: [failing_tests, story_context]
       output: [implementation, passing_tests]
       gate:
+        file: gates/tests-pass
         type: tests_pass
         condition: All tests passing, no skipped tests
 
@@ -35,6 +37,7 @@ workflow:
       input: [implementation, passing_tests]
       output: [approval]
       gate:
+        file: gates/approval
         type: approval
         condition: Code review approved, no blocking issues
 

package/pennyfarthing-dist/workflows/trivial.yaml

@@ -19,6 +19,7 @@ workflow:
       input: [session_file]
       output: [implementation]
       gate:
+        file: gates/tests-pass
         type: tests_pass
         condition: Existing tests still pass
 
@@ -27,6 +28,7 @@ workflow:
       input: [implementation]
       output: [approval]
       gate:
+        file: gates/approval
         type: approval
 
     - name: finish

package/pennyfarthing_scripts/bikerack/debug_panel.py

@@ -0,0 +1,218 @@
+"""DebugPanel — Context usage and token stats for BikeRack TUI.
+
+Story 103-17: Port of the React DebugPanel. Subscribes to /ws/context
+and /ws/token-stats, renders context usage (tokens, percent, tier) and
+token consumption stats (input, output, cache, cost).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Group
+from rich.table import Table
+from rich.text import Text
+
+from pennyfarthing_scripts.bikerack.base_panel import PANEL_ICONS, BasePanel
+
+# Tier → Rich style mapping
+_TIER_STYLES: dict[str, str] = {
+    "FULL": "bold green",
+    "REFRESH": "bold yellow",
+    "HANDOFF": "bold cyan",
+    "MINIMAL": "bold red",
+}
+
+
+def _safe_int(value: Any) -> int | None:
+    """Safely convert a value to int, returning None on failure."""
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (ValueError, TypeError):
+        return None
+
+
+def _safe_float(value: Any) -> float | None:
+    """Safely convert a value to float, returning None on failure."""
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (ValueError, TypeError):
+        return None
+
+
+def _format_tokens(value: Any) -> str:
+    """Format a token count with comma separators."""
+    n = _safe_int(value)
+    if n is None:
+        return "—"
+    return f"{n:,}"
+
+
+class DebugPanel(BasePanel):
+    """Context usage and token stats panel.
+
+    Subscribes to both ``context`` and ``token-stats`` WebSocket channels.
+    Renders context usage (tokens, percentage, tier) and token consumption
+    stats (input, output, cache read/write, cost).
+    """
+
+    channel: str = "context"
+    panel_name: str = "Debug"
+    icon: str = PANEL_ICONS["debug"][0]
+
+    def __init__(self, client: Any = None, **kwargs: Any) -> None:
+        super().__init__(client=client, **kwargs)
+        self._context_data: dict[str, Any] | None = None
+        self._token_stats: dict[str, Any] | None = None
+
+    def on_mount(self) -> None:
+        """Subscribe to both context and token-stats channels."""
+        self._mounted = True
+        if self._client is not None:
+            self._client.subscribe("context", self._handle_context_message)
+            self._client.subscribe("token-stats", self._handle_token_stats_message)
+
+    def _handle_context_message(self, message: dict[str, Any] | None) -> None:
+        """Handle incoming context channel message."""
+        if message is None:
+            return
+        ctx = message.get("context")
+        if isinstance(ctx, dict):
+            self._context_data = ctx
+        else:
+            self._context_data = {}
+        self._rerender()
+
+    def _handle_token_stats_message(self, message: dict[str, Any] | None) -> None:
+        """Handle incoming token-stats channel message."""
+        if message is None:
+            return
+        self._token_stats = message
+        self._rerender()
+
+    def _rerender(self) -> None:
+        """Re-render with the latest data from both channels."""
+        rendered = self.render_panel(self._context_data or {})
+        try:
+            self.update(rendered)
+        except Exception:
+            pass
+
+    def render_panel(self, payload: dict[str, Any]) -> Any:
+        """Render combined context usage and token stats."""
+        parts: list[Any] = []
+
+        # --- Context Usage Section ---
+        ctx = self._context_data
+        if ctx:
+            parts.append(_render_context(ctx))
+        elif not self._token_stats:
+            return Text("No context data", style="dim italic")
+
+        # --- Token Stats Section ---
+        if self._token_stats:
+            if parts:
+                parts.append(Text(""))  # spacer
+            parts.append(_render_token_stats(self._token_stats))
+
+        if not parts:
+            return Text("No context data", style="dim italic")
+
+        return Group(*parts)
+
+
+def _render_context(ctx: dict[str, Any]) -> Any:
+    """Render context usage section."""
+    parts: list[Any] = []
+
+    # Tier badge
+    tier = ctx.get("tier")
+    if tier and isinstance(tier, str):
+        style = _TIER_STYLES.get(tier, "bold")
+        tier_text = Text()
+        tier_text.append(tier, style=style)
+        savings = _tier_savings(tier)
+        if savings > 0:
+            tier_text.append(f" {savings}% savings", style="dim")
+        parts.append(tier_text)
+
+    # Token usage
+    tokens = _safe_int(ctx.get("tokens"))
+    percent = _safe_int(ctx.get("percent"))
+    baseline = _safe_int(ctx.get("baseline"))
+    available = _safe_int(ctx.get("available"))
+
+    if tokens is not None:
+        usage_text = Text()
+        usage_text.append(f"{tokens:,}", style="bold")
+        if baseline is not None and available is not None:
+            total = baseline + available
+            usage_text.append(f" / {total:,}")
+        usage_text.append(" tokens")
+        if percent is not None:
+            usage_text.append(f" ({percent}%)")
+        parts.append(usage_text)
+
+    # Breakdown: baseline / conversation / available
+    if baseline is not None:
+        breakdown = Table(show_header=False, show_edge=False, pad_edge=False, box=None)
+        breakdown.add_column("Label", style="dim")
+        breakdown.add_column("Value", justify="right")
+        breakdown.add_row("System Prompt", _format_tokens(baseline))
+        usable = _safe_int(ctx.get("usableTokens"))
+        if usable is not None:
+            breakdown.add_row("Conversation", _format_tokens(usable))
+        if available is not None:
+            breakdown.add_row("Available", _format_tokens(available))
+        parts.append(breakdown)
+
+    if not parts:
+        return Text("No context data", style="dim italic")
+
+    return Group(*parts)
+
+
+def _render_token_stats(stats: dict[str, Any]) -> Any:
+    """Render token stats section."""
+    table = Table(show_header=False, show_edge=False, pad_edge=False, box=None)
+    table.add_column("Stat", style="dim")
+    table.add_column("Value", justify="right")
+
+    rows: list[tuple[str, str]] = []
+
+    input_t = _safe_int(stats.get("inputTokens"))
+    if input_t is not None:
+        rows.append(("Input", f"{input_t:,}"))
+
+    output_t = _safe_int(stats.get("outputTokens"))
+    if output_t is not None:
+        rows.append(("Output", f"{output_t:,}"))
+
+    cache_read = _safe_int(stats.get("cacheReadTokens"))
+    if cache_read is not None:
+        rows.append(("Cache Read", f"{cache_read:,}"))
+
+    cache_write = _safe_int(stats.get("cacheCreationTokens"))
+    if cache_write is not None:
+        rows.append(("Cache Write", f"{cache_write:,}"))
+
+    cost = _safe_float(stats.get("totalCostUsd"))
+    if cost is not None and cost > 0:
+        rows.append(("Cost", f"${cost:.4f}"))
+
+    if not rows:
+        return Text("No token stats", style="dim italic")
+
+    for label, value in rows:
+        table.add_row(label, value)
+
+    return table
+
+
+def _tier_savings(tier: str) -> int:
+    """Calculate token savings percentage for a tier vs FULL."""
+    return {"FULL": 0, "REFRESH": 85, "HANDOFF": 82, "MINIMAL": 95}.get(tier, 0)