review try-out: open a PR with the classifications on the page

The try-out page gets an "open a PR" button. It posts the page's
classifications to the new POST /api/review-classifier/open-pr, which
merges them by name into the repo's rules file on the default branch
and has the review-classifier forge account commit the result on a new
branch, review-classifier/<user>-<8 hex>, through the contents API. The
commit's author is the forge account named like the session's
Remote-User, read with the controller's admin token. The answer links
to the forge's compare page, where the user opens the PR as themselves.

The push uses the account's existing token from the store
(swarm/services/review-classifier/forge/token, scope write:repository),
so the account needs write access to the repo; a refused push answers
403 naming that. In a YAML rules file, the entries the merge leaves
alone keep their text, as long as the result reads back as the merged
list; otherwise the file is written out whole.

DefaultBranchFiles now carries each file's blob sha, which the forge
needs to replace a file, and the repo's web URL for the link.

Fixes #5259
Refs #5096

docs/swarm/review-classifier.md

@@ -241,8 +241,8 @@ its one token, `swarm-review-classifier` with scope `write:repository`, into
 the store at `swarm/services/review-classifier/forge/token`. A pass at start
 and every five minutes re-mints when the token is missing or no longer
 matches the forge. The controller refuses an existing account by that name
-with any other email. The controller posts the reviews with that token, and
-the classifier service never sees it.
+with any other email. The controller posts the reviews and pushes the try-out
+branches with that token, and the classifier service never sees it.
 
 **Giving a repo access is a repo admin's step, by hand.** Nothing grants
 it automatically. In the repo's settings, add `review-classifier` as a
@@ -254,7 +254,10 @@ collaborator:
   its request-changes blocks the merge where the branch protection blocks on
   rejected reviews. Where the branch protection restricts approvals to an
   allowlist, the account counts only once it's on that list, and read access
-  is then enough.
+  is then enough for reviews.
+
+The try-out page's **open a PR** pushes a branch to the repo itself, so it
+needs **write** whatever the branch protection says.
 
 The repo also needs a rules file on its default branch (see
 [Repo configuration](#repo-configuration)). Without one, a request posts a
@@ -464,10 +467,46 @@ since a run also works on a merged or closed PR. Two routes feed them:
 
 Every error is problem+json with the reason in `detail`.
 
-When it's ready, **open a PR** has the service account push a branch that
-adds the classification to the repo's config, with you, the swarm UI user,
-as commit author. The page then links you to the forge's new-PR page for
-that branch, where you log in as usual and open the PR yourself.
+When it's ready, **open a PR** (`POST /api/review-classifier/open-pr`, with
+the repo and the classifications) has the service account push a branch that
+adds the classifications to the repo's rules, with you, the swarm UI user, as
+commit author. The page then links you to the forge's compare page for that
+branch, where you log in as usual and open the PR yourself.
+
+- **The branch** is `review-classifier/<you>-<8 hex digits>`, made from the
+  default branch's head with one commit, through the forge's contents API.
+- **The file** is the rules file on the default branch, merged by name: a
+  classification named like an entry replaces it, a new name goes at the end,
+  and every other entry stays. A repo with no rules file gets
+  `.hyperhive/review-classifier.yml`. In a YAML file, the entries the merge
+  leaves alone keep their text, comments included. The merged file has to
+  pass the same checks the `rules` route makes.
+- **The author** is the forge account named like your swarm UI login. A forge
+  account made by an SSO login carries the SSO username, so it's yours once
+  you've logged in to the forge. The commit carries its full name, or the
+  login when it has none, and its email. The committer is the service
+  account.
+- **The token** is the service account's own, read from the store for each
+  push (see [The service account](#the-service-account)), so the account
+  needs **write** access to the repo.
+
+The route answers **201** with `branch`, `path` (the file written) and
+`compare_url`, or:
+
+- **400** for a body the try-out POST would refuse in its repo or
+  classifications
+- **401** without the `Remote-User` header the gateway sets
+- **403** when the forge refuses the push: the service account isn't a
+  collaborator with write access
+- **404** for a repo the forge doesn't know, or one with no commit on its
+  default branch
+- **409** when the forge has no account named like you yet, or the rules
+  file changed on the default branch during the push
+- **422** for a default branch holding both rules files or one the `rules`
+  route refuses; classifications the file already holds unchanged; or a
+  merge that breaks a rule, such as more than ten classifications
+- **503** when this host has no forge token, the service account's token
+  isn't minted yet, or the forge failed or didn't answer within two minutes
 
 ## Run store and retention
 
@@ -575,7 +614,3 @@ These get settled, and filled in here, as the work reaches them:
   `secret/swarm/services/review-classifier/forge/token`.
 - **Reviewer handoff.** How a later reviewer, human or agent, learns the
   classifier passed a PR before it starts its own review.
-- **Try-out branch access.** The service account's access for pushing try-out
-  branches, beyond what a repo admin gives it for reviews.
-- **Commit author for try-out PRs.** How the classifier derives the commit
-  author's name and email from the swarm UI login.