@pennyfarthing/core 11.3.2 → 11.3.4

package/pennyfarthing_scripts/CLAUDE.md

@@ -1,213 +0,0 @@
-# CLAUDE.md — pf CLI
-
-Python Click CLI for Pennyfarthing. Entry point: `pennyfarthing_scripts/cli.py`. Invoked as `pf`.
-
-## Command Index
-
-| Command | Description | Source |
-|---------|-------------|--------|
-| `pf sprint` | Sprint status and story operations | `sprint/cli.py` |
-| `pf jira` | Jira issue management | `jira/cli.py` |
-| `pf theme` | Persona theme management | `theme/cli.py` |
-| `pf bc` | Panel focus and layout management | `bc/cli.py` |
-| `pf validate` | Project validators | `validate/cli.py` |
-| `pf agent` | Agent session management | `cli.py` (inline) |
-| `pf workflow` | Workflow state and phase management | `workflow/cli.py` |
-| `pf bikerack` | BikeRack dashboard launcher | `bikerack/cli.py` |
-| `pf git` | Repository operations (status, branches, worktree, hooks) | `git_group/cli.py` |
-| `pf debug` | Analysis tools (hotspots, deadcode, healthscore) | `cli.py` (inline group) |
-
-### Sugar Shortcuts
-
-| Shortcut | Expands To |
-|----------|------------|
-| `pf status` | `pf sprint status` |
-| `pf backlog` | `pf sprint backlog` |
-| `pf work` | `pf sprint work` |
-| `pf story` | `pf sprint story` |
-
-## pf sprint
-
-| Command | Description | Source |
-|---------|-------------|--------|
-| `pf sprint status [FILTER]` | Show sprint status. Filter: `all`, `backlog`, `in-progress`, `done`, `review` | `sprint/status.py` |
-| `pf sprint backlog` | Available stories grouped by epic | `sprint/cli.py` |
-| `pf sprint work [STORY_ID]` | Start work on a story (`next` for auto-select) | `sprint/work.py` |
-| `pf sprint check IDENTIFIER` | Check story/epic availability (JSON output) | `sprint/cli.py` |
-| `pf sprint info` | Sprint header as JSON | `sprint/cli.py` |
-| `pf sprint metrics` | Sprint metrics and velocity | `sprint/cli.py` |
-| `pf sprint future [EPIC_ID]` | Future initiatives overview | `sprint/cli.py` |
-| `pf sprint new` | Initialize a new sprint | `sprint/cli.py` |
-| `pf sprint archive STORY_ID PR` | Archive a completed story | `sprint/archive.py` |
-| `pf sprint standalone TITLE` | Wrap changes into standalone Jira story + PR | `sprint/cli.py` |
-| `pf sprint validate` | Validate sprint YAML | `sprint/validate_cmd.py` |
-
-### pf sprint story
-
-| Command | Description | Source |
-|---------|-------------|--------|
-| `pf sprint story show ID` | Show story details | `sprint/cli.py` |
-| `pf sprint story add EPIC_ID TITLE POINTS` | Add story to epic | `sprint/story_add.py` |
-| `pf sprint story update ID [OPTIONS]` | Update story fields | `sprint/story_update.py` |
-| `pf sprint story field ID FIELD` | Get single field value | `sprint/cli.py` |
-| `pf sprint story size [POINTS]` | Sizing guidelines | `sprint/cli.py` |
-| `pf sprint story template [TYPE]` | Story templates | `sprint/cli.py` |
-| `pf sprint story finish ID` | Complete story (archive, merge, Jira) | `sprint/story_finish.py` |
-| `pf sprint story claim JIRA_KEY` | Claim/unclaim in Jira | `sprint/cli.py` |
-
-### pf sprint epic
-
-| Command | Description | Source |
-|---------|-------------|--------|
-| `pf sprint epic show ID` | Show epic details | `sprint/cli.py` |
-| `pf sprint epic add ID TITLE` | Add new epic | `sprint/epic_add.py` |
-| `pf sprint epic update ID [OPTIONS]` | Update epic fields | `sprint/epic_update.py` |
-| `pf sprint epic field ID FIELD` | Get single field value | `sprint/cli.py` |
-| `pf sprint epic promote ID` | Move from future to current sprint | `sprint/cli.py` |
-| `pf sprint epic archive [ID]` | Archive completed epics | `sprint/archive_epic.py` |
-| `pf sprint epic cancel ID` | Cancel epic and all stories | `sprint/cli.py` |
-| `pf sprint epic import FILE` | Import BMAD epics to future.yaml | `sprint/import_epic.py` |
-| `pf sprint epic remove ID` | Remove from future.yaml | `sprint/cli.py` |
-
-### pf sprint initiative
-
-| Command | Description | Source |
-|---------|-------------|--------|
-| `pf sprint initiative show ID` | Show initiative details | `sprint/cli.py` |
-| `pf sprint initiative cancel ID` | Cancel initiative and all children | `sprint/cli.py` |
-
-## pf jira
-
-| Command | Description | Source |
-|---------|-------------|--------|
-| `pf jira view KEY` | View issue details | `jira/cli.py` |
-| `pf jira check KEY` | Check if story is available | `jira/cli.py` |
-| `pf jira claim KEY` | Assign to self + In Progress | `jira/claim.py` |
-| `pf jira assign KEY USER` | Assign to user (email or GitHub username) | `jira/cli.py` |
-| `pf jira move KEY STATUS` | Transition issue status | `jira/cli.py` |
-| `pf jira link KEY1 KEY2 [TYPE]` | Link two issues | `jira/cli.py` |
-| `pf jira search JQL` | Search by JQL | `jira/cli.py` |
-| `pf jira create epic EPIC_ID` | Create epic + children from YAML | `jira/epic.py` |
-| `pf jira create story EPIC_KEY STORY_ID` | Create single story under epic | `jira/story.py` |
-| `pf jira create standalone TITLE` | Create standalone story, add to sprint, Done | `jira/create.py` |
-| `pf jira sync EPIC_ID` | Sync YAML to Jira | `jira/sync.py` |
-| `pf jira bidirectional` | Bidirectional sync (Jira wins by default) | `jira/bidirectional.py` |
-| `pf jira reconcile` | Report mismatches between YAML and Jira | `jira/reconcile.py` |
-| `pf jira sprint add SPRINT_ID KEY` | Add issue to sprint | `jira/cli.py` |
-
-## pf theme
-
-| Command | Description | Source |
-|---------|-------------|--------|
-| `pf theme list` | All available themes | `theme/cli.py` |
-| `pf theme show [NAME]` | Theme details (current if no name) | `theme/cli.py` |
-| `pf theme set NAME` | Set active theme | `theme/cli.py` |
-| `pf theme create NAME` | Create custom theme from base | `theme/cli.py` |
-
-## pf bc
-
-| Command | Description | Source |
-|---------|-------------|--------|
-| `pf bc <panel>` | Focus panel (sprint, git, diffs, todo, workflow, background, audit-log, changed, ac, debug, settings, tty) | `bc/cli.py` |
-| `pf bc reset` | Clear focus | `bc/cli.py` |
-| `pf bc save NAME` | Save current layout | `bc/cli.py` |
-| `pf bc load NAME` | Load saved layout | `bc/cli.py` |
-| `pf bc list` | List saved layouts | `bc/cli.py` |
-| `pf bc clear NAME` | Delete layout | `bc/cli.py` |
-| `pf bc clear-all` | Delete all layouts | `bc/cli.py` |
-
-## pf validate
-
-| Command | Description | Source |
-|---------|-------------|--------|
-| `pf validate` | Run all validators | `validate/cli.py` |
-| `pf validate sprint` | Sprint YAML validation | `validate/cli.py` |
-| `pf validate schema` | XML schema validation | `validate/cli.py` |
-| `pf validate agent` | Agent definition validation | `validate/cli.py` |
-| `pf validate workflow` | Workflow definition validation | `validate/cli.py` |
-
-Options: `--fix` (auto-fix), `--strict` (warnings as errors)
-
-## pf agent
-
-| Command | Description | Source |
-|---------|-------------|--------|
-| `pf agent start NAME` | Start agent session with context | `prime/` |
-
-Options: `--session-id`, `--no-persona`, `--json`, `--minimal`, `--full`, `--quiet`, `--tier {full,refresh,handoff,minimal}`
-
-## pf workflow
-
-| Command | Description | Source |
-|---------|-------------|--------|
-| `pf workflow check [--json]` | Current workflow state | `workflow/cli.py` |
-| `pf workflow phase-check WORKFLOW PHASE` | Check phase owner | `workflow/cli.py` |
-| `pf workflow handoff AGENT` | Emit handoff marker | `workflow/cli.py` |
-| `pf workflow type WORKFLOW` | Get workflow type (phased/stepped/procedural) | `workflow/cli.py` |
-| `pf workflow list` | List all available workflows | `workflow/cli.py` |
-| `pf workflow show [NAME]` | Show workflow details | `workflow/cli.py` |
-| `pf workflow start NAME [--mode M]` | Start stepped workflow | `workflow/cli.py` |
-| `pf workflow resume [NAME]` | Resume interrupted workflow | `workflow/cli.py` |
-| `pf workflow status [NAME]` | Show stepped workflow progress | `workflow/cli.py` |
-| `pf workflow fix-phase ID PHASE [--dry-run]` | Repair session phase | `workflow/cli.py` |
-| `pf workflow complete-step [NAME] [--step N]` | Complete current step | `workflow/cli.py` |
-
-## pf bikerack
-
-| Command | Description | Source |
-|---------|-------------|--------|
-| `pf bikerack start` | Start BikeRack + Claude CLI | `bikerack/cli.py` |
-| `pf bikerack stop` | Stop running instance | `bikerack/cli.py` |
-| `pf bikerack status` | Show running state | `bikerack/cli.py` |
-
-## pf git
-
-| Command | Description | Source |
-|---------|-------------|--------|
-| `pf git status [--brief]` | Check git status of all repos | `git/status_all.py` |
-| `pf git branches BRANCH [--repos all\|api\|ui]` | Create feature branches | `git/create_branches.py` |
-| `pf git cleanup` | Start git-cleanup workflow | `git_group/cli.py` |
-| `pf git worktree create NAME BRANCH` | Create worktree(s) | `git/worktree.py` |
-| `pf git worktree remove NAME` | Remove worktree | `git/worktree.py` |
-| `pf git worktree list` | List active worktrees | `git/worktree.py` |
-| `pf git worktree status` | Show worktree status | `git/worktree.py` |
-| `pf git install-hooks` | Install git hooks with .d/ dispatcher | `git/hooks_installer.py` |
-
-## pf debug
-
-| Command | Description | Source |
-|---------|-------------|--------|
-| `pf debug hotspots analyze` | Full hotspot analysis | `hotspots/analyze.py` |
-| `pf debug hotspots files` | File-level hotspot report | `hotspots/cli.py` |
-| `pf debug hotspots dirs` | Directory-level hotspot report | `hotspots/cli.py` |
-| `pf debug deadcode stale` | Files with no recent commits | `deadcode/analyze.py` |
-| `pf debug deadcode exports` | Unused TypeScript exports | `deadcode/cli.py` |
-| `pf debug healthscore analyze` | Composite health score | `healthscore/cli.py` |
-
-## Hooks (`pf hooks`)
-
-All hooks are in `hooks/` subpackage, invoked via `pf hooks <name>`.
-
-| Command | Hook Type | Purpose |
-|---------|-----------|---------|
-| `pf hooks session-start` | SessionStart | Session setup, checkpoint, WheelHub, welcome |
-| `pf hooks session-stop` | Stop | Save checkpoint for cross-session continuity |
-| `pf hooks reflector-check` | Stop | Enforce CYCLIST reflector markers |
-| `pf hooks pre-edit-check` | PreToolUse | Block edits to protected files |
-| `pf hooks context-warning` | PreToolUse | Warn when context usage is high |
-| `pf hooks context-breaker` | PreToolUse | Block tool execution at critical context |
-| `pf hooks cyclist-pretooluse` | PreToolUse | Route approval through WheelHub |
-| `pf hooks schema-validation` | PreToolUse:Write | Validate session/skill/step schema |
-| `pf hooks bell-mode` | PostToolUse | Bell queue + tandem injection |
-| `pf hooks sprint-yaml` | PostToolUse | Validate sprint YAML (YAML 1.2) |
-| `pf hooks statusline` | statusLine | Render Claude Code status bar |
-
-Legacy shims (`bellmode_hook.py`, `pretooluse_hook.py`, etc.) re-export from `hooks/` for backward compat.
-
-## Architecture
-
-- **Framework:** Click (lazy-loaded groups for <200ms startup)
-- **Entry point:** `cli.py` registers all groups, `pyproject.toml` maps `pf` to `pennyfarthing_scripts.cli:main`
-- **Pattern:** Each command group is a subpackage with `cli.py` defining Click commands and sibling modules for logic
-- **Output:** JSON for machine consumption (`--json`), formatted text for humans
-- **Dry run:** Most mutating commands support `--dry-run` to preview changes

package/pennyfarthing_scripts/README.md

@@ -1,66 +0,0 @@
-# Pennyfarthing Scripts (Python)
-
-**This is a distributed Python package.** It ships to users via npm alongside the bash scripts.
-
-## Installation
-
-The package is automatically available when Pennyfarthing is installed. PYTHONPATH is set by the calling script via environment variables.
-
-## Packages
-
-| Package | Purpose |
-|---------|---------|
-| `common/` | Shared utilities (output formatting, config) |
-| `jira/` | Jira CLI wrapper (sync, create, claim) |
-| `sprint/` | Sprint YAML management |
-| `story/` | Story operations |
-| `git/` | Git utilities |
-| `brownfield/` | Codebase analysis for new projects |
-| `prime/` | Context priming |
-| `preflight/` | Pre-flight checks |
-
-## Top-Level Modules
-
-| Module | Purpose |
-|--------|---------|
-| `hooks.py` | Claude Code hook implementations |
-| `bellmode_hook.py` | Bell mode hook |
-| `pretooluse_hook.py` | PreToolUse hook |
-| `welcome_hook.py` | Welcome message hook |
-| `workflow.py` | Workflow utilities |
-| `swebench.py` | SWE-bench evaluation support |
-
-## Usage
-
-Scripts invoke Python modules directly:
-
-```bash
-# From a bash script
-python -m pennyfarthing_scripts.jira.sync "$EPIC_ID"
-
-# PYTHONPATH is set by the script:
-# export PYTHONPATH="${PROJECT_ROOT}${PYTHONPATH:+:$PYTHONPATH}"
-```
-
-## Dependencies
-
-Minimal dependencies - standard library plus:
-- `httpx` - HTTP client
-- `pyyaml` - YAML parsing
-
-NO GPU dependencies here. Those belong in meta scripts (`scripts/*.py`).
-
-## Testing
-
-```bash
-cd pennyfarthing
-python -m pytest pennyfarthing_scripts/tests/
-```
-
-## What Does NOT Go Here
-
-Meta-only Python scripts belong in `scripts/`:
-- Portrait generation (requires torch, diffusers)
-- Other GPU-heavy tools
-
-See `CLAUDE.md` for the full decision tree.

package/pennyfarthing_scripts/bc/cli.py

@@ -1,242 +0,0 @@
-"""BC CLI — Panel focus management for Cyclist.
-
-Usage:
-    pf bc <panel>    Set focus to a panel
-    pf bc reset      Clear focus setting
-    pf bc save       Save a named layout
-    pf bc load       Load a named layout
-    pf bc list       List saved layouts
-    pf bc clear      Delete a named layout
-    pf bc clear-all  Delete all named layouts
-"""
-
-from __future__ import annotations
-
-import json
-import sys
-import urllib.error
-import urllib.request
-
-import click
-
-from pennyfarthing_scripts.bc.focus import (
-    VALID_PANELS,
-    clear_all_named_layouts,
-    clear_named_layout,
-    clear_panel_focus,
-    list_named_layouts,
-    load_named_layout,
-    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 .bikerack-port (shared by both Cyclist and BikeRack) and fetches
-    the layout endpoint.
-
-    Returns:
-        Layout dict, or None if no server is running or fetch fails.
-    """
-    from pennyfarthing_scripts.bc.focus import _get_root
-
-    root = _get_root()
-
-    candidates = [
-        (root / ".bikerack-port", "/api/settings/bikerack-layout"),
-    ]
-
-    for port_file, endpoint in candidates:
-        if not port_file.exists():
-            continue
-        try:
-            port = int(port_file.read_text().strip())
-        except (ValueError, OSError):
-            continue
-
-        url = f"http://localhost:{port}{endpoint}"
-        try:
-            req = urllib.request.Request(url, headers={"Accept": "application/json"})
-            with urllib.request.urlopen(req, timeout=3) as resp:
-                data = json.loads(resp.read().decode())
-                layout = data.get("layout")
-                if layout and isinstance(layout, dict) and layout.get("panels"):
-                    return layout
-        except (urllib.error.URLError, OSError, json.JSONDecodeError):
-            continue
-
-    return None
-
-
-@click.group()
-def bc():
-    """Panel focus management.
-
-    \b
-    Commands:
-      sprint      - Focus on Sprint panel
-      git         - Focus on Git panel
-      diffs       - Focus on Diffs panel
-      todo        - Focus on Todo panel
-      workflow    - Focus on Workflow panel
-      background  - Focus on Background panel
-      audit-log   - Focus on Audit Log panel
-      changed     - Focus on Changed panel
-      ac          - Focus on Acceptance Criteria panel
-      debug       - Focus on Debug panel
-      settings    - Focus on Settings panel
-      tty         - Focus on TTY panel
-      reset       - Clear focus setting
-    """
-    pass
-
-
-def _make_focus_command(panel_name: str):
-    """Create a Click command for a panel."""
-
-    @click.command(panel_name, help=f"Focus on {panel_name} panel.")
-    @click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
-    def focus_cmd(dry_run):
-        if dry_run:
-            click.echo(json.dumps({"dry_run": True, "action": "set_focus", "panel": panel_name}))
-            return
-        result = set_panel_focus(panel_name)
-        if result["success"]:
-            click.echo(json.dumps({"success": True, "panel": result["data"]}))
-        else:
-            click.echo(json.dumps({"success": False, "error": result["error"]}), err=True)
-            sys.exit(1)
-
-    return focus_cmd
-
-
-for _panel in VALID_PANELS:
-    bc.add_command(_make_focus_command(_panel))
-
-
-@bc.command("reset")
-@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
-def reset_focus(dry_run):
-    """Clear focus setting."""
-    if dry_run:
-        click.echo(json.dumps({"dry_run": True, "action": "clear_focus"}))
-        return
-    result = clear_panel_focus()
-    if result["success"]:
-        click.echo(json.dumps({"success": True, "message": result.get("message", "focus cleared")}))
-    else:
-        click.echo(json.dumps({"success": False, "error": result["error"]}), err=True)
-        sys.exit(1)
-
-
-# --- Story 104-4: Named layout commands ---
-
-
-@bc.command("save")
-@click.argument("name")
-@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
-def save_layout(name: str, dry_run: bool):
-    """Save current layout under a name.
-
-    Fetches the active layout from the running Cyclist/BikeRack server
-    and stores it in config.local.yaml under the given name.
-    """
-    layout_data = _get_current_layout()
-    if not layout_data:
-        click.echo(
-            json.dumps({"success": False, "error": "No running Cyclist/BikeRack server found, or layout is empty"}),
-            err=True,
-        )
-        sys.exit(1)
-    if dry_run:
-        panel_count = len(layout_data.get("panels", {}))
-        click.echo(json.dumps({"dry_run": True, "action": "save_layout", "name": name, "panels": panel_count}))
-        return
-    result = save_named_layout(name, layout_data)
-    if result["success"]:
-        panel_count = len(layout_data.get("panels", {}))
-        click.echo(json.dumps({"success": True, "name": result["data"], "panels": panel_count}))
-    else:
-        click.echo(json.dumps({"success": False, "error": result["error"]}), err=True)
-        sys.exit(1)
-
-
-@bc.command("load")
-@click.argument("name")
-@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
-def load_layout(name: str, dry_run: bool):
-    """Load a previously saved named layout."""
-    if dry_run:
-        click.echo(json.dumps({"dry_run": True, "action": "load_layout", "name": name}))
-        return
-    result = load_named_layout(name)
-    if result["success"]:
-        click.echo(json.dumps({"success": True, "name": name, "layout": result["data"]}))
-    else:
-        click.echo(json.dumps({"success": False, "error": result["error"]}), err=True)
-        sys.exit(1)
-
-
-@bc.command("list")
-def list_layouts():
-    """List all saved named layouts."""
-    result = list_named_layouts()
-    if result["success"]:
-        click.echo(json.dumps({"success": True, "layouts": result["data"]}))
-    else:
-        click.echo(json.dumps({"success": False, "error": result["error"]}), err=True)
-        sys.exit(1)
-
-
-@bc.command("clear")
-@click.argument("name")
-@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
-def clear_layout(name: str, dry_run: bool):
-    """Delete a specific named layout."""
-    if dry_run:
-        click.echo(json.dumps({"dry_run": True, "action": "clear_layout", "name": name}))
-        return
-    result = clear_named_layout(name)
-    if result["success"]:
-        click.echo(json.dumps({"success": True, "message": result.get("message", "layout cleared")}))
-    else:
-        click.echo(json.dumps({"success": False, "error": result["error"]}), err=True)
-        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):
-    """Delete all named layouts."""
-    if dry_run:
-        click.echo(json.dumps({"dry_run": True, "action": "clear_all_layouts"}))
-        return
-    result = clear_all_named_layouts()
-    if result["success"]:
-        click.echo(json.dumps({"success": True, "message": result.get("message", "all layouts cleared")}))
-    else:
-        click.echo(json.dumps({"success": False, "error": result["error"]}), err=True)
-        sys.exit(1)