✨ feat(reviewer-lane): ship the adjudication contract as a template (#5617 item 2)

[Danathar]

Summary

Item 2 of #5617 — the embedded kick template — which is the last of the four deferred follow-ups still outstanding, and the one @clubanderson's dispatch on the issue asked for. The reviewer lane's adjudication contract moves from a compiled-in string into pkg/policies/defaults/reviewer-lane.md.

The lane reaches its prompt by role, not by kick_template: an operator enables it by adding a cadence agent with role: reviewer — any name, no kick_template — so the ordinary resolution order never reached it and the contract was changeable only by rebuilding the binary. It now resolves through the same paths as every other template, so an operator-saved copy or a policies-checkout copy wins over the embedded default.

This is an extraction, and that is asserted rather than claimed

TestReviewerLaneTemplate_ByteIdenticalToBuilder renders the template and the builder it came from and compares them byte for byte, at both close-authority levels, reporting the first differing line on failure.

That test is the load-bearing one. Every line of this contract is a rule an agent follows against a human queue, so "the template looks right" is not a standard worth shipping — and the pre-existing TestBuildReviewerMessage_ContractAtL5 can only check the ~25 strings somebody thought to list. Those existing tests now exercise the template path too, since that is what buildReviewerMessage returns, which is the parity coverage step 3 of the dispatch asked for.

Three decisions deliberately stay in Go

The template is editable — that is the point of shipping one. These are not wording, so an override must not be able to reach them:

Decision	Where	Why
Is the lane awake?	Go, before any template is read	Below ACMM L5 the kick is a stand-down. An override must not wake a lane on a low-trust hive.
Is there work?	Go, before any template is read	An empty escalated queue is a stand-down. An override must not manufacture a contract with nothing to adjudicate.
May this agent close a PR?	Go, rendered into ${REVIEWER_CLOSE_AUTHORITY}	Closing is operator-only below ACMM L6. Whether an agent may close a human-queued PR is a trust decision.

So the worst an override can do is change the wording of a kick that was already going to be sent. All three are pinned by tests that install a rogue operator template — one that unconditionally issues a contract and offers gh pr close — and prove it cannot wake the lane, invent work, or grant close authority.

Two smaller decisions worth flagging

The work list is passed into the substitution, not recomputed inside it. buildReviewerMessage has already gated on that exact list; re-reading ci-failing.json during rendering would reopen a window where a rewrite between the two reads renders a full adjudication contract over an empty list. That needed a substituteTemplateWithVars variant taking caller-supplied ${VAR}s — in which the built-ins win a name clash, so no call site can redefine ${GH_AUTH}. A test pins that.

The compiled-in contract is kept as the resolution fallback. Step 4 of the dispatch says to remove it "only after template coverage is green"; I have kept it, because a stripped binary or an override that reads as empty must not leave the reviewer with no contract, which is worse than the previous wording. The parity test is what makes keeping both safe — they cannot drift without failing it. Removing it is a follow-up, not this PR.

Cluster claimed (files/functions)

• src/pkg/policies/defaults/reviewer-lane.md (new) — the extracted contract.
• src/pkg/scheduler/reviewer_lane.go — reviewerLaneTemplate, reviewerKickHeader, renderReviewerLaneTemplate, reviewerCloseAuthority, and buildReviewerMessageHardcoded (the former body, unchanged text, now the fallback).
• src/pkg/scheduler/scheduler.go — substituteTemplateWithVars; substituteTemplateWithPolicy delegates to it with nil, so every existing caller is untouched.
• src/pkg/scheduler/reviewer_lane_template_test.go (new, 6 tests), src/docs/agent-configuration.md, CHANGELOG.md.

No behaviour change: this is the "pure template extraction plus parity tests" scope the dispatch specified.

Validation

• go build ./..., go vet ./pkg/scheduler/ ./pkg/policies/, gofmt -l clean on every file I touched. (gofmt flags three other pkg/scheduler test files — pre-existing drift, untouched here.)

• go test ./pkg/scheduler/ ./pkg/policies/ — both packages pass in full, including every pre-existing reviewer-lane contract test.

• src/scripts/check-docs-links.py: all links and anchors resolve.

• Mutation-checked, and both mutations are caught by the new tests and by the pre-existing ones:

  Mutation	Caught by
  Drop one INVARIANT clause from the template	_ByteIdenticalToBuilder and TestBuildReviewerMessage_ContractAtL5
  Resolve the template before the ACMM gate	_GatesAreNotTemplated and TestBuildReviewerMessage_ACMMGateDormantBelowL5 and _EmptyQueueStandsDown

Related issues

Refs #5617 (item 2 of 4 — items 1, 3 and 4 landed in #5634 and #5682). Related: #5480 (the reviewer lane), #5511 (the one-pass ladder the contract encodes).

Testing

• cd src && go build ./...
• cd src && go test ./... — ran ./pkg/scheduler/ and ./pkg/policies/ in full (the only packages touched); both pass.

— hive: backend=claude model=claude-opus-5

[kubestellar-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign danathar for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[clubanderson]

Reviewed the diff against the requested base in a detached worktree. Validation: cd src && go build ./... plus targeted package tests for changed Go packages (and relay tests where applicable) passed locally. I found no blocking issues.

[clubanderson]

/lgtm

[kubestellar-prow]

LGTM label has been added.

Details

Git tree hash: c3a1021896f6447689c13676160878951b75f258

[kubestellar-prow]

LGTM label has been added.

Details

Git tree hash: c3a1021896f6447689c13676160878951b75f258