@brainervirus/workit-core 8.1.0 → 8.3.0

package/src/forge/gitlab.ts

@@ -11,6 +11,7 @@ import {
   type ForgePrStatus,
   type ForgeResult,
   type ForgeThread,
+  type PrMeta,
   type PrState,
 } from "./types";
 
@@ -22,6 +23,8 @@ type GlUser = { username?: string; bot?: boolean } | null;
 
 type GlMr = {
   iid: number;
+  title?: string;
+  reviewers?: Array<{ id: number }>;
   web_url: string;
   state: string;
   draft?: boolean;
@@ -169,6 +172,20 @@ const safeUrl = (value: string | null): string | null => (value ? redactText(val
 const isBot = (author: GlUser): boolean =>
   author?.bot === true || /(?:^project_\d+_bot|bot$|\[bot\]$)/iu.test(author?.username ?? "");
 
+/** GitLab's draft markers at the start of an MR title. */
+const DRAFT_PREFIX = /^(?:\s*(?:\[draft\]|\(draft\)|draft:)\s*)+/iu;
+
+/**
+ * `title` with GitLab's draft markers (`Draft:`, `[Draft]`, `(Draft)`,
+ * repeated) replaced by one `Draft: ` or removed (GitLab keeps draft in the
+ * title). Null when nothing but markers is left.
+ */
+const draftTitle = (title: string, draft: boolean): string | null => {
+  const bare = title.replace(DRAFT_PREFIX, "").trim();
+  if (!bare) return null;
+  return draft ? `Draft: ${bare}` : bare;
+};
+
 // Statuses where GitLab has not finished computing mergeability.
 const UNSETTLED = new Set(["checking", "unchecked", "preparing", "approvals_syncing"]);
 
@@ -233,6 +250,26 @@ export function createGitLabForge(options: {
     return tip.ok && typeof tip.data.commit?.id === "string" ? tip.data.commit.id : null;
   };
 
+  const getMr = (iid: number): ForgeResult<GlMr> =>
+    apiJson<GlMr>(
+      runner,
+      "glab",
+      apiHost,
+      api(`${project}/merge_requests/${iid}`),
+      `merge request !${iid}`,
+    );
+
+  const putMr = (iid: number, fields: string[], what: string): ForgeResult<void> => {
+    const updated = apiWrite<unknown>(
+      runner,
+      "glab",
+      apiHost,
+      ["api", "-X", "PUT", `${project}/merge_requests/${iid}`, ...fields],
+      `${what} of merge request !${iid}`,
+    );
+    return updated.ok ? success(undefined) : updated;
+  };
+
   return {
     kind: "gitlab",
     apiHost,
@@ -552,5 +589,135 @@ export function createGitLabForge(options: {
       );
       return updated.ok ? success(undefined) : updated;
     },
+
+    prMeta(iid) {
+      const mr = getMr(iid);
+      if (!mr.ok) return mr;
+      const value = mr.data;
+      const meta: PrMeta = {
+        number: value.iid,
+        url: value.web_url,
+        state: mrState(value.state),
+        draft: value.draft ?? value.work_in_progress ?? false,
+        title: value.title ?? "",
+        base: value.target_branch,
+        headBranch: value.source_branch,
+      };
+      return success(meta);
+    },
+
+    setDraft(iid, draft) {
+      const mr = getMr(iid);
+      if (!mr.ok) return mr;
+      const title = draftTitle(mr.data.title ?? "", draft);
+      if (title === null)
+        return failure(
+          "invalid_input",
+          `merge request !${iid} has no title besides its draft marker`,
+        );
+      return putMr(iid, ["-f", `title=${title}`], `draft state`);
+    },
+
+    editPr(iid, edit) {
+      const mr = getMr(iid);
+      if (!mr.ok) return mr;
+      const fields: string[] = [];
+      // A new title keeps the MR's draft state (it lives in the title).
+      if (edit.title !== undefined) {
+        const title = draftTitle(edit.title, mr.data.draft ?? mr.data.work_in_progress ?? false);
+        if (title === null)
+          return failure("invalid_input", "--title must have text besides a draft marker");
+        fields.push("-f", `title=${title}`);
+      }
+      if (edit.body !== undefined) fields.push("-f", `description=${edit.body}`);
+      if (edit.base !== undefined) fields.push("-f", `target_branch=${edit.base}`);
+      if (edit.addLabels.length) fields.push("-f", `add_labels=${edit.addLabels.join(",")}`);
+      if (edit.removeLabels.length)
+        fields.push("-f", `remove_labels=${edit.removeLabels.join(",")}`);
+      if (edit.addReviewers.length) {
+        // reviewer_ids replaces the list: keep the current reviewers.
+        const ids = new Set((mr.data.reviewers ?? []).map((reviewer) => reviewer.id));
+        for (const username of edit.addReviewers) {
+          const users = apiJson<Array<{ id?: number; username?: string }>>(
+            runner,
+            "glab",
+            apiHost,
+            api(`users?username=${encodeURIComponent(username)}`),
+            `user ${username}`,
+          );
+          if (!users.ok) return users;
+          const user = Array.isArray(users.data)
+            ? users.data.find((entry) => entry.username?.toLowerCase() === username.toLowerCase())
+            : undefined;
+          if (typeof user?.id !== "number")
+            return failure("not_found", `GitLab user ${username} was not found`);
+          ids.add(user.id);
+        }
+        // One JSON array: glab rejects `reviewer_ids[]=` keys in a JSON body.
+        fields.push("-F", `reviewer_ids=${JSON.stringify([...ids])}`);
+      }
+      return fields.length ? putMr(iid, fields, "edit") : success(undefined);
+    },
+
+    replyThread(iid, thread, body) {
+      const note = apiWrite<{ id?: number }>(
+        runner,
+        "glab",
+        apiHost,
+        [
+          "api",
+          "-X",
+          "POST",
+          `${project}/merge_requests/${iid}/discussions/${encodeURIComponent(thread)}/notes`,
+          "-f",
+          `body=${body}`,
+        ],
+        `reply on merge request !${iid}`,
+      );
+      if (!note.ok) return note;
+      return success({ url: null });
+    },
+
+    resolveThread(iid, thread) {
+      const resolved = apiWrite<{ notes?: GlNote[] }>(
+        runner,
+        "glab",
+        apiHost,
+        [
+          "api",
+          "-X",
+          "PUT",
+          `${project}/merge_requests/${iid}/discussions/${encodeURIComponent(thread)}`,
+          "-F",
+          "resolved=true",
+        ],
+        `resolve on merge request !${iid}`,
+      );
+      if (!resolved.ok) return resolved;
+      const open = (resolved.data.notes ?? []).some(
+        (note) => note.resolvable === true && note.resolved !== true,
+      );
+      return open
+        ? failure("failed", `discussion ${thread} on merge request !${iid} is still unresolved`)
+        : success(undefined);
+    },
+
+    threadState(iid, thread) {
+      const discussion = apiJson<GlDiscussion>(
+        runner,
+        "glab",
+        apiHost,
+        api(`${project}/merge_requests/${iid}/discussions/${encodeURIComponent(thread)}`),
+        `discussion ${thread}`,
+      );
+      if (!discussion.ok) return discussion.code === "not_found" ? success(null) : discussion;
+      const notes = Array.isArray(discussion.data.notes) ? discussion.data.notes : [];
+      if (!notes.some((note) => note.resolvable === true)) return success(null);
+      return success(
+        notes.some((note) => note.resolvable === true && note.resolved !== true)
+          ? "open"
+          : "resolved",
+      );
+    },
   };
 }

package/src/forge/pr-edit.ts

@@ -0,0 +1,291 @@
+// `workit pr ready|edit|threads|reply` (audit M13): the PR lifecycle steps
+// `pr status` prescribes, so an agent never reaches for gh/glab directly.
+//
+// Every write needs the `pr` grant and an open PR/MR. `edit --base` retargets
+// only to the branch's default target or to a branch the workspace policy does
+// not protect, so a feature PR is never pointed at a production branch by an
+// edit. `reply` and `resolve` act only on a thread `pr status` lists as
+// unresolved on that PR, so a stray id never lands on another PR.
+import { spawnSync } from "node:child_process";
+import { requireGrant } from "../autonomy";
+import { isProtectedTarget } from "../core/branch";
+import { recordedBaseKey, workspaceReleaseTracks } from "../core/release-tracks";
+import { vcsConfig } from "../core/vcs-config";
+import { GIT_TIMEOUTS } from "../git/rev";
+import { listStacks } from "../stack";
+import { checkNames } from "./pr-ops";
+import { selectPr } from "./report";
+import type { ResolvedForge } from "./resolve";
+import {
+  failure,
+  success,
+  type ForgeResult,
+  type ForgeThread,
+  type PrEdit,
+  type PrMeta,
+} from "./types";
+
+const label = (resolved: ResolvedForge, number: number): string =>
+  `${resolved.forge.kind === "github" ? "PR #" : "MR !"}${number}`;
+
+/** The grant, the PR number and its metadata; refuses a closed or merged PR. */
+function openPr(cwd: string, resolved: ResolvedForge, pr: number | null): ForgeResult<PrMeta> {
+  const grant = requireGrant(cwd, "pr");
+  if (!grant.allowed) return failure("blocked", grant.error, grant.unblock);
+  const number = selectPr(cwd, resolved, { pr });
+  if (!number.ok) return number;
+  const meta = resolved.forge.prMeta(number.data);
+  if (!meta.ok) return meta;
+  if (meta.data.state !== "open")
+    return failure(
+      "blocked",
+      `${meta.data.state}: ${label(resolved, meta.data.number)} is ${meta.data.state}`,
+      `workit pr status --pr ${meta.data.number}`,
+    );
+  return meta;
+}
+
+export type ReadyOutcome = { number: number; url: string; draft: boolean; changed: boolean };
+
+/** Mark a draft ready for review, or (`undo`) convert it back to a draft; verified after. */
+export function readyPullRequest(
+  cwd: string,
+  resolved: ResolvedForge,
+  input: { pr: number | null; undo: boolean },
+): ForgeResult<ReadyOutcome> {
+  const meta = openPr(cwd, resolved, input.pr);
+  if (!meta.ok) return meta;
+  const { number, url } = meta.data;
+  const want = input.undo;
+  if (meta.data.draft === want) return success({ number, url, draft: want, changed: false });
+  const set = resolved.forge.setDraft(number, want);
+  if (!set.ok) return set;
+  const after = resolved.forge.prMeta(number);
+  if (!after.ok) return after;
+  if (after.data.draft !== want)
+    return failure(
+      "failed",
+      `ready_unverified: the forge accepted the change but ${label(resolved, number)} still reads ${after.data.draft ? "draft" : "ready"}`,
+      `workit pr status --pr ${number}`,
+    );
+  return success({ number, url, draft: want, changed: true });
+}
+
+export type EditOutcome = {
+  number: number;
+  url: string;
+  title: string;
+  base: string;
+  /** What was asked for, by field (title, body, base, labels, reviewers). */
+  changed: string[];
+};
+
+const git = (cwd: string, args: string[]): string | null => {
+  const run = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    timeout: GIT_TIMEOUTS.local,
+    killSignal: "SIGKILL",
+  });
+  return run.status === 0 ? run.stdout.trim() || null : null;
+};
+
+/**
+ * Where `pr edit --base` may point the PR: the head branch's default target
+ * (from the release track that owns the PR's current base, else the head's
+ * own track; an undetermined line refuses), or the head's stack parent —
+ * its recorded `workitBase` or its parent entry in a stack. A protected
+ * branch other than the default target never qualifies.
+ */
+function checkBase(cwd: string, meta: PrMeta, base: string): ForgeResult<void> {
+  const head = meta.headBranch;
+  if (!base || /\s/u.test(base) || base.startsWith("refs/") || base.startsWith("-"))
+    return failure("invalid_input", `--base must be a plain branch name, not "${base}"`);
+  if (base === head) return failure("invalid_input", `${head} cannot be its own base`);
+  const read = workspaceReleaseTracks(cwd);
+  if (read.error) return failure("blocked", read.error, "fix the workspace's releaseTracks");
+  const owners = read.tracks.filter((track) =>
+    [
+      track.integrationBranch,
+      track.productionBranch,
+      track.baseBranch,
+      track.pullRequestTarget,
+    ].includes(meta.base),
+  );
+  const config = vcsConfig("resolve", cwd, {
+    branch: head,
+    ...(owners.length === 1 ? { track: owners[0].name } : {}),
+  });
+  if (config.ok === false)
+    return failure("blocked", String(config.error), "fix ~/.config/workit/vcs.json");
+  const blocking = config.releaseTrack?.blocking;
+  if (blocking)
+    return failure(
+      "blocked",
+      String(blocking),
+      "retarget it on the forge yourself, or fix WORKFLOW_RELEASE_TRACK",
+    );
+  const target = String(config.defaultTargetBranch ?? "") || null;
+  if (base === target) return success(undefined);
+  const instead = target
+    ? `workit pr edit --pr ${meta.number} --base ${target}  # or retarget it on the forge yourself`
+    : "retarget it on the forge yourself";
+  if (isProtectedTarget(cwd, base))
+    return failure(
+      "blocked",
+      `protected_base: ${base} is protected by the workspace branch policy and is not ${head}'s default target${target ? ` (${target})` : ""}; workit never retargets a PR onto it`,
+      instead,
+    );
+  const stacks = listStacks(cwd);
+  // Only the branch directly below the head: a descendant or sibling would
+  // make a cycle or cross stacks.
+  const parents = new Set<string>(
+    stacks.ok
+      ? stacks.data.flatMap((stack) =>
+          stack.branches.filter((entry) => entry.branch === head).map((entry) => entry.parent),
+        )
+      : [],
+  );
+  const recorded = git(cwd, ["config", "--get", recordedBaseKey(head)]);
+  if (base === recorded || parents.has(base)) return success(undefined);
+  return failure(
+    "blocked",
+    `not_stack_parent: ${base} is neither ${head}'s default target${target ? ` (${target})` : ""} nor its stack parent; workit retargets only to those`,
+    instead,
+  );
+}
+
+export function editPullRequest(
+  cwd: string,
+  resolved: ResolvedForge,
+  input: { pr: number | null; edit: PrEdit },
+): ForgeResult<EditOutcome> {
+  const { edit } = input;
+  const changed = [
+    ...(edit.title !== undefined ? ["title"] : []),
+    ...(edit.body !== undefined ? ["body"] : []),
+    ...(edit.base !== undefined ? ["base"] : []),
+    ...(edit.addLabels.length || edit.removeLabels.length ? ["labels"] : []),
+    ...(edit.addReviewers.length ? ["reviewers"] : []),
+  ];
+  if (!changed.length) return failure("invalid_input", "nothing to edit");
+  if (edit.title !== undefined && !edit.title.trim())
+    return failure("invalid_input", "--title must not be empty");
+  const bad = checkNames(
+    resolved.forge.kind,
+    resolved.forge.repo,
+    [...edit.addLabels, ...edit.removeLabels],
+    edit.addReviewers,
+  );
+  if (bad) return failure("invalid_input", bad);
+
+  const meta = openPr(cwd, resolved, input.pr);
+  if (!meta.ok) return meta;
+  const { number } = meta.data;
+  if (edit.base !== undefined) {
+    const allowed = checkBase(cwd, meta.data, edit.base);
+    if (!allowed.ok) return allowed;
+  }
+  const done = resolved.forge.editPr(number, edit);
+  if (!done.ok) return done;
+  const after = resolved.forge.prMeta(number);
+  if (!after.ok) return after;
+  if (edit.base !== undefined && after.data.base !== edit.base)
+    return failure(
+      "failed",
+      `edit_unverified: ${label(resolved, number)} still targets ${after.data.base}, not ${edit.base}`,
+      `workit pr status --pr ${number}`,
+    );
+  return success({
+    number,
+    url: after.data.url,
+    title: after.data.title,
+    base: after.data.base,
+    changed,
+  });
+}
+
+export type ThreadsOutcome = {
+  number: number;
+  url: string;
+  threads: ForgeThread[];
+  truncated: boolean;
+};
+
+/** The PR's unresolved review threads (the ones `pr status` counts). Read-only. */
+export function listThreads(
+  cwd: string,
+  resolved: ResolvedForge,
+  input: { pr: number | null },
+): ForgeResult<ThreadsOutcome> {
+  const number = selectPr(cwd, resolved, { pr: input.pr });
+  if (!number.ok) return number;
+  const status = resolved.forge.prStatus(number.data);
+  if (!status.ok) return status;
+  return success({
+    number: status.data.number,
+    url: status.data.url,
+    threads: status.data.threads,
+    truncated: status.data.truncated,
+  });
+}
+
+export type ReplyOutcome = {
+  number: number;
+  thread: string;
+  replied: boolean;
+  replyUrl: string | null;
+  resolved: boolean;
+};
+
+/** Reply to and/or resolve one unresolved thread of the PR. */
+export function replyToThread(
+  cwd: string,
+  resolved: ResolvedForge,
+  input: { pr: number | null; thread: string; body: string | null; resolve: boolean },
+): ForgeResult<ReplyOutcome> {
+  if (input.body === null && !input.resolve)
+    return failure("invalid_input", "pass --body-file <f> and/or --resolve");
+  if (input.body !== null && !input.body.trim())
+    return failure("invalid_input", "the reply body is empty");
+  const meta = openPr(cwd, resolved, input.pr);
+  if (!meta.ok) return meta;
+  const { number } = meta.data;
+  const status = resolved.forge.prStatus(number);
+  if (!status.ok) return status;
+  const listed = status.data.threads.some((thread) => thread.id === input.thread);
+  // A list cut at the page cap may miss the thread: ask for it directly.
+  const open =
+    listed ||
+    (status.data.truncated &&
+      (() => {
+        const state = resolved.forge.threadState(number, input.thread);
+        return state.ok && state.data === "open";
+      })());
+  if (!open)
+    return failure(
+      "not_found",
+      `thread ${input.thread} is not an unresolved thread of ${label(resolved, number)}`,
+      `workit pr threads --pr ${number}`,
+    );
+  let replyUrl: string | null = null;
+  if (input.body !== null) {
+    const replied = resolved.forge.replyThread(number, input.thread, input.body);
+    if (!replied.ok) return replied;
+    replyUrl = replied.data.url;
+  }
+  if (input.resolve) {
+    const done = resolved.forge.resolveThread(number, input.thread);
+    if (!done.ok)
+      return input.body === null
+        ? done
+        : failure(done.code, `replied, but not resolved: ${done.error}`, done.unblock);
+  }
+  return success({
+    number,
+    thread: input.thread,
+    replied: input.body !== null,
+    replyUrl,
+    resolved: input.resolve,
+  });
+}

package/src/forge/pr-ops.ts

@@ -59,6 +59,9 @@ export type CreateInput = {
   body: string;
   draft: boolean;
   actor: LedgerActor;
+  /** Applied after the PR is opened or found (`--label`, `--reviewer`). */
+  labels?: string[];
+  reviewers?: string[];
 };
 
 export type CreateOutcome = {
@@ -86,10 +89,14 @@ const createNext = (cwd: string): string => {
   return `a non-author verifies the head (workit-review); the endpoint is ${endpoint}, so ${AFTER_REVIEW[endpoint]}`;
 };
 
+/** Workit's own commit trailer: provenance for the ledger, not PR prose. */
+const SESSION_TRAILER = /^Workit-Session:.*$/gimu;
+
 /**
  * `--fill`: the title and body from the branch's commits on top of the base
  * (fetched first). One commit gives its subject and body; several give the
- * oldest subject and a list of every subject.
+ * oldest subject and every subject with its body, like `gh pr create
+ * --fill-verbose`. `Workit-Session:` trailers are left out of the body.
  */
 export function fillFromCommits(
   cwd: string,
@@ -122,7 +129,7 @@ export function fillFromCommits(
     .filter(Boolean)
     .map((entry) => {
       const [subject = "", body = ""] = entry.split("\x1f");
-      return { subject: subject.trim(), body: body.trim() };
+      return { subject: subject.trim(), body: body.replace(SESSION_TRAILER, "").trim() };
     });
   if (commits.length === 0)
     return failure(
@@ -133,10 +140,49 @@ export function fillFromCommits(
   if (commits.length === 1) return success({ title: commits[0].subject, body: commits[0].body });
   return success({
     title: commits[0].subject,
-    body: commits.map((commit) => `- ${commit.subject}`).join("\n"),
+    body: commits
+      .map((commit) =>
+        [`- ${commit.subject}`, ...(commit.body ? ["", indent(commit.body), ""] : [])].join("\n"),
+      )
+      .join("\n")
+      .trim(),
   });
 }
 
+const indent = (text: string): string =>
+  text
+    .split("\n")
+    .map((line) => (line ? `  ${line}` : line))
+    .join("\n");
+
+/**
+ * Labels and reviewers a PR write may send, checked before any forge call
+ * (so `pr create --label/--reviewer` never fails after the PR is open):
+ * comma-free names (GitLab joins labels with commas), GitLab reviewers are
+ * usernames, and a GitHub `org/team` belongs to the repository's owner.
+ */
+export function checkNames(
+  kind: "github" | "gitlab",
+  repo: string,
+  labels: readonly string[],
+  reviewers: readonly string[],
+): string | null {
+  const bad = [...labels, ...reviewers].find(
+    (value) => !value.trim() || value.includes(",") || value !== value.trim(),
+  );
+  if (bad !== undefined) return `invalid label or reviewer "${bad}"`;
+  const owner = repo.split("/")[0]?.toLowerCase() ?? "";
+  for (const reviewer of reviewers) {
+    if (!reviewer.includes("/")) continue;
+    if (kind === "gitlab") return `GitLab reviewers are usernames, not teams ("${reviewer}")`;
+    const [org = "", team = "", ...rest] = reviewer.split("/");
+    if (!team || rest.length) return `invalid team reviewer "${reviewer}" (use <org>/<team>)`;
+    if (org.toLowerCase() !== owner)
+      return `team ${reviewer} is not in ${owner}; GitHub only requests teams of the repository's owner`;
+  }
+  return null;
+}
+
 /** The pushed head of the current branch, bound before any forge write. */
 export function boundSource(
   cwd: string,
@@ -193,6 +239,13 @@ export async function createPullRequest(
   input: CreateInput,
   sleep: Sleep,
 ): Promise<ForgeResult<CreateOutcome>> {
+  const names = checkNames(
+    resolved.forge.kind,
+    resolved.forge.repo,
+    input.labels ?? [],
+    input.reviewers ?? [],
+  );
+  if (names) return failure("invalid_input", names);
   const grant = requireGrant(cwd, "pr");
   if (!grant.allowed) return grantBlocked(grant);
   const source = boundSource(cwd, resolved);
@@ -242,6 +295,21 @@ export async function createPullRequest(
     repo: resolved.forge.repo,
     created,
   });
+  const labels = input.labels ?? [];
+  const reviewers = input.reviewers ?? [];
+  if (labels.length || reviewers.length) {
+    const edited = resolved.forge.editPr(ref.number, {
+      addLabels: labels,
+      removeLabels: [],
+      addReviewers: reviewers,
+    });
+    if (!edited.ok)
+      return failure(
+        edited.code,
+        `${noun(resolved)} #${ref.number} is open (${ref.url}), but its labels or reviewers were not set: ${edited.error}`,
+        `workit pr edit --pr ${ref.number}${labels.map((name) => ` --add-label ${name}`).join("")}${reviewers.map((name) => ` --add-reviewer ${name}`).join("")}`,
+      );
+  }
   return success({
     number: ref.number,
     url: ref.url,
@@ -351,19 +419,37 @@ const refuse = (error: string, unblock: string, refusal: MergeRefusal): MergeRes
   refusal,
 });
 
-const NEXT_HINTS: Record<string, string> = {
-  RESOLVE_CONFLICTS: "rebase onto the base, resolve, then workit git push --force-with-lease",
-  REBASE: "rebase onto the base, then workit git push --force-with-lease",
-  RESOLVE_THREADS: "address and resolve the open review threads (workit pr status lists them)",
-  FIX_CI:
-    "fix the failing checks (workit pr status shows the log tails), push, then workit ci wait",
-  WAITING_CI: "workit ci wait",
-  ADDRESS_REVIEW: "address the requested changes",
-  REVIEW: "get the required review",
-  MARK_READY: "mark the PR ready for review",
-  IN_MERGE_QUEUE: "the PR is already in the merge queue",
-  NOT_MERGEABLE: "workit pr status  # the forge reports it cannot merge yet",
-};
+/**
+ * The command (or step) that clears a `next` blocker, for `pr status` and a
+ * `pr merge` refusal; null for READY and the terminal states.
+ */
+export function nextHint(next: string, number: number): string | null {
+  const pr = `--pr ${number}`;
+  switch (next) {
+    case "RESOLVE_CONFLICTS":
+      return "rebase onto the base, resolve, then workit git push --force-with-lease";
+    case "REBASE":
+      return "rebase onto the base, then workit git push --force-with-lease";
+    case "RESOLVE_THREADS":
+      return `workit pr threads ${pr}; fix or answer each: workit pr reply ${pr} --thread <id> --body-file <f> [--resolve]`;
+    case "FIX_CI":
+      return "fix the failing checks (workit pr status shows the log tails), push, then workit ci wait";
+    case "WAITING_CI":
+      return "workit ci wait";
+    case "ADDRESS_REVIEW":
+      return `address the requested changes; answer threads with workit pr reply ${pr} --thread <id> --body-file <f>`;
+    case "REVIEW":
+      return `get the required review (workit pr edit ${pr} --add-reviewer <login>)`;
+    case "MARK_READY":
+      return `workit pr ready ${pr}`;
+    case "IN_MERGE_QUEUE":
+      return "the PR is already in the merge queue";
+    case "NOT_MERGEABLE":
+      return "workit pr status  # the forge reports it cannot merge yet";
+    default:
+      return null;
+  }
+}
 
 export async function mergePullRequest(
   cwd: string,
@@ -406,7 +492,7 @@ export async function mergePullRequest(
   if (doc.next !== "READY")
     return refuse(
       `not_ready: ${label} is ${doc.next} (${doc.blockers.join(", ") || doc.next.toLowerCase()})`,
-      NEXT_HINTS[doc.next] ?? "workit pr status",
+      nextHint(doc.next, doc.number) ?? "workit pr status",
       { reason: "not_ready", next: doc.next, blockers: doc.blockers },
     );
 

package/src/forge/report.ts

@@ -473,14 +473,15 @@ export function waitVerdict(
     return { state: "waiting", reason: "head_mismatch" };
   const checks = doc.checks.state;
   if (checks === "failing") return { state: "failed", reason: "checks_failing" };
-  if (checks === "pending") return { state: "waiting", reason: "checks_pending" };
-  if (checks === "passing") return { state: "ready", reason: "checks_passing" };
-  if (doc.conflicts)
+  // Before "pending": CI never runs on a conflicting PR, so waiting cannot help (M8).
+  if (doc.conflicts && checks !== "passing")
     return {
       state: "blocked",
       reason: "conflicts",
       unblock: `rebase onto ${doc.base} and push; CI does not run on a conflicting PR`,
     };
+  if (checks === "pending") return { state: "waiting", reason: "checks_pending" };
+  if (checks === "passing") return { state: "ready", reason: "checks_passing" };
   const ciRequired =
     doc.checks.missingRequired === null ||
     doc.mergeState === "ci_must_pass" ||