@1aboveio/skills 0.10.0

package/skills/engineering/engineering-runtime/scripts/package-lock.json

@@ -0,0 +1,43 @@
+{
+  "name": "engineering-runtime",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "engineering-runtime",
+      "version": "1.0.0",
+      "dependencies": {
+        "js-yaml": "4.3.1"
+      }
+    },
+    "node_modules/argparse": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmmirror.com/argparse/-/argparse-2.0.1.tgz",
+      "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
+      "license": "Python-2.0"
+    },
+    "node_modules/js-yaml": {
+      "version": "4.3.1",
+      "resolved": "https://registry.npmmirror.com/js-yaml/-/js-yaml-4.3.1.tgz",
+      "integrity": "sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/puzrin"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/nodeca"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^2.0.1"
+      },
+      "bin": {
+        "js-yaml": "bin/js-yaml.js"
+      }
+    }
+  }
+}

package/skills/engineering/engineering-runtime/scripts/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "engineering-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Engineering Workflow runtime dependency closure",
+  "dependencies": {
+    "js-yaml": "4.3.1"
+  }
+}

package/skills/engineering/engineering-runtime/scripts/required-check-plan.mjs

@@ -0,0 +1,223 @@
+// Versioned required-check plans bind merge-admission discovery and execution
+// evidence to one frozen head. Epic-892 showed that supplied green jobs alone
+// cannot claim completeness: the omitted `skill-size` gate failed after publish.
+
+export const REQUIRED_CHECK_PLAN_VERSION = 1
+export const CHECK_PHASES = Object.freeze(['pr-head', 'queue-head'])
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0
+const strings = (value) => Array.isArray(value) && value.every(nonEmpty) && new Set(value).size === value.length
+const SHA = /^[0-9a-f]{40}$/i
+
+function exactObject(value, fields, label, errors) {
+  if (!isObject(value)) { errors.push(`${label} must be an object`); return false }
+  const unknown = Object.keys(value).find((key) => !fields.includes(key))
+  if (unknown) errors.push(`${label} has unknown property ${unknown}`)
+  return true
+}
+
+function conditionTree(value, label, errors) {
+  if (!isObject(value)) { errors.push(`${label} must be a condition tree object`); return [] }
+  const keys = Object.keys(value)
+  if (keys.length !== 1 || !['condition', 'all', 'any'].includes(keys[0])) {
+    errors.push(`${label} must contain exactly one of condition|all|any`)
+    return []
+  }
+  if (keys[0] === 'condition') return nonEmpty(value.condition) ? [value.condition] : (errors.push(`${label}.condition must be a non-empty string`), [])
+  if (!Array.isArray(value[keys[0]]) || value[keys[0]].length === 0) {
+    errors.push(`${label}.${keys[0]} must be a non-empty array`)
+    return []
+  }
+  return value[keys[0]].flatMap((child, index) => conditionTree(child, `${label}.${keys[0]}[${index}]`, errors))
+}
+
+function validateDiscoverySource(value, label, errors, { github = false } = {}) {
+  const fields = github ? ['conditions', 'trees', 'rulesets'] : ['conditions', 'trees', 'phases']
+  if (!exactObject(value, fields, label, errors)) return
+  if (!strings(value.conditions)) errors.push(`${label}.conditions must preserve live merge-admission conditions`)
+  if (!Array.isArray(value.trees) || value.trees.length === 0) {
+    errors.push(`${label}.trees must preserve every live merge-admission condition tree`)
+    return
+  }
+  const leaves = value.trees.flatMap((tree, index) => conditionTree(tree, `${label}.trees[${index}]`, errors))
+  const preserved = new Set(value.conditions || [])
+  for (const leaf of leaves) if (!preserved.has(leaf)) errors.push(`${label}.trees contains condition absent from ${label}.conditions: ${leaf}`)
+  for (const condition of value.conditions || []) if (!leaves.includes(condition)) errors.push(`${label}.conditions omits condition tree leaf: ${condition}`)
+  if (github) {
+    return
+  }
+  // Pre-phase fixture plans remain readable as PR-head-only plans. Live discovery
+  // always writes phases; it cannot omit queue-head requirements.
+  if (value.phases === undefined) return
+  if (!Array.isArray(value.phases) || !value.phases.length) {
+    errors.push(`${label}.phases must preserve every live Mergify lifecycle phase`)
+    return
+  }
+  const ids = new Set()
+  for (const [index, phase] of value.phases.entries()) {
+    const at = `${label}.phases[${index}]`
+    if (!exactObject(phase, ['id', 'phase', 'source', 'trees', 'conditions'], at, errors)) continue
+    if (!nonEmpty(phase.id) || ids.has(phase.id)) errors.push(`${at}.id must be a unique non-empty source identity`)
+    else ids.add(phase.id)
+    if (!CHECK_PHASES.includes(phase.phase)) errors.push(`${at}.phase must be ${CHECK_PHASES.join('|')}`)
+    if (!nonEmpty(phase.source)) errors.push(`${at}.source must be a non-empty source identity`)
+    if (!strings(phase.conditions)) errors.push(`${at}.conditions must preserve this phase's condition leaves`)
+    const phaseLeaves = Array.isArray(phase.trees)
+      ? phase.trees.flatMap((tree, treeIndex) => conditionTree(tree, `${at}.trees[${treeIndex}]`, errors))
+      : []
+    if (!Array.isArray(phase.trees) || !phase.trees.length) errors.push(`${at}.trees must be a non-empty array`)
+    for (const leaf of phaseLeaves) if (!preserved.has(leaf)) errors.push(`${at}.trees contains condition absent from ${label}.conditions: ${leaf}`)
+    for (const leaf of phaseLeaves) if (!phase.conditions?.includes(leaf)) errors.push(`${at}.conditions omits phase tree leaf: ${leaf}`)
+    for (const condition of phase.conditions || []) if (!phaseLeaves.includes(condition)) errors.push(`${at}.conditions has leaf absent from its trees: ${condition}`)
+  }
+}
+
+export function checksForPhase(plan, phase) {
+  return (plan?.checks || []).filter((check) => check?.admission === 'required' && (Array.isArray(check?.phases) ? check.phases.includes(phase) : phase === 'pr-head'))
+}
+
+export function locallyReproducedJobs(plan, phase = 'pr-head') {
+  return checksForPhase(plan, phase)
+    .filter((check) => check.classification === 'locally-reproduced')
+    .map((check) => check.evidence?.job)
+    .filter(nonEmpty)
+    .sort()
+}
+
+export function validateRequiredCheckPlan(plan, { expectedHeadSha, requireEvidence = false, label = 'requiredCheckPlan' } = {}) {
+  const errors = []
+  if (!isObject(plan)) return { ok: false, errors: [`${label} is a legacy required-check manifest without requiredCheckPlan; rediscover GitHub rulesets and Mergify conditions, classify every live check, then regenerate exact-head evidence`] }
+  exactObject(plan, ['version', 'kind', 'repository', 'targetBranch', 'headSha', 'discovery', 'checks', 'allowedSkippedJobs'], label, errors)
+  if (![1, 2].includes(plan.version)) errors.push(`${label}.version must be 1 (legacy PR-head) or 2 (phase-aware lifecycle plan)`)
+  if (plan.kind !== 'required-check-plan') errors.push(`${label}.kind must be "required-check-plan"`)
+  if (!nonEmpty(plan.repository) || !/^[^/\s]+\/[^/\s]+$/.test(plan.repository)) errors.push(`${label}.repository must be owner/name`)
+  if (!nonEmpty(plan.targetBranch)) errors.push(`${label}.targetBranch must be a non-empty string`)
+  if (!nonEmpty(plan.headSha) || !SHA.test(plan.headSha)) errors.push(`${label}.headSha must be a full 40-character commit SHA`)
+  if (expectedHeadSha && plan.headSha !== expectedHeadSha) errors.push(`${label} is STALE: stamped ${plan.headSha}, expected ${expectedHeadSha}`)
+  if (exactObject(plan.discovery, ['github', 'mergify', 'requiredChecks'], `${label}.discovery`, errors)) {
+    if (!strings(plan.discovery.requiredChecks)) errors.push(`${label}.discovery.requiredChecks must be unique non-empty check names`)
+    validateDiscoverySource(plan.discovery.github, `${label}.discovery.github`, errors, { github: true })
+    validateDiscoverySource(plan.discovery.mergify, `${label}.discovery.mergify`, errors)
+    if (plan.version === 2 && !Array.isArray(plan.discovery.github?.rulesets)) errors.push(`${label}.discovery.github.rulesets must preserve applicable target-branch source conditions`)
+    if (plan.version === 2 && !Array.isArray(plan.discovery.mergify?.phases)) errors.push(`${label}.discovery.mergify.phases must preserve every lifecycle source`)
+  }
+  if (!strings(plan.allowedSkippedJobs)) errors.push(`${label}.allowedSkippedJobs must be unique non-empty job names`)
+  if (!Array.isArray(plan.checks) || plan.checks.length === 0) return { ok: false, errors: [...errors, `${label}.checks must be a non-empty array`] }
+  const names = new Set()
+  for (const [index, check] of plan.checks.entries()) {
+    const at = `${label}.checks[${index}]`
+    const allowedCheckFields = plan.version === 1 ? ['name', 'admission', 'classification', 'sources', 'evidence', 'changedPathExemption'] : ['name', 'admission', 'classification', 'sources', 'phases', 'evidence', 'queueEvidence', 'changedPathExemption']
+    if (!exactObject(check, allowedCheckFields, at, errors)) continue
+    if (!nonEmpty(check.name)) errors.push(`${at}.name must be a non-empty string`)
+    else if (names.has(check.name)) errors.push(`${label}.checks duplicates ${check.name}`)
+    else names.add(check.name)
+    if (!['required', 'exempted'].includes(check.admission)) errors.push(`${at}.admission must be required|exempted`)
+    if (!['locally-reproduced', 'publish-only'].includes(check.classification)) errors.push(`${at}.classification must be locally-reproduced|publish-only`)
+    if (!strings(check.sources) || !check.sources.length) errors.push(`${at}.sources must preserve discovery sources`)
+    if ((plan.version === 2 && check.phases === undefined) || (check.phases !== undefined && (!strings(check.phases) || !check.phases.length || check.phases.some((phase) => !CHECK_PHASES.includes(phase))))) errors.push(`${at}.phases must name one or more known evidence phases`)
+    if (check.admission === 'exempted' && (!isObject(check.changedPathExemption) || check.changedPathExemption.applies !== true || !nonEmpty(check.changedPathExemption.condition))) errors.push(`${at}.exempted check requires an explicit applicable changed-path exemption`)
+    if (check.classification === 'locally-reproduced') {
+      if (!isObject(check.evidence) || !nonEmpty(check.evidence.command) || !nonEmpty(check.evidence.job)) errors.push(`${at}.locally-reproduced evidence requires command and job`)
+      if (requireEvidence && check.admission === 'required' && (check.phases === undefined || check.phases.includes('pr-head')) && check.evidence?.result !== 'success') errors.push(`${at}.locally-reproduced evidence.result must be success; skipped is never success`)
+    } else {
+      if (!isObject(check.evidence) || !nonEmpty(check.evidence.provider) || !nonEmpty(check.evidence.reason)) errors.push(`${at}.publish-only evidence requires provider and reason`)
+      if (Object.hasOwn(check.evidence || {}, 'conclusion')) errors.push(`${at}.publish-only plan evidence must not embed a provider conclusion; use the separate provider artifact`)
+    }
+    if (check.admission === 'required' && check.phases?.includes('queue-head')) {
+      if (!isObject(check.queueEvidence) || !nonEmpty(check.queueEvidence.provider) || !nonEmpty(check.queueEvidence.acquisition)) {
+        errors.push(`${at}.queueEvidence requires a provider and acquisition path before enqueue; queue-head checks cannot be authorized from future synthetic evidence`)
+      }
+    } else if (check.queueEvidence !== undefined) {
+      errors.push(`${at}.queueEvidence is only meaningful for a required queue-head check`)
+    }
+  }
+  for (const name of plan.discovery?.requiredChecks || []) if (!names.has(name)) errors.push(`${label} omits live required check ${name}; epic-892 omitted skill-size, so green supplied jobs are not complete evidence`)
+  const local = new Set(locallyReproducedJobs(plan, 'pr-head'))
+  for (const skipped of plan.allowedSkippedJobs || []) if (local.has(skipped)) errors.push(`${label}.allowedSkippedJobs includes locally reproduced job ${skipped}; skipped is never success`)
+  return { ok: errors.length === 0, errors }
+}
+
+export function validatePublishOnlyEvidence(plan, evidence, { expectedHeadSha, expectedRepository, expectedPr, label = 'publishOnlyEvidence' } = {}) {
+  const errors = []
+  const expected = checksForPhase(plan, 'pr-head').filter((check) => check.classification === 'publish-only')
+  if (!Array.isArray(evidence)) return { ok: false, errors: [`${label} must be an array`] }
+  const byName = new Map()
+  for (const [index, item] of evidence.entries()) {
+    const at = `${label}[${index}]`
+    if (!exactObject(item, ['name', 'provider', 'repository', 'pr', 'headSha', 'conclusion'], at, errors)) continue
+    if (!nonEmpty(item.name) || !nonEmpty(item.provider)) errors.push(`${at}.name and provider must be non-empty strings`)
+    if (!nonEmpty(item.repository) || !/^[^/\s]+\/[^/\s]+$/.test(item.repository)) errors.push(`${at}.repository must be owner/name`)
+    else if (expectedRepository && item.repository !== expectedRepository) errors.push(`${at} repository mismatch: expected ${expectedRepository}, received ${item.repository}`)
+    if (!Number.isInteger(item.pr) || item.pr < 1) errors.push(`${at}.pr must be a positive integer`)
+    else if (expectedPr && item.pr !== expectedPr) errors.push(`${at} PR mismatch: expected ${expectedPr}, received ${item.pr}`)
+    if (!nonEmpty(item.headSha) || !SHA.test(item.headSha)) errors.push(`${at}.headSha must be a full 40-character commit SHA`)
+    else if (expectedHeadSha && item.headSha !== expectedHeadSha) errors.push(`${at} is STALE: stamped ${item.headSha}, expected ${expectedHeadSha}`)
+    if (item.conclusion !== 'success') errors.push(`${at}.conclusion must be success; skipped is never success`)
+    if (byName.has(item.name)) errors.push(`${label} has duplicate/ambiguous evidence for ${item.name}`)
+    else byName.set(item.name, item)
+  }
+  for (const check of expected) {
+    const item = byName.get(check.name)
+    if (!item) errors.push(`${label} is missing provider evidence for publish-only required check ${check.name}`)
+    else if (item.provider !== check.evidence?.provider) errors.push(`${label} provider mismatch for ${check.name}: expected ${check.evidence?.provider}, received ${item.provider}`)
+  }
+  for (const name of byName.keys()) if (!expected.some((check) => check.name === name)) errors.push(`${label} has evidence for non-PR-head publish-only check ${name}`)
+  return { ok: errors.length === 0, errors }
+}
+
+export function validateRequiredCheckExecution(plan, jobs, { expectedHeadSha } = {}) {
+  const planVerdict = validateRequiredCheckPlan(plan, { expectedHeadSha })
+  const errors = [...planVerdict.errors]
+  const byName = new Map(Array.isArray(jobs) ? jobs.filter(isObject).map((job) => [job.name, job]) : [])
+  if (!Array.isArray(jobs)) errors.push('workflow jobs must be an array')
+  for (const check of checksForPhase(plan, 'pr-head')) {
+    if (check.classification !== 'locally-reproduced') continue
+    const job = byName.get(check.evidence?.job)
+    if (!job) errors.push(`locally reproduced PR-head required check ${check.name} is missing workflow job ${check.evidence?.job}`)
+    else if (job.conclusion !== 'success') errors.push(`locally reproduced PR-head required check ${check.name} is ${job.conclusion ?? 'pending'}; skipped is never success`)
+  }
+  return { ok: errors.length === 0, errors }
+}
+
+// Queue/batch checks run on a provider-created synthetic head. This separate artifact
+// prevents PR-head authorization from fabricating delivery evidence.
+export function validateQueueExecutionArtifact(plan, artifact, { expectedRepository, expectedPr, expectedPrHeadSha, label = 'queueExecutionArtifact' } = {}) {
+  const errors = []
+  const required = checksForPhase(plan, 'queue-head')
+  if (!required.length) return { ok: artifact == null, errors: artifact == null ? [] : [`${label} is unnecessary because this plan has no queue-head checks`] }
+  if (!exactObject(artifact, ['version', 'kind', 'repository', 'pr', 'prHeadSha', 'queuePr', 'queueHeadSha', 'provider', 'checks', 'status'], label, errors)) return { ok: false, errors }
+  if (artifact.version !== 1 || artifact.kind !== 'queue-execution') errors.push(`${label} must be a version 1 queue-execution artifact`)
+  if (artifact.repository !== (expectedRepository ?? plan?.repository)) errors.push(`${label}.repository must equal the planned repository`)
+  if (!Number.isInteger(artifact.pr) || artifact.pr < 1 || (expectedPr && artifact.pr !== expectedPr)) errors.push(`${label}.pr must equal the planned PR`)
+  if (!Number.isInteger(artifact.queuePr) || artifact.queuePr < 1 || artifact.queuePr === artifact.pr) errors.push(`${label}.queuePr must identify a distinct provider-created synthetic queue pull request`)
+  if (artifact.prHeadSha !== (expectedPrHeadSha ?? plan?.headSha)) errors.push(`${label}.prHeadSha must equal the frozen PR head`)
+  if (!nonEmpty(artifact.queueHeadSha) || !SHA.test(artifact.queueHeadSha)) errors.push(`${label}.queueHeadSha must be a full synthetic queue SHA`)
+  else if (artifact.queueHeadSha === artifact.prHeadSha) errors.push(`${label}.queueHeadSha must differ from prHeadSha; synthetic queue evidence cannot bind to the PR SHA`)
+  const queueProviders = [...new Set(required.map((check) => check.queueEvidence?.provider))]
+  if (queueProviders.length !== 1 || !nonEmpty(queueProviders[0])) {
+    errors.push(`${label} requires exactly one non-empty provider across planned queue-head checks`)
+  }
+  const expectedProvider = queueProviders[0]
+  if (!nonEmpty(artifact.provider)) errors.push(`${label}.provider must identify the observing provider`)
+  else if (expectedProvider && artifact.provider !== expectedProvider) errors.push(`${label}.provider mismatch: expected ${expectedProvider}, received ${artifact.provider}`)
+  if (artifact.status !== 'pass') errors.push(`${label}.status must be "pass"`)
+  if (!Array.isArray(artifact.checks)) errors.push(`${label}.checks must be an array`)
+  const byName = new Map()
+  for (const [index, check] of (Array.isArray(artifact.checks) ? artifact.checks : []).entries()) {
+    const at = `${label}.checks[${index}]`
+    if (!exactObject(check, ['name', 'provider', 'conclusion', 'headSha'], at, errors)) continue
+    if (!nonEmpty(check.name) || !nonEmpty(check.provider)) errors.push(`${at}.name and provider must be non-empty strings`)
+    if (!nonEmpty(check.headSha) || !SHA.test(check.headSha)) errors.push(`${at}.headSha must be a full queue-head SHA`)
+    if (byName.has(check.name)) errors.push(`${label} has duplicate/ambiguous evidence for ${check.name}`)
+    else byName.set(check.name, check)
+  }
+  for (const check of required) {
+    const observed = byName.get(check.name)
+    if (!observed) errors.push(`${label} is missing queue-head evidence for ${check.name}`)
+    else if (observed.provider !== check.queueEvidence?.provider) errors.push(`${label} provider mismatch for queue-head check ${check.name}: expected ${check.queueEvidence?.provider}, received ${observed.provider}`)
+    else if (observed.conclusion !== 'success' || observed.headSha !== artifact.queueHeadSha) errors.push(`${label} queue-head check ${check.name} must succeed on queueHeadSha; skipped is never success`)
+  }
+  for (const name of byName.keys()) if (!required.some((check) => check.name === name)) errors.push(`${label} has evidence for non-queue-head check ${name}`)
+  return { ok: errors.length === 0, errors }
+}