@plainconceptsplatform/workflows 1.12.0 → 1.13.1

package/loops/actions/merge-dependabot/action.yml

@@ -0,0 +1,62 @@
+# Managed by @plainconceptsplatform/workflows. Source: loops/actions/merge-dependabot/action.yml. Update with workflows update --force; consumer edits may be overwritten.
+name: Merge Dependabot pull requests
+description: >-
+  Squash-merge the open Dependabot pull requests whose checks are all green, ask Dependabot to
+  rebase the ones that are behind or conflicting, and leave the failing ones with a line in the job
+  summary. Only pull requests Dependabot opened and every commit of which Dependabot made are
+  touched. API calls only: no pull request code is checked out or run, and no model decides.
+
+inputs:
+  token:
+    description: >-
+      Token for the writes: approve, merge, comment. Contents and pull-requests write. The App
+      token makes the merge start the push workflows on the default branch; a merge made with
+      GITHUB_TOKEN starts none.
+    required: true
+  read-token:
+    description: >-
+      Token for the reads: pull requests, check runs, commit statuses. Needs checks and statuses
+      read, which the App may not hold. A read it is refused skips that pull request with a warning.
+    required: false
+    default: ${{ github.token }}
+  scope:
+    description: "Which updates merge: all, minor (minor and patch), patch, or off."
+    required: false
+    default: all
+  merge-without-checks:
+    description: "true merges a pull request with no checks at all, once its head is an hour old. false leaves it."
+    required: false
+    default: 'true'
+  max-merges:
+    description: How many pull requests one run merges at most.
+    required: false
+    default: '5'
+  skip-labels:
+    description: Space-separated labels that keep a pull request out.
+    required: false
+    default: do-not-merge blocked human-review hold
+  post-merge-event:
+    description: repository_dispatch event sent after each merge, the one land-pull-request sends. Empty sends none.
+    required: false
+    default: agentic-post-merge
+  dry-run:
+    description: Decide and report, and write nothing.
+    required: false
+    default: 'false'
+
+runs:
+  using: composite
+  steps:
+    - name: Merge Dependabot pull requests
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        READ_TOKEN: ${{ inputs.read-token }}
+        REPO: ${{ github.repository }}
+        SCOPE: ${{ inputs.scope }}
+        MERGE_WITHOUT_CHECKS: ${{ inputs.merge-without-checks }}
+        MAX_MERGES: ${{ inputs.max-merges }}
+        SKIP_LABELS: ${{ inputs.skip-labels }}
+        POST_MERGE_EVENT: ${{ inputs.post-merge-event }}
+        DRY_RUN: ${{ inputs.dry-run }}
+      run: node "${GITHUB_ACTION_PATH}/merge-dependabot.mjs"

package/loops/actions/merge-dependabot/merge-dependabot.mjs

@@ -0,0 +1,373 @@
+// Managed by @plainconceptsplatform/workflows. Source: loops/actions/merge-dependabot/merge-dependabot.mjs. Update with workflows update --force; consumer edits may be overwritten.
+//
+// Squash-merges Dependabot pull requests whose checks are green. API calls only: the pull
+// request's code is never checked out or run, and no model decides anything.
+
+import { appendFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+export const DEPENDABOT_LOGINS = new Set(["dependabot[bot]", "app/dependabot"]);
+// Dependabot's commits are created through the API: GitHub commits and signs them as web-flow.
+const DEPENDABOT_COMMITTERS = new Set(["web-flow", "dependabot[bot]"]);
+export const SCOPES = ["all", "minor", "patch", "off"];
+export const REBASE_COMMAND = "@dependabot rebase";
+const BUMP_RANK = { patch: 1, minor: 2, major: 3, unknown: 4 };
+const OK_CONCLUSIONS = new Set(["success", "neutral", "skipped"]);
+const MAX_EXAMINED = 30;
+const MIN_RATE_REMAINING = 100;
+export const NO_CHECKS_GRACE_MINUTES = 60;
+
+export const isDependabot = (login) => DEPENDABOT_LOGINS.has(login ?? "");
+
+// A read the token may not make. The pull request is skipped and the run goes on.
+export class ReadDenied extends Error {
+  constructor(what, permission) {
+    super(`cannot read ${what}: grant ${permission}: read to the App or the workflow token`);
+  }
+}
+
+export function authorshipProblem(pr, commits, repository) {
+  if (!isDependabot(pr.user?.login)) return `opened by ${pr.user?.login ?? "unknown"}`;
+  if (String(pr.head?.repo?.full_name).toLowerCase() !== repository.toLowerCase()) return "its branch is in another repository";
+  if (!String(pr.head?.ref ?? "").startsWith("dependabot/")) return `branch ${pr.head?.ref} is not a Dependabot branch`;
+  if (commits.length === 0) return "it has no commits";
+  // The commits endpoint stops at 250, so a longer list cannot be proven all Dependabot's.
+  if (commits.length >= 250) return "too many commits to verify";
+  for (const commit of commits) {
+    const sha = String(commit.sha ?? "").slice(0, 7);
+    if (!isDependabot(commit.author?.login)) return `commit ${sha} is by ${commit.author?.login ?? "an unknown author"}`;
+    if (!DEPENDABOT_COMMITTERS.has(commit.committer?.login ?? "")) return `commit ${sha} was committed by ${commit.committer?.login ?? "an unknown committer"}`;
+    if (commit.commit?.verification?.verified !== true) return `commit ${sha} is not verified`;
+  }
+  return null;
+}
+
+export function labelProblem(pr, skipLabels) {
+  const held = (pr.labels ?? []).map((label) => label.name).filter((name) => skipLabels.includes(name));
+  return held.length > 0 ? `labelled ${held.join(", ")}` : null;
+}
+
+const VERSION = "`?(v?[0-9][^\\s`|]*?)`?";
+const TITLE_UPDATE = new RegExp(`\\bbump (\\S+) from ${VERSION} to ${VERSION}(?:\\s+in\\s|\\s*$)`, "i");
+const BODY_UPDATE = new RegExp(`^(?:Bumps|Updates|Updated) \\[?\`?([^\\]\`\\s]+)\`?\\]?(?:\\([^)]*\\))? from ${VERSION} to ${VERSION}\\.?\\s*$`, "i");
+const TABLE_ROW = new RegExp(`^\\|\\s*\\[?([^\\]|]+?)\\]?(?:\\([^)]*\\))?\\s*\\|\\s*${VERSION}\\s*\\|\\s*${VERSION}\\s*\\|\\s*$`);
+
+export function parseUpdates(title, body) {
+  const updates = [];
+  const titleMatch = TITLE_UPDATE.exec(title ?? "");
+  if (titleMatch) updates.push({ name: titleMatch[1], from: titleMatch[2], to: titleMatch[3] });
+  // Release notes and changelogs sit inside <details>, and they quote versions of their own.
+  const text = String(body ?? "").replace(/\r\n/g, "\n").replace(/<details>[\s\S]*?<\/details>/gi, "");
+  let inTable = false;
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (/^\|\s*Package\s*\|\s*From\s*\|\s*To\s*\|$/i.test(trimmed)) { inTable = true; continue; }
+    if (!trimmed.startsWith("|")) inTable = false;
+    const match = BODY_UPDATE.exec(trimmed) ?? (inTable ? TABLE_ROW.exec(trimmed) : null);
+    if (match) updates.push({ name: match[1].trim(), from: match[2], to: match[3] });
+  }
+  const seen = new Set();
+  return updates.filter((update) => {
+    const key = `${update.name}\0${update.from}\0${update.to}`;
+    return seen.has(key) ? false : (seen.add(key), true);
+  });
+}
+
+const numeric = (version) => {
+  const match = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(version);
+  return match ? [Number(match[1]), Number(match[2] ?? 0), Number(match[3] ?? 0)] : null;
+};
+
+export function bumpLevel(from, to) {
+  const before = numeric(from);
+  const after = numeric(to);
+  if (before === null || after === null) return "unknown";
+  if (before[0] !== after[0]) return "major";
+  if (before[1] !== after[1]) return "minor";
+  return "patch";
+}
+
+export function highestBump(updates) {
+  if (updates.length === 0) return "unknown";
+  return updates.map((update) => bumpLevel(update.from, update.to))
+    .reduce((highest, level) => (BUMP_RANK[level] > BUMP_RANK[highest] ? level : highest), "patch");
+}
+
+export function scopeAllows(scope, bump) {
+  if (scope === "all") return true;
+  if (scope === "minor") return bump === "patch" || bump === "minor";
+  if (scope === "patch") return bump === "patch";
+  return false;
+}
+
+export function summarizeChecks({ checkRuns = [], statuses = [], required = [] }) {
+  const latest = new Map();
+  for (const run of checkRuns) {
+    const known = latest.get(run.name);
+    if (known === undefined || run.id > known.id) latest.set(run.name, run);
+  }
+  const failing = [];
+  const pending = [];
+  for (const run of latest.values()) {
+    if (run.status !== "completed") pending.push(run.name);
+    else if (!OK_CONCLUSIONS.has(run.conclusion)) failing.push(`${run.name} (${run.conclusion})`);
+  }
+  for (const status of statuses) {
+    if (status.state === "pending") pending.push(status.context);
+    else if (status.state !== "success") failing.push(`${status.context} (${status.state})`);
+  }
+  const reported = new Set([...latest.keys(), ...statuses.map((status) => status.context)]);
+  for (const context of required) {
+    if (!reported.has(context)) pending.push(`${context} (required, not reported)`);
+  }
+  const state = failing.length > 0 ? "failure" : pending.length > 0 ? "pending" : reported.size === 0 ? "none" : "success";
+  return { state, failing, pending };
+}
+
+export function rebaseAlreadyRequested(comments, headCommittedAt) {
+  const since = Date.parse(headCommittedAt ?? "");
+  return comments.some((comment) =>
+    String(comment.body ?? "").trim().toLowerCase() === REBASE_COMMAND &&
+    (Number.isNaN(since) || Date.parse(comment.created_at) >= since));
+}
+
+// One pull request, everything already fetched. The decision is pure so it can be tested.
+export function decide({ pr, commits, defaultBranch, repository, skipLabels, scope, checks, comments, mergeWithoutChecks, now }) {
+  const bump = highestBump(parseUpdates(pr.title, pr.body));
+  const skip = (reason) => ({ action: "skip", reason, bump });
+  if (pr.draft) return skip("draft");
+  if (pr.base?.ref !== defaultBranch) return skip(`targets ${pr.base?.ref}, not ${defaultBranch}`);
+  const labelled = labelProblem(pr, skipLabels);
+  if (labelled) return skip(labelled);
+  const authorship = authorshipProblem(pr, commits, repository);
+  if (authorship) return skip(authorship);
+  if (!scopeAllows(scope, bump)) return skip(`${bump} update, DEPENDABOT_MERGE is ${scope}`);
+
+  const headCommittedAt = commits.at(-1)?.commit?.committer?.date;
+  if (pr.mergeable === false || pr.mergeable_state === "dirty" || pr.mergeable_state === "behind") {
+    const why = pr.mergeable_state === "behind" ? "behind its base" : "conflicting";
+    if (rebaseAlreadyRequested(comments, headCommittedAt)) return { action: "wait", reason: `${why}; rebase already requested`, bump };
+    return { action: "rebase", reason: why, bump };
+  }
+  if (pr.mergeable !== true) return { action: "wait", reason: "GitHub has not computed mergeability yet", bump };
+
+  if (checks.state === "failure") return { action: "fail", reason: `failing: ${checks.failing.join(", ")}`, bump };
+  if (checks.state === "pending") return { action: "wait", reason: `pending: ${checks.pending.join(", ")}`, bump };
+  if (checks.state === "none") {
+    if (!mergeWithoutChecks) return skip("no checks, DEPENDABOT_MERGE_WITHOUT_CHECKS is false");
+    // CI that has not registered yet looks like no CI at all.
+    const ageMinutes = (now - Date.parse(headCommittedAt ?? pr.updated_at)) / 60000;
+    if (!(ageMinutes >= NO_CHECKS_GRACE_MINUTES)) return { action: "wait", reason: `no checks yet; merging once the head is ${NO_CHECKS_GRACE_MINUTES} minutes old`, bump };
+    return { action: "merge", reason: "no checks configured", bump };
+  }
+  return { action: "merge", reason: "checks green", bump };
+}
+
+export function readConfig(env) {
+  const scope = String(env.SCOPE || "all").trim().toLowerCase();
+  if (!SCOPES.includes(scope)) throw new Error(`DEPENDABOT_MERGE must be one of ${SCOPES.join(", ")}, not "${env.SCOPE}"`);
+  const maxMerges = Number(env.MAX_MERGES || "5");
+  if (!Number.isInteger(maxMerges) || maxMerges < 0) throw new Error(`max-merges must be a whole number, not "${env.MAX_MERGES}"`);
+  return {
+    scope,
+    maxMerges,
+    mergeWithoutChecks: String(env.MERGE_WITHOUT_CHECKS || "true").trim().toLowerCase() !== "false",
+    skipLabels: String(env.SKIP_LABELS ?? "").split(/[\s,]+/).filter(Boolean),
+    dryRun: String(env.DRY_RUN || "false").trim().toLowerCase() === "true",
+    postMergeEvent: String(env.POST_MERGE_EVENT ?? "").trim(),
+  };
+}
+
+export function createClient({ token, apiUrl = "https://api.github.com", fetchImpl = fetch }) {
+  const state = { remaining: Infinity };
+  const request = async (method, path, body) => {
+    const response = await fetchImpl(path.startsWith("http") ? path : `${apiUrl}${path}`, {
+      method,
+      headers: {
+        authorization: `Bearer ${token}`,
+        accept: "application/vnd.github+json",
+        "x-github-api-version": "2022-11-28",
+        ...(body === undefined ? {} : { "content-type": "application/json" }),
+      },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    const remaining = Number(response.headers.get("x-ratelimit-remaining"));
+    if (!Number.isNaN(remaining)) state.remaining = remaining;
+    const text = await response.text();
+    let data = null;
+    try { data = text ? JSON.parse(text) : null; } catch { data = text; }
+    return { status: response.status, data, link: response.headers.get("link") ?? "" };
+  };
+  const paginate = async (path, limit = 300) => {
+    const items = [];
+    let next = path;
+    while (next && items.length < limit) {
+      const page = await request("GET", next);
+      if (page.status >= 400) throw Object.assign(new Error(`GET ${next} answered ${page.status}: ${JSON.stringify(page.data)}`), { status: page.status });
+      items.push(...(Array.isArray(page.data) ? page.data : page.data?.check_runs ?? []));
+      next = /<([^>]+)>;\s*rel="next"/.exec(page.link)?.[1];
+    }
+    return items;
+  };
+  return { request, paginate, rateRemaining: () => state.remaining };
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const denied = async (what, permission, read) => {
+  try { return await read(); } catch (error) {
+    throw error.status === 403 ? new ReadDenied(what, permission) : error;
+  }
+};
+
+async function readPullRequest(client, repository, number, wait) {
+  for (let attempt = 0; ; attempt++) {
+    const { status, data } = await client.request("GET", `/repos/${repository}/pulls/${number}`);
+    if (status === 403) throw new ReadDenied("pull requests", "Pull requests");
+    if (data?.mergeable !== null || attempt >= 3) return data;
+    await wait(2000);
+  }
+}
+
+async function requiredChecks(client, repository, branch) {
+  const contexts = new Set();
+  const rules = await client.request("GET", `/repos/${repository}/rules/branches/${encodeURIComponent(branch)}`);
+  for (const rule of Array.isArray(rules.data) ? rules.data : []) {
+    if (rule.type !== "required_status_checks") continue;
+    for (const check of rule.parameters?.required_status_checks ?? []) contexts.add(check.context);
+  }
+  const protection = await client.request("GET", `/repos/${repository}/branches/${encodeURIComponent(branch)}`);
+  for (const context of protection.data?.protection?.required_status_checks?.contexts ?? []) contexts.add(context);
+  return [...contexts];
+}
+
+async function readChecks(client, repository, sha, required) {
+  const checkRuns = await denied("checks", "Checks", () => client.paginate(`/repos/${repository}/commits/${sha}/check-runs?per_page=100`));
+  const combined = await client.request("GET", `/repos/${repository}/commits/${sha}/status?per_page=100`);
+  if (combined.status === 403) throw new ReadDenied("commit statuses", "Commit statuses");
+  return summarizeChecks({ checkRuns, statuses: combined.data?.statuses ?? [], required });
+}
+
+async function land(client, repository, pr, config) {
+  if (pr.mergeable_state === "blocked") {
+    // A ruleset may require an approval; one from this token meets it.
+    await client.request("POST", `/repos/${repository}/pulls/${pr.number}/reviews`, {
+      commit_id: pr.head.sha, event: "APPROVE", body: "Dependabot update with every check green.",
+    });
+  }
+  const merged = await client.request("PUT", `/repos/${repository}/pulls/${pr.number}/merge`, {
+    merge_method: "squash", sha: pr.head.sha,
+  });
+  if (merged.status === 200) {
+    await client.request("DELETE", `/repos/${repository}/git/refs/heads/${pr.head.ref}`);
+    if (config.postMergeEvent) {
+      // The same payload land-pull-request sends, so a consumer deploying on it needs nothing new.
+      await client.request("POST", `/repos/${repository}/dispatches`, {
+        event_type: config.postMergeEvent, client_payload: { sha: pr.head.sha, pr: String(pr.number), base: pr.base.ref },
+      });
+    }
+    return { action: "merged", reason: `squash-merged as ${String(merged.data?.sha ?? "").slice(0, 7)}` };
+  }
+  const message = String(merged.data?.message ?? JSON.stringify(merged.data)).slice(0, 200);
+  if (merged.status === 405 && /merge queue/i.test(message)) {
+    const enqueued = await client.request("POST", "/graphql", {
+      query: "mutation($id:ID!,$sha:GitObjectID!){enqueuePullRequest(input:{pullRequestId:$id,expectedHeadOid:$sha}){mergeQueueEntry{state}}}",
+      variables: { id: pr.node_id, sha: pr.head.sha },
+    });
+    if (enqueued.data?.data?.enqueuePullRequest?.mergeQueueEntry) return { action: "enqueued", reason: "added to the merge queue" };
+    return { action: "blocked", reason: `the merge queue refused it: ${JSON.stringify(enqueued.data?.errors ?? enqueued.data).slice(0, 200)}` };
+  }
+  if (merged.status === 409) return { action: "wait", reason: "the head moved while it was judged; next run" };
+  if ([403, 405, 422].includes(merged.status)) return { action: "blocked", reason: `GitHub refused the merge: ${message}` };
+  return { action: "error", reason: `merge answered ${merged.status}: ${message}` };
+}
+
+// `client` writes (approve, merge, comment) and `reader` reads. The App token writes, so its merge
+// starts the push workflows; the workflow token reads, as the App may hold no Checks permission.
+export async function run({ client, reader = client, repository, config, now = Date.now(), log = console.log, wait = sleep }) {
+  const rows = [];
+  const deniedReads = new Set();
+  if (config.scope === "off") return { rows, off: true };
+
+  const { data: repo } = await reader.request("GET", `/repos/${repository}`);
+  const defaultBranch = repo.default_branch;
+  const open = await reader.paginate(`/repos/${repository}/pulls?state=open&sort=created&direction=asc&per_page=100`);
+  const candidates = open.filter((pr) => isDependabot(pr.user?.login)).slice(0, MAX_EXAMINED);
+  const required = candidates.length > 0 ? await requiredChecks(reader, repository, defaultBranch) : [];
+  let merges = 0;
+
+  for (const listed of candidates) {
+    if (reader.rateRemaining() < MIN_RATE_REMAINING) {
+      rows.push({ number: listed.number, title: listed.title, bump: "", action: "wait", reason: "API rate limit nearly spent" });
+      continue;
+    }
+    let pr, commits, comments, checks;
+    try {
+      pr = await readPullRequest(reader, repository, listed.number, wait);
+      commits = await denied("pull request commits", "Pull requests", () => reader.paginate(`/repos/${repository}/pulls/${pr.number}/commits?per_page=100`, 250));
+      comments = await denied("issue comments", "Issues", () => reader.paginate(`/repos/${repository}/issues/${pr.number}/comments?per_page=100`));
+      const mergeableNow = pr.mergeable === true && !["dirty", "behind"].includes(pr.mergeable_state);
+      checks = mergeableNow ? await readChecks(reader, repository, pr.head.sha, required) : { state: "none", failing: [], pending: [] };
+    } catch (error) {
+      if (!(error instanceof ReadDenied)) throw error;
+      deniedReads.add(error.message);
+      log(`::warning::#${listed.number} skipped: ${error.message}`);
+      rows.push({ number: listed.number, title: listed.title, bump: "", action: "skip", reason: error.message });
+      continue;
+    }
+    let outcome = decide({
+      pr, commits, defaultBranch, repository, comments, checks, now,
+      skipLabels: config.skipLabels, scope: config.scope, mergeWithoutChecks: config.mergeWithoutChecks,
+    });
+
+    if (outcome.action === "merge" && merges >= config.maxMerges) {
+      outcome = { ...outcome, action: "wait", reason: `${config.maxMerges} merged this run; next run` };
+    } else if (outcome.action === "merge") {
+      merges++;
+      outcome = config.dryRun ? { ...outcome, action: "would merge" } : { ...outcome, ...await land(client, repository, pr, config) };
+    } else if (outcome.action === "rebase") {
+      if (!config.dryRun) await client.request("POST", `/repos/${repository}/issues/${pr.number}/comments`, { body: REBASE_COMMAND });
+      outcome = { ...outcome, action: config.dryRun ? "would ask rebase" : "asked rebase" };
+    }
+    log(`#${pr.number} ${outcome.action}: ${outcome.reason}`);
+    rows.push({ number: pr.number, title: pr.title, bump: outcome.bump, action: outcome.action, reason: outcome.reason });
+  }
+  return { rows, off: false, denied: [...deniedReads] };
+}
+
+export function renderSummary({ rows, off, denied: deniedReads = [] }, config) {
+  const lines = [`## Dependabot merge (${config.dryRun ? "dry run, " : ""}scope: ${config.scope})`, ""];
+  if (off) return [...lines, "DEPENDABOT_MERGE is off: nothing was examined.", ""].join("\n");
+  for (const message of deniedReads) lines.push("> [!WARNING]", `> ${message}.`, "");
+  if (rows.length === 0) return [...lines, "No open Dependabot pull requests.", ""].join("\n");
+  lines.push("| PR | Update | Bump | Result | Why |", "|---|---|---|---|---|");
+  const cell = (value) => String(value ?? "").replace(/\|/g, "\\|").replace(/\n/g, " ");
+  for (const row of rows) lines.push(`| #${row.number} | ${cell(row.title)} | ${cell(row.bump)} | ${cell(row.action)} | ${cell(row.reason)} |`);
+  return [...lines, ""].join("\n");
+}
+
+async function main() {
+  const config = readConfig({
+    SCOPE: process.env.SCOPE, MAX_MERGES: process.env.MAX_MERGES, MERGE_WITHOUT_CHECKS: process.env.MERGE_WITHOUT_CHECKS,
+    SKIP_LABELS: process.env.SKIP_LABELS, DRY_RUN: process.env.DRY_RUN, POST_MERGE_EVENT: process.env.POST_MERGE_EVENT,
+  });
+  const apiUrl = process.env.GITHUB_API_URL || "https://api.github.com";
+  const client = createClient({ token: process.env.GH_TOKEN, apiUrl });
+  const reader = process.env.READ_TOKEN ? createClient({ token: process.env.READ_TOKEN, apiUrl }) : client;
+  const result = await run({ client, reader, repository: process.env.REPO, config });
+  const summary = renderSummary(result, config);
+  if (process.env.GITHUB_STEP_SUMMARY) appendFileSync(process.env.GITHUB_STEP_SUMMARY, `${summary}\n`);
+  else console.log(summary);
+  const stuck = result.rows.filter((row) => row.action === "fail" || row.action === "blocked").length;
+  if (stuck > 0) console.log(`::notice::${stuck} Dependabot pull request(s) left open with failing checks or a refused merge; see the job summary.`);
+  const errors = result.rows.filter((row) => row.action === "error");
+  for (const row of errors) console.log(`::error::#${row.number}: ${row.reason}`);
+  if (errors.length > 0) process.exitCode = 1;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    console.log(`::error::${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/loops/actions/verify-route-matrix/verify-route-matrix.sh

@@ -1293,6 +1293,50 @@ if [ -f "$HOUSEKEEPING_YML" ]; then
   if [ "$HK_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 fi
 
+# Dependabot merges ride the maintenance run. They merge code nobody on the team wrote, so the
+# guarantees are asserted: the App token (a GITHUB_TOKEN merge starts no push workflow), the knobs
+# in the env: block, no checkout or process of the pull request's code, and only verified commits.
+DEPENDABOT_DIR="${HERE}/../merge-dependabot"
+if [ -f "${DEPENDABOT_DIR}/action.yml" ] && grep -q '^  housekeeping:$' "$ROUTER_YML"; then
+  DB_OK=1
+  hk_job=$(sed -n '/^  housekeeping:$/,/^  [a-z0-9_-]*:$/p' "$ROUTER_YML")
+  db_step=$(printf '%s\n' "$hk_job" | sed -n '/uses: \.\/\.github\/actions\/merge-dependabot/,/^      - /p')
+  printf '%s' "$db_step" | grep -q 'token: ${{ steps.app-token.outputs.token }}' ||
+    { DB_OK=0; echo "FAIL: the maintenance run does not merge Dependabot pull requests with the App token" >&2; }
+  # The App installation may hold no Checks permission: the reads run on the job token.
+  if ! printf '%s' "$db_step" | grep -q 'read-token: ${{ github.token }}' ||
+    ! printf '%s\n' "$hk_job" | grep -q '^      checks: read$'; then
+    DB_OK=0; echo "FAIL: the Dependabot merge must read checks with GITHUB_TOKEN granted checks: read" >&2
+  fi
+  for knob in DEPENDABOT_MERGE DEPENDABOT_MERGE_WITHOUT_CHECKS; do
+    if [ -z "$(router_env "$knob")" ] || ! printf '%s' "$db_step" | grep -q "env.${knob}"; then
+      DB_OK=0
+      echo "FAIL: ${knob} is not both declared in the router env: block and read by the Dependabot merge step" >&2
+    fi
+  done
+  if grep -q 'actions/checkout' "${DEPENDABOT_DIR}/action.yml" ||
+    grep -qE 'node:child_process|execFile|spawn\(' "${DEPENDABOT_DIR}/merge-dependabot.mjs"; then
+    DB_OK=0
+    echo "FAIL: merge-dependabot checks out or runs something; it must work through the API alone" >&2
+  fi
+  grep -qF 'verification?.verified !== true' "${DEPENDABOT_DIR}/merge-dependabot.mjs" ||
+    { DB_OK=0; echo "FAIL: merge-dependabot no longer requires every commit to be verified" >&2; }
+  grep -qF 'merge_method: "squash", sha: pr.head.sha' "${DEPENDABOT_DIR}/merge-dependabot.mjs" ||
+    { DB_OK=0; echo "FAIL: merge-dependabot must squash-merge the head it judged" >&2; }
+  if [ "$DB_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+fi
+# Dependabot's runs get a read-only token, so a CI template's merge-train dispatch fails its pull
+# request and holds the update forever.
+for template in "${HERE}/../../templates/ci/"*.yml; do
+  [ -f "$template" ] || continue
+  if ! grep -q 'operation=merge-train' "$template" || grep -q "pull_request.user.login != 'dependabot\[bot\]'" "$template"; then
+    PASS=$((PASS + 1))
+  else
+    FAIL=$((FAIL + 1))
+    echo "FAIL: $(basename "$template") dispatches the merge train from Dependabot's read-only runs" >&2
+  fi
+done
+
 # The audit chain closes its own reports, and every way it can be wrong is silent: a report
 # closed as completed with nothing implemented, or a report pinned open forever so the next
 # audit never runs. Both happened. Assert the three conditions that decide it.
@@ -2584,6 +2628,63 @@ if worker_installed audit; then
   if [ "$AUDIT_EMPTY_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 fi
 
+# Every audit from 2026-09-21 until 1.12.1 filed one issue over refine's size gate, labelled `refine`,
+# and was refused. The audit now files a report refine never sees and stories under the gate.
+if worker_installed audit; then
+  AUDIT_FILE_OK=1
+  AUDIT_WORKER_MD="${WORKFLOWS_DIR}/agent-audit.md"
+  REFINE_WORKER_MD="${WORKFLOWS_DIR}/agent-refine.md"
+  af() { AUDIT_FILE_OK=0; echo "FAIL: the audit $1" >&2; }
+  file_block=$(awk '/uses: \.\/\.github\/actions\/file-audit-issues/{found=1} found{print} found && /^  [a-z_]+:$/{exit}' "$AUDIT_WORKER_MD")
+  [ -n "$file_block" ] || af "does not file through file-audit-issues, so nothing measures what it files"
+  labels_of() { printf '%s\n' "$file_block" | awk -v key="$1:" '$1 == key {f=1; next} /^ *$|^ *#|^ *[a-z_-]+:/{f=0} f' | tr -d ' '; }
+  report_labels=$(labels_of report-labels)
+  story_labels=$(labels_of story-labels)
+  printf '%s\n' "$report_labels" | grep -qx audit || af "report is not labelled audit, so backpressure and audit-close cannot see it"
+  printf '%s\n' "$report_labels" | grep -qx refine && af "report is labelled refine; refine refuses a report of every finding"
+  printf '%s\n' "$story_labels" | grep -qx refine || af "stories are not labelled refine, so nothing refines them"
+  printf '%s\n' "$story_labels" | grep -qx audit && af "stories are labelled audit; three of them fill the backpressure and audit-close treats each as a report"
+  grep -qE '^  staged: true' "$AUDIT_WORKER_MD" || af "is not staged, so gh-aw files the issues before they are measured"
+  audit_env() { sed -n "s/^  $1: \"\([0-9]*\)\"$/\1/p" "$AUDIT_WORKER_MD" | head -1; }
+  if [ -f "$REFINE_WORKER_MD" ]; then
+    refine_chars=$(sed -n 's/^  REFINE_MAX_BODY_CHARS: "\([0-9]*\)"$/\1/p' "$REFINE_WORKER_MD" | head -1)
+    refine_units=$(sed -n 's/^  REFINE_MAX_WORK_UNITS: "\([0-9]*\)"$/\1/p' "$REFINE_WORKER_MD" | head -1)
+    [ "$(audit_env AUDIT_MAX_BODY_CHARS)" -lt "${refine_chars:-0}" ] 2>/dev/null ||
+      af "AUDIT_MAX_BODY_CHARS is not below refine's REFINE_MAX_BODY_CHARS (${refine_chars:-unset})"
+    [ "$(audit_env AUDIT_MAX_WORK_UNITS)" -lt "${refine_units:-0}" ] 2>/dev/null ||
+      af "AUDIT_MAX_WORK_UNITS is not below refine's REFINE_MAX_WORK_UNITS (${refine_units:-unset})"
+    grep -qF 'uses: ./.github/actions/measure-issue-size' "$REFINE_WORKER_MD" ||
+      af "and refine measure with different rules; refine's size_guard must use measure-issue-size"
+  fi
+  if [ "$AUDIT_FILE_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+fi
+
+# The docs audit filed the same single refine-labelled report and hit the same gate; it now files
+# like the audit: a report refine never sees and stories under the gate, measured before filing.
+if worker_installed docs-audit; then
+  DOCS_FILE_OK=1
+  DOCS_WORKER_MD="${WORKFLOWS_DIR}/agent-docs-audit.md"
+  dfa() { DOCS_FILE_OK=0; echo "FAIL: the docs audit $1" >&2; }
+  docs_block=$(awk '/uses: \.\/\.github\/actions\/file-audit-issues/{found=1} found{print} found && /^  [a-z_]+:$/{exit}' "$DOCS_WORKER_MD")
+  [ -n "$docs_block" ] || dfa "does not file through file-audit-issues, so nothing measures what it files"
+  docs_labels_of() { printf '%s\n' "$docs_block" | awk -v key="$1:" '$1 == key {f=1; next} /^ *$|^ *#|^ *[a-z_-]+:/{f=0} f' | tr -d ' '; }
+  docs_report_labels=$(docs_labels_of report-labels)
+  docs_story_labels=$(docs_labels_of story-labels)
+  printf '%s\n' "$docs_report_labels" | grep -qx docs-audit || dfa "report is not labelled docs-audit, so backpressure and audit-close cannot see it"
+  printf '%s\n' "$docs_report_labels" | grep -qx refine && dfa "report is labelled refine; refine refuses a report of every finding"
+  printf '%s\n' "$docs_story_labels" | grep -qx refine || dfa "stories are not labelled refine, so nothing refines them"
+  printf '%s\n' "$docs_story_labels" | grep -qx docs-audit && dfa "stories are labelled docs-audit; one of them fills the backpressure"
+  grep -qE '^  staged: true' "$DOCS_WORKER_MD" || dfa "is not staged, so gh-aw files the issues before they are measured"
+  grep -q 'add-issue-labels' "$DOCS_WORKER_MD" && dfa "still labels a report gh-aw filed itself"
+  if [ -f "${WORKFLOWS_DIR}/agent-refine.md" ]; then
+    docs_chars=$(sed -n 's/^  DOCS_AUDIT_MAX_BODY_CHARS: "\([0-9]*\)"$/\1/p' "$DOCS_WORKER_MD" | head -1)
+    refine_chars=$(sed -n 's/^  REFINE_MAX_BODY_CHARS: "\([0-9]*\)"$/\1/p' "${WORKFLOWS_DIR}/agent-refine.md" | head -1)
+    [ "${docs_chars:-99999999}" -lt "${refine_chars:-0}" ] 2>/dev/null ||
+      dfa "DOCS_AUDIT_MAX_BODY_CHARS is not below refine's REFINE_MAX_BODY_CHARS (${refine_chars:-unset})"
+  fi
+  if [ "$DOCS_FILE_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+fi
+
 echo "── Retrying a run that died early ────────────────────────────────────────"
 
 # A run that died before producing anything is worth repeating; one that worked and then failed