@pennyfarthing/core 10.4.0 → 11.0.0-alpha.0

package/pennyfarthing-dist/scripts/portraits/generate-portraits.sh

@@ -20,18 +20,30 @@ while [[ ! -d "$_dir/.pennyfarthing" ]] && [[ ! -d "$_dir/pennyfarthing-dist" ]]
 done
 PROJECT_ROOT="$_dir"
 
-# If we're in the pennyfarthing repo itself, look for .venv there
-# If we're in a user project, .venv should be at project root
-VENV_DIR="$PROJECT_ROOT/.venv"
+# Find Python venv - check multiple locations
+# Priority: VENV_DIR env var > project .venv > ~/.venvs/sd > ~/.venv
 PYTHON_SCRIPT="$SCRIPT_DIR/generate-portraits.py"
 
+if [[ -z "${VENV_DIR:-}" ]]; then
+    if [[ -d "$PROJECT_ROOT/.venv" ]]; then
+        VENV_DIR="$PROJECT_ROOT/.venv"
+    elif [[ -d "$HOME/.venvs/sd" ]]; then
+        VENV_DIR="$HOME/.venvs/sd"
+    elif [[ -d "$HOME/.venv" ]]; then
+        VENV_DIR="$HOME/.venv"
+    fi
+fi
+
 # Check venv exists
-if [[ ! -d "$VENV_DIR" ]]; then
-    echo "Error: Virtual environment not found at $VENV_DIR"
-    echo "Create it with: python3 -m venv .venv"
+if [[ -z "${VENV_DIR:-}" ]] || [[ ! -d "$VENV_DIR" ]]; then
+    echo "Error: Virtual environment not found"
+    echo "Searched: $PROJECT_ROOT/.venv, ~/.venvs/sd, ~/.venv"
+    echo "Or set VENV_DIR=/path/to/venv"
+    echo "Create with: python3 -m venv .venv"
     echo "Then install: pip install diffusers transformers accelerate torch pillow pyyaml"
     exit 1
 fi
+echo "Using venv: $VENV_DIR"
 
 # Check Python script exists
 if [[ ! -f "$PYTHON_SCRIPT" ]]; then

package/pennyfarthing-dist/scripts/sprint/README.md

@@ -34,7 +34,7 @@ pf sprint epic promote epic-41
 
 ## Ownership
 
-- **Primary users:** SM agent, `/sprint` skill
+- **Primary users:** SM agent, `/pf-sprint` skill
 - **Maintained by:** Core Pennyfarthing team
 
 ## Migration Note

package/pennyfarthing-dist/scripts/story/README.md

@@ -19,5 +19,5 @@ Scripts for story creation and management.
 
 ## Ownership
 
-- **Primary users:** SM agent, `/sprint story` commands
+- **Primary users:** SM agent, `/pf-sprint story` commands
 - **Maintained by:** Core Pennyfarthing team

package/pennyfarthing-dist/scripts/workflow/README.md

@@ -24,5 +24,5 @@ pf sprint story finish MSSCI-12345
 
 ## Ownership
 
-- **Primary users:** SM agent, `/workflow` skill
+- **Primary users:** SM agent, `/pf-workflow` skill
 - **Maintained by:** Core Pennyfarthing team

package/pennyfarthing-dist/skills/pf-bc/examples.md

@@ -0,0 +1,83 @@
+# BC (Panel Focus) — Examples
+
+## Setting Focus
+
+```bash
+# Focus on Sprint panel
+pf bc sprint
+
+# Focus on Diffs panel
+pf bc diffs
+
+# Focus on Acceptance Criteria
+pf bc ac
+
+# Focus on Git panel
+pf bc git
+
+# Preview without changing
+pf bc sprint --dry-run
+```
+
+## Clearing Focus
+
+```bash
+# Remove focus setting
+pf bc reset
+
+# Preview
+pf bc reset --dry-run
+```
+
+## Named Layouts
+
+```bash
+# Save current layout as "normal"
+pf bc save normal
+
+# Save current layout as "review"
+pf bc save review
+
+# Save current layout as "debug"
+pf bc save debug
+
+# List all saved layouts
+pf bc list
+
+# Switch to review layout
+pf bc load review
+
+# Switch back to normal
+pf bc load normal
+
+# Delete a specific layout
+pf bc clear review
+
+# Delete all layouts
+pf bc clear-all
+```
+
+## Common Workflows
+
+### During code review
+```bash
+pf bc save normal          # Save current layout first
+pf bc diffs                # Focus on diffs
+# ... do review ...
+pf bc load normal          # Restore normal layout
+```
+
+### Debugging session
+```bash
+pf bc save normal
+pf bc debug                # Focus debug panel
+# ... debug ...
+pf bc reset                # Clear focus
+```
+
+### Sprint planning
+```bash
+pf bc sprint               # Focus sprint panel
+# ... review backlog ...
+pf bc reset
+```

package/pennyfarthing-dist/skills/pf-bc/skill.md

@@ -0,0 +1,51 @@
+---
+name: bc
+description: |
+  Panel focus management for Cyclist. Set which panel BikeRack/Cyclist should focus on,
+  or clear the focus setting. Save and load named layouts. Writes to `.pennyfarthing/config.local.yaml`.
+args: "[panel|reset|save|load|list|clear|clear-all] [name]"
+---
+
+# /bc - Panel Focus & Layout Management
+
+Set or clear the focused panel in Cyclist/BikeRack. Save and restore named layouts.
+
+## Quick Reference
+
+### Panel Focus
+
+| Command | CLI | Purpose |
+|---------|-----|---------|
+| `/bc sprint` | `pf bc sprint [--dry-run]` | Focus Sprint panel |
+| `/bc git` | `pf bc git [--dry-run]` | Focus Git panel |
+| `/bc diffs` | `pf bc diffs [--dry-run]` | Focus Diffs panel |
+| `/bc todo` | `pf bc todo [--dry-run]` | Focus Todo panel |
+| `/bc workflow` | `pf bc workflow [--dry-run]` | Focus Workflow panel |
+| `/bc background` | `pf bc background [--dry-run]` | Focus Background panel |
+| `/bc audit-log` | `pf bc audit-log [--dry-run]` | Focus Audit Log panel |
+| `/bc changed` | `pf bc changed [--dry-run]` | Focus Changed panel |
+| `/bc ac` | `pf bc ac [--dry-run]` | Focus Acceptance Criteria panel |
+| `/bc debug` | `pf bc debug [--dry-run]` | Focus Debug panel |
+| `/bc settings` | `pf bc settings [--dry-run]` | Focus Settings panel |
+| `/bc reset` | `pf bc reset [--dry-run]` | Clear focus setting |
+
+### Named Layouts
+
+| Command | CLI | Purpose |
+|---------|-----|---------|
+| `/bc save <name>` | `pf bc save <name> [--dry-run]` | Save current layout from running server |
+| `/bc load <name>` | `pf bc load <name> [--dry-run]` | Load a saved layout |
+| `/bc list` | `pf bc list` | List all saved layouts |
+| `/bc clear <name>` | `pf bc clear <name> [--dry-run]` | Delete a saved layout |
+| `/bc clear-all` | `pf bc clear-all [--dry-run]` | Delete all saved layouts |
+
+### Notes
+
+- The `message` panel (sacred center) is not focusable
+- Config written to `.pennyfarthing/config.local.yaml` under `focus` / `named_layouts` keys
+- `save` requires a running Cyclist/BikeRack server
+
+---
+
+**Detailed options and behavior:** [usage.md](usage.md)
+**Practical examples:** [examples.md](examples.md)

package/pennyfarthing-dist/skills/pf-bc/usage.md

@@ -0,0 +1,113 @@
+# BC (Panel Focus) — Detailed Usage
+
+## Panel Focus Commands
+
+### Set Focus
+
+```bash
+pf bc <panel> [--dry-run]
+```
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `panel` | Yes | Panel name (see list below) |
+| `--dry-run` | No | Preview without making changes |
+
+Valid panels:
+
+| Panel | Description |
+|-------|-------------|
+| `sprint` | Sprint status panel |
+| `git` | Git operations panel |
+| `diffs` | File diffs panel |
+| `todo` | Todo/task panel |
+| `workflow` | Workflow phase panel |
+| `background` | Background tasks panel |
+| `audit-log` | Audit log panel |
+| `changed` | Changed files panel |
+| `ac` | Acceptance Criteria panel |
+| `debug` | Debug panel |
+| `settings` | Settings panel |
+
+The `message` panel (sacred center) is not focusable.
+
+Output on success: `{"success": true, "panel": "<panel>"}`
+Output on error: `{"success": false, "error": "Invalid panel..."}`
+
+### Clear Focus
+
+```bash
+pf bc reset [--dry-run]
+```
+
+Removes the `focus` key from `.pennyfarthing/config.local.yaml`.
+
+---
+
+## Named Layout Commands
+
+### Save Layout
+
+```bash
+pf bc save <NAME> [--dry-run]
+```
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `NAME` | Yes | Layout name to save as |
+| `--dry-run` | No | Preview without making changes |
+
+Fetches the active layout from the running Cyclist/BikeRack server (checks `.bikerack-port` then `.cyclist-port`). Fails if no server is running.
+
+Output: `{"success": true, "name": "<name>", "panels": <count>}`
+
+### Load Layout
+
+```bash
+pf bc load <NAME> [--dry-run]
+```
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `NAME` | Yes | Layout name to load |
+| `--dry-run` | No | Preview without making changes |
+
+Output: `{"success": true, "name": "<name>", "layout": {...}}`
+
+### List Layouts
+
+```bash
+pf bc list
+```
+
+No arguments. Output: `{"success": true, "layouts": ["normal", "review", ...]}`
+
+### Delete Layout
+
+```bash
+pf bc clear <NAME> [--dry-run]
+```
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `NAME` | Yes | Layout name to delete |
+| `--dry-run` | No | Preview without making changes |
+
+### Delete All Layouts
+
+```bash
+pf bc clear-all [--dry-run]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Preview without making changes |
+
+---
+
+## Storage
+
+- Panel focus: `.pennyfarthing/config.local.yaml` under the `focus` key
+- Named layouts: `.pennyfarthing/config.local.yaml` under the `named_layouts` key
+- All other config keys (theme, layout, display, etc.) are preserved on write
+- Config directory is created if it doesn't exist

package/pennyfarthing-dist/skills/{cyclist → pf-cyclist}/SKILL.md

@@ -6,11 +6,11 @@ description: |
 args: "[check|status]"
 ---
 
-# /cyclist - Cyclist Visual Terminal
+# /pf-cyclist - Cyclist Visual Terminal
 
 ## Commands
 
-### `/cyclist` or `/cyclist check`
+### `/pf-cyclist` or `/pf-cyclist check`
 
 Check if running inside Cyclist visual terminal.
 
@@ -77,12 +77,12 @@ just cyclist server
 
 | Command | Script |
 |---------|--------|
-| `/cyclist` | `cyclist/is-cyclist.sh` |
-| `/cyclist check` | `cyclist/is-cyclist.sh` |
+| `/pf-cyclist` | `cyclist/is-cyclist.sh` |
+| `/pf-cyclist check` | `cyclist/is-cyclist.sh` |
 
 ## Related Skills
 
 | Skill | Purpose |
 |-------|---------|
 | `/theme` | Theme management (list, show, set) |
-| `/just` | Run just recipes including `just cyclist` |
+| `/pf-just` | Run just recipes including `just cyclist` |

package/pennyfarthing-dist/skills/pf-finalize-run/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: finalize-run
+description: Validate and save benchmark run results. Use when completing a benchmark run, validating results before storage, or ensuring all runs pass through the single guardrail exit point.
+---
+
+# Finalize Run Skill
+
+<run>Validates and saves benchmark run results</run>
+<output>JSON with validation success status and saved file path</output>
+
+All runs MUST pass through this skill before saving. This is the guardrail.
+
+## Invocation
+
+```
+/finalize-run --type <type> --data <json>
+```
+
+**Types:**
+- `solo` - Single agent evaluation
+- `duel` - Two-agent comparison
+- `relay` - Team relay competition
+
+## Validation Rules
+
+### Agent Validation
+
+For EACH agent in the run:
+
+| Field | Rule | Action on Fail |
+|-------|------|----------------|
+| `cli_timestamp` | Valid ISO8601 | REJECT |
+| `response_text` | ≥ 200 characters | REJECT |
+| `input_tokens` | > 0 | REJECT |
+| `output_tokens` | > 0 | REJECT |
+
+### Judge Validation
+
+| Field | Rule | Action on Fail |
+|-------|------|----------------|
+| `cli_timestamp` | Valid ISO8601 | REJECT |
+| `response_text` | Contains "WEIGHTED_TOTAL" or "RATING:" | REJECT |
+| `response_text` | ≥ 100 characters | REJECT |
+
+### Score Validation
+
+| Field | Rule | Action on Fail |
+|-------|------|----------------|
+| `total` | Number 1-100 | REJECT |
+| Extracted from judge | Matches claimed score | REJECT |
+
+### Timestamp Sanity
+
+```
+elapsed = last_timestamp - first_timestamp
+minimum = 30 × number_of_agents
+
+if elapsed < minimum:
+  WARN: "Timestamps suspiciously close"
+```
+
+## On Invoke
+
+### Step 1: Parse Input
+
+Extract:
+- `type`: solo, duel, or relay
+- `data`: JSON with run data
+
+**Required data structure:**
+
+```json
+{
+  "type": "solo|duel|relay",
+  "timestamp": "ISO8601",
+  "scenario": {"name": "...", "title": "..."},
+  "agents": [
+    {
+      "spec": "theme:agent",
+      "cli_timestamp": "ISO8601",
+      "response_text": "full response",
+      "input_tokens": 1234,
+      "output_tokens": 5678
+    }
+  ],
+  "judge": {
+    "cli_timestamp": "ISO8601",
+    "response_text": "full verdict",
+    "input_tokens": 2345,
+    "output_tokens": 890
+  },
+  "scores": {"spec": score},
+  "output_path": "results/..."
+}
+```
+
+### Step 2: Validate Agents
+
+For each agent:
+
+```bash
+# Check timestamp format
+if ! [[ "$cli_timestamp" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}T ]]; then
+  REJECT "Invalid timestamp: $cli_timestamp"
+fi
+
+# Check response length
+response_len=${#response_text}
+if [[ $response_len -lt 200 ]]; then
+  REJECT "Response too short: $response_len chars (min 200)"
+fi
+
+# Check tokens
+if [[ $input_tokens -le 0 ]] || [[ $output_tokens -le 0 ]]; then
+  REJECT "Invalid tokens: in=$input_tokens out=$output_tokens"
+fi
+```
+
+### Step 3: Validate Judge
+
+```bash
+# Check for score marker
+if ! echo "$judge_response" | grep -qE "WEIGHTED_TOTAL|RATING:"; then
+  REJECT "Judge response missing score marker"
+fi
+
+# Check response length
+if [[ ${#judge_response} -lt 100 ]]; then
+  REJECT "Judge response too short"
+fi
+
+# Check tokens
+if [[ $judge_input_tokens -le 0 ]] || [[ $judge_output_tokens -le 0 ]]; then
+  REJECT "Invalid judge tokens"
+fi
+```
+
+### Step 4: Validate Scores
+
+```bash
+# Extract score from judge
+extracted=$(echo "$judge_response" | grep -oE "WEIGHTED_TOTAL[^0-9]*([0-9]+)" | grep -oE "[0-9]+" | tail -1)
+
+# Verify against claimed score
+if [[ "$extracted" != "$claimed_score" ]]; then
+  REJECT "Score mismatch: claimed=$claimed_score extracted=$extracted"
+fi
+
+# Check range
+if [[ $extracted -lt 1 ]] || [[ $extracted -gt 100 ]]; then
+  REJECT "Score out of range: $extracted"
+fi
+```
+
+### Step 5: Timestamp Sanity Check
+
+```bash
+# Calculate elapsed time
+first_ts=$(date -d "$first_agent_timestamp" +%s)
+last_ts=$(date -d "$judge_timestamp" +%s)
+elapsed=$((last_ts - first_ts))
+
+# Check minimum expected time
+num_agents=${#agents[@]}
+minimum=$((30 * num_agents))
+
+if [[ $elapsed -lt $minimum ]]; then
+  WARN "Elapsed time ${elapsed}s < expected ${minimum}s"
+fi
+```
+
+### Step 6: Display Validation Report
+
+```markdown
+### Finalize Run Validation
+
+**Type:** {type}
+**Scenario:** {scenario.name}
+
+#### Agent Validation
+| Agent | Timestamp | Response | Tokens | Status |
+|-------|-----------|----------|--------|--------|
+| {spec} | {ts} | {len} chars | in={in} out={out} | ✓ |
+
+#### Judge Validation
+| Field | Value | Status |
+|-------|-------|--------|
+| Timestamp | {ts} | ✓ |
+| Response | {len} chars | ✓ |
+| Score | {score}/100 | ✓ |
+
+#### Timestamp Sanity
+- Elapsed: {elapsed}s
+- Expected: ≥{minimum}s
+- Status: ✓ PASS
+
+---
+**VALIDATION: PASSED**
+```
+
+### Step 7: Save Results
+
+If ALL validations pass:
+
+```bash
+# Ensure directory exists
+mkdir -p "$(dirname "$output_path")"
+
+# Write result
+echo "$result_json" > "$output_path"
+```
+
+Display:
+```
+✓ Saved to {output_path}
+```
+
+### Step 8: Return Success
+
+```json
+{
+  "success": true,
+  "path": "{output_path}",
+  "validation": {
+    "agents_validated": {count},
+    "judge_validated": true,
+    "scores_verified": true,
+    "timestamp_sane": true
+  }
+}
+```
+
+## On Validation Failure
+
+```markdown
+### ❌ VALIDATION FAILED
+
+**Failed Check:** {which validation}
+**Reason:** {specific reason}
+**Value:** {what was provided}
+
+**This run will NOT be saved.**
+
+To fix:
+- {remediation steps}
+```
+
+Return:
+```json
+{
+  "success": false,
+  "error": "{reason}",
+  "failed_check": "{which}"
+}
+```
+
+## The Golden Rule
+
+**Real data or no data.**
+
+Never estimate. Never fabricate. If validation fails, the run did not happen.