omp-conductor 0.18.1 → 0.19.0

package/src/verbs/protocol.ts

@@ -286,6 +286,14 @@ export const VERB_SPECS: Readonly<Record<VerbName, VerbSpec>> = {
         required: false,
         description: "Tag to prepare or cut, for version-bump-pr, git-tag, and github-release.",
       },
+      sha: {
+        type: "string",
+        required: false,
+        description:
+          "Pin the tag to this exact commit instead of whatever the released repo's default branch " +
+          "is at cut time (#695), for git-tag and git-push-tags. The commit must be reachable from " +
+          "that branch, or the release is refused naming it. Omit it and the behaviour is unchanged.",
+      },
       artefact: {
         type: "string",
         required: false,
@@ -371,6 +379,47 @@ export const VERB_SPECS: Readonly<Record<VerbName, VerbSpec>> = {
     roleRefusalText: (role) =>
       `review authority is the orchestrator's; this is a ${role} session, and a worker never returns its own PR for revision.`,
   },
+  conductor_pr_review_clear: {
+    name: "conductor_pr_review_clear",
+    mutating: true,
+    allowedRoles: ["orchestrator"],
+    description:
+      "Record that the durable review findings standing at one exact head are settled, so " +
+      "`conductor_pr_merge` stops refusing that head with merge-blocked-by-review (#913). This is the " +
+      "only clearance reachable at an UNCHANGED head: a re-review at the same head opens or appends to " +
+      "another blocking round rather than superseding one, and nothing settles a round from outside a " +
+      "worker. The clearance applies strictly backwards — it suppresses the evidence recorded up to the " +
+      "moment it is taken, never a finding recorded afterwards — and to that one head only. It bypasses " +
+      "nothing else: authority, pause, base-red-freeze, exact-head, green checks, release composition and " +
+      "single-flight all still apply to the merge. Refused for a PR no run of this project owns, a head " +
+      "that is not the live head, and a head where nothing is blocking.",
+    args: {
+      prUrl: {
+        type: "string",
+        required: true,
+        description:
+          "Full pull request URL — one a run of this project recorded, in a routed repository.",
+      },
+      headSha: {
+        type: "string",
+        required: true,
+        description:
+          "The exact head being cleared. Must equal the live head; checks are not re-read here " +
+          "(the merge gate re-checks green itself).",
+      },
+      reason: {
+        type: "string",
+        required: true,
+        description:
+          "Why this evidence is settled, in your own words. Non-empty, recorded verbatim in the " +
+          "ledger and the digest — this is the audit trail for a merge that a review round refused.",
+      },
+      rationale: RATIONALE_ARG,
+    },
+    roleRefusalText: (role) =>
+      `clearing review findings is the orchestrator's disposition; this is a ${role} session, ` +
+      "and a worker never clears the findings standing against its own pull request.",
+  },
   conductor_pr_recover: {
     name: "conductor_pr_recover",
     mutating: true,
@@ -570,13 +619,32 @@ export function parseVerbRequest(raw: unknown): VerbParse {
     if (arg.oneOf !== undefined && !arg.oneOf.some((allowed) => allowed === value)) {
       // `reason` is the field #129 closed on purpose, so it gets its own
       // refusal code: an out-of-enum reason is vocabulary drift, not a typo.
+      const reasonDrift = key === "reason";
+      // Measured on this fleet 2026-08-23: this is the largest single refusal
+      // cause in the ledger — 99 of 241, across the four verbs whose `reason`
+      // is a closed set, still firing. Every one of the 99 carried a real
+      // explanation ("landed directly in PR #940; queue label would re-dispatch
+      // finished work"), which is exactly the audit content the ledger exists
+      // to hold, and 7578 characters of it were discarded. None of the 99
+      // supplied `rationale` — the field built for it — because the moment a
+      // caller has a sentence to record is the moment they are told only that
+      // `reason` is closed (#968).
+      //
+      // Keyed on the spec rather than a hardcoded verb list: a verb with an
+      // enum `reason` and no `rationale` must not be told to use a field it
+      // would then refuse as `unknown-argument`, turning one wasted round trip
+      // into two.
+      const carriesRationale = reasonDrift && spec.args["rationale"] !== undefined;
       return {
         ok: false,
         verb,
-        refusal: key === "reason" ? "reason-not-in-enum" : "malformed-argument",
+        refusal: reasonDrift ? "reason-not-in-enum" : "malformed-argument",
         detail:
           `refused: ${verb} argument "${key}" must be one of ${arg.oneOf.join(", ")}, ` +
-          `got ${JSON.stringify(value)}.`,
+          `got ${JSON.stringify(value)}.` +
+          (carriesRationale
+            ? ' Pick the enum value that fits and put that sentence in "rationale", which is logged verbatim.'
+            : ""),
       };
     }
   }