ref-agents 1.0.0__py3-none-any.whl

ref_agents/utils/handoff_logger.py

@@ -0,0 +1,368 @@
+"""Handoff event logger for REF Agents.
+
+Logs ownership transfers, escalations, and other handoff events
+to handoff_log.jsonl for audit trail.
+"""
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Literal
+
+import structlog
+
+from ref_agents.utils.git_utils import get_current_user_id
+
+logger = structlog.get_logger(__name__)
+
+
+def _write_graph_node(
+    node_type: str,
+    content: str,
+    story_id: str | None,
+    metadata: dict[str, str],
+) -> None:
+    """Write a node to the context graph from a handoff event.
+
+    Args:
+        node_type: Valid ContextGraph NodeType string (issue, decision, agent_session…).
+        content: One-sentence description of the event.
+        story_id: Active story identifier (empty string if unknown).
+        metadata: Additional key/value metadata attached to the node.
+    """
+    try:
+        from datetime import datetime, timezone
+
+        from ref_agents.tools.context_graph import ContextNode, get_context_graph
+
+        graph = get_context_graph()
+        ts = datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S%f")
+        node = ContextNode(
+            id=f"{node_type}-hl-{ts}",
+            node_type=node_type,  # type: ignore[arg-type]
+            content=content,
+            story_id=story_id or "",
+            metadata=metadata,
+        )
+        graph.add_node(node)
+        graph.save()
+    except Exception as e:
+        logger.warning("handoff_graph_write_failed", error=str(e))
+
+
+EventType = Literal[
+    "ownership_transfer",
+    "agent_activation",
+    "escalation",
+    "escalation_resolved",
+    "replan_triggered",
+    "debt_logged",
+    "phase_complete",
+]
+
+
+def _get_log_path(project_root: Path | None = None) -> Path:
+    """Get path to handoff log file.
+
+    Args:
+        project_root: Project root directory. Defaults to session project_root
+                      if set, otherwise cwd.
+
+    Returns:
+        Path to handoff_log.jsonl.
+    """
+    if project_root is None:
+        from ref_agents.session import SessionManager
+
+        session = SessionManager.get()
+        project_root = session.project_root or Path.cwd()
+
+    return project_root / "ref-reports" / "handoff_log.jsonl"
+
+
+def log_event(
+    event_type: EventType,
+    project_root: Path | None = None,
+    **kwargs: str | list[str] | None,
+) -> bool:
+    """Log a handoff event to handoff_log.jsonl.
+
+    Args:
+        event_type: Type of event to log.
+        project_root: Project root directory.
+        **kwargs: Additional event-specific fields.
+
+    Returns:
+        True if logged successfully, False otherwise.
+    """
+    log_path = _get_log_path(project_root)
+
+    # Ensure directory exists
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+
+    user = get_current_user_id(project_root)
+
+    event = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "event": event_type,
+        "user": user,
+        **{k: v for k, v in kwargs.items() if v is not None},
+    }
+
+    try:
+        with log_path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(event) + "\n")
+        logger.info("event_logged", event_type=event_type, user=user)
+        return True
+    except OSError as e:
+        logger.error("event_log_failed", error=str(e))
+        return False
+
+
+def log_agent_activation(agent: str, project_root: Path | None = None) -> bool:
+    """Log agent activation event and create context graph node.
+
+    Args:
+        agent: Agent that was activated.
+        project_root: Project root directory.
+
+    Returns:
+        True if logged successfully.
+    """
+    # Log to handoff_log.jsonl (existing behavior)
+    result = log_event("agent_activation", project_root, agent=agent)
+
+    # Create agent_session node in context graph and link to active story.
+    try:
+        from ref_agents.tools.context_graph import ContextNode, get_context_graph
+        from ref_agents.workflow.state_machine import WorkflowManager
+
+        graph = get_context_graph(project_root)
+        ts = datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
+        node_id = f"agent_session-{ts}"
+
+        # Resolve active story for story_id tagging and edge creation.
+        active_story_id: str | None = None
+        try:
+            active_story_id = WorkflowManager().get_active_story()
+        except Exception:
+            pass
+
+        node = ContextNode(
+            id=node_id,
+            node_type="agent_session",
+            content=f"Agent session: {agent}",
+            story_id=active_story_id or "",
+            metadata={"agent": agent},
+        )
+        graph.add_node(node)
+
+        # Link to story node if one is active and exists in graph.
+        if active_story_id:
+            story_node_candidates = [
+                n
+                for n in graph._graph.nodes
+                if graph._graph.nodes[n].get("node_type") == "story"
+                and active_story_id in n
+            ]
+            for story_node_id in story_node_candidates:
+                try:
+                    graph.add_edge(node_id, story_node_id, "affects")
+                except ValueError:
+                    pass
+
+        graph.save()
+        logger.info(
+            "agent_session_node_created",
+            node_id=node_id,
+            agent=agent,
+            story_id=active_story_id,
+        )
+    except (OSError, ValueError, ImportError) as e:
+        # Non-blocking: log error but don't fail activation
+        logger.warning("context_graph_node_failed", agent=agent, error=str(e))
+
+    return result
+
+
+def log_ownership_transfer(  # noqa: PLR0913  # TECH_DEBT: refactor to TypedDict — STORY-046
+    story_id: str,
+    from_owner: str,
+    to_owner: str,
+    reason: str,
+    project_root: Path | None = None,
+) -> bool:
+    """Log ownership transfer event.
+
+    Args:
+        story_id: Story being transferred.
+        from_owner: Previous owner.
+        to_owner: New owner.
+        reason: Reason for transfer.
+        project_root: Project root directory.
+
+    Returns:
+        True if logged successfully.
+    """
+    result = log_event(
+        "ownership_transfer",
+        project_root,
+        story_id=story_id,
+        from_owner=from_owner,
+        to_owner=to_owner,
+        reason=reason,
+    )
+    _write_graph_node(
+        "agent_session",
+        f"Ownership: {from_owner} → {to_owner}",
+        story_id,
+        {},
+    )
+    return result
+
+
+def log_escalation(  # noqa: PLR0913  # TECH_DEBT: refactor to TypedDict — STORY-046
+    level: str,
+    from_agent: str,
+    to_agents: list[str],
+    reason: str,
+    story_id: str | None = None,
+    project_root: Path | None = None,
+) -> bool:
+    """Log escalation event.
+
+    Args:
+        level: Escalation level (L1, L2, L3).
+        from_agent: Agent that escalated.
+        to_agents: Agents escalated to.
+        reason: Reason for escalation.
+        story_id: Related story ID.
+        project_root: Project root directory.
+
+    Returns:
+        True if logged successfully.
+    """
+    result = log_event(
+        "escalation",
+        project_root,
+        level=level,
+        from_agent=from_agent,
+        to_agents=to_agents,
+        reason=reason,
+        story_id=story_id,
+    )
+    _write_graph_node(
+        "issue",
+        f"Escalation {level}: {reason[:100]}",
+        story_id,
+        {"level": level},
+    )
+    return result
+
+
+def log_debt_found(  # noqa: PLR0913  # TECH_DEBT: refactor to TypedDict — STORY-046
+    debt_id: str,
+    location: str,
+    debt_type: str,
+    severity: str,
+    story_id: str | None = None,
+    project_root: Path | None = None,
+) -> bool:
+    """Log technical debt discovery event.
+
+    Args:
+        debt_id: Debt registry ID.
+        location: File and line location.
+        debt_type: Type of debt.
+        severity: Debt severity.
+        story_id: Story during which debt was found.
+        project_root: Project root directory.
+
+    Returns:
+        True if logged successfully.
+    """
+    result = log_event(
+        "debt_logged",
+        project_root,
+        debt_id=debt_id,
+        location=location,
+        debt_type=debt_type,
+        severity=severity,
+        story_id=story_id,
+    )
+    _write_graph_node(
+        "issue",
+        f"Debt [{severity}] {debt_type} at {location}",
+        story_id,
+        {"debt_id": debt_id},
+    )
+    return result
+
+
+def log_phase_complete(  # noqa: PLR0913  # TECH_DEBT: refactor to TypedDict — STORY-046
+    story_id: str,
+    phase: str,
+    outcome: str,
+    next_phase: str | None = None,
+    project_root: Path | None = None,
+) -> bool:
+    """Log phase completion event.
+
+    Args:
+        story_id: Story that completed phase.
+        phase: Phase that was completed.
+        outcome: Outcome (passed, failed).
+        next_phase: Next phase in flow.
+        project_root: Project root directory.
+
+    Returns:
+        True if logged successfully.
+    """
+    result = log_event(
+        "phase_complete",
+        project_root,
+        story_id=story_id,
+        phase=phase,
+        outcome=outcome,
+        next_phase=next_phase,
+    )
+    _write_graph_node(
+        "decision",
+        f"[{outcome.upper()}] {phase} → {next_phase or 'end'}",
+        story_id,
+        {},
+    )
+    return result
+
+
+def log_replan_triggered(
+    story_id: str,
+    trigger: str,
+    impact: str,
+    project_root: Path | None = None,
+) -> bool:
+    """Log replan trigger event.
+
+    Args:
+        story_id: Story being replanned.
+        trigger: What triggered the replan (new req, blocker, etc).
+        impact: Expected impact (scope change, delay).
+        project_root: Project root directory.
+
+    Returns:
+        True if logged successfully.
+    """
+    result = log_event(
+        "replan_triggered",
+        project_root,
+        story_id=story_id,
+        trigger=trigger,
+        impact=impact,
+    )
+    _write_graph_node(
+        "issue",
+        f"Replan: {trigger[:100]}",
+        story_id,
+        {"impact": impact},
+    )
+    return result

ref_agents/utils/ignore_matcher.py

@@ -0,0 +1,270 @@
+"""Ignore pattern matcher for .gitignore and .dockerignore files.
+
+Parses ignore files and checks if paths match ignore patterns.
+Used to avoid flagging intentionally ignored files as dead code.
+"""
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+
+@dataclass
+class IgnorePattern:
+    """Represents a single ignore pattern.
+
+    Attributes:
+        pattern: Original pattern string.
+        regex: Compiled regex for matching.
+        negated: True if pattern starts with ! (negation).
+        directory_only: True if pattern ends with / (directory only).
+    """
+
+    pattern: str
+    regex: re.Pattern[str]
+    negated: bool = False
+    directory_only: bool = False
+
+
+@dataclass
+class IgnorePatternMatcher:
+    """Matches file paths against .gitignore/.dockerignore patterns.
+
+    Attributes:
+        patterns: List of parsed ignore patterns.
+        base_dir: Base directory for relative path resolution.
+    """
+
+    patterns: list[IgnorePattern] = field(default_factory=list)
+    base_dir: Path = field(default_factory=Path.cwd)
+
+    @classmethod
+    def from_file(
+        cls,
+        ignore_file: Path,
+        base_dir: Path | None = None,
+    ) -> "IgnorePatternMatcher":
+        """Create matcher from ignore file.
+
+        Args:
+            ignore_file: Path to .gitignore or .dockerignore file.
+            base_dir: Base directory for pattern matching.
+
+        Returns:
+            Configured IgnorePatternMatcher instance.
+        """
+        matcher = cls(base_dir=base_dir or ignore_file.parent)
+
+        if not ignore_file.exists():
+            return matcher
+
+        try:
+            content = ignore_file.read_text(encoding="utf-8")
+            for line in content.splitlines():
+                pattern = matcher._parse_line(line)
+                if pattern:
+                    matcher.patterns.append(pattern)
+        except OSError as e:
+            logger.warning(
+                "ignore_file_read_error", file=str(ignore_file), error=str(e)
+            )
+
+        return matcher
+
+    @classmethod
+    def from_directory(cls, directory: Path) -> "IgnorePatternMatcher":
+        """Create matcher from all ignore files in directory.
+
+        Loads .gitignore and .dockerignore if present.
+
+        Args:
+            directory: Directory to scan for ignore files.
+
+        Returns:
+            Combined IgnorePatternMatcher instance.
+        """
+        matcher = cls(base_dir=directory)
+
+        for ignore_name in [".gitignore", ".dockerignore"]:
+            ignore_file = directory / ignore_name
+            if ignore_file.exists():
+                file_matcher = cls.from_file(ignore_file, directory)
+                matcher.patterns.extend(file_matcher.patterns)
+                logger.debug(
+                    "loaded_ignore_file",
+                    file=ignore_name,
+                    patterns=len(file_matcher.patterns),
+                )
+
+        return matcher
+
+    def _parse_line(self, line: str) -> IgnorePattern | None:
+        """Parse a single ignore pattern line.
+
+        Args:
+            line: Line from ignore file.
+
+        Returns:
+            Parsed IgnorePattern or None if line is empty/comment.
+        """
+        # Strip whitespace
+        line = line.strip()
+
+        # Skip empty lines and comments
+        if not line or line.startswith("#"):
+            return None
+
+        negated = False
+        directory_only = False
+
+        # Check for negation
+        if line.startswith("!"):
+            negated = True
+            line = line[1:]
+
+        # Check for directory-only pattern
+        if line.endswith("/"):
+            directory_only = True
+            line = line[:-1]
+
+        # Convert gitignore pattern to regex
+        regex = self._pattern_to_regex(line)
+
+        return IgnorePattern(
+            pattern=line,
+            regex=regex,
+            negated=negated,
+            directory_only=directory_only,
+        )
+
+    def _pattern_to_regex(self, pattern: str) -> re.Pattern[str]:
+        """Convert gitignore pattern to compiled regex.
+
+        Args:
+            pattern: Gitignore-style pattern.
+
+        Returns:
+            Compiled regex pattern.
+        """
+        # Handle leading slash (anchor to root)
+        anchored = pattern.startswith("/")
+        if anchored:
+            pattern = pattern[1:]
+
+        # Escape special regex characters except * and ?
+        escaped = ""
+        i = 0
+        while i < len(pattern):
+            char = pattern[i]
+            if char == "*":
+                if i + 1 < len(pattern) and pattern[i + 1] == "*":
+                    # ** matches any path including /
+                    escaped += ".*"
+                    i += 2
+                    # Skip following /
+                    if i < len(pattern) and pattern[i] == "/":
+                        i += 1
+                    continue
+                else:
+                    # * matches anything except /
+                    escaped += "[^/]*"
+            elif char == "?":
+                escaped += "[^/]"
+            elif char in ".^$+{}[]|()":
+                escaped += "\\" + char
+            else:
+                escaped += char
+            i += 1
+
+        # Build final regex
+        if anchored:
+            regex_str = f"^{escaped}"
+        else:
+            # Match anywhere in path
+            regex_str = f"(^|/){escaped}"
+
+        # Match end of string or path separator
+        regex_str += "(/|$)"
+
+        try:
+            return re.compile(regex_str)
+        except re.error as e:
+            logger.warning("invalid_ignore_pattern", pattern=pattern, error=str(e))
+            # Return pattern that matches nothing
+            return re.compile(r"^\b$")
+
+    def is_ignored(self, path: Path | str, is_dir: bool = False) -> bool:
+        """Check if path matches any ignore pattern.
+
+        Args:
+            path: File or directory path (relative to base_dir).
+            is_dir: True if path is a directory.
+
+        Returns:
+            True if path should be ignored.
+        """
+        if isinstance(path, str):
+            path = Path(path)
+
+        # Make path relative to base_dir
+        try:
+            rel_path = path.relative_to(self.base_dir)
+        except ValueError:
+            rel_path = path
+
+        # Convert to forward slashes for matching
+        path_str = str(rel_path).replace("\\", "/")
+
+        ignored = False
+
+        for pattern in self.patterns:
+            # For directory-only patterns, check if any parent matches
+            if pattern.directory_only:
+                if is_dir:
+                    if pattern.regex.search(path_str):
+                        ignored = not pattern.negated
+                else:
+                    # Check if file is under a matching directory (not the file itself)
+                    # Only check parent directories, not the file's own name
+                    if len(rel_path.parts) > 1:
+                        for part_idx in range(len(rel_path.parts) - 1):
+                            parent_path = "/".join(rel_path.parts[: part_idx + 1])
+                            if pattern.regex.search(parent_path):
+                                ignored = not pattern.negated
+                                break
+            elif pattern.regex.search(path_str):
+                # Regular pattern
+                ignored = not pattern.negated
+
+        return ignored
+
+    def filter_paths(self, paths: list[Path]) -> list[Path]:
+        """Filter list of paths, removing ignored ones.
+
+        Args:
+            paths: List of paths to filter.
+
+        Returns:
+            Paths that are NOT ignored.
+        """
+        return [p for p in paths if not self.is_ignored(p, is_dir=p.is_dir())]
+
+
+def is_intentionally_ignored(file_path: Path, project_root: Path) -> bool:
+    """Check if file is in .gitignore or .dockerignore.
+
+    Convenience function for dead code detection.
+
+    Args:
+        file_path: Path to check.
+        project_root: Project root directory.
+
+    Returns:
+        True if file is intentionally ignored.
+    """
+    matcher = IgnorePatternMatcher.from_directory(project_root)
+    return matcher.is_ignored(file_path)

ref_agents/workflow/__init__.py

@@ -0,0 +1,19 @@
+"""Workflow State Machine for REF Agents.
+
+This package provides SDLC workflow tracking:
+- State persistence per story
+- Phase transitions with artifact validation
+- Parallel task coordination
+- Capability detection for tools
+"""
+
+from ref_agents.workflow.capabilities import CapabilityDetector
+from ref_agents.workflow.state_machine import WorkflowManager, WorkflowState
+from ref_agents.workflow.transitions import TransitionValidator
+
+__all__ = [
+    "CapabilityDetector",
+    "TransitionValidator",
+    "WorkflowManager",
+    "WorkflowState",
+]