@pennyfarthing/core 10.0.3 → 10.1.0

package/pennyfarthing_scripts/tests/test_yaml_io.py

@@ -696,3 +696,120 @@ class TestReadSprint:
         assert isinstance(data["epics"], list)
         assert isinstance(data["epics"][0]["stories"], list)
         assert isinstance(data["epics"][0]["stories"][0]["points"], int)
+
+
+# =============================================================================
+# Sharded format support
+# =============================================================================
+
+
+SHARDED_INDEX_YAML = """\
+sprint:
+  name: "TO Sprint 2606"
+  jira_sprint_id: 309
+  jira_sprint_name: "TO Sprint 2606"
+  goal: Test sharding
+  start_date: 2026-02-02
+  end_date: 2026-02-15
+  status: active
+epics:
+  - MSSCI-14298
+  - epic-40
+stories: []
+"""
+
+SHARD_JIRA_YAML = """\
+id: MSSCI-14298
+type: epic
+title: "Epic: Stepped Workflow"
+priority: P1
+status: in_progress
+jira: MSSCI-14298
+stories:
+  - id: MSSCI-14299
+    title: Wire up stepped workflow
+    points: 5
+    priority: P0
+    status: done
+"""
+
+SHARD_INTERNAL_YAML = """\
+id: epic-40
+type: epic
+title: "Epic: Scale Adaptation"
+priority: P2
+status: backlog
+stories:
+  - id: 40-1
+    title: First story
+    points: 3
+    priority: P1
+    status: backlog
+"""
+
+
+@pytest.fixture
+def sharded_sprint_dir(tmp_path: Path) -> Path:
+    """Create a sharded sprint directory structure."""
+    (tmp_path / "current-sprint.yaml").write_text(SHARDED_INDEX_YAML)
+    (tmp_path / "epic-MSSCI-14298.yaml").write_text(SHARD_JIRA_YAML)
+    (tmp_path / "epic-epic-40.yaml").write_text(SHARD_INTERNAL_YAML)
+    return tmp_path
+
+
+class TestShardedReadWrite:
+    """Tests for sharded epic format in yaml_io."""
+
+    def test_read_merges_shards(self, sharded_sprint_dir: Path) -> None:
+        """read_sprint should merge shard files into full epics."""
+        data = read_sprint(sharded_sprint_dir / "current-sprint.yaml")
+
+        assert len(data["epics"]) == 2
+        assert data["epics"][0]["id"] == "MSSCI-14298"
+        assert data["epics"][1]["id"] == "epic-40"
+        assert len(data["epics"][0]["stories"]) == 1
+        assert len(data["epics"][1]["stories"]) == 1
+
+    def test_write_preserves_sharded_format(self, sharded_sprint_dir: Path) -> None:
+        """write_sprint should write back to shard files when format is sharded."""
+        index_path = sharded_sprint_dir / "current-sprint.yaml"
+        data = read_sprint(index_path)
+
+        # Mutate a story
+        data["epics"][1]["stories"][0]["status"] = "in_progress"
+
+        write_sprint(index_path, data)
+
+        # Index should still have string refs
+        import yaml
+        with open(index_path) as f:
+            raw_index = yaml.safe_load(f)
+        assert isinstance(raw_index["epics"][0], str)
+        assert raw_index["epics"][0] == "MSSCI-14298"
+
+        # Shard file should have the updated story
+        shard = read_sprint(sharded_sprint_dir / "epic-epic-40.yaml")
+        assert shard["stories"][0]["status"] == "in_progress"
+
+    def test_sharded_round_trip(self, sharded_sprint_dir: Path) -> None:
+        """Read-write-read on sharded format should be stable."""
+        index_path = sharded_sprint_dir / "current-sprint.yaml"
+
+        data1 = read_sprint(index_path)
+        write_sprint(index_path, data1)
+        data2 = read_sprint(index_path)
+
+        assert canonical_dump(data1) == canonical_dump(data2)
+
+    def test_non_sharded_write_unchanged(self, tmp_path: Path, full_sprint_file: Path) -> None:
+        """write_sprint on non-sharded data should write a single file."""
+        data = read_sprint(full_sprint_file)
+        out_path = tmp_path / "output.yaml"
+
+        write_sprint(out_path, data)
+
+        # Should be a single file, no shard files created
+        import yaml
+        with open(out_path) as f:
+            raw = yaml.safe_load(f)
+        assert isinstance(raw["epics"][0], dict)  # Full dicts, not refs

package/pennyfarthing_scripts/theme/__init__.py

@@ -0,0 +1,5 @@
+"""
+Theme management for Pennyfarthing persona themes.
+
+Provides CLI commands for listing, showing, setting, and creating themes.
+"""

package/pennyfarthing_scripts/theme/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as: python -m pennyfarthing_scripts.theme"""
+
+from pennyfarthing_scripts.theme.cli import theme
+
+if __name__ == "__main__":
+    theme()

package/pennyfarthing_scripts/theme/cli.py

@@ -0,0 +1,286 @@
+"""
+CLI commands for theme management.
+
+Usage:
+    pf theme list
+    pf theme show [NAME] [--full]
+    pf theme set <NAME>
+    pf theme create <NAME> [--base <THEME>] [--user]
+"""
+
+from __future__ import annotations
+
+import re
+
+import click
+
+
+@click.group()
+def theme():
+    """Persona theme management.
+
+    \b
+    Commands:
+      list    - Show all available themes
+      show    - Show theme details
+      set     - Set the active theme
+      create  - Create a new custom theme
+    """
+    pass
+
+
+@theme.command("list")
+def list_cmd():
+    """Show all available themes with current theme highlighted."""
+    from pennyfarthing_scripts.common.themes import format_theme_list
+
+    click.echo(format_theme_list())
+
+
+@theme.command("show")
+@click.argument("name", required=False)
+@click.option("--full", is_flag=True, help="Show full agent details (OCEAN, quirks, catchphrases, etc.)")
+def show(name: str | None, full: bool):
+    """Show theme details including agent character mappings.
+
+    \b
+    Arguments:
+      NAME  - Theme to show (defaults to current theme)
+    """
+    import yaml
+
+    from pennyfarthing_scripts.common.themes import (
+        get_current_theme,
+        list_themes,
+        resolve_theme_path,
+    )
+
+    theme_name = name
+    if not theme_name:
+        theme_name = get_current_theme()
+        if not theme_name:
+            click.echo("No theme currently set.")
+            click.echo("Use 'pf theme set <name>' to select a theme.")
+            return
+
+    theme_path = resolve_theme_path(theme_name)
+    if not theme_path:
+        available = ", ".join(list_themes()[:10])
+        raise click.ClickException(f"Theme '{theme_name}' not found.\nAvailable: {available}...")
+
+    data = yaml.safe_load(theme_path.read_text())
+    if not data:
+        raise click.ClickException(f"Invalid theme file: {theme_path}")
+
+    theme_meta = data.get("theme", {})
+    agents = data.get("agents", {})
+
+    # Header
+    click.echo(f"Theme: {theme_name}")
+    if theme_meta.get("description"):
+        click.echo(f"Description: {theme_meta['description']}")
+    if theme_meta.get("tier"):
+        click.echo(f"Tier: {theme_meta['tier']}")
+    click.echo()
+
+    # Agents
+    click.echo("Agents:")
+    agent_order = [
+        "sm", "tea", "dev", "reviewer", "orchestrator",
+        "pm", "architect", "devops", "tech-writer", "ux-designer",
+    ]
+
+    displayed: set[str] = set()
+    for agent_name in agent_order:
+        agent = agents.get(agent_name)
+        if agent and agent.get("character"):
+            _display_agent(agent_name, agent, full)
+            displayed.add(agent_name)
+
+    for agent_name, agent in agents.items():
+        if agent_name not in displayed and isinstance(agent, dict) and agent.get("character"):
+            _display_agent(agent_name, agent, full)
+
+
+def _display_agent(name: str, agent: dict, full: bool) -> None:
+    """Display a single agent's info."""
+    click.echo(f"  {name}:")
+    click.echo(f"    Character: {agent['character']}")
+    if agent.get("style"):
+        click.echo(f"    Style: {agent['style']}")
+
+    if not full:
+        return
+
+    if agent.get("ocean"):
+        ocean = agent["ocean"]
+        click.echo(
+            f"    OCEAN: O={ocean.get('O', '?')} C={ocean.get('C', '?')} "
+            f"E={ocean.get('E', '?')} A={ocean.get('A', '?')} N={ocean.get('N', '?')}"
+        )
+    if agent.get("trait"):
+        click.echo(f"    Trait: {agent['trait']}")
+    if agent.get("expertise"):
+        click.echo(f"    Expertise: {agent['expertise']}")
+    if agent.get("role"):
+        click.echo(f"    Role: {agent['role']}")
+    if agent.get("quirks"):
+        click.echo("    Quirks:")
+        for q in agent["quirks"]:
+            click.echo(f"      - {q}")
+    if agent.get("catchphrases"):
+        click.echo("    Catchphrases:")
+        for c in agent["catchphrases"]:
+            click.echo(f"      - {c}")
+    if agent.get("emoji"):
+        click.echo(f"    Emoji: {agent['emoji']}")
+    if agent.get("helper"):
+        helper = agent["helper"]
+        hname = helper.get("name", "?")
+        hstyle = helper.get("style", "?")
+        click.echo(f"    Helper: {hname} ({hstyle})")
+
+
+@theme.command("set")
+@click.argument("name")
+def set_theme(name: str):
+    """Set the active persona theme.
+
+    \b
+    Arguments:
+      NAME  - Theme name to activate
+    """
+    import yaml
+
+    from pennyfarthing_scripts.common.config import get_project_root
+    from pennyfarthing_scripts.common.themes import (
+        list_themes,
+        resolve_theme_path,
+    )
+
+    theme_path = resolve_theme_path(name)
+    if not theme_path:
+        available = ", ".join(list_themes()[:10])
+        raise click.ClickException(f"Theme '{name}' not found.\nAvailable: {available}...")
+
+    theme_data = yaml.safe_load(theme_path.read_text())
+    theme_meta = theme_data.get("theme", {})
+    agents = theme_data.get("agents", {})
+
+    # Build theme_characters map (matches Node.js setTheme behavior)
+    theme_characters: dict[str, str] = {}
+    for agent_id, agent_info in agents.items():
+        if isinstance(agent_info, dict) and agent_info.get("character"):
+            theme_characters[agent_id] = agent_info["character"]
+
+    # Read existing config, preserve other fields
+    root = get_project_root()
+    config_path = root / ".pennyfarthing" / "config.local.yaml"
+
+    config: dict = {}
+    if config_path.exists():
+        try:
+            existing = yaml.safe_load(config_path.read_text())
+            if existing and isinstance(existing, dict):
+                config = existing
+        except Exception:
+            pass
+
+    config["theme"] = name
+    config["theme_characters"] = theme_characters
+
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    header = (
+        "# Pennyfarthing Local Configuration\n"
+        "# This file is gitignored - your personal preferences\n\n"
+    )
+    config_path.write_text(
+        header + yaml.dump(config, default_flow_style=False, sort_keys=False)
+    )
+
+    click.echo(f"Theme changed to '{name}'.")
+    click.echo()
+    click.echo(f"  {theme_meta.get('name', name)}")
+
+    samples = []
+    for key in ["sm", "tea", "dev"]:
+        agent = agents.get(key)
+        if agent and agent.get("character"):
+            samples.append(f"{key.upper()}: {agent['character']}")
+    if samples:
+        click.echo(f"  {' | '.join(samples)}")
+
+    click.echo()
+    click.echo("Start a new agent session to use the new theme.")
+
+
+@theme.command("create")
+@click.argument("name")
+@click.option("--base", default=None, help="Base theme to copy from (defaults to current theme)")
+@click.option("--user", is_flag=True, help="Create as user-level theme (~/.claude/pennyfarthing/themes/)")
+def create(name: str, base: str | None, user: bool):
+    """Create a new custom theme from a base theme.
+
+    \b
+    Arguments:
+      NAME  - Name for the new theme (lowercase, hyphens allowed)
+    """
+    import yaml
+    from pathlib import Path
+
+    from pennyfarthing_scripts.common.config import get_project_root
+    from pennyfarthing_scripts.common.themes import (
+        get_current_theme,
+        list_themes,
+        resolve_theme_path,
+    )
+
+    if not base:
+        base = get_current_theme() or "blade-runner"
+
+    if name != name.lower():
+        raise click.ClickException("Theme name must be lowercase")
+    if " " in name:
+        raise click.ClickException("Theme name cannot contain spaces (use hyphens)")
+    if not re.match(r"^[a-z][a-z0-9-]*$", name):
+        raise click.ClickException(
+            "Theme name must start with a letter and contain only lowercase letters, numbers, and hyphens"
+        )
+
+    if name in list_themes():
+        raise click.ClickException(f"Theme '{name}' already exists")
+
+    base_path = resolve_theme_path(base)
+    if not base_path:
+        available = ", ".join(list_themes()[:10])
+        raise click.ClickException(f"Base theme '{base}' not found.\nAvailable: {available}...")
+
+    if user:
+        target_dir = Path.home() / ".claude" / "pennyfarthing" / "themes"
+    else:
+        root = get_project_root()
+        target_dir = root / ".claude" / "pennyfarthing" / "themes"
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+    target_path = target_dir / f"{name}.yaml"
+
+    base_data = yaml.safe_load(base_path.read_text())
+    base_data["theme"]["name"] = name.replace("-", " ").title()
+    base_data["theme"]["description"] = f"Custom theme based on {base}"
+
+    file_header = (
+        f"# Custom Theme: {name}\n"
+        f"# Based on: {base}\n"
+        "# Edit this file to customize your agent personas\n\n"
+    )
+    target_path.write_text(
+        file_header + yaml.dump(base_data, default_flow_style=False, sort_keys=False)
+    )
+
+    click.echo(f"Created theme '{name}'.")
+    click.echo()
+    click.echo(f"  File: {target_path}")
+    click.echo()
+    click.echo("Next steps:")
+    click.echo(f"  1. Edit the theme file to customize your agents")
+    click.echo(f"  2. Run 'pf theme set {name}' to activate")

package/scripts/README.md

@@ -0,0 +1,53 @@
+# Meta Scripts
+
+**These scripts are NOT distributed to users.** They are for Pennyfarthing framework development only.
+
+## Contents
+
+| Script | Purpose |
+|--------|---------|
+| `deploy.sh` | Release Pennyfarthing (version bump, tag, push, GitHub release) |
+| `benchmark-runner.{sh,js}` | Run persona benchmarks |
+| `job-fair-*.sh` | Job Fair character evaluations |
+| `aggregate-benchmark-stats.{sh,js}` | Aggregate benchmark results |
+| `solo-runner.sh` | Run single agent on a scenario |
+| `parallel-benchmark.sh` | Parallel benchmark execution |
+| `consolidate-job-fair.sh` | Consolidate Job Fair results |
+| `convert-jobfair-to-benchmarks.sh` | Format conversion |
+| `generate-leaderboard.sh` | Build leaderboard from benchmarks |
+| `regenerate-summaries.sh` | Regenerate benchmark summaries |
+| `cyclist-debug.mjs` | Debug Cyclist connection |
+| `handoff-cli.{sh,js}` | Test handoff flow |
+| `verify-visual-mapping.js` | Verify theme visual mappings |
+| `migrate-assets-to-slug.sh` | One-time migration script |
+| `resize-portraits.sh` | Resize portrait images |
+| `resolve-portrait.mjs` | Portrait resolution logic |
+
+## Usage
+
+Run from pennyfarthing repo root:
+
+```bash
+# Release a new version
+./scripts/deploy.sh --dry-run patch
+./scripts/deploy.sh patch
+
+# Run benchmarks
+./scripts/benchmark-runner.sh --theme mash --agent sm
+
+# Job Fair
+./scripts/job-fair-runner.sh mash
+```
+
+## Where Should My Script Go?
+
+**Put it here if:**
+- It's for framework development/CI only
+- Users should NOT have access to it
+- It uses GPU/heavy dependencies (keep in meta, not distributed)
+
+**Put it in `pennyfarthing-dist/scripts/` if:**
+- Users need it for their workflows
+- It's part of the sprint/story/jira tooling
+
+See `CLAUDE.md` for the full decision tree.

package/scripts/postinstall.cjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// Fix execute permissions on shell scripts after npm install.
+// npm may strip +x bits depending on platform/version.
+
+const { readdirSync, chmodSync, statSync } = require('fs');
+const { join } = require('path');
+
+const scriptsDir = join(__dirname, '..', 'pennyfarthing-dist', 'scripts');
+
+function fixPermissions(dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      fixPermissions(full);
+    } else if (entry.name.endsWith('.sh') && entry.name !== 'find-root.sh') {
+      try {
+        const stat = statSync(full);
+        if ((stat.mode & 0o111) === 0) {
+          chmodSync(full, 0o755);
+        }
+      } catch {
+        // Skip files we can't chmod
+      }
+    }
+  }
+}
+
+fixPermissions(scriptsDir);

package/pennyfarthing-dist/agents/workflow-status-check.md

@@ -1,96 +0,0 @@
----
-name: workflow-status-check
-description: Determine workflow state using sprint scripts
-tools: Bash, Read
-model: haiku
----
-
-<info>
-Universal entry point telling agents: what work exists, what phase, and whether to activate.
-Uses `/sprint` skill scripts for deterministic output.
-</info>
-
-<arguments>
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `CALLING_AGENT` | Yes | Agent requesting status check (e.g., "SM", "Architect", "PM") |
-</arguments>
-
----
-
-## Execution
-
-Run the sprint status script and parse output:
-
-```bash
-.pennyfarthing/scripts/sprint/sprint-status.sh
-```
-
-Then check for active sessions:
-
-```bash
-if ls .session/*-session.md 1>/dev/null 2>&1; then
-  for f in .session/*-session.md; do head -30 "$f"; done
-else
-  echo "No active sessions"
-fi
-```
-
----
-
-## State Determination
-
-| State | Condition |
-|-------|-----------|
-| `FINISH_STATE` | Session exists with Phase=approved OR Status=approved |
-| `IN_PROGRESS_STATE` | Phased workflow session with active phase (setup/red/green/implement/review) |
-| `STEPPED_WORKFLOW_STATE` | Stepped workflow session (workflow type = stepped) |
-| `NEW_WORK_STATE` | No sessions AND sprint has backlog/ready stories |
-| `EMPTY_BACKLOG_STATE` | No sessions AND sprint has NO backlog/ready stories |
-
-**Detecting workflow type from session:**
-```bash
-# Read workflow name from session
-WORKFLOW=$(grep '^\*\*Workflow:\*\*' .session/*-session.md | head -1 | sed 's/.*: //')
-# Check if stepped
-.pennyfarthing/scripts/workflow/get-workflow-type.sh "$WORKFLOW"
-```
-
-**Important:** Sprints are fixed two-week periods (kanban-style). Never suggest closing a sprint early or starting sprint planning when backlog is empty. The correct response to `EMPTY_BACKLOG_STATE` is to suggest promoting stories from `future.yaml`.
-
----
-
-<output>
-## Output Format
-
-Return a `STATUS_CHECK_RESULT` block:
-
-### Success
-```
-STATUS_CHECK_RESULT:
-  status: success
-  state: {FINISH_STATE|IN_PROGRESS_STATE|NEW_WORK_STATE|EMPTY_BACKLOG_STATE}
-  story_id: {ID or null}
-  phase: {current phase or null}
-  phase_owner: {agent name or null}
-  sprint_number: {N}
-  backlog_count: {N}
-
-  next_steps:
-    - FINISH_STATE: "Proceed to Finish Flow - spawn sm-finish with PHASE=preflight"
-    - IN_PROGRESS_STATE: "Report phase owner '{phase_owner}' should continue. Run handoff-marker.sh {phase_owner}"
-    - STEPPED_WORKFLOW_STATE: "Stepped workflow in progress. Tell user to run /workflow resume or /workflow status"
-    - NEW_WORK_STATE: "Present available stories to user. Await selection, then spawn sm-setup MODE=setup"
-    - EMPTY_BACKLOG_STATE: "Report backlog empty. Suggest promoting from future.yaml"
-```
-
-### Active Session Details (if IN_PROGRESS_STATE)
-```
-  session:
-    story_id: {ID}
-    title: "{title}"
-    workflow: {workflow}
-    phase: {phase}
-    branch: {branch}
-```
-</output>