feat(review): add reviewer routing hints and diff risk signals for Rascal PR handoff #163

Summary

Rascal can already create or update PRs and move runs into a review state, but the handoff to humans is still thin. It does not help prioritize risky diffs, suggest likely reviewers, or distinguish changes that deserve extra attention.

This issue adds a lightweight review-handoff layer that computes routing hints and risk signals when Rascal opens or updates a PR.

Outcome

When a run reaches PR handoff, Rascal can attach reviewer suggestions, risk metadata, and review-priority signals so the human review step is faster and better targeted.

Goals

• Improve the quality of the human handoff without turning Rascal into a noisy review bot.
• Surface high-risk changes explicitly.
• Suggest likely reviewers using repository-local signals.
• Keep everything explainable, inspectable, and GitHub-native.
• Preserve conservative defaults and avoid surprise reviewer spam.

Non-goals

• Building a full inbox product with calendars, timezones, or org graphs.
• Auto-approving or auto-merging PRs.
• Replacing CODEOWNERS or branch protection.
• Emitting large volumes of AI-generated inline review comments.

Scope

Implement V1 review-handoff support with the following behavior.

1. Review handoff artifact

• Persist explicit handoff metadata in the run directory, for example:
  • review-handoff.json
  • review-handoff.md
• Include at least:
  • suggested reviewers
  • risk score or risk level
  • reasons for the risk classification
  • changed path summary
  • notable signals such as tests changed or not changed

2. Reviewer suggestion heuristics

• Suggest reviewers from a small, deterministic set of signals such as:
  • CODEOWNERS matches when available
  • recent file-touch history within the repo
  • previous PR author/reviewer activity for the same area
• Keep the heuristics explainable and stable.
• If no high-confidence suggestion exists, record that explicitly instead of guessing.

3. Risk classification

• Compute a compact risk classification such as low, medium, high.
• V1 signals may include:
  • number of files changed
  • number of directories or packages touched
  • presence of config/deploy/runtime files
  • changes in security-sensitive or infra-sensitive paths
  • missing test deltas for production code changes
  • cross-cutting changes spanning multiple areas
• Keep the scoring heuristic simple and visible in the artifact.

4. GitHub presentation

• Add the handoff summary to the PR body or completion comment in a concise way.
• Optionally add conservative labels such as:
  • rascal:risk-high
  • rascal:needs-review
• Do not request reviewers automatically in V1 unless explicitly configured.
• Start with suggestions and metadata, not side effects.

5. CLI/API visibility

• Expose handoff metadata through API/JSON output and optionally a CLI view command.
• Operators should be able to inspect why Rascal considered a change risky.

6. Notification hygiene

• Ensure handoff metadata updates are idempotent when Rascal revises an existing PR.
• Avoid posting duplicate comments or churning labels on every follow-up run.

Suggested implementation approach

1. Add a small review-handoff package.

• Separate reviewer suggestion, risk scoring, artifact rendering, and GitHub presentation.
• Keep the scorer independent from backend-specific execution details.

2. Start with repo-local deterministic signals only.

• Prefer CODEOWNERS and git history over external services.
• If CODEOWNERS parsing is absent today, add a narrow parser sufficient for reviewer discovery.

3. Keep side effects opt-in.

• Suggest reviewers first.
• Automatic reviewer requests can be a follow-up once confidence and ergonomics are proven.

4. Make idempotency explicit.

• Reuse the existing notification-marker pattern or its successor.
• PR body sections or comments should be updateable rather than appended repeatedly.

5. Keep the risk model intentionally small.

• The point is prioritization, not perfect prediction.
• A transparent heuristic is preferable to an opaque score.

Acceptance criteria

• Rascal produces explicit review-handoff artifacts when a run reaches PR handoff.
• Reviewer suggestions use deterministic repo-local signals and include explanation.
• Rascal assigns a compact risk classification with visible reasons.
• GitHub presentation is concise and idempotent.
• The feature works for newly created PRs and existing PR updates.
• Tests cover CODEOWNERS/history suggestion paths, risk scoring, presentation idempotency, and no-suggestion fallback.

Suggested test plan

• Unit tests for CODEOWNERS matching and reviewer suggestion ranking.
• Unit tests for risk classification heuristics.
• Integration tests for PR-body or comment updates without duplication.
• Regression tests for follow-up runs that revise the same PR and preserve stable handoff metadata.
• API/CLI tests for handoff artifact visibility.

Implementation notes

• This should make review easier, not louder.
• Keep reviewer suggestions advisory until the heuristics earn operator trust.
• High-signal handoff metadata is much more valuable here than broad automation.