@pennyfarthing/core 11.0.0-alpha.0 → 11.1.0

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

package/pennyfarthing_scripts/handoff/gate_file.py

@@ -0,0 +1,105 @@
+"""Gate file discovery and resolution.
+
+Resolves gate file references (e.g., "gates/tests-pass") to actual file paths.
+Resolution order:
+  1. .pennyfarthing/gates/{name}.md  (project-local override)
+  2. pennyfarthing-dist/gates/{name}.md  (built-in fallback)
+
+Non-existent files return an error result with status "blocked".
+
+Story: 106-4 (Gate File Discovery and Resolution)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def resolve_gate_file(
+    gate_ref: str,
+    project_root: Path | None = None,
+) -> dict:
+    """Resolve a gate file reference to an absolute file path.
+
+    Args:
+        gate_ref: Gate reference string (e.g., "gates/tests-pass" or "tests-pass")
+        project_root: Project root path. Auto-detected if None.
+
+    Returns:
+        dict with keys:
+            status: "found" | "not_found"
+            path: str | None  (absolute path if found)
+            error: str | None (error message if not found)
+    """
+    if project_root is None:
+        project_root = _find_project_root()
+
+    name = _sanitize_gate_name(gate_ref)
+    if name is None:
+        return _result(
+            status="not_found",
+            error=f"Invalid gate reference: {gate_ref!r}",
+        )
+
+    # Resolution order: local first, built-in fallback
+    search_paths = [
+        project_root / ".pennyfarthing" / "gates" / f"{name}.md",
+        project_root / "pennyfarthing-dist" / "gates" / f"{name}.md",
+    ]
+
+    for candidate in search_paths:
+        if candidate.is_file():
+            return _result(status="found", path=str(candidate.resolve()))
+
+    return _result(
+        status="not_found",
+        error=f"Gate file not found: {name}",
+    )
+
+
+def _sanitize_gate_name(gate_ref: str) -> str | None:
+    """Extract a clean gate name from a reference string.
+
+    Strips 'gates/' prefix and '.md' suffix. Rejects empty names
+    and path traversal attempts.
+    """
+    if not gate_ref:
+        return None
+
+    name = gate_ref
+    # Strip gates/ prefix
+    if name.startswith("gates/"):
+        name = name[len("gates/"):]
+    # Strip .md suffix
+    if name.endswith(".md"):
+        name = name[: -len(".md")]
+
+    if not name:
+        return None
+
+    # Reject path traversal
+    if ".." in name or "/" in name:
+        return None
+
+    return name
+
+
+def _result(
+    status: str,
+    path: str | None = None,
+    error: str | None = None,
+) -> dict:
+    return {
+        "status": status,
+        "path": path,
+        "error": error,
+    }
+
+
+def _find_project_root() -> Path:
+    """Walk up from cwd looking for .pennyfarthing/ directory."""
+    cwd = Path.cwd()
+    for parent in [cwd, *cwd.parents]:
+        if (parent / ".pennyfarthing").is_dir():
+            return parent
+    return cwd

package/pennyfarthing_scripts/handoff/gate_runner.py

@@ -0,0 +1,152 @@
+"""Gate subagent runner — parse gate files and extract GATE_RESULT.
+
+Provides two core functions for the agent exit protocol (step 6):
+  1. parse_gate_file(path) — read gate file, extract model/name/content
+  2. extract_gate_result(raw_output) — regex-extract GATE_RESULT from subagent output
+
+The actual subagent spawning is handled by the Claude agent via Task tool.
+These functions provide the parsing layer around that interaction.
+
+Default-deny: missing or unparseable GATE_RESULT always returns fail.
+Gate files are read-only at runtime — never written to.
+
+Story: 106-2 (Gate subagent runner with GATE_RESULT contract)
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+_DEFAULT_FAIL: dict = {
+    "status": "fail",
+    "message": "Gate evaluation failed or did not return GATE_RESULT",
+    "checks": [],
+}
+
+
+def parse_gate_file(
+    gate_path: str | Path,
+) -> dict:
+    """Parse a gate file and extract its metadata and content.
+
+    Reads the gate file (read-only), extracts the model attribute and gate name
+    from the <gate> tag, and returns the full content for subagent prompting.
+
+    Args:
+        gate_path: Absolute path to the gate file.
+
+    Returns:
+        dict with keys:
+            status: "ok" | "error"
+            name: str | None (gate name from <gate name="...">)
+            model: str (model from <gate model="..."> or "haiku")
+            content: str | None (full gate file content)
+            error: str | None
+    """
+    path = Path(gate_path)
+
+    if not path.exists():
+        return {
+            "status": "error",
+            "name": None,
+            "model": "haiku",
+            "content": None,
+            "error": f"Gate file not found: {path}",
+        }
+
+    content = path.read_text()
+
+    gate_match = re.search(r"<gate\b[^>]*>", content)
+    if not gate_match:
+        return {
+            "status": "error",
+            "name": None,
+            "model": "haiku",
+            "content": None,
+            "error": "No <gate> tag found in file",
+        }
+
+    gate_tag = gate_match.group(0)
+
+    name_match = re.search(r'name="([^"]+)"', gate_tag)
+    name = name_match.group(1) if name_match else None
+
+    model_match = re.search(r'model="([^"]+)"', gate_tag)
+    model = model_match.group(1) if model_match else "haiku"
+
+    return {
+        "status": "ok",
+        "name": name,
+        "model": model,
+        "content": content,
+        "error": None,
+    }
+
+
+def extract_gate_result(
+    raw_output: str | None,
+) -> dict:
+    """Extract GATE_RESULT from raw subagent output via regex.
+
+    Parses the subagent's text output to find a GATE_RESULT YAML block.
+    Uses regex/grep patterns — NOT a full YAML parser.
+
+    Default-deny: if GATE_RESULT cannot be extracted, returns fail.
+
+    Args:
+        raw_output: Raw text output from the gate subagent.
+
+    Returns:
+        dict with keys:
+            status: "pass" | "fail"
+            message: str
+            checks: list[dict] (each with name, status, detail)
+    """
+    if raw_output is None or not raw_output.strip():
+        return dict(_DEFAULT_FAIL)
+
+    # Split on GATE_RESULT: and take the last block (AC7: multiple → last wins)
+    blocks = raw_output.split("GATE_RESULT:")
+    if len(blocks) < 2:
+        return dict(_DEFAULT_FAIL)
+
+    block = blocks[-1]
+
+    # Extract status — strict enum: only "pass" or "fail"
+    status_match = re.search(r"^\s*status:\s*(pass|fail)\s*$", block, re.MULTILINE)
+    if not status_match:
+        return dict(_DEFAULT_FAIL)
+
+    status = status_match.group(1)
+
+    # Extract message — double-quoted, single-quoted, or unquoted
+    message_match = re.search(
+        r"""^\s*message:\s*(?:"([^"]*)"|'([^']*)'|(.+?))\s*$""",
+        block,
+        re.MULTILINE,
+    )
+    message = ""
+    if message_match:
+        message = message_match.group(1) or message_match.group(2) or message_match.group(3) or ""
+
+    # Extract checks list via regex on consecutive name/status/detail lines
+    checks: list[dict] = []
+    check_pattern = re.compile(
+        r"^\s*-\s*name:\s*(?:\"([^\"]*)\"|'([^']*)'|(\S+))\s*\n"
+        r"\s*status:\s*(pass|fail)\s*\n"
+        r"\s*detail:\s*(?:\"([^\"]*)\"|'([^']*)'|(.+?))\s*$",
+        re.MULTILINE,
+    )
+    for m in check_pattern.finditer(block):
+        checks.append({
+            "name": m.group(1) or m.group(2) or m.group(3),
+            "status": m.group(4),
+            "detail": m.group(5) or m.group(6) or m.group(7) or "",
+        })
+
+    return {
+        "status": status,
+        "message": message,
+        "checks": checks,
+    }

package/pennyfarthing_scripts/handoff/marker.py

@@ -0,0 +1,109 @@
+"""Generate AGENT_COMMAND block for handoff markers.
+
+Replaces handoff-marker.sh with a Python implementation that reuses
+the existing context.py module for environment detection.
+
+Story: 105-4 (Script-First Handoff)
+"""
+
+from __future__ import annotations
+
+from pennyfarthing_scripts.context import check_context
+
+
+def generate_marker(
+    next_agent: str | None = None,
+    *,
+    error: str | None = None,
+) -> str:
+    """Generate an AGENT_COMMAND block for agent handoff.
+
+    Args:
+        next_agent: Agent to hand off to (e.g., "dev", "tea", "reviewer").
+        error: If set, generates an error block instead of a handoff.
+
+    Returns:
+        YAML-formatted AGENT_COMMAND block string.
+    """
+    if error:
+        return _block(fallback=error, error=True)
+
+    if not next_agent:
+        return _block(fallback="No next agent specified", error=True)
+
+    ctx = check_context()
+
+    cmd = f"/pf-{next_agent}"
+    pct = ctx.usable_percent if not ctx.error else "unknown"
+
+    if pct != "unknown" and pct >= 60:
+        context_warning = f" (context: {pct}% - consider /clear before continuing)"
+    elif pct != "unknown":
+        context_warning = f" (context: {pct}%)"
+    else:
+        context_warning = ""
+
+    if not ctx.relay_mode:
+        # Relay off — ask for confirmation
+        if ctx.is_cyclist:
+            return _block(
+                marker="<!-- CYCLIST:QUESTION:yesno -->",
+                question=f"Ready to hand off to {cmd}?",
+                fallback=f"Run `{cmd}` to continue",
+            )
+        return _block(
+            fallback=f"Run `{cmd}` to continue{context_warning}",
+            relay_mode=False,
+            context_percent=pct,
+        )
+
+    # Relay on — auto-handoff
+    # Cyclist uses its feedback loop (QuickActions → slash command injection).
+    # Non-Cyclist: we're already in the session, invoke the agent directly.
+    marker = None
+    if ctx.use_tirepump:
+        marker = f"<!-- CYCLIST:CONTEXT_CLEAR:{cmd} -->" if ctx.is_cyclist else None
+    else:
+        marker = f"<!-- CYCLIST:HANDOFF:{cmd} -->" if ctx.is_cyclist else None
+
+    if ctx.is_cyclist:
+        return _block(
+            marker=marker,
+            fallback=f"Run `{cmd}` to continue",
+        )
+
+    # Non-Cyclist relay: invoke the next agent directly
+    import subprocess
+    try:
+        result = subprocess.run(
+            ["pf", "agent", "start", next_agent],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        agent_output = result.stdout.strip()
+    except Exception as e:
+        agent_output = f"Failed to invoke agent: {e}"
+
+    return _block(
+        fallback=f"Run `{cmd}` to continue{context_warning}",
+        relay_mode=True,
+        context_percent=pct,
+        invoke=cmd,
+    ) + f"\n\n{agent_output}"
+
+
+def _block(**fields: object) -> str:
+    """Format an AGENT_COMMAND YAML block."""
+    lines = ["---", "AGENT_COMMAND:"]
+    for key, value in fields.items():
+        if isinstance(value, bool):
+            lines.append(f"  {key}: {str(value).lower()}")
+        elif isinstance(value, str) and value:
+            lines.append(f'  {key}: "{value}"')
+        elif value == "":
+            lines.append(f'  {key}: ""')
+        else:
+            lines.append(f"  {key}: {value}")
+    lines.append("---")
+    return "\n".join(lines)

package/pennyfarthing_scripts/handoff/resolve_gate.py

@@ -0,0 +1,152 @@
+"""Resolve gate for current workflow phase.
+
+Reads workflow YAML, finds current phase gate, checks for assessment
+section in session file, and returns a structured RESOLVE_RESULT.
+
+Story: 105-1 (Script-First Handoff)
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import yaml
+
+
+def resolve_gate(
+    story_id: str,
+    workflow: str,
+    phase: str,
+    project_root: Path | None = None,
+) -> dict:
+    """Resolve the gate for the current workflow phase.
+
+    Args:
+        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")
+        project_root: Project root path. Auto-detected if None.
+
+    Returns:
+        RESOLVE_RESULT dict with keys:
+            status: "ready" | "blocked" | "skip"
+            gate_type: str | None
+            gate_file: str | None
+            next_agent: str | None
+            next_phase: str | None
+            assessment_found: bool
+            error: str | None
+    """
+    if project_root is None:
+        project_root = _find_project_root()
+
+    workflow_path = _find_workflow_yaml(project_root, workflow)
+    if workflow_path is None:
+        return _result(status="error", error=f"Workflow '{workflow}' not found")
+
+    try:
+        data = yaml.safe_load(workflow_path.read_text())
+        phases = data["workflow"]["phases"]
+    except Exception as e:
+        return _result(status="error", error=f"Failed to parse workflow: {e}")
+
+    current_idx = None
+    current_phase = None
+    for i, p in enumerate(phases):
+        if p["name"] == phase:
+            current_idx = i
+            current_phase = p
+            break
+
+    if current_phase is None:
+        return _result(
+            status="error",
+            error=f"Phase '{phase}' not found in workflow '{workflow}'",
+        )
+
+    gate = current_phase.get("gate")
+
+    if current_idx + 1 < len(phases):
+        nxt = phases[current_idx + 1]
+        next_phase = nxt["name"]
+        next_agent = nxt["agent"]
+    else:
+        next_phase = None
+        next_agent = None
+
+    if not gate:
+        return _result(
+            status="skip",
+            next_agent=next_agent,
+            next_phase=next_phase,
+            assessment_found=True,
+        )
+
+    gate_type = gate.get("type")
+    gate_file = gate.get("file")
+
+    if gate_type == "manual":
+        return _result(
+            status="skip",
+            gate_type="manual",
+            next_agent=next_agent,
+            next_phase=next_phase,
+            assessment_found=True,
+        )
+
+    session_path = project_root / ".session" / f"{story_id}-session.md"
+    assessment_found = False
+    if session_path.exists():
+        content = session_path.read_text()
+        assessment_found = bool(
+            re.search(r"^##\s+.*Assessment", content, re.MULTILINE)
+        )
+
+    status = "ready" if assessment_found else "blocked"
+    return _result(
+        status=status,
+        gate_type=gate_type,
+        gate_file=gate_file,
+        next_agent=next_agent,
+        next_phase=next_phase,
+        assessment_found=assessment_found,
+    )
+
+
+def _result(
+    status: str,
+    gate_type: str | None = None,
+    gate_file: str | None = None,
+    next_agent: str | None = None,
+    next_phase: str | None = None,
+    assessment_found: bool = False,
+    error: str | None = None,
+) -> dict:
+    return {
+        "status": status,
+        "gate_type": gate_type,
+        "gate_file": gate_file,
+        "next_agent": next_agent,
+        "next_phase": next_phase,
+        "assessment_found": assessment_found,
+        "error": error,
+    }
+
+
+def _find_workflow_yaml(project_root: Path, workflow: str) -> Path | None:
+    flat = project_root / ".pennyfarthing" / "workflows" / f"{workflow}.yaml"
+    if flat.exists():
+        return flat
+    subdir = project_root / ".pennyfarthing" / "workflows" / workflow / "workflow.yaml"
+    if subdir.exists():
+        return subdir
+    return None
+
+
+def _find_project_root() -> Path:
+    cwd = Path.cwd()
+    for parent in [cwd, *cwd.parents]:
+        if (parent / ".pennyfarthing").is_dir():
+            return parent
+    return cwd