ref-agents 1.0.0__py3-none-any.whl

ref_agents/workflow/transitions.py

@@ -0,0 +1,658 @@
+"""Phase Transition Rules for REF Workflow.
+
+Validates phase transitions based on artifact requirements
+and determines next suggested agents.
+"""
+
+import json
+import time
+from pathlib import Path
+
+import structlog
+
+from ref_agents.constants import (
+    AGENT_NEXT_SUGGESTION,
+    PHASE_CONFIG,
+)
+from ref_agents.workflow.state_machine import WorkflowManager, WorkflowState
+
+logger = structlog.get_logger(__name__)
+
+# Health report older than this is treated as stale — forces re-scan.
+_HEALTH_REPORT_MAX_AGE_SECONDS: int = 7200  # 2 hours
+
+
+def _check_health_report_clean(project_root: Path) -> bool:
+    """Check health_report.json for zero Critical/High violations.
+
+    Reads the latest health report. Returns False if report missing,
+    stale (>2h old), or contains Critical/High findings. Accepts
+    health_scan_deferred as an explicit audited bypass.
+
+    Args:
+        project_root: Project root directory for report lookup.
+
+    Returns:
+        True only if report exists, is fresh, and Critical==0 and High==0.
+    """
+    try:
+        from ref_agents.tools.compliance_remediation import _find_health_report_json
+
+        report_path = _find_health_report_json(str(project_root))
+    except Exception:
+        logger.warning("health_report_lookup_failed", project_root=str(project_root))
+        return False
+
+    if report_path is None:
+        logger.info("health_report_missing", project_root=str(project_root))
+        return False
+
+    try:
+        age = time.time() - report_path.stat().st_mtime
+        if age > _HEALTH_REPORT_MAX_AGE_SECONDS:
+            logger.info(
+                "health_report_stale",
+                age_seconds=int(age),
+                max_age=_HEALTH_REPORT_MAX_AGE_SECONDS,
+            )
+            return False
+
+        with report_path.open("r", encoding="utf-8") as fh:
+            data = json.load(fh)
+
+        critical = int(data.get("critical", data.get("Critical", 0)) or 0)
+        high = int(data.get("high", data.get("High", 0)) or 0)
+
+        clean = critical == 0 and high == 0
+        logger.info(
+            "health_report_checked",
+            critical=critical,
+            high=high,
+            clean=clean,
+        )
+        return clean
+
+    except (OSError, json.JSONDecodeError, ValueError) as exc:
+        logger.warning("health_report_read_error", error=str(exc))
+        return False
+
+
+def _check_test_smell_clean(project_root: Path, state: WorkflowState) -> bool:
+    """Verify zero CRITICAL test_smell findings on changed files (STORY-TQ-001 M1b).
+
+    Gate behaviour:
+        - Read latest ``health_report.json``.
+        - Filter to ``scanner == "test_smell"`` and ``severity == "critical"``.
+        - Intersect with files changed in the current git working tree.
+        - Pass when intersection is empty.
+        - Honour ``state.artifacts["tests_smell_deferred"]`` as an audited bypass.
+
+    Args:
+        project_root: Project root for report + git lookup.
+        state: Active workflow state (carries deferral flag).
+
+    Returns:
+        True when the gate is clean OR a valid deferral is logged.
+    """
+    if state.artifacts.get("tests_smell_deferred", False):
+        logger.info(
+            "test_smell_gate_deferred",
+            story_id=state.story_id,
+        )
+        return True
+
+    try:
+        from ref_agents.tools.compliance_remediation import _find_health_report_json
+        from ref_agents.utils.git_utils import get_changed_files
+    except ImportError as exc:
+        logger.warning("test_smell_gate_import_failed", error=str(exc))
+        return False
+
+    report_path = _find_health_report_json(str(project_root))
+    if report_path is None:
+        logger.info("test_smell_gate_no_report", project_root=str(project_root))
+        return False
+
+    try:
+        age = time.time() - report_path.stat().st_mtime
+        if age > _HEALTH_REPORT_MAX_AGE_SECONDS:
+            logger.info("test_smell_gate_report_stale", age_seconds=int(age))
+            return False
+        with report_path.open("r", encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (OSError, json.JSONDecodeError, ValueError) as exc:
+        logger.warning("test_smell_gate_read_error", error=str(exc))
+        return False
+
+    findings = data.get("findings", []) if isinstance(data, dict) else []
+    critical_smells = [
+        f
+        for f in findings
+        if isinstance(f, dict)
+        and f.get("scanner") == "test_smell"
+        and str(f.get("severity", "")).lower() == "critical"
+    ]
+    if not critical_smells:
+        logger.info("test_smell_gate_clean", story_id=state.story_id)
+        return True
+
+    changed = {str(p) for p in get_changed_files(str(project_root))}
+    if not changed:
+        # Detached HEAD or no diff — fall back to scan-all (Design Changed-Files section).
+        offending = [f.get("file", "") for f in critical_smells]
+        logger.warning(
+            "test_smell_gate_scan_all_fallback",
+            story_id=state.story_id,
+            offending=offending[:5],
+        )
+        return False
+
+    # Match against both full and basename to absorb path-style mismatches.
+    changed_basenames = {Path(p).name for p in changed}
+    blocking = []
+    for f in critical_smells:
+        path_str = f.get("file", "")
+        if not isinstance(path_str, str) or not path_str:
+            continue
+        normalized = path_str
+        # Compare relative-to-project-root when path is absolute.
+        if path_str.startswith(str(project_root)):
+            normalized = path_str[len(str(project_root)) :].lstrip("/")
+        if normalized in changed or Path(path_str).name in changed_basenames:
+            blocking.append(f)
+
+    if blocking:
+        logger.info(
+            "test_smell_gate_blocked",
+            story_id=state.story_id,
+            blocking_count=len(blocking),
+        )
+        return False
+
+    logger.info("test_smell_gate_clean_after_diff", story_id=state.story_id)
+    return True
+
+
+def advisory_symbol_drift(
+    project_root: Path,
+    state: WorkflowState,
+) -> list[str]:
+    """Return advisory WARNING strings for missing grounded symbols (STORY-TQ-003).
+
+    Reads ``tests/plans/STORY-XXX.json`` for grounded ``symbol_under_test``
+    entries. Walks the AST of each changed file and checks whether each
+    declared symbol is defined (top-level ``def`` / ``class`` / class-method).
+    Emits a warning per missing symbol. **Never blocks the transition** —
+    advisory only in v1 per FR-13.
+
+    Args:
+        project_root: Project root for plan + git diff lookup.
+        state: Active workflow state (story_id drives plan lookup).
+
+    Returns:
+        List of warning strings. Empty when all grounded symbols are defined OR
+        when no grounded entries exist OR when no changed files are visible.
+    """
+    plan_path = project_root / "tests" / "plans" / f"{state.story_id}.json"
+    if not plan_path.exists():
+        return []
+
+    try:
+        plan = json.loads(plan_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return []
+
+    grounded = _grounded_symbols(plan)
+    if not grounded:
+        return []
+
+    changed_files = _resolve_changed_python_files(project_root)
+    if not changed_files:
+        return []
+
+    declared = _collect_declared_symbols(changed_files)
+    warnings: list[str] = []
+    for entry in grounded:
+        name = entry["name"]
+        bare = name.split(".", 1)[0]
+        if bare in declared:
+            continue
+        warnings.append(
+            f"⚠️ symbol_drift advisory: `{name}` (from `{entry.get('module_path', 'unknown')}`) "
+            f"not found in changed files. Test case {entry['test_case_id']}. "
+            f"Grounding: {entry.get('grounding', 'n/a')}"
+        )
+    return warnings
+
+
+def _grounded_symbols(plan: dict) -> list[dict]:
+    test_cases = plan.get("test_cases", []) if isinstance(plan, dict) else []
+    if not isinstance(test_cases, list):
+        return []
+    out: list[dict] = []
+    for tc in test_cases:
+        if not isinstance(tc, dict):
+            continue
+        sut = tc.get("symbol_under_test")
+        if not isinstance(sut, dict):
+            continue
+        if sut.get("source") not in ("code_map", "story_public_interface"):
+            continue
+        name = sut.get("name")
+        if not isinstance(name, str) or not name.strip():
+            continue
+        out.append(
+            {
+                "test_case_id": str(tc.get("id", "UNKNOWN")),
+                "name": name,
+                "module_path": sut.get("module_path"),
+                "grounding": sut.get("grounding"),
+            }
+        )
+    return out
+
+
+def _resolve_changed_python_files(project_root: Path) -> list[Path]:
+    try:
+        from ref_agents.utils.git_utils import get_changed_files
+    except ImportError:
+        return []
+    paths = get_changed_files(str(project_root))
+    out: list[Path] = []
+    for rel in paths:
+        full = project_root / rel
+        if full.suffix == ".py" and full.exists():
+            out.append(full)
+    return out
+
+
+def _collect_declared_symbols(paths: list[Path]) -> set[str]:
+    import ast as _ast
+
+    declared: set[str] = set()
+    for path in paths:
+        try:
+            tree = _ast.parse(path.read_text(encoding="utf-8"))
+        except (OSError, SyntaxError):
+            continue
+        for node in _ast.walk(tree):
+            if isinstance(
+                node, (_ast.FunctionDef, _ast.AsyncFunctionDef, _ast.ClassDef)
+            ):
+                declared.add(node.name)
+    return declared
+
+
+def _check_full_suite_clean(project_root: Path, state: WorkflowState) -> bool:
+    """Verify the full-suite gate (STORY-TQ-002).
+
+    Honours:
+        - ``full_suite_deferred`` artifact: audited bypass (writes debt entry
+          elsewhere; gate returns True).
+        - ``greenfield_no_tests`` artifact: accepted only when the report status
+          is ``no_runners``.
+
+    Args:
+        project_root: Project root for report lookup.
+        state: Active workflow state.
+
+    Returns:
+        True when the gate is clean OR a valid bypass is in place.
+    """
+    if state.artifacts.get("full_suite_deferred", False):
+        logger.info("full_suite_gate_deferred", story_id=state.story_id)
+        return True
+
+    try:
+        from ref_agents.tools.full_suite_runner import evaluate_gate
+    except ImportError as exc:
+        logger.warning("full_suite_gate_import_failed", error=str(exc))
+        return False
+
+    decision = evaluate_gate(project_root)
+    if decision.passed:
+        return True
+
+    # Greenfield projects can bypass `no_runners` specifically — never other failures.
+    if (
+        decision.reason == "status_not_passed"
+        and decision.detail.get("status") == "no_runners"
+        and state.artifacts.get("greenfield_no_tests", False)
+    ):
+        logger.info("full_suite_gate_greenfield_bypass", story_id=state.story_id)
+        return True
+
+    logger.info(
+        "full_suite_gate_blocked",
+        story_id=state.story_id,
+        reason=decision.reason,
+        detail=decision.detail,
+    )
+    return False
+
+
+class TransitionValidator:
+    """Validates and executes phase transitions.
+
+    Attributes:
+        manager: WorkflowManager instance.
+        project_root: Root directory for artifact detection.
+    """
+
+    def __init__(
+        self,
+        manager: WorkflowManager | None = None,
+        project_root: Path | None = None,
+    ) -> None:
+        """Initialize transition validator.
+
+        Args:
+            manager: WorkflowManager instance. Creates default if None.
+            project_root: Project root for artifact detection.
+        """
+        self.manager = manager or WorkflowManager()
+        self.project_root = project_root or Path(".")
+
+    def check_artifacts(self, state: WorkflowState, phase: str) -> dict[str, bool]:
+        """Check if required artifacts exist for a phase.
+
+        Args:
+            state: Current workflow state.
+            phase: Target phase ID.
+
+        Returns:
+            Dict of artifact name -> exists flag.
+        """
+        config = PHASE_CONFIG.get(phase, {})
+        required = config.get("required_artifacts", [])
+
+        results: dict[str, bool] = {}
+
+        for artifact in required:
+            if artifact in state.artifacts:
+                results[artifact] = state.artifacts[artifact]
+            elif artifact == "CODE_MAP.md":
+                results[artifact] = (self.project_root / "CODE_MAP.md").exists()
+            elif artifact.startswith("docs/specs/"):
+                # Substitute {story_id} placeholder before checking file existence
+                resolved = artifact.replace("{story_id}", state.story_id)
+                results[artifact] = (self.project_root / resolved).exists()
+            elif artifact.startswith("requirements/"):
+                req_dir = self.project_root / "docs" / "requirements"
+                results[artifact] = req_dir.exists() and any(req_dir.glob("*.md"))
+            elif artifact == "conceptual_tests":
+                # Check for tests/plans/STORY-XXX.json file
+                plan_file = (
+                    self.project_root / "tests" / "plans" / f"{state.story_id}.json"
+                )
+                results[artifact] = plan_file.exists() or state.artifacts.get(
+                    artifact, False
+                )
+            elif artifact == "health_scan_passed":
+                # Deferred bypass (audited escape hatch) takes precedence over disk check.
+                if state.artifacts.get("health_scan_deferred", False):
+                    results[artifact] = True
+                else:
+                    results[artifact] = _check_health_report_clean(self.project_root)
+            elif artifact == "tests_smell_passed":
+                # STORY-TQ-001 M1b — gate code present, not wired into required_artifacts yet.
+                # Ship-2 promotes by appending to REVIEW required_artifacts.
+                results[artifact] = _check_test_smell_clean(self.project_root, state)
+            elif artifact == "full_suite_passed":
+                # STORY-TQ-002 M2a: gate code present, NOT wired into
+                # required_artifacts yet. M2b promotes by editing constants.py.
+                results[artifact] = _check_full_suite_clean(self.project_root, state)
+            elif artifact in (
+                "ac_validated",
+                "design",
+                "implementation",
+                "codemap_updated",
+                "review_passed",
+            ):
+                results[artifact] = state.artifacts.get(artifact, False)
+            elif artifact in ("tests_passed", "security_passed"):
+                if state.parallel_status:
+                    tasks = state.parallel_status.get("tasks", {})
+                    if artifact == "tests_passed":
+                        results[artifact] = tasks.get("tester") == "passed"
+                    else:
+                        results[artifact] = tasks.get("security_owner") == "passed"
+                else:
+                    results[artifact] = state.artifacts.get(artifact, False)
+            else:
+                results[artifact] = state.artifacts.get(artifact, False)
+
+        return results
+
+    def can_transition(self, story_id: str, target_phase: str) -> tuple[bool, str]:
+        """Check if transition to target phase is valid.
+
+        Args:
+            story_id: Story identifier.
+            target_phase: Target phase ID.
+
+        Returns:
+            Tuple of (can_transition, reason).
+        """
+        state = self.manager.get_state(story_id)
+        if not state:
+            return False, f"No workflow state found for {story_id}"
+
+        if target_phase not in PHASE_CONFIG:
+            return False, f"Invalid phase: {target_phase}"
+
+        current_config = PHASE_CONFIG.get(state.current_phase, {})
+        if current_config.get("next_phase") != target_phase:
+            # Allow skipping back or jumping if artifacts exist
+            pass
+
+        # Check required artifacts
+        artifact_status = self.check_artifacts(state, target_phase)
+        missing = [name for name, exists in artifact_status.items() if not exists]
+
+        if missing:
+            return False, f"Missing artifacts: {', '.join(missing)}"
+
+        # Check for blockers
+        if state.blockers:
+            return False, f"Active blockers: {len(state.blockers)}"
+
+        return True, "All requirements met"
+
+    def transition(self, story_id: str, target_phase: str) -> WorkflowState:
+        """Execute transition to target phase.
+
+        Args:
+            story_id: Story identifier.
+            target_phase: Target phase ID.
+
+        Returns:
+            Updated WorkflowState.
+
+        Raises:
+            ValueError: If transition not valid.
+        """
+        can_trans, reason = self.can_transition(story_id, target_phase)
+        if not can_trans:
+            raise ValueError(f"Cannot transition: {reason}")
+
+        return self.manager.update_phase(story_id, target_phase)
+
+    def get_next_phase(self, story_id: str) -> str | None:
+        """Get the next phase for a story.
+
+        Args:
+            story_id: Story identifier.
+
+        Returns:
+            Next phase ID or None if at end.
+        """
+        state = self.manager.get_state(story_id)
+        if not state:
+            return None
+
+        config = PHASE_CONFIG.get(state.current_phase, {})
+        return config.get("next_phase")
+
+    def suggest_next_agent(
+        self,
+        story_id: str,
+        completed_task: str = "",
+    ) -> dict:
+        """Suggest next agent after task completion.
+
+        Args:
+            story_id: Story identifier.
+            completed_task: Description of completed task.
+
+        Returns:
+            Dict with suggestion details.
+        """
+        state = self.manager.get_state(story_id)
+        if not state:
+            return {
+                "error": f"No workflow state found for {story_id}",
+                "suggestion": None,
+            }
+
+        current_agent = state.active_agents[0] if state.active_agents else None
+        current_config = PHASE_CONFIG.get(state.current_phase, {})
+
+        # Check for background notifications
+        notifications = []
+        if state.parallel_status:
+            notifications = state.parallel_status.get("notifications", [])
+
+        next_suggestion = AGENT_NEXT_SUGGESTION.get(current_agent or "")
+
+        is_parallel = isinstance(next_suggestion, list)
+        parallel_agents = next_suggestion if is_parallel else None
+
+        background_agent = current_config.get("background_agent")
+        background_notification = None
+        if background_agent and notifications:
+            background_notification = notifications[-1] if notifications else None
+
+        # Gate: validate current phase artifacts before allowing next agent suggestion.
+        # Without this check, workflow skips phases when artifacts (e.g. codemap_updated,
+        # implementation) are never set by the agent.
+        next_phase = current_config.get("next_phase")
+        missing_artifacts: list[str] = []
+        if next_suggestion is not None and next_phase:
+            artifact_status = self.check_artifacts(state, next_phase)
+            missing_artifacts = [k for k, v in artifact_status.items() if not v]
+
+        if missing_artifacts:
+            return {
+                "story_id": story_id,
+                "current_phase": state.current_phase,
+                "current_agent": current_agent,
+                "completed_task": completed_task,
+                "next_agent": None,
+                "is_parallel": False,
+                "parallel_agents": None,
+                "background_notification": None,
+                "notifications": notifications,
+                "reason": f"Blocked — missing artifacts: {', '.join(missing_artifacts)}",
+                "blocked": True,
+                "missing_artifacts": missing_artifacts,
+            }
+
+        # Determine single next agent
+        if is_parallel:
+            next_agent = next_suggestion  # List of parallel agents
+        else:
+            next_agent = next_suggestion
+
+        advisory_warnings = advisory_symbol_drift(self.project_root, state)
+
+        return {
+            "story_id": story_id,
+            "current_phase": state.current_phase,
+            "current_agent": current_agent,
+            "completed_task": completed_task,
+            "next_agent": next_agent,
+            "is_parallel": is_parallel,
+            "parallel_agents": parallel_agents,
+            "background_notification": background_notification,
+            "notifications": notifications,
+            "reason": self._get_suggestion_reason(current_agent, next_agent),
+            "warnings": advisory_warnings,
+        }
+
+    def _get_suggestion_reason(
+        self,
+        current_agent: str | None,
+        next_agent: str | list | None,
+    ) -> str:
+        """Generate reason for agent suggestion.
+
+        Args:
+            current_agent: Current agent name.
+            next_agent: Suggested next agent(s).
+
+        Returns:
+            Human-readable reason.
+        """
+        if not next_agent:
+            return "Workflow complete"
+
+        if isinstance(next_agent, list):
+            agents_str = " + ".join(next_agent)
+            return f"Ready for parallel validation: {agents_str}"
+
+        reasons = {
+            "product_manager": "CODE_MAP ready → Define requirements",
+            "qa_lead": "Requirements ready → Validate AC",
+            "test_designer": "Requirements ready → Design conceptual tests",
+            "architect": "AC validated → Design system",
+            "developer": "QA Gate passed → Implement",
+            "pr_reviewer": "Implementation ready → Review code",
+            "tester": "Review passed → Write executable tests",
+            "security_owner": "Review passed → Security audit",
+            "scrum_master": "All validations passed → Close loop",
+        }
+
+        return reasons.get(next_agent, f"Proceed to {next_agent}")
+
+    def get_phase_status(self, story_id: str) -> dict:
+        """Get current phase status summary.
+
+        Args:
+            story_id: Story identifier.
+
+        Returns:
+            Dict with phase status details.
+        """
+        state = self.manager.get_state(story_id)
+        if not state:
+            return {"error": f"No workflow state found for {story_id}"}
+
+        current_config = PHASE_CONFIG.get(state.current_phase, {})
+        artifact_status = self.check_artifacts(state, state.current_phase)
+
+        # Check next phase readiness
+        next_phase = current_config.get("next_phase")
+        next_ready = False
+        next_missing = []
+
+        if next_phase:
+            next_artifact_status = self.check_artifacts(state, next_phase)
+            next_missing = [k for k, v in next_artifact_status.items() if not v]
+            next_ready = len(next_missing) == 0
+
+        return {
+            "story_id": story_id,
+            "story_type": state.story_type,
+            "current_phase": state.current_phase,
+            "phase_name": current_config.get("name", "Unknown"),
+            "active_agents": state.active_agents,
+            "completed_phases": state.completed_phases,
+            "artifacts": artifact_status,
+            "next_phase": next_phase,
+            "next_phase_ready": next_ready,
+            "next_missing_artifacts": next_missing,
+            "parallel_status": state.parallel_status,
+            "blockers": state.blockers,
+            "capabilities": state.capabilities,
+        }