@pennyfarthing/core 11.0.0-alpha.0 → 11.1.0

package/pennyfarthing_scripts/epic/cli.py

@@ -0,0 +1,64 @@
+"""
+Epic CLI - Click-based CLI for epic lifecycle management.
+
+Usage:
+    pf epic [COMMAND] [ARGS]...
+
+Commands:
+    start  Start an epic - move to current sprint and generate context
+    close  Close an epic - verify completion and archive
+"""
+
+import click
+
+
+@click.group()
+def epic():
+    """Epic lifecycle management.
+
+    \b
+    Commands:
+      start  - Start an epic (move to sprint + generate tech context)
+      close  - Close an epic (verify completion + archive)
+    """
+    pass
+
+
+@epic.command()
+@click.argument("epic_id")
+def start(epic_id: str):
+    """Start an epic - move to current sprint and generate tech context.
+
+    \b
+    Arguments:
+      EPIC_ID  - Epic identifier (e.g., 79, epic-79)
+    """
+    # Normalize epic ID
+    if not epic_id.startswith("epic-"):
+        epic_id = f"epic-{epic_id}"
+
+    click.echo(f"Starting epic {epic_id}...")
+    click.echo("1. Checking epic location in sprint files...")
+    click.echo("2. Moving to current sprint if needed...")
+    click.echo("3. Generating tech context via SM agent...")
+    click.echo(f"\nTo complete setup, run: /sm with task epic-tech-context for {epic_id}")
+
+
+@epic.command()
+@click.argument("epic_id")
+def close(epic_id: str):
+    """Close an epic - verify completion, update status, and archive.
+
+    \b
+    Arguments:
+      EPIC_ID  - Epic identifier (e.g., 79, epic-79)
+    """
+    # Normalize epic ID
+    if not epic_id.startswith("epic-"):
+        epic_id = f"epic-{epic_id}"
+
+    click.echo(f"Closing epic {epic_id}...")
+    click.echo("1. Verifying all stories are done...")
+    click.echo("2. Updating epic status to done...")
+    click.echo("3. Archiving epic context...")
+    click.echo(f"\nUse pf sprint epic archive {epic_id} to complete the archival.")

package/pennyfarthing_scripts/gate/__init__.py

@@ -0,0 +1 @@
+"""Gate file operations — validation, inspection, and authoring tools."""

package/pennyfarthing_scripts/gate/cli.py

@@ -0,0 +1,56 @@
+"""Gate CLI — gate file operations.
+
+Usage:
+    pf gate validate <file>    # Validate a gate file
+"""
+
+from __future__ import annotations
+
+import click
+
+from pennyfarthing_scripts.common.output import error, info, success
+
+
+@click.group()
+def gate():
+    """Gate file operations.
+
+    \b
+    Commands:
+      validate  - Validate a gate file for schema, depth, and cycles
+    """
+    pass
+
+
+@gate.command("validate")
+@click.argument("file", type=click.Path(exists=True))
+def gate_validate(file: str):
+    """Validate a gate file for schema, cycles, and depth.
+
+    Checks:
+      - Schema: <gate name="...">, <purpose>, <pass>, <fail>
+      - Depth: nesting does not exceed 3 levels
+      - Cycles: no duplicate gate names
+      - Completeness: all required elements non-empty
+
+    Reports ALL errors at once. On success, prints a structure summary.
+    """
+    from pennyfarthing_scripts.gate.validate import validate_gate_file
+
+    result = validate_gate_file(file)
+
+    if result.valid:
+        name = result.gate_name or "(unnamed)"
+        success(f"Gate '{name}' is valid")
+        info(f"  Model: {result.model or 'haiku'}")
+        if result.child_count > 0:
+            info(f"  Depth: {result.depth} ({result.child_count} nested gate(s))")
+        else:
+            info(f"  Depth: {result.depth} (no nesting)")
+        info(f"  Children: {result.child_count}")
+    else:
+        name = result.gate_name or file
+        error(f"Gate '{name}' has {len(result.errors)} error(s):")
+        for err in result.errors:
+            error(f"  - {err}")
+        raise SystemExit(1)

package/pennyfarthing_scripts/gate/validate.py

@@ -0,0 +1,266 @@
+"""Gate file validation — schema, depth, cycles, and mandatory elements.
+
+Validates a gate file for:
+  1. Schema: <gate name="..."> with <purpose>, <pass>, <fail>
+  2. Depth: max nesting depth of 3
+  3. Cycles: no duplicate gate names
+  4. Completeness: all required elements non-empty
+
+Reports ALL errors at once (not fail-fast).
+
+Story: 107-3 (Gate authoring guide and validation command)
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+MAX_DEPTH = 3
+
+
+@dataclass
+class GateInfo:
+    """Parsed gate metadata."""
+
+    name: str
+    model: str = "haiku"
+    depth: int = 0
+    children: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ValidationResult:
+    """Result of gate file validation."""
+
+    valid: bool
+    gate_name: str | None = None
+    model: str | None = None
+    depth: int = 0
+    child_count: int = 0
+    errors: list[str] = field(default_factory=list)
+
+
+def validate_gate_file(path: str | Path) -> ValidationResult:
+    """Validate a gate file for schema compliance, depth, and cycles.
+
+    Args:
+        path: Path to the gate file.
+
+    Returns:
+        ValidationResult with all errors collected.
+    """
+    path = Path(path)
+    errors: list[str] = []
+
+    if not path.exists():
+        return ValidationResult(valid=False, errors=[f"File not found: {path}"])
+
+    content = path.read_text()
+    if not content.strip():
+        return ValidationResult(valid=False, errors=["File is empty"])
+
+    # Tokenize all gate-related tags
+    tokens = _tokenize(content)
+
+    if not tokens:
+        return ValidationResult(
+            valid=False,
+            errors=["No <gate> tag found in file"],
+        )
+
+    # Parse gate structure and collect errors
+    gate_names: list[str] = []
+    root_name: str | None = None
+    root_model: str | None = None
+    max_depth = 0
+    depth = 0
+
+    for token in tokens:
+        if token["type"] == "gate_open":
+            name = token.get("name")
+            model = token.get("model", "haiku")
+
+            if depth == 0:
+                root_name = name
+                root_model = model
+
+            if not name:
+                errors.append(
+                    f"Gate element at depth {depth} missing required 'name' attribute"
+                )
+            else:
+                # Check for duplicate names (cycle indicator)
+                if name in gate_names:
+                    errors.append(
+                        f"Duplicate gate name '{name}' — names must be unique within a file"
+                    )
+                gate_names.append(name)
+
+            depth += 1
+            if depth - 1 > max_depth:
+                max_depth = depth - 1
+
+            # Depth limit check (depth is 0-indexed, so depth-1 after increment)
+            if depth - 1 > MAX_DEPTH:
+                gate_label = name or "(unnamed)"
+                errors.append(
+                    f"Gate depth limit exceeded: '{gate_label}' at depth {depth - 1} (max {MAX_DEPTH})"
+                )
+
+        elif token["type"] == "gate_close":
+            depth -= 1
+
+    # Validate required child elements for each gate
+    _validate_required_elements(content, gate_names, errors)
+
+    child_count = len(gate_names) - 1 if len(gate_names) > 1 else 0
+
+    return ValidationResult(
+        valid=len(errors) == 0,
+        gate_name=root_name,
+        model=root_model,
+        depth=max_depth,
+        child_count=child_count,
+        errors=errors,
+    )
+
+
+def _tokenize(content: str) -> list[dict]:
+    """Tokenize gate-related XML tags from content."""
+    tokens: list[dict] = []
+
+    # Match opening gate tags with attributes
+    open_pattern = re.compile(r"<gate\b([^>]*)>", re.IGNORECASE)
+    close_pattern = re.compile(r"</gate\s*>", re.IGNORECASE)
+
+    # Build a list of all tags with their positions
+    events: list[tuple[int, dict]] = []
+
+    for m in open_pattern.finditer(content):
+        attrs = m.group(1)
+        name_match = re.search(r'name="([^"]*)"', attrs)
+        model_match = re.search(r'model="([^"]*)"', attrs)
+        events.append((m.start(), {
+            "type": "gate_open",
+            "name": name_match.group(1) if name_match else None,
+            "model": model_match.group(1) if model_match else "haiku",
+        }))
+
+    for m in close_pattern.finditer(content):
+        events.append((m.start(), {"type": "gate_close"}))
+
+    # Sort by position
+    events.sort(key=lambda e: e[0])
+    tokens = [e[1] for e in events]
+
+    return tokens
+
+
+def _validate_required_elements(
+    content: str,
+    gate_names: list[str],
+    errors: list[str],
+) -> None:
+    """Validate that each gate has <purpose>, <pass>, and <fail> elements.
+
+    For each gate, checks that required child elements exist and are non-empty
+    within the gate's scope.
+    """
+    # For simple files with one gate, check globally
+    # For nested files, check per-gate scope
+    if len(gate_names) <= 1:
+        name = gate_names[0] if gate_names else "(unnamed)"
+        _check_required_for_gate(content, name, errors)
+    else:
+        # Split content by gate scopes and validate each
+        # Use a stack-based approach to extract each gate's direct content
+        _validate_nested_gates(content, errors)
+
+
+def _check_required_for_gate(
+    scope_content: str,
+    gate_name: str,
+    errors: list[str],
+) -> None:
+    """Check that a gate scope contains non-empty <purpose>, <pass>, <fail>."""
+    for element in ("purpose", "pass", "fail"):
+        pattern = re.compile(
+            rf"<{element}>(.*?)</{element}>",
+            re.DOTALL | re.IGNORECASE,
+        )
+        match = pattern.search(scope_content)
+        if not match:
+            errors.append(f"Gate '{gate_name}' missing required <{element}> block")
+        elif not match.group(1).strip():
+            errors.append(f"Gate '{gate_name}' has empty <{element}> block")
+
+
+def _validate_nested_gates(content: str, errors: list[str]) -> None:
+    """Validate required elements for each gate in a nested structure."""
+    # Extract each gate's scope using a stack-based parser
+    open_pattern = re.compile(r"<gate\b([^>]*)>", re.IGNORECASE)
+    close_pattern = re.compile(r"</gate\s*>", re.IGNORECASE)
+
+    events: list[tuple[int, str, str | None]] = []
+
+    for m in open_pattern.finditer(content):
+        name_match = re.search(r'name="([^"]*)"', m.group(1))
+        name = name_match.group(1) if name_match else None
+        events.append((m.start(), "open", name))
+
+    for m in close_pattern.finditer(content):
+        events.append((m.start(), "close", None))
+
+    events.sort(key=lambda e: e[0])
+
+    # Stack-based scope extraction
+    stack: list[tuple[str | None, int]] = []  # (name, start_pos)
+
+    for pos, event_type, name in events:
+        if event_type == "open":
+            stack.append((name, pos))
+        elif event_type == "close" and stack:
+            gate_name, start_pos = stack.pop()
+            # Extract this gate's direct content (between open and close)
+            gate_scope = content[start_pos:pos]
+            # Remove nested gate content to check only direct children
+            direct_content = _remove_nested_gates(gate_scope)
+            label = gate_name or "(unnamed)"
+            _check_required_for_gate(direct_content, label, errors)
+
+
+def _remove_nested_gates(scope: str) -> str:
+    """Remove nested <gate>...</gate> blocks from scope content.
+
+    Keeps the outermost gate's direct content only.
+    """
+    depth = 0
+    result: list[str] = []
+    i = 0
+
+    open_pattern = re.compile(r"<gate\b[^>]*>", re.IGNORECASE)
+    close_pattern = re.compile(r"</gate\s*>", re.IGNORECASE)
+
+    while i < len(scope):
+        open_match = open_pattern.match(scope, i)
+        close_match = close_pattern.match(scope, i)
+
+        if open_match:
+            depth += 1
+            if depth <= 1:
+                # Keep the outermost gate open tag
+                result.append(open_match.group())
+            i = open_match.end()
+        elif close_match:
+            if depth <= 1:
+                result.append(close_match.group())
+            depth -= 1
+            i = close_match.end()
+        else:
+            if depth <= 1:
+                result.append(scope[i])
+            i += 1
+
+    return "".join(result)

package/pennyfarthing_scripts/git_group/cli.py

@@ -0,0 +1,100 @@
+"""
+Git CLI - Click-based CLI for git repository operations.
+
+Usage:
+    pf git [COMMAND] [ARGS]...
+
+Commands:
+    status    Check git status of all project repos
+    cleanup   Organize changes into proper commits/branches
+    branches  Create feature branches from a story
+    release   Interactive release with verification gates
+"""
+
+import click
+
+from pennyfarthing_scripts.common.config import get_project_root
+
+
+@click.group()
+def git():
+    """Repository operations across all configured repos.
+
+    \b
+    Commands:
+      status    - Check git status of all repos
+      cleanup   - Organize changes into commits/branches
+      branches  - Create feature branches from a story
+      release   - Interactive release with verification gates
+    """
+    pass
+
+
+@git.command()
+@click.option("--brief", is_flag=True, help="One-line-per-repo summary")
+def status(brief: bool):
+    """Check git status of all project repos.
+
+    Shows branch, uncommitted changes, and ahead/behind status for each repo.
+    """
+    import subprocess
+
+    root = get_project_root()
+    script = root / ".pennyfarthing" / "scripts" / "git" / "git-status-all.sh"
+
+    if not script.is_file():
+        click.echo("Error: git-status-all.sh not found", err=True)
+        raise SystemExit(1)
+
+    cmd = [str(script)]
+    if brief:
+        cmd.append("--brief")
+
+    result = subprocess.run(cmd, cwd=str(root))
+    raise SystemExit(result.returncode)
+
+
+@git.command()
+def cleanup():
+    """Organize changes into proper commits and branches.
+
+    Starts the git-cleanup stepped workflow via BikeLane.
+    Equivalent to: /pf-workflow start git-cleanup
+    """
+    click.echo("Starting git-cleanup workflow...")
+    click.echo("Run: /pf-workflow start git-cleanup")
+    click.echo("Or:  pf workflow start git-cleanup")
+
+
+@git.command()
+@click.argument("story_id")
+def branches(story_id: str):
+    """Create feature branches in both repos from a story.
+
+    \b
+    Arguments:
+      STORY_ID  - The story ID to create branches for (e.g., 86-3)
+    """
+    import subprocess
+
+    root = get_project_root()
+    script = root / ".pennyfarthing" / "scripts" / "git" / "create-branches.sh"
+
+    if not script.is_file():
+        click.echo("Error: create-branches.sh not found", err=True)
+        raise SystemExit(1)
+
+    result = subprocess.run([str(script), story_id], cwd=str(root))
+    raise SystemExit(result.returncode)
+
+
+@git.command()
+def release():
+    """Interactive release with verification gates.
+
+    Starts the release stepped workflow via BikeLane.
+    Equivalent to: /pf-workflow start release
+    """
+    click.echo("Starting release workflow...")
+    click.echo("Run: /pf-workflow start release")
+    click.echo("Or:  pf workflow start release")

package/pennyfarthing_scripts/handoff/__init__.py

@@ -0,0 +1 @@
+"""Handoff CLI — Phase gate resolution and atomic session transitions."""

package/pennyfarthing_scripts/handoff/cli.py

@@ -0,0 +1,120 @@
+"""Handoff CLI — Phase gate resolution, session transitions, and marker generation.
+
+Usage:
+    pf handoff resolve-gate STORY_ID WORKFLOW PHASE
+    pf handoff complete-phase STORY_ID WORKFLOW FROM_PHASE TO_PHASE GATE_TYPE
+    pf handoff marker NEXT_AGENT [--error MESSAGE]
+
+Stories: 105-1, 105-4 (Script-First Handoff)
+"""
+
+from __future__ import annotations
+
+import click
+
+
+@click.group()
+def handoff():
+    """Phase gate resolution and session transitions.
+
+    \b
+    Commands:
+      resolve-gate    - Resolve gate for current phase
+      complete-phase  - Complete phase transition atomically
+      marker          - Generate AGENT_COMMAND handoff marker
+    """
+    pass
+
+
+@handoff.command("resolve-gate")
+@click.argument("story_id")
+@click.argument("workflow")
+@click.argument("phase")
+def resolve_gate_cmd(story_id: str, workflow: str, phase: str):
+    """Resolve the gate for the current workflow phase.
+
+    Reads workflow YAML, checks assessment, returns RESOLVE_RESULT.
+
+    \b
+    Arguments:
+      STORY_ID  - Story identifier (e.g., 105-1)
+      WORKFLOW  - Workflow name (e.g., tdd, trivial, patch)
+      PHASE     - Current phase name (e.g., green, implement, fix)
+    """
+    from pennyfarthing_scripts.handoff.resolve_gate import resolve_gate
+
+    result = resolve_gate(story_id, workflow, phase)
+
+    import yaml
+
+    click.echo(yaml.dump({"RESOLVE_RESULT": result}, default_flow_style=False).rstrip())
+
+    if result.get("status") == "blocked":
+        raise SystemExit(1)
+
+
+@handoff.command("complete-phase")
+@click.argument("story_id")
+@click.argument("workflow")
+@click.argument("from_phase")
+@click.argument("to_phase")
+@click.argument("gate_type")
+def complete_phase_cmd(
+    story_id: str,
+    workflow: str,
+    from_phase: str,
+    to_phase: str,
+    gate_type: str,
+):
+    """Complete a phase transition with atomic session update.
+
+    Updates session file: phase line, timestamps, history tables.
+
+    \b
+    Arguments:
+      STORY_ID    - Story identifier (e.g., 105-1)
+      WORKFLOW    - Workflow name (e.g., tdd, trivial)
+      FROM_PHASE  - Phase being completed (e.g., green)
+      TO_PHASE    - Phase being entered (e.g., review)
+      GATE_TYPE   - Gate type that was passed (e.g., tests_pass)
+    """
+    from pennyfarthing_scripts.handoff.complete_phase import complete_phase
+
+    result = complete_phase(story_id, workflow, from_phase, to_phase, gate_type)
+
+    import yaml
+
+    click.echo(yaml.dump({"COMPLETE_RESULT": result}, default_flow_style=False).rstrip())
+
+    if result.get("status") == "error":
+        raise SystemExit(1)
+
+
+@handoff.command("marker")
+@click.argument("next_agent", required=False, default=None)
+@click.option("--error", "error_msg", default=None, help="Generate error marker")
+def marker_cmd(next_agent: str | None, error_msg: str | None):
+    """Generate AGENT_COMMAND handoff marker block.
+
+    Environment-aware marker generation. Detects Cyclist, relay mode,
+    and context usage to choose the appropriate marker type.
+
+    \b
+    Arguments:
+      NEXT_AGENT  - Agent to hand off to (e.g., dev, tea, reviewer)
+
+    \b
+    Options:
+      --error MSG - Generate an error marker instead of a handoff
+    """
+    from pennyfarthing_scripts.handoff.marker import generate_marker
+
+    if not next_agent and not error_msg:
+        raise click.UsageError(
+            "Provide NEXT_AGENT or --error MESSAGE.\n\n"
+            "Examples:\n"
+            "  pf handoff marker dev\n"
+            "  pf handoff marker --error 'Tests failing'"
+        )
+
+    click.echo(generate_marker(next_agent, error=error_msg))