@pennyfarthing/core 11.2.1 → 11.3.1

package/pennyfarthing-dist/workflows/installation-check/steps/step-06-legacy.md

@@ -0,0 +1,94 @@
+# Step 6: Legacy Artifact Cleanup
+
+<step-meta>
+step: 6
+name: legacy
+workflow: installation-check
+agent: devops
+gate: true
+next: step-07-tools
+</step-meta>
+
+<purpose>
+Detect and clean up legacy artifacts from previous Pennyfarthing versions. These include old statusline scripts, persona configs at deprecated paths, legacy sidecar directories, and hook commands still using `.sh` scripts instead of `pf hooks` commands. This step has a gate because some fixes delete files.
+</purpose>
+
+<prerequisites>
+- Layout check completed (step 5)
+- User understands current vs legacy file locations
+</prerequisites>
+
+<instructions>
+1. Run the doctor command for the legacy category
+2. For each result, explain what the legacy artifact is and why it should be cleaned up:
+   - **legacy/.claude/scripts/statusline.sh**: Old statusline location that may shadow the proper `.pennyfarthing/scripts/misc/statusline.sh`.
+   - **legacy/.claude/persona-config.yaml**: Pre-v7 theme config. Should be migrated to `.pennyfarthing/config.local.yaml`.
+   - **legacy/.claude/project/agents/sidecars**: Pre-v8 sidecar location. Should be at `.pennyfarthing/sidecars/`.
+   - **legacy/sprint/sidecars**: Another pre-v8 sidecar location.
+   - **legacy/.claude/project/hooks/setup-env.sh**: Pre-v9 hook location. Should be at `.pennyfarthing/project/hooks/`.
+   - **settings/statusline-path**: settings.local.json references a legacy statusline script path.
+   - **legacy/hook-commands**: Hook entries in settings.local.json still use `.sh` script paths instead of `pf hooks` commands. The `.sh` scripts work (they're shims) but `pf hooks` is faster — no shell indirection.
+3. For each fix, explain what will be deleted or moved and whether it's reversible
+4. Present gate criteria — user must approve before files are deleted
+
+**IMPORTANT:** Legacy cleanup deletes files. The user may have customized legacy locations. Always explain what will be removed before applying fixes.
+</instructions>
+
+<actions>
+- Run: `pennyfarthing doctor --json --category legacy`
+- Check: No legacy artifacts at `.claude/scripts/`, `.claude/persona-config.yaml`
+- Check: No legacy sidecar directories
+- Check: Hook commands use `pf hooks` not `.sh` scripts
+</actions>
+
+<output>
+Present results:
+
+```markdown
+## Legacy Artifact Check Results
+
+| Artifact | Status | Detail |
+|----------|--------|--------|
+| statusline.sh | ... | ... |
+| persona-config.yaml | ... | ... |
+| agent sidecars | ... | ... |
+| sprint sidecars | ... | ... |
+| project hooks | ... | ... |
+| statusline path | ... | ... |
+| hook commands | ... | ... |
+
+### Cleanup Actions
+[For each warning, explain what the fix will do: delete, move, or update]
+```
+</output>
+
+<gate>
+## Completion Criteria
+- [ ] All legacy artifacts reviewed with user
+- [ ] User understands what each cleanup action will do
+- [ ] User approved or declined each destructive cleanup
+- [ ] No unapproved file deletions performed
+</gate>
+
+<collaboration-menu>
+- **[F] Fix** - Run `pennyfarthing doctor --fix --category legacy` to clean up (requires gate approval)
+- **[E] Explain** - Deep dive on a specific legacy artifact's history
+- **[C] Continue** - Approve cleanup and proceed to Tools check
+- **[R] Recheck** - Re-run after manual cleanup
+</collaboration-menu>
+
+<next-step>
+After user approves legacy cleanup, proceed to step-07-tools.md for Optional Tools verification.
+</next-step>
+
+## Failure Modes
+
+- Deleting customized legacy files without checking for user modifications
+- Not explaining that `.sh` shims still work (migration is optional optimization)
+- Removing sidecar directories before confirming new location has the content
+
+## Success Metrics
+
+- All legacy artifacts addressed (cleaned up or acknowledged)
+- User made informed decisions about each cleanup action
+- Gate approval recorded

package/pennyfarthing-dist/workflows/installation-check/steps/step-07-tools.md

@@ -0,0 +1,80 @@
+# Step 7: Optional Tools
+
+<step-meta>
+step: 7
+name: tools
+workflow: installation-check
+agent: devops
+gate: false
+next: step-08-summary
+</step-meta>
+
+<purpose>
+Check optional components that enhance but are not required for core Pennyfarthing functionality. These include the Cyclist visual terminal and the pf Python CLI.
+</purpose>
+
+<prerequisites>
+- Core installation verified (steps 1-6)
+</prerequisites>
+
+<instructions>
+1. Run the doctor command for the tools category
+2. For each result, explain what the tool provides and when it's needed:
+   - **cyclist/installed**: Cyclist is the Electron visual terminal for Pennyfarthing. It provides a graphical UI with panels for sprint tracking, diffs, workflow visualization, and more. Not required for CLI-only usage.
+   - **cyclist/node-pty**: node-pty powers the terminal panel in Cyclist. Without it, the embedded terminal won't work but other panels still function.
+   - **cyclist/spawn-helper**: The native binary that node-pty uses to spawn processes. Must have execute permission on macOS/Linux. Missing permission causes `posix_spawnp` failures.
+   - **tools/pf-cli**: The Python `pf` command provides agent activation (`pf agent start`), hook dispatch (`pf hooks`), and sprint management. Required for agent workflows. Installable via `uv tool install pennyfarthing-scripts` or `pipx install pennyfarthing-scripts`.
+3. For missing tools, explain whether they're required or optional based on the user's workflow
+4. Present the collaboration menu
+</instructions>
+
+<actions>
+- Run: `pennyfarthing doctor --json --category tools`
+- Check: Cyclist package location and node-pty health
+- Check: `pf` CLI is available and reports a version
+</actions>
+
+<output>
+Present results:
+
+```markdown
+## Optional Tools Check Results
+
+### Cyclist Visual Terminal
+| Check | Status | Detail |
+|-------|--------|--------|
+| installed | ... | ... |
+| node-pty | ... | ... |
+| spawn-helper | ... | ... |
+
+### Python CLI
+| Check | Status | Detail |
+|-------|--------|--------|
+| pf CLI | ... | ... |
+
+### Recommendation
+[Based on results, recommend which tools to install for the user's use case]
+```
+</output>
+
+<collaboration-menu>
+- **[F] Fix** - Run `pennyfarthing doctor --fix --category tools` to fix permissions or install pf CLI
+- **[E] Explain** - Deep dive on a specific tool's purpose
+- **[C] Continue** - Proceed to Summary
+- **[R] Recheck** - Re-run after installing tools
+</collaboration-menu>
+
+<next-step>
+After reviewing tools, proceed to step-08-summary.md for the final health report.
+</next-step>
+
+## Failure Modes
+
+- Installing Cyclist when only CLI usage is needed (unnecessary complexity)
+- spawn-helper permission issues after pnpm install (common on macOS)
+
+## Success Metrics
+
+- User understands which tools they need
+- Required tools (pf CLI) are installed
+- Optional tools have clear install path if wanted

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/project-setup/steps/step-01-discover.md

@@ -20,6 +20,53 @@ Discover the project structure, detect repositories, identify tech stack, and ga
 - User-confirmed discovery ready for repos.yaml generation
 </output>
 
+## PRE-FLIGHT: Environment Check
+
+Before discovery, verify the environment is clean.
+
+### Check for Global `pf` Installation
+
+A globally installed `pf` CLI causes version drift between projects. All `pf`
+invocations should go through `uv run` via the shell shims in `.pennyfarthing/scripts/`.
+
+```bash
+# Check for global pf binary
+which pf 2>/dev/null
+```
+
+**If `which pf` returns a path**, the user has a stale global install. Guide them through removal:
+
+1. **Check the source** of the global install:
+   ```bash
+   which pf
+   head -3 "$(which pf)" 2>/dev/null
+   pip3 show pennyfarthing-scripts 2>/dev/null | grep -E "^(Version|Location|Editable)"
+   uv tool list 2>/dev/null | grep pennyfarthing
+   ```
+
+2. **Remove based on source:**
+
+   | Source | Command |
+   |--------|---------|
+   | `uv tool` | `uv tool uninstall pennyfarthing-scripts` |
+   | `pip` (Homebrew Python) | `pip3 uninstall pennyfarthing-scripts --break-system-packages -y` |
+   | `pip` (venv/system) | `pip3 uninstall pennyfarthing-scripts -y` |
+   | `pipx` | `pipx uninstall pennyfarthing-scripts` |
+
+3. **Verify removal:**
+   ```bash
+   hash -r  # Clear shell cache
+   which pf 2>/dev/null && echo "STILL INSTALLED — check for multiple installs" || echo "Clean"
+   ```
+
+4. **Explain to user:** Pennyfarthing hooks use `uv run` to resolve `pf` from the
+   local project's `pyproject.toml`. This ensures each project runs its own version
+   of the CLI without cross-project contamination. No global install is needed.
+
+**If `which pf` returns nothing**, the environment is clean — continue to discovery.
+
+---
+
 ## DISCOVERY TASKS
 
 ### 1. Detect Repository Structure

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-team.yaml

@@ -0,0 +1,80 @@
+# TDD Team Workflow - TDD with Native Team Collaboration
+#
+# When to use: Best for 5+ point feature stories where sustained parallel
+# collaboration provides more value than periodic tandem consultation.
+# Use this instead of tdd-tandem when teammates need to work alongside the
+# lead for the full phase — e.g., Architect reviewing patterns as Dev
+# implements, not just answering a single question.
+#
+# Compared to tdd-tandem: Tandem spawns a Haiku subagent for a single
+# request/response exchange. Team mode spawns full teammate sessions that
+# work in parallel with the lead for the entire phase duration.
+#
+# Team pairings:
+#   - GREEN phase: Dev (lead) + Architect — Architect reviews implementation
+#     approach and patterns in real-time via SendMessage
+#   - REVIEW phase: Reviewer (lead) + Architect — Architect validates
+#     architectural patterns during code review
+#
+# Fallback: When native teams are unavailable (non-interactive mode, feature
+# flag off, or CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS not set), phases with
+# team blocks fall back to solo execution. The lead agent works alone —
+# consider using tdd-tandem as an alternative that works in all modes.
+#
+# Flow: SM → TEA → Dev (+Architect) → Reviewer (+Architect) → SM
+
+workflow:
+  name: tdd-team
+  description: TDD with native team collaboration — architect pairing on green and review phases
+  version: "1.0.0"
+
+  phases:
+    - name: setup
+      agent: sm
+      output: [session_file, branches, story_context]
+
+    - name: red
+      agent: tea
+      input: [session_file, story_context]
+      output: [failing_tests]
+      gate:
+        file: gates/tests-fail
+        type: tests_fail
+        condition: All acceptance criteria have test coverage
+
+    - name: green
+      agent: dev
+      input: [failing_tests, story_context]
+      output: [implementation, passing_tests]
+      gate:
+        file: gates/tests-pass
+        type: tests_pass
+        condition: All tests passing, no skipped tests
+      team:
+        teammates:
+          - agent: architect
+            task: "Review implementation approach and patterns. Send observations via SendMessage as Dev works."
+
+    - name: review
+      agent: reviewer
+      input: [implementation, passing_tests]
+      output: [approval]
+      gate:
+        file: gates/approval
+        type: approval
+        condition: Code review approved, no blocking issues
+      team:
+        teammates:
+          - agent: architect
+            task: "Validate architectural patterns and coupling. Flag concerns via SendMessage."
+
+    - name: finish
+      agent: sm
+      input: [approval]
+      output: [archived_session, story_summary]
+
+  triggers:
+    tags: [team, tdd-team]
+    points:
+      min: 5
+    default: false

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/__init__.py

@@ -14,4 +14,4 @@ Modules:
     swebench: SWE-bench patch parsing and scenario utilities
 """
 
-__version__ = "7.6.1"
+__version__ = "8.1.0"

package/pennyfarthing_scripts/bc/cli.py

@@ -29,12 +29,13 @@ 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:
     """Fetch the current layout from a running Cyclist or BikeRack server.
 
-    Reads .wheelhub-port (shared by both Cyclist and BikeRack) and fetches
+    Reads .bikerack-port (shared by both Cyclist and BikeRack) and fetches
     the layout endpoint.
 
     Returns:
@@ -45,7 +46,7 @@ def _get_current_layout() -> dict | None:
     root = _get_root()
 
     candidates = [
-        (root / ".wheelhub-port", "/api/settings/bikerack-layout"),
+        (root / ".bikerack-port", "/api/settings/bikerack-layout"),
     ]
 
     for port_file, endpoint in candidates:
@@ -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)}