@pennyfarthing/core 11.2.2 → 11.3.1

package/pennyfarthing-dist/workflows/installation-check/steps/step-08-summary.md

@@ -0,0 +1,99 @@
+# Step 8: Health Summary
+
+<step-meta>
+step: 8
+name: summary
+workflow: installation-check
+agent: devops
+gate: false
+next: complete
+</step-meta>
+
+<purpose>
+Aggregate results from all previous steps into a final health report with an overall score and prioritized recommendations.
+</purpose>
+
+<prerequisites>
+- All previous steps (1-7) completed
+</prerequisites>
+
+<instructions>
+1. Run the full doctor command to get a complete picture
+2. Aggregate results into a health score:
+   - **HEALTHY**: All checks pass (0 failures, 0 warnings)
+   - **GOOD**: No failures, some warnings (non-critical issues)
+   - **NEEDS_ATTENTION**: 1-3 failures (some features broken)
+   - **NEEDS_FIX**: 4+ failures (significant functionality impaired)
+3. Group remaining issues by priority:
+   - **Critical**: Failures that break core functionality (missing settings.local.json, broken symlinks, missing manifest)
+   - **Important**: Warnings that degrade features (missing hooks, stale commands, non-executable scripts)
+   - **Optional**: Informational items (legacy artifacts, missing optional tools)
+4. For each remaining issue, provide the specific fix command
+5. Write the summary to the output file if configured
+6. Suggest next steps based on the health score
+</instructions>
+
+<actions>
+- Run: `pennyfarthing doctor --json`
+- Write: `{output_file}` with full health report
+</actions>
+
+<output>
+Present the final report:
+
+```markdown
+# Pennyfarthing Health Report
+
+**Project:** {project_root}
+**Version:** {installed_version} / {package_version}
+**Mode:** {installation_type}
+**Health:** {HEALTHY | GOOD | NEEDS_ATTENTION | NEEDS_FIX}
+**Score:** {pass_count}/{total_count} checks passing
+
+## Results by Category
+
+| Category | Pass | Warn | Fail |
+|----------|------|------|------|
+| Installation | ... | ... | ... |
+| Commands & Skills | ... | ... | ... |
+| Hook Configuration | ... | ... | ... |
+| Hook Scripts | ... | ... | ... |
+| Directory Layout | ... | ... | ... |
+| Legacy Artifacts | ... | ... | ... |
+| Optional Tools | ... | ... | ... |
+
+## Remaining Issues (by priority)
+
+### Critical
+[List failures with fix commands]
+
+### Important
+[List warnings with fix commands]
+
+### Optional
+[List informational items]
+
+## Recommended Next Steps
+1. [Based on health score]
+2. [Specific to findings]
+```
+</output>
+
+<collaboration-menu>
+- **[F] Fix** - Run `pennyfarthing doctor --fix` to auto-repair all fixable issues
+- **[E] Explain** - Deep dive on any remaining issue
+- **[C] Continue** - Complete the health check workflow
+- **[R] Recheck** - Run full check again to verify fixes
+</collaboration-menu>
+
+## Failure Modes
+
+- Reporting HEALTHY when critical issues were skipped in earlier steps
+- Not prioritizing issues (user doesn't know what to fix first)
+
+## Success Metrics
+
+- Complete health report generated
+- All issues categorized by priority
+- Clear next steps provided
+- User has actionable path to resolve any remaining issues

package/pennyfarthing-dist/workflows/installation-check/workflow.yaml

@@ -0,0 +1,47 @@
+# Installation Check Workflow
+# Interactive health check with AI-guided explanation and remediation
+#
+# Flow: Foundation → Commands → Hooks (gate) → Scripts → Layout → Legacy (gate) → Tools → Summary
+# Wraps `pennyfarthing doctor --category` for step-by-step guided verification
+#
+# Use for: onboarding, post-update verification, troubleshooting broken installs
+
+workflow:
+  name: installation-check
+  description: Interactive installation health check with AI-guided remediation. Walks through each check category with explanation and targeted fixes.
+  version: "1.0.0"
+  type: stepped
+
+  steps:
+    path: ./steps/
+    pattern: step-{nn}-*.md
+
+  variables:
+    project_root: .
+    doctor_command: pennyfarthing doctor --json
+    output_file: .session/doctor-results.md
+
+  gates:
+    after_steps: [3, 6]
+    gate_marker: "<!-- GATE -->"
+
+  collaboration:
+    menus:
+      - key: F
+        name: Fix
+        description: Apply recommended fixes for this category
+      - key: E
+        name: Explain
+        description: Get detailed explanation of a specific check
+      - key: C
+        name: Continue
+        description: Proceed to next check category
+      - key: R
+        name: Recheck
+        description: Re-run checks after manual changes
+
+  agent: devops
+
+  triggers:
+    types: [installation-check, doctor, health-check]
+    tags: [installation, health, diagnostics]

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

@@ -23,6 +23,10 @@ workflow:
     - name: setup
       agent: sm
       output: [session_file, branches, story_context]
+      gate:
+        file: gates/sm-setup-exit
+        type: sm_setup_exit
+        condition: Session file created with workflow, phase, context, and branch
 
     - name: red
       agent: tea
@@ -41,9 +45,9 @@ 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
+        file: gates/dev-exit
+        type: dev_exit
+        condition: Tests green, tree clean, no debug code, correct branch
       tandem:
         partner: architect
         scope: file-watch

package/pennyfarthing-dist/workflows/tdd.yaml

@@ -13,6 +13,10 @@ workflow:
     - name: setup
       agent: sm
       output: [session_file, branches, story_context]
+      gate:
+        file: gates/sm-setup-exit
+        type: sm_setup_exit
+        condition: Session file created with workflow, phase, context, and branch
 
     - name: red
       agent: tea
@@ -28,9 +32,9 @@ 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
+        file: gates/dev-exit
+        type: dev_exit
+        condition: Tests green, tree clean, no debug code, correct branch
 
     - name: verify
       agent: tea

package/pennyfarthing-dist/workflows/trivial.yaml

@@ -13,15 +13,19 @@ workflow:
     - name: setup
       agent: sm
       output: [session_file, branches]
+      gate:
+        file: gates/sm-setup-exit
+        type: sm_setup_exit
+        condition: Session file created with workflow, phase, and branch
 
     - name: implement
       agent: dev
       input: [session_file]
       output: [implementation]
       gate:
-        file: gates/tests-pass
-        type: tests_pass
-        condition: Existing tests still pass
+        file: gates/dev-exit
+        type: dev_exit
+        condition: Tests green, tree clean, no debug code, correct branch
 
     - name: review
       agent: reviewer

package/pennyfarthing_scripts/bc/cli.py

@@ -29,6 +29,7 @@ from pennyfarthing_scripts.bc.focus import (
     save_named_layout,
     set_panel_focus,
 )
+from pennyfarthing_scripts.bc.split import set_split_layout
 
 
 def _get_current_layout() -> dict | None:
@@ -206,6 +207,26 @@ def clear_layout(name: str, dry_run: bool):
         sys.exit(1)
 
 
+@bc.command("split")
+@click.argument("left")
+@click.argument("right")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def split_layout(left: str, right: str, dry_run: bool):
+    """Set split-pane layout with LEFT and RIGHT panels.
+
+    Example: pf bc split sprint diffs
+    """
+    if dry_run:
+        click.echo(json.dumps({"dry_run": True, "action": "split", "left": left, "right": right}))
+        return
+    result = set_split_layout(left, right)
+    if result["success"]:
+        click.echo(json.dumps({"success": True, "split": result["data"]}))
+    else:
+        click.echo(json.dumps({"success": False, "error": result["error"]}), err=True)
+        sys.exit(1)
+
+
 @bc.command("clear-all")
 @click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
 def clear_all_layouts(dry_run: bool):

package/pennyfarthing_scripts/bc/focus.py

@@ -34,6 +34,7 @@ VALID_PANELS = [
     "changed",
     "ac",
     "debug",
+    "progress",
     "settings",
     "tty",
 ]

package/pennyfarthing_scripts/bc/split.py

@@ -0,0 +1,52 @@
+"""Split layout management — read/write split config in config.local.yaml.
+
+Story 110-4: /bc split <left> <right> command support.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pennyfarthing_scripts.bc.focus import (
+    VALID_PANELS,
+    _read_config,
+    _write_config,
+)
+
+
+def set_split_layout(
+    left: str, right: str, project_dir: Path | None = None
+) -> dict:
+    """Set split layout in config.local.yaml.
+
+    Args:
+        left: Panel for left pane (must be in VALID_PANELS).
+        right: Panel for right pane (must be in VALID_PANELS).
+        project_dir: Override project root (for testing).
+
+    Returns:
+        {success: bool, data?: dict, error?: str}
+    """
+    if left not in VALID_PANELS:
+        return {
+            "success": False,
+            "error": f"Invalid panel '{left}'. Valid panels: {', '.join(VALID_PANELS)}",
+        }
+    if right not in VALID_PANELS:
+        return {
+            "success": False,
+            "error": f"Invalid panel '{right}'. Valid panels: {', '.join(VALID_PANELS)}",
+        }
+    if left == right:
+        return {
+            "success": False,
+            "error": f"Left and right panels must be different (both are '{left}'). Use same panel in single mode instead.",
+        }
+
+    try:
+        config_path, config = _read_config(project_dir)
+        config["split"] = {"left": left, "right": right}
+        _write_config(config_path, config)
+        return {"success": True, "data": {"left": left, "right": right}}
+    except Exception as exc:
+        return {"success": False, "error": str(exc)}

package/pennyfarthing_scripts/bikerack/context_meter_footer.py

@@ -4,11 +4,15 @@ Story 110-5: Context meter footer bar. Displays context window usage
 percentage with color-coded tier thresholds, always visible at the
 bottom of the layout.
 
+Story 110-12: Periodic refresh timer, event-driven redraws, and
+throttling for more frequent updates without performance degradation.
+
 Subscribes to /ws/context WebSocket channel.
 """
 
 from __future__ import annotations
 
+import time
 from typing import Any
 
 from rich.text import Text
@@ -35,34 +39,80 @@ class ContextMeterFooter(Static):
     #: WebSocket channel this footer subscribes to
     channel: str = "context"
 
+    #: Seconds between periodic refresh redraws
+    refresh_interval: float = 5.0
+
+    #: Minimum seconds between redraws (throttle)
+    min_redraw_interval: float = 0.25
+
     def __init__(self, client: Any = None, **kwargs: Any) -> None:
         super().__init__(**kwargs)
         self._client = client
         self._context_data: dict[str, Any] | None = None
         self._mounted = False
+        self._refresh_timer: Any = None
+        self._last_redraw_time: float = 0.0
+        self.last_update_time: float = 0.0
+
+    @property
+    def is_stale(self) -> bool:
+        """True if no context data has been received."""
+        return self._context_data is None
 
     def on_mount(self) -> None:
-        """Subscribe to context channel on mount."""
+        """Subscribe to context channel and start periodic refresh on mount."""
         self._mounted = True
         if self._client is not None:
             self._client.subscribe("context", self.handle_context_message)
+            self._client.on_state_change(self.on_connection_state_change)
+        try:
+            self._refresh_timer = self.set_interval(
+                self.refresh_interval, self.request_refresh
+            )
+        except RuntimeError:
+            # No running event loop (e.g. unit tests calling on_mount directly)
+            pass
 
     def on_unmount(self) -> None:
-        """Mark as unmounted so further messages are ignored."""
+        """Stop timer and mark as unmounted so further messages are ignored."""
         self._mounted = False
+        if self._refresh_timer is not None:
+            self._refresh_timer.stop()
 
     def on_context_meter_footer_meter_update(self, event: MeterUpdate) -> None:
         """Process MeterUpdate in Textual message context — triggers repaint."""
         self.update(event.content)
 
+    def request_refresh(self) -> None:
+        """Redraw from cached context data. Safe to call at any time."""
+        if not self._mounted or self._context_data is None:
+            return
+        try:
+            rendered = self.render_meter(self._context_data)
+            self.post_message(self.MeterUpdate(rendered))
+        except Exception:
+            pass
+
+    def on_connection_state_change(self, state: Any) -> None:
+        """Redraw on WebSocket reconnection."""
+        self.request_refresh()
+
     def handle_context_message(self, msg: dict[str, Any] | None) -> None:
-        """Process incoming /ws/context message."""
+        """Process incoming /ws/context message with throttling."""
         if not self._mounted or msg is None:
             return
         ctx = msg.get("context")
         if ctx is None:
             return
         self._context_data = ctx
+        self.last_update_time = time.monotonic()
+
+        # Throttle: skip redraw if too soon after last one
+        now = time.monotonic()
+        if now - self._last_redraw_time < self.min_redraw_interval:
+            return
+        self._last_redraw_time = now
+
         try:
             rendered = self.render_meter(ctx)
             self.post_message(self.MeterUpdate(rendered))