review-classifier: skip draft prs, classify once when they leave draft

docs/swarm/notify-router.md

@@ -80,8 +80,8 @@ field holds (`assignees_added`, `todo_holders`, …) or to one named agent.
 
 The router ships the three flows above, each a source → match on `action` →
 todo, and `head-classifier`: source `pull_request` and `pull_request_sync` →
-match on `action` (`opened`, `reopened`, `synchronized`) → `request_reviewer`
-for `review-classifier` ([below](#requesting-a-review)). The code defines them
+match on `action` (`opened`, `reopened`, `synchronized`) and `draft` = `false`, or on
+`undrafted` → `request_reviewer` for `review-classifier` ([below](#requesting-a-review)). The code defines them
 (`swarm_wire::notify_flows::builtins`), so a build that changes one reaches
 every swarm. Each switches off on `/notifications`. A custom flow has the same type and
 the same evaluator, so it can do anything a built-in does.
@@ -152,7 +152,12 @@ harmless: a reviewer with a pending request is a no-op for the forge, and one
 who has reviewed gets `skipped`.
 
 `head-classifier` requests the review classifier's review when someone opens or
-reopens a PR and on every push to an open PR. The classifier then runs as it does
+reopens a PR and on every push to an open PR that isn't a draft. A draft is a
+PR the forge reports with `draft` true, which it does for a title starting
+`WIP:` or `[WIP]`. A title edit that drops that prefix (`undrafted` is true:
+the event is `edited`, the PR is no draft, and the old title in the payload
+started with the prefix) requests the review once, so a PR whose last push
+came as a draft gets a classification. The classifier then runs as it does
 for any requested review
 ([`review-classifier.md`](review-classifier.md#trigger-and-lifecycle)), through
 its own request queue, which replaces a waiting request for the same PR. A
@@ -194,7 +199,9 @@ document of a version it doesn't know.
 **Deploying in any order.** The controller, the router and the UI can be on
 different hosts. A router that predates `request_reviewer` reads a document
 holding such a node (a custom flow with one) as one it can't read and keeps the
-flows it had; it also has no `head-classifier`. A router that has it, with a
+flows it had; it also has no `head-classifier`. A router that has `head-classifier`
+but predates the `draft` and `undrafted` fields requests the review of a draft PR
+as before. A router that has `request_reviewer`, with a
 controller that predates it, gets no answer to the request and logs that. A controller that predates this leaves the key absent, and the
 router runs the built-ins as before. A router that predates this ignores the
 document, so the page and the API show a state the router isn't yet running.

docs/swarm/review-classifier.md

@@ -89,7 +89,13 @@ as a reviewer on a PR starts a run:
 Opening or pushing to a PR starts no run by itself. The notification router's
 `head-classifier` flow requests the account's review when someone opens or
 reopens a PR and on every push to an open PR, unless its review of the new head
-already stands ([`notify-router.md`](notify-router.md#requesting-a-review)).
+already stands ([`notify-router.md`](notify-router.md#requesting-a-review)). It
+requests nothing for a draft PR, one whose title starts with `WIP:` or `[WIP]`
+and which the forge reports as `draft`. The edit that takes a PR out of draft
+requests the review once, for the head the PR has then. A request that reaches
+the controller for a PR that's a draft when the run place frees up (queued,
+or made by hand) runs nothing, posts nothing and counts as `draft`; request
+the review again once the PR is ready.
 
 When a post can't reach the secret store or the forge, because the
 connection fails or a try gets no answer within two minutes, the controller