@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/scripts/combine-and-verify.mjs

@@ -0,0 +1,721 @@
+// combine-and-verify — the MECHANIZED epic integration gate. It assembles the
+// cluster (creates an integration branch off the target, merges each unit's
+// branch in dependency order, captures conflicts) and reduces the gate results
+// into a single integration verdict whose status is ALIVE only when the combined
+// tree is assembled clean AND its CI, integrated review, and smoke all came back
+// green.
+//
+// The smoke gate has ONE honest exception (#393). A component in a repo with no
+// bootable surface / no curated golden-path manifest genuinely cannot run smoke —
+// this skills repo is the case in point (no root package.json, no app to boot). For
+// that, and ONLY that, smoke reaches its pass by an explicit, reasoned
+// `not-applicable`: the orchestrator records `gates.smoke = 'not-applicable'` AND a
+// top-level `smokeNotApplicableReason: '<why>'`. This is the SAME honesty pattern as
+// green-gate's N/A: an N/A-with-reason is NOT a pass fabricated to get green. The
+// guardrails are sharp — an N/A with no reason fails closed (treated like a missing
+// gate); a MISSING smoke field is still DEAD (missing ≠ N/A, never a silent default);
+// `pending`/`DEAD`/`EMPTY` still fail; and a repo that CAN boot still owes a real
+// ALIVE. Fabricating `smoke: 'ALIVE'` where the app never ran is still forbidden —
+// the reasoned N/A is the alternative to that fabrication, and `verdict`/`mergeable`
+// surface it in the handoff so a merge-without-smoke is recorded, never buried.
+//
+// Why this exists as a script and not prose: the integration gate is a
+// load-bearing, late-in-a-long-run step. Described in prose it degrades to a
+// lookalike or gets skipped ("no cluster"). Mechanized, it cannot be forgotten —
+// and its `integration-verdict.json` is the forcing artifact a merge/promote
+// step refuses to proceed without. "No artifact, or status DEAD" = the gate did
+// not pass = do not merge.
+//
+//   node combine-and-verify.mjs validate  --units units.json
+//   node combine-and-verify.mjs assemble  --units units.json --target dev --branch integ/epic-42 --out integration-verdict.json
+//   node combine-and-verify.mjs verdict   --in integration-verdict.json   # exit 0 = ALIVE, 1 = DEAD
+//   node combine-and-verify.mjs mergeable --in integration-verdict.json --manifest run-manifest.json --component <id> --pr <ref> [--deps id:ref,…]
+//                                # step-7 gate: exit 0 = safe to merge, 1 = no. Authorization is READ from the
+//                                # manifest's mergeShippable (never a flag); ancestry checks fetch + use origin/<target>.
+//
+// units.json is the cluster roster (from the run manifest): an array of
+// { id, branch, dependsOn?: [ids] }. The CI / review / smoke results are filled
+// into the verdict's `gates` by the agent steps that run those skills; this
+// script owns the decidable shell — merge order, the git assembly, and the
+// gate arithmetic — never the judgment (review) or the driving (smoke).
+
+import fs from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import { validateExactHeadArtifact } from '../../engineering-runtime/scripts/exact-head-artifact.mjs'
+import { checksForPhase, validateQueueExecutionArtifact } from '../../engineering-runtime/scripts/required-check-plan.mjs'
+import { targetBaseDrift, validateComponentCandidates } from './component-candidate.mjs'
+import { completionBlockers } from './unit-lifecycle.mjs'
+
+// ---- pure, unit-testable core (no git, no network) ----
+
+// The gates that must each be green for the combined tree to be ALIVE, and the
+// single value each must hold. Anything else — including the `pending` the
+// assemble step writes — keeps the verdict DEAD. That is the forcing function:
+// the artifact stays DEAD until the real sub-results are recorded.
+//
+// `smoke` has one extra pass value beyond `ALIVE`: an explicit, reasoned
+// `not-applicable` (see the file header and `SMOKE_NOT_APPLICABLE` /
+// `computeIntegrationVerdict`). ci and review have NO such exception — only smoke
+// gains it, because only smoke can be genuinely unrunnable (no bootable surface).
+export const GATE_PASS = { ci: 'green', review: 'PASS', smoke: 'ALIVE' }
+
+// The third, explicitly-reasoned smoke state (#393): NOT a pass on its own — it
+// passes ONLY when accompanied by a top-level `smokeNotApplicableReason` on the
+// verdict. Absent the reason it fails closed, exactly like a missing gate.
+export const SMOKE_NOT_APPLICABLE = 'not-applicable'
+
+// Structural validation of the cluster roster. Decidable, zero-judgment.
+export function validateUnits(units) {
+  const errors = []
+  if (!Array.isArray(units) || units.length === 0) {
+    return { ok: false, errors: ['units must be a non-empty array — an integration gate over no units proves nothing'] }
+  }
+  const ids = new Set()
+  for (const [i, u] of units.entries()) {
+    const at = `units[${i}]${u && u.id ? ` (${u.id})` : ''}`
+    if (!u || typeof u !== 'object') { errors.push(`${at}: not an object`); continue }
+    if (!u.id) errors.push(`${at}: missing id`)
+    else if (ids.has(u.id)) errors.push(`${at}: duplicate id "${u.id}"`)
+    else ids.add(u.id)
+    if (!u.branch) errors.push(`${at}: missing branch`)
+  }
+  for (const u of units) {
+    for (const dep of u.dependsOn || []) {
+      if (!ids.has(dep)) errors.push(`unit "${u.id}": dependsOn unknown unit "${dep}"`)
+    }
+  }
+  return { ok: errors.length === 0, errors }
+}
+
+// Dependency-order the units (topological sort), preserving input order among
+// independent units so merges are stable and break-attribution is clean. Throws
+// on a cycle — an unorderable cluster is a finding, not a silent arbitrary order.
+export function mergeOrder(units) {
+  const byId = new Map(units.map((u) => [u.id, u]))
+  const state = new Map() // id -> 0 unvisited | 1 in-progress | 2 done
+  const order = []
+  const visit = (id, stack) => {
+    if (state.get(id) === 2) return
+    if (state.get(id) === 1) throw new Error(`dependency cycle: ${[...stack, id].join(' → ')}`)
+    state.set(id, 1)
+    for (const dep of byId.get(id).dependsOn || []) {
+      if (byId.has(dep)) visit(dep, [...stack, id])
+    }
+    state.set(id, 2)
+    order.push(id)
+  }
+  for (const u of units) visit(u.id, [])
+  return order
+}
+
+export function consumeQueueExecutionArtifact(verdict = {}, artifact) {
+  const plan = verdict.requiredCheckPlan ?? verdict.exactHeadEvidence?.requiredCheckPlan ?? null
+  const validation = validateQueueExecutionArtifact(plan, artifact, {
+    expectedRepository: plan?.repository,
+    expectedPr: verdict.combinedPr ?? undefined,
+    expectedPrHeadSha: verdict.integrationHeadSha,
+  })
+  return {
+    ...verdict,
+    gates: { ...(verdict.gates || {}), queueExecution: validation.ok ? 'pass' : 'fail' },
+    queueExecutionEvidence: validation.ok ? artifact : { errors: validation.errors },
+  }
+}
+
+export function consumeExactHeadArtifact(verdict = {}, artifact) {
+  const expectedHeadSha = verdict.integrationHeadSha
+  const validation = expectedHeadSha
+    ? validateExactHeadArtifact(artifact, { expectedHeadSha })
+    : { ok: false, errors: ['integrationHeadSha is not recorded — cannot bind exact-head evidence'] }
+  const provenance = artifact?.collectionMode === 'choreographed'
+    ? { kind: 'choreographed', restorationProved: artifact?.restoration?.proved === true }
+    : artifact?.collectionMode === 'observed-existing-run'
+      ? {
+          kind: 'observed-existing-run',
+          headObservedBeforeAndAfter: artifact?.observation?.before?.headSha === artifact?.headSha
+            && artifact?.observation?.after?.headSha === artifact?.headSha,
+          workflowRunId: artifact?.workflow?.runId ?? null,
+        }
+      : { kind: null }
+  return {
+    ...verdict,
+    gates: { ...(verdict.gates || {}), exactHead: validation.ok ? 'pass' : 'fail' },
+    requiredCheckPlan: artifact?.requiredCheckPlan ?? null,
+    exactHeadEvidence: {
+      collectionMode: artifact?.collectionMode ?? null,
+      headSha: artifact?.headSha ?? null,
+      outcome: artifact?.summary?.outcome ?? null,
+      jobs: Array.isArray(artifact?.jobs)
+        ? artifact.jobs.map(({ id, name, status, conclusion }) => ({ id, name, status: status ?? null, conclusion }))
+        : [],
+      provenance,
+      errors: validation.errors,
+    },
+  }
+}
+
+// Reduce the assembled result + the gate results into the integration verdict.
+// ALIVE iff: assembled with no conflicts AND every gate holds its pass value.
+// A `pending` / missing / wrong gate value keeps it DEAD, with the reason named.
+//
+// `smoke` alone has a third pass state — an explicit, reasoned `not-applicable`
+// (#393): for a repo with no bootable surface, `gates.smoke = 'not-applicable'`
+// PLUS a non-empty top-level `smokeNotApplicableReason` reaches ALIVE. Fail-closed
+// guardrails: an N/A with no reason is DEAD (unreasoned, treated like a missing
+// gate); a MISSING smoke field is DEAD (missing ≠ N/A); `pending`/`DEAD`/`EMPTY`
+// stay DEAD; `ALIVE` is still the real pass a bootable repo owes. ci and review get
+// no exception — the special-case is scoped to smoke.
+export function computeIntegrationVerdict({ assembled, conflicts = [], gates = {}, smokeNotApplicableReason, integrationHeadSha, requiredCheckPlan } = {}) {
+  const reasons = []
+  if (!assembled) reasons.push('assembly did not complete')
+  if (conflicts.length) reasons.push(`merge conflict(s): ${conflicts.map((c) => c.unit).join(', ')} — route each back to the owning unit (do not hand-resolve)`)
+  if (integrationHeadSha && gates.exactHead !== 'pass') {
+    reasons.push(`gate "exactHead" is ${gates.exactHead == null ? 'not recorded' : `"${gates.exactHead}"`}, needs "pass" from a validated exact-head artifact`)
+  }
+  for (const [gate, want] of Object.entries(GATE_PASS)) {
+    const got = gates[gate]
+    if (gate === 'smoke') {
+      if (got === want) continue                                   // real ALIVE — the pass a bootable repo owes
+      if (got === SMOKE_NOT_APPLICABLE) {
+        const reason = typeof smokeNotApplicableReason === 'string' && smokeNotApplicableReason.trim()
+        if (reason) continue                                       // honest N/A: passes, surfaced in the handoff
+        reasons.push(`gate "smoke" is "${SMOKE_NOT_APPLICABLE}" but no smokeNotApplicableReason was recorded — an unreasoned N/A fails closed, exactly like a missing gate`)
+        continue
+      }
+      // missing / pending / DEAD / EMPTY / any other value: still DEAD (missing ≠ N/A).
+      reasons.push(`gate "smoke" is ${got == null ? 'not recorded' : `"${got}"`}, needs "${want}" (or "${SMOKE_NOT_APPLICABLE}" with a smokeNotApplicableReason for a repo with no bootable surface)`)
+      continue
+    }
+    if (got !== want) reasons.push(`gate "${gate}" is ${got == null ? 'not recorded' : `"${got}"`}, needs "${want}"`)
+  }
+  return { status: reasons.length === 0 ? 'ALIVE' : 'DEAD', ok: reasons.length === 0, reasons }
+}
+
+// The handoff note that surfaces an N/A smoke decision so a merge-without-smoke is
+// recorded, not buried (#393's core ask). Returns null when smoke actually ran
+// (ALIVE) or is not N/A — nothing to surface. When smoke is `not-applicable`, echoes
+// the reason (or names the missing reason). Consumed by the `verdict` and `mergeable`
+// CLI output; pure + exported so it is unit-testable.
+export function smokeHandoffNote(verdict = {}) {
+  const gates = verdict.gates || {}
+  if (gates.smoke !== SMOKE_NOT_APPLICABLE) return null
+  const reason = typeof verdict.smokeNotApplicableReason === 'string' && verdict.smokeNotApplicableReason.trim()
+  return reason
+    ? `smoke: not-applicable — ${reason} (no ALIVE was fabricated; fabricating one is still forbidden)`
+    : 'smoke: not-applicable but no smokeNotApplicableReason recorded — unreasoned N/A, treated as a missing gate'
+}
+
+// The decidable preconditions for merging an independently-shippable component
+// into the target branch (integration gate step 7). This is the sibling of
+// computeIntegrationVerdict: like `verdict` it only *decides and refuses*, it
+// does not act. The difference from the prose it replaces is that every fact is
+// gathered live (gh/git) by the CLI below and **fails closed** — an ungatherable
+// fact reads as not-satisfied, never satisfied — so the check verifies real state
+// rather than the orchestrator's belief. It deliberately does NOT perform the
+// merge: pushing to a protected branch is repo-policy-shaped *driving* the
+// orchestrator owns (the same boundary that keeps smoke's driving out of here),
+// and a merge has no mandatory manifest chokepoint to make a gate unbypassable
+// the way the round circuit-breaker's transition commands are. What this buys is
+// a live, decidable go/no-go — run it, gate on exit 0, then `gh pr merge`.
+export function publishedPrHead(view) {
+  return typeof view?.headRefOid === 'string' && /^[0-9a-f]{7,64}$/i.test(view.headRefOid)
+    ? view.headRefOid
+    : null
+}
+
+export function candidateAuthorization(manifest, componentId, verdict, liveHeadSha) {
+  const reasons = []
+  if (typeof componentId !== 'string' || !componentId.trim()) {
+    reasons.push('component id is required — unit PASS is preliminary evidence and cannot select the final authorization boundary')
+    return { authorized: false, reasons }
+  }
+  const component = Array.isArray(manifest?.components)
+    ? manifest.components.find((entry) => entry?.id === componentId)
+    : null
+  if (!component) {
+    reasons.push(`component ${componentId} is not recorded in the run manifest`)
+    return { authorized: false, reasons }
+  }
+  const validationErrors = validateComponentCandidates(manifest)
+  if (validationErrors.length) reasons.push(`component candidate state is invalid: ${validationErrors[0]}`)
+  const candidate = component.candidate
+  const frozen = candidate?.frozen
+  const terminal = Array.isArray(candidate?.authorizations) ? candidate.authorizations.at(-1) : null
+  if (candidate?.state !== 'authorized') reasons.push(`component candidate is ${candidate?.state ?? 'not recorded'}, needs "authorized"`)
+  if (!frozen?.headSha) reasons.push('component candidate has no frozen HEAD')
+  if (!terminal || terminal.generation !== candidate?.generation || terminal.headSha !== frozen?.headSha) {
+    reasons.push('component candidate has no terminal authorization for its current frozen generation')
+  }
+  if (component.authorizationBoundary?.kind !== 'integration' || component.authorizationBoundary?.value !== frozen?.headSha) {
+    reasons.push('component authorization boundary is not the frozen component HEAD')
+  }
+  const recomputed = verdict?.requiredCheckPlan ? computeIntegrationVerdict(verdict) : { ok: verdict?.status === 'ALIVE', reasons: [] }
+  if (verdict?.status !== 'ALIVE' || !recomputed.ok) reasons.push(`integration verdict is ${verdict?.status == null ? 'not recorded' : `"${verdict.status}"`}, needs recomputed "ALIVE" (${recomputed.reasons.join('; ') || 'stored status mismatch'})`)
+  if (verdict?.integrationBranch !== frozen?.branch) reasons.push('integration verdict branch does not match the frozen candidate branch')
+  if (liveHeadSha !== frozen?.headSha) reasons.push(`published PR HEAD ${liveHeadSha ?? 'could not be resolved'} does not equal frozen candidate HEAD ${frozen?.headSha ?? 'not recorded'}`)
+  return { authorized: reasons.length === 0, reasons }
+}
+
+export function mergePreconditions({ authorized, candidateAuthorized, verdictStatus, ciGreen, unmergedDeps = [], completionBlockedOn = [], fastForwardable, targetDrifted = false, targetDriftReasons = [] }) {
+  const reasons = []
+  if (authorized !== true) reasons.push('mergeShippable was not authorized at pre-flight — this skill merges nothing without it (guarantee 4)')
+  if (candidateAuthorized !== true) reasons.push('the published PR HEAD is not the authorized frozen component HEAD — unit PASSes and stale component verdicts are preliminary evidence, not delivery authorization')
+  if (verdictStatus !== 'ALIVE') reasons.push(`integration verdict is ${verdictStatus == null ? 'not recorded' : `"${verdictStatus}"`}, needs "ALIVE"`)
+  if (ciGreen !== true) reasons.push("CI is not verified green on the PR's current HEAD")
+  if (unmergedDeps.length) reasons.push(`dependency component(s) not yet in the target: ${unmergedDeps.join(', ')} — a component merges only after everything it depends on`)
+  if (completionBlockedOn.length) reasons.push(`external/human completion dependency is still pending: ${completionBlockedOn.join(', ')}`)
+  if (fastForwardable !== true) reasons.push('the integration branch is not fast-forwardable onto the target — back-merge the target in and re-verify CI first, never force')
+  // #944 / epic-867: target trunk moved under a multi-unit component mid-integration.
+  if (targetDrifted === true) {
+    const detail = Array.isArray(targetDriftReasons) && targetDriftReasons.length
+      ? targetDriftReasons.join('; ')
+      : 'target trunk moved since assemble without re-ALIVE'
+    reasons.push(detail)
+  }
+  return { ok: reasons.length === 0, reasons }
+}
+
+// Queue-head checks stay in the frozen required-check plan, but their synthetic
+// commit cannot exist before admission. Eligibility proves the plan has a real
+// provider observation path; completion consumes the resulting artifact.
+export function queueObservationMapping(plan) {
+  const errors = []
+  for (const check of checksForPhase(plan, 'queue-head')) {
+    if (!check?.queueEvidence?.provider || !check?.queueEvidence?.acquisition) {
+      errors.push(`queue-head requirement ${check?.name ?? 'unknown'} has no provider observation path`)
+    }
+  }
+  return { ok: errors.length === 0, errors }
+}
+
+export function enqueueEligibility({ authorized, candidateAuthorized, verdict, ciGreen, unmergedDeps = [], completionBlockedOn = [], targetDrifted = false, targetDriftReasons = [] } = {}) {
+  // Source-to-live-target fast-forwardability is a direct-merge requirement. A batched
+  // queue deliberately accepts a source branch behind the live target and tests the
+  // synthetic current-base plus candidate tree. targetDrifted carries the queue-specific
+  // ancestry proof: the recorded assembly base must still be in live target history.
+  const preconditions = mergePreconditions({ authorized, candidateAuthorized, verdictStatus: verdict?.status, ciGreen, unmergedDeps, completionBlockedOn, fastForwardable: true, targetDrifted, targetDriftReasons })
+  const mapping = queueObservationMapping(verdict?.requiredCheckPlan)
+  return { ok: preconditions.ok && mapping.ok, reasons: [...preconditions.reasons, ...mapping.errors] }
+}
+
+export function deliveryCompletion(verdict = {}, { pr, mergedSha, ancestry } = {}) {
+  const reasons = []
+  if (ancestry !== true) reasons.push('merge commit ancestry is not proved in freshly fetched origin target')
+  if (typeof mergedSha !== 'string' || !/^[0-9a-f]{7,64}$/i.test(mergedSha)) reasons.push('mergedSha must be the provider-reported merge commit')
+  const plan = verdict.requiredCheckPlan
+  if (checksForPhase(plan, 'queue-head').length) {
+    const evidence = validateQueueExecutionArtifact(plan, verdict.queueExecutionEvidence, {
+      expectedRepository: plan?.repository,
+      expectedPr: pr,
+      expectedPrHeadSha: verdict.integrationHeadSha,
+    })
+    if (!evidence.ok) reasons.push(`queue-head delivery evidence is invalid: ${evidence.errors[0]}`)
+  }
+  return { ok: reasons.length === 0, reasons }
+}
+
+export function unresolvedCompletionDependencies(manifest = {}, verdict = {}, pr = null) {
+  const units = Array.isArray(manifest.units) ? manifest.units.filter((unit) => unit && typeof unit === 'object') : []
+  const ids = new Set(Array.isArray(verdict.mergeOrder) ? verdict.mergeOrder : [])
+  if (!ids.size && Array.isArray(manifest.components)) {
+    const component = manifest.components.find((entry) => entry?.pr != null && String(entry.pr) === String(pr))
+    for (const unit of component?.units ?? []) ids.add(typeof unit === 'string' ? unit : unit?.id)
+  }
+  const selected = ids.size
+    ? units.filter((unit) => ids.has(unit.id))
+    : units.filter((unit) => unit.pr != null && String(unit.pr) === String(pr))
+  return selected.flatMap((unit) => completionBlockers(manifest, unit).map((dependency) => `${unit.id}->${dependency}`))
+}
+
+// ---- git/gh live facts (side-effecting; not unit-tested, like smoke's driving) ----
+
+function git(args, opts = {}) {
+  return execFileSync('git', args, { encoding: 'utf8', ...opts }).trim()
+}
+
+// Every gather below FAILS CLOSED: a non-zero exit (not an ancestor, missing ref,
+// no gh, unauthenticated, a pending or failing check) resolves to the unsafe
+// answer, never the safe one — the merge decision must never default to "go".
+// Pure half of the --pr check, so the rule can be tested without a repo or a network.
+// `view` is `gh pr view --json state,mergeCommit,headRefOid`.
+export function deliveredShaCheck(sha, view) {
+  const state = view?.state
+  const merge = view?.mergeCommit?.oid ?? null
+  const head = view?.headRefOid ?? null
+  if (state && state !== 'MERGED') {
+    return { ok: false, reason: `the PR is ${state}, not MERGED — "delivered" is a claim about a merge that has happened; a request is not a result` }
+  }
+  if (!merge) return { ok: true, note: 'the PR reports no mergeCommit — checking the --sha as given' }
+  if (sha === merge) return { ok: true }
+  if (head && sha === head) {
+    return {
+      ok: false,
+      reason: `--sha ${sha} is the PR's BRANCH HEAD; the merge landed as ${merge}. On a squash or rebase queue the head is never contained in the target, so this check would report a genuinely merged PR as undelivered — pass the merge commit (${merge})`,
+    }
+  }
+  return { ok: false, reason: `--sha ${sha} is neither the PR's merge commit (${merge}) nor its head (${head ?? 'unknown'}) — record what actually landed, not a sha from elsewhere in the run` }
+}
+
+export function tryJson(cmd, args) {
+  try { return JSON.parse(execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })) }
+  catch { return null }
+}
+
+export function isAncestor(ancestor, descendant) {
+  // Exit-code-only (no stdout to trim), so call execFileSync directly rather than
+  // through git()'s .trim() wrapper. stderr silenced: a missing ref is an expected
+  // fail-closed path, not an error to surface — `false` is the answer, git's
+  // diagnostic just noise.
+  try { execFileSync('git', ['merge-base', '--is-ancestor', ancestor, descendant], { stdio: 'ignore' }); return true }
+  catch { return false }
+}
+
+// Does a ref resolve? Used to decide whether origin/<target> exists before the
+// ancestry checks compare against it — a non-existent ref would fail closed, but we
+// want to distinguish "no remote configured" from "genuinely behind" and say which.
+export function isRef(ref) {
+  try { execFileSync('git', ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], { stdio: 'ignore' }); return true }
+  catch { return false }
+}
+
+function ciGreenFor(pr) {
+  // `gh pr checks` exits 0 only when every required check has passed (8 = still
+  // pending, 1 = a failure); any non-zero → not green.
+  try { execFileSync('gh', ['pr', 'checks', pr], { stdio: 'ignore' }); return true }
+  catch { return false }
+}
+
+// Assemble the live facts mergePreconditions needs. `deps` is [{ id, ref }] — the
+// dependency components' tips, each of which must already be an ancestor of the
+// target (i.e. merged) before this component may go. Caveat the caller owns: this
+// verifies the deps it is GIVEN are merged, not that the list is complete — the
+// component graph lives in the manifest, so the orchestrator must pass every
+// dependency; a dep nobody declares is a dep this gate can't fail closed on.
+//
+// `targetRef` is the ref the ancestry checks run against — the CLI passes the
+// freshly-fetched `origin/<target>`, NOT the bare local branch, because `mergeable`
+// runs long after `assemble` (after CI/review/smoke) and a local branch that fell
+// behind origin would let the "live" FF/deps check pass on stale data. `authorized`
+// is a fact the CALLER must have read from durable state (the manifest's
+// mergeShippable), never asserted — the CLI reads it from --manifest.
+export function gatherMergeFacts(verdict, { authorized, pr, deps = [], targetRef }, ci = ciGreenFor) {
+  const target = targetRef || verdict.targetBranch
+  return {
+    authorized: authorized === true,
+    verdictStatus: verdict.status,
+    ciGreen: pr ? ci(pr) : false,
+    unmergedDeps: deps.filter((d) => !isAncestor(d.ref, target)).map((d) => d.id),
+    fastForwardable: isAncestor(target, verdict.integrationBranch),
+  }
+}
+
+// `--target` may be the fetched remote head (`origin/dev` — the assemble base
+// should be the latest head, not a stale local branch). The verdict's
+// `targetBranch` field is consumed as a PR *base*, which must be the plain
+// branch name — so strip the remote qualifier there, while the diff range
+// keeps the exact ref the assembly actually ran against.
+export function branchName(ref) {
+  return ref.replace(/^origin\//, '')
+}
+
+// Create the integration branch off `target` and merge each unit in dependency
+// order. A merge that conflicts is aborted (branch returns to the last clean
+// tip) and recorded — then the run continues so ALL conflicts surface in one
+// pass. Returns { assembled, conflicts, mergeOrder, merged }.
+export function assemble(units, target, branch) {
+  const order = mergeOrder(units)
+  const byId = new Map(units.map((u) => [u.id, u]))
+  git(['checkout', '-B', branch, target])
+  const conflicts = []
+  const merged = []
+  for (const id of order) {
+    const u = byId.get(id)
+    try {
+      git(['merge', '--no-ff', '--no-edit', u.branch])
+      merged.push(id)
+    } catch {
+      let files = []
+      try { files = git(['diff', '--name-only', '--diff-filter=U']).split('\n').filter(Boolean) } catch { /* ignore */ }
+      try { git(['merge', '--abort']) } catch { /* ignore */ }
+      conflicts.push({ unit: id, branch: u.branch, files })
+    }
+  }
+  return { assembled: conflicts.length === 0, conflicts, mergeOrder: order, merged }
+}
+
+// ---- CLI ----
+
+function parseArgs(argv) {
+  const f = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--units') f.units = argv[++i]
+    else if (a === '--component') f.component = argv[++i]
+    else if (a === '--target') f.target = argv[++i]
+    else if (a === '--branch') f.branch = argv[++i]
+    else if (a === '--out') f.out = argv[++i]
+    else if (a === '--in') f.in = argv[++i]
+    else if (a === '--pr') f.pr = argv[++i]
+    else if (a === '--artifact') f.artifact = argv[++i]
+    else if (a === '--deps') f.deps = argv[++i]
+    else if (a === '--manifest') f.manifest = argv[++i]
+    else if (a === '--sha') f.sha = argv[++i]
+    else if (a === '--no-fetch') f.noFetch = true
+    else if (a === '--json') f.json = true
+    else if (!f.cmd) f.cmd = a
+  }
+  return f
+}
+
+const readJson = (p) => JSON.parse(fs.readFileSync(p, 'utf8'))
+
+// The synopsis the docs point `--help` at (references/integration-gate.md treats
+// the script as the source of truth for flags/exit codes/merge order). Kept in
+// sync with the four commands runCli dispatches.
+const USAGE = `combine-and-verify — the mechanized epic integration gate.
+Usage:
+  combine-and-verify validate  --units <units.json>
+  combine-and-verify assemble  --units <units.json> --target <branch> --branch <integ-branch> [--out <verdict.json>]
+  combine-and-verify record-exact-head --in <integration-verdict.json> --artifact <exact-head.json> [--out <verdict.json>]
+  combine-and-verify record-queue-execution --in <integration-verdict.json> --artifact <queue-execution.json> [--out <verdict.json>]
+  combine-and-verify verdict   --in <integration-verdict.json> [--json]     # exit 0 = ALIVE, 1 = DEAD
+  combine-and-verify mergeable --in <integration-verdict.json> --manifest <run-manifest.json> --component <id> --pr <ref> [--deps id:ref,…] [--no-fetch] # direct delivery only
+  combine-and-verify enqueue-eligible --in <integration-verdict.json> --manifest <run-manifest.json> --component <id> --pr <ref> [--deps id:ref,…] [--no-fetch]
+  combine-and-verify delivered --sha <merge-sha> --target <branch> [--pr <n>] [--no-fetch]   # direct completion only
+  combine-and-verify queue-delivered --in <integration-verdict.json> --artifact <queue-execution.json> --sha <merge-sha> --target <branch> --pr <n> [--no-fetch]
+                                                                                  # --pr checks the sha IS the PR's merge commit (squash/rebase queues never contain the head)
+Authorization for mergeable is READ from the manifest: mergeShippable plus the named component's authorized frozen HEAD, never flags. See the file header for the full contract.`
+
+export function runCli(argv) {
+  const f = parseArgs(argv)
+  if (f.cmd === 'help' || f.cmd === '--help' || f.cmd === '-h') { console.log(USAGE); return 0 }
+  if (!f.cmd) { console.error('usage: combine-and-verify <validate|assemble|verdict> [--units f] [--target b] [--branch b] [--in f] [--out f]'); return 2 }
+
+  if (f.cmd === 'validate') {
+    if (!f.units) { console.error('--units is required'); return 2 }
+    const { ok, errors } = validateUnits(readJson(f.units))
+    if (ok) console.log('combine-and-verify: ✓ units valid')
+    else { console.log('combine-and-verify: ✗ units invalid:'); errors.forEach((e) => console.log(`  - ${e}`)) }
+    return ok ? 0 : 1
+  }
+
+  if (f.cmd === 'assemble') {
+    if (!f.units || !f.target || !f.branch) { console.error('assemble needs --units, --target, --branch'); return 2 }
+    const units = readJson(f.units)
+    const { ok, errors } = validateUnits(units)
+    if (!ok) { console.error('combine-and-verify: units invalid:'); errors.forEach((e) => console.error(`  - ${e}`)); return 1 }
+    const a = assemble(units, f.target, f.branch)
+    // The gates start `pending` — the agent records ci/review/smoke as it runs
+    // those skills against the assembled tip, then `verdict` computes the gate.
+    const verdict = {
+      targetBranch: branchName(f.target),
+      integrationBranch: f.branch,
+      integrationHeadSha: git(['rev-parse', f.branch]),
+      combinedDiffRange: `${f.target}...${f.branch}`,
+      mergeOrder: a.mergeOrder,
+      merged: a.merged,
+      assembled: a.assembled,
+      conflicts: a.conflicts,
+      gates: { ci: 'pending', review: 'pending', smoke: 'pending', exactHead: 'pending' },
+      exactHeadEvidence: null,
+      requiredCheckPlan: null,
+      queueExecutionEvidence: null,
+      // Filled ONLY when smoke genuinely cannot run — a repo with no bootable
+      // surface / no curated golden-path manifest (#393). Then the orchestrator sets
+      // `gates.smoke = 'not-applicable'` AND writes the reason here; both are required
+      // for the N/A to pass. Left null when smoke ran (records a real ALIVE/DEAD) —
+      // never a silent default for a missing smoke result.
+      smokeNotApplicableReason: null,
+      // Filled by the orchestrator after the verdict is ALIVE: the single
+      // combined PR published from this integration branch (gate step 6). The
+      // epic's handoff deliverable; null until published.
+      combinedPr: null,
+    }
+    const computed = computeIntegrationVerdict(verdict)
+    const out = { ...verdict, status: computed.status, reasons: computed.reasons }
+    const dest = f.out || 'integration-verdict.json'
+    fs.writeFileSync(dest, JSON.stringify(out, null, 2) + '\n')
+    console.log(`combine-and-verify: assembled ${a.merged.length}/${units.length} onto ${f.branch}${a.conflicts.length ? ` — ${a.conflicts.length} conflict(s)` : ''}; gates pending → wrote ${dest}`)
+    a.conflicts.forEach((c) => console.log(`  ✗ conflict: ${c.unit} (${c.branch}) — ${c.files.join(', ') || 'see git'}`))
+    console.log('  next: record ci/review/smoke results into the gates, then `verdict --in ' + dest + '`')
+    return a.assembled ? 0 : 1
+  }
+
+  if (f.cmd === 'record-queue-execution') {
+    if (!f.in || !f.artifact) { console.error('record-queue-execution needs --in <integration-verdict.json> --artifact <queue-execution.json> [--out <verdict.json>]'); return 2 }
+    const consumed = consumeQueueExecutionArtifact(readJson(f.in), readJson(f.artifact))
+    const computed = computeIntegrationVerdict(consumed)
+    const out = { ...consumed, status: computed.status, reasons: computed.reasons }
+    fs.writeFileSync(f.out || f.in, JSON.stringify(out, null, 2) + '\n')
+    return consumed.gates.queueExecution === 'pass' ? 0 : 1
+  }
+
+  if (f.cmd === 'record-exact-head') {
+    if (!f.in || !f.artifact) { console.error('record-exact-head needs --in <integration-verdict.json> --artifact <exact-head.json> [--out <verdict.json>]'); return 2 }
+    const consumed = consumeExactHeadArtifact(readJson(f.in), readJson(f.artifact))
+    const computed = computeIntegrationVerdict(consumed)
+    const out = { ...consumed, status: computed.status, reasons: computed.reasons }
+    const destination = f.out || f.in
+    fs.writeFileSync(destination, JSON.stringify(out, null, 2) + '\n')
+    const accepted = consumed.gates.exactHead === 'pass'
+    if (accepted) console.log(`combine-and-verify: exact-head artifact accepted at ${consumed.integrationHeadSha}; integration remains ${computed.status}`)
+    else {
+      console.log('combine-and-verify: exact-head artifact rejected:')
+      consumed.exactHeadEvidence.errors.forEach((error) => console.log(`  ✗ ${error}`))
+    }
+    return accepted ? 0 : 1
+  }
+
+  if (f.cmd === 'verdict') {
+    if (!f.in) { console.error('--in <integration-verdict.json> is required'); return 2 }
+    const v = readJson(f.in)
+    const computed = computeIntegrationVerdict(v)
+    const out = { ...v, status: computed.status, reasons: computed.reasons }
+    if (f.out || f.in) fs.writeFileSync(f.out || f.in, JSON.stringify(out, null, 2) + '\n')
+    if (f.json) console.log(JSON.stringify(out, null, 2))
+    else {
+      console.log(`combine-and-verify: ${computed.ok ? '✅ ALIVE' : '❌ DEAD'} — combined tree ${v.combinedDiffRange}`)
+      const note = smokeHandoffNote(out)
+      if (note) console.log(`  ⓘ ${note}`)   // surface an N/A smoke decision, not bury it
+      computed.reasons.forEach((r) => console.log(`  ✗ ${r}`))
+    }
+    return computed.ok ? 0 : 1
+  }
+
+  if (f.cmd === 'mergeable' || f.cmd === 'enqueue-eligible') {
+    if (!f.in || !f.manifest || !f.component || !f.pr) { console.error('mergeable needs --in <integration-verdict.json> --manifest <run-manifest.json> --component <id> --pr <ref> [--deps id:ref,…]'); return 2 }
+    const verdict = readJson(f.in)
+    const deps = (f.deps || '').split(',').map((s) => s.trim()).filter(Boolean).map((spec) => {
+      const [id, ref] = spec.split(':')
+      return { id, ref: ref || id }
+    })
+    // Authorization is READ from durable state, never asserted: mergeShippable in the
+    // run manifest is what pre-flight recorded (guarantee 4). Absent/unreadable
+    // manifest → not authorized (fail closed). A bare --authorized flag was the hole
+    // the review caught — it let a mistaken command satisfy the one precondition
+    // guarantee 4 exists to protect — so authorization has no CLI-flag source.
+    let authorized = false
+    let manifest = null
+    let deliveryMode = 'direct'
+    try {
+      manifest = readJson(f.manifest)
+      authorized = manifest.mergeShippable === true
+      deliveryMode = manifest.deliveryMode ?? 'direct'
+    } catch {
+      console.error(`  ⚠ could not read --manifest ${f.manifest}; treating merge and candidate authorization as NOT satisfied`)
+    }
+    // Fetch so the ancestry checks run against the real remote head, not a local
+    // branch that fell behind during the (possibly hours-long) verify phase.
+    const target = branchName(verdict.targetBranch)
+    let targetRef = `origin/${target}`
+    if (!f.noFetch) {
+      try { execFileSync('git', ['fetch', 'origin', target], { stdio: 'ignore' }) }
+      catch { console.error(`  ⚠ git fetch origin ${target} failed; FF/deps checks run against the last-known origin/${target}`) }
+    }
+    // If there is no origin/<target> at all (no remote), fall back to the local ref
+    // and say so rather than silently comparing against a ref that doesn't exist.
+    if (!isRef(targetRef)) { console.error(`  ⚠ ${targetRef} does not exist; comparing against local ${target}`); targetRef = target }
+    const liveHeadSha = publishedPrHead(tryJson('gh', ['pr', 'view', String(f.pr), '--json', 'headRefOid']))
+    const candidate = candidateAuthorization(manifest, f.component, verdict, liveHeadSha)
+    const facts = gatherMergeFacts(verdict, { authorized, pr: f.pr, deps, targetRef })
+    facts.completionBlockedOn = unresolvedCompletionDependencies(manifest ?? {}, verdict, f.pr)
+    // #944: direct delivery owns target integration and therefore requires exact-tip
+    // freshness. A queue provider owns speculative integration: forward movement is safe
+    // when the recorded assembly base remains an ancestor of the live target. The frozen
+    // PR head stays immutable; queue-head CI proves compatibility with the current base.
+    let liveTargetSha = null
+    try { liveTargetSha = execFileSync('git', ['rev-parse', targetRef], { encoding: 'utf8' }).trim() } catch { /* fail open on tip read → no drift signal */ }
+    const componentRow = Array.isArray(manifest?.components)
+      ? manifest.components.find((entry) => entry?.id === f.component)
+      : null
+    const assembleBaseIsAncestor = Boolean(componentRow?.baseShaAtAssemble && liveTargetSha)
+      && isAncestor(componentRow.baseShaAtAssemble, liveTargetSha)
+    const drift = targetBaseDrift({
+      baseShaAtAssemble: componentRow?.baseShaAtAssemble,
+      baseShaAtEnqueue: componentRow?.baseShaAtEnqueue,
+      liveTargetSha,
+      deliveryMode,
+      assembleBaseIsAncestor,
+    })
+    const gate = f.cmd === 'enqueue-eligible' ? enqueueEligibility : mergePreconditions
+    const { ok, reasons } = gate({
+      ...facts,
+      candidateAuthorized: candidate.authorized,
+      verdict,
+      targetDrifted: drift.drifted,
+      targetDriftReasons: drift.reasons,
+    })
+    reasons.push(...candidate.reasons.filter((reason) => !reasons.includes(reason)))
+    if (f.cmd === 'mergeable' && deliveryMode === 'queue') reasons.push('deliveryMode is queue — run enqueue-eligible, then request one provider enqueue; Mergify performs the merge')
+    if (f.cmd === 'enqueue-eligible' && deliveryMode !== 'queue') reasons.push(`deliveryMode is ${deliveryMode} — enqueue-eligible is only for queue delivery; run mergeable for direct delivery`)
+    // If this component reached ALIVE with smoke recorded not-applicable, surface that
+    // in the merge output so the merge-without-smoke is a recorded, visible decision
+    // (#393) — printed whether or not the merge is allowed, never buried.
+    const note = smokeHandoffNote(verdict)
+    if (note) console.log(`  ⓘ ${note}`)
+    const label = f.cmd === 'enqueue-eligible' ? 'enqueue-eligible' : 'mergeable'
+    if (ok) console.log(`combine-and-verify: ✅ ${label} into ${target} — every precondition verified live against ${targetRef}`)
+    else { console.log(`combine-and-verify: ❌ NOT ${label}:`); reasons.forEach((r) => console.log(`  ✗ ${r}`)) }
+    console.log(f.cmd === 'enqueue-eligible'
+      ? '  (queue delivery: one authorized enqueue request only; Mergify performs the merge, never gh pr merge)'
+      : '  (direct delivery only: perform the merge with `gh pr merge`, never a forced push; production promotion stays resolve-release)')
+    return ok ? 0 : 1
+  }
+
+  if (f.cmd === 'queue-delivered') {
+    if (!f.in || !f.artifact || !f.sha || !f.target || !f.pr) { console.error('queue-delivered needs --in <integration-verdict.json> --artifact <queue-execution.json> --sha <merge-sha> --target <branch> --pr <n>'); return 2 }
+    const verdict = consumeQueueExecutionArtifact(readJson(f.in), readJson(f.artifact))
+    const delivered = runCli(['delivered', '--sha', f.sha, '--target', f.target, '--pr', f.pr, ...(f.noFetch ? ['--no-fetch'] : [])]) === 0
+    const completion = deliveryCompletion(verdict, { pr: Number(f.pr), mergedSha: f.sha, ancestry: delivered })
+    if (completion.ok) console.log('combine-and-verify: queue delivery complete — ancestry and synthetic queue evidence proved')
+    else { console.log('combine-and-verify: queue delivery evidence-blocked:'); completion.reasons.forEach((reason) => console.log(`  ✗ ${reason}`)) }
+    return completion.ok ? 0 : 1
+  }
+
+  // The POST-condition to `mergeable`'s pre-condition. `mergeable` proves the bar is met
+  // before the merge action; nothing proved the action landed. epic-986 performed its
+  // delivery action (`@mergifyio queue`), the PR did not merge, and the loop moved on —
+  // four units reported merge-ready with `mergedSha: null`. A merge tool's return code,
+  // a queue acknowledgement, and an auto-merge flag are all REQUESTS. Only ancestry in
+  // the freshly-fetched target branch is a result, so that is what this checks.
+  if (f.cmd === 'delivered') {
+    if (!f.sha || !f.target) { console.error('delivered needs --sha <merge-sha> --target <branch> [--pr <n>] [--no-fetch]'); return 2 }
+    // WHICH sha is checked is the whole correctness of this gate, and until now nothing
+    // enforced it. Ancestry of the PR's HEAD passes on a merge-commit queue (the head is
+    // an ancestor of the merge commit) and FAILS on a squash or rebase queue, where the
+    // queue writes new commits and the head lands nowhere. So the same honest caller gets
+    // "✅ delivered" on one repo and "❌ NOT delivered" for a genuinely merged PR on the
+    // next — and the loop hands back landed work. `--pr` closes it by taking the SHA from
+    // the PR's own merge record instead of trusting the caller's.
+    if (f.pr) {
+      const view = tryJson('gh', ['pr', 'view', String(f.pr), '--json', 'state,mergeCommit,headRefOid'])
+      if (!view) console.error(`  ⚠ could not read PR #${f.pr} — falling back to the --sha given; verify it is the MERGE commit, not the branch head`)
+      else {
+        const verdict = deliveredShaCheck(f.sha, view)
+        if (!verdict.ok) { console.log(`combine-and-verify: ❌ ${verdict.reason}`); return 1 }
+        if (verdict.note) console.error(`  ⚠ ${verdict.note}`)
+      }
+    }
+    const target = branchName(f.target)
+    let targetRef = `origin/${target}`
+    if (!f.noFetch) {
+      try { execFileSync('git', ['fetch', 'origin', target], { stdio: 'ignore' }) }
+      catch { console.error(`  ⚠ git fetch origin ${target} failed; containment is checked against the last-known origin/${target}`) }
+    }
+    if (!isRef(targetRef)) { console.error(`  ⚠ ${targetRef} does not exist; comparing against local ${target}`); targetRef = target }
+    const landed = isAncestor(f.sha, targetRef)
+    if (landed) console.log(`combine-and-verify: ✅ delivered — ${f.sha} is contained in ${targetRef}`)
+    else {
+      console.log(`combine-and-verify: ❌ NOT delivered — ${f.sha} is not contained in ${targetRef}`)
+      console.log('  The delivery action was performed but the commit did not land. Record the attempt with its')
+      console.log('  outcome (run-state record-delivery-attempt), not a terminal "merged" — a request is not a result.')
+    }
+    return landed ? 0 : 1
+  }
+
+  console.error(`unknown command: ${f.cmd}`)
+  return 2
+}
+
+if (isMainModule(import.meta.url)) process.exit(runCli(process.argv.slice(2)))