@1aboveio/skills 0.10.0

package/skills/engineering/engineering-runtime/scripts/exact-head-artifact.mjs

@@ -0,0 +1,131 @@
+// Shared read-only validator for exact-head CI artifacts. The mutating adapter lives
+// in resolve-issues; consumers import this contract so review and integration use the
+// same fail-closed definition of valid evidence.
+import { locallyReproducedJobs, validatePublishOnlyEvidence, validateRequiredCheckExecution, validateRequiredCheckPlan } from './required-check-plan.mjs'
+
+export const EXACT_HEAD_ARTIFACT_VERSION = 2
+export const EXACT_HEAD_COLLECTION_MODES = Object.freeze(['choreographed', 'observed-existing-run'])
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable)
+  if (!isObject(value)) return value
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]))
+}
+
+export function sameExactHeadState(left, right) {
+  return JSON.stringify(stable(left)) === JSON.stringify(stable(right))
+}
+
+export function providerWorkflowIdentityMatches(expected, identity) {
+  if (typeof expected !== 'string' || !expected.trim() || !isObject(identity)) return false
+  const aliases = [identity.id, identity.name, identity.path]
+    .filter((value) => (typeof value === 'string' && value.trim()) || typeof value === 'number')
+    .map(String)
+  if (typeof identity.path === 'string') aliases.push(identity.path.split('/').at(-1))
+  return aliases.includes(expected)
+}
+
+function validateProviderWorkflowIdentity(identity) {
+  const errors = []
+  if (!isObject(identity)) return ['artifact.workflow.provider must preserve provider-issued workflow identity']
+  if ((typeof identity.id !== 'string' && typeof identity.id !== 'number') || !String(identity.id).trim()) errors.push('artifact.workflow.provider.id must identify the provider workflow')
+  if (typeof identity.name !== 'string' || !identity.name.trim()) errors.push('artifact.workflow.provider.name must preserve the provider workflow name')
+  if (identity.path !== undefined && (typeof identity.path !== 'string' || !identity.path.trim())) errors.push('artifact.workflow.provider.path must be a non-empty string when present')
+  return errors
+}
+
+function classifyRawJobs(jobs, policy) {
+  const errors = []
+  if (!Array.isArray(jobs)) return { outcome: 'failure', errors: ['artifact.jobs must be an array'] }
+  if (!isObject(policy) || !Array.isArray(policy.requiredJobs) || !Array.isArray(policy.allowedSkippedJobs)) {
+    return { outcome: 'failure', errors: ['artifact.policy must preserve requiredJobs and allowedSkippedJobs arrays'] }
+  }
+  const byName = new Map()
+  for (const [index, job] of jobs.entries()) {
+    if (!isObject(job) || typeof job.name !== 'string' || !Object.hasOwn(job, 'conclusion')) {
+      errors.push(`artifact.jobs[${index}] must preserve name and conclusion`)
+      continue
+    }
+    if (byName.has(job.name)) errors.push(`artifact.jobs has duplicate/ambiguous evidence for ${job.name}`)
+    else byName.set(job.name, job)
+  }
+  const missing = policy.requiredJobs.filter((name) => !byName.has(name))
+  const notSuccessful = policy.requiredJobs.filter((name) => byName.has(name) && byName.get(name).conclusion !== 'success')
+  const allowedSkipped = new Set(policy.allowedSkippedJobs)
+  const disallowedSkipped = jobs.filter((job) => job?.conclusion === 'skipped' && !allowedSkipped.has(job.name)).map((job) => job.name)
+  const failed = jobs.filter((job) => job && !['success', 'skipped'].includes(job.conclusion)).map((job) => `${job.name} (${job.conclusion ?? 'pending'})`)
+  if (missing.length) errors.push(`required jobs missing: ${missing.join(', ')}`)
+  if (notSuccessful.length) errors.push(`required jobs not successful: ${notSuccessful.join(', ')}`)
+  if (disallowedSkipped.length) errors.push(`jobs skipped without policy allowance: ${disallowedSkipped.join(', ')}`)
+  if (failed.length) errors.push(`raw jobs contain failure states: ${failed.join(', ')}`)
+  let outcome = 'success'
+  if (jobs.length === 0) outcome = 'zero-job-workflow-failure'
+  else if (jobs.some((job) => job?.conclusion === 'cancelled')) outcome = 'cancelled'
+  else if (errors.length) outcome = 'failure'
+  else if (jobs.some((job) => job?.conclusion === 'skipped')) outcome = 'success-with-skipped'
+  return { outcome, errors }
+}
+
+export function validateExactHeadArtifact(artifact, { expectedHeadSha } = {}) {
+  const errors = []
+  if (!isObject(artifact)) return { ok: false, errors: ['exact-head artifact must be an object'] }
+  if (artifact.version !== EXACT_HEAD_ARTIFACT_VERSION) errors.push(`unsupported exact-head artifact version ${artifact.version}`)
+  if (artifact.kind !== 'exact-head-ci') errors.push('exact-head artifact kind must be "exact-head-ci"')
+  if (!EXACT_HEAD_COLLECTION_MODES.includes(artifact.collectionMode)) errors.push(`artifact.collectionMode must be one of ${EXACT_HEAD_COLLECTION_MODES.join('|')}`)
+  if (typeof artifact.repository !== 'string' || !/^[^/\s]+\/[^/\s]+$/.test(artifact.repository)) errors.push('artifact.repository must be owner/name')
+  if (!Number.isInteger(artifact.pr) || artifact.pr < 1) errors.push('artifact.pr must be a positive integer')
+  if (typeof artifact.headSha !== 'string' || !/^[0-9a-f]{40}$/i.test(artifact.headSha)) errors.push('artifact.headSha must be a full 40-character commit SHA')
+  if (expectedHeadSha && artifact.headSha !== expectedHeadSha) errors.push(`exact-head artifact is STALE: stamped ${artifact.headSha}, expected ${expectedHeadSha}`)
+  const plan = validateRequiredCheckPlan(artifact.requiredCheckPlan, { expectedHeadSha: artifact.headSha })
+  errors.push(...plan.errors)
+  if (artifact.requiredCheckPlan?.repository !== artifact.repository) errors.push('requiredCheckPlan repository does not match artifact.repository')
+  const execution = validateRequiredCheckExecution(artifact.requiredCheckPlan, artifact.jobs, { expectedHeadSha: artifact.headSha })
+  errors.push(...execution.errors.filter((error) => !plan.errors.includes(error)))
+  const publishOnly = validatePublishOnlyEvidence(artifact.requiredCheckPlan, artifact.publishOnlyEvidence, { expectedHeadSha: artifact.headSha, expectedRepository: artifact.repository, expectedPr: artifact.pr })
+  errors.push(...publishOnly.errors)
+  if (!isObject(artifact.workflow) || typeof artifact.workflow.id !== 'string' || !artifact.workflow.id.trim()) errors.push('artifact.workflow.id must identify the requested provider workflow')
+  errors.push(...validateProviderWorkflowIdentity(artifact.workflow?.provider))
+  if (isObject(artifact.workflow?.provider) && !providerWorkflowIdentityMatches(artifact.workflow?.id, artifact.workflow.provider)) errors.push('provider workflow identity does not match artifact.workflow.id')
+  if (typeof artifact.workflow?.runId !== 'string' && typeof artifact.workflow?.runId !== 'number') errors.push('artifact.workflow.runId must identify the provider run')
+  if (artifact.workflow?.headSha !== artifact.headSha) errors.push('workflow headSha does not match artifact headSha')
+  if (!Array.isArray(artifact.jobs)) errors.push('artifact.jobs must be an array')
+  else for (const [index, job] of artifact.jobs.entries()) {
+    if (!isObject(job) || typeof job.name !== 'string' || !Object.hasOwn(job, 'conclusion')) errors.push(`artifact.jobs[${index}] must preserve name and conclusion`)
+  }
+  const expectedPolicy = {
+    requiredJobs: locallyReproducedJobs(artifact.requiredCheckPlan),
+    allowedSkippedJobs: artifact.requiredCheckPlan?.allowedSkippedJobs,
+  }
+  if (!sameExactHeadState(artifact.policy, expectedPolicy)) errors.push('artifact.policy must be derived exactly from requiredCheckPlan')
+  const raw = classifyRawJobs(artifact.jobs, artifact.policy)
+  errors.push(...raw.errors)
+  if (artifact.summary?.outcome !== raw.outcome) errors.push(`summary outcome "${artifact.summary?.outcome ?? 'missing'}" contradicts raw jobs outcome "${raw.outcome}"`)
+
+  if (artifact.collectionMode === 'choreographed') {
+    if (!Array.isArray(artifact.choreography) || artifact.choreography.length === 0) errors.push('choreographed artifacts must preserve the mutation choreography')
+    if (Object.hasOwn(artifact, 'observation')) errors.push('choreographed artifacts cannot claim observed-existing-run provenance')
+    if (artifact.restoration?.proved !== true) errors.push('live restoration was not proved')
+    if (!sameExactHeadState(artifact.snapshot, artifact.restoration?.observed)) errors.push('restoration observation does not equal the original snapshot')
+  }
+  if (artifact.collectionMode === 'observed-existing-run') {
+    if (Object.hasOwn(artifact, 'choreography')) errors.push('observed-existing-run artifacts cannot claim mutation choreography')
+    if (Object.hasOwn(artifact, 'restoration')) errors.push('observed-existing-run artifacts cannot contain a restoration claim')
+    if (Object.hasOwn(artifact, 'snapshot')) errors.push('observed-existing-run artifacts must use before/after observation provenance, not a choreography snapshot')
+    if (!isObject(artifact.observation) || !isObject(artifact.observation.before) || !isObject(artifact.observation.after)) {
+      errors.push('observed-existing-run artifacts require live PR observations before and after provider evidence acquisition')
+    } else {
+      if (artifact.observation.before.headSha !== artifact.headSha) errors.push('observed-existing-run before observation does not match artifact.headSha')
+      if (artifact.observation.after.headSha !== artifact.headSha) errors.push('observed-existing-run after observation does not match artifact.headSha')
+    }
+  }
+  if (!Array.isArray(artifact.errors)) errors.push('artifact.errors must be an array')
+  else if (artifact.errors.length) errors.push('passing exact-head artifacts cannot preserve collection errors')
+  if (artifact.status !== 'pass') errors.push(`exact-head status is "${artifact.status ?? 'missing'}", needs "pass"`)
+  if (!['success', 'success-with-skipped'].includes(artifact.summary?.outcome)) errors.push(`exact-head outcome is "${artifact.summary?.outcome ?? 'missing'}", not a passing outcome`)
+  if (!['success', 'success-with-skipped'].includes(raw.outcome)) errors.push(`raw jobs outcome "${raw.outcome}" is not passing`)
+  return { ok: errors.length === 0, errors }
+}

package/skills/engineering/engineering-runtime/scripts/head-check-set.mjs

@@ -0,0 +1,398 @@
+// head-check-set — the FULL observed state of one commit, not the named subset of it.
+//
+// A required-check plan answers "are the checks I named green?". #1081 is what that
+// question cannot see. Two release workflows were rejected by GitHub at validation
+// time; every push produced two runs that completed in the same second having executed
+// ZERO jobs, named after the file path instead of the declared `name:`. That was
+// visible for seven hours across fourteen commits, and the unit still earned an
+// independent PASS and a merge-ready mark, because the one check anybody read
+// (`skill-script-tests`) was green — and it genuinely was.
+//
+// THE SUBTLETY THAT DEFEATS THE OBVIOUS FIX. "Read every check-run instead of the
+// named ones" would ALSO have missed #1081. A workflow GitHub cannot parse produces no
+// check-run at all — not a red one, none. The real observation at that SHA:
+//
+//   GET /commits/ee5dd91a…/check-runs  → 4 entries, every one success/neutral/skipped
+//   GET /commits/ee5dd91a…/status      → state "pending", zero statuses
+//   GET /actions/runs?head_sha=ee5dd91a… → 3 runs, TWO of them conclusion "failure"
+//                                          with name == path and zero jobs
+//
+// So the full state of a commit is the union of three channels — check-runs, legacy
+// commit statuses, and Actions runs — and the third is the only one where a startup
+// failure lives. This module classifies that union. Both halves are load-bearing: the
+// union is what makes undeclared red visible, and the zero-job run is what makes the
+// #1081 class NAMEABLE rather than a number in a count.
+//
+// WHAT THIS DELIBERATELY DOES NOT DO. It does not gate. Whether a red check nobody
+// declared required should block a merge is a policy decision belonging to the human
+// and to `.mergify.yml`, and a reporting script that quietly changed what merges would
+// be a worse defect than the one it fixes. The partition names `undeclaredRed`
+// separately from `requiredRed` precisely so a caller can act on the difference; the
+// only outcome this module calls failing is the one the existing contract already
+// blocks on — a REQUIRED check red or absent.
+
+export const HEAD_CHECK_SET_VERSION = 1
+export const HEAD_CHECK_SET_KIND = 'head-check-set'
+export const OBSERVATION_SOURCES = Object.freeze(['check-run', 'commit-status', 'actions-run'])
+export const OBSERVATION_STATES = Object.freeze(['green', 'red', 'neutral', 'pending'])
+
+// Why `cancelled` counts as red: a cancelled required check is not a passed one, and
+// the surrounding contract has said "skipped is never success" since epic-892. Neutral
+// and skipped stay `neutral` — they are not passes either, but they are not evidence of
+// breakage, and conflating the two is how a report gets ignored.
+const RED_CONCLUSIONS = new Set(['failure', 'timed_out', 'action_required', 'startup_failure', 'stale', 'cancelled'])
+const NEUTRAL_CONCLUSIONS = new Set(['skipped', 'neutral'])
+const COMPLETED = new Set(['completed'])
+
+// A run GitHub could not parse is reported with its file path where its name belongs,
+// because there is no parsed `name:` to report. Corroborating, never sufficient: a
+// workflow may legitimately declare no `name:`, in which case GitHub also uses the path.
+const WORKFLOW_PATH = /^\.github\/workflows\/[^/]+\.ya?ml$/
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0
+const SHA = /^[0-9a-f]{40}$/i
+const lower = (value) => (value == null ? null : String(value).toLowerCase())
+
+function stateOf(status, conclusion) {
+  const normalizedStatus = lower(status)
+  const normalizedConclusion = lower(conclusion)
+  if (normalizedStatus !== null && !COMPLETED.has(normalizedStatus)) return 'pending'
+  if (normalizedConclusion === null) return 'pending'
+  if (normalizedConclusion === 'success') return 'green'
+  if (NEUTRAL_CONCLUSIONS.has(normalizedConclusion)) return 'neutral'
+  if (RED_CONCLUSIONS.has(normalizedConclusion)) return 'red'
+  // Deny-by-default on a conclusion this module has never seen: an unknown conclusion
+  // read as green is exactly the failure this file exists to remove.
+  return 'red'
+}
+
+function commitStatusState(state) {
+  const normalized = lower(state)
+  if (normalized === 'success') return 'green'
+  if (normalized === 'pending') return 'pending'
+  return 'red'
+}
+
+/** Every check name the plan declares required, in any phase. */
+export function requiredCheckNames(plan) {
+  const fromChecks = (plan?.checks || [])
+    .filter((check) => check?.admission === 'required' && nonEmpty(check?.name))
+    .map((check) => check.name)
+  const fromDiscovery = (plan?.discovery?.requiredChecks || []).filter(nonEmpty)
+  return [...new Set([...fromChecks, ...fromDiscovery])].sort()
+}
+
+function checkRunObservation(run) {
+  return {
+    source: 'check-run',
+    name: String(run?.name ?? ''),
+    state: stateOf(run?.status, run?.conclusion),
+    status: run?.status ?? null,
+    conclusion: run?.conclusion ?? null,
+    app: run?.app?.slug ?? null,
+    checkSuiteId: run?.check_suite?.id ?? null,
+    url: run?.html_url ?? null,
+  }
+}
+
+function commitStatusObservation(status) {
+  return {
+    source: 'commit-status',
+    name: String(status?.context ?? ''),
+    state: commitStatusState(status?.state),
+    status: 'completed',
+    conclusion: status?.state ?? null,
+    app: status?.creator?.login ?? null,
+    checkSuiteId: null,
+    url: status?.target_url ?? null,
+  }
+}
+
+/**
+ * An Actions run, plus the two facts that make #1081 nameable.
+ *
+ * `jobCount` is supplied by the caller because it costs one extra API call per run and
+ * this module is pure. A run that has completed with `jobCount === 0` executed nothing:
+ * that is the startup-failure signature, and it is the whole reason the Actions channel
+ * is read at all. `null` means the caller could not determine it — reported as unknown,
+ * never as zero, because "we did not look" and "there were none" must not render alike.
+ */
+function actionsRunObservation(run) {
+  const name = String(run?.name ?? '')
+  const path = run?.path ?? null
+  const jobCount = Number.isInteger(run?.jobCount) ? run.jobCount : null
+  const state = stateOf(run?.status, run?.conclusion)
+  const completed = COMPLETED.has(lower(run?.status) ?? '')
+  return {
+    source: 'actions-run',
+    name,
+    state,
+    status: run?.status ?? null,
+    conclusion: run?.conclusion ?? null,
+    app: 'github-actions',
+    checkSuiteId: run?.check_suite_id ?? null,
+    url: run?.html_url ?? null,
+    runId: run?.id ?? null,
+    path,
+    event: run?.event ?? null,
+    jobCount,
+    // Recorded, never classified on. The obvious reading of "is this run attached to the
+    // pull request?" is the API's `pull_requests` array, and it is not usable: at
+    // ee5dd91a the perfectly healthy `pull_request`-event `Skill gates` run also carries
+    // `pull_requests: []`. Deriving an attachment boolean from it would report every
+    // healthy run as unattached. `event` is what actually distinguishes an out-of-band
+    // dispatch, and it is what `absenceReason` uses.
+    pullRequests: Array.isArray(run?.pull_requests) ? run.pull_requests.map((entry) => entry?.number ?? null) : [],
+    nameEqualsPath: nonEmpty(path) && name === path,
+    looksLikeWorkflowPath: WORKFLOW_PATH.test(name),
+    zeroJobs: completed && jobCount === 0,
+  }
+}
+
+/** Raw Actions runs (each optionally carrying an integer `jobCount`) as observations. */
+export function observeActionsRuns(runs) {
+  return (Array.isArray(runs) ? runs : []).map(actionsRunObservation)
+}
+
+/**
+ * The #1081 signature: a run that COMPLETED, executed zero jobs, and did not succeed.
+ *
+ * Kept distinct from "a red run" on purpose. A red run with jobs failed while doing its
+ * work and its jobs say why; a red run with no jobs never started, and nothing else in
+ * the system says so — no check-run exists to be red. The name-equals-path corroboration
+ * is reported alongside rather than required, because a workflow with no declared `name:`
+ * produces the same coincidence honestly.
+ */
+export function startupFailures(observations) {
+  return observations
+    .filter((entry) => entry.source === 'actions-run' && entry.zeroJobs && entry.state !== 'green')
+    .map((entry) => ({
+      runId: entry.runId,
+      name: entry.name,
+      path: entry.path,
+      event: entry.event,
+      conclusion: entry.conclusion,
+      state: entry.state,
+      nameEqualsPath: entry.nameEqualsPath,
+      looksLikeWorkflowPath: entry.looksLikeWorkflowPath,
+      url: entry.url,
+    }))
+}
+
+/**
+ * Why a required check produced no observation at all. This is #1058's distinction and
+ * it falls out of the same union: the three answers call for opposite responses, and the
+ * single string they share today ("no workflow run found") reads as *still queued* for
+ * all three.
+ */
+export function ciAbsence(observations) {
+  const actionsRuns = (observations || []).filter((entry) => entry.source === 'actions-run')
+  return absenceReason(observations || [], actionsRuns)
+}
+
+function absenceReason(observations, actionsRuns) {
+  if (observations.some((entry) => entry.state === 'pending')) {
+    return {
+      reason: 'pending',
+      detail: 'a run for this SHA has not finished; waiting is correct and dispatching another would waste a run',
+    }
+  }
+  if (observations.length === 0) {
+    return {
+      reason: 'no-run-anywhere',
+      detail: 'no check-run, commit status or Actions run exists for this SHA — the triggering event was most likely never delivered; waiting is futile, a workflow_dispatch or a close/reopen at the same head is the intervention',
+    }
+  }
+  // #1058's third state: a run exists at this SHA, but it got there by hand. The check
+  // it produced is honest exact-head evidence and satisfies no merge-queue condition,
+  // and the situation is actionable NOW rather than something to wait out.
+  const dispatched = actionsRuns.filter((entry) => entry.event === 'workflow_dispatch')
+  if (dispatched.length && dispatched.length === actionsRuns.length) {
+    return {
+      reason: 'dispatched-out-of-band',
+      detail: `every Actions run at this SHA was started by workflow_dispatch (${dispatched.map((entry) => entry.runId).join(', ')}) — the event that would have created this check was never delivered; the dispatched run is honest exact-head evidence but satisfies no merge-queue check condition, so delivery still needs the event`,
+    }
+  }
+  return {
+    reason: 'absent-though-runs-completed',
+    detail: 'runs for this SHA have completed without ever producing this check — inspect the workflow trigger and path filters, and the startupFailures channel: a workflow GitHub refuses to parse creates a run and produces no check-run at all',
+  }
+}
+
+/**
+ * Classify the full observed state of one head SHA.
+ *
+ * @param {object} input
+ * @param {string} input.repository            owner/name
+ * @param {string} input.headSha               the 40-character commit being described
+ * @param {object[]} [input.checkRuns]         raw `GET /commits/{sha}/check-runs` entries
+ * @param {object[]} [input.statuses]          raw `GET /commits/{sha}/status` `.statuses` entries
+ * @param {object[]} [input.actionsRuns]       raw `GET /actions/runs?head_sha=` entries, each
+ *                                             optionally carrying an integer `jobCount`
+ * @param {object|null} [input.plan]           a required-check plan; OPTIONAL — with none, nothing
+ *                                             is required and this degrades to a pure observation
+ *                                             report rather than calling every red undeclared
+ * @param {string} [input.collectedAt]
+ */
+export function classifyHeadCheckSet({
+  repository,
+  headSha,
+  checkRuns = [],
+  statuses = [],
+  actionsRuns = [],
+  plan = null,
+  collectedAt = new Date().toISOString(),
+}) {
+  const observations = [
+    ...checkRuns.map(checkRunObservation),
+    ...statuses.map(commitStatusObservation),
+    ...actionsRuns.map(actionsRunObservation),
+  ]
+  const required = requiredCheckNames(plan)
+  const requiredSet = new Set(required)
+  for (const entry of observations) entry.required = requiredSet.has(entry.name)
+
+  const observedNames = new Set(observations.map((entry) => entry.name))
+  const actionsObservations = observations.filter((entry) => entry.source === 'actions-run')
+
+  const red = observations.filter((entry) => entry.state === 'red')
+  const partition = {
+    requiredRed: red.filter((entry) => entry.required),
+    // The #1081 case. Informational by contract — see this file's header — but never silent.
+    undeclaredRed: red.filter((entry) => !entry.required),
+    neverRan: required
+      .filter((name) => !observedNames.has(name))
+      .map((name) => ({ name, ...absenceReason(observations, actionsObservations) })),
+    pending: observations.filter((entry) => entry.state === 'pending'),
+    neutral: observations.filter((entry) => entry.state === 'neutral'),
+    green: observations.filter((entry) => entry.state === 'green'),
+  }
+  const signatures = { startupFailures: startupFailures(observations) }
+
+  // Outcome ordering is the caller's decision order, and `green-with-undeclared-red` is
+  // deliberately its own value rather than folded into either neighbour: it is the state
+  // #1081 was in for seven hours, and it must be neither "failure" (it does not block)
+  // nor "green" (it is not).
+  let outcome = 'green'
+  if (partition.requiredRed.length) outcome = 'required-red'
+  else if (partition.neverRan.length) outcome = 'required-missing'
+  else if (partition.pending.length) outcome = 'pending'
+  else if (partition.undeclaredRed.length || signatures.startupFailures.length) outcome = 'green-with-undeclared-red'
+
+  return {
+    version: HEAD_CHECK_SET_VERSION,
+    kind: HEAD_CHECK_SET_KIND,
+    repository,
+    headSha,
+    collectedAt,
+    planned: { required, planPresent: plan != null },
+    observations,
+    signatures,
+    partition,
+    summary: {
+      outcome,
+      counts: {
+        observations: observations.length,
+        checkRuns: checkRuns.length,
+        commitStatuses: statuses.length,
+        actionsRuns: actionsRuns.length,
+        requiredRed: partition.requiredRed.length,
+        undeclaredRed: partition.undeclaredRed.length,
+        neverRan: partition.neverRan.length,
+        pending: partition.pending.length,
+        startupFailures: signatures.startupFailures.length,
+      },
+    },
+  }
+}
+
+/**
+ * True when the REQUIRED set — and only the required set — is unsatisfied.
+ *
+ * This is the whole of the blocking judgement, isolated here so that the one place a
+ * caller could turn undeclared red into a merge decision is a single named function
+ * rather than an exit-code expression buried in a CLI.
+ */
+export function blocksOnRequiredSet(artifact) {
+  return (artifact?.partition?.requiredRed?.length ?? 0) > 0
+    || (artifact?.partition?.neverRan?.length ?? 0) > 0
+}
+
+export function validateHeadCheckSetArtifact(artifact, { expectedHeadSha, label = 'headCheckSet' } = {}) {
+  const errors = []
+  if (!isObject(artifact)) return { ok: false, errors: [`${label} must be an object`] }
+  if (artifact.version !== HEAD_CHECK_SET_VERSION) errors.push(`${label}.version must be ${HEAD_CHECK_SET_VERSION}`)
+  if (artifact.kind !== HEAD_CHECK_SET_KIND) errors.push(`${label}.kind must be "${HEAD_CHECK_SET_KIND}"`)
+  if (!nonEmpty(artifact.repository) || !/^[^/\s]+\/[^/\s]+$/.test(artifact.repository)) errors.push(`${label}.repository must be owner/name`)
+  if (!nonEmpty(artifact.headSha) || !SHA.test(artifact.headSha)) errors.push(`${label}.headSha must be a full 40-character commit SHA`)
+  else if (expectedHeadSha && artifact.headSha !== expectedHeadSha) errors.push(`${label} is STALE: stamped ${artifact.headSha}, expected ${expectedHeadSha}`)
+  if (!Array.isArray(artifact.observations)) errors.push(`${label}.observations must be an array`)
+  else {
+    for (const [index, entry] of artifact.observations.entries()) {
+      const at = `${label}.observations[${index}]`
+      if (!isObject(entry)) { errors.push(`${at} must be an object`); continue }
+      if (!OBSERVATION_SOURCES.includes(entry.source)) errors.push(`${at}.source must be ${OBSERVATION_SOURCES.join('|')}`)
+      if (!nonEmpty(entry.name)) errors.push(`${at}.name must be a non-empty string`)
+      if (!OBSERVATION_STATES.includes(entry.state)) errors.push(`${at}.state must be ${OBSERVATION_STATES.join('|')}`)
+      if (typeof entry.required !== 'boolean') errors.push(`${at}.required must be boolean`)
+    }
+  }
+  if (!isObject(artifact.partition)) errors.push(`${label}.partition must be an object`)
+  else {
+    for (const key of ['requiredRed', 'undeclaredRed', 'neverRan', 'pending', 'neutral', 'green']) {
+      if (!Array.isArray(artifact.partition[key])) errors.push(`${label}.partition.${key} must be an array`)
+    }
+    for (const [index, entry] of (artifact.partition.neverRan || []).entries()) {
+      const at = `${label}.partition.neverRan[${index}]`
+      if (!isObject(entry) || !nonEmpty(entry.name)) errors.push(`${at}.name must be a non-empty string`)
+      // The reason is the entire point of the row: an absence without one reads as
+      // "still queued" for all three of #1058's cases.
+      else if (!nonEmpty(entry.reason) || !nonEmpty(entry.detail)) errors.push(`${at} requires an actionable reason and detail`)
+    }
+  }
+  if (!isObject(artifact.signatures) || !Array.isArray(artifact.signatures.startupFailures)) errors.push(`${label}.signatures.startupFailures must be an array`)
+  if (!isObject(artifact.summary) || !nonEmpty(artifact.summary.outcome)) errors.push(`${label}.summary.outcome must be a non-empty string`)
+  return { ok: errors.length === 0, errors }
+}
+
+function describe(entry) {
+  const detail = entry.source === 'actions-run'
+    ? ` — run ${entry.runId ?? '?'}, event ${entry.event ?? '?'}, ${entry.jobCount === null ? 'job count unknown' : `${entry.jobCount} job(s)`}`
+    : ''
+  return `${entry.name} [${entry.source}] ${entry.conclusion ?? entry.status ?? 'pending'}${detail}`
+}
+
+export function renderHeadCheckSet(artifact) {
+  const lines = [
+    '<!-- generated by head-check-set.mjs — do not hand-edit; re-run collect -->',
+    `**Full check set at \`${artifact.headSha}\`** (${artifact.repository}, collected ${artifact.collectedAt})`,
+    '',
+    `- Outcome: **${artifact.summary?.outcome}** — ${artifact.summary?.counts?.observations ?? 0} observation(s) across `
+      + `${artifact.summary?.counts?.checkRuns ?? 0} check-run(s), ${artifact.summary?.counts?.commitStatuses ?? 0} commit status(es), `
+      + `${artifact.summary?.counts?.actionsRuns ?? 0} Actions run(s)`,
+    `- Required by the plan: ${artifact.planned?.planPresent ? (artifact.planned.required.join(', ') || 'none') : 'NO PLAN SUPPLIED — nothing is classified required, so this is an observation report only'}`,
+  ]
+  const section = (title, rows) => {
+    if (!rows.length) return
+    lines.push(`- ${title}:`)
+    for (const row of rows) lines.push(`  - ${row}`)
+  }
+  section('REQUIRED and red (blocking under the existing contract)', artifact.partition?.requiredRed?.map(describe) ?? [])
+  section(
+    'NOT required and red (informational — surfaced, never gated here; whether it should block belongs to `.mergify.yml` and the human)',
+    artifact.partition?.undeclaredRed?.map(describe) ?? [],
+  )
+  section(
+    'Required but never ran at all',
+    artifact.partition?.neverRan?.map((row) => `${row.name}: ${row.reason} — ${row.detail}`) ?? [],
+  )
+  section(
+    'Workflow runs that completed having executed ZERO jobs (the #1081 startup-failure signature)',
+    artifact.signatures?.startupFailures?.map((row) =>
+      `run ${row.runId} \`${row.name}\` (${row.conclusion}) executed no jobs`
+      + `${row.nameEqualsPath ? ' and its name equals its file path — corroborating a workflow GitHub refused to parse' : ''}`) ?? [],
+  )
+  section('Pending', artifact.partition?.pending?.map(describe) ?? [])
+  return lines.join('\n')
+}

package/skills/engineering/engineering-runtime/scripts/main-module.mjs

@@ -0,0 +1,80 @@
+// The one ESM main-module guard every skill script in this repo uses.
+//
+// Not a style preference — the hand-written versions of this three-line check had two opposite
+// silent failure modes in production, and both shipped:
+//
+//   #718  `import.meta.url === pathToFileURL(process.argv[1]).href`
+//         Node resolves `import.meta.url` to the REAL path; `argv[1]` keeps whatever the caller
+//         typed. A skills install is a symlink farm (`~/.claude/skills/<skill>` → the checkout),
+//         so through the install path the two never match: the CLI does not run and node exits 0.
+//         `coverage-ledger.mjs` shipped this and recorded a false pass in the wild
+//         (a consumer product repo: epic #352, unit #379, PR #384) on a gate whose only job is to
+//         say no. Fails OPEN, invisibly — "passed" and "never ran" are byte-identical evidence.
+//
+//   #446  `fs.realpathSync(process.argv[1]) === …`, unguarded.
+//         `node -` sets `argv[1]` to the literal string `"-"` — truthy, so the usual
+//         `process.argv[1] &&` prefix does not save it — and realpath throws ENOENT at MODULE
+//         LOAD, before a line of the module's own code runs. The module cannot be imported by
+//         anything that does not launch it as a file. Fails CLOSED, at load.
+//
+// So the contract has exactly two obligations, one per failure mode:
+//   1. realpath BOTH sides before comparing, so a symlinked invocation is still the main module;
+//   2. degrade to `false` — "not the main module" — for anything that does not resolve, never throw.
+//
+// WHY IT IS SHARED RATHER THAN COPIED. PR #278 fixed twelve copies of failure mode #718 by hand and
+// mechanized nothing. Five weeks later `mergify/scripts/audit.mjs` was written with the pre-#278
+// form, and `coverage-ledger.mjs` survived the whole pass because it spelled the same bug a third
+// way that #278's grep did not match. One module plus `main-guard-hygiene.test.mjs` is what stops
+// the next copy: there is now no second place for this logic to drift to, and adding one fails CI.
+//
+// WHERE IT LIVES, AND WHY HERE. Native Skills CLI installation flattens selected packages into
+// sibling directories under `~/.agents/skills`, while this repository nests them under
+// `skills/engineering`. A Workflow consumer at `<skill>/scripts` therefore imports
+// `../../engineering-runtime/scripts/main-module.mjs`: the same specifier reaches this package in
+// both layouts. Claude Code launches through a per-skill symlink into the canonical store; node's
+// realpath-aware module resolution and this predicate preserve that path as well.
+//
+// `engineering-runtime` owns the helper as an installable support package rather than a user
+// capability. `resolve-issues/scripts/sandbox-selftest.mjs` reconstructs the same sibling layout and
+// links this package beside the skill under test. Every consumer imports this package directly.
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Is the module identified by `importMetaUrl` the script node was launched with?
+ *
+ * Symlink-transparent, and total: any input that does not resolve to a real file answers `false`
+ * instead of throwing, so importing a CLI module is always safe.
+ *
+ * @param {string} importMetaUrl the caller's own `import.meta.url`
+ * @returns {boolean}
+ */
+export function isMainModule(importMetaUrl) {
+  const entry = process.argv[1];
+  if (typeof entry !== 'string' || entry === '') return false; // imported, or an embedding harness
+
+  let entryPath;
+  try {
+    entryPath = fs.realpathSync(entry);
+  } catch {
+    return false; // #446: `node -` gives "-"; some harnesses give a path that is not on disk
+  }
+
+  let selfPath;
+  try {
+    selfPath = fileURLToPath(importMetaUrl);
+  } catch {
+    return false; // a data:/http: module has no path to compare, so it is never the launched script
+  }
+  try {
+    // #718: the launched side is resolved above, so this side must be too. Under Node's default
+    // resolution `import.meta.url` is already real and this is a no-op; under `--preserve-symlinks`
+    // it is the half that makes the comparison hold.
+    selfPath = fs.realpathSync(selfPath);
+  } catch {
+    // The module is executing, so it existed a moment ago. Compare what we have rather than
+    // claiming "not main" — a vanished file should not silently disable a running CLI.
+  }
+
+  return entryPath === selfPath;
+}

package/skills/engineering/engineering-runtime/scripts/mergify-yaml.mjs

@@ -0,0 +1,11 @@
+import { DEFAULT_SCHEMA, load } from "js-yaml"
+
+export function parseMergifyYaml(yaml) {
+  try {
+    const value = load(String(yaml || ""), { schema: DEFAULT_SCHEMA, json: false })
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Mergify YAML root must be a mapping")
+    return value
+  } catch (error) {
+    throw new Error(`Mergify YAML structural parse failed closed: ${String(error.message || error).trim()}`)
+  }
+}