@pennyfarthing/core 11.0.0 → 11.1.1

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

package/pennyfarthing_scripts/prime/workflow.py

@@ -275,3 +275,42 @@ def check_redirect(workflow_status: WorkflowStatus, agent_name: str) -> tuple[st
             )
 
     return None
+
+
+def get_phase_tandem_config(
+    workflow_name: str, phase_name: str, project_root: Path | None = None
+) -> dict[str, Any] | None:
+    """Extract tandem configuration for a specific workflow phase.
+
+    Reads the workflow YAML and returns the tandem block for the given phase,
+    or None if the phase has no tandem configuration.
+
+    Args:
+        workflow_name: Workflow name (tdd-tandem, bdd-tandem, etc.)
+        phase_name: Phase name (red, green, review, etc.)
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        Dict with tandem config (partner, mode, model, token_budget, triggers, scope)
+        or None if no tandem config on this phase.
+    """
+    root = project_root or get_project_root()
+    workflow_path = root / "pennyfarthing-dist" / "workflows" / f"{workflow_name}.yaml"
+
+    if not workflow_path.exists():
+        return None
+
+    try:
+        data = yaml.safe_load(workflow_path.read_text())
+        phases = data.get("workflow", {}).get("phases", [])
+
+        for phase in phases:
+            if isinstance(phase, dict) and phase.get("name") == phase_name:
+                tandem = phase.get("tandem")
+                if isinstance(tandem, dict):
+                    return dict(tandem)
+                return None
+
+        return None
+    except Exception:
+        return None