Add LLM-assisted reviewer router (Kubernetes-only v1)

[ChrisJBurns]

Summary

Today's .github/CODEOWNERS assigns reviewers purely by path glob, which makes every listed owner a required, blocking, notified reviewer. That conflates two different jobs — gatekeeping ("must approve") and awareness ("want to know") — and the result is notification fatigue: owners get pinged on churn within paths they own but no longer actively work, while static lists quietly go stale.

This PR introduces an advisory, context-aware reviewer router that rides on top of the existing CODEOWNERS gate (which is left untouched and still governs merges). Instead of a coarse glob, an LLM reads a natural-language ownership doc and requests reviewers based on what actually changed — e.g. it can require the controller owner on reconcile-logic changes but skip the full operator list for a pure CRD-doc regeneration.

Scope is intentionally limited to Kubernetes changes for this first iteration so the mechanism can prove out before expanding.

• .github/REVIEWERS.md — natural-language ownership doc (Kubernetes-only for v1) with per-area conditions that let routing be more precise than a glob (skip doc-regen/chart-version-bump/generated-only changes; always include @ChrisJBurns on controller changes).
• .github/workflows/assign-reviewers.yml — a pull_request-triggered workflow that runs claude-code-action (same pattern as the existing issue-triage workflow) to request the appropriate reviewers.

Type of change

• New feature

Test plan

• Manual testing (describe below)

This is CI/automation config (no Go code). Verification so far: YAML structure and action/SHA pins match the existing issue-triage.yml and claude.yml workflows. End-to-end behavior (the action requesting reviewers on a real Kubernetes PR) needs to be observed once merged or tested on a throwaway PR, since the workflow only runs with repository secrets available.

Does this introduce a user-facing change?

No. This only affects the reviewer-assignment experience for contributors; it does not change ToolHive's runtime behavior.

Special notes for reviewers

Security model. The workflow uses pull_request (not pull_request_target, which this repo deliberately avoids), so fork/dependabot PRs receive no ANTHROPIC_API_KEY and the Claude step skips — those fall back to the deterministic CODEOWNERS gate. The token is scoped to pull-requests: write and allowed_tools is restricted to reading repo files plus the GitHub API. Routing is advisory: the worst a prompt-injected diff can do is request the wrong reviewer, which CODEOWNERS still gates against.

Known follow-ups (intentionally out of scope here):

• allowed_tools is currently mcp__github__*; it should be narrowed to just the reviewer-request tool. Left broad for the v1 trial.
• Routing covers Kubernetes only; other areas (CLI, vMCP, security, AI gateway, …) fall through to the existing CODEOWNERS default and will be added once this proves out.
• A future "slim gate" CODEOWNERS only becomes worthwhile once router coverage is broad enough to make the full file redundant.

Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 70.35%. Comparing base (729ebd1) to head (73f280b).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5637      +/-   ##
==========================================
- Coverage   70.42%   70.35%   -0.07%     
==========================================
  Files         651      651              
  Lines       66285    66285              
==========================================
- Hits        46678    46638      -40     
- Misses      16232    16286      +54     
+ Partials     3375     3361      -14     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

🤖 Reviewer router requested the following based on .github/REVIEWERS.md:

• @JAORMX — Controller reconcile-logic change in cmd/thv-operator/controllers/mcpgroup_controller.go matches the controller/reconcile-logic rule.

Advisory only — merge gating is governed by CODEOWNERS.

[aponcedeleonch]

Flagging this as request-changes mainly to open a discussion before approval, not as a hard block. The PR works as framed; I'd just like to talk through an alternative direction first.

The problem you're naming is real. CODEOWNERS makes every path owner a required, blocking, notified reviewer, and that conflates two jobs: gatekeeping ("must approve") and awareness ("want to know"). The fatigue and the silent staleness are both worth fixing, and I like the care you put into the brain/hands split and the security model.

My hesitation is with the mechanism, so let me pitch a simpler alternative that keeps your goals but leans on CODEOWNERS instead of paralleling it.

Where I'm hesitant

• REVIEWERS.md is still a hand-maintained owner list. In v1 it names two people across two rules, so the ownership isn't smarter than CODEOWNERS, it's the same hardcoded mapping in prose. The new capability is really conditional firing, not smarter ownership.
• Most of those conditions are path globs plus simple exclusions a deterministic script could do. The one case needing semantic judgment is "comment-only vs logic change," which feels thin for an LLM call, an API-key dependency, and nondeterminism on every PR.
• It rides alongside CODEOWNERS rather than replacing it, so today it's net-added complexity. The spam payoff only lands once CODEOWNERS is slimmed, which this defers.

The counter-proposal: keep CODEOWNERS, add one weekly job

CODEOWNERS stays the single source GitHub already enforces, carrying both personas. The only thing we add is a weekly job that recomputes the file and opens a bot-drafted PR for a human to approve. Nothing reshapes ownership without that review, same as today, you're just reviewing a draft instead of writing globs by hand.

People who want to follow an area opt in by name, never by path. The job handles the path expansion.

.github/CODEOWNERS:

# ---- area definitions: friendly name -> globs (job-maintained) ----
# Names are stable and human-chosen. The globs under each name are recomputed
# weekly, so subscribing by name never goes stale.
#@area operator-controllers: /cmd/thv-operator/controllers/** /pkg/operator/**
#@area auth-registry:        /pkg/registry/auth/**
#@area cli:                  /cmd/thv/**

# ---- subscriptions: opt in by area name, never by path ----
# Add yourself with a one-line PR. You never touch globs.
#@subscribe auth-registry:        @alejandro
#@subscribe operator-controllers: @JAORMX

# ===================== GENERATED BELOW, do not hand-edit =====================

# must-review owners (history-derived)
# BEGIN auto-owners
/cmd/thv-operator/controllers/   @ChrisJBurns
/pkg/operator/                   @ChrisJBurns
/pkg/registry/auth/              @johnford
# END auto-owners

# want-to-know subscribers (expanded from the @subscribe directives above)
# BEGIN auto-subscribers
/pkg/registry/auth/              @alejandro
/cmd/thv-operator/controllers/   @JAORMX
/pkg/operator/                   @JAORMX
# END auto-subscribers

GitHub ignores every #@... line, so the directives are just friendly input. The BEGIN/END blocks are the compiled output that actually takes effect.

What the weekly job does

All three steps land in one reviewed PR:

1. Recompute areas. Refresh the globs under each #@area name from the current directory structure, so new and moved code stays mapped. Names stay fixed, only the globs move, so existing subscriptions never break.
2. Recompute must-review owners. Read git history per area, filter against the active roster, and rewrite the auto-owners block with the dominant active author.
3. Re-expand subscribers. For each #@subscribe <area>: @handle, look up that area's refreshed globs and rewrite the auto-subscribers block.

The job only ever rewrites between the markers. Area definitions and subscription directives above them are yours, edited by normal PRs.

Opting in by area name

This is the part you wanted to keep easy. Say you want to follow the auth registry. You add one line, #@subscribe auth-registry: @alejandro, and open a PR. You never work out which paths that means. The job resolves the name to globs and writes the real /pkg/registry/auth/ @alejandro line for you. Because people subscribe to the name and not the paths, the weekly glob refresh can move files around underneath without orphaning anyone.

The one caveat: renaming an area is the thing that breaks subscriptions, since the name is the join key. The job should fail the PR (or warn loudly) if a #@subscribe points at an area name that no longer exists, rather than silently dropping it.

Why I'd lean this way

It's CODEOWNERS doing what it already does, plus one job, in one file. No parallel ownership doc, no per-PR LLM, no API key, no nondeterminism on the critical path. The staleness you called out gets fixed by the weekly recompute. The want-to-know case becomes a one-line, by-name opt-in. And both owners and subscribers still land through a reviewed PR, so a human is always between the heuristic and the merge gate.

To be fair, the history-derived owners are the part with the most edge cases, which is exactly why that half stays human-approved rather than auto-merged. Curious what you think.