@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/drain-labeled-backlog/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: drain-labeled-backlog
+description: "This skill should be used when draining a labeled issue backlog (deferred-scope-out, code-review, type/security) in one cleanup PR. Groups by code area and delegates to soleur:one-shot."
+---
+
+<!-- soleur-cloud-mode:start -->
+**Cloud Mode (Devin):** before pipeline work run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/cloud-detect.sh"`. If `CLAUDE_PLUGIN_ROOT` is unset (cloud exec shells do not export it), resolve the root by IDENTITY, never by script basename: for `d` in `"$HOME/.local/share/devin/cli/plugins/cache"` and `/opt/.devin/plugins`, skip unless `[ -d "$d" ]`, then `MANIFEST="$(find "$d" -path '*/.claude-plugin/plugin.json' -exec grep -l '"name"[[:space:]]*:[[:space:]]*"soleur"' {} + 2>/dev/null | head -1)"`, `ROOT="${MANIFEST%/.claude-plugin/plugin.json}"` — one resolution, two consumers: `$ROOT/scripts/cloud-detect.sh` and `$ROOT/scripts/precommit-guard.sh`. (Shape check, not authentication: a planted `{"name":"soleur"}` dir passes — ADR-179 A11.) `local` or `not-local:no-devin-env` proceeds normally; any other `not-local:<reason>` applies `<plugin-root>/devin/INSTRUCTIONS.md` §Cloud Mode: emit the `--banner`, fan out sequentially with `Reviewed-Coverage: sequential-fallback` disclosure (never claim an independent review ran), `message_user` ack before any secrets read or production mutation, and run `precommit-guard.sh` before any `git commit` — hooks do not fire in cloud.
+<!-- soleur-cloud-mode:end -->
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+> **Dynamic-workflow alternative (opt-in).** A [`Workflow`-tool](https://claude.com/blog/introducing-dynamic-workflows-in-claude-code) port of this skill lives at [`workflows/drain-labeled-backlog.workflow.js`](./workflows/drain-labeled-backlog.workflow.js) — deterministic fan-out, journaled resume, schema-validated output. Run it with `Workflow({ scriptPath: "plugins/soleur/skills/drain-labeled-backlog/workflows/drain-labeled-backlog.workflow.js", args: ... })`. The prose skill below stays the default; the two coexist during calibration. See [`knowledge-base/project/specs/archive/20261013-032858-feat-review-workflow-prototype/spec.md`](../../../../knowledge-base/project/specs/archive/20261013-032858-feat-review-workflow-prototype/spec.md). When the workflow ran, post its returned `counts.agent_rounds` via `bash "${CLAUDE_PLUGIN_ROOT}/scripts/pipeline-tally.sh" init` + `incr agent_rounds <n>` — the workflow-return IS the count; do not also incr per dispatch (one writer per dimension, #9403).
+
+# Drain Labeled Backlog
+
+Drain a labeled-issue backlog by batching issues that touch the same code area into a single focused refactor PR. Defaults to `deferred-scope-out` (the original use case, inspired by PR #2486, which closed `#2467 + #2468 + #2469` in one cleanup). Any other label works via `--label` — e.g., `code-review` drains unresolved review findings, `type/security` drains the security backlog.
+
+## When to use
+
+- A labeled backlog has grown and needs a scheduled drain — `deferred-scope-out` (the original use case), `code-review` (unresolved review findings), `type/security` (open security issues), or any label validated by `gh label list`.
+- Multiple open issues carrying the target label reference the same top-level directory (e.g., `apps/web-platform`) and are safe to batch.
+- You want one PR to close 3+ issues instead of N separate PRs.
+
+Use `soleur:review` to file new scope-outs. Use this skill to close existing labeled issues.
+
+<decision_gate>
+**API budget.** This skill delegates each selected cluster to `soleur:one-shot`, which runs a full plan→work→review→ship pipeline (30–90 min wall-clock per cluster; non-trivial Anthropic credit per run scaling with plan complexity and review-cycle count). With `--top-n N`, the cost multiplies by N. The `--dry-run` flag previews scope without delegating. Soleur does not bill or proxy these calls — Anthropic does, against the key in your session. The Soleur LICENSE (BSL 1.1) disclaims warranty for runtime cost; you operate this loop against your own budget.
+
+Confirm cluster scope (size, `--top-n`, milestone) before allowing the skill to fan out.
+</decision_gate>
+
+**Pipeline tally (#9403).** `bash "${CLAUDE_PLUGIN_ROOT}/scripts/pipeline-tally.sh" init` first (merge-safe; pass any `--max-agent-rounds N` from `$ARGUMENTS` through). Before each `soleur:one-shot` dispatch below: `bash "${CLAUDE_PLUGIN_ROOT}/scripts/pipeline-tally.sh" gate agent_rounds` — `STOP` → write `knowledge-base/project/specs/<feature>/session-state.md` (`status: budget-capped` + `budget-capped: agent_rounds=<count>/<cap>` + resume prompt listing remaining clusters) and exit cleanly; `WARN`/`UNKNOWN` → continue. `bash "${CLAUDE_PLUGIN_ROOT}/scripts/pipeline-tally.sh" incr agent_rounds` once per dispatched cluster. Each dispatched one-shot keeps its own ledger on its own branch — this ledger counts only this drain's dispatches. When a dispatch's item branch is known ahead of the child's own `init` (e.g. the `feat-one-shot-<issue>-*` name derivable from the scope arg), attribute the dispatch to it too: `bash "${CLAUDE_PLUGIN_ROOT}/scripts/pipeline-tally.sh" init --branch <item-branch>` FIRST (pre-creates the ledger — `incr` never auto-creates, so a bare `incr --branch` silently drops), then `bash "${CLAUDE_PLUGIN_ROOT}/scripts/pipeline-tally.sh" incr agent_rounds --branch <item-branch>` — the item's PR then carries the dispatch in its tally (branch-isolated: no cross-branch rollup in v1).
+
+## Prerequisites
+
+- `gh` authenticated, `jq` and `python3` available.
+- Current directory is a git worktree (not the bare root).
+- At least one cluster of `min-cluster-size` open issues carrying the target label.
+
+## Arguments
+
+<arguments> #$ARGUMENTS </arguments>
+
+Optional flags (any subset):
+
+- `--label <name>` — which GitHub label drives the backlog query. Default: `deferred-scope-out`. Pass `code-review` to drain unresolved review findings; pass any other label for a custom drain. Validated against `gh label list` before querying so an invalid name fails fast with a readable error rather than a silent empty cluster.
+
+  **`meta/machinery` is excluded from every drain whose `--label` is not itself `meta/machinery`.** The exclusion is explicit in the helper rather than implied by the default: machinery findings are out of a `deferred-scope-out` drain today only because nobody has changed that default, and a future change would silently pull hundreds of findings-about-guards into a drain the operator reads as user-facing work. It is applied as a `jq` filter over the labels the query already returns, **not** as a `-label:` search qualifier — measured 2026-09-10, `gh issue list` silently discards `--search` when `--label` is present, so a query-level exclusion here is a no-op that passes every positive test. Naming `--label meta/machinery` outright lifts the exclusion, which is how the weekly machinery cadence drains that ledger deliberately.
+- `--milestone "<title>"` — which milestone to drain. Default: `Post-MVP / Later` (where 15+ of the open scope-outs live at plan time). Takes the milestone **title**, never a numeric ID — `gh issue create` rejects numeric milestone IDs with a clear error.
+- `--top-n N` — how many clusters to consider. Default: `1`.
+- `--min-cluster-size M` — minimum issues in a cluster before the skill will pick it. Default: `3`.
+- `--dry-run` — print the selected cluster and the one-shot scope argument that would be built, without delegating.
+
+## Workflow
+
+### 1. Prerequisites check
+
+Verify `gh`, `jq`, `python3` are on PATH. If any is missing, abort with installation guidance. Verify the current directory is a git repository with `git -C . rev-parse --git-dir >/dev/null 2>&1` — `git` errors clearly on non-repo paths (`fatal: not a git repository`), so a fail-fast precheck beats a confusing downstream error.
+
+### 2. Resolve milestone
+
+```bash
+MILESTONE="${ARG_MILESTONE:-Post-MVP / Later}"
+```
+
+Default is `Post-MVP / Later`: plan-time verification showed 15+ of the 22 open `deferred-scope-out` issues live there. Defaulting to the current phase milestone would return an empty cluster set on first run and make the skill appear broken.
+
+### 3. Query and group issues
+
+Delegate to the helper [group-by-area.sh](./scripts/group-by-area.sh):
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/drain-labeled-backlog/scripts/group-by-area.sh" \
+  --label "${LABEL:-deferred-scope-out}" \
+  --milestone "$MILESTONE" \
+  --top-n "${N:-1}" \
+  --min-cluster-size "${MIN_CLUSTER:-3}"
+```
+
+The helper:
+
+- Validates the label exists via `gh label list` and the milestone title exists via `gh api ...milestones` + an exact-line `grep -Fx` before querying. Both checks fail fast on invalid input rather than producing a silent empty cluster.
+- Uses two-stage piping (`gh --json ... | jq`), never `gh --jq` with `--arg` (learning `2026-04-15-gh-jq-does-not-forward-arg-to-jq`).
+- Parses each issue body for file paths matching `(ts|tsx|js|jsx|py|rb|go|md|sh|yml|yaml|sql|tf|njk)` extensions via a non-capturing regex.
+- Assigns each issue to an **area** = top two path segments (e.g., `apps/web-platform`, `plugins/soleur`) of its most-referenced file path.
+- Reports ALL clusters sorted by size desc; does not pre-select one.
+- Exits 0 with "No cleanup cluster available" if no area clears the floor.
+
+### 4. Pick a cluster
+
+- **Interactive:** display the top cluster(s) and confirm before proceeding. Allow the user to override with `--area <name>` or pick a different cluster from the listed output.
+- **Headless** (pipeline mode — arguments include a path or `--headless`): auto-pick the first cluster (largest) whose `count >= min-cluster-size`. If none meets the floor, the helper already printed "No cleanup cluster available"; exit 0 — do NOT open a low-value PR.
+
+### 5. Build the one-shot scope argument
+
+For the picked cluster, compose a scope string the `one-shot` skill can consume directly. Mention the originating label so the downstream plan frames the work correctly (e.g., "deferred-scope-out backlog" vs. "code-review findings"):
+
+```text
+Drain the <label> backlog for code area <area> by closing
+#<A> + #<B> + #<C> in a single focused refactor PR. Each issue names
+specific files and proposed fixes; fold them all into one change.
+
+Issues:
+  - #<A>: <title>
+    Files: <files parsed from body>
+    Fix: <proposed-fix section from body>
+  - #<B>: ...
+  - #<C>: ...
+
+PR body MUST include `Closes #<A>`, `Closes #<B>`, `Closes #<C>`.
+Reference PR #2486 as the pattern — one PR, three closures.
+```
+
+Pull `## Problem`, `## Proposed Fix`, and `Location:` / file paths from each issue body via `gh issue view <N> --json body`.
+
+### 6. Delegate to one-shot
+
+**Claude:** Skill tool `skill: soleur:one-shot`, args: `<scope argument built above>`. **Grok:** Read `plugins/soleur/skills/one-shot/SKILL.md` in this process (`soleur:one-shot` with that scope) — slash names the skill; it is not a nested tool_use.
+
+`soleur:one-shot` handles worktree creation, plan, deepen, work, review, QA, compound, and ship. This skill does NOT run any lifecycle phases itself — it only assembles scope.
+
+### 7. Report backlog delta
+
+After `one-shot` returns (PR merged), re-query the milestone using the same label:
+
+```bash
+gh issue list --label "${LABEL:-deferred-scope-out}" --state open \
+  --milestone "$MILESTONE" --json number --jq 'length'
+```
+
+Report: `Before: X, After: Y, Closed: Z` and the per-area drain.
+
+### Closing floor (weekly cadence only)
+
+The weekly machinery cadence carries a **closing floor of 20**: a scheduled run
+that closes fewer than 20 FAILS. That floor is what makes the gate net-NEGATIVE
+rather than net-zero — per-PR net-zero, perfectly enforced, holds the backlog at
+its current size forever.
+
+**The floor is gated on candidate supply, and that arm is not optional.** The run
+fails below the floor only when the candidate pool held at least 20 to begin
+with. When the pool is smaller, the run closes every candidate and PASSES,
+reporting:
+
+```
+closed=N of N candidates (floor waived: pool < floor)
+```
+
+Without that arm the floor becomes unsatisfiable-by-construction the moment the
+backlog is actually drained — a scheduled monitor whose steady state on success
+is red, which trains the operator to ignore it. That is the failure this whole
+change exists to remove, so reproducing it inside the fix would be self-defeating.
+
+The waiver is **reported, never silent**: a chronically empty pool must be
+visible rather than indistinguishable from a healthy run.
+
+Both the floor and the waiver line are cited by the runner and its test from a
+single named constant, so the two cannot drift apart.
+
+## Post-merge follow-up — Scheduling
+
+The `soleur:schedule` skill accepts any soleur skill as `--skill <name>` and generates a standalone `.github/workflows/scheduled-<name>.yml`. After merging the PR that ships this skill, schedule a weekly cleanup:
+
+```text
+soleur:schedule create --name weekly-deferred-scope-out-drain \
+  --skill drain-labeled-backlog --cron "0 14 * * 1" --model claude-sonnet-5-5
+```
+
+This turns the skill from a manual cadence tool into a programmatic backlog opener. Tracked as a follow-up issue rather than bundled into this skill, so the skill lands clean.
+
+## Pipeline detection
+
+If `$ARGUMENTS` contains a `RETURN CONTRACT` section (i.e., this skill is being driven by another skill), run headless:
+
+- Skip interactive cluster confirmation — auto-pick the first cluster meeting the floor.
+- Skip `--dry-run` prompts.
+
+Follows the same pattern as `plan`, `review`, and `ship` skills.
+
+## Sharp edges
+
+- The helper skips issues whose bodies name zero file paths. That is intentional — area grouping requires at least one path. If an issue has no paths but belongs to a cluster thematically, add a `Location:` line to its body and re-run.
+- Sub-grouping by second-level directory is NOT implemented (YAGNI). Current backlogs never exceed 10 issues in a single top-level area. If that changes, track as a follow-up issue before adding the branch; don't build for cases that don't exist.
+- `--milestone` takes the title literally (quote it). A numeric ID fails with `milestone 'N' not found` — `gh issue create` rejects numeric milestone IDs with a clear error, so the failure is loud rather than silent.
+- Rule `rf-review-finding-default-fix-inline` governs the opposite direction (new findings default to fix-inline); this skill drains existing scope-outs. The two rules are complementary.
+- When writing a data-reshape shell script that fetches JSON and groups it, default to a single pure-jq pipeline before reaching for python/awk. Multi-language serialization round-trips add dependencies, silent-fallback error paths, and ~2x the LOC without reshape capability jq already provides.
+- `jq scan(...)` returns the **captured group** when the regex contains a capture, otherwise the full match. Alternations inside `scan` MUST be non-capturing: `(?:ts|tsx|js)` not `(ts|tsx|js)`. Otherwise `scan("[A-Za-z_./\\-]+\\.(?:ts|js)\\b")` returns full paths, whereas the capturing form would return just the extension.
+- When binding `as` against a **multi-value** jq source (e.g., `.[] | select(...)`), the downstream expression runs once per yielded value, producing multiple top-level JSON outputs. This breaks callers that do `$(jq '.field' <<<"$VAR")` under `[[ -eq 0 ]]`. Collect into an array first: `[ .[] | select(...) ] as $meets | { ... }`.
+- Sub-agent confirmation gates (like the second-reviewer gate in `review/SKILL.md`) need a **mechanical first-line output contract** (`CONCUR` / `DISSENT: <reason>`), not free-form prose interpretation. Treat anything other than `CONCUR` as `DISSENT` to fail-safe toward fix-inline.
+- Per-issue "top path" ranking is **qualified-over-bare, deepest-first, frequency tie-break**. Review bodies typically cite one fully-qualified path (`apps/web-platform/components/chat/chat-input.tsx:107-127`) and then shorthand the rest (`chat-input.tsx:17-19, 58, 120-124`). Ranking by frequency alone lets shorthand outvote the qualified citation and produces singleton clusters keyed by bare filename. Ranking by depth alone lets a shallow shorthand `server/ws-handler.ts` beat a deep `apps/web-platform/server/rate-limiter.ts`. The combined rule handles both. Regression-tested in `shorthand-refs.json` (T8) and `mixed-depth.json` (T9).
+- When the top cluster has **≥7 issues from ≥3 unrelated source PRs**, operator sub-selection beats "pick top cluster, delegate whole thing". The natural coherence heuristic is **originating review PR** — three scope-outs filed from the same review (same `Ref #NNNN` in their bodies) are almost always tight siblings, regardless of which subdirectory each path lives under. First dogfood run (PR #2499) hit this at `apps/web-platform` (9 issues spanning kb/chat/billing/analytics); operator read bodies and delegated a coherent 3-issue subset from the same originating review. See `knowledge-base/project/learnings/2026-04-17-cleanup-scope-outs-sub-cluster-selection.md`.
+
+## Test
+
+Unit tests live at [drain-labeled-backlog.test.sh](../../test/drain-labeled-backlog.test.sh). Run them with:
+
+```bash
+bash plugins/soleur/test/drain-labeled-backlog.test.sh
+```
+
+Covers: clustered fixtures, dispersed fixtures (no cluster), empty fixtures, JSON output shape, and sort order.

package/skills/drain-labeled-backlog/scripts/group-by-area.sh

@@ -0,0 +1,208 @@
+#!/usr/bin/env bash
+# Queries open issues carrying a given label, parses file paths from their
+# bodies, groups issues by top-level directory ("code area"), and reports
+# clusters sorted by size descending.
+#
+# Usage:
+#   group-by-area.sh [--label <name>] [--milestone <title>] [--top-n N]
+#                    [--min-cluster-size M] [--format text|json]
+#                    [--fixture <path>]
+#
+# --label defaults to `deferred-scope-out` (the original use case). Any other
+# GitHub label works — e.g., `code-review` drains unresolved review findings
+# rather than deferred ones.
+# --fixture is test-only: reads the issue JSON from a file instead of `gh`.
+
+set -euo pipefail
+
+LABEL="deferred-scope-out"
+# Excluded from every drain whose --label is not itself this value (see the
+# query below). Named once so the guard and its test cannot drift apart.
+MACHINERY_LABEL="meta/machinery"
+MILESTONE="Post-MVP / Later"
+TOP_N=0           # 0 = all clusters
+MIN_CLUSTER_SIZE=3
+FORMAT="text"
+FIXTURE=""
+
+usage() {
+  cat <<'EOF'
+Usage: group-by-area.sh [--label <name>] [--milestone <title>] [--top-n N]
+                        [--min-cluster-size M] [--format text|json]
+                        [--fixture <path>]
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --label)             LABEL="$2";            shift 2 ;;
+    --milestone)         MILESTONE="$2";        shift 2 ;;
+    --top-n)             TOP_N="$2";            shift 2 ;;
+    --min-cluster-size)  MIN_CLUSTER_SIZE="$2"; shift 2 ;;
+    --format)            FORMAT="$2";           shift 2 ;;
+    --fixture)           FIXTURE="$2";          shift 2 ;;
+    -h|--help)           usage; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+[[ -n "$LABEL" ]] \
+  || { echo "Error: --label must be non-empty" >&2; exit 2; }
+
+# Validate numeric args before they reach jq --argjson or bash arithmetic.
+[[ "$TOP_N" =~ ^[0-9]+$ ]] \
+  || { echo "Error: --top-n must be a non-negative integer (got: $TOP_N)" >&2; exit 2; }
+[[ "$MIN_CLUSTER_SIZE" =~ ^[0-9]+$ ]] \
+  || { echo "Error: --min-cluster-size must be a non-negative integer (got: $MIN_CLUSTER_SIZE)" >&2; exit 2; }
+[[ "$FORMAT" == "text" || "$FORMAT" == "json" ]] \
+  || { echo "Error: --format must be 'text' or 'json' (got: $FORMAT)" >&2; exit 2; }
+
+command -v jq >/dev/null 2>&1 || { echo "jq not available" >&2; exit 2; }
+
+# Fetch issue JSON (either live via gh or from a fixture file for tests).
+if [[ -n "$FIXTURE" ]]; then
+  [[ -f "$FIXTURE" ]] || { echo "Fixture not found: $FIXTURE" >&2; exit 2; }
+  ISSUES_JSON="$(cat "$FIXTURE")"
+else
+  command -v gh >/dev/null 2>&1 || { echo "gh CLI not available" >&2; exit 2; }
+
+  # Validate milestone title exists before querying (fail fast).
+  # gh milestone flags take the title, not numeric ID — rule
+  # cq-gh-issue-create-milestone-takes-title.
+  if ! grep -Fxq "$MILESTONE" \
+        < <(gh api "repos/:owner/:repo/milestones?state=open&per_page=100" --jq '.[].title' 2>/dev/null); then
+    echo "Error: milestone title '$MILESTONE' not found (open milestones only)" >&2
+    exit 2
+  fi
+
+  # Validate label exists before querying (rule cq-gh-issue-label-verify-name).
+  # `gh label list` returns tab-separated name<TAB>description<TAB>color; match
+  # the first column exactly.
+  if ! grep -Fxq "$LABEL" \
+        < <(gh label list --limit 200 2>/dev/null | awk -F'\t' '{print $1}'); then
+    echo "Error: label '$LABEL' not found in repo" >&2
+    exit 2
+  fi
+
+  # Two-stage piping: gh --json ... | jq. Never single-stage `gh --jq` with
+  # `--arg`, which silently drops flags (learning 2026-04-15).
+  # The machinery ledger is excluded from every user-facing drain EXPLICITLY,
+  # never by accident of the default label. `/drain` defaults to
+  # `deferred-scope-out`, so `meta/machinery` is out of scope today only
+  # because nobody has changed that default -- a future change would silently
+  # pull hundreds of findings-about-guards into a drain the operator reads as
+  # user-facing work. The exclusion lifts only when the operator names the
+  # label outright, which is how the weekly machinery cadence drains it.
+  #
+  # WHY A jq POST-FILTER AND NOT A QUERY QUALIFIER. Measured 2026-09-10
+  # against this repo, `gh issue list` SILENTLY DISCARDS `--search` when
+  # `--label` is also passed: the self-exclusion control
+  #   gh issue list --label deferred-scope-out --search '-label:"deferred-scope-out"'
+  # returned the full 200 rather than 0. Dropping `--label` in favour of a
+  # pure `--search` fails the same control the same way -- `gh issue list`
+  # does not route through the search API. (The REST search endpoint DOES
+  # honour `-label:`, which is what makes the `gh issue list` behaviour a
+  # trap rather than a platform limit.) A query-level exclusion here would
+  # therefore have been a no-op that looked correct in any positive test,
+  # because a positive test passes whether or not the filter binds. The
+  # labels array is already materialised by `--json labels`, so filtering
+  # here costs nothing and is authoritative -- it is also immune to GitHub
+  # Search's eventual-consistency window on a freshly-applied label.
+  ISSUES_JSON="$(gh issue list \
+    --label "$LABEL" --state open \
+    --milestone "$MILESTONE" \
+    --json number,title,body,labels --limit 200)"
+  if [[ "$LABEL" != "$MACHINERY_LABEL" ]]; then
+    ISSUES_JSON="$(jq -c --arg m "$MACHINERY_LABEL" \
+      '[.[] | select([.labels[].name] | index($m) | not)]' <<<"$ISSUES_JSON")"
+  fi
+fi
+# The kill-switch labels are excluded for EVERY --label, the machinery one
+# included: the standing weekly measurement issue is machinery AND `keep-open`,
+# so a machinery drain that honoured only the exclusion above would close its
+# own measurement surface. Applied after the fetch/fixture fork so the fixture
+# path exercises the same filter. `keep-open` is the sweeper's kill-switch
+# (`KILLSWITCH_LABELS` in cron-stale-deferred-scope-outs.ts); the drain and
+# measurement line 1d honour the same label (#8076).
+ISSUES_JSON="$(jq -c \
+  '[.[] | select([.labels[].name] | (index("keep-open") or index("do-not-autoclose")) | not)]' <<<"$ISSUES_JSON")"
+
+# Single pure-jq pipeline: parse file paths from each issue body, pick the
+# "top" path per issue, derive its "area" (top two path segments). Ranking:
+#   1. Qualified paths (containing "/") outrank bare filenames — shorthand
+#      refs like `chat-input.tsx:17` must not beat the qualified
+#      `apps/web-platform/components/chat/chat-input.tsx:107`.
+#   2. Among qualified paths, deepest wins — a 5-segment
+#      `apps/web-platform/server/rate-limiter.ts` outranks a 2-segment
+#      `server/ws-handler.ts` in the same body, since issue authors
+#      typically give one fully-qualified citation and shorthand the rest.
+#   3. Ties broken by frequency.
+#   4. Fall back to bare filenames only when no qualified path exists.
+# Non-capturing extension regex so `scan` returns full matches, not
+# captured extensions.
+CLUSTERS_JSON="$(jq '
+  [ .[] as $i
+    | ($i.body // "")
+    | [ scan("[A-Za-z0-9_./\\-]+\\.(?:ts|tsx|js|jsx|py|rb|go|md|sh|yml|yaml|sql|tf|njk)\\b") ]
+      as $paths
+    | select(($paths | length) > 0)
+    | ([ $paths[] | select(contains("/")) ]) as $qualified
+    | ( if ($qualified | length) > 0
+        then ($qualified
+              | group_by(.)
+              | max_by([(.[0] | split("/") | length), length])
+              | .[0])
+        else ($paths | group_by(.) | max_by(length) | .[0])
+        end ) as $top
+    | ($top | split("/")) as $parts
+    | ( if ($parts | length) >= 2
+        then "\($parts[0])/\($parts[1])"
+        else $parts[0]
+        end ) as $area
+    | { area: $area, issue: { number: $i.number, title: $i.title } }
+  ]
+  | group_by(.area)
+  | map({ area: .[0].area, count: length, issues: (map(.issue)) })
+  | sort_by(-.count)
+' <<<"$ISSUES_JSON")"
+
+# Partition clusters into picked / other / below based on --top-n and
+# --min-cluster-size. Produces a single object the rest of the script reads.
+PARTITIONED="$(jq --argjson m "$MIN_CLUSTER_SIZE" --argjson n "$TOP_N" '
+  [ .[] | select(.count >= $m) ] as $meets
+  | {
+      picked: (if $n > 0 then $meets[:$n] else $meets end),
+      other:  (if $n > 0 then $meets[$n:] else []     end),
+      below:  [ .[] | select(.count <  $m) ]
+    }
+' <<<"$CLUSTERS_JSON")"
+
+# No cluster meets floor → clean exit 0 with message.
+if [[ "$(jq '.picked | length' <<<"$PARTITIONED")" -eq 0 ]]; then
+  echo "No cleanup cluster available; backlog is distributed across too many areas (min-cluster-size=$MIN_CLUSTER_SIZE)."
+  exit 0
+fi
+
+if [[ "$FORMAT" == "json" ]]; then
+  jq '.picked' <<<"$PARTITIONED"
+  exit 0
+fi
+
+# Text format: picked clusters in detail, then other clusters (summary) and
+# below-floor clusters (why they weren't picked) for operator context.
+jq -r '
+  .picked[] |
+  "Cluster: \(.area)  [\(.count) issues]",
+  (.issues[] | "  #\(.number): \(.title)"),
+  ""
+' <<<"$PARTITIONED"
+
+if [[ "$(jq '.other | length' <<<"$PARTITIONED")" -gt 0 ]]; then
+  echo "--- Other clusters (not selected by --top-n=$TOP_N) ---"
+  jq -r '.other[] | "  \(.area)  [\(.count) issues]"' <<<"$PARTITIONED"
+fi
+
+if [[ "$(jq '.below | length' <<<"$PARTITIONED")" -gt 0 ]]; then
+  echo "--- Below min-cluster-size=$MIN_CLUSTER_SIZE (not picked) ---"
+  jq -r '.below[] | "  \(.area)  [\(.count) issues]"' <<<"$PARTITIONED"
+fi