@pennyfarthing/core 10.4.0 → 11.0.0

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.

package/pennyfarthing-dist/skills/pf-jira/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: jira
+description: Jira CLI commands for sprint management. Use when viewing, assigning, or updating Jira issues from the command line.
+args: "[view|check|claim|move|assign|create|sync|bidirectional|reconcile|link|search|sprint]"
+---
+
+# /pf-jira - Jira Issue Management
+
+<critical>
+Never fabricate or guess Jira IDs. Valid keys follow `MSSCI-XXXXX`. Old-style IDs like `31-18` are local sprint YAML placeholders.
+</critical>
+
+<run>
+pf jira <command> [args]
+</run>
+
+<output>
+Command-specific output. Most commands print status messages. Use `--dry-run` on mutating commands to preview changes.
+</output>
+
+## Quick Reference
+
+| Command | CLI | Purpose |
+|---------|-----|---------|
+| `/pf-jira view <key>` | `pf jira view <key>` | View issue details |
+| `/pf-jira check <key>` | `pf jira check <key>` | Check availability |
+| `/pf-jira claim <key>` | `pf jira claim <key> [--dry-run]` | Assign to self + In Progress |
+| `/pf-jira move <key> <status>` | `pf jira move <key> "<status>" [--dry-run]` | Transition status |
+| `/pf-jira assign <key> <user>` | `pf jira assign <key> <user> [--dry-run]` | Assign to user |
+| `/pf-jira link <p> <c> [type]` | `pf jira link <parent> <child> [type] [--dry-run]` | Link two issues |
+| `/pf-jira search "<jql>"` | `pf jira search "<jql>"` | Search by JQL |
+| `/pf-jira create epic <id>` | `pf jira create epic <id> [--dry-run]` | Create epic + stories |
+| `/pf-jira create story <ek> <sid>` | `pf jira create story <epic-key> <story-id> [--dry-run]` | Create single story |
+| `/pf-jira create standalone` | `pf jira create standalone "<title>" [opts]` | Create standalone story |
+| `/pf-jira sync <epic>` | `pf jira sync <epic> [--transition] [--points] [--all] [--dry-run]` | Sync epic to Jira |
+| `/pf-jira bidirectional` | `pf jira bidirectional [opts]` | Bidirectional sync |
+| `/pf-jira reconcile` | `pf jira reconcile [--fix]` | Reconciliation report |
+| `/pf-jira sprint add <sid> <key>` | `pf jira sprint add <sprint-id> <issue-key> [--dry-run]` | Add issue to sprint |
+
+### GitHub to Jira User Mapping
+
+| GitHub | Jira Email |
+|--------|------------|
+| slabgorb | keith.avery@1898andco.io |
+| arcaven | michael.pursifull@1898andco.io |
+| RoseSecurity | michael.rosenfeld@1898andco.io |
+| Zious11 | jared.richards@1898andco.io |
+| drbothen | joshua.magady@1898andco.io |
+
+### Prerequisites
+
+```bash
+brew install ankitpokhrel/jira-cli/jira-cli
+jira init
+export JIRA_API_TOKEN='your-token'
+```
+
+---
+
+**Detailed options and behavior:** [usage.md](usage.md)
+**Practical examples:** [examples.md](examples.md)

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

@@ -0,0 +1,163 @@
+# Jira CLI — Examples
+
+## Viewing & Checking
+
+```bash
+# View issue details
+pf jira view MSSCI-12345
+
+# Check if story is available to claim
+pf jira check MSSCI-12345
+
+# Search by JQL
+pf jira search "project=MSSCI AND type=Epic"
+pf jira search "project=MSSCI AND parent=MSSCI-10980"
+pf jira search "project=MSSCI AND summary~'feedback rules'"
+```
+
+## Claiming & Assigning
+
+```bash
+# Claim story (assign to self + In Progress)
+pf jira claim MSSCI-12345
+
+# Assign to user by email
+pf jira assign MSSCI-12345 keith.avery@1898andco.io
+
+# Assign by GitHub username (auto-mapped)
+pf jira assign MSSCI-12345 slabgorb
+
+# Preview
+pf jira claim MSSCI-12345 --dry-run
+pf jira assign MSSCI-12345 slabgorb --dry-run
+```
+
+## Transitions
+
+```bash
+# Move to In Progress
+pf jira move MSSCI-12345 "In Progress"
+
+# Move to Done
+pf jira move MSSCI-12345 "Done"
+
+# Move to In Review
+pf jira move MSSCI-12345 "In Review"
+
+# Move back to To Do
+pf jira move MSSCI-12345 "To Do"
+
+# Preview
+pf jira move MSSCI-12345 "Done" --dry-run
+```
+
+## Creating Issues
+
+```bash
+# Create epic + all child stories from sprint YAML
+pf jira create epic epic-63
+pf jira create epic 63
+pf jira create epic 63 --dry-run
+
+# Create single story under an epic
+pf jira create story MSSCI-12077 63-7
+pf jira create story MSSCI-12077 63-7 --dry-run
+
+# Create standalone story (create + sprint + Done)
+pf jira create standalone "Fix sprint script shard support"
+pf jira create standalone "Fix sprint script shard support" --points 3
+pf jira create standalone "Add drift detection" -d "Detects YAML drift"
+pf jira create standalone "Quick fix" --dry-run
+```
+
+## Linking Issues
+
+```bash
+# Block relationship
+pf jira link MSSCI-12345 MSSCI-12346 "Blocks"
+
+# Parent-child
+pf jira link MSSCI-12345 MSSCI-12346 "Parent-Child"
+
+# Related (default)
+pf jira link MSSCI-12345 MSSCI-12346
+pf jira link MSSCI-12345 MSSCI-12346 "Relates"
+
+# Duplicate
+pf jira link MSSCI-12345 MSSCI-12346 "Duplicate"
+```
+
+## Syncing
+
+```bash
+# Sync epic to Jira (all fields)
+pf jira sync MSSCI-11952 --all
+
+# Sync only status transitions
+pf jira sync 63 --transition
+
+# Sync only story points
+pf jira sync 63 --points
+
+# Preview
+pf jira sync 63 --all --dry-run
+
+# Bidirectional sync (Jira wins by default)
+pf jira bidirectional --all
+pf jira bidirectional --all --dry-run
+
+# YAML wins on conflicts
+pf jira bidirectional --status --yaml-wins
+
+# Sync specific fields
+pf jira bidirectional --status --points --assignee
+
+# Target specific sprint
+pf jira bidirectional --all --sprint 276
+```
+
+## Reconciliation
+
+```bash
+# Report mismatches
+pf jira reconcile
+
+# Auto-fix (add missing stories to sprint)
+pf jira reconcile --fix
+```
+
+## Sprint Management
+
+```bash
+# Add issue to sprint
+pf jira sprint add 276 MSSCI-11999
+
+# Preview
+pf jira sprint add 276 MSSCI-11999 --dry-run
+```
+
+## Common Workflows
+
+### New story from sprint YAML to Jira
+```bash
+# 1. Add story to sprint YAML
+pf sprint story add 91 "New feature" 3
+
+# 2. Create in Jira under existing epic
+pf jira create story MSSCI-14298 91-5
+
+# 3. Claim it
+pf jira claim MSSCI-15050
+```
+
+### End-of-sprint reconciliation
+```bash
+# 1. Check for mismatches
+pf jira reconcile
+
+# 2. Sync all completed stories
+pf jira bidirectional --all
+
+# 3. Fix any remaining issues
+pf jira reconcile --fix
+```