@plainconceptsplatform/workflows 1.12.0 → 1.13.0

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

@@ -0,0 +1,54 @@
+# 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 with 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
+  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 }}
+        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,343 @@
+// 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 ?? "");
+
+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 new Error(`GET ${next} answered ${page.status}: ${JSON.stringify(page.data)}`);
+      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));
+
+async function readPullRequest(client, repository, number, wait) {
+  for (let attempt = 0; ; attempt++) {
+    const { data } = await client.request("GET", `/repos/${repository}/pulls/${number}`);
+    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 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`);
+  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}` };
+}
+
+export async function run({ client, repository, config, now = Date.now(), log = console.log, wait = sleep }) {
+  const rows = [];
+  if (config.scope === "off") return { rows, off: true };
+
+  const { data: repo } = await client.request("GET", `/repos/${repository}`);
+  const defaultBranch = repo.default_branch;
+  const open = await client.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(client, repository, defaultBranch) : [];
+  let merges = 0;
+
+  for (const listed of candidates) {
+    if (client.rateRemaining() < MIN_RATE_REMAINING) {
+      rows.push({ number: listed.number, title: listed.title, bump: "", action: "wait", reason: "API rate limit nearly spent" });
+      continue;
+    }
+    const pr = await readPullRequest(client, repository, listed.number, wait);
+    const commits = await client.paginate(`/repos/${repository}/pulls/${pr.number}/commits?per_page=100`, 250);
+    const comments = await client.paginate(`/repos/${repository}/issues/${pr.number}/comments?per_page=100`);
+    const mergeableNow = pr.mergeable === true && !["dirty", "behind"].includes(pr.mergeable_state);
+    const checks = mergeableNow ? await readChecks(client, repository, pr.head.sha, required) : { state: "none", failing: [], pending: [] };
+    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 };
+}
+
+export function renderSummary({ rows, off }, 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");
+  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 client = createClient({ token: process.env.GH_TOKEN, apiUrl: process.env.GITHUB_API_URL || "https://api.github.com" });
+  const result = await run({ client, 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,45 @@ 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; }
+  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 +2623,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

package/loops/docs/diagrams.md

@@ -100,7 +100,7 @@ flowchart LR
     gate -.->|"CI failed or conflict"| fix("Fix, push, CI again") --> ci
     gate -.->|".github, secrets<br/>or 10000+ lines"| human(("Human review"))
     review("Someone reviews the PR") --> applyReview("apply-review") --> ci
-    audit("audit, weekly") -->|"files one issue"| refine
+    audit("audit, weekly") -->|"files stories"| refine
 
     classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
     classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
@@ -114,9 +114,7 @@ flowchart LR
     class merged success
 ```
 
-Audit creates work rather than consuming it, and files into `refine` rather than straight to
-`implement`, so a report of several unrelated findings becomes one properly sized issue per finding
-instead of one pull request that has to fix them all.
+Audit creates work rather than consuming it, and files into `refine` rather than straight to `implement`: one story issue per top finding, each under refine's size limit, plus a tracking report refine never sees, instead of one pull request that has to fix them all.
 
 ### The merge train
 
@@ -489,7 +487,7 @@ before anything changes. Applying them one at a time produces contradictory comm
 
 ## agent-audit.md
 
-Creates work rather than consuming it. Read-only: it files an issue and changes nothing.
+Creates work rather than consuming it. Read-only: it files a tracking report and one story issue per top finding, and changes nothing else.
 
 ```mermaid
 flowchart TD
@@ -506,8 +504,9 @@ flowchart TD
     auDedupe{"Already tracked, or<br/>previously rejected?"}
     auDedupe -.->|"all of them"| auQuiet
     auDedupe -->|"some are new"| auFile
-    auFile("One issue: every finding,<br/>top 3 refined into stories") --> auReport
-    auReport(("Filed<br/>labelled refine, so it gets<br/>sized and split per finding"))
+    auFile("Report of every finding,<br/>plus one story per top 3") --> auMeasure
+    auMeasure("conclude (rung 6)<br/>each body measured with<br/>refine's rule, trimmed to fit") --> auReport
+    auReport(("Filed<br/>report: audit, not refine<br/>stories: refine, sub-issues"))
     auQuiet(("Nothing to file<br/>the right outcome on a<br/>clean codebase"))
     auIdle(("Idle<br/>backlog already full"))
 
@@ -517,12 +516,14 @@ flowchart TD
     classDef idle fill:#202c40,stroke:#738198,stroke-width:2px,color:#ffffff
     classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
     class auStart start
-    class auFacts,auRun,auScore,auFile action
+    class auFacts,auRun,auScore,auFile,auMeasure action
     class auBack,auFilter,auDedupe decision
     class auIdle idle
     class auReport,auQuiet success
 ```
 
+The report never goes to refine: refine's size gate refused every audit filed as one issue of every finding and three stories, from 2026-09-21 until 1.12.1. Each story is filed on its own, labelled `refine`, linked under the report and listed in it, so `audit-close` closes the report once its stories are closed. A story already tracked by an open issue is listed against that issue instead of filed again.
+
 Memory matters here: open issues only cover what is still open, so a finding reported weeks ago and
 consciously not acted on would come back every single run. The audit records its dispositions and
 reads them next time.
@@ -549,8 +550,9 @@ flowchart TD
     daDedupe{"New finding, proven<br/>on both sides?"}
     daDedupe -.->|"none left"| daQuiet
     daDedupe -->|"some"| daFile
-    daFile("One issue with<br/>evidence per finding") --> daReport
-    daReport(("Filed<br/>labelled docs-audit and refine,<br/>sized and split per finding"))
+    daFile("Report of every finding,<br/>plus one story per top 3") --> daMeasure
+    daMeasure("conclude (rung 6)<br/>each body measured with<br/>refine's rule, trimmed to fit") --> daReport
+    daReport(("Filed<br/>report: docs-audit, not refine<br/>stories: refine, sub-issues"))
     daQuiet(("Nothing to file<br/>the documentation is current"))
     daIdle(("Idle<br/>no agent, no spend"))
 
@@ -560,7 +562,7 @@ flowchart TD
     classDef idle fill:#202c40,stroke:#738198,stroke-width:2px,color:#ffffff
     classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
     class daStart start
-    class daFacts,daRun,daFile action
+    class daFacts,daRun,daFile,daMeasure action
     class daBack,daMoved,daDedupe decision
     class daIdle idle
     class daReport,daQuiet success
@@ -569,6 +571,8 @@ flowchart TD
 Reports join the audit chain: `audit-close` closes one when its children are closed, and marks it
 `stale-audit` when nobody acted on it, which frees the slot.
 
+It files the way the audit does, through the same `file-audit-issues` step: the report never goes to refine, which refused a single report of every finding once it grew past its size gate. Each top story is filed on its own, labelled `refine`, linked under the report and listed in it.
+
 ---
 
 ## agent-release.md
@@ -652,7 +656,8 @@ flowchart TB
     hkBranch -->|yes| hkDelete("Delete the branch")
     hkBranch -.->|"open PR, human PR,<br/>or the default branch"| hkDigest
     hkDelete --> hkDigest
-    hkDigest("Rewrite one issue:<br/>Needs a human") --> hkEnd
+    hkDigest("Rewrite one issue:<br/>Needs a human") --> hkDependabot
+    hkDependabot("Squash-merge Dependabot PRs<br/>whose checks are all green") --> hkEnd
     hkEnd(("One place to look<br/>instead of four repos"))
 
     classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
@@ -660,7 +665,7 @@ flowchart TB
     classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
     classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
     class hkCron start
-    class hkScan,hkRetry,hkStrand,hkParent,hkDelete,hkDigest,hkStackClose action
+    class hkScan,hkRetry,hkStrand,hkParent,hkDelete,hkDigest,hkStackClose,hkDependabot action
     class hkPark,hkWhy,hkBudget,hkBranch,hkStack,hkStackWait decision
     class hkEnd success
 ```
@@ -681,6 +686,8 @@ held for days after its announcement, a root closed by accident with children op
 root pull request each get one line in the digest. No labels move, so nothing the router listens
 for is raised by the sweep itself.
 
+The last step merges Dependabot's updates through the `merge-dependabot` action: only pull requests Dependabot opened with every commit verified and its own, squash-merged once every check is green, a stale one asked once to rebase, a failing one listed in the job summary. It reads nothing of the pull request but the API, and `DEPENDABOT_MERGE` sets its scope. See `docs/dependabot-merge.md` in the package.
+
 ---
 
 ## agentics-app-errors

package/loops/templates/ci/app-ci-dotnet-next.yml

@@ -963,6 +963,9 @@ jobs:
   # If a deploy pipeline calls this workflow with `uses:`, that caller must also grant
   # `actions: write`. A called workflow may not request a scope its caller withheld, and the
   # whole run fails to start with zero jobs and no annotation when it does.
+  #
+  # Not for Dependabot: its runs get a read-only token, so the dispatch would fail its pull request,
+  # and the router's maintenance run merges Dependabot updates instead of the train.
   dispatch-merge-gate:
     name: Dispatch merge gate
     needs: [api, mutation-api, web, mutation-web, secret-scan, deps-and-iac-scan, sast-scan, sbom, engineering-excellence, platform-conformance, full-ci]
@@ -972,6 +975,7 @@ jobs:
       github.event_name == 'pull_request' &&
       github.event.pull_request.head.repo.full_name == github.repository &&
       github.event.pull_request.draft == false &&
+      github.event.pull_request.user.login != 'dependabot[bot]' &&
       (github.event.pull_request.user.login == 'app/github-actions' || endsWith(github.event.pull_request.user.login, '[bot]'))
     runs-on: ${{ vars.CI_RUNNER || 'agents-arc' }}
     timeout-minutes: 5