@pennyfarthing/core 11.0.0 → 11.1.1

package/pennyfarthing-dist/guides/bikerack.md

@@ -0,0 +1,128 @@
+# BikeRack
+
+<info>
+Standalone panel viewer for CLI-first developers. BikeRack runs WheelHub (the Express/WebSocket server) without Cyclist's conversation UI, serving dashboard panels in a browser while Claude Code runs in your own terminal.
+</info>
+
+## Overview
+
+Cyclist bundles the conversation UI and dashboard panels into one Electron app. BikeRack decouples them: you get the panels (sprint status, git diffs, workflow state, etc.) in a browser, and Claude Code stays in your terminal.
+
+```
+┌─────────────────┐       ┌──────────────────────┐
+│  Claude CLI      │       │  WheelHub (BikeRack)  │
+│  (your terminal) │──────▶│  Port 2898            │
+│                  │ OTEL  │  No ClaudeService     │
+│                  │ files │  16 WS channels       │
+└─────────────────┘       └──────────┬─────────────┘
+                                     │ HTTP + WS
+                                     ▼
+                          ┌──────────────────────┐
+                          │  Browser              │
+                          │  Dockview layout      │
+                          │  or ?panel=X routing  │
+                          └──────────────────────┘
+```
+
+## Quick Start
+
+```bash
+# Launch BikeRack + Claude CLI together
+pf bikerack start
+
+# Or via just recipe
+just bikerack
+
+# With a specific project directory
+just bikerack dir=/path/to/project
+
+# Stop a running instance
+pf bikerack stop
+
+# Check status
+pf bikerack status
+```
+
+BikeRack opens a browser with the Dockview panel layout. Claude CLI runs in the foreground. When Claude exits, BikeRack shuts down automatically via `trap EXIT`.
+
+## Panel Routing
+
+BikeRack supports two modes:
+
+**Dockview layout** (default) — full multi-panel workspace at `http://localhost:{port}/bikerack`
+
+**Standalone panel** — single panel full-screen via query param:
+
+| URL | Panel |
+|-----|-------|
+| `?panel=sprint` | Sprint status |
+| `?panel=git` | Git operations |
+| `?panel=diffs` | Diff viewer |
+| `?panel=workflow` | Workflow state |
+| `?panel=changed` | Changed files |
+| `?panel=ac` | Acceptance criteria |
+| `?panel=todos` | Task list |
+| `?panel=audit` | Audit log |
+| `?panel=background` | Background jobs |
+| `?panel=debug` | Debug/prime context |
+| `?panel=bikelane` | BikeLane workflow |
+| `?panel=settings` | Settings |
+| `?panel=portrait` | Agent portrait |
+
+## How It Works
+
+1. **Launcher** (`pf bikerack start`) starts WheelHub with `IS_BIKERACK=1`
+2. **WheelHub** listens on port 2898 (separate from Cyclist's 1898)
+3. **ClaudeService is skipped** — no `/ws/claude` WebSocket channel
+4. **OTEL telemetry** flows from Claude CLI to WheelHub's OTLP receiver
+5. **File watchers** detect changes to `.session/`, `sprint/`, and git state
+6. **Panels** render as React components consuming WebSocket data — identical components to Cyclist
+
+### Mode Detection
+
+```typescript
+// Server-side
+import { isBikeRackMode } from './server.js';
+if (isBikeRackMode()) { /* skip Claude-specific setup */ }
+```
+
+Client-side detection is URL-based: the presence of `?panel=X` triggers standalone rendering.
+
+### Port and PID Files
+
+| File | Purpose |
+|------|---------|
+| `.bikerack-port` | Port number, written after `server.listen()` — readiness signal |
+| `.bikerack-pid` | WheelHub PID, written by launcher — enables `pf bikerack stop` |
+
+Both are deleted on shutdown. Separate from Cyclist's `.cyclist-port` and `.cyclist-pid` for coexistence.
+
+## Layout Persistence
+
+Save and restore BikeRack panel layouts:
+
+```bash
+pf bc save my-layout      # Save current layout
+pf bc load my-layout      # Restore a saved layout
+pf bc list                 # List saved layouts
+```
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `packages/cyclist/src/bikerack.ts` | BikeRack WheelHub entry point |
+| `packages/core/src/public/components/BikeRackWorkspace.tsx` | Dockview layout for BikeRack |
+| `packages/core/src/public/components/BikeRackIndex.tsx` | Panel listing index page |
+| `packages/core/src/public/components/StandalonePanel.tsx` | `?panel=X` routing + `PANEL_REGISTRY` |
+| `pennyfarthing_scripts/bikerack/cli.py` | `pf bikerack` launcher CLI |
+
+## Constraints
+
+- **No MessagePanel** — Claude conversation stays in your terminal. This is intentional.
+- **Single session** — one Claude CLI per BikeRack instance (multi-session is deferred).
+- **Bell/Relay/Reflector are dormant** — these features require ClaudeService and are skipped in BikeRack mode.
+
+<info>
+**ADR:** `docs/adr/0024-bikerack-mode.md`
+</info>

package/pennyfarthing-dist/guides/brownfield-tools.md

@@ -0,0 +1,133 @@
+# Brownfield & Code Analysis Tools
+
+<info>
+CLI tools for analyzing existing codebases. Identify change hotspots, complexity bottlenecks, dead code, stale dependencies, and code markers (TODO/FIXME). Each tool produces table, JSON, or CSV output and has a corresponding WheelHub API route for panel integration.
+</info>
+
+## Overview
+
+All tools are available under `pf debug` and share a consistent interface: `--format` (table/json/csv), `--output` (file), `--top` (result count), `--exclude` (patterns), and `--repo` (target).
+
+## Tools
+
+### Hotspots
+
+Find files that change most frequently — high churn often correlates with bugs and complexity.
+
+```bash
+# Full analysis (files + directories)
+pf debug hotspots analyze
+
+# File-level only
+pf debug hotspots files
+
+# Directory-level only
+pf debug hotspots dirs
+
+# Options
+pf debug hotspots analyze --days 90 --top 20 --repo pennyfarthing
+pf debug hotspots analyze --format json --output hotspots.json
+pf debug hotspots analyze --exclude "*.test.ts" --branch main
+pf debug hotspots analyze --skip-type orchestrator
+```
+
+### Complexity
+
+Measure code complexity metrics across files.
+
+```bash
+pf debug complexity analyze
+pf debug complexity analyze --path ./packages/core/src
+pf debug complexity analyze --top 30 --format csv
+```
+
+### Dead Code
+
+Find unused code: stale files with no recent commits, and unused TypeScript exports.
+
+```bash
+# Files with no recent commits (default: 180 days)
+pf debug deadcode stale
+pf debug deadcode stale --days 90 --repo pennyfarthing
+
+# Unused TypeScript exports (via ts-prune)
+pf debug deadcode exports
+pf debug deadcode exports --repo pennyfarthing --format json
+```
+
+### Code Markers
+
+Detect TODO, FIXME, HACK, and XXX comments with git blame data.
+
+```bash
+# Full analysis with blame data
+pf debug codemarkers analyze
+
+# Only stale markers (older than threshold)
+pf debug codemarkers stale --days 90
+
+# Summary counts by type
+pf debug codemarkers summary
+
+# Deprecated symbol detection
+pf debug codemarkers deprecations
+```
+
+### Dependencies
+
+Analyze dependency staleness and security advisories.
+
+```bash
+pf debug dependencies analyze
+pf debug dependencies analyze --path ./pennyfarthing --format json
+```
+
+### Health Score
+
+Composite health score across all dimensions (hotspots, complexity, dead code, dependencies, markers).
+
+```bash
+pf debug healthscore analyze
+pf debug healthscore analyze --no-cache   # Bypass cache
+pf debug healthscore analyze --format json --output health.json
+```
+
+## Common Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--repo NAME` | Analyze a single named repo from `repos.yaml` | All repos |
+| `--path DIR` | Analyze a standalone directory | Current directory |
+| `--format FMT` | Output format: `table`, `json`, `csv` | `table` |
+| `--output FILE` | Write output to file | stdout |
+| `--top N` | Number of top results | 20 |
+| `--exclude PAT` | Exclude patterns (repeatable) | — |
+| `--days N` | Time window for analysis | Varies by tool |
+
+## WheelHub API Routes
+
+Each tool has a corresponding HTTP API in WheelHub for panel integration:
+
+| Route | Tool |
+|-------|------|
+| `/api/hotspots` | Hotspot analysis |
+| `/api/complexity` | Complexity metrics |
+| `/api/dead-code` | Dead code detection |
+| `/api/dependencies` | Dependency health |
+| `/api/code-markers` | Code marker scan |
+| `/api/health-score` | Composite health score |
+
+These power the **HotspotsPanel** in Cyclist and BikeRack.
+
+## Key Files
+
+| Directory | Purpose |
+|-----------|---------|
+| `pennyfarthing_scripts/hotspots/` | Hotspot analysis (analyze, formatters, models) |
+| `pennyfarthing_scripts/complexity/` | Complexity analysis |
+| `pennyfarthing_scripts/deadcode/` | Dead code detection |
+| `pennyfarthing_scripts/dependencies/` | Dependency analysis |
+| `pennyfarthing_scripts/codemarkers/` | Code marker detection |
+| `pennyfarthing_scripts/healthscore/` | Composite health score |
+| `pennyfarthing_scripts/brownfield/` | Brownfield codebase discovery |
+| `packages/core/src/server/api/` | WheelHub API routes |

package/pennyfarthing-dist/guides/command-tag-taxonomy.md

@@ -65,7 +65,7 @@
 - `<agent-activation>` — Required to show activation
 - `<instructions>` — Required for agent behavior
 
-**Script-Based Commands (e.g., /check, /run-ci)**
+**Script-Based Commands (e.g., /check, /pf-ci run)**
 - `<execution>` — Required with options
 - `<reference>` — Links to scripts
 
@@ -78,7 +78,7 @@
 - `<when-not-to-use>` — When NOT to pick this
 - `<related>` — Alternatives to consider
 
-**Workflow/Phase Commands (e.g., /sprint, /release)**
+**Workflow/Phase Commands (e.g., /sprint, /pf-git release)**
 - `<workflow>` — Phase breakdown
 - `<commands>` or subcommand table — Available subcommands
 

package/pennyfarthing-dist/guides/gate-schema.md

@@ -0,0 +1,227 @@
+# Gate File Schema
+
+<info>
+Gate files define quality checks that run at workflow phase boundaries. A gate file is a markdown document containing XML tags that instruct a subagent to evaluate pass/fail criteria before allowing a workflow to proceed.
+</info>
+
+## File Location
+
+Gate files are discovered in this order (first match wins):
+
+1. `.pennyfarthing/gates/{name}.md` — project-local override
+2. `pennyfarthing-dist/gates/{name}.md` — built-in gates
+
+## Schema
+
+```xml
+<gate name="gate-name" model="haiku">
+
+<purpose>
+What this gate checks and why it matters.
+</purpose>
+
+<pass>
+Instructions for the subagent when all checks succeed.
+Must include a GATE_RESULT YAML block with status: pass.
+</pass>
+
+<fail>
+Instructions for the subagent when any check fails.
+Must include a GATE_RESULT YAML block with status: fail.
+Include recovery guidance so the agent knows how to fix the issue.
+</fail>
+
+</gate>
+```
+
+### Required Elements
+
+| Element | Description |
+|---------|-------------|
+| `<gate name="...">` | Root element. `name` attribute is required, must be unique. |
+| `<purpose>` | Describes what the gate checks. Helps agents understand context. |
+| `<pass>` | Instructions when checks succeed. Must template a `GATE_RESULT` with `status: pass`. |
+| `<fail>` | Instructions when checks fail. Must template a `GATE_RESULT` with `status: fail`. |
+
+### Optional Attributes
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `model` | `haiku` | LLM model for the gate subagent. Use `haiku` for fast, cheap checks. |
+
+### Nested Gates
+
+Gates can contain nested `<gate>` elements for compound checks. Maximum nesting depth is **3 levels** (root = level 0).
+
+```xml
+<gate name="release-ready" model="haiku">
+  <purpose>Verify release readiness</purpose>
+  <pass>All release checks pass</pass>
+  <fail>Release blocked</fail>
+
+  <gate name="tests-pass" model="haiku">
+    <purpose>All tests green</purpose>
+    <pass>Tests passing</pass>
+    <fail>Tests failing</fail>
+  </gate>
+
+  <gate name="lint-clean" model="haiku">
+    <purpose>No lint errors</purpose>
+    <pass>Lint clean</pass>
+    <fail>Lint errors found</fail>
+  </gate>
+</gate>
+```
+
+**Rules for nesting:**
+- Maximum depth: 3 (root at depth 0, deepest child at depth 3)
+- Gate names must be unique within the file — no duplicates, no cycles
+- Sibling gates at the same depth may share a parent but not a name
+
+## GATE_RESULT Contract
+
+Gate subagents must return a `GATE_RESULT` YAML block. The runtime uses default-deny: if no parseable result is found, the gate fails.
+
+```yaml
+GATE_RESULT:
+  status: pass | fail
+  gate: "gate-name"
+  message: "Human-readable summary"
+  checks:
+    - name: check-name
+      status: pass | fail
+      detail: "What was checked and the outcome"
+  recovery:                    # Only on fail
+    - "Step to fix issue 1"
+    - "Step to fix issue 2"
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `status` | Yes | `pass` or `fail` — strict enum, no other values |
+| `gate` | No | Gate name (for traceability) |
+| `message` | Yes | One-line summary of the result |
+| `checks` | No | Array of individual check results |
+| `recovery` | No | Array of fix instructions (fail only) |
+
+## Working Example
+
+Here is a complete gate file that checks whether documentation exists for new exports:
+
+```xml
+<gate name="docs-check" model="haiku">
+
+<purpose>
+Verify that all new public exports have corresponding documentation.
+Runs after the Dev phase to catch undocumented APIs before review.
+</purpose>
+
+<pass>
+Check the git diff for new export statements. For each new export,
+verify a matching entry exists in the relevant guide or README.
+
+If all exports are documented, return:
+
+GATE_RESULT:
+  status: pass
+  gate: docs-check
+  message: "All new exports documented"
+  checks:
+    - name: export-coverage
+      status: pass
+      detail: "{N} new exports, all documented"
+</pass>
+
+<fail>
+If any new export lacks documentation, list the gaps:
+
+GATE_RESULT:
+  status: fail
+  gate: docs-check
+  message: "Undocumented exports found"
+  checks:
+    - name: export-coverage
+      status: fail
+      detail: "{N} exports missing documentation"
+  recovery:
+    - "Add documentation for: {list of undocumented exports}"
+    - "Update the relevant guide in pennyfarthing-dist/guides/"
+</fail>
+
+</gate>
+```
+
+## Workflow Integration
+
+Gates are referenced in workflow YAML files via the `gate.file` field:
+
+```yaml
+workflow:
+  name: my-workflow
+  phases:
+    - name: implement
+      agent: dev
+      gate:
+        file: gates/tests-pass    # References pennyfarthing-dist/gates/tests-pass.md
+        condition: All tests passing
+```
+
+The `gate.file` value is resolved by the gate file discovery algorithm (project-local first, built-in fallback).
+
+### Built-in Gate Types vs File Gates
+
+| Approach | When to Use |
+|----------|-------------|
+| `gate.type` (built-in) | Standard checks: `tests_pass`, `tests_fail`, `approval`, `manual` |
+| `gate.file` (file-based) | Custom checks with specific pass/fail logic |
+| Both | File-based gate with type for fallback categorization |
+
+## Validation
+
+Validate gate files before use:
+
+```bash
+pf gate validate path/to/gate-file.md
+```
+
+The validator checks:
+- **Schema:** `<gate>` tag with `name` attribute, `<purpose>`, `<pass>`, `<fail>` present and non-empty
+- **Depth:** Nesting does not exceed 3 levels
+- **Cycles:** No duplicate gate names (which would indicate cycles in nested structures)
+- **Completeness:** Every gate (including nested) has all required elements
+
+All errors are reported at once — fix everything in a single pass.
+
+On success, the validator prints a structure summary:
+
+```
+Gate 'tests-pass' is valid
+  Model: haiku
+  Depth: 0 (no nesting)
+  Children: 0
+```
+
+## Best Practices
+
+1. **Keep gates focused.** One gate = one quality dimension. Use nesting for compound checks, not unrelated concerns.
+
+2. **Write actionable fail instructions.** The `<fail>` block should tell the agent exactly how to diagnose and fix the issue. Include specific commands to run and files to check.
+
+3. **Template the GATE_RESULT.** Include the exact YAML structure in both `<pass>` and `<fail>` blocks so the subagent knows the expected output format.
+
+4. **Use `haiku` for speed.** Gate checks should be fast and cheap. Only use a larger model if the gate requires deep reasoning.
+
+5. **Include checks for traceability.** The `checks` array in GATE_RESULT lets the calling agent see exactly what passed or failed without re-running the gate.
+
+6. **Add recovery steps.** The `recovery` array in failed results gives the agent a clear path to fix issues and retry.
+
+7. **Test with the validator.** Run `pf gate validate` on your gate file before referencing it in a workflow.
+
+## Related
+
+- [Workflow Schema](workflow-schema.md) — How gates are referenced in workflow definitions
+- [Approval Gates Pattern](patterns/approval-gates-pattern.md) — Pattern for approval-style gates
+- Story 106-2: Gate subagent runner with GATE_RESULT contract
+- Story 106-4: Gate file discovery and resolution
+- Story 107-1: Gate schema validation at parse time
+- Story 107-2: Acyclic validation and depth limit enforcement

package/pennyfarthing-dist/guides/gates.md

@@ -0,0 +1,120 @@
+# Workflow Gates
+
+<info>
+Conditional checks that block or allow workflow phase transitions. Gates enforce quality thresholds — tests must pass, reviews must be approved, instructions must be unambiguous — before an agent can hand off to the next phase.
+</info>
+
+## Overview
+
+Gates live in `pennyfarthing-dist/gates/` and are referenced by workflow YAML files via the `gate.file` field on phase definitions. When an agent finishes a phase, the handoff CLI resolves the gate, spawns a Haiku subagent to evaluate it, and blocks the transition if the gate fails.
+
+## Built-in Gates
+
+| Gate | File | Purpose | Used By |
+|------|------|---------|---------|
+| **tests-pass** | `gates/tests-pass.md` | Verify all tests pass, working tree clean, correct branch | Dev → Reviewer transitions |
+| **tests-fail** | `gates/tests-fail.md` | Verify tests are RED (failing) with AC coverage | TEA → Dev transitions |
+| **approval** | `gates/approval.md` | Verify reviewer has issued explicit APPROVED verdict | Reviewer → SM transitions |
+| **confidence-sm** | `gates/confidence-sm.md` | Check if user instruction to SM is ambiguous | SM entry gate |
+
+## Gate File Format
+
+Gates use XML-style tags with `<pass>` and `<fail>` sections:
+
+```xml
+<gate name="tests-pass" model="haiku">
+
+<purpose>
+What this gate checks and why.
+</purpose>
+
+<pass>
+Instructions for the gate subagent when checks succeed.
+Must return a GATE_RESULT YAML block with status: pass.
+</pass>
+
+<fail>
+Instructions for diagnosing failures.
+Must return a GATE_RESULT YAML block with status: fail
+and actionable recovery guidance.
+</fail>
+
+</gate>
+```
+
+## GATE_RESULT Contract
+
+Gate subagents must return a structured YAML result:
+
+```yaml
+GATE_RESULT:
+  status: pass | fail
+  gate: gate-name
+  message: "Human-readable summary"
+  checks:
+    - name: check-name
+      status: pass | fail
+      detail: "What was checked and the result"
+  recovery:          # Only on fail
+    - "Actionable step to fix the issue"
+```
+
+## Workflow Integration
+
+Gates are declared in workflow YAML on phase transitions:
+
+```yaml
+phases:
+  green:
+    agent: dev
+    gate:
+      file: tests-pass     # References gates/tests-pass.md
+    next: review
+```
+
+## Agent Exit Protocol
+
+Agents interact with gates through the handoff CLI during their exit sequence:
+
+```
+1. Agent writes assessment to session file
+2. pf handoff resolve-gate {story-id} {workflow} {phase}
+   → Reads workflow YAML, finds gate for current phase
+   → Returns RESOLVE_RESULT: {status: ready|skip|blocked, gate_file: ...}
+3. If ready → spawn Haiku subagent with gate file → GATE_RESULT
+4. If GATE_RESULT.status == fail → fix issues, retry (max 3)
+5. If GATE_RESULT.status == pass → continue to complete-phase
+6. pf handoff complete-phase {story-id} {workflow} {from} {to} {gate-type}
+7. pf handoff marker {next-agent}
+```
+
+If a phase has no `gate:` block, `resolve-gate` returns `status: skip` and the agent proceeds directly to `complete-phase`.
+
+## Gate Evaluations
+
+Extended evaluation criteria can live in `gates/evaluations/`:
+
+| File | Purpose |
+|------|---------|
+| `evaluations/confidence-sm.md` | Detailed rubric for SM confidence scoring |
+
+## Creating Custom Gates
+
+1. Create `pennyfarthing-dist/gates/my-gate.md` following the XML format above
+2. Reference it in a workflow phase: `gate: { file: my-gate }`
+3. The gate runner discovers files in the `gates/` directory by name
+
+Gates run as Haiku subagents — keep instructions focused and evaluation criteria concrete.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `pennyfarthing-dist/gates/*.md` | Gate definitions |
+| `pennyfarthing_scripts/handoff/gate_runner.py` | Spawns gate subagents |
+| `pennyfarthing_scripts/handoff/gate_file.py` | Gate file discovery and resolution |
+| `pennyfarthing_scripts/handoff/resolve_gate.py` | Resolves gate for a workflow phase |
+
+<info>
+**ADR:** `docs/adr/0025-script-first-gate-extraction.md`
+</info>