@soleur/opencode 0.0.0-stage → 3.354.2

package/skills/drain-labeled-backlog/workflows/drain-labeled-backlog.workflow.js

@@ -0,0 +1,433 @@
+export const meta = {
+  name: 'drain-labeled-backlog-workflow',
+  description:
+    'Workflow-backed soleur:drain-labeled-backlog — query open issues for a label/milestone, cluster by code area (qualified-over-bare, deepest-first, frequency tie-break), then pipeline() each picked cluster: stage 1 builds a scoped one-shot brief from issue bodies, stage 2 delegates the cluster to /soleur:one-shot. Respects --top-n and --dry-run.',
+  // Same phase titles as the phase() calls below so progress groups line up.
+  phases: [
+    { title: 'Cluster', detail: 'one agent validates label/milestone and groups open issues by code area' },
+    { title: 'Confirm', detail: 'apply --top-n / --min-cluster-size floor; dry-run stops here' },
+    { title: 'Drain', detail: 'pipeline: build a scoped brief per cluster, then delegate each to /soleur:one-shot' },
+    { title: 'Report', detail: 're-query the milestone for the backlog delta (before/after/closed)' },
+  ],
+}
+
+// ===========================================================================
+// API-BUDGET DISCLOSURE (mirrors SKILL.md §decision_gate, per
+// hr-autonomous-loop-skill-api-budget-disclosure).
+//
+// This workflow delegates EACH picked cluster to `/soleur:one-shot`, which runs
+// a full plan → deepen → work → review → QA → compound → 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: ONE full one-shot fans out PER PICKED CLUSTER, so N clusters
+// = N one-shots = N×(the agents one-shot itself spawns). Anthropic bills every
+// one of those agents against the key in your session — Soleur neither bills nor
+// proxies them. The Soleur LICENSE (BSL 1.1) disclaims warranty for runtime
+// cost; you operate this loop against your own budget.
+//
+// The --dry-run flag previews the picked clusters and the one-shot scope
+// argument that WOULD be built, delegating nothing. CONFIRM cluster scope
+// (size, --top-n, milestone) before allowing the workflow to fan out.
+// ===========================================================================
+
+// ---------------------------------------------------------------------------
+// Input. args may be a bare string (the label) or an object:
+//   { label, milestone, topN, minClusterSize, dryRun }
+//   label:          GitHub label driving the backlog query (default below)
+//   milestone:      milestone TITLE to drain (never a numeric id — gh rejects it)
+//   topN:           how many clusters to consider / delegate (default 1)
+//   minClusterSize: minimum issues in a cluster before it is picked (default 3)
+//   dryRun:         preview picked clusters + scope; delegate nothing
+// A bare string is treated as the label.
+// ---------------------------------------------------------------------------
+const DEFAULT_LABEL = 'deferred-scope-out'
+const DEFAULT_MILESTONE = 'Post-MVP / Later' // 15+ of 22 open scope-outs live here at plan time; the current-phase milestone would return an empty cluster set on first run.
+const DEFAULT_TOP_N = 1
+const DEFAULT_MIN_CLUSTER = 3
+
+const label = (typeof args === 'string' ? args : args?.label) || DEFAULT_LABEL
+const milestone = (typeof args === 'object' && args?.milestone) || DEFAULT_MILESTONE
+const topN = Math.max(1, Number((typeof args === 'object' && args?.topN) || DEFAULT_TOP_N) | 0)
+const minClusterSize = Math.max(1, Number((typeof args === 'object' && args?.minClusterSize) || DEFAULT_MIN_CLUSTER) | 0)
+const dryRun = typeof args === 'object' && !!args?.dryRun
+
+// ---------------------------------------------------------------------------
+// Harden untrusted text before it reaches a shell argv. The label and milestone
+// flow into `gh` invocations the cluster/report agents run; issue titles flow
+// into the one-shot brief. Strip control chars + shell metacharacters, collapse
+// whitespace, cap length. Leading "-" is stripped so a value can never smuggle a
+// flag into gh. Mirrors the template's safeTitle().
+// ---------------------------------------------------------------------------
+function safeArg(raw) {
+  return String(raw)
+    .replace(/[\x00-\x1f\x7f]/g, ' ') // control chars incl. newlines
+    .replace(/[`$"'\\;|&<>(){}[\]!*?~#]/g, ' ') // shell metacharacters, backslash, brackets
+    .replace(/\s+/g, ' ')
+    .replace(/^-+/, '') // no leading dash → cannot be read as a gh flag
+    .trim()
+    .slice(0, 200)
+}
+
+const safeLabel = safeArg(label)
+const safeMilestone = safeArg(milestone)
+
+// ---------------------------------------------------------------------------
+// Budget. Each delegated cluster is a full one-shot — by far the expensive part.
+// Floor the remaining budget before each fan-out so we never start a one-shot we
+// cannot afford to let run, and NEVER silently skip — log dropped clusters.
+// ---------------------------------------------------------------------------
+const ONE_SHOT_FLOOR = 200_000 // output tokens to reserve for one full one-shot run
+const droppedClusters = []
+
+function budgetOk() {
+  return !budget.total || budget.remaining() > ONE_SHOT_FLOOR
+}
+
+// ---------------------------------------------------------------------------
+// Schemas — validated at the tool-call layer, so agents retry on mismatch.
+// additionalProperties:false everywhere; agents return DATA, not prose.
+// ---------------------------------------------------------------------------
+
+// Stage 0: cluster the backlog. Faithful port of group-by-area.sh — the agent
+// runs the same gh queries + jq grouping and returns the structured clusters.
+const CLUSTERS_SCHEMA = {
+  type: 'object',
+  required: ['labelValid', 'milestoneValid', 'totalOpen', 'clusters'],
+  additionalProperties: false,
+  properties: {
+    labelValid: { type: 'boolean', description: 'label exists per `gh label list` (first column exact match)' },
+    milestoneValid: { type: 'boolean', description: 'milestone TITLE exists per `gh api .../milestones` (open milestones)' },
+    totalOpen: { type: 'integer', description: 'count of open issues carrying the label in the milestone' },
+    error: { type: 'string', description: 'set when labelValid or milestoneValid is false; a readable fail-fast message' },
+    clusters: {
+      type: 'array',
+      description: 'ALL clusters sorted by count desc; NOT pre-filtered by min-cluster-size',
+      items: {
+        type: 'object',
+        required: ['area', 'count', 'issues'],
+        additionalProperties: false,
+        properties: {
+          area: { type: 'string', description: 'top two path segments of the issue cluster (e.g. apps/web-platform)' },
+          count: { type: 'integer' },
+          issues: {
+            type: 'array',
+            items: {
+              type: 'object',
+              required: ['number', 'title'],
+              additionalProperties: false,
+              properties: {
+                number: { type: 'integer' },
+                title: { type: 'string' },
+                files: { type: 'array', items: { type: 'string' }, description: 'file paths parsed from the issue body' },
+                problem: { type: 'string', description: 'the issue body ## Problem section (verbatim or trimmed)' },
+                proposedFix: { type: 'string', description: 'the issue body ## Proposed Fix section (verbatim or trimmed)' },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+}
+
+// Stage 1: assemble the one-shot scope string for a single picked cluster.
+const BRIEF_SCHEMA = {
+  type: 'object',
+  required: ['area', 'issueNumbers', 'scope'],
+  additionalProperties: false,
+  properties: {
+    area: { type: 'string' },
+    issueNumbers: { type: 'array', items: { type: 'integer' } },
+    scope: { type: 'string', description: 'the full scope argument to hand to /soleur:one-shot (includes Closes #N lines)' },
+  },
+}
+
+// Stage 2: outcome of delegating a cluster to /soleur:one-shot.
+const ONE_SHOT_RESULT_SCHEMA = {
+  type: 'object',
+  required: ['area', 'status'],
+  additionalProperties: false,
+  properties: {
+    area: { type: 'string' },
+    status: { type: 'string', enum: ['merged', 'pr-open', 'failed'], description: 'merged = PR landed and closed the issues; pr-open = PR raised but not merged; failed = one-shot aborted' },
+    prUrl: { type: 'string' },
+    prNumber: { type: 'integer' },
+    closedIssues: { type: 'array', items: { type: 'integer' } },
+    notes: { type: 'string' },
+  },
+}
+
+// Stage 3 (report): the post-drain backlog delta for the milestone.
+const DELTA_SCHEMA = {
+  type: 'object',
+  required: ['after'],
+  additionalProperties: false,
+  properties: {
+    after: { type: 'integer', description: 'open issues carrying the label in the milestone, re-queried after the drain' },
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Prompt builders. Each names the EXACT gh/jq mechanics from group-by-area.sh
+// so the agent reproduces the helper's behavior deterministically.
+// ---------------------------------------------------------------------------
+const clusterPrompt = `You are the backlog-clustering gate for a labeled-issue drain. Reproduce the logic of plugins/soleur/skills/drain-labeled-backlog/scripts/group-by-area.sh EXACTLY — prefer running that script if it is present.
+
+Label:     "${safeLabel}"
+Milestone: "${safeMilestone}"   (this is a TITLE, never a numeric id)
+
+Steps (fail fast, fail readable):
+1. Validate the milestone TITLE exists among OPEN milestones:
+   gh api "repos/:owner/:repo/milestones?state=open&per_page=100" --jq '.[].title' | grep -Fxc "${safeMilestone}" >/dev/null
+   If absent → milestoneValid=false, set error, return (do NOT query issues).
+2. Validate the label exists (first column of \`gh label list\`):
+   gh label list --limit 200 | awk -F'\\t' '{print $1}' | grep -Fxc "${safeLabel}" >/dev/null
+   If absent → labelValid=false, set error, return.
+3. Query open issues (two-stage piping — gh --json … | jq; never \`gh --jq\` with --arg):
+   gh issue list --label "${safeLabel}" --state open --milestone "${safeMilestone}" --json number,title,body,labels --limit 200
+4. For each issue body, scan file paths with the NON-CAPTURING extension regex
+   [A-Za-z0-9_./\\-]+\\.(?:ts|tsx|js|jsx|py|rb|go|md|sh|yml|yaml|sql|tf|njk)\\b
+   Skip issues whose body names ZERO paths (area grouping requires a path).
+5. Pick each issue's TOP path: qualified paths (containing "/") outrank bare
+   filenames; among qualified, DEEPEST (most path segments) wins; ties broken by
+   frequency; fall back to bare filenames only if no qualified path exists.
+6. area = top TWO path segments of the top path (e.g. apps/web-platform), or the
+   single segment if only one.
+7. Group issues by area; return ALL clusters sorted by count DESC. Do NOT
+   pre-filter by min-cluster-size — the workflow applies that floor itself.
+8. For each issue also extract its body "## Problem" and "## Proposed Fix"
+   sections and its parsed file paths, so a downstream brief can cite them.
+
+Set totalOpen to the count of open labeled issues in the milestone. Return the structured object only — do not delegate or open any PR.`
+
+function briefPrompt(cluster) {
+  const issuesBlock = cluster.issues
+    .map(
+      (i) =>
+        `  - #${i.number}: ${i.title}\n    Files: ${(i.files || []).join(', ') || '(none parsed)'}\n    Problem: ${i.problem || '(see issue body)'}\n    Fix: ${i.proposedFix || '(see issue body)'}`,
+    )
+    .join('\n')
+  const closes = cluster.issues.map((i) => `Closes #${i.number}`).join('\n')
+  return `You are assembling the scope argument for /soleur:one-shot to drain a labeled backlog cluster in ONE focused refactor PR. Return DATA only — do NOT invoke one-shot or open a PR.
+
+Cluster area: ${cluster.area}   (${cluster.count} issues)
+Originating label: ${safeLabel}
+
+Pull the freshest "## Problem", "## Proposed Fix", and Location:/file paths for each issue via \`gh issue view <N> --json body\` if you need more than what is given below.
+
+Issues in this cluster:
+${issuesBlock}
+
+Build a scope string in EXACTLY this shape (frame the work by the originating label — "${safeLabel} backlog"):
+
+  Drain the ${safeLabel} backlog for code area ${cluster.area} by closing
+  ${cluster.issues.map((i) => `#${i.number}`).join(' + ')} in a single focused refactor PR. Each issue names
+  specific files and proposed fixes; fold them all into one change.
+
+  Issues:
+${issuesBlock}
+
+  PR body MUST include these literal lines so merging closes every issue:
+${closes}
+  Reference PR #2486 as the pattern — one PR, multiple closures.
+
+Return: area, the issueNumbers array, and the assembled scope string.`
+}
+
+function oneShotPrompt(brief) {
+  return `Delegate this cluster to the full autonomous engineering pipeline. Use the Skill tool to invoke \`soleur:one-shot\` with the scope argument below as its args.
+
+/soleur:one-shot owns worktree creation, plan, deepen, work, review, QA, compound, and ship. This step runs NO lifecycle phases itself — it only hands off the scope and reports the outcome.
+
+The PR body MUST carry the \`Closes #<n>\` lines already present in the scope so the merge closes every issue in the cluster (issues: ${brief.issueNumbers.map((n) => `#${n}`).join(', ')}).
+
+Scope argument (pass verbatim as the skill's args):
+---SCOPE START---
+${brief.scope}
+---SCOPE END---
+
+After one-shot returns, report: status (merged / pr-open / failed), the PR url + number, and which issue numbers were closed.`
+}
+
+const reportPrompt = `Re-query the backlog AFTER the drain to compute the delta. Run EXACTLY (two-stage piping):
+
+gh issue list --label "${safeLabel}" --state open --milestone "${safeMilestone}" --json number --jq 'length'
+
+Return only \`after\` = that count. Do not modify any issue.`
+
+// ---------------------------------------------------------------------------
+// Run.
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// ADR-110: semantic tier → harness spawn value. Workflow runtime has no import
+// (same constraint as plan-review named-panel inlining). Source of truth:
+// plugins/soleur/lib/harness-model-map.ts — keep this copy byte-identical.
+// <!-- harness-model-map:start -->
+function resolveWorkflowModel(tier) {
+  var env = (typeof process !== 'undefined' && process.env) ? process.env : {}
+  var claude = !!env.CLAUDECODE
+  var opencode = !claude && !!env.OPENCODE
+  var grok = !claude && !opencode && (env.GROK_HOME || env.GROK_AGENT || env.GROK_DEFAULT_MODEL || env.GROK_SUBAGENTS)
+  var map = grok
+    ? { cheap: 'grok-4.5', standard: 'grok-4.7', strong: 'grok-4.7', advisor: 'grok-4.7', inherit: 'inherit' }
+    : claude
+      ? { cheap: 'haiku', standard: 'sonnet', strong: 'opus', advisor: 'fable', inherit: 'inherit' }
+      : opencode
+        ? { cheap: 'opencode/glm-5.3-flash-free', standard: 'opencode/big-pickle', strong: 'opencode/big-pickle', advisor: 'opencode/big-pickle', inherit: 'inherit' }
+        : { cheap: 'inherit', standard: 'inherit', strong: 'inherit', advisor: 'inherit', inherit: 'inherit' }
+  var resolved = map[tier]
+  if (!resolved) throw new Error('unknown semantic tier: ' + String(tier))
+  return resolved
+}
+;(function (hostAgent) {
+  agent = function agent(prompt, opts) {
+    if (opts && typeof opts.model === 'string') {
+      opts.model = resolveWorkflowModel(opts.model)
+    }
+    return hostAgent(prompt, opts)
+  }
+})(agent)
+// <!-- harness-model-map:end -->
+// ---------------------------------------------------------------------------
+
+phase('Cluster')
+log('tier pins: cluster→standard, report→standard (mechanical steps per ADR-053; brief + one-shot inherit the session model)')
+// Pinned 'standard': issue clustering from a structured list is mechanical (ADR-053).
+const clustered = await agent(clusterPrompt, { label: 'cluster', phase: 'Cluster', schema: CLUSTERS_SCHEMA, model: 'standard' })
+
+// Fail-fast on invalid label/milestone — mirror the helper's exit 2 paths.
+if (!clustered || !clustered.labelValid || !clustered.milestoneValid) {
+  const why = !clustered
+    ? 'clustering agent failed to return'
+    : clustered.error || (!clustered.labelValid ? `label "${safeLabel}" not found in repo` : `milestone title "${safeMilestone}" not found (open milestones only)`)
+  log(`Abort: ${why}`)
+  return {
+    label: safeLabel,
+    milestone: safeMilestone,
+    dryRun,
+    aborted: true,
+    reason: why,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Confirm: apply --min-cluster-size floor, then take the top --top-n. The
+// SCRIPT (not the model) owns selection — the agent reported ALL clusters.
+// ---------------------------------------------------------------------------
+phase('Confirm')
+const meets = (clustered.clusters || []).filter((c) => c.count >= minClusterSize).sort((a, b) => b.count - a.count)
+const picked = meets.slice(0, topN)
+const other = meets.slice(topN)
+const below = (clustered.clusters || []).filter((c) => c.count < minClusterSize)
+
+log(
+  `Label "${safeLabel}" / milestone "${safeMilestone}": ${clustered.totalOpen} open. ` +
+    `${meets.length} cluster(s) ≥ ${minClusterSize}; picking top ${topN} → ${picked.length}. ` +
+    `${other.length} other, ${below.length} below floor.`,
+)
+
+// No cluster clears the floor → clean stop. Do NOT open a low-value PR.
+if (picked.length === 0) {
+  log(`No cleanup cluster available; backlog is distributed across too many areas (min-cluster-size=${minClusterSize}).`)
+  return {
+    label: safeLabel,
+    milestone: safeMilestone,
+    minClusterSize,
+    topN,
+    totalOpen: clustered.totalOpen,
+    picked: [],
+    clusters: { meets: meets.length, other: other.length, below: below.length },
+    delegated: 0,
+    message: 'No cleanup cluster available.',
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Drain: pipeline() each picked cluster — NO barrier between brief-build and
+// delegation, so cluster k's one-shot can start the moment its brief lands while
+// cluster k+1's brief is still being assembled. Stage 1 builds the scoped brief;
+// stage 2 hands it to /soleur:one-shot (skipped under --dry-run or budget floor).
+// ---------------------------------------------------------------------------
+phase('Drain')
+let oneShotsDispatched = 0 // #9403: pipeline-tally `counts` surface
+const drainResults = await pipeline(
+  picked,
+  // Stage 1: scoped brief from issue bodies.
+  (cluster) => agent(briefPrompt(cluster), { label: `brief:${cluster.area}`, phase: 'Drain', schema: BRIEF_SCHEMA }),
+  // Stage 2: delegate the cluster to a full one-shot (gated on dry-run + budget).
+  (brief, cluster) => {
+    if (!brief) return { area: cluster.area, status: 'failed', notes: 'brief assembly failed' }
+    if (dryRun) {
+      return {
+        area: brief.area,
+        status: 'dry-run',
+        issueNumbers: brief.issueNumbers,
+        wouldDelegateScope: brief.scope,
+      }
+    }
+    if (!budgetOk()) {
+      droppedClusters.push(brief.area)
+      return {
+        area: brief.area,
+        status: 'skipped-budget',
+        issueNumbers: brief.issueNumbers,
+        notes: `SKIPPED — token budget floor (${ONE_SHOT_FLOOR}) reached; not enough headroom to run a full one-shot for this cluster.`,
+      }
+    }
+    oneShotsDispatched++ // #9403: pipeline-tally counts — the invoking prose posts this via `incr agent_rounds`
+    return agent(oneShotPrompt(brief), { label: `one-shot:${brief.area}`, phase: 'Drain', schema: ONE_SHOT_RESULT_SCHEMA })
+  },
+)
+
+const results = drainResults.filter(Boolean)
+
+// ---------------------------------------------------------------------------
+// Report: re-query the milestone for the backlog delta. Skipped on dry-run
+// (nothing was delegated, so the count is unchanged).
+// ---------------------------------------------------------------------------
+phase('Report')
+let after = null
+if (!dryRun && results.some((r) => r.status === 'merged')) {
+  // Pinned 'standard': markdown report assembly from structured data is mechanical (ADR-053).
+  const delta = await agent(reportPrompt, { label: 'report', phase: 'Report', schema: DELTA_SCHEMA, model: 'standard' })
+  after = delta?.after ?? null
+}
+
+const before = clustered.totalOpen
+const merged = results.filter((r) => r.status === 'merged')
+const closed = after != null ? Math.max(0, before - after) : merged.reduce((n, r) => n + (r.closedIssues?.length || 0), 0)
+
+const summary = {
+  label: safeLabel,
+  milestone: safeMilestone,
+  dryRun,
+  topN,
+  minClusterSize,
+  selection: {
+    totalOpen: before,
+    clustersMeetingFloor: meets.length,
+    pickedCount: picked.length,
+    otherClusters: other.map((c) => ({ area: c.area, count: c.count })),
+    belowFloor: below.map((c) => ({ area: c.area, count: c.count })),
+  },
+  picked: picked.map((c) => ({ area: c.area, count: c.count, issues: c.issues.map((i) => i.number) })),
+  budget: { total: budget.total, spent: budget.spent(), oneShotFloor: ONE_SHOT_FLOOR, droppedClusters },
+  // #9403: pipeline-tally bridge — the invoking prose posts these via
+  // `pipeline-tally.sh incr <dim> <n>`. agent_rounds counts one-shot dispatches
+  // only (brief/cluster/report agents are mechanical spawns, not counted).
+  counts: { agent_rounds: oneShotsDispatched },
+  delegated: dryRun ? 0 : results.filter((r) => r.status === 'merged' || r.status === 'pr-open' || r.status === 'failed').length,
+  results,
+  backlogDelta: { before, after, closed },
+}
+
+if (droppedClusters.length) {
+  log(`⚠ budget floor hit — ${droppedClusters.length} cluster(s) NOT delegated: ${droppedClusters.join(', ')}`)
+}
+log(
+  dryRun
+    ? `Dry-run: ${picked.length} cluster(s) would delegate to /soleur:one-shot (no fan-out). Confirm scope, then re-run without --dry-run.`
+    : `Done: ${merged.length}/${picked.length} cluster(s) merged. Backlog ${before} → ${after ?? '?'} (closed ${closed}).`,
+)
+
+return summary

package/skills/drain-prs/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: drain-prs
+description: "This skill should be used when draining open remote GitHub PRs: triage every open pull request into mergeable tiers, confirm scope with the operator, then fix and merge the green ones. The PR-counterpart to drain-labeled-backlog."
+---
+
+<!-- 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 -->
+
+# Drain PRs
+
+Triage all open **remote** GitHub PRs and drain the mergeable ones in one operator-confirmed pass: enumerate → triage into tiers → **confirm scope** → fix each in-scope PR to green → merge. The PR-counterpart to `drain-labeled-backlog` (which drains labeled *issues*). Distilled from the 2026-06-30 drain session that merged 11 PRs across tiers.
+
+## When to use
+
+- The open-PR backlog has accumulated (dependabot bumps, bot-fixes, stale feature branches) and you want to triage and merge the mergeable ones in one pass.
+- You want a single triage view that separates "ready to merge now" from "needs a lockfile fix / conflict resolution / review" so nothing green sits unmerged and nothing broken merges by accident.
+
+Use `merge-pr` for a single named PR. Use `drain-labeled-backlog` for labeled *issues* (not PRs). Use this skill to drain the open-PR queue.
+
+<decision_gate>
+**Merging is outward-facing — confirm before any merge.** This skill confirms tier scope with the operator via `AskUserQuestion` **before merging anything**, and supports per-PR opt-out within a tier (not just per-tier accept/reject). Confirming a tier means **the selected PRs are squash-merged to `main`** — this is not a preview; it lands code (higher irreversibility than the issue-drain, which ends at PR-opened). Respects `wg-zero-agents-until-user-confirms`.
+
+**API budget.** Fixing or reviewing PRs may delegate to `soleur:review` (feature PRs) and spawn review agents, which run autonomously and spend non-trivial Anthropic credit against the key in your session, scaling with PR count and review-cycle depth. The `--dry-run` flag prints the full tier table with zero merges and zero delegation. Soleur does not bill or proxy these calls — Anthropic does. The Soleur LICENSE (BSL 1.1) disclaims warranty for runtime cost; you operate this loop against your own budget.
+</decision_gate>
+
+## Prerequisites
+
+- `gh` authenticated, `jq` available.
+- Current directory is a git worktree (not the bare root) — fix-recipes that touch files (lockfiles, generated files, stale branches) need a working tree.
+
+## Arguments
+
+<arguments> #$ARGUMENTS </arguments>
+
+Optional flags (any subset):
+
+- `--tiers <list>` — comma-separated tiers to drain (e.g., `ready-green,needs-lockfile-fix`). Default: prompt for tier scope at the decision gate. Tiers: `ready-green`, `needs-lockfile-fix`, `needs-conflict-resolution`, `needs-review`, `broken`, plus `ready-unarmed` (recover-only, never armed). Drafts are always excluded.
+- `--pr <N,…>` — restrict the whole run to an explicit set of PR numbers (still triaged + still gated).
+- `--dry-run` — print the full tier table and exit with zero merges and zero delegation. More valuable here than in the sibling because this skill *merges*.
+
+## Workflow
+
+### 1. Prerequisites check
+
+Verify `gh` and `jq` are on PATH (abort with installation guidance if missing). Verify the current directory is a git repository: `git -C . rev-parse --git-dir >/dev/null 2>&1` — `git` errors clearly on non-repo paths, so a fail-fast precheck beats a confusing downstream error.
+
+### 2. Enumerate + triage
+
+Delegate to the helper [triage-prs.sh](./scripts/triage-prs.sh):
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/drain-prs/scripts/triage-prs.sh"
+```
+
+The helper runs `gh pr list --state open --json number,title,headRefName,isDraft,mergeable,reviewDecision,labels,author,createdAt,statusCheckRollup` (two-stage `gh --json … | jq`, never `gh --jq` with `--arg` — learning `2026-04-15-gh-jq-does-not-forward-arg-to-jq`) and classifies each PR into **seven tiers**:
+
+| Tier | Signal | Default handling |
+|------|--------|------------------|
+| `ready-green` | `mergeable=MERGEABLE`, no failing/pending checks | merge directly |
+| `needs-lockfile-fix` | deps PR (`labels` has `dependencies`) failing `lockfile-sync` / `test-webplat` / `e2e` on a frozen-install step | fix-recipe (a) → merge |
+| `needs-conflict-resolution` | `mergeable=CONFLICTING`, few/no other failures | fix-recipe (b) → merge |
+| `needs-review` | `bot-fix/review-required` label, or a feature PR with no review | review (delegate or inline) → merge |
+| `ready-unarmed` | ready PR whose head verdict (`ci-head-verdict.sh`) is `no-run` or `stalled`: no full CI run exists, the red `test` row is the draft run's. `awaiting-approval` is not here: it lands in `needs-review` (the line shows `ci=awaiting-approval`; a maintainer must approve the fork run) | **recover, never arm**, unless another session is still inside `wait-ready-run` for it: `gh pr ready --undo <N>`, then the whole ready block ([ready-run-wait.md](${CLAUDE_PLUGIN_ROOT}/skills/ship/references/ready-run-wait.md)), then re-triage |
+| `drafts` | `isDraft=true` | **skip** — author-owned WIP, never merged |
+| `broken` | `CONFLICTING` **and** many failing checks | surface; fix only if in explicit scope |
+
+Pass `--dry-run` to stop here and print the table.
+
+### 3. Decision gate (confirm scope)
+
+Present the tier table via `AskUserQuestion`. The operator selects which tiers to drain and may opt individual PRs out within a tier. Nothing merges until this returns. (See the `<decision_gate>` block above for the irreversibility + budget framing.)
+
+### 4. Per in-scope PR — ensure green, then merge
+
+For each selected PR: bring it to green via the fix-recipes below if needed, then arm it (under the merge queue this ENQUEUES the PR; it is not yet merged). A `ready-unarmed` PR (readied, but no full CI run exists) is NOT armed: recover it first (`gh pr ready --undo <N>` with a user token, then the whole block below; `GITHUB_TOKEN` cannot ready a PR). A draft the operator authorizes is readied the same way and armed only once `K=$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/ci-head-verdict.sh" ready-count <N>) && gh pr ready <N> && bash "${CLAUDE_PLUGIN_ROOT}/scripts/ci-head-verdict.sh" wait-ready-run <N> --before-count "$K"` exits 0 (one Bash call, `timeout: 420000`; reasons and recoveries: [ready-run-wait.md](${CLAUDE_PLUGIN_ROOT}/skills/ship/references/ready-run-wait.md)); on non-zero report "readied but unarmed" with the last stdout line and arm nothing:
+
+```bash
+gh pr merge <N> --squash --auto
+```
+
+- **Never arm a cross-repository (fork) PR, or one touching `.github/**`, without explicit operator confirmation.** `merge_group` runs the candidate's workflows in the base-repo context with repo secrets, so a pre-queue-green fork or workflow edit can exfiltrate them before anyone reads a run. Check each PR before arming: `gh pr view <N> --json isCrossRepository --jq .isCrossRepository` and `gh api repos/{owner}/{repo}/pulls/<N>/files --paginate --jq '.[].filename | select(startswith(".github/"))'` (not `gh pr view --json files`: it stops at 100 files, so a large PR could hide a workflow edit); `true` or any output means stop and ask (the tier confirmation at the decision gate does not cover it).
+- **Merge queue is active on `main`** (#9454, ADR-270; the `merge_queue` rule lives in `infra/github/ruleset-ci-required.tf`) — `gh pr merge <N> --squash --auto` **enqueues** the PR (a green PR enqueues, so the bullet and the block above agree); the queue handles the up-to-date merge, serialization and the final merge automatically — do not hand-roll update/wait loops, and never push `gh pr update-branch` or a merge of `origin/main` to a PR that is in the queue (a push dequeues it). An admin-bypass merge (only via [settle-then-admin-merge.md](${CLAUDE_PLUGIN_ROOT}/skills/ship/references/settle-then-admin-merge.md)) is the last resort, not the drain path. CodeQL is advisory on `main` (it reports no status on `merge_group`); the post-merge `codeql-main-alert-gate.yml` run is the signal. History: a first adoption (#5800) was reverted the same day for exactly that reason (ADR-032 amendment, upstream `github/codeql-action#1537`); #5840 stays open as the upstream tracker.
+- **Dequeue arm — a PR that leaves the queue.** When CI is red on the queue's temp ref `gh-readonly-queue/main/pr-<N>-<sha>`, the failing check-run is on the queue SHA, not the PR head, so `gh pr checks <N>` still reads green. Read the run instead: `gh run list --event merge_group --limit 100 --json databaseId,headBranch,conclusion,url --jq '.[] | select(.headBranch | startswith("gh-readonly-queue/main/pr-<N>-"))'`, (about 8 runs per queue entry, so a smaller `--limit` can miss the PR on a busy queue), then diagnose the failing job from that run. The dequeue is silent (a `failed_checks` removal is re-queued by GitHub 2 to 3.5 minutes later while auto-merge normally stays armed; a red advisory job does not dequeue, so do not push over it): the PR stays OPEN, so `gh pr view <N> --json state,autoMergeRequest` reads `OPEN` with auto-merge armed (`autoMergeRequest` set) or disarmed (`null`); section 7's wait names it (`LEFT THE MERGE QUEUE UNMERGED`, reason from the queue's removal event). Recipe: [merge-queue-dequeue.md](${CLAUDE_PLUGIN_ROOT}/skills/ship/references/merge-queue-dequeue.md). On a conflict or lockfile / `kb-index` drift, the local arm is: merge `origin/main` into the PR branch (merge-pr §3.1 "Route conflicts"), push only for a failure that will recur, and re-arm `gh pr merge <N> --squash --auto` only when `autoMergeRequest` is `null` (the recipe's steps 2 and 3 win over any shorter inline recovery text). Cap it at ONE re-enqueue per PR before escalating to the operator.
+- **Armed on a merge-queue repo, not yet enqueued: leave it alone** until `[ship.phase7.queue_wait_expired]` (an armed PR that merely reads BEHIND is waiting for GitHub to enqueue it; the ship Phase 7 poll prints `[ship.phase7.queue_wait]`, and `sync-pr-behind.sh` itself refuses it with `kind=queue_wait`; never `gh pr update-branch` it). **Otherwise, if the PR is not in the queue** (an admin-bypass path, or a rejection that names "not up to date"), run `gh pr update-branch <N>` — **but never when both sides moved the `knowledge-base/` file count**, which a server-side merge resolves without the `kb-index` driver; merge `origin/main` locally and push instead (see [merge-pr/SKILL.md](../merge-pr/SKILL.md) §3.1 "Route conflicts"), then wait for CI to go green using **Claude: Monitor tool** / **Grok: AwaitShell** (`plugins/soleur/lib/harness.ts` `pollInstructions()`) — NEVER a backgrounded poll loop (`hr-monitor-not-run-in-background-for-polling`, hook-enforced by `background-poll-prefer-monitor.sh`), then merge.
+
+### 5. Review delegation
+
+- **Feature PRs** (`needs-review`, non-trivial diff): delegate to `soleur:review`. Merge only if it passes.
+- **Single-file `priority/p3-low` bot-fixes**: inline diff review (`gh pr diff <N>`) is sufficient; the diff is small and the change is mechanical.
+- **Bot-fix PRs that failed the cron gate** (multi-file, or the source issue is not `priority/p3-low`, so the PR carries `bot-fix/review-required`): delegate to `soleur:review`, not an inline read. Inline reading is for single-file `priority/p3-low` PRs only.
+
+### 6. Fix-recipes
+
+See `knowledge-base/project/learnings/workflow-patterns/2026-06-30-update-branch-drifts-lockfiles-and-npm11-pin.md` and `knowledge-base/project/learnings/workflow-patterns/2026-06-30-stale-bot-cron-pr-hallucinated-api-and-registration-sweep.md` for the full failure analyses.
+
+- **(a) Lockfile drift on deps PRs.** `gh pr update-branch` / a main-merge silently desyncs the lockfile. There is exactly ONE lockfile per directory since ADR-191 — do not recreate `bun.lock`:
+
+  ```bash
+  cd apps/web-platform
+  npx --yes npm@11 install --package-lock-only           # package-lock.json — npm@11 ONLY
+  ```
+
+  The `lockfile-sync` CI gate pins **npm@11**; regenerating `package-lock.json` with local npm produces a divergent shape and fails the gate. On a lockfile **merge conflict**, resolve by regenerating (`git checkout --ours -- <lockfiles>` then re-run), not by hand-picking hunks.
+- **(b) Generated-file conflicts.** Since #8377 / ADR-235 exactly one generated artifact is still committed: `knowledge-base/engineering/architecture/diagrams/model.likec4.json` (the KB index trio and `rule-metrics.json` are untracked caches and cannot conflict). Resolve it with `bash "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-regenerable-conflicts.sh" origin/main`, which completes the merge and regenerates from the MERGED sources; do NOT hand-merge conflict markers in a generated artifact, and do NOT side-pick (`--ours`/`--theirs` each yield an artifact matching neither side's sources). The same holds for a HAND-AUTHORED file whose conflict sits beside clean hunks: `git checkout --theirs <file>` takes that side's WHOLE file and silently drops the other side's non-conflicting edits (#9134, `model.c4`); `git checkout -m <file>` recreates the markers so only the conflicting hunk is resolved.
+- **(c) Stale bot PR (especially crons).** Rebase first (`gh pr update-branch`) to re-validate against current `main` — an old green predates current gates — except an armed PR on a merge-queue repo, which the queue makes current itself (see the armed-on-a-merge-queue-repo bullet above; never `update-branch` it). Then check for a hallucinated substrate API (`tsc --noEmit`) and missing registration locations per **ADR-033 §Registration checklist** (the canonical list of every gated location for a new `cron-*` function). Mirror the structurally-closest live twin signature-for-signature rather than the PR's prose.
+
+### 7. Cleanup + report
+
+Arming returns at ENQUEUE, not at merge. Run `cleanup-merged` only once the PRs it should reap read `MERGED`. Wait on each enqueued PR with a BOUND (90 polls x 60s, the Phase 7 cap), through the Monitor tool / AwaitShell (never a backgrounded loop): `bash "${CLAUDE_PLUGIN_ROOT}/scripts/monitor-pr-checks.sh" <N> --interval 60 --max-polls 90`. It reads the merge queue (`sync-pr-behind.sh <N> --queue-state`) and ends `MERGED`, or `LEFT THE MERGE QUEUE UNMERGED` with the removal reason (the dequeue arm above: ONE re-enqueue, then report), or a timeout; it never syncs or pushes. An enqueued PR that never reaches `MERGED` is that dequeue arm, not a merged PR:
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh" cleanup-merged
+```
+
+Report the drain delta: before/after open-PR count and the per-tier outcome (merged / enqueued / skipped / deferred), listing an enqueued PR as enqueued until it reads `MERGED`.
+
+## Pipeline detection
+
+If `$ARGUMENTS` contains a `RETURN CONTRACT` section (i.e., this skill is being driven by another skill), run headless: skip the interactive decision gate and `--dry-run` prompts; drain only tiers explicitly named via `--tiers`. Follows the same pattern as `plan`, `review`, and `ship`.
+
+## Sharp edges
+
+- **Drafts are skipped unless the operator names one.** A draft PR is author-owned WIP; merging it would ship incomplete work. The only exception is a draft the operator explicitly authorizes in the request (readied and armed through the block above); no flag selects drafts.
+- **`gh pr merge --squash --auto` cannot bypass server-side required checks.** Branch protection enforces `CI Required` and the merge queue re-runs the checks on its own candidate, so a mis-triaged red PR never lands — but under the queue it does not fail at merge time: a red candidate is a SILENT dequeue (the PR stays OPEN, auto-merge disarmed). See it with the dequeue arm in step 4 (`gh run list --event merge_group`, or `gh pr view <N> --json state,autoMergeRequest`); the triage is an optimization, not the safety boundary.
+- **An operator-authorized admin merge removes the server-side check the bullet above relies on.** It goes through [settle-then-admin-merge.md](${CLAUDE_PLUGIN_ROOT}/skills/ship/references/settle-then-admin-merge.md) step 2 (`"${CLAUDE_PLUGIN_ROOT}/scripts/admin-merge-ready.sh"`, which must exit 0) and that file's merge block, never through a `gh pr checks --required` watch (#8458, #8500). For a PR that is BEHIND with the new head's checks unsettled, "CI was green" is encoded as `--green-sha <prior-green-sha>`: it certifies the current head only when that head is GitHub's own verified merge of the green sha and the base — see the reference's "was-green carryover" section.
+- **The two `2026-06-30-*` learnings and ADR-033 §Registration checklist** referenced in the fix-recipes landed in PR #5808 — they are on `main`. If a future reorg moves them, update the paths here.
+- **Never poll CI from a backgrounded Bash loop.** Use the Monitor tool (Claude) or AwaitShell (Grok) for the post-`update-branch` CI wait (`hr-monitor-not-run-in-background-for-polling`).
+- **Lockfile drift reads as a *test* failure, not a lockfile error.** A red `test-webplat`/`e2e` shard on a deps PR is usually recipe (a), not a real regression — check the install step before assuming the bump broke something.
+
+## Test
+
+Unit tests live at [drain-prs.test.sh](../../test/drain-prs.test.sh). Run them with:
+
+```bash
+bash plugins/soleur/test/drain-prs.test.sh
+```
+
+Covers: one synthetic PR per tier (ready-green, lockfile-fail, conflicting, review-required, draft, broken), the head-verdict rows (`ready-unarmed`, pending-full / decided / awaiting-approval, resolver error), an empty-list case, and the tier-grouped JSON output shape.