ref-agents 1.0.0__py3-none-any.whl

ref_agents/tools/gherkin_parser.py

@@ -0,0 +1,227 @@
+"""Gherkin parser for converting text to structured Gherkin models."""
+
+import re
+from typing import Literal, Optional, cast
+
+import structlog
+
+from ref_agents.models.gherkin import GherkinScenario, GherkinStep
+
+logger = structlog.get_logger(__name__)
+
+GherkinKeyword = Literal["Given", "When", "Then", "And", "But"]
+
+# Gherkin keyword patterns
+GHERKIN_KEYWORDS: list[GherkinKeyword] = ["Given", "When", "Then", "And", "But"]
+GHERKIN_KEYWORDS_LOWER = [kw.lower() for kw in GHERKIN_KEYWORDS]
+
+
+def parse_gherkin_text(text: str) -> list[GherkinScenario]:
+    """Parse Gherkin text into structured scenarios.
+
+    Args:
+        text: Gherkin-formatted text (can include multiple scenarios)
+
+    Returns:
+        List of GherkinScenario objects
+
+    Example:
+        text = '''
+        Scenario: User login
+        Given a user exists
+        When the user logs in
+        Then the user is authenticated
+        '''
+    """
+    scenarios = []
+    lines = text.strip().split("\n")
+
+    current_scenario: Optional[GherkinScenario] = None
+    current_steps: list[GherkinStep] = []
+
+    for line in lines:
+        line = line.strip()
+        if not line:
+            continue
+
+        # Check for scenario title
+        if line.lower().startswith("scenario:"):
+            # Save previous scenario if exists
+            if current_scenario:
+                current_scenario.steps = current_steps
+                scenarios.append(current_scenario)
+
+            scenario_title = line.split(":", 1)[1].strip()
+            current_scenario = GherkinScenario(scenario=scenario_title)
+            current_steps = []
+
+        # Check for Gherkin step
+        elif _is_gherkin_step(line):
+            step = _parse_step(line)
+            if step:
+                current_steps.append(step)
+
+    # Save last scenario
+    if current_scenario:
+        current_scenario.steps = current_steps
+        scenarios.append(current_scenario)
+    elif current_steps:
+        # If no scenario title, create default scenario
+        scenarios.append(
+            GherkinScenario(scenario="Default Scenario", steps=current_steps)
+        )
+
+    return scenarios
+
+
+def parse_markdown_ac(markdown_text: str) -> list[GherkinScenario]:
+    """Parse acceptance criteria from markdown format.
+
+    Handles formats like:
+    - **AC-1**: Given X, When Y, Then Z
+    - ### AC-1: Title
+      **Given** X
+      **When** Y
+      **Then** Z
+
+    Args:
+        markdown_text: Markdown-formatted acceptance criteria
+
+    Returns:
+        List of GherkinScenario objects
+    """
+    scenarios = []
+
+    # Pattern for AC with title: ### AC-1: Title
+    ac_title_pattern = r"^###\s*(AC-\d+|AC\d+):\s*(.+)$"
+    # Pattern for bold keywords: **Given** text
+    bold_keyword_pattern = r"\*\*(Given|When|Then|And|But)\*\*\s*(.+)$"
+
+    lines = markdown_text.strip().split("\n")
+    current_scenario: Optional[GherkinScenario] = None
+    current_steps: list[GherkinStep] = []
+
+    for line in lines:
+        line = line.strip()
+        if not line:
+            continue
+
+        # Check for AC title
+        title_match = re.match(ac_title_pattern, line, re.IGNORECASE)
+        if title_match:
+            # Save previous scenario
+            if current_scenario:
+                current_scenario.steps = current_steps
+                scenarios.append(current_scenario)
+
+            ac_id = title_match.group(1)
+            ac_title = title_match.group(2).strip()
+            current_scenario = GherkinScenario(scenario=f"{ac_id}: {ac_title}")
+            current_steps = []
+
+        # Check for bold keyword (markdown format)
+        elif current_scenario:
+            bold_match = re.match(bold_keyword_pattern, line, re.IGNORECASE)
+            if bold_match:
+                keyword = cast(GherkinKeyword, bold_match.group(1).capitalize())
+                text = bold_match.group(2).strip()
+                current_steps.append(GherkinStep(keyword=keyword, text=text))
+        # Check for inline format: **AC1**: Given X, When Y, Then Z (even without current scenario)
+        elif ":" in line and any(kw.lower() in line.lower() for kw in GHERKIN_KEYWORDS):
+            inline_scenario = _parse_inline_ac(line)
+            if inline_scenario:
+                scenarios.append(inline_scenario)
+
+    # Save last scenario
+    if current_scenario:
+        current_scenario.steps = current_steps
+        scenarios.append(current_scenario)
+
+    return scenarios
+
+
+def validate_gherkin_syntax(text: str) -> tuple[bool, Optional[str]]:
+    """Validate Gherkin syntax.
+
+    Args:
+        text: Gherkin text to validate
+
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    scenarios = parse_gherkin_text(text)
+
+    if not scenarios:
+        return False, "No scenarios found"
+
+    for scenario in scenarios:
+        if not scenario.steps:
+            return False, f"Scenario '{scenario.scenario}' has no steps"
+
+        # Check for at least one Given/When/Then
+        has_given = any(step.keyword == "Given" for step in scenario.steps)
+        has_when = any(step.keyword == "When" for step in scenario.steps)
+
+        if not (has_given or has_when):
+            return (
+                False,
+                f"Scenario '{scenario.scenario}' must have at least one Given or When step",
+            )
+
+    return True, None
+
+
+def _is_gherkin_step(line: str) -> bool:
+    """Check if line starts with a Gherkin keyword."""
+    line_lower = line.lower().strip()
+    return any(line_lower.startswith(kw.lower()) for kw in GHERKIN_KEYWORDS)
+
+
+def _parse_step(line: str) -> Optional[GherkinStep]:
+    """Parse a single Gherkin step line."""
+    line = line.strip()
+
+    # Find keyword
+    keyword = None
+    for kw in GHERKIN_KEYWORDS:
+        if line.lower().startswith(kw.lower()):
+            keyword = kw
+            break
+
+    if not keyword:
+        return None
+
+    # Extract text (remove keyword)
+    text = line[len(keyword) :].strip()
+    return GherkinStep(keyword=keyword, text=text)
+
+
+def _parse_inline_ac(line: str) -> Optional[GherkinScenario]:
+    """Parse inline AC format: **AC1**: Given X, When Y, Then Z."""
+    # Pattern: **AC-1** or **AC1**: Given X, When Y, Then Z
+    pattern = r"\*\*(AC[- ]?\d+)\*\*:\s*(.+)$"
+    match = re.match(pattern, line, re.IGNORECASE)
+
+    if not match:
+        return None
+
+    ac_id = match.group(1)
+    steps_text = match.group(2)
+
+    # Parse steps from comma-separated or newline-separated format
+    steps = []
+    # Try splitting by comma first
+    if "," in steps_text:
+        parts = [p.strip() for p in steps_text.split(",")]
+    else:
+        parts = [steps_text.strip()]
+
+    for part in parts:
+        step = _parse_step(part)
+        if step:
+            steps.append(step)
+
+    if steps:
+        return GherkinScenario(scenario=f"{ac_id}", steps=steps)
+
+    return None

ref_agents/tools/guard_tools.py

@@ -0,0 +1,139 @@
+from pathlib import Path
+import structlog
+from ref_agents.constants import Status, PHASE_CONFIG, AVAILABLE_AGENTS
+from ref_agents.workflow.state_machine import WorkflowManager
+from ref_agents.tools.context_tools import find_project_root
+
+logger = structlog.get_logger(__name__)
+
+# Pre-compute agent requirements from PHASE_CONFIG for performance
+_AGENT_REQUIREMENTS: dict[str, list[str]] = {}
+for phase in PHASE_CONFIG.values():
+    _AGENT_REQUIREMENTS[phase["primary_agent"]] = phase["required_artifacts"]
+    # Handle parallel/background agents if needed, though usually they share phase reqs
+    if "parallel_agent" in phase:
+        _AGENT_REQUIREMENTS[phase["parallel_agent"]] = phase["required_artifacts"]
+
+
+def _check_codemap_exists() -> bool:
+    """Check if CODE_MAP.md exists using priority-based detection.
+
+    Detection priority (industry best practice):
+    1. Session project_root (explicit user setting via set_project_root)
+    2. CWD (current working directory - primary for test isolation)
+    3. CWD parent traversal (find project root)
+    4. Secondary endpoint: docs/CODE_MAP.md in root locations
+
+    Returns:
+        True if CODE_MAP.md found in any checked location.
+    """
+    from ref_agents.session import SessionManager
+
+    # Priority 1: Explicit session project_root (highest priority)
+    # Verify path still exists (handles stale session state)
+    session_root = SessionManager.get().project_root
+    if session_root and session_root.exists():
+        if (session_root / "CODE_MAP.md").exists():
+            logger.debug("codemap_found", source="session_root", path=str(session_root))
+            return True
+        # Secondary endpoint: docs/CODE_MAP.md
+        if (session_root / "docs" / "CODE_MAP.md").exists():
+            logger.debug(
+                "codemap_found",
+                source="session_root_docs",
+                path=str(session_root / "docs" / "CODE_MAP.md"),
+            )
+            return True
+
+    # Priority 2: CWD (important for test isolation)
+    cwd = Path.cwd()
+    if (cwd / "CODE_MAP.md").exists():
+        logger.debug("codemap_found", source="cwd", path=str(cwd))
+        return True
+    # Secondary endpoint: docs/CODE_MAP.md in CWD
+    if (cwd / "docs" / "CODE_MAP.md").exists():
+        logger.debug(
+            "codemap_found", source="cwd_docs", path=str(cwd / "docs" / "CODE_MAP.md")
+        )
+        return True
+
+    # Priority 3: CWD parent traversal (find project root)
+    for parent in cwd.parents:
+        if (parent / "CODE_MAP.md").exists():
+            logger.debug("codemap_found", source="cwd_parent", path=str(parent))
+            return True
+        # Secondary endpoint: docs/CODE_MAP.md in parent
+        if (parent / "docs" / "CODE_MAP.md").exists():
+            logger.debug(
+                "codemap_found",
+                source="cwd_parent_docs",
+                path=str(parent / "docs" / "CODE_MAP.md"),
+            )
+            return True
+
+    logger.debug(
+        "codemap_not_found", checked_session=str(session_root), checked_cwd=str(cwd)
+    )
+    return False
+
+
+def _check_artifact_exists(artifact: str) -> bool:
+    """Check if an artifact exists using found root."""
+    if artifact == "CODE_MAP.md":
+        return _check_codemap_exists()
+
+    root = find_project_root()
+    if not root:
+        root = Path.cwd()
+
+    if artifact == "requirements":
+        req_dir = root / "docs/requirements"
+        return req_dir.exists() and any(req_dir.glob("*.md"))
+
+    # Handle wildcards correctly
+    if artifact == "requirements/*.md":
+        req_dir = root / "docs/requirements"
+        return req_dir.exists() and any(req_dir.glob("*.md"))
+
+    if artifact in ("design", "implementation", "ac_validated", "review_passed"):
+        manager = WorkflowManager()
+        active = manager.get_active_story()
+        if active:
+            state = manager.get_state(active)
+            if state:
+                return state.artifacts.get(artifact, False)
+        return False
+
+    # Handle regular file paths (e.g., docs/ARCHITECTURE.md)
+    artifact_path = root / artifact
+    return artifact_path.exists()
+
+
+def _check_agent_artifacts(agent_name: str) -> tuple[bool, list[str]]:
+    """Check required artifacts for agent."""
+    required = _AGENT_REQUIREMENTS.get(agent_name, [])
+    missing = [art for art in required if not _check_artifact_exists(art)]
+    return len(missing) == 0, missing
+
+
+def check_agent_prerequisites_impl(agent_name: str) -> str:
+    """Implementation of check_agent_prerequisites tool."""
+    if agent_name not in AVAILABLE_AGENTS:
+        return f"{Status.ERROR} Invalid agent: {agent_name}"
+
+    all_exist, missing = _check_agent_artifacts(agent_name)
+
+    if all_exist:
+        return f"{Status.SUCCESS} All prerequisites met for `{agent_name}`."
+
+    lines = [
+        f"{Status.ERROR} Prerequisites not met for `{agent_name}`",
+        "",
+        "Missing artifacts:",
+    ]
+    for art in missing:
+        lines.append(f"  - {art}")
+
+    lines.append("")
+    lines.append("Complete these before activating the agent.")
+    return "\n".join(lines)

ref_agents/tools/handoff_tools.py

@@ -0,0 +1,282 @@
+"""Handoff Tools for REF Agents.
+
+Consolidated logging for workflow events: escalation, ownership, replan, debt, phase.
+"""
+
+import uuid
+
+from ref_agents.constants import Status
+from ref_agents.session import SessionManager
+from ref_agents.utils import handoff_logger
+
+# Valid event types
+EVENT_TYPES = ("escalation", "ownership", "replan", "debt", "phase")
+
+
+def _log_escalation_event(  # noqa: PLR0913  # TECH_DEBT: refactor to TypedDict — STORY-046
+    level: str,
+    reason: str,
+    to_agents: str,
+    from_agent: str,
+    active_agent: str,
+    story_id: str | None,
+) -> str:
+    """Handle escalation event."""
+    agents_list = [a.strip() for a in to_agents.split(",") if a.strip()]
+    src_agent = from_agent if from_agent else active_agent
+    success = handoff_logger.log_escalation(
+        level=level,
+        from_agent=src_agent,
+        to_agents=agents_list,
+        reason=reason,
+        story_id=story_id,
+    )
+    if success:
+        return (
+            f"{Status.SUCCESS} Escalation logged\n"
+            f"Level: {level}\n"
+            f"From: {src_agent} → To: {', '.join(agents_list)}\n"
+            f"Reason: {reason}"
+        )
+    return f"{Status.ERROR} Failed to log escalation"
+
+
+def _log_ownership_event(
+    story_id: str,
+    active_agent: str,
+    to_owner: str,
+    reason: str,
+) -> str:
+    """Handle ownership transfer event."""
+    success = handoff_logger.log_ownership_transfer(
+        story_id=story_id,
+        from_owner=active_agent,
+        to_owner=to_owner,
+        reason=reason,
+    )
+    if success:
+        return (
+            f"{Status.SUCCESS} Ownership transfer logged\n"
+            f"Story: {story_id}\n"
+            f"From: {active_agent} → To: {to_owner}\n"
+            f"Reason: {reason}"
+        )
+    return f"{Status.ERROR} Failed to log ownership transfer"
+
+
+def _log_replan_event(story_id: str, trigger: str, impact: str) -> str:
+    """Handle replan event."""
+    success = handoff_logger.log_replan_triggered(
+        story_id=story_id,
+        trigger=trigger,
+        impact=impact,
+    )
+    if success:
+        return (
+            f"{Status.SUCCESS} Replan logged\n"
+            f"Story: {story_id}\n"
+            f"Trigger: {trigger}\n"
+            f"Impact: {impact}"
+        )
+    return f"{Status.ERROR} Failed to log replan"
+
+
+def _log_debt_event(
+    debt_type: str, severity: str, location: str, story_id: str | None
+) -> str:
+    """Handle debt event."""
+    debt_id = f"DEBT-{str(uuid.uuid4())[:8]}"
+    success = handoff_logger.log_debt_found(
+        debt_id=debt_id,
+        location=location,
+        debt_type=debt_type,
+        severity=severity,
+        story_id=story_id,
+    )
+    if success:
+        return (
+            f"{Status.SUCCESS} Debt logged: {debt_id}\n"
+            f"Type: {debt_type} | Severity: {severity}\n"
+            f"Location: {location}"
+        )
+    return f"{Status.ERROR} Failed to log debt"
+
+
+def _log_phase_event(story_id: str, phase: str, outcome: str, next_phase: str) -> str:
+    """Handle phase event."""
+    next_p = next_phase if next_phase else None
+    success = handoff_logger.log_phase_complete(story_id, phase, outcome, next_p)
+    if success:
+        return (
+            f"{Status.SUCCESS} Phase completion logged\n"
+            f"Story: {story_id}\n"
+            f"Phase: {phase} → {outcome}\n"
+            f"Next: {next_phase or 'None'}"
+        )
+    return f"{Status.ERROR} Failed to log phase completion"
+
+
+def log_event(  # noqa: PLR0913  # TECH_DEBT: refactor to TypedDict — STORY-046
+    event_type: str,
+    story_id: str = "",
+    level: str = "",
+    reason: str = "",
+    to_agents: str = "",
+    from_agent: str = "",
+    to_owner: str = "",
+    trigger: str = "",
+    impact: str = "",
+    debt_type: str = "",
+    severity: str = "",
+    location: str = "",
+    phase: str = "",
+    outcome: str = "",
+    next_phase: str = "",
+) -> str:
+    """Log a workflow event.
+
+    Args:
+        event_type: One of: escalation, ownership, replan, debt, phase.
+        story_id: Story identifier.
+        level: Escalation level (L1, L2, L3) - for escalation events.
+        reason: Reason for event - for escalation, ownership events.
+        to_agents: Comma-separated target agents - for escalation events.
+        from_agent: Source agent - for escalation events.
+        to_owner: New owner - for ownership events.
+        trigger: Replan trigger - for replan events.
+        impact: Replan impact - for replan events.
+        debt_type: Debt type - for debt events.
+        severity: Debt severity - for debt events.
+        location: Debt location - for debt events.
+        phase: Phase name - for phase events.
+        outcome: Phase outcome - for phase events.
+        next_phase: Next phase - for phase events.
+
+    Returns:
+        Success/error message.
+    """
+    if event_type not in EVENT_TYPES:
+        return f"{Status.ERROR} Invalid event_type. Use: {', '.join(EVENT_TYPES)}"
+
+    active_agent = SessionManager.get().active_agent or "unknown"
+    story = story_id if story_id else None
+
+    if event_type == "escalation":
+        return _log_escalation_event(
+            level, reason, to_agents, from_agent, active_agent, story
+        )
+
+    if event_type == "ownership":
+        return _log_ownership_event(story_id, active_agent, to_owner, reason)
+
+    if event_type == "replan":
+        return _log_replan_event(story_id, trigger, impact)
+
+    if event_type == "debt":
+        return _log_debt_event(debt_type, severity, location, story)
+
+    if event_type == "phase":
+        return _log_phase_event(story_id, phase, outcome, next_phase)
+
+    return f"{Status.ERROR} Unknown event type: {event_type}"
+
+
+def log_phase_completion_impl(
+    story_id: str, phase: str, outcome: str, next_phase: str = ""
+) -> str:
+    """Log phase completion event (wrapper for MCP tool).
+
+    Args:
+        story_id: Story identifier.
+        phase: Phase that was completed.
+        outcome: Outcome (passed, failed).
+        next_phase: Next phase in flow.
+
+    Returns:
+        Success/error message.
+    """
+    return log_event(
+        event_type="phase",
+        story_id=story_id,
+        phase=phase,
+        outcome=outcome,
+        next_phase=next_phase,
+    )
+
+
+def log_phase_complete_impl(
+    story_id: str, phase: str, outcome: str, next_phase: str = ""
+) -> str:
+    """Log phase completion event (alias for compatibility).
+
+    Args:
+        story_id: Story identifier.
+        phase: Phase that was completed.
+        outcome: Outcome (passed, failed).
+        next_phase: Next phase in flow.
+
+    Returns:
+        Success/error message.
+    """
+    return log_phase_completion_impl(story_id, phase, outcome, next_phase)
+
+
+# Backward compatibility wrappers for server.py
+def log_escalation_impl(
+    level: str, reason: str, to_agents: str, story_id: str = ""
+) -> str:
+    """Log escalation event (wrapper)."""
+    return log_event(
+        event_type="escalation",
+        level=level,
+        reason=reason,
+        to_agents=to_agents,
+        story_id=story_id,
+    )
+
+
+def log_ownership_transfer_impl(story_id: str, to_owner: str, reason: str) -> str:
+    """Log ownership transfer event (wrapper)."""
+    return log_event(
+        event_type="ownership",
+        story_id=story_id,
+        to_owner=to_owner,
+        reason=reason,
+    )
+
+
+def log_replan_triggered_impl(story_id: str, trigger: str, impact: str) -> str:
+    """Log replan triggered event (wrapper)."""
+    return log_event(
+        event_type="replan",
+        story_id=story_id,
+        trigger=trigger,
+        impact=impact,
+    )
+
+
+def log_debt_found_impl(
+    debt_type: str, severity: str, location: str, story_id: str = ""
+) -> str:
+    """Log debt found event (wrapper)."""
+    return log_event(
+        event_type="debt",
+        debt_type=debt_type,
+        severity=severity,
+        location=location,
+        story_id=story_id,
+    )
+
+
+def log_escalation_event_impl(  # noqa: PLR0913  # TECH_DEBT: refactor to TypedDict — STORY-046
+    level: str, from_agent: str, to_agents: str, reason: str, story_id: str = ""
+) -> str:
+    """Log escalation event with explicit from_agent (wrapper)."""
+    return log_event(
+        event_type="escalation",
+        level=level,
+        from_agent=from_agent,
+        to_agents=to_agents,
+        reason=reason,
+        story_id=story_id,
+    )