@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/scripts/next-operations.mjs

@@ -0,0 +1,419 @@
+// Exact next-operation rendering for resolve-issues. This module composes existing
+// state-machine and first-party CLI contracts; it owns no duplicate transition logic.
+import { execFileSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+
+import { deliveryFlow } from './fix-rounds.mjs'
+import { terminalDisposition } from './terminal-dispositions.mjs'
+import { runIsComplete } from './postmortem.mjs'
+import { unitPrReconciliationStatus } from './reconcile-contained-unit-prs.mjs'
+
+const SCRIPT_PATHS = Object.freeze({
+  runState: fileURLToPath(new URL('./run-state.mjs', import.meta.url)),
+  watchDelivery: fileURLToPath(new URL('./watch-delivery.mjs', import.meta.url)),
+  combineAndVerify: fileURLToPath(new URL('./combine-and-verify.mjs', import.meta.url)),
+  exactHeadCi: fileURLToPath(new URL('./exact-head-ci.mjs', import.meta.url)),
+})
+
+const object = (value) => value != null && typeof value === 'object' && !Array.isArray(value)
+const text = (value) => typeof value === 'string' && value.trim().length > 0
+const numberRef = (value) => String(value ?? '').trim().match(/^#?(\d+)$/)?.[1] ?? null
+
+function tryExec(command, args, cwd) {
+  try {
+    return { ok: true, stdout: execFileSync(command, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() }
+  } catch {
+    return { ok: false, stdout: '' }
+  }
+}
+
+function repositoryFromRemote(remote) {
+  const match = String(remote ?? '').trim().replace(/\.git$/, '').match(/(?:github\.com[:/])([^/]+\/[^/]+)$/)
+  return match?.[1] ?? null
+}
+
+export function probeNextOperations(manifest = {}, { cwd = process.cwd() } = {}) {
+  const top = tryExec('git', ['rev-parse', '--show-toplevel'], cwd)
+  const repoRoot = top.ok ? path.resolve(top.stdout) : path.resolve(cwd)
+  const branch = tryExec('git', ['branch', '--show-current'], repoRoot)
+  const status = tryExec('git', ['status', '--porcelain'], repoRoot)
+  const unpublished = tryExec('git', ['rev-list', '--max-count=1', 'HEAD', '--not', '--remotes'], repoRoot)
+  const remote = tryExec('git', ['remote', 'get-url', 'origin'], repoRoot)
+  const repository = text(manifest.repository) ? manifest.repository.trim() : (remote.ok ? repositoryFromRemote(remote.stdout) : null)
+  const originalBranchExists = text(manifest.originalBranch)
+    ? tryExec('git', ['show-ref', '--verify', '--quiet', `refs/heads/${manifest.originalBranch}`], repoRoot).ok
+    : false
+  const prStates = {}
+  const issueStates = {}
+  for (const unit of Array.isArray(manifest.units) ? manifest.units : []) {
+    const pr = numberRef(unit?.pr)
+    const issue = numberRef(unit?.id)
+    if (repository && pr && (unit?.status === 'merge-ready' || terminalDisposition(unit))) {
+      const read = tryExec('gh', ['pr', 'view', pr, '--repo', repository, '--json', 'state,mergedAt,mergeCommit,headRefOid,isDraft'], repoRoot)
+      if (read.ok) try { prStates[unit.id] = JSON.parse(read.stdout) } catch {}
+    }
+    if (repository && issue && terminalDisposition(unit)) {
+      const read = tryExec('gh', ['issue', 'view', issue, '--repo', repository, '--json', 'state'], repoRoot)
+      if (read.ok) try { issueStates[unit.id] = JSON.parse(read.stdout) } catch {}
+    }
+  }
+  return {
+    repository,
+    repoRoot,
+    currentBranch: branch.ok && branch.stdout ? branch.stdout : null,
+    clean: status.ok && status.stdout === '',
+    currentPublished: unpublished.ok && unpublished.stdout === '',
+    originalBranchExists,
+    prStates,
+    issueStates,
+  }
+}
+
+function operation({ id, kind, argv, cwd, expectedExitCodes, transition, authorizedBy = [], detail = null }) {
+  return {
+    id,
+    kind,
+    mutates: kind === 'mutation',
+    argv,
+    cwd,
+    expectedExitCodes,
+    authorizes: { transition },
+    authorizedBy,
+    ...(detail ? { detail } : {}),
+  }
+}
+
+function exactHeadPaths(unit) {
+  const config = object(unit?.exactHeadCi) ? unit.exactHeadCi : null
+  if (!text(config?.requestPath) || !text(config?.artifactPath)
+      || !path.isAbsolute(config.requestPath) || !path.isAbsolute(config.artifactPath)) return null
+  return { request: config.requestPath, artifact: config.artifactPath }
+}
+
+function verdictPath(manifest, unit, probe) {
+  if (text(unit.integrationVerdictPath) && path.isAbsolute(unit.integrationVerdictPath)) return unit.integrationVerdictPath
+  const component = (Array.isArray(manifest.components) ? manifest.components : [])
+    .find((entry) => Array.isArray(entry?.units) && entry.units.includes(unit.id))
+  if (text(component?.integrationVerdictPath) && path.isAbsolute(component.integrationVerdictPath)) return component.integrationVerdictPath
+  const observed = probe?.integrationVerdicts?.[unit.id]
+  return text(observed) && path.isAbsolute(observed) ? observed : null
+}
+
+export function deriveNextOperations(manifest = {}, {
+  slug = null,
+  manifestPath = null,
+  probe = {},
+  actions = [],
+  actionNames = {},
+} = {}) {
+  const m = object(manifest) ? manifest : {}
+  const runSlug = slug ?? (text(m.runSlug) ? m.runSlug : null)
+  const file = manifestPath ? path.resolve(manifestPath) : null
+  const repoRoot = path.resolve(probe.repoRoot || m.workspacePath || process.cwd())
+  const repository = text(m.repository) ? m.repository.trim() : (text(probe.repository) ? probe.repository.trim() : null)
+  const units = (Array.isArray(m.units) ? m.units : []).filter(object)
+  const byId = new Map(units.filter((unit) => text(unit.id)).map((unit) => [unit.id, unit]))
+  const invocationReady = text(runSlug) && file
+  const inspections = []
+  const mutations = []
+  const blocked = []
+  const block = (id, reason, transition) => blocked.push({ id, reason, authorizes: { transition } })
+  const add = (entry) => {
+    if (!Array.isArray(entry.argv) || entry.argv.some((arg) => typeof arg !== 'string') || !path.isAbsolute(entry.cwd)) {
+      block(entry.id, 'exact argv/cwd could not be derived from state; no partial operation is emitted', entry.authorizes.transition)
+      return
+    }
+    if (entry.mutates && !invocationReady) {
+      block(entry.id, 'run slug and resolved manifest path are required before any mutation can be authorized', entry.authorizes.transition)
+      return
+    }
+    ;(entry.mutates ? mutations : inspections).push(entry)
+  }
+  const runStateArgv = (...args) => [process.execPath, SCRIPT_PATHS.runState, ...args, ...(file ? ['--file', file] : [])]
+  const operationExit = (id) => probe?.operationResults?.[id]
+  const operationPassed = (id, exitCode = 0) => operationExit(id) === exitCode
+  if (!invocationReady) block('invocation-identity', 'run slug and resolved manifest path are required for run-state-backed operations', 'state -> unchanged')
+
+  for (const action of actions) {
+    const unit = byId.get(action.unit)
+    if (!unit) continue
+    if ([actionNames.PRODUCER_SPAWN, actionNames.REVIEW_SPAWN, actionNames.FIX_ROUND].includes(action.action)) {
+      const kind = action.action === actionNames.REVIEW_SPAWN ? 'review' : (action.action === actionNames.FIX_ROUND ? 'fix' : 'producer')
+      add(operation({ id: `spawn-contract:${unit.id}`, kind: 'inspection', cwd: repoRoot, argv: runStateArgv('spawn-contract', runSlug, unit.id, '--kind', kind), expectedExitCodes: [0, 4], transition: `${unit.status ?? 'queued'} -> ${action.action}` }))
+      continue
+    }
+    if (action.action === actionNames.BREAKER_DECISION) {
+      add(operation({ id: `breaker-diagnosis:${unit.id}`, kind: 'inspection', cwd: repoRoot, argv: runStateArgv('diagnose-breaker', runSlug, unit.id), expectedExitCodes: [0, 1], transition: 'breaker-fired -> breaker-diagnosed' }))
+      continue
+    }
+    if (action.action === actionNames.INTAKE_REENTRY) {
+      add(operation({ id: `intake-reentry:${unit.id}`, kind: 'mutation', cwd: repoRoot, argv: runStateArgv('record-intake-reentry', runSlug, unit.id), expectedExitCodes: [0], transition: 'breaker-decided -> in-progress', authorizedBy: [{ state: 'units[].breaker.decision' }] }))
+      continue
+    }
+    if (action.action === actionNames.WAIT_ON_DEPENDENCY) {
+      add(operation({ id: `runnable:${unit.id}`, kind: 'inspection', cwd: repoRoot, argv: runStateArgv('runnable', runSlug, '--json'), expectedExitCodes: [0], transition: 'dependency-wait -> admission-decision' }))
+      continue
+    }
+    if ([actionNames.HUMAN, actionNames.CANNOT_TELL].includes(action.action)) {
+      block(`current-action:${unit.id}`, action.why, `${unit.status ?? 'unknown'} -> unresolved`)
+      continue
+    }
+    if (![actionNames.DELIVER, actionNames.DELIVERY_WATCH].includes(action.action)) continue
+
+    const component = action.componentId && Array.isArray(m.components)
+      ? m.components.find((entry) => entry?.id === action.componentId)
+      : null
+    if (component?.delivery) {
+      const delivery = component.delivery
+      const componentId = component.id
+      const pr = numberRef(delivery.pr ?? component.pr)
+      const head = text(delivery.authorizedHeadSha) ? delivery.authorizedHeadSha.trim() : null
+      const flow = deliveryFlow(m)
+      const attempts = Array.isArray(delivery.attempts) ? delivery.attempts : []
+      const observed = probe?.deliveryOutcomes?.[componentId] ?? probe?.deliveryOutcomes?.[unit.id] ?? null
+      const integration = component.integrationVerdictPath ?? probe?.integrationVerdicts?.[componentId] ?? null
+      if (!repository) block(`delivery:${componentId}`, 'repository identity is absent from the manifest and Git remote probe', 'component-authorized -> delivery-requested')
+      if (!m.mergeShippable) block(`delivery-request:${componentId}`, 'mergeShippable authorization is absent/off; no merge or enqueue mutation may be emitted', 'component-authorized -> delivery-requested')
+      if (!pr) block(`delivery:${componentId}`, 'a concrete component PR number is required', 'component-authorized -> delivery-requested')
+      if (!head) block(`delivery:${componentId}`, 'components[].delivery.authorizedHeadSha is absent', 'component-authorized -> delivery-requested')
+      if (!flow) block(`delivery:${componentId}`, 'delivery flow is unresolved; deliveryMode and queueProvider must come from the probe', 'component-authorized -> delivery-requested')
+
+      if (repository && pr && head && flow) {
+        if (attempts.length) {
+          const watch = `delivery-watch:${componentId}`
+          if (operationPassed(watch, 5)) block(watch, 'component delivery watch exited 5 (exact-head CI failed); reopen the component generation and do not record a terminal outcome', 'delivery-attempt-recorded -> fresh-authorization-required')
+          else if (flow.watchable && operationExit(watch) === undefined && !observed) {
+            add(operation({ id: watch, kind: 'inspection', cwd: repoRoot, argv: [process.execPath, SCRIPT_PATHS.watchDelivery, '--pr', pr, '--repo', repository, ...(flow.provider ? ['--provider', flow.provider] : []), '--head', head], expectedExitCodes: [0, 4, 5], transition: 'component-delivery-attempt-recorded -> component-delivery-observed' }))
+          }
+        } else {
+          const gate = `delivery-preflight:${componentId}`
+          const request = `delivery-request:${componentId}`
+          if (!integration) block(request, 'component integration verdict path is absent; the authorized component cannot be delivered without its ALIVE artifact', 'component-authorized -> delivery-requested')
+          else {
+            const gateCommand = flow.mode === 'queue' ? 'enqueue-eligible' : 'mergeable'
+            if (operationExit(gate) === undefined) add(operation({ id: gate, kind: 'inspection', cwd: repoRoot, argv: [process.execPath, SCRIPT_PATHS.combineAndVerify, gateCommand, '--in', integration, '--manifest', file, '--component', componentId, '--pr', pr], expectedExitCodes: [0, 1], transition: 'component-authorized -> delivery-authorized' }))
+            if (operationPassed(gate) && operationExit(request) === undefined) {
+              const argv = flow.mode === 'direct'
+                ? ['gh', 'pr', 'merge', pr, '--repo', repository, '--squash']
+                : flow.provider === 'mergify'
+                  ? ['gh', 'pr', 'comment', pr, '--repo', repository, '--body', '@mergifyio queue']
+                  : ['gh', 'pr', 'merge', pr, '--repo', repository, '--auto', '--squash']
+              add(operation({ id: request, kind: 'mutation', cwd: repoRoot, argv, expectedExitCodes: [0], transition: 'component-authorized -> delivery-requested', authorizedBy: [{ operation: gate, exitCode: 0 }, { state: 'mergeShippable=true' }] }))
+            } else if (!operationPassed(gate)) block(request, `${gate} ${operationExit(gate) === undefined ? 'has not produced exit 0' : `produced exit ${operationExit(gate)}, not 0`}; delivery authorization is absent`, 'component-authorized -> delivery-requested')
+          }
+          const observedAttempt = probe?.deliveryAttempts?.[componentId] ?? probe?.deliveryAttempts?.[unit.id]
+          if (operationPassed(gate) && operationPassed(request) && object(observedAttempt)) {
+            const payload = { generation: delivery.generation, headSha: head, attempt: observedAttempt }
+            add(operation({ id: `record-component-delivery-attempt:${componentId}`, kind: 'mutation', cwd: repoRoot,
+              argv: runStateArgv('record-component-delivery-attempt', runSlug, componentId, JSON.stringify(payload)), expectedExitCodes: [0], transition: 'delivery-requested -> component-delivery-attempt-recorded',
+              authorizedBy: [{ operation: gate, exitCode: 0 }, { operation: request, exitCode: 0 }, { probe: `deliveryAttempts.${componentId}` }],
+            }))
+          } else block(`record-component-delivery-attempt:${componentId}`, 'delivery preflight and provider request have not both produced exit 0 with one observed provider payload', 'delivery-requested -> component-delivery-attempt-recorded')
+        }
+      }
+
+      if (observed?.outcome === 'merged' && text(observed.mergedSha) && repository && pr && text(m.targetBranch)) {
+        const proof = `delivery-proof:${componentId}`
+        const queueArtifactReady = flow?.mode !== 'queue' || (text(observed.queueExecutionArtifactPath) && integration)
+        const proofArgv = flow?.mode === 'queue'
+          ? (queueArtifactReady ? [process.execPath, SCRIPT_PATHS.combineAndVerify, 'queue-delivered', '--in', integration, '--artifact', observed.queueExecutionArtifactPath, '--sha', observed.mergedSha, '--target', m.targetBranch, '--pr', pr] : null)
+          : [process.execPath, SCRIPT_PATHS.combineAndVerify, 'delivered', '--sha', observed.mergedSha, '--target', m.targetBranch, '--pr', pr]
+        if (!proofArgv) block(proof, 'queue delivery completion requires the integration verdict and queue-execution artifact path; direct ancestry proof cannot substitute for synthetic queue evidence', 'component-delivery-observed -> component-delivery-proved')
+        else if (operationExit(proof) === undefined) add(operation({ id: proof, kind: 'inspection', cwd: repoRoot, argv: proofArgv, expectedExitCodes: [0, 1], transition: 'component-delivery-observed -> component-delivery-proved' }))
+        if (attempts.length && operationPassed(proof)) {
+          const queueExecution = object(observed.queueExecution)
+            ? observed.queueExecution
+            : text(observed.queueExecutionArtifactPath) && object(observed.queueExecutionArtifact)
+              ? { artifact: observed.queueExecutionArtifactPath, evidence: observed.queueExecutionArtifact }
+              : null
+          const payload = {
+            generation: delivery.generation,
+            headSha: head,
+            outcome: 'merged',
+            mergedSha: observed.mergedSha,
+            ...(observed.mergedAt ? { mergedAt: observed.mergedAt } : {}),
+            ...(queueExecution ? { queueExecution } : {}),
+          }
+          add(operation({ id: `record-component-delivery-outcome:${componentId}`, kind: 'mutation', cwd: repoRoot,
+            argv: runStateArgv('record-component-delivery-outcome', runSlug, componentId, JSON.stringify(payload)), expectedExitCodes: [0], transition: 'component-authorized -> delivered', authorizedBy: [{ operation: proof, exitCode: 0 }],
+          }))
+        } else if (!attempts.length) block(`record-component-delivery-outcome:${componentId}`, 'canonical component delivery requires its one provider attempt before merged outcome recording', 'component-authorized -> delivered')
+        else block(`record-component-delivery-outcome:${componentId}`, `${proof} has not produced exit 0; ancestry/queue evidence authorization is absent`, 'component-authorized -> delivered')
+      } else if (observed?.outcome === 'handed-back' && text(observed.blockedOn)) {
+        const watch = `delivery-watch:${componentId}`
+        const payload = { generation: delivery.generation, headSha: head, outcome: 'handed-back', blockedOn: observed.blockedOn }
+        if (operationPassed(watch, 4)) add(operation({ id: `record-component-delivery-outcome:${componentId}`, kind: 'mutation', cwd: repoRoot,
+          argv: runStateArgv('record-component-delivery-outcome', runSlug, componentId, JSON.stringify(payload)), expectedExitCodes: [0], transition: 'component-authorized -> handed-back', authorizedBy: [{ operation: watch, exitCode: 4 }],
+        }))
+        else block(`record-component-delivery-outcome:${componentId}`, `${watch} has not produced exit 4; hand-back authorization is absent`, 'component-authorized -> handed-back')
+      }
+      continue
+    }
+
+    const pr = numberRef(unit.pr)
+    const head = text(unit.pushedSha) ? unit.pushedSha.trim() : null
+    const flow = deliveryFlow(m)
+    const exact = exactHeadPaths(unit)
+    const attempts = Array.isArray(unit.delivery?.attempts) ? unit.delivery.attempts : []
+    const observed = probe?.deliveryOutcomes?.[unit.id] ?? (() => {
+      const state = probe?.prStates?.[unit.id]
+      const oid = state?.mergeCommit?.oid
+      return (state?.state === 'MERGED' || state?.mergedAt) && text(oid)
+        ? { outcome: 'merged', mergedSha: oid, ...(state.mergedAt ? { mergedAt: state.mergedAt } : {}) }
+        : null
+    })()
+    if (!repository) block(`delivery:${unit.id}`, 'repository identity is absent from the manifest and Git remote probe', 'merge-ready -> delivery-requested')
+    if (!m.mergeShippable) block(`delivery-request:${unit.id}`, 'mergeShippable authorization is absent/off; no merge or enqueue mutation may be emitted', 'merge-ready -> delivery-requested')
+    if (!pr) block(`delivery:${unit.id}`, 'a concrete PR number is required', 'merge-ready -> delivery-requested')
+    if (!head) block(`delivery:${unit.id}`, 'units[].pushedSha is absent; exact HEAD delivery is required', 'merge-ready -> delivery-requested')
+    if (!flow) block(`delivery:${unit.id}`, 'delivery flow is unresolved; deliveryMode and queueProvider must come from the probe', 'merge-ready -> delivery-requested')
+
+    if (repository && pr && head && flow) {
+      if (attempts.length) {
+        const watch = `delivery-watch:${unit.id}`
+        if (operationPassed(watch, 5)) block(watch, 'delivery watch exited 5 (exact-head CI failed); re-enter the fix/review loop and do not record a terminal outcome', 'delivery-attempt-recorded -> fresh-verdict-required')
+        else if (flow.watchable && operationExit(watch) === undefined && !observed) {
+          add(operation({ id: watch, kind: 'inspection', cwd: repoRoot, argv: [process.execPath, SCRIPT_PATHS.watchDelivery, '--pr', pr, '--repo', repository, ...(flow.provider ? ['--provider', flow.provider] : []), '--head', head], expectedExitCodes: [0, 4, 5], transition: 'delivery-attempt-recorded -> delivery-observed' }))
+        }
+      } else if (!exact) {
+        block(`exact-head-ci:${unit.id}`, 'exact-head CI request/artifact paths are absent; delivery cannot start without the #889 adapter request', 'reviewed-head -> exact-head-ci-recorded')
+        block(`delivery-request:${unit.id}`, 'exact-head CI authorization is absent', 'merge-ready -> delivery-requested')
+      } else {
+        const exactRun = `exact-head-ci:${unit.id}`
+        const exactValidate = `exact-head-ci-validate:${unit.id}`
+        const exactRunPassed = operationPassed(exactRun)
+        const exactValidatePassed = exactRunPassed && operationPassed(exactValidate)
+        if (operationExit(exactRun) === undefined) {
+          add(operation({ id: exactRun, kind: 'mutation', cwd: repoRoot, argv: [process.execPath, SCRIPT_PATHS.exactHeadCi, 'run', '--input', exact.request, '--out', exact.artifact], expectedExitCodes: [0, 1], transition: 'reviewed-head -> exact-head-ci-recorded', authorizedBy: [{ state: `units[${unit.id}].exactHeadCi` }, { state: `units[${unit.id}].pushedSha=${head}` }] }))
+          block(exactValidate, `${exactRun} has not produced exit 0`, 'exact-head-ci-recorded -> exact-head-ci-proved')
+        } else if (!exactRunPassed) {
+          block(exactValidate, `${exactRun} produced exit ${operationExit(exactRun)}, not 0`, 'exact-head-ci-recorded -> exact-head-ci-proved')
+        } else if (operationExit(exactValidate) === undefined) {
+          add(operation({ id: exactValidate, kind: 'inspection', cwd: repoRoot, argv: [process.execPath, SCRIPT_PATHS.exactHeadCi, 'validate', exact.artifact, '--head', head], expectedExitCodes: [0, 1], transition: 'exact-head-ci-recorded -> exact-head-ci-proved' }))
+        } else if (!exactValidatePassed) {
+          block(exactValidate, `${exactValidate} produced exit ${operationExit(exactValidate)}, not 0`, 'exact-head-ci-recorded -> exact-head-ci-proved')
+        }
+
+        const integration = verdictPath(m, unit, probe)
+        const gate = `delivery-preflight:${unit.id}`
+        const request = `delivery-request:${unit.id}`
+        if (!m.mergeShippable) block(request, 'mergeShippable authorization is absent/off; hand back merge-ready and do not enqueue or merge', 'merge-ready -> delivery-requested')
+        else if (!exactValidatePassed) block(request, `${exactRun} and ${exactValidate} have not both produced exit 0; exact-head authorization is absent`, 'merge-ready -> delivery-requested')
+        else if (!integration) block(request, 'integration verdict path is absent; combine-and-verify mergeable must authorize delivery first', 'merge-ready -> delivery-requested')
+        else {
+          if (operationExit(gate) === undefined) add(operation({ id: gate, kind: 'inspection', cwd: repoRoot, argv: [process.execPath, SCRIPT_PATHS.combineAndVerify, 'mergeable', '--in', integration, '--manifest', file, '--pr', pr], expectedExitCodes: [0, 1], transition: 'merge-ready -> delivery-authorized' }))
+          if (operationPassed(gate) && operationExit(request) === undefined) {
+            const argv = flow.mode === 'direct'
+              ? ['gh', 'pr', 'merge', pr, '--repo', repository, '--squash']
+              : flow.provider === 'mergify'
+                ? ['gh', 'pr', 'comment', pr, '--repo', repository, '--body', '@mergifyio queue']
+                : ['gh', 'pr', 'merge', pr, '--repo', repository, '--auto', '--squash']
+            add(operation({ id: request, kind: 'mutation', cwd: repoRoot, argv, expectedExitCodes: [0], transition: 'merge-ready -> delivery-requested', authorizedBy: [{ operation: gate, exitCode: 0 }, { state: 'mergeShippable=true' }] }))
+          } else if (!operationPassed(gate)) block(request, `${gate} ${operationExit(gate) === undefined ? 'has not produced exit 0' : `produced exit ${operationExit(gate)}, not 0`}; delivery authorization is absent`, 'merge-ready -> delivery-requested')
+          else if (!operationPassed(request)) block(request, `${request} produced exit ${operationExit(request)}, not 0`, 'merge-ready -> delivery-requested')
+        }
+
+        const observedAttempt = probe?.deliveryAttempts?.[unit.id]
+        const requestPassed = operationPassed(gate) && operationPassed(request)
+        if (requestPassed && object(observedAttempt)) add(operation({ id: `record-delivery-attempt:${unit.id}`, kind: 'mutation', cwd: repoRoot,
+          argv: runStateArgv('record-delivery-attempt', runSlug, unit.id, JSON.stringify(observedAttempt)), expectedExitCodes: [0], transition: 'delivery-requested -> delivery-attempt-recorded',
+          authorizedBy: [{ operation: gate, exitCode: 0 }, { operation: request, exitCode: 0 }, { probe: `deliveryAttempts.${unit.id}` }],
+        }))
+        else block(`record-delivery-attempt:${unit.id}`, `${gate} and ${request} have not both produced exit 0 with an observed provider payload; no attempt record is authorized`, 'delivery-requested -> delivery-attempt-recorded')
+      }
+    }
+
+    if (observed?.outcome === 'merged' && text(observed.mergedSha) && repository && pr && text(m.targetBranch)) {
+      const proof = `delivery-proof:${unit.id}`
+      if (operationExit(proof) === undefined) add(operation({ id: proof, kind: 'inspection', cwd: repoRoot, argv: [process.execPath, SCRIPT_PATHS.combineAndVerify, 'delivered', '--sha', observed.mergedSha, '--target', m.targetBranch, '--pr', pr], expectedExitCodes: [0, 1], transition: 'delivery-observed -> delivery-proved' }))
+      if (Array.isArray(unit.delivery?.attempts) && unit.delivery.attempts.length) {
+        const payload = { outcome: 'merged', mergedSha: observed.mergedSha, ...(observed.mergedAt ? { mergedAt: observed.mergedAt } : {}) }
+        if (operationPassed(proof)) add(operation({ id: `record-delivery-outcome:${unit.id}`, kind: 'mutation', cwd: repoRoot, argv: runStateArgv('record-delivery-outcome', runSlug, unit.id, JSON.stringify(payload)), expectedExitCodes: [0], transition: 'merge-ready -> delivered', authorizedBy: [{ operation: proof, exitCode: 0 }] }))
+        else block(`record-delivery-outcome:${unit.id}`, `${proof} has not produced exit 0; ancestry authorization is absent`, 'merge-ready -> delivered')
+      } else block(`record-delivery-outcome:${unit.id}`, 'typed delivery state requires a recorded attempt before merged outcome recording; do not invent an enqueue for an auto-merge observation', 'merge-ready -> delivered')
+    } else if (observed?.outcome === 'handed-back' && text(observed.blockedOn)) {
+      const payload = { outcome: 'handed-back', blockedOn: observed.blockedOn }
+      const watch = `delivery-watch:${unit.id}`
+      if (operationPassed(watch, 4)) add(operation({ id: `record-delivery-outcome:${unit.id}`, kind: 'mutation', cwd: repoRoot, argv: runStateArgv('record-delivery-outcome', runSlug, unit.id, JSON.stringify(payload)), expectedExitCodes: [0], transition: 'merge-ready -> handed-back', authorizedBy: [{ operation: watch, exitCode: 4 }] }))
+      else block(`record-delivery-outcome:${unit.id}`, `${watch} has not produced exit 4; hand-back authorization is absent`, 'merge-ready -> handed-back')
+    }
+  }
+
+  for (const unit of units) {
+    if (unit.disposition === 'descoped' && terminalDisposition(unit) !== 'descoped') {
+      if (unit.scopeDecision?.issueDisposition === 'closed-not-planned') block(`issue-disposition:${unit.id}`, 'scopeDecision is not a valid human descope; issue closure is not authorized', 'descoped -> issue-closed-not-planned')
+      if (unit.scopeDecision?.prDisposition === 'closed-unmerged') block(`pr-disposition:${unit.id}`, 'scopeDecision is not a valid human descope; PR closure is not authorized', 'descoped -> pr-closed-unmerged')
+      continue
+    }
+    if (terminalDisposition(unit) !== 'descoped' || !repository) continue
+    const issue = numberRef(unit.id)
+    const pr = numberRef(unit.pr)
+    if (issue) add(operation({ id: `issue-disposition-check:${unit.id}`, kind: 'inspection', cwd: repoRoot, argv: ['gh', 'issue', 'view', issue, '--repo', repository, '--json', 'state'], expectedExitCodes: [0], transition: `${terminalDisposition(unit)} -> issue-disposition-observed` }))
+    if (unit.scopeDecision?.issueDisposition === 'closed-not-planned' && issue && probe?.issueStates?.[unit.id]?.state === 'OPEN' && unit.scopeDecision?.decidedBy === 'human') {
+      add(operation({ id: `issue-disposition:${unit.id}`, kind: 'mutation', cwd: repoRoot, argv: ['gh', 'issue', 'close', issue, '--repo', repository, '--reason', 'not planned'], expectedExitCodes: [0], transition: 'descoped -> issue-closed-not-planned', authorizedBy: [{ state: 'scopeDecision.decidedBy=human' }] }))
+    } else if (unit.scopeDecision?.issueDisposition === 'closed-not-planned' && issue && probe?.issueStates?.[unit.id]?.state === 'OPEN') {
+      block(`issue-disposition:${unit.id}`, 'scopeDecision.decidedBy is not human; issue closure is not authorized', 'descoped -> issue-closed-not-planned')
+    }
+    if (pr) add(operation({ id: `pr-disposition-check:${unit.id}`, kind: 'inspection', cwd: repoRoot, argv: ['gh', 'pr', 'view', pr, '--repo', repository, '--json', 'state'], expectedExitCodes: [0], transition: `${terminalDisposition(unit)} -> pr-disposition-observed` }))
+    if (unit.scopeDecision?.prDisposition === 'closed-unmerged' && pr && probe?.prStates?.[unit.id]?.state === 'OPEN' && unit.scopeDecision?.decidedBy === 'human') {
+      add(operation({ id: `pr-disposition:${unit.id}`, kind: 'mutation', cwd: repoRoot, argv: ['gh', 'pr', 'close', pr, '--repo', repository], expectedExitCodes: [0], transition: 'descoped -> pr-closed-unmerged', authorizedBy: [{ state: 'scopeDecision.decidedBy=human' }] }))
+    } else if (unit.scopeDecision?.prDisposition === 'closed-unmerged' && pr && probe?.prStates?.[unit.id]?.state === 'OPEN') {
+      block(`pr-disposition:${unit.id}`, 'scopeDecision.decidedBy is not human; PR closure is not authorized', 'descoped -> pr-closed-unmerged')
+    }
+  }
+
+  if (runIsComplete(m)) {
+    const reconciliation = unitPrReconciliationStatus(m)
+    if (reconciliation.state === 'invalid') {
+      block('reconcile-contained-unit-prs', reconciliation.reason, 'run-terminal -> unit-prs-reconciled')
+      block('finalize', 'contained unit PR reconciliation state is invalid', 'run-terminal -> finalized')
+    } else if (reconciliation.required && !reconciliation.complete) {
+      add(operation({
+        id: 'reconcile-contained-unit-prs',
+        kind: 'mutation',
+        cwd: repoRoot,
+        argv: runStateArgv('reconcile-contained-unit-prs', runSlug),
+        expectedExitCodes: [0, 1],
+        transition: 'run-terminal -> unit-prs-reconciled',
+        authorizedBy: [{ state: 'canonical combined component delivery is merged' }],
+        detail: 'freshly verify exact unit heads, target ancestry, and the live component merge before closing superseded unit PRs',
+      }))
+      block('finalize', 'delivery-linked unit PRs require terminal reconciliation observations first', 'run-terminal -> finalized')
+    } else {
+      add(operation({
+        id: 'finalize',
+        kind: 'mutation',
+        cwd: repoRoot,
+        argv: runStateArgv('finalize', runSlug),
+        expectedExitCodes: [0, 1],
+        transition: 'run-terminal -> finalized',
+        authorizedBy: [{ state: 'all units have typed terminal dispositions' }, ...(reconciliation.required ? [{ state: 'delivery-linked unit PRs have terminal reconciliation observations' }] : [])],
+        detail: 'finalize owns and validates live terminal state, original-branch restoration, and workspace cleanup',
+      }))
+    }
+  }
+
+  return { version: 1, slug: runSlug, manifest: file, phase: runIsComplete(m) ? 'finalization' : 'active', actions, inspections, mutations, blocked }
+}
+
+export function renderNextOperations(result = {}) {
+  const out = [`NEXT OPERATIONS  ${result.slug ?? '(no slug)'}  phase ${result.phase ?? 'unknown'}`]
+  const section = (title, rows) => {
+    out.push('', `  ${title}`)
+    if (!rows?.length) { out.push('    (none)'); return }
+    for (const row of rows) {
+      out.push(`    ${row.id}  ${row.authorizes?.transition ?? 'no transition'}`)
+      out.push(`      cwd: ${row.cwd}`)
+      out.push(`      argv: ${JSON.stringify(row.argv)}`)
+      out.push(`      expected exits: ${row.expectedExitCodes.join(', ')}`)
+      if (row.authorizedBy?.length) out.push(`      authorized by: ${JSON.stringify(row.authorizedBy)}`)
+    }
+  }
+  section('INSPECTIONS (read-only)', result.inspections)
+  section('MUTATIONS (state/auth present)', result.mutations)
+  out.push('', '  BLOCKED MUTATIONS')
+  if (!result.blocked?.length) out.push('    (none)')
+  else for (const row of result.blocked) out.push(`    ${row.id}  ${row.authorizes?.transition ?? 'no transition'} — ${row.reason}`)
+  return out.join('\n')
+}