@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/scripts/fixtures/evidence-lifecycle-circular-1001.json

@@ -0,0 +1,16 @@
+{
+  "version": 1,
+  "discoveredConditions": ["pre-enqueue-alive-needs-future-queue-evidence"],
+  "conditions": [
+    {
+      "id": "pre-enqueue-alive-needs-future-queue-evidence",
+      "phase": "synthetic-queue-head-execution",
+      "subjectKind": "synthetic-queue-head-sha",
+      "producer": "mergify-queue",
+      "provider": "mergify",
+      "acquisitionOperation": "read-synthetic-queue-checks",
+      "consumingTransition": "authorize-enqueue",
+      "failureBehavior": "block-transition"
+    }
+  ]
+}

package/skills/engineering/resolve-issues/scripts/fixtures/evidence-lifecycle-valid-sequencing.json

@@ -0,0 +1,51 @@
+{
+  "version": 1,
+  "discoveredConditions": [
+    "pr-head-checks",
+    "queue-admission",
+    "synthetic-queue-execution",
+    "target-branch-delivery"
+  ],
+  "conditions": [
+    {
+      "id": "pr-head-checks",
+      "phase": "pr-head-authorization",
+      "subjectKind": "pr-head-sha",
+      "producer": "github-actions",
+      "provider": "github",
+      "acquisitionOperation": "read-exact-pr-head-checks",
+      "consumingTransition": "authorize-enqueue",
+      "failureBehavior": "block-transition"
+    },
+    {
+      "id": "queue-admission",
+      "phase": "queue-admission",
+      "subjectKind": "pr-head-sha",
+      "producer": "resolve-issues-orchestrator",
+      "provider": "resolve-issues",
+      "acquisitionOperation": "evaluate-enqueue-eligibility",
+      "consumingTransition": "enqueue",
+      "failureBehavior": "block-transition"
+    },
+    {
+      "id": "synthetic-queue-execution",
+      "phase": "synthetic-queue-head-execution",
+      "subjectKind": "synthetic-queue-head-sha",
+      "producer": "mergify-queue",
+      "provider": "mergify",
+      "acquisitionOperation": "read-synthetic-queue-checks",
+      "consumingTransition": "record-queue-execution",
+      "failureBehavior": "mark-delivery-unproven"
+    },
+    {
+      "id": "target-branch-delivery",
+      "phase": "target-branch-ancestry",
+      "subjectKind": "merge-commit-sha",
+      "producer": "target-branch",
+      "provider": "git",
+      "acquisitionOperation": "fetch-target-and-check-ancestry",
+      "consumingTransition": "finalize-delivery",
+      "failureBehavior": "mark-delivery-unproven"
+    }
+  ]
+}

package/skills/engineering/resolve-issues/scripts/fixtures/fmm-express-830-component-candidate.json

@@ -0,0 +1,17 @@
+{
+  "incident": "consumer-product-repo#830",
+  "componentId": "tax-production",
+  "highRisk": true,
+  "units": [
+    { "id": "#831", "headSha": "8318318318318318318318318318318318318318", "preliminaryRounds": 2 },
+    { "id": "#832", "headSha": "8328328328328328328328328328328328328328", "preliminaryRounds": 3 },
+    { "id": "#833", "headSha": "8338338338338338338338338338338338338338", "preliminaryRounds": 4 },
+    { "id": "#834", "headSha": "8348348348348348348348348348348348348348", "preliminaryRounds": 3 },
+    { "id": "#835", "headSha": "8358358358358358358358358358358358358358", "preliminaryRounds": 2 },
+    { "id": "#836", "headSha": "8368368368368368368368368368368368368368", "preliminaryRounds": 3 },
+    { "id": "#837", "headSha": "8378378378378378378378378378378378378378", "preliminaryRounds": 3 },
+    { "id": "#838", "headSha": "8388388388388388388388388388388388388388", "preliminaryRounds": 6 }
+  ],
+  "historicalFullReviews": 8,
+  "expectedTerminalFullReviews": 1
+}

package/skills/engineering/resolve-issues/scripts/fixtures/head-check-set-1081.json

@@ -0,0 +1,166 @@
+{
+  "_source": "Captured verbatim from the GitHub REST API on 2026-08-16 against this repository. `incident` is the #1081 head ee5dd91a211d85f3158cbc4da8537b0cb1aee2d8; `postFix` is 284d6ca6c97d13479abe9011a4c2288f6e318852, the merge that fixed it. Trimmed to the fields head-check-set.mjs reads, and no value is invented. The one field dropped rather than trimmed is `html_url`: it names the private repository in every entry, which this package must not publish (package-audit disclosure:private-repository), and nothing classifies on it.",
+  "incident": {
+    "headSha": "ee5dd91a211d85f3158cbc4da8537b0cb1aee2d8",
+    "checkRuns": [
+      {
+        "name": "Mergify Merge Protections",
+        "status": "completed",
+        "conclusion": "neutral",
+        "app": {
+          "slug": "mergify"
+        },
+        "check_suite": {
+          "id": 86459201578
+        }
+      },
+      {
+        "name": "skill-script-tests-queue",
+        "status": "completed",
+        "conclusion": "skipped",
+        "app": {
+          "slug": "github-actions"
+        },
+        "check_suite": {
+          "id": 86459211379
+        }
+      },
+      {
+        "name": "skill-script-tests",
+        "status": "completed",
+        "conclusion": "success",
+        "app": {
+          "slug": "github-actions"
+        },
+        "check_suite": {
+          "id": 86459211379
+        }
+      },
+      {
+        "name": "Mergify Merge Queue",
+        "status": "completed",
+        "conclusion": "neutral",
+        "app": {
+          "slug": "mergify"
+        },
+        "check_suite": {
+          "id": 86459201578
+        }
+      }
+    ],
+    "statuses": [],
+    "actionsRuns": [
+      {
+        "id": 31871939947,
+        "name": "Skill gates",
+        "path": ".github/workflows/skill-gates.yml",
+        "event": "pull_request",
+        "status": "completed",
+        "conclusion": "success",
+        "head_sha": "ee5dd91a211d85f3158cbc4da8537b0cb1aee2d8",
+        "check_suite_id": 86459211379,
+        "run_started_at": "2026-08-15T07:26:09Z",
+        "updated_at": "2026-08-15T07:32:49Z",
+        "pull_requests": [],
+        "jobCount": 2
+      },
+      {
+        "id": 31871936796,
+        "name": ".github/workflows/release-package.yml",
+        "path": ".github/workflows/release-package.yml",
+        "event": "push",
+        "status": "completed",
+        "conclusion": "failure",
+        "head_sha": "ee5dd91a211d85f3158cbc4da8537b0cb1aee2d8",
+        "check_suite_id": 86459203727,
+        "run_started_at": "2026-08-15T07:26:05Z",
+        "updated_at": "2026-08-15T07:26:05Z",
+        "pull_requests": [],
+        "jobCount": 0
+      },
+      {
+        "id": 31871936392,
+        "name": ".github/workflows/bootstrap-package.yml",
+        "path": ".github/workflows/bootstrap-package.yml",
+        "event": "push",
+        "status": "completed",
+        "conclusion": "failure",
+        "head_sha": "ee5dd91a211d85f3158cbc4da8537b0cb1aee2d8",
+        "check_suite_id": 86459202731,
+        "run_started_at": "2026-08-15T07:26:04Z",
+        "updated_at": "2026-08-15T07:26:04Z",
+        "pull_requests": [],
+        "jobCount": 0
+      }
+    ]
+  },
+  "postFix": {
+    "headSha": "284d6ca6c97d13479abe9011a4c2288f6e318852",
+    "checkRuns": [
+      {
+        "name": "skill-script-tests-queue",
+        "status": "completed",
+        "conclusion": "skipped",
+        "app": {
+          "slug": "github-actions"
+        },
+        "check_suite": {
+          "id": 86509201805
+        }
+      },
+      {
+        "name": "test-runner",
+        "status": "completed",
+        "conclusion": "success",
+        "app": {
+          "slug": "github-actions"
+        },
+        "check_suite": {
+          "id": 86509201866
+        }
+      },
+      {
+        "name": "skill-script-tests",
+        "status": "completed",
+        "conclusion": "success",
+        "app": {
+          "slug": "github-actions"
+        },
+        "check_suite": {
+          "id": 86509201805
+        }
+      }
+    ],
+    "statuses": [],
+    "actionsRuns": [
+      {
+        "id": 31893819954,
+        "name": "Test Self-Hosted Runner",
+        "path": ".github/workflows/test-self-hosted.yml",
+        "event": "push",
+        "status": "completed",
+        "conclusion": "success",
+        "head_sha": "284d6ca6c97d13479abe9011a4c2288f6e318852",
+        "check_suite_id": 86509201866,
+        "run_started_at": "2026-08-15T15:49:50Z",
+        "updated_at": "2026-08-15T15:50:21Z",
+        "pull_requests": [],
+        "jobCount": 1
+      },
+      {
+        "id": 31893819933,
+        "name": "Skill gates",
+        "path": ".github/workflows/skill-gates.yml",
+        "event": "push",
+        "status": "completed",
+        "conclusion": "success",
+        "head_sha": "284d6ca6c97d13479abe9011a4c2288f6e318852",
+        "check_suite_id": 86509201805,
+        "run_started_at": "2026-08-15T15:49:50Z",
+        "updated_at": "2026-08-15T15:56:45Z",
+        "pull_requests": [],
+        "jobCount": 2
+      }
+    ]
+  }
+}

package/skills/engineering/resolve-issues/scripts/gate-value-series.mjs

@@ -0,0 +1,92 @@
+// Durable cross-run gate-value observations. The manifest remains run-local resume state;
+// this append-only series survives it and is the only evidence retirement may use.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import { gateAudit, GATE_RETIREMENT_MINIMUM_RUNS } from './fix-rounds.mjs'
+
+const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0
+
+export function gateValueDir(env = process.env) {
+  if (nonEmpty(env?.RESOLVER_GATE_VALUE_DIR)) return env.RESOLVER_GATE_VALUE_DIR.replace(/\/+$/, '')
+  if (nonEmpty(env?.RESOLVER_RUN_DIR)) return path.join(env.RESOLVER_RUN_DIR.replace(/\/+$/, ''), 'gate-value')
+  const state = nonEmpty(env?.XDG_STATE_HOME)
+    ? env.XDG_STATE_HOME.replace(/\/+$/, '')
+    : path.join(os.homedir(), '.local', 'state')
+  return path.join(state, 'resolver-gate-value')
+}
+
+export function gateValuePaths(env = process.env) {
+  const dir = gateValueDir(env)
+  return { dir, index: path.join(dir, 'index.jsonl') }
+}
+
+export function gateRetirementMinimumRuns(env = process.env) {
+  const configured = Number(env?.RESOLVER_GATE_RETIREMENT_MIN_RUNS)
+  return Number.isSafeInteger(configured) && configured > 0 ? configured : GATE_RETIREMENT_MINIMUM_RUNS
+}
+
+export function gateValueObservation(manifest, now = new Date()) {
+  return {
+    observedAt: now.toISOString(),
+    runSlug: nonEmpty(manifest?.runSlug) ? manifest.runSlug : null,
+    gateValue: gateAudit(manifest),
+  }
+}
+
+// A diagnostic save never fails the run. The returned error keeps an unwritten series
+// distinguishable from a successful zero-value observation.
+export function saveGateValueObservation(manifest, env = process.env, now = new Date()) {
+  const paths = gateValuePaths(env)
+  try {
+    fs.mkdirSync(paths.dir, { recursive: true })
+    fs.appendFileSync(paths.index, `${JSON.stringify(gateValueObservation(manifest, now))}\n`)
+    return { saved: true, paths, error: null }
+  } catch (error) {
+    return { saved: false, paths, error: error?.message ?? String(error) }
+  }
+}
+
+export function readGateValueSeries(env = process.env) {
+  const { index } = gateValuePaths(env)
+  if (!fs.existsSync(index)) return []
+  let text
+  try {
+    text = fs.readFileSync(index, 'utf8')
+  } catch (error) {
+    return [{ unreadable: true, reason: `series read failed: ${error?.message ?? String(error)}` }]
+  }
+
+  const latest = new Map()
+  const unreadable = []
+  for (const [lineIndex, line] of text.split('\n').entries()) {
+    if (!line.trim()) continue
+    try {
+      const observation = JSON.parse(line)
+      if (!observation || typeof observation !== 'object' || !nonEmpty(observation.runSlug) || !Array.isArray(observation.gateValue)) {
+        unreadable.push({ lineIndex, unreadable: true, reason: `malformed series row ${lineIndex + 1}` })
+        continue
+      }
+      latest.set(observation.runSlug, { lineIndex, ...observation })
+    } catch (error) {
+      unreadable.push({ lineIndex, unreadable: true, reason: `unreadable series row ${lineIndex + 1}: ${error?.message ?? String(error)}` })
+    }
+  }
+  return [...latest.values(), ...unreadable]
+    .sort((a, b) => a.lineIndex - b.lineIndex)
+    .map(({ lineIndex, ...observation }) => observation)
+}
+
+export function auditGateValue(manifest, options = {}) {
+  const env = options.env ?? process.env
+  const persisted = options.persist === false
+    ? null
+    : saveGateValueObservation(manifest, env, options.now ?? new Date())
+  const series = readGateValueSeries(env)
+  if (persisted && !persisted.saved) series.push({ unreadable: true, reason: `current gate-value observation was not saved: ${persisted.error}` })
+  return gateAudit(manifest, {
+    series,
+    minimumObservationRuns: gateRetirementMinimumRuns(env),
+  })
+}

package/skills/engineering/resolve-issues/scripts/guide-index.mjs

@@ -0,0 +1,73 @@
+// The routing table that used to be `SKILL.md`'s Reference Map — 24 rows and 3.6KB of the
+// always-loaded file, spent on a lookup nobody reads start to finish.
+//
+// WHY IT MOVED. SKILL.md is the one file loaded into every run's context, so every byte in it is
+// paid on every run whether or not it is used. A 24-row "when you need X, read Y" table is
+// consulted *situationally* — you want one row, when you already know what you are doing next.
+// That is the shape of a query, not of doctrine, and it is the only section of SKILL.md that was
+// pure lookup data. The phase-routing table stayed behind: it is read once at the start and is
+// what makes a truncated read survivable.
+//
+// WHAT DID NOT MOVE, AND WHY THAT MATTERS. A table in context is *passively* available; a command
+// must be *actively* invoked. So this trade is only safe because `run-state.mjs guide` is named in
+// SKILL.md itself, near the top of what survives a partial read. If that pointer is ever dropped,
+// this file becomes unreachable and the routing silently stops existing — which is why
+// `guide-index.test.mjs` pins both the pointer and the reachability of every destination.
+
+export const GUIDE = [
+  { need: 'run the pre-flight gate — its seven steps, and which chapter owns each', targets: [{ label: 'references/pre-flight.md', path: 'references/pre-flight.md' }] },
+  { need: 'settle both model slots (discovery, tiering, the reviewer default)', targets: [{ label: 'references/pre-flight-model-slots.md', path: 'references/pre-flight-model-slots.md' }] },
+  { need: 'settle the merge path (`deliveryMode` + `queueProvider`) at pre-flight', targets: [{ label: '`scripts/detect-delivery-mode.mjs`', path: 'scripts/detect-delivery-mode.mjs' }] },
+  { need: 'settle where the run writes code (`shared` vs its own worktree)', targets: [{ label: '`scripts/detect-workspace-mode.mjs`', path: 'scripts/detect-workspace-mode.mjs' }] },
+  { need: 'record interference, schedule concurrent units, or reap their workspaces', targets: [{ label: 'references/interference.md', path: 'references/interference.md' }, { label: '`run-state.mjs runnable`', path: 'scripts/run-state.mjs' }, { label: '`scripts/workspaces.mjs`', path: 'scripts/workspaces.mjs' }] },
+  { need: 'get this run\'s delivery flow and its exact enqueue/read/nudge/dequeue commands', targets: [{ label: '`run-state.mjs delivery-flow`', path: 'scripts/run-state.mjs' }] },
+  { need: 'report the plan before building, or progress **every time a unit leaves the loop** (the trigger: [loop.md](references/loop.md#3--fix-then-loop))', targets: [{ label: '`run-state.mjs plan`/`progress`', path: 'scripts/run-state.mjs' }, { label: 'renderers', path: 'scripts/report.mjs' }] },
+  { need: 'route a round that corrects a claim, not the code', targets: [{ label: 'references/evidence-lane.md', path: 'references/evidence-lane.md' }] },
+  { need: 'find out **why** this run kept buying evidence rounds — and whether to run a screen or build one', targets: [{ label: '`run-state.mjs evidence-audit`', path: 'scripts/run-state.mjs' }] },
+  { need: 'honour the leaf-spawn contract on a spawn — **render it** rather than compose it', targets: [{ label: '`run-state.mjs spawn-contract`', path: 'scripts/run-state.mjs' }, { label: 'references/spawn-contract.md', path: 'references/spawn-contract.md' }] },
+  { need: 'deliver a merge-ready component (enqueue, watch, dequeue routing)', targets: [{ label: 'references/delivery.md', path: 'references/delivery.md' }] },
+  { need: 'wait out an enqueued PR without spending foreground turns', targets: [{ label: '`scripts/watch-delivery.mjs`', path: 'scripts/watch-delivery.mjs' }] },
+  { need: 'preserve terminal provider facts while coherence blocks delivery, then reconcile them', targets: [{ label: 'references/terminal-evidence-journal.md', path: 'references/terminal-evidence-journal.md' }, { label: '`scripts/terminal-evidence-journal.mjs`', path: 'scripts/terminal-evidence-journal.mjs' }, { label: '`run-state.mjs reconcile-terminal-evidence`', path: 'scripts/run-state.mjs' }] },
+  { need: 'diagnose a stuck unit / answer a fired circuit-breaker', targets: [{ label: 'references/breaker.md', path: 'references/breaker.md' }, { label: '`run-state.mjs diagnose-breaker`', path: 'scripts/run-state.mjs' }] },
+  { need: 'run a high-risk unit\'s deep protocol (hazard hunt, round-1 depth, theme-complete fixes)', targets: [{ label: 'references/high-risk.md', path: 'references/high-risk.md' }] },
+  { need: 'fan a stage out via the Workflow harness', targets: [{ label: 'references/fan-out.md', path: 'references/fan-out.md' }] },
+  { need: 'run the epic integration gate', targets: [{ label: 'references/integration-gate.md', path: 'references/integration-gate.md' }, { label: '`scripts/combine-and-verify.mjs`', path: 'scripts/combine-and-verify.mjs' }] },
+  { need: '**pick up a dead session\'s run** — find it, then see what it was waiting on', targets: [{ label: '`run-state.mjs list`', path: 'scripts/run-state.mjs' }, { label: '`run-state.mjs resume <slug>`', path: 'scripts/run-state.mjs' }] },
+  { need: 'finalize and render the correctness handoff', targets: [{ label: '`run-state.mjs finalize`', path: 'scripts/run-state.mjs' }, { label: 'references/finalization.md', path: 'references/finalization.md' }] },
+  { need: 'run an optional, non-blocking profile diagnostic', targets: [{ label: '`run-state.mjs postmortem`', path: 'scripts/run-state.mjs' }, { label: 'references/postmortem.md', path: 'references/postmortem.md' }] },
+  { need: 'persist/resume run state', targets: [{ label: 'references/run-state.md', path: 'references/run-state.md' }] },
+  { need: 'classify a model at pre-flight', targets: [{ label: 'references/model-catalog.md', path: 'references/model-catalog.md' }] },
+  { need: 'know the bar any step must serve — the four guarantees in full', targets: [{ label: 'references/guarantees.md', path: 'references/guarantees.md' }] },
+  { need: 'know **why** a rule exists — its incident, measurement, or audit', targets: [{ label: 'references/why.md', path: 'references/why.md' }] },
+  { need: 'edit this skill, or grade a transcript', targets: [{ label: 'references/regression-checklist.md', path: 'references/regression-checklist.md' }] },
+  { need: 'test this skill from a scratch copy (mutation testing, sandboxing)', targets: [{ label: 'references/sandboxed-testing.md', path: 'references/sandboxed-testing.md' }] },
+  { need: 'turn issues into scheduled units — the decomposition, design and scope gates', targets: [{ label: 'references/intake.md', path: 'references/intake.md' }] },
+  { need: 'run a unit through produce -> review ∥ CI -> fix, and record each round', targets: [{ label: 'references/loop.md', path: 'references/loop.md' }] },
+  { need: 'scope a component and decide what ships together', targets: [{ label: 'references/deliverables.md', path: 'references/deliverables.md' }] },
+  { need: 'gate CI on the exact reviewed head', targets: [{ label: 'references/exact-head-ci.md', path: 'references/exact-head-ci.md' }] },
+  { need: 'record the pre-flight answers, settle autonomy, prepare the checkout', targets: [{ label: 'references/pre-flight-recording-and-checkout.md', path: 'references/pre-flight-recording-and-checkout.md' }] },
+]
+// Match on the need text and on the destination paths, because a caller knows either "what I am
+// trying to do" or "the file I half-remember". Ranked, not filtered: an empty result is a worse
+// answer than a weak one, so a query that matches nothing falls back to the full list.
+export function guideLookup(query) {
+  const q = String(query ?? '').toLowerCase().trim()
+  if (!q) return { query: '', matches: GUIDE }
+  const terms = q.split(/\s+/).filter(Boolean)
+  const scored = GUIDE.map((row) => {
+    const hay = (row.need + ' ' + row.targets.map((t) => `${t.label} ${t.path}`).join(' ')).toLowerCase()
+    return { row, score: terms.reduce((n, t) => n + (hay.includes(t) ? 1 : 0), 0) }
+  }).filter((s) => s.score > 0).sort((a, b) => b.score - a.score)
+  return { query: q, matches: scored.map((s) => s.row), fellBack: scored.length === 0 }
+}
+
+export function renderGuide(result) {
+  const out = []
+  if (result.fellBack) out.push(`no row matches ${JSON.stringify(result.query)} — showing all ${GUIDE.length}:`, '')
+  const rows = result.fellBack ? GUIDE : result.matches
+  for (const row of rows) {
+    out.push(`  ${row.need}`)
+    for (const t of row.targets) out.push(`      ${t.path}`)
+  }
+  return out.join('\n')
+}

package/skills/engineering/resolve-issues/scripts/head-check-set.mjs

@@ -0,0 +1,159 @@
+// head-check-set — ask the SET question about a head SHA, not the NAME question.
+//
+//   node head-check-set.mjs collect --repository owner/name --head <40-sha>
+//                                   [--plan required-check-plan.json]
+//                                   [--out head-check-set.json] [--markdown] [--strict]
+//   node head-check-set.mjs report   <head-check-set.json>
+//   node head-check-set.mjs validate <head-check-set.json> --head <40-sha>
+//
+// The classification is pure and lives in engineering-runtime/head-check-set.mjs, which
+// carries the incident (#1081) and the reason all three channels are read. This file is
+// only the `gh` boundary and the CLI around it.
+//
+// EXIT CODES, and the line this tool does not cross. `collect` exits 1 when a REQUIRED
+// check is red or never ran — the state the existing merge-admission contract already
+// blocks on — and 0 otherwise, INCLUDING when an undeclared check is red. That is
+// deliberate and is acceptance criterion 4 of #1082: whether a non-required red check
+// should stop a merge is a policy decision belonging to the human and to `.mergify.yml`,
+// and a reporting script that silently changed what merges would be a worse defect than
+// the one it fixes. `--strict` opts in to exiting 1 on undeclared red; it is off by
+// default and nothing in the loop passes it.
+//
+// The plan is OPTIONAL. Without one, nothing is required: the report degrades to a pure
+// observation of the SHA rather than pretending every red is undeclared, and `collect`
+// can then only exit 0 or 2.
+
+import fs from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import {
+  blocksOnRequiredSet,
+  classifyHeadCheckSet,
+  renderHeadCheckSet,
+  validateHeadCheckSetArtifact,
+} from '../../engineering-runtime/scripts/head-check-set.mjs'
+
+export { blocksOnRequiredSet, classifyHeadCheckSet, renderHeadCheckSet, validateHeadCheckSetArtifact }
+
+const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0
+const SHA = /^[0-9a-f]{40}$/i
+
+const DEFAULT_BOUNDARY = Object.freeze({
+  ghJson(args) {
+    const text = execFileSync('gh', args, { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 }).trim()
+    return text ? JSON.parse(text) : null
+  },
+})
+
+/**
+ * The three channels, read at one SHA.
+ *
+ * Each is a separate call because each is a separate GitHub concept, and the third is
+ * the only one where a workflow GitHub refused to parse leaves a trace — it produces no
+ * check-run to be red. Job counts cost one call per run and are what make that trace
+ * nameable rather than merely red.
+ */
+export function collectHeadCheckSet({ repository, headSha, plan = null, now }, boundary = DEFAULT_BOUNDARY) {
+  const api = (path) => boundary.ghJson(['api', `repos/${repository}/${path}`])
+  const slurped = (path, key) => {
+    const pages = boundary.ghJson(['api', '--paginate', '--slurp', `repos/${repository}/${path}`]) || []
+    return pages.flatMap((page) => page?.[key] || [])
+  }
+  const checkRuns = slurped(`commits/${headSha}/check-runs?per_page=100`, 'check_runs')
+  const statuses = api(`commits/${headSha}/status?per_page=100`)?.statuses || []
+  const actionsRuns = slurped(`actions/runs?head_sha=${headSha}&per_page=100`, 'workflow_runs').map((run) => {
+    // `total_count` on the jobs endpoint, not the length of a page: a run with zero jobs
+    // and a run whose first page we failed to read must not both read as zero.
+    let jobCount = null
+    try {
+      const jobs = api(`actions/runs/${run.id}/jobs?per_page=1`)
+      if (Number.isInteger(jobs?.total_count)) jobCount = jobs.total_count
+    } catch {
+      jobCount = null
+    }
+    return { ...run, jobCount }
+  })
+  return classifyHeadCheckSet({
+    repository,
+    headSha,
+    checkRuns,
+    statuses,
+    actionsRuns,
+    plan,
+    ...(now ? { collectedAt: now } : {}),
+  })
+}
+
+function parseArgs(argv) {
+  const options = {}
+  const positional = []
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === '--repository') options.repository = argv[++index]
+    else if (arg === '--head') options.headSha = argv[++index]
+    else if (arg === '--plan') options.plan = argv[++index]
+    else if (arg === '--out' || arg === '-o') options.out = argv[++index]
+    else if (arg === '--markdown') options.markdown = true
+    else if (arg === '--strict') options.strict = true
+    else if (arg === '--help' || arg === '-h') options.help = true
+    else if (arg.startsWith('--')) throw new Error(`unknown argument ${arg}`)
+    else positional.push(arg)
+  }
+  return { command: positional[0], file: positional[1], options }
+}
+
+const USAGE = 'usage: head-check-set collect --repository owner/name --head <40-sha> [--plan plan.json] [--out out.json] [--markdown] [--strict]'
+  + ' | report <artifact.json> | validate <artifact.json> --head <40-sha>'
+
+export function runCli(argv, boundary = DEFAULT_BOUNDARY) {
+  let parsed
+  try { parsed = parseArgs(argv) } catch (error) { console.error(`head-check-set: ${error.message}`); return 2 }
+  const { command, file, options } = parsed
+  if (options.help || command === 'help' || command === undefined) { console.log(USAGE); return options.help || command === 'help' ? 0 : 2 }
+
+  if (command === 'collect') {
+    if (!nonEmpty(options.repository) || !/^[^/\s]+\/[^/\s]+$/.test(options.repository)) { console.error('head-check-set collect requires --repository owner/name'); return 2 }
+    if (!nonEmpty(options.headSha) || !SHA.test(options.headSha)) { console.error('head-check-set collect requires --head <full 40-character commit SHA>'); return 2 }
+    let plan = null
+    try {
+      if (options.plan) plan = JSON.parse(fs.readFileSync(options.plan, 'utf8'))
+    } catch (error) { console.error(`head-check-set: ${String(error.message || error)}`); return 2 }
+    let artifact
+    try {
+      artifact = collectHeadCheckSet({ repository: options.repository, headSha: options.headSha, plan }, boundary)
+    } catch (error) { console.error(`head-check-set: ${String(error.message || error)}`); return 2 }
+    const rendered = options.markdown ? renderHeadCheckSet(artifact) : `${JSON.stringify(artifact, null, 2)}\n`
+    if (options.out) fs.writeFileSync(options.out, rendered.endsWith('\n') ? rendered : `${rendered}\n`)
+    else console.log(rendered.replace(/\n$/, ''))
+    // Reported on stderr so that stdout stays exactly the artifact a pipe consumes.
+    console.error(`head-check-set: ${artifact.summary.outcome} at ${artifact.headSha} — ${artifact.summary.counts.requiredRed} required red, ${artifact.summary.counts.undeclaredRed} undeclared red, ${artifact.summary.counts.neverRan} never ran, ${artifact.summary.counts.startupFailures} zero-job workflow run(s)`)
+    for (const failure of artifact.signatures.startupFailures) {
+      console.error(`head-check-set: run ${failure.runId} "${failure.name}" completed ${failure.conclusion} having executed ZERO jobs${failure.nameEqualsPath ? ' — its name equals its file path, corroborating a workflow GitHub refused to parse' : ''}`)
+    }
+    for (const entry of artifact.partition.undeclaredRed) {
+      console.error(`head-check-set: UNDECLARED RED (not required, not gated here): ${entry.name} [${entry.source}] ${entry.conclusion ?? entry.status}`)
+    }
+    if (blocksOnRequiredSet(artifact)) return 1
+    return options.strict && artifact.partition.undeclaredRed.length ? 1 : 0
+  }
+
+  if (command === 'report') {
+    if (!file) { console.error('head-check-set report <artifact.json>'); return 2 }
+    console.log(renderHeadCheckSet(JSON.parse(fs.readFileSync(file, 'utf8'))))
+    return 0
+  }
+
+  if (command === 'validate') {
+    if (!file || !nonEmpty(options.headSha)) { console.error('head-check-set validate <artifact.json> --head <40-sha>'); return 2 }
+    const artifact = JSON.parse(fs.readFileSync(file, 'utf8'))
+    const verdict = validateHeadCheckSetArtifact(artifact, { expectedHeadSha: options.headSha })
+    if (verdict.ok) console.log(`head-check-set: valid ${artifact.summary.outcome} artifact at ${options.headSha}`)
+    else verdict.errors.forEach((error) => console.error(`error: ${error}`))
+    return verdict.ok ? 0 : 1
+  }
+
+  console.error(USAGE)
+  return 2
+}
+
+if (isMainModule(import.meta.url)) process.exit(runCli(process.argv.slice(2)))