docs(fleet-triage): design for org-wide PR/issue triage routine

[asachs01]

Design doc only — no workflow or script changes.

Why now

Survey of org automation on 2026-08-17 found two silent absence-of-signal failures running concurrently:

1. dependabot-janitor has been disabled_manually since 2026-07-21 — 27 days, 241 open Dependabot PRs — and nothing alerted on the gap. It produced zero failed runs because it produced zero runs.
2. dependabot-backlog.md, which dependabot-janitor.sh writes and whose comments name a downstream weekly digest routine as its consumer, 404s on main. It has never been committed.

Neither is reachable by hardening the merge policy, which is where all prior effort went (#28, #36, #38, #23). So liveness is component 1 of the design, not an afterthought.

What this specs

The gaps dependabot-janitor does not cover: liveness/deadman, issue triage (65 open), non-Dependabot PR triage (~175 open), the code-owner-blocked backlog, release decoupling, and agent-authored fixes.

Explicitly not a second merge policy. Dependabot merging stays dependabot-janitor.sh's job; the routine consumes its output buckets rather than re-classifying. That script encodes two production incidents a fresh implementation would re-learn the expensive way.

Findings that need a decision regardless of this doc

• required_status_checks is NULL on 20/20 sampled *-mcp repos. CI passing is enforced nowhere at the branch level. The janitor's gh pr checks read is the only CI gate in the system, and it has been wrong twice (fix(janitor): don't auto-merge grouped/major bumps with no CI to verify them #36, fix(janitor): treat all-skipping CI checks as no-CI, not green #38) with nothing behind it.
• harden(janitor): group classify() reads per-dep bumps (fail-closed) #23 is still a live hole. classify() retains the blanket grep -qiE '\bgroup\b' -> ELIGIBLE title shortcut; fix(janitor): don't auto-merge grouped/major bumps with no CI to verify them #36 added only a downstream guard for grouped PRs with no CI. A grouped PR with green CI still auto-merges on a title match — the node-datto-rmm#46 shape minus the no-CI leg. CONFLICTING; needs a rebase onto post-fix(janitor): don't auto-merge grouped/major bumps with no CI to verify them #36/fix(janitor): treat all-skipping CI checks as no-CI, not green #38 main, not a rewrite.
• harden(janitor): SHA-pin actions/checkout (org-token-handling action) #22 is obsolete and would regress if merged. It pins actions/checkout to v4.3.1; main already SHA-pins v6.0.3 via ci: bump deprecated Node 20 actions to Node 24 versions #24. Recommend closing with a pointer to ci: bump deprecated Node 20 actions to Node 24 versions #24.
• fix(janitor): add cortextos+conduit to dependabot-janitor repo scope #50 is MERGEABLE/CLEAN and ready.

Open questions in the doc

1. The CI-split precondition (task_1786765529531, per fix(janitor): add cortextos+conduit to dependabot-janitor repo scope #50) — the janitor was turned off deliberately. Nothing should re-enable it until this is answered.
2. Code-owner policy for resolving the blocked bucket.
3. Whether a Claude cloud routine can hold a GitHub App installation token — unverified.
4. Run budget across 100 repos.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[asachs01]

Automated review (forge):

Docs-only PR (docs/fleet-triage.md + CHANGELOG), no workflow or script changes, so no runtime risk from merging this directly. Read the full doc, not just the description.

Content quality: well-scoped design doc. The explicit non-goal ("not a second merge policy — consumes dependabot-janitor's output buckets rather than re-classifying") is the right constraint and is reinforced later in the trust-model section with a concrete reason (two production incidents, #36/#38, that a fresh implementation would re-learn). The liveness-first framing is well-justified: a 27-day silent gap with zero failed runs is a real argument that failure-watching alone is insufficient.

Cross-checked its own claims against #54/#55, which I also reviewed:

• The doc's "harden(janitor): group classify() reads per-dep bumps (fail-closed) #23 is still a live hole" and the specific node-datto-rmm#46 shape it describes match fix(janitor): classify grouped PRs per-dependency, fail-closed (supersedes #23) #54's diff and measured numbers (69/108 cross-major grouped PRs) almost exactly — good consistency, this doc was clearly written from the same investigation.
• Doc recommends "fix(janitor): add cortextos+conduit to dependabot-janitor repo scope #50 merge, harden(janitor): SHA-pin actions/checkout (org-token-handling action) #22 close, harden(janitor): group classify() reads per-dep bumps (fail-closed) #23 rebase-and-merge" in the janitor hardening backlog table — consistent with what I found reviewing fix(janitor): add cortextos+conduit to dependabot-janitor repo scope #50 and fix(janitor): classify grouped PRs per-dependency, fail-closed (supersedes #23) #54 directly.
• One thing worth flagging: this doc's rollout order (open question 1 — CI-split precondition — before re-enabling) is consistent with what fix(janitor): add cortextos+conduit to dependabot-janitor repo scope #50's PR body says (task_1786765529531), but I couldn't independently verify that task's current status; that's an operational gap this doc correctly identifies rather than assumes away, so no action needed here, just noting it's still open per the doc's own admission.

CHANGELOG: the added "Added" section is well-formed markdown and doesn't conflict structurally with the existing "Fixed" section below it. Note for awareness (not a blocker): #52, #54 and #55 also each add entries to CHANGELOG.md's Unreleased section — four of the five PRs touch this file, so expect routine markdown merge conflicts on ordering/adjacency regardless of merge order (trivial to resolve, unlike the dependabot-janitor.sh collision below).

Collision note (for completeness, doesn't apply to this PR's own mergeability): #50, #54 and #55 independently edit .github/scripts/dependabot-janitor.sh from the same base commit — whichever lands first will likely conflict out the other two. This PR is unaffected since it touches no shared script.

Verdict: safe to merge as written.