feat: add rule engine integration, risk labels, load balancing, and missing risk signals

CHANGELOG.md

@@ -8,6 +8,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- **AI-powered reviewer recommendation** -- `/reviewers` slash command suggests
+  the best reviewers for a PR based on CODEOWNERS ownership, commit history
+  expertise, Watchflow rule severity, and current review load. Supports
+  `--force` flag to bypass cooldown. Recommended reviewers are automatically
+  assigned to the PR via the GitHub API.
+- **PR risk assessment** -- `/risk` slash command posts a detailed risk
+  breakdown (size, sensitive paths, test coverage, contributor history, revert
+  detection, dependency changes, breaking changes, and matched Watchflow rule
+  severity). Applies `watchflow:risk-{level}` labels automatically.
+- **Contributor expertise profiles** -- reviewer expertise is persisted to
+  `.watchflow/expertise.json` across PRs and used to boost candidates with
+  cross-PR historical ownership.
+- **CODEOWNERS + rule integration** -- CODEOWNERS individual users and
+  `@org/team` entries are handled separately; team slugs are passed to
+  GitHub's `team_reviewers` API field to prevent 422 errors. When no
+  CODEOWNERS exists, high/critical Watchflow rule path matches infer implicit
+  ownership from commit history.
+- **Load balancing** -- reviewers with heavy recent review queues are
+  penalised; reviewer count scales with risk level (low→1, medium→2,
+  high/critical→3). Stale CODEOWNERS owners (no recent commits) receive a
+  reduced score.
+
 - **Description-diff alignment** -- `DescriptionDiffAlignmentCondition` uses
   the configured AI provider (OpenAI / Bedrock / Vertex AI) to verify that
   the PR description semantically matches the actual code changes. First

docs/getting-started/quick-start.md

@@ -87,10 +87,46 @@ Parameter names must match the [supported conditions](configuration.md); see [Co
 |--------|--------|
 | `@watchflow acknowledge "reason"` / `@watchflow ack "reason"` | Record an acknowledgment for a violation (when the rule allows it). |
 | `@watchflow evaluate "rule in plain English"` | Ask whether a rule is feasible and get suggested YAML. |
+| `/risk` | Run a risk analysis on the PR and post a signal summary (file churn, ownership gaps, rule violations). |
+| `/reviewers` | Get AI-powered reviewer recommendations based on code ownership, commit history, and risk signals. |
 | `@watchflow help` | List commands. |
 
 ---
 
+## Try it: risk analysis and reviewer recommendations
+
+Once Watchflow is installed and `.watchflow/rules.yaml` is in place, open a pull request and post a comment:
+
+```
+/risk
+```
+
+Watchflow will reply with a breakdown of risk signals — for example:
+
+> **Risk signals detected (2)**
+> - `src/auth/jwt.py` modified — no matching test file updated (medium)
+> - PR exceeds 500 lines changed (medium)
+>
+> **Active rules evaluated:** 7 · **Violations:** 2
+
+Then ask for reviewer suggestions:
+
+```
+/reviewers
+```
+
+Watchflow analyses commit history, CODEOWNERS, and the risk signals, then replies with ranked recommendations:
+
+> **Recommended reviewers**
+> 1. `@alice` — recent commits to `src/auth/jwt.py`, CODEOWNERS owner of `src/auth/`
+> 2. `@bob` — top contributor to `src/auth/` over the last 90 days
+>
+> *Tip: add a reviewer with `gh pr edit --add-reviewer alice`.*
+
+You can see a working example of both commands against a real repo at [test-watchflow](https://github.com/warestack/test-watchflow).
+
+---
+
 ## Next steps
 
 - **Tune rules** — [Configuration](configuration.md) for parameter reference and examples.

src/agents/factory.py

@@ -14,6 +14,7 @@
 from src.agents.extractor_agent import RuleExtractorAgent
 from src.agents.feasibility_agent import RuleFeasibilityAgent
 from src.agents.repository_analysis_agent import RepositoryAnalysisAgent
+from src.agents.reviewer_recommendation_agent import ReviewerRecommendationAgent
 
 logger = logging.getLogger(__name__)
 
@@ -51,6 +52,10 @@ def get_agent(agent_type: str, **kwargs: Any) -> BaseAgent:
         return AcknowledgmentAgent(**kwargs)
     elif agent_type == "repository_analysis":
         return RepositoryAnalysisAgent(**kwargs)
+    elif agent_type == "reviewer_recommendation":
+        return ReviewerRecommendationAgent()
     else:
-        supported = ", ".join(["engine", "feasibility", "extractor", "acknowledgment", "repository_analysis"])
+        supported = ", ".join(
+            ["engine", "feasibility", "extractor", "acknowledgment", "repository_analysis", "reviewer_recommendation"]
+        )
         raise ValueError(f"Unsupported agent type: {agent_type}. Supported: {supported}")

src/agents/reviewer_recommendation_agent/__init__.py

@@ -0,0 +1,3 @@
+from src.agents.reviewer_recommendation_agent.agent import ReviewerRecommendationAgent
+
+__all__ = ["ReviewerRecommendationAgent"]

src/agents/reviewer_recommendation_agent/agent.py

@@ -0,0 +1,96 @@
+# File: src/agents/reviewer_recommendation_agent/agent.py
+
+from typing import Any
+
+import structlog
+from langgraph.graph import END, StateGraph
+
+from src.agents.base import AgentResult, BaseAgent
+from src.agents.reviewer_recommendation_agent import nodes
+from src.agents.reviewer_recommendation_agent.models import RecommendationState
+
+logger = structlog.get_logger()
+
+
+class ReviewerRecommendationAgent(BaseAgent):
+    """
+    Agent that recommends reviewers for a PR based on:
+    1. CODEOWNERS ownership of changed files
+    2. Commit history expertise (who recently touched the same files)
+    3. Deterministic risk assessment (file count, sensitive paths, contributor status)
+    4. LLM-powered ranking with natural-language reasoning
+
+    Outputs both a risk breakdown and ranked reviewer suggestions.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(agent_name="reviewer_recommendation")
+
+    def _build_graph(self) -> Any:
+        workflow: StateGraph[RecommendationState] = StateGraph(RecommendationState)
+
+        llm = self.llm
+
+        async def _recommend_reviewers(state: RecommendationState) -> RecommendationState:
+            return await nodes.recommend_reviewers(state, llm)
+
+        workflow.add_node("fetch_pr_data", nodes.fetch_pr_data)
+        workflow.add_node("assess_risk", nodes.assess_risk)
+        workflow.add_node("recommend_reviewers", _recommend_reviewers)
+
+        workflow.set_entry_point("fetch_pr_data")
+        workflow.add_edge("fetch_pr_data", "assess_risk")
+        workflow.add_edge("assess_risk", "recommend_reviewers")
+        workflow.add_edge("recommend_reviewers", END)
+
+        return workflow.compile()
+
+    async def execute(self, **kwargs: Any) -> AgentResult:
+        """
+        Args:
+            repo_full_name: str  — owner/repo
+            pr_number: int       — PR number
+            installation_id: int — GitHub App installation ID
+        """
+        repo_full_name: str | None = kwargs.get("repo_full_name")
+        pr_number: int | None = kwargs.get("pr_number")
+        installation_id: int | None = kwargs.get("installation_id")
+
+        if not repo_full_name or not pr_number or not installation_id:
+            return AgentResult(success=False, message="repo_full_name, pr_number, and installation_id are required")
+
+        initial_state = RecommendationState(
+            repo_full_name=repo_full_name,
+            pr_number=pr_number,
+            installation_id=installation_id,
+        )
+
+        try:
+            result = await self._execute_with_timeout(self.graph.ainvoke(initial_state), timeout=45.0)
+            final_state = RecommendationState(**result) if isinstance(result, dict) else result
+
+            if final_state.error:
+                return AgentResult(success=False, message=final_state.error)
+
+            return AgentResult(
+                success=True,
+                message="Recommendation complete",
+                data={
+                    "risk_level": final_state.risk_level,
+                    "risk_score": final_state.risk_score,
+                    "risk_signals": [s.model_dump() for s in final_state.risk_signals],
+                    "candidates": [c.model_dump() for c in final_state.candidates],
+                    "llm_ranking": final_state.llm_ranking.model_dump() if final_state.llm_ranking else None,
+                    "pr_files_count": len(final_state.pr_files),
+                    "pr_author": final_state.pr_author,
+                    "codeowners_team_slugs": final_state.codeowners_team_slugs,
+                    "pr_base_branch": final_state.pr_base_branch,
+                },
+            )
+
+        except TimeoutError:
+            logger.error("agent_execution_timeout", agent="reviewer_recommendation", repo=repo_full_name)
+            return AgentResult(success=False, message="Recommendation timed out after 45 seconds")
+        except Exception as e:
+            logger.exception("agent_execution_failed", agent="reviewer_recommendation", error=str(e))
+            return AgentResult(success=False, message=str(e))

src/agents/reviewer_recommendation_agent/models.py

@@ -0,0 +1,85 @@
+# File: src/agents/reviewer_recommendation_agent/models.py
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ReviewerCandidate(BaseModel):
+    """A candidate reviewer with a score and reasons for recommendation."""
+
+    username: str
+    score: int = 0
+    ownership_pct: int = 0  # % of changed files they own or recently touched
+    reasons: list[str] = Field(default_factory=list)
+
+
+class RiskSignal(BaseModel):
+    """A single contributing factor to the PR risk score."""
+
+    label: str
+    description: str
+    points: int
+
+
+class RankedReviewer(BaseModel):
+    """A single reviewer entry in the LLM ranking output."""
+
+    username: str = Field(description="GitHub username of the reviewer")
+    reason: str = Field(description="Short explanation of why this reviewer is recommended")
+
+
+class LLMReviewerRanking(BaseModel):
+    """Structured output from the LLM reviewer ranking step."""
+
+    ranked_reviewers: list[RankedReviewer] = Field(description="Ordered list of reviewers, best match first")
+    summary: str = Field(description="One-line overall recommendation summary")
+
+
+class RecommendationState(BaseModel):
+    """Shared state (blackboard) for the ReviewerRecommendationAgent graph."""
+
+    # --- Inputs ---
+    repo_full_name: str
+    pr_number: int
+    installation_id: int
+
+    # --- Collected Data ---
+    pr_files: list[str] = Field(default_factory=list)
+    pr_author: str = ""
+    pr_additions: int = 0
+    pr_deletions: int = 0
+    pr_commits_count: int = 0
+    pr_author_association: str = "NONE"
+    codeowners_content: str | None = None
+    contributors: list[dict[str, Any]] = Field(default_factory=list)
+    # file_path -> list of recent committer logins
+    file_experts: dict[str, list[str]] = Field(default_factory=dict)
+    # Matched Watchflow rules (description, severity) loaded from .watchflow/rules.yaml
+    matched_rules: list[dict[str, str]] = Field(default_factory=list)
+    # Recent review activity: login -> count of reviews on recent PRs (for load balancing)
+    reviewer_load: dict[str, int] = Field(default_factory=dict)
+    # Reviewer acceptance rates: login -> approval rate (0.0–1.0) from recent PRs
+    reviewer_acceptance_rates: dict[str, float] = Field(default_factory=dict)
+    # PR title (for revert detection)
+    pr_title: str = ""
+
+    # --- Risk Assessment ---
+    risk_score: int = 0
+    risk_level: str = "low"  # low / medium / high / critical
+    risk_signals: list[RiskSignal] = Field(default_factory=list)
+
+    # --- Recommendations ---
+    candidates: list[ReviewerCandidate] = Field(default_factory=list)
+    llm_ranking: LLMReviewerRanking | None = None
+
+    # PR base branch (used when writing .watchflow/expertise.json)
+    pr_base_branch: str = "main"
+    # Team slugs extracted from CODEOWNERS (@org/team entries) — used to split
+    # reviewer assignment into `reviewers` vs `team_reviewers` GitHub API fields
+    codeowners_team_slugs: list[str] = Field(default_factory=list)
+    # Persisted expertise profiles loaded from .watchflow/expertise.json
+    expertise_profiles: dict[str, Any] = Field(default_factory=dict)
+
+    # --- Execution Metadata ---
+    error: str | None = None