✨ feature: live-link review perspectives from a GitHub file (like definition_source) #17975

Use case

We run a hive on torch-spyre/spyre-inference and torch-spyre/torch-spyre. We want two things at once:

1. Our review perspectives (which ones run, and each one's focus text) kept in our repo, edited by maintainers through normal PRs, and live-reloaded by the hive.
2. The stock reviewer-queue.md, unforked, so we keep getting upstream changes to the protocol it teaches: hive-review relay usage, the per-perspective verdict-array schema, --record-verdict, the routing markers, and [hive-reviewed] skips.

Today definition_source and prompt_source can live-link agent fields and kick templates. But review.perspectives and review.perspective_prompts are hive config, editable only from the dashboard or the overlay. The workarounds we tried each break one of the two goals:

• Short perspective_prompts that point at checklist files in the repo ("apply .hive/review/x.md"). The checklist text can be worked on together, but adding or removing a perspective still needs a hive config edit, so the set itself can't be changed through PRs.
• Forking reviewer-queue.md and listing the perspectives in it. That shadows every upstream protocol fix. It doesn't work anyway, because the relay validates verdicts against the hive's configured set, not the prompt.

Proposed solution

Add a hive-level review.perspectives_source that mirrors DefinitionSourceConfig:

review:
  combined_perspectives: true          # stays operator-owned
  perspectives_source:
    owner: torch-spyre
    repo: spyre-inference
    path: .hive/review-perspectives.yaml
    ref: main                          # optional; default branch otherwise

# .hive/review-perspectives.yaml
kind: ReviewPerspectives
perspectives:
  - name: correctness                  # built-in; no focus = built-in text
  - name: security
  - name: intent-alignment
  - name: spyre-constraints            # custom
    focus: "Head size a multiple of 64; fp16 only; DP>1 and bf16 with TP>1 rejected."
  - name: spyre-numerics
    focus: "Silent CPU fallbacks (FallbackWarning) and fp16 accumulation-order changes."

Suggested behaviour, reusing what defsrc already does:

• Same trust gate. Allowed only for repos on GitHubPromptAllowed, the allowlist that can only be set in the base config.
• Same resolve points and fallbacks. Fetched at startup and on every config reload. If the fetch is denied, there's no client, it errors, or the file is malformed: use the last-known-good document, then inline review.perspectives. A document that fails NewPerspectiveSet validation should keep the last good set and raise a visible warning, rather than quietly falling back to the five built-ins.
• Same apply path as a dashboard edit. The GitHub client caches the perspective set at boot (installReviewRelaySettings, the ReviewConfigApplied hook). A newly resolved set has to go through that path, or the relay keeps validating verdicts against the old set.
• Safe changes to the set. Linking makes changes to the set routine rather than rare, so the handling from review: changing review.perspectives strands mid-review PRs: heads wait forever on removed perspectives #14905 (heads waiting on removed perspectives) needs to cover this path too, and probably needs a test.
• Dashboard. Review Gate → Perspectives shows the linked source and is read-only while linked, the same way linked agents are shown.
• Scope. The file covers names and focus text only. combined_perspectives, plan_match and max_perspectives_per_pr are cost and dispatch settings that should stay with the operator, but we're open to other views.

${REVIEW_PERSPECTIVES} and every other consumer would read the resolved set, so reviewer-queue.md doesn't change.

Alternatives considered

1. A per-agent spec.reviewPerspectives on AgentDefinition, live-linked through definition_source. This was our first idea. But the set is read per PR: dispatch planning, head aggregation and merge-eligibility, and relay validation (client.SetPerspectives). With several reviewer agents or review heads, it becomes unclear whose set governs a PR.
2. A per-repo source. Read the reviewed repo's own .hive/review-perspectives.yaml from its default branch, keyed by repo. This is arguably the most natural fit, since perspectives describe the code being reviewed, and a hive covering several repos could use a different set per repo. It's a bigger change because every consumer would need a set keyed by repo. It must read the default branch, never the PR head, or a PR could edit the rules it's reviewed against. It could be a later extension that uses the same file format.
3. Pointer prompts plus in-repo checklists. Workable for focus text, but adding or removing a perspective still needs a hive config edit (see Use case).
4. Forking reviewer-queue.md. Loses upstream protocol changes, and the relay's validation makes it ineffective anyway.

Scope and compatibility

• Target branch or version: v5. We run 5.217.x on the stable channel. Landing in v6 first is fine.
• Operator impact: opt-in. If perspectives_source isn't set, behaviour is unchanged.
• Contributor/agent impact: none. Templates are unchanged and ${REVIEW_PERSPECTIVES} renders from the resolved set.
• Migration or backwards-compatibility concerns: none. One question for maintainers: when both inline perspectives and perspectives_source are set, we suggest the source wins and inline acts as the fallback. Rejecting the combination would also be reasonable.

Additional context

• review: changing review.perspectives strands mid-review PRs: heads wait forever on removed perspectives #14905: transition hazard when review.perspectives changes.
• docs/agent-configuration.md → "Live-linked agent definitions (definition_source)": the trust gate and fallback model this mirrors.
• docs/review-swarm.md: the perspectives and combined mode.
• Consumers of the hive-wide set in v5: cmd/hive/main_sweeps.go (reviewPerspectiveSet, installReviewRelaySettings, dispatch and aggregation wiring), pkg/scheduler/policy_overlays.go (${REVIEW_PERSPECTIVES}), pkg/github/review_request_watcher.go (relay validation and confidence line), pkg/review/review_heads_*.go.