@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/scripts/finalize.mjs

@@ -0,0 +1,488 @@
+// Correctness-only run finalization. Diagnostics are deliberately outside this gate.
+import { execFileSync, spawnSync } from 'node:child_process'
+
+import { deliveryForUnit, terminalDisposition, terminalDispositionTally } from './terminal-dispositions.mjs'
+import { effectiveUnitKind, unitKindComplete } from './unit-lifecycle.mjs'
+import { validateComponentCandidates } from './component-candidate.mjs'
+
+const isObject = (value) => value != null && typeof value === 'object' && !Array.isArray(value)
+const arr = (value) => (Array.isArray(value) ? value.filter(isObject) : [])
+const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0
+const sha7 = (value) => nonEmpty(value) ? value.slice(0, 7) : '(none)'
+const refNumber = (value) => {
+  if (Number.isInteger(value) && value > 0) return value
+  const match = String(value ?? '').match(/(?:^|#)(\d+)$/)
+  return match ? Number(match[1]) : null
+}
+const componentUnitIds = (component) => (Array.isArray(component?.units) ? component.units : [])
+  .map((unit) => typeof unit === 'string' ? unit : unit?.id).filter(nonEmpty)
+
+function normalizedGithubObservation(kind, requestedNumber, live) {
+  if (!isObject(live)) throw new Error(`${kind} #${requestedNumber} returned no structured observation`)
+  if (!Number.isInteger(live.number) || live.number <= 0) {
+    throw new Error(`${kind} #${requestedNumber} returned missing or malformed numeric identity`)
+  }
+  if (live.number !== requestedNumber) {
+    throw new Error(`${kind} #${requestedNumber} returned identity ${live.number}`)
+  }
+  return { ...structuredClone(live), number: requestedNumber }
+}
+
+function expectedIssueState(unit, disposition) {
+  if (disposition === 'delivered' || disposition === 'already-done' || disposition === 'descoped') return 'CLOSED'
+  if (disposition === 'handed-back') return null
+  const kind = effectiveUnitKind(unit)
+  if (kind !== 'implementation') return unitKindComplete(unit) ? 'CLOSED' : 'OPEN'
+  return null
+}
+
+function expectedPrState(disposition, scopeDecision) {
+  if (disposition === 'descoped') return { state: 'CLOSED', merged: false, label: scopeDecision?.prDisposition ?? 'closed-unmerged' }
+  if (disposition === 'delivered') return { terminal: true, label: 'closed or merged after component delivery' }
+  if (disposition === 'handed-back') return { merged: false, label: 'open or closed unmerged hand-back' }
+  if (disposition === 'already-done') return { terminal: true, label: 'closed or merged prior art' }
+  return null
+}
+
+function workspaceErrors(cleanup) {
+  const errors = []
+  if (!isObject(cleanup)) return ['workspace cleanup returned no structured result']
+  if (nonEmpty(cleanup.commandError)) errors.push(`workspace cleanup command failed: ${cleanup.commandError}`)
+  if (cleanup.collection?.ran !== true) errors.push(`workspace orphan collection did not run: ${cleanup.collection?.reason ?? 'no reason recorded'}`)
+  for (const failure of Array.isArray(cleanup.removalFailures) ? cleanup.removalFailures : []) {
+    errors.push(`workspace removal failed: ${typeof failure === 'string' ? failure : failure?.path ?? JSON.stringify(failure)}`)
+  }
+  const byPath = new Map(arr(cleanup.decisions).map((row) => [row.path, row]))
+  for (const remaining of Array.isArray(cleanup.remaining) ? cleanup.remaining : []) {
+    const path = typeof remaining === 'string' ? remaining : remaining?.path
+    const row = byPath.get(path) ?? (isObject(remaining) ? remaining : null)
+    if (/orchestrator's own checkout|orchestrator's tree/i.test(row?.reason ?? '')) continue
+    if (row?.unpublished === true || /unpublished work|uncommitted|untracked|on no remote/i.test(row?.reason ?? '')) {
+      errors.push(`unpublished work was preserved, never discarded, at ${path}: ${row?.reason ?? 'reason not recorded'}`)
+    } else {
+      errors.push(`unreaped workspace remains at ${path}: ${row?.reason ?? 'cleanup did not remove it'}`)
+    }
+  }
+  return errors
+}
+
+// A non-implementation unit is settled two ways, not one: it completed its kind's own protocol,
+// or a human descoped it. `record-scope-decision` never restricted descoping by kind, so a run
+// could record an honest descope that finalization then refused forever (#1087) — and
+// `external-verification`, the kind that exists precisely for work no agent session can perform,
+// is the kind most likely to need one. This is not a bypass: `terminalDisposition` re-validates
+// the whole scope decision on every read, so a loop-applied, non-human, or delivery-claiming
+// "descope" resolves to null and the unit stays pending.
+const nonImplementationSettled = (unit, manifest) => unitKindComplete(unit)
+  || terminalDisposition(unit, manifest) === 'descoped'
+
+const descopedIn = (roster, manifest) => roster
+  .filter((unit) => !unitKindComplete(unit) && terminalDisposition(unit, manifest) === 'descoped')
+
+function scopeTally(roster, manifest) {
+  return {
+    total: roster.length,
+    complete: roster.filter(unitKindComplete).length,
+    descoped: descopedIn(roster, manifest).length,
+    pending: roster.filter((unit) => !nonImplementationSettled(unit, manifest)).length,
+  }
+}
+
+// The two scope rosters, named once: the record, its read-back validator and the rendered handoff
+// all derive from these, so a finalized run can never be rejected by a tally computed differently
+// from the one that was written.
+const SCOPE_ROSTERS = [
+  ['external', 'external verification', (unit) => effectiveUnitKind(unit) === 'external-verification'],
+  ['humanOrPrerequisite', 'human decisions/prerequisites', (unit) => ['human-decision', 'prerequisite'].includes(effectiveUnitKind(unit))],
+]
+
+function scopeRecord(units, manifest) {
+  return Object.fromEntries(SCOPE_ROSTERS.map(([key, , belongs]) => [key, scopeTally(units.filter(belongs), manifest)]))
+}
+
+// A run finalized before `descoped` joined the tally recorded three counts, not four. Absent
+// reads as 0 — the true historical value, since a descoped non-implementation unit could not
+// finalize at all then. Field-by-field so the comparison is order-independent and all four
+// numbers stay strictly checked rather than the whole block being waved through.
+const normalizedScopeTally = (tally) => ({
+  total: tally?.total, complete: tally?.complete, descoped: tally?.descoped ?? 0, pending: tally?.pending,
+})
+// Driven off SCOPE_ROSTERS, never a second hand-written key list: a roster named in one place and
+// forgotten in the other would silently drop out of the staleness comparison.
+const normalizedScope = (scope) => Object.fromEntries(
+  SCOPE_ROSTERS.map(([key]) => [key, normalizedScopeTally(scope?.[key])]))
+
+function autonomousDecisions(units) {
+  const rows = []
+  for (const unit of units) {
+    for (const decision of [...arr(unit.breakerLog), ...(isObject(unit.breaker) ? [unit.breaker] : [])]) {
+      if (decision.autoApplied === true) rows.push({
+        unit: unit.id,
+        decision: decision.decision,
+        signal: decision.signal ?? 'not recorded',
+        autonomyAtDecision: decision.autonomyAtDecision ?? null,
+        decidedAt: decision.decidedAt ?? null,
+      })
+    }
+  }
+  return rows
+}
+
+export function renderFinalHandoff(manifest, finalization) {
+  const units = arr(manifest.units)
+  const byId = new Map(units.map((unit) => [unit.id, unit]))
+  const lines = [
+    'FINAL HANDOFF',
+    `run ${manifest.runSlug ?? '(unknown)'} -> ${manifest.targetBranch ?? '(unknown target)'} @ ${sha7(finalization.target?.headSha)}`,
+    '',
+    'Delivery:',
+  ]
+  for (const unit of units.filter((entry) => effectiveUnitKind(entry) === 'implementation')) {
+    const disposition = terminalDisposition(unit, manifest)
+    const delivery = deliveryForUnit(unit, manifest)
+    if (disposition === 'delivered') lines.push(`  - ${unit.id}: delivered via component ${unit.deliveryRef?.componentId ?? '(legacy unit)'} @ ${sha7(delivery?.mergedSha)}`)
+    else if (disposition === 'handed-back') lines.push(`  - ${unit.id}: handed back - ${delivery?.blockedOn ?? 'reason not recorded'}`)
+    else if (disposition === 'already-done') lines.push(`  - ${unit.id}: already done (verified prior art)`)
+    else if (disposition === 'descoped') lines.push(`  - ${unit.id}: human-descoped - ${unit.scopeDecision?.reason ?? 'reason not recorded'}`)
+  }
+  for (const component of arr(manifest.components)) {
+    if (componentUnitIds(component).some((id) => terminalDisposition(byId.get(id), manifest) === 'delivered')) {
+      lines.push(`  - component ${component.id}: merged ${sha7(component.delivery?.mergedSha ?? component.mergedSha)}`)
+    }
+  }
+
+  lines.push('', 'Scope:')
+  for (const [, label, belongs] of SCOPE_ROSTERS) {
+    const roster = units.filter(belongs)
+    const tally = scopeTally(roster, manifest)
+    lines.push(`  - ${label}: ${tally.complete} complete, ${tally.descoped ? `${tally.descoped} descoped, ` : ''}${tally.pending} pending`)
+    // A count nobody can act on is not a handoff: name each unit the human removed, and why.
+    for (const unit of descopedIn(roster, manifest)) {
+      lines.push(`    - ${unit.id}: human-descoped - ${unit.scopeDecision?.reason ?? 'reason not recorded'}`)
+    }
+  }
+
+  lines.push('', 'Cleanup:')
+  lines.push(`  - original branch: ${finalization.branchRestore.expected ?? 'not applicable'} (${finalization.branchRestore.restored ? 'restored' : 'not restored'})`)
+  const cleanupRows = arr(finalization.cleanup?.decisions)
+  lines.push(`  - workspaces: ${cleanupRows.filter((row) => row.verdict === 'absent').length} absent, ${cleanupRows.filter((row) => row.verdict === 'reap').length} reaped, ${cleanupRows.filter((row) => row.verdict === 'preserve').length} preserved`)
+
+  lines.push('', 'Deferrals and known debt:')
+  const deferrals = arr(manifest.deferrals)
+  if (!deferrals.length) lines.push('  - none recorded')
+  else for (const row of deferrals) lines.push(`  - ${row.requirement ?? '(unnamed requirement)'} -> ${row.trackedIn ?? '(untracked)'}`)
+
+  lines.push('', 'Autonomous breaker decisions:')
+  if (!finalization.autonomousBreakerDecisions.length) lines.push('  - none')
+  else for (const row of finalization.autonomousBreakerDecisions) {
+    lines.push(`  - ${row.unit}: ${row.decision} (${row.signal})${row.autonomyAtDecision ? ` under ${row.autonomyAtDecision}` : ''}`)
+  }
+  return lines.join('\n')
+}
+
+export async function finalizeRun(manifest, boundary) {
+  const input = structuredClone(manifest)
+  const errors = []
+  const units = arr(input.units)
+  if (input.finalization !== undefined) errors.push('run is already finalized; finalization evidence is immutable')
+  if (!units.length) errors.push('finalize requires at least one typed unit')
+  const implementations = units.filter((unit) => effectiveUnitKind(unit) === 'implementation')
+  if (input.completionAudit !== undefined) {
+    errors.push('caller-authored completionAudit cannot authorize finalization; every completion fact is re-established live')
+  }
+  for (const unit of implementations) {
+    const disposition = terminalDisposition(unit, input)
+    if (!['delivered', 'handed-back', 'already-done', 'descoped'].includes(disposition)) {
+      errors.push(`${unit.id ?? '(unknown unit)'} has no honest in-scope terminal disposition (expected delivered, handed-back, already-done, or human-descoped)`)
+    }
+  }
+  errors.push(...validateComponentCandidates(input).map((error) => `component candidate: ${error}`))
+  for (const unit of units.filter((entry) => effectiveUnitKind(entry) !== 'implementation')) {
+    if (!nonImplementationSettled(unit, input)) errors.push(`${unit.id ?? '(unknown unit)'} ${effectiveUnitKind(unit)} is still pending and prevents whole-run finalization`)
+  }
+
+  let target = null
+  try { target = await boundary.fetchTarget(input.targetBranch) } catch (error) { errors.push(`fresh target fetch failed: ${error.message ?? error}`) }
+  if (!isObject(target) || !nonEmpty(target.ref) || !nonEmpty(target.headSha)) errors.push('fresh target fetch returned no target ref/head SHA')
+
+  const ancestry = []
+  const ancestryClaims = []
+  const byId = new Map(units.map((unit) => [unit.id, unit]))
+  const deliveredComponents = arr(input.components).filter((component) => componentUnitIds(component)
+    .some((id) => terminalDisposition(byId.get(id), input) === 'delivered'))
+  const canonicallyDeliveredUnits = new Set(deliveredComponents
+    .filter((component) => component.delivery?.outcome === 'merged')
+    .flatMap(componentUnitIds))
+  for (const unit of implementations) {
+    if (terminalDisposition(unit, input) === 'delivered' && !canonicallyDeliveredUnits.has(unit.id)) {
+      ancestryClaims.push({ kind: 'unit', id: unit.id, sha: deliveryForUnit(unit, input)?.mergedSha })
+    }
+  }
+  for (const component of deliveredComponents) {
+    const mergedSha = component.delivery?.mergedSha ?? component.mergedSha
+    if (!nonEmpty(mergedSha)) errors.push(`delivered component ${component.id ?? '(unknown)'} has no recorded merge SHA`)
+    else ancestryClaims.push({ kind: 'component', id: component.id, sha: mergedSha })
+  }
+  if (target?.ref) {
+    for (const claim of ancestryClaims) {
+      let contained = false
+      try { contained = await boundary.isAncestor(claim.sha, target.ref) } catch (error) { errors.push(`ancestry check failed for ${claim.kind} ${claim.id}: ${error.message ?? error}`) }
+      ancestry.push({ ...claim, targetRef: target.ref, contained })
+      if (!contained) errors.push(`${claim.kind} ${claim.id} merge SHA ${claim.sha} is not an ancestor of freshly fetched ${target.ref}`)
+    }
+  }
+
+  const github = { issues: [], prs: [] }
+  for (const unit of units) {
+    const issue = refNumber(unit.issue ?? unit.id)
+    if (issue == null) { errors.push(`${unit.id ?? '(unknown unit)'} has no GitHub issue reference for live terminal verification`); continue }
+    try {
+      const observed = await boundary.readIssue(issue, input.repository)
+      const live = normalizedGithubObservation('issue', issue, observed)
+      github.issues.push({ ...live, unit: unit.id, number: issue })
+      const disposition = terminalDisposition(unit, input)
+      const expected = expectedIssueState(unit, disposition)
+      if (expected && live.state !== expected) errors.push(`${unit.id} issue is ${live.state ?? 'unreadable'}, expected ${expected} for ${disposition ?? effectiveUnitKind(unit)}`)
+      if (disposition === 'descoped' && unit.scopeDecision?.issueDisposition === 'closed-not-planned'
+          && live.stateReason !== undefined && live.stateReason !== null && live.stateReason !== 'NOT_PLANNED') {
+        errors.push(`${unit.id} issue state reason is ${live.stateReason}, expected NOT_PLANNED for closed-not-planned descope`)
+      }
+    } catch (error) { errors.push(`${unit.id} issue could not be verified live: ${error.message ?? error}`) }
+
+    const pr = refNumber(unit.pr)
+    if (pr != null) {
+      try {
+        const observed = await boundary.readPr(pr, input.repository)
+        const live = normalizedGithubObservation('PR', pr, observed)
+        github.prs.push({ ...live, unit: unit.id, role: 'unit', number: pr })
+        const expected = expectedPrState(terminalDisposition(unit, input), unit.scopeDecision)
+        if (expected?.merged === false && live.merged === true) errors.push(`${unit.id} PR #${pr} is merged, expected ${expected.label}`)
+        if (expected?.state && live.state !== expected.state) errors.push(`${unit.id} PR #${pr} is ${live.state}, expected ${expected.state} (${expected.label})`)
+        if (expected?.terminal && !['CLOSED', 'MERGED'].includes(live.state)) errors.push(`${unit.id} PR #${pr} is ${live.state}, expected terminal CLOSED or MERGED`)
+      } catch (error) { errors.push(`${unit.id} PR #${pr} could not be verified live: ${error.message ?? error}`) }
+    }
+  }
+  for (const component of arr(input.components)) {
+    const pr = refNumber(component.pr)
+    if (pr == null) continue
+    try {
+      const observed = await boundary.readPr(pr, input.repository)
+      const live = normalizedGithubObservation('PR', pr, observed)
+      github.prs.push({ ...live, component: component.id, role: 'component', number: pr })
+      const hasDelivered = componentUnitIds(component).some((id) => terminalDisposition(byId.get(id), input) === 'delivered')
+      if (hasDelivered && (live.state !== 'MERGED' || live.merged !== true)) errors.push(`delivered component ${component.id} PR #${pr} is ${live.state}, expected MERGED`)
+      const expectedMergeSha = component.delivery?.mergedSha ?? component.mergedSha
+      if (hasDelivered && nonEmpty(expectedMergeSha) && live.mergeCommitSha !== expectedMergeSha) {
+        errors.push(`delivered component ${component.id} PR #${pr} merge SHA is ${live.mergeCommitSha ?? 'missing'}, expected ${expectedMergeSha}`)
+      }
+      if (!hasDelivered && live.merged === true) errors.push(`non-delivered component ${component.id} PR #${pr} is unexpectedly merged`)
+    } catch (error) { errors.push(`component ${component.id} PR #${pr} could not be verified live: ${error.message ?? error}`) }
+  }
+
+  let branchRestore = null
+  try { branchRestore = await boundary.restoreOriginalBranch(input.originalBranch) } catch (error) { errors.push(`original branch restoration failed: ${error.message ?? error}`) }
+  if (!isObject(branchRestore) || branchRestore.restored !== true || branchRestore.observed !== input.originalBranch) {
+    errors.push(`original branch was not restored to ${input.originalBranch ?? '(not recorded)'} (observed ${branchRestore?.observed ?? 'unknown'})`)
+  }
+  if (Array.isArray(branchRestore?.unpublished) && branchRestore.unpublished.length) {
+    errors.push(`original branch restoration refused with unpublished checkout work: ${branchRestore.unpublished.join(', ')}`)
+  }
+
+  let cleanup = null
+  if (errors.length === 0) {
+    try { cleanup = await boundary.cleanupWorkspaces(input) } catch (error) { errors.push(`workspace cleanup failed: ${error.message ?? error}`) }
+    errors.push(...workspaceErrors(cleanup))
+  }
+
+  const tally = terminalDispositionTally(implementations, input)
+  const finalization = {
+    status: 'finalized', finalizedAt: boundary.now(),
+    target, ancestry, github, branchRestore, cleanup,
+    delivery: tally,
+    scope: scopeRecord(units, input),
+    deferrals: structuredClone(Array.isArray(input.deferrals) ? input.deferrals : []),
+    autonomousBreakerDecisions: autonomousDecisions(units),
+  }
+  const resultManifest = structuredClone(input)
+  if (errors.length) return { ok: false, errors, manifest: resultManifest, target, ancestry, github, branchRestore, cleanup, handoff: null }
+  delete resultManifest.completionAudit
+  finalization.handoff = renderFinalHandoff(resultManifest, finalization)
+  resultManifest.finalization = finalization
+  const candidateErrors = finalizationErrors(resultManifest)
+  if (candidateErrors.length) {
+    return { ok: false, errors: candidateErrors, manifest: structuredClone(input), target, ancestry, github, branchRestore, cleanup, handoff: null }
+  }
+  return { ok: true, errors: [], manifest: resultManifest, target, ancestry, github, branchRestore, cleanup, handoff: finalization.handoff }
+}
+
+function expectedAncestryClaims(manifest) {
+  const units = arr(manifest?.units)
+  const implementations = units.filter((unit) => effectiveUnitKind(unit) === 'implementation')
+  const byId = new Map(units.map((unit) => [unit.id, unit]))
+  const claims = []
+  const deliveredComponents = arr(manifest?.components).filter((component) => componentUnitIds(component)
+    .some((id) => terminalDisposition(byId.get(id), manifest) === 'delivered'))
+  const canonicalMembers = new Set(deliveredComponents
+    .filter((component) => component.delivery?.outcome === 'merged')
+    .flatMap(componentUnitIds))
+  for (const unit of implementations) {
+    if (terminalDisposition(unit, manifest) === 'delivered' && !canonicalMembers.has(unit.id)) {
+      claims.push({ kind: 'unit', id: unit.id, sha: deliveryForUnit(unit, manifest)?.mergedSha })
+    }
+  }
+  for (const component of deliveredComponents) {
+    claims.push({ kind: 'component', id: component.id, sha: component.delivery?.mergedSha ?? component.mergedSha })
+  }
+  return claims
+}
+
+function ancestryRecordErrors(manifest, record) {
+  const expected = expectedAncestryClaims(manifest)
+  const actual = arr(record?.ancestry)
+  const normalized = (rows) => rows.map(({ kind, id, sha }) => ({ kind, id, sha }))
+  if (JSON.stringify(normalized(actual)) !== JSON.stringify(normalized(expected))) {
+    return ['finalization.ancestry is stale or does not match the delivered unit/component claim set']
+  }
+  if (actual.some((row) => row.contained !== true || row.targetRef !== record.target?.ref)) {
+    return ['finalization.ancestry is stale or does not prove every claim against finalization.target.ref']
+  }
+  return []
+}
+
+function githubRecordErrors(manifest, record) {
+  const errors = []
+  const units = arr(manifest?.units)
+  const byId = new Map(units.map((unit) => [unit.id, unit]))
+  const expectedIssues = units.map((unit) => ({ unit, number: refNumber(unit.issue ?? unit.id) }))
+  const issues = arr(record?.github?.issues)
+  const issueKeys = issues.map((row) => `${row.unit}:${row.number}`)
+  const expectedIssueKeys = expectedIssues.map(({ unit, number }) => `${unit.id}:${number}`)
+  if (expectedIssues.some(({ number }) => number == null)
+      || issues.some((row) => !Number.isInteger(row.number) || row.number <= 0)
+      || JSON.stringify(issueKeys) !== JSON.stringify(expectedIssueKeys)) {
+    errors.push('finalization GitHub issue observations are stale or incomplete')
+  } else {
+    for (let index = 0; index < expectedIssues.length; index++) {
+      const { unit } = expectedIssues[index]
+      const live = issues[index]
+      const disposition = terminalDisposition(unit, manifest)
+      const expectedState = expectedIssueState(unit, disposition)
+      if (expectedState && live.state !== expectedState) errors.push('finalization GitHub issue observations are stale or incomplete')
+      if (disposition === 'descoped' && unit.scopeDecision?.issueDisposition === 'closed-not-planned'
+          && live.stateReason !== undefined && live.stateReason !== null && live.stateReason !== 'NOT_PLANNED') {
+        errors.push('finalization GitHub issue observations are stale or incomplete')
+      }
+    }
+  }
+
+  const expectedPrs = []
+  for (const unit of units) {
+    const number = refNumber(unit.pr)
+    if (number != null) expectedPrs.push({ role: 'unit', unit, number })
+  }
+  for (const component of arr(manifest?.components)) {
+    const number = refNumber(component.pr)
+    if (number != null) expectedPrs.push({ role: 'component', component, number })
+  }
+  const prs = arr(record?.github?.prs)
+  const prKey = (row) => row.role === 'unit'
+    ? `unit:${row.unit}:${row.number}`
+    : `component:${row.component}:${row.number}`
+  const expectedPrKeys = expectedPrs.map((row) => row.role === 'unit'
+    ? `unit:${row.unit.id}:${row.number}`
+    : `component:${row.component.id}:${row.number}`)
+  if (prs.some((row) => !Number.isInteger(row.number) || row.number <= 0)
+      || JSON.stringify(prs.map(prKey)) !== JSON.stringify(expectedPrKeys)) {
+    errors.push('finalization GitHub PR observations are stale or incomplete')
+  } else {
+    for (let index = 0; index < expectedPrs.length; index++) {
+      const expected = expectedPrs[index]
+      const live = prs[index]
+      if (expected.role === 'unit') {
+        const terminal = expectedPrState(terminalDisposition(expected.unit, manifest), expected.unit.scopeDecision)
+        if (terminal?.merged === false && live.merged === true) errors.push('finalization GitHub PR observations are stale or incomplete')
+        if (terminal?.state && live.state !== terminal.state) errors.push('finalization GitHub PR observations are stale or incomplete')
+        if (terminal?.terminal && !['CLOSED', 'MERGED'].includes(live.state)) errors.push('finalization GitHub PR observations are stale or incomplete')
+      } else {
+        const delivered = componentUnitIds(expected.component).some((id) => terminalDisposition(byId.get(id), manifest) === 'delivered')
+        const expectedMergeSha = expected.component.delivery?.mergedSha ?? expected.component.mergedSha
+        if (delivered && (live.state !== 'MERGED' || live.merged !== true || live.mergeCommitSha !== expectedMergeSha)) {
+          errors.push('finalization GitHub PR observations are stale or incomplete')
+        }
+        if (!delivered && live.merged === true) errors.push('finalization GitHub PR observations are stale or incomplete')
+      }
+    }
+  }
+  return [...new Set(errors)]
+}
+
+export function finalizationErrors(manifest) {
+  const record = manifest?.finalization
+  if (record === undefined) return []
+  if (!isObject(record)) return ['finalization must be an object written by the dedicated finalize command']
+  const errors = []
+  if (record.status !== 'finalized') errors.push('finalization.status must be "finalized"')
+  if (!nonEmpty(record.finalizedAt)) errors.push('finalization.finalizedAt is required')
+  if (!nonEmpty(record.target?.ref) || !nonEmpty(record.target?.headSha)) errors.push('finalization.target requires the freshly fetched ref and headSha')
+  if (!Array.isArray(record.ancestry) || record.ancestry.some((row) => !isObject(row) || row.contained !== true || !nonEmpty(row.sha))) {
+    errors.push('finalization.ancestry must contain only proved merge-SHA ancestry rows')
+  }
+  if (!isObject(record.github) || !Array.isArray(record.github.issues) || !Array.isArray(record.github.prs)) errors.push('finalization.github requires live issue and PR observations')
+  errors.push(...ancestryRecordErrors(manifest, record))
+  errors.push(...githubRecordErrors(manifest, record))
+  if (!isObject(record.branchRestore) || record.branchRestore.restored !== true || record.branchRestore.observed !== manifest.originalBranch) {
+    errors.push('finalization.branchRestore must prove the recorded originalBranch was restored')
+  }
+  errors.push(...workspaceErrors(record.cleanup).map((error) => `finalization: ${error}`))
+  const units = arr(manifest?.units)
+  const implementations = units.filter((unit) => effectiveUnitKind(unit) === 'implementation')
+  const expectedDelivery = terminalDispositionTally(implementations, manifest)
+  if (JSON.stringify(record.delivery) !== JSON.stringify(expectedDelivery)) errors.push('finalization.delivery is stale or does not match current typed dispositions')
+  const expectedScope = scopeRecord(units, manifest)
+  if (JSON.stringify(normalizedScope(record.scope)) !== JSON.stringify(normalizedScope(expectedScope))) errors.push('finalization.scope is stale or does not match current non-implementation completion')
+  if (expectedScope.external.pending || expectedScope.humanOrPrerequisite.pending) errors.push('finalization cannot coexist with pending external/human/prerequisite units')
+  if (JSON.stringify(record.deferrals) !== JSON.stringify(Array.isArray(manifest?.deferrals) ? manifest.deferrals : [])) errors.push('finalization.deferrals is stale')
+  if (JSON.stringify(record.autonomousBreakerDecisions) !== JSON.stringify(autonomousDecisions(units))) errors.push('finalization autonomous breaker decisions are stale')
+  const expectedHandoff = renderFinalHandoff(manifest, record)
+  if (record.handoff !== expectedHandoff) errors.push('finalization.handoff was not rendered from the current validated state')
+  return errors
+}
+
+function runJson(command, args, cwd) {
+  return JSON.parse(execFileSync(command, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }))
+}
+
+export function createLiveFinalizeBoundary({ cwd = process.cwd(), cleanupWorkspaces, now = () => new Date().toISOString() } = {}) {
+  return {
+    now,
+    fetchTarget: async (branch) => {
+      if (!nonEmpty(branch)) throw new Error('targetBranch is not recorded')
+      execFileSync('git', ['fetch', 'origin', branch], { cwd, stdio: ['ignore', 'ignore', 'pipe'] })
+      const ref = `origin/${branch}`
+      const headSha = execFileSync('git', ['rev-parse', ref], { cwd, encoding: 'utf8' }).trim()
+      return { remote: 'origin', branch, ref, headSha, fetchedAt: now() }
+    },
+    isAncestor: async (sha, ref) => spawnSync('git', ['merge-base', '--is-ancestor', sha, ref], { cwd }).status === 0,
+    readIssue: async (id, repository) => {
+      const number = refNumber(id)
+      if (number == null || !nonEmpty(repository)) throw new Error('issue number and repository are required')
+      const view = runJson('gh', ['issue', 'view', String(number), '--repo', repository, '--json', 'number,state,stateReason,url'], cwd)
+      return { id, number: view.number, state: view.state, stateReason: view.stateReason ?? null, url: view.url }
+    },
+    readPr: async (id, repository) => {
+      if (!Number.isInteger(id) || !nonEmpty(repository)) throw new Error('PR number and repository are required')
+      const view = runJson('gh', ['pr', 'view', String(id), '--repo', repository, '--json', 'number,state,mergedAt,mergeCommit,url,headRefOid'], cwd)
+      return { id, number: view.number, state: view.state, merged: view.state === 'MERGED' || nonEmpty(view.mergedAt), mergedAt: view.mergedAt ?? null, mergeCommitSha: view.mergeCommit?.oid ?? null, headSha: view.headRefOid ?? null, url: view.url }
+    },
+    restoreOriginalBranch: async (expected) => {
+      const before = execFileSync('git', ['branch', '--show-current'], { cwd, encoding: 'utf8' }).trim() || null
+      if (expected == null) return { expected: null, before, observed: null, restored: true, unpublished: [], reason: 'detached/disposable checkout recorded at pre-flight' }
+      const status = execFileSync('git', ['status', '--porcelain'], { cwd, encoding: 'utf8' }).split('\n').filter(Boolean)
+      if (status.length) return { expected, before, observed: before, restored: before === expected, unpublished: status }
+      if (before !== expected) execFileSync('git', ['switch', expected], { cwd, stdio: ['ignore', 'ignore', 'pipe'] })
+      const observed = execFileSync('git', ['branch', '--show-current'], { cwd, encoding: 'utf8' }).trim() || null
+      return { expected, before, observed, restored: observed === expected, unpublished: [] }
+    },
+    cleanupWorkspaces: cleanupWorkspaces ?? (async () => { throw new Error('no workspace cleanup boundary configured') }),
+  }
+}