@pennyfarthing/core 11.0.0 → 11.1.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))

package/pennyfarthing_scripts/handoff/complete_phase.py

@@ -0,0 +1,155 @@
+"""Complete phase transition with atomic session update.
+
+Atomically updates the session file (temp + mv) with phase transition,
+timestamps, and history table entries.
+
+Story: 105-1 (Script-First Handoff)
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import tempfile
+from datetime import UTC, datetime
+from pathlib import Path
+
+import yaml
+
+
+def complete_phase(
+    story_id: str,
+    workflow: str,
+    from_phase: str,
+    to_phase: str,
+    gate_type: str,
+    project_root: Path | None = None,
+) -> dict:
+    """Complete a phase transition with atomic session file update.
+
+    Args:
+        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")
+        project_root: Project root path. Auto-detected if None.
+
+    Returns:
+        COMPLETE_RESULT dict with keys:
+            status: "success" | "error"
+            session_file: str (path to session file)
+            error: str | None
+    """
+    if project_root is None:
+        project_root = _find_project_root()
+
+    session_path = project_root / ".session" / f"{story_id}-session.md"
+    if not session_path.exists():
+        return {
+            "status": "error",
+            "session_file": None,
+            "error": "Session file not found",
+        }
+
+    content = session_path.read_text()
+    now = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    from_agent = _get_phase_agent(project_root, workflow, from_phase)
+    to_agent = _get_phase_agent(project_root, workflow, to_phase)
+
+    # Update all **Phase:** lines to new phase
+    content = re.sub(r"(\*\*Phase:\*\*) \S+", rf"\1 {to_phase}", content)
+
+    # Update all **Phase Started:** lines to now
+    content = re.sub(r"(\*\*Phase Started:\*\*) \S+", rf"\1 {now}", content)
+
+    # Update Phase History: fill Ended/Duration for from_phase, add new row
+    lines = content.splitlines()
+    result_lines = []
+    for line in lines:
+        if line.strip().startswith(f"| {from_phase}"):
+            cols = [c.strip() for c in line.split("|") if c.strip()]
+            if len(cols) >= 4 and cols[2] == "-":
+                started_str = cols[1]
+                duration = _calc_duration(started_str, now)
+                result_lines.append(
+                    f"| {from_phase} | {started_str} | {now} | {duration} |"
+                )
+                result_lines.append(f"| {to_phase} | {now} | - | - |")
+                continue
+        result_lines.append(line)
+    content = "\n".join(result_lines)
+
+    # Add Handoff History row at end of table
+    handoff_row = (
+        f"| {from_phase} ({from_agent}) | {to_phase} ({to_agent}) "
+        f"| {gate_type} | PASSED | {now} |"
+    )
+    lines = content.splitlines()
+    insert_after = None
+    in_handoff = False
+    for i, line in enumerate(lines):
+        if "### Handoff History" in line:
+            in_handoff = True
+        if in_handoff and line.strip().startswith("|"):
+            insert_after = i
+    if insert_after is not None:
+        lines.insert(insert_after + 1, handoff_row)
+    content = "\n".join(lines)
+
+    # Atomic write: temp file in same directory + rename
+    temp_fd, temp_path_str = tempfile.mkstemp(
+        dir=str(session_path.parent), suffix=".tmp"
+    )
+    os.close(temp_fd)
+    temp_path = Path(temp_path_str)
+    try:
+        temp_path.write_text(content)
+        temp_path.rename(session_path)
+    except Exception:
+        temp_path.unlink(missing_ok=True)
+        raise
+
+    return {
+        "status": "success",
+        "session_file": f".session/{story_id}-session.md",
+        "error": None,
+    }
+
+
+def _calc_duration(started_str: str, ended_str: str) -> str:
+    started = datetime.fromisoformat(started_str.replace("Z", "+00:00"))
+    ended = datetime.fromisoformat(ended_str.replace("Z", "+00:00"))
+    total_seconds = int((ended - started).total_seconds())
+    if total_seconds < 60:
+        return f"{total_seconds}s"
+    minutes = total_seconds // 60
+    seconds = total_seconds % 60
+    if total_seconds < 3600:
+        return f"{minutes}m {seconds}s" if seconds else f"{minutes}m"
+    hours = total_seconds // 3600
+    rem_minutes = (total_seconds % 3600) // 60
+    return f"{hours}h {rem_minutes}m" if rem_minutes else f"{hours}h"
+
+
+def _get_phase_agent(project_root: Path, workflow: str, phase: str) -> str:
+    for name in [f"{workflow}.yaml", f"{workflow}/workflow.yaml"]:
+        path = project_root / ".pennyfarthing" / "workflows" / name
+        if path.exists():
+            try:
+                data = yaml.safe_load(path.read_text())
+                for p in data["workflow"]["phases"]:
+                    if p["name"] == phase:
+                        return p.get("agent", phase)
+            except Exception:
+                pass
+    return phase
+
+
+def _find_project_root() -> Path:
+    cwd = Path.cwd()
+    for parent in [cwd, *cwd.parents]:
+        if (parent / ".pennyfarthing").is_dir():
+            return parent
+    return cwd