feat(meta): CTL-2266 — Mergify merge queue config + labels for catalyst

[ryanrozich]

Summary

Phases 2–3 of the CTL-2266 plan — extends the catalyst-cloud Mergify merge-queue trial to coalesce-labs/catalyst. Phase 1 (the monotonic version guard) already merged as #4077, so AC2's silent version-collision case is already covered by check-versions on main — this PR does not touch that logic again.

• Phase 2 — queue:ready and hold:hand-steps labels created on the repo (colors/descriptions match the catalyst-cloud trial); AGENTS.md documents queue-merge as the PR default once activated.
• Phase 3 — .mergify.yml, validated and simulated against real open PRs below.

This PR does not activate the queue and is not merged by the queue itself (it touches .mergify.yml, which the config's own path exclusion routes to hand-merge). The coordinator merges this by hand, then runs the live @Mergifyio probe per plan Phase 4 — Ryan has already activated the repo in the Mergify dashboard.

One deliberate deviation from the plan: max_parallel_checks: 3

The plan as researched specified max_parallel_checks: 1 (in-place checks, matching the catalyst-cloud shape). Per Ryan's direction from today's catalyst-cloud experience, this PR ships with max_parallel_checks: 3 instead.

Measured caveat, not fixed by this PR: gh api repos/coalesce-labs/catalyst/rulesets/13503799 still reports the "main branch protection" ruleset's required_status_checks.strict_required_status_checks_policy: true (verbatim, re-checked just before opening this PR). Mergify computes allow_inplace_checks automatically, and only enables it when max_parallel_checks == 1 + batch_size == 1 + merge_conditions == queue_conditions for every queue — setting max_parallel_checks: 3 opts OUT of in-place checks, so Mergify will run CI on temporary merge-queue branches instead of pushing update commits onto the PR branch. Separately, with strict_required_status_checks_policy: true, each queued PR's required checks are only valid against the exact current main, so real parallel throughput still needs that ruleset setting turned off — otherwise batches serialize behind rebase-and-recheck regardless of the configured slot count.

I have not touched branch protection — that's explicitly out of scope for me per the dispatch instructions; it's a call for Ryan. The config comments in .mergify.yml spell this out inline so it isn't only in this PR description.

Validation

mergify config validate

$ mergify config validate -f .mergify.yml
Fetching schema from https://docs.mergify.com…
Configuration file '.mergify.yml' is valid.

mergify config simulate — real open PRs, both polarities

#4070 (CTL-2240, Ryan's own PR, all required + non-required checks green) — real state, no queue:ready label:

### Rule: enqueue when a lane marks a PR ready (queue)
- [ ] `label=queue:ready`
- [ ] any of: [🔀 queue conditions]
  - [ ] all of: [📌 queue conditions of queue rule `default`]
    - [ ] `#review-threads-unresolved = 0` [🛡 GitHub repository ruleset rule `main branch protection`]
    ...
    - [X] `-check-failure=quality`
    - [X] `-draft`
    - [X] `-files~=^\.github/workflows/publish-`
    - [X] `-files~=^\.mergify\.yml$`
    - [X] `-files~=^plugins/dev/scripts/db-migrations/`
    - [X] `-head~=^release-please--`
    - [X] `base=main`
    - [X] all six required checks (success/neutral/skipped)
    - [X] all three non-required always-on gates

Every guard is TRUE except the label — as expected for an unlabeled PR. While testing this (toggling queue:ready on and off on #4070 to get the positive-polarity read, see below), I discovered #4070 genuinely has unresolved Codex P1 review threads right now (#review-threads-unresolved = 0 reads [ ] false) — real, not caused by my testing. That's a live negative-polarity data point for that specific condition, not a config defect: the guard correctly refuses to admit a PR with unresolved review threads. Ryan/coordinator: #4070 is not actually queue:ready-eligible today for that reason, independent of this PR.

#4066 (dependabot/bun/eslint-10.9.1) — I temporarily applied queue:ready (removed immediately after, confirmed back to ["dependencies","javascript"]), to get the positive polarity on a real PR:

$ mergify config simulate -f .mergify.yml https://github.com/coalesce-labs/catalyst/pull/4066
1 rule matches

### ✅ Rule: enqueue when a lane marks a PR ready (queue)
- [X] `-closed` [📌 queue requirement]
- [X] `-conflict` [📌 queue requirement]
- [X] `-draft` [📌 queue requirement]
- [X] `base=main`
- [X] `label=queue:ready`
- [X] any of: [🔀 queue conditions]
  - [X] all of: [📌 queue conditions of queue rule `default`]
    - [X] `#review-threads-unresolved = 0` [🛡 GitHub repository ruleset rule `main branch protection`]
    - [X] all path exclusions, all six required checks, all three non-required gates, all TRUE

Full green — this dependabot PR would actually enter the queue with the label applied. This is the genuine positive control the plan's Phase 3 step 3 asks for (not a list of ticks on a PR that was never going to queue).

#4028 (release-please--branches--main) — real state, read-only, no label change — negative control for the outward-facing exclusion:

- [ ] `-head~=^release-please--`

Confirms the head-branch regex correctly refuses a real release-please PR (this repo has one live right now, since CTL-2263 reinstated release-please — landed on main between this branch's original cut and this rebase; the -head~=^release-please-- exclusion already covers it, no config change needed, matching the plan's "correct under both futures" claim in decision 3).

Required-check population, re-confirmed live

gh api .../commits/<sha>/check-runs on both #4070 and #4066 shows all six ruleset-required contexts plus packaging-gate, skills-gate, check-plugin-manifest-parity, and quality present and green on both — consistent with the plan's check-population table.

What's not in this PR

• Queue activation (Ryan's one Mergify-dashboard click, plan Phase 4).
• The first end-to-end live merge and post-merge trigger verification (Phase 4, after activation).
• Negative-control drills (Phase 5) — path-exclusion refusal, hold:hand-steps refusal, pause behavior — run live after activation.
• Any change to branch-protection / the ruleset's strict_required_status_checks_policy — that's Ryan's call, not made here.

Linear

CTL-2266 → In Review.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-08-28T22:09:41.494447Z	c7003e0	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c7003e00d5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".