@1aboveio/skills 0.10.0

package/skills/engineering/resolve-release/scripts/version-postmortem.mjs

@@ -0,0 +1,485 @@
+// The VERSION-LEVEL release post-mortem: what one version cost across every attempt it took (#961).
+//
+// WHY THIS EXISTS. The single-manifest post-mortem (postmortem.mjs) profiles ONE run's record for
+// completeness. It cannot see the shape that made Forex v0.1.12 the incident it was: NINE attempts
+// for one version, eight of them non-released, and the release lane's own tooling — never the
+// application — as the repeated owner of the failures. Reconstructing that meant reading nine
+// durable bundles by hand, which is exactly the work the durable record exists to make mechanical.
+// So this pass aggregates every durable evidence bundle a version left behind and asks the
+// cross-attempt questions: how many attempts, how each one ended, how far each one got, who owned
+// the failures, and whether one owner kept repeating.
+//
+// WHAT IT READS. The durable evidence bundles (`evidence-bundle.mjs`, keyed
+// `<version>-attempt.<n>--<terminal-state>.json`) — NOT the run manifest, and never a live service.
+// The bundles are the immutable record (principle 10); this pass is their aggregate reader. It is
+// deliberately tolerant of schema drift across attempts: real bundles were written by different
+// releases months apart, so every signal below is read defensively and an absent signal is reported
+// as absent, never invented.
+//
+// THE CLASSIFICATION SURFACE IS A CONTRACT (#962 consumes it). `FAILURE_OWNERS` and the derivation
+// order in `classifyFailureOwner` are documented in references/postmortem.md and are STABLE:
+// changing a name, the order, or a rule's meaning is a breaking change to a downstream contract.
+// A bundle may DECLARE its owner (`failureOwner`, top-level or in `disposition`) — the declaration
+// wins, because the human or mechanism closest to the failure knows more than any heuristic — and
+// everything else is derived from the recorded verdicts by the ordered rules below.
+//
+// What this pass deliberately does NOT do (the issue's non-goals): it does not treat a rollback as
+// a failure of the release process — a rollback that happened and was recorded is the machine
+// working, reported as a fact in the counts — and it does not adjudicate its own findings. The
+// repeated-owner finding says WHERE to look; what to change is still a human's call.
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { renderProfile, saveProfile } from '../../resolve-issues/scripts/postmortem.mjs'
+import { ATTEMPT_TERMINAL_STATES } from '../../resolve-issues/scripts/run-state.mjs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+// The normalized failure-owner classification, in its documented order. STABLE SURFACE (#962).
+export const FAILURE_OWNERS = ['application', 'configuration', 'platform', 'release-tooling', 'gate-environment']
+
+// WHERE the lane stopped, normalized the same way the owner is (#962). `pre-candidate` — the
+// attempt ended before any candidate evidence exists (promotion/build/probe; also every failure
+// on the `no-deploy` shape, which never has a candidate); `candidate-validation` — a candidate
+// was judged at 0% and traffic never moved (step 4a); `post-exposure` — traffic moved and was
+// restored (a rollback, by construction). Same stability rule as FAILURE_OWNERS: the
+// rc-circuit-breaker records this per qualifying attempt.
+export const FAILURE_PHASES = ['pre-candidate', 'candidate-validation', 'post-exposure']
+
+const isObject = (v) => v != null && typeof v === 'object' && !Array.isArray(v)
+const nonEmpty = (v) => typeof v === 'string' && v.trim() !== ''
+
+// The states that END an attempt without shipping, where something — not someone — owns the
+// outcome. `revoked` is an operator's deliberate abandonment and `blocked-manual` is a park, not
+// an outcome; classifying either would manufacture a failure that did not happen.
+const FAILURE_STATES = new Set(['failed-pre-promotion', 'rolled-back'])
+
+// ---- classification ----
+//
+// Ordered, first match wins. The order is the contract: each rule is stated so that a LATER rule
+// never re-attributes what an earlier one already explained.
+//
+//   1. DECLARED. `failureOwner` on the bundle or its disposition, naming one of the five. The
+//      stable extension point: a future mechanism (#962) writes the owner at close time and this
+//      pass reads it back verbatim.
+//   2. gate-environment. The candidate verdict is CANNOT-RUN — an applicable gate that could not
+//      run (principle 13): absent credentials, an unavailable external service, a harness that
+//      would not start. The world stayed known and the question went unanswered; the owner is the
+//      gate's environment, not the candidate and not the lane.
+//   3. application / configuration / platform. The live or candidate evidence judged the artifact
+//      UNHEALTHY. Attributed by the recorded reason: configuration-shaped evidence (secrets, env
+//      vars, config) → `configuration`; platform-shaped (quota, the hosting platform, deploy
+//      infrastructure) → `platform`; anything else unhealthy → `application` — the observed defect
+//      belongs to the artifact until the evidence says otherwise.
+//   4. release-tooling (healthy). The live evidence shows the candidate HEALTHY — serving, ready,
+//      probes passing — and the attempt failed anyway. What failed is the lane's own machinery:
+//      the verifier, the normalization, an adapter, a gate's assumption about a valid platform
+//      representation. Forex 0.1.12's dominant owner.
+//   5. release-tooling (unmeasured stop). The candidate verdict was ALIVE and the attempt still
+//      ended in a failure state — the lane discarded or rolled back a candidate its own gate
+//      judged alive, so the stopping assumption lives in the lane.
+//   6. release-tooling (no evidence). No verdict evidence at all: the lane ended an attempt it
+//      never measured. The hole is in the lane's record, so the owner is the lane.
+const CONFIG_SIGNAL = /config|secret|env\s?var|missing (key|token|credential)|api[- ]?key/i
+const PLATFORM_SIGNAL = /quota|cloud run|platform|infrastructure|deploy(ment)? fail|provision/i
+
+function evidenceText(bundle) {
+  return [bundle?.candidateVerdict, bundle?.liveVerdict, bundle?.disposition]
+    .filter(isObject)
+    .flatMap((o) => [o.verdict, o.runtimeStatus, o.reason, o.releaseLaneVerdict, o.action])
+    .filter(nonEmpty)
+    .join(' · ')
+}
+
+function attributeUnhealthy(bundle) {
+  const text = evidenceText(bundle)
+  if (CONFIG_SIGNAL.test(text)) return 'configuration'
+  if (PLATFORM_SIGNAL.test(text)) return 'platform'
+  return 'application'
+}
+
+const healthyLiveSignal = (lv) => isObject(lv) && (
+  (nonEmpty(lv.runtimeStatus) && /^healthy/i.test(lv.runtimeStatus))
+  || lv.verdict === 'ALIVE'
+  || (nonEmpty(lv.verdict) && /^probe-succeeded/i.test(lv.verdict))
+)
+
+const unhealthySignal = (v) => isObject(v) && (
+  v.verdict === 'DEAD'
+  || (nonEmpty(v.runtimeStatus) && !/^healthy/i.test(v.runtimeStatus))
+)
+
+// Returns { owner, basis } for a failure terminal state, null otherwise. `basis` names the rule
+// and the signals used, so a reader can disbelieve the classification against the bundle itself.
+export function classifyFailureOwner(bundle) {
+  if (!isObject(bundle) || !FAILURE_STATES.has(bundle.terminalState)) return null
+
+  // 1. declared
+  const declared = [bundle.failureOwner, isObject(bundle.disposition) ? bundle.disposition.failureOwner : null]
+    .find((v) => FAILURE_OWNERS.includes(v))
+  if (declared) return { owner: declared, basis: 'declared in the bundle' }
+
+  const cv = isObject(bundle.candidateVerdict) ? bundle.candidateVerdict : null
+  const lv = isObject(bundle.liveVerdict) ? bundle.liveVerdict : null
+
+  // 2. gate-environment
+  if (cv?.verdict === 'CANNOT-RUN') {
+    return { owner: 'gate-environment', basis: 'candidate verdict CANNOT-RUN — an applicable gate that could not run (principle 13)' }
+  }
+  // 3. unhealthy evidence, attributed. Live evidence wins over the pre-exposure verdict: what
+  // production showed after the shift is the stronger observation (principle 5).
+  if (unhealthySignal(lv)) return { owner: attributeUnhealthy(bundle), basis: `live verdict unhealthy (${lv.verdict ?? lv.runtimeStatus})` }
+  if (unhealthySignal(cv)) return { owner: attributeUnhealthy(bundle), basis: 'candidate verdict DEAD' }
+  // 4. healthy live evidence, attempt failed anyway
+  if (healthyLiveSignal(lv)) {
+    return { owner: 'release-tooling', basis: `live evidence healthy (${lv.runtimeStatus ?? lv.verdict}) while the attempt ${bundle.terminalState} — the lane's own machinery stopped it` }
+  }
+  // 5. candidate judged alive, attempt failed
+  if (cv?.verdict === 'ALIVE') {
+    return { owner: 'release-tooling', basis: `candidate verdict ALIVE but the attempt ${bundle.terminalState}` }
+  }
+  // 6. no verdict evidence at all
+  return { owner: 'release-tooling', basis: 'no verdict evidence recorded — the lane ended an attempt it never measured' }
+}
+
+// The phase a failure terminal state stopped at, derived from the bundle's own evidence — or
+// the bundle's declared `failurePhase` when the author recorded one (declared wins, the same
+// rule as the owner: the mechanism closest to the failure knows more than the derivation).
+// Null for non-failure terminal states, exactly as the owner is.
+export function classifyFailurePhase(bundle) {
+  if (!isObject(bundle) || !FAILURE_STATES.has(bundle.terminalState)) return null
+  if (FAILURE_PHASES.includes(bundle.failurePhase)) return bundle.failurePhase
+  if (bundle.terminalState === 'rolled-back') return 'post-exposure'
+  if (isObject(bundle.liveVerdict) || isObject(bundle.trafficTransition)) return 'post-exposure'
+  if (isObject(bundle.candidateVerdict) || isObject(bundle.candidateReceipt)) return 'candidate-validation'
+  return 'pre-candidate'
+}
+
+// ---- discovery ----
+
+const ATTEMPT_KEY = /^(?<version>.+)-attempt\.(?<ordinal>\d+)$/
+const RC_KEY = /^(?<version>.+)-rc\.(?<ordinal>\d+)$/
+const normVersion = (v) => String(v ?? '').trim().replace(/^v/, '')
+
+// The version a bundle file belongs to, and its ordering ordinal, parsed from the FILENAME — the
+// filename is the immutable key (evidence-bundle.mjs), so a bundle whose content disagrees with
+// its own key is discovered under the key, exactly as `path` would locate it. Returns null for
+// anything that is not a bundle file (sidecars like `<id>-rollout.json` never match: the key and
+// state are separated by `--`, and the state must be one of #432's terminal states).
+function parseBundleFilename(entry) {
+  if (!entry.endsWith('.json')) return null
+  const stem = entry.slice(0, -'.json'.length)
+  const sep = stem.indexOf('--')
+  if (sep < 0) return null
+  const key = stem.slice(0, sep)
+  const state = stem.slice(sep + 2)
+  if (!ATTEMPT_TERMINAL_STATES.includes(state)) return null
+  const m = ATTEMPT_KEY.exec(key) ?? RC_KEY.exec(key)
+  if (!m) return null
+  return { key, state, version: m.groups.version, ordinal: Number(m.groups.ordinal) }
+}
+
+// Every durable bundle for one version, ordered by the immutable attempt id's ordinal —
+// NUMERICALLY, so attempt.10 follows attempt.9 (a lexicographic sort silently reorders history).
+// Legacy pre-#599 bundles key off the rc tag (`v<version>-rc.<n>`) and sort by the rc ordinal on
+// the same scale. Version comparison normalizes the leading `v` off BOTH sides (evidence-bundle's
+// own rule): a repo may spell its version `0.1.12` while its tags say `v0.1.12`.
+//
+// FAIL CLOSED, same reading as evidence-bundle.mjs: a dir that cannot be READ throws (EACCES,
+// ENOTDIR, …) — only ENOENT is "nothing emitted yet". A bundle FILE that cannot be parsed is not
+// skipped either: it comes back in `unreadable` so the profile can fault it — a durable record
+// that cannot be read is a hole in exactly the history this pass exists to account for.
+export function discoverVersionBundles(dir, version) {
+  if (!nonEmpty(dir)) throw new Error('discoverVersionBundles: a durable evidence dir is required')
+  if (!nonEmpty(version)) throw new Error('discoverVersionBundles: a version is required')
+  let entries
+  try {
+    entries = fs.readdirSync(dir)
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e
+    entries = []
+  }
+  const wanted = normVersion(version)
+  const attempts = []
+  const unreadable = []
+  for (const entry of entries) {
+    const parsed = parseBundleFilename(entry)
+    if (!parsed || normVersion(parsed.version) !== wanted) continue
+    const file = path.join(dir, entry)
+    let bundle = null
+    try {
+      bundle = JSON.parse(fs.readFileSync(file, 'utf8'))
+    } catch {
+      unreadable.push(`${entry} (unparseable)`)
+      continue
+    }
+    attempts.push({
+      attemptId: parsed.key,
+      ordinal: parsed.ordinal,
+      terminalState: parsed.state,
+      file: entry,
+      path: file,
+      bundle,
+    })
+  }
+  attempts.sort((a, b) => (a.ordinal - b.ordinal) || (a.attemptId < b.attemptId ? -1 : 1))
+  return { attempts, unreadable }
+}
+
+// ---- the per-attempt measurements ----
+
+// The highest traffic percent the candidate is recorded reaching, from whichever artifact carried
+// it: the staged transition (`stages[].to`), the atomic shape (`after.candidatePercent`), the
+// live verdict's read, or the receipt's. `null` when nothing recorded an exposure — reported as
+// absent, never zero-filled: 0% is a measurement (never exposed), null is no record.
+function maxExposure(bundle) {
+  const candidates = []
+  const tt = isObject(bundle.trafficTransition) ? bundle.trafficTransition : null
+  if (tt) {
+    if (Array.isArray(tt.stages)) {
+      for (const s of tt.stages) if (isObject(s) && Number.isFinite(s.to)) candidates.push(s.to)
+    }
+    if (isObject(tt.after) && Number.isFinite(tt.after.candidatePercent)) candidates.push(tt.after.candidatePercent)
+  }
+  const lv = isObject(bundle.liveVerdict) ? bundle.liveVerdict : null
+  if (lv) {
+    if (Number.isFinite(lv.candidatePercent)) candidates.push(lv.candidatePercent)
+    if (isObject(lv.traffic) && Number.isFinite(lv.traffic.candidate)) candidates.push(lv.traffic.candidate)
+  }
+  const receipt = isObject(bundle.candidateReceipt) ? bundle.candidateReceipt : null
+  if (receipt && Number.isFinite(receipt.trafficPercent)) candidates.push(receipt.trafficPercent)
+  return candidates.length ? Math.max(...candidates) : null
+}
+
+// Every recorded traffic-affecting mutation: each observed shift stage (or the single before/after
+// transition), plus the rollback restore — restoring the incumbent is a traffic mutation too, and
+// counting only the shifts would understate what production went through by exactly the unwind.
+function trafficMutations(bundle) {
+  let n = 0
+  const tt = isObject(bundle.trafficTransition) ? bundle.trafficTransition : null
+  if (tt) {
+    if (Array.isArray(tt.stages)) n += tt.stages.filter(isObject).length
+    else if (isObject(tt.before) && isObject(tt.after)) n += 1
+  }
+  if (bundle.terminalState === 'rolled-back' && isObject(bundle.disposition)) n += 1
+  return n
+}
+
+// Rolled back while the recorded evidence shows the candidate healthy/ready. Reported SEPARATELY
+// from unhealthy rollbacks (the AC): a healthy candidate rolled back is the lane doubting itself,
+// an unhealthy one is the lane working — conflating them is how "the tooling cried wolf six times"
+// reads as "the release failed six times". The signal is POSITIVE health evidence in the live
+// verdict (healthy/* runtime status, ALIVE, probe-succeeded) — a candidate merely judged ALIVE at
+// 0% is not "healthy when rolled back", because exposure is where health became a question.
+const healthyAtRollback = (a) => a.terminalState === 'rolled-back' && healthyLiveSignal(a.bundle.liveVerdict)
+
+// ---- the profile ----
+
+// Whether the version was REUSED or BURNED. Under both tag-after-verify shapes a failed attempt
+// burns nothing (principle 10: the only tag carrying a promise is minted post-verification), so
+// more than one attempt means the version was reused. The burn is the legacy `final-tag` shape:
+// the pipeline fires on the final tag, so a failed attempt consumed the version claim and the
+// retry takes the next patch (references/versioning.md). A burn the bundle itself recorded
+// (`disposition.versionWithdrawn`) is honored on any shape.
+function versionDisposition(attempts) {
+  const burned = attempts.some((a) => a.bundle.deployTrigger === 'final-tag'
+    || (isObject(a.bundle.disposition) && a.bundle.disposition.versionWithdrawn === true))
+  if (burned) return 'burned'
+  return attempts.length > 1 ? 'reused' : 'single-attempt'
+}
+
+export function versionPostmortem({ dir, version, runSlug = null } = {}) {
+  const { attempts, unreadable } = discoverVersionBundles(dir, version)
+
+  const rows = attempts.map((a) => {
+    const failure = classifyFailureOwner(a.bundle)
+    return {
+      attemptId: a.attemptId,
+      ordinal: a.ordinal,
+      terminalState: a.terminalState,
+      rcTag: nonEmpty(a.bundle.rcTag) ? a.bundle.rcTag : null,
+      maxExposure: maxExposure(a.bundle),
+      trafficMutations: trafficMutations(a.bundle),
+      failureOwner: failure?.owner ?? null,
+      failureBasis: failure?.basis ?? null,
+      failurePhase: classifyFailurePhase(a.bundle),
+      healthyAtRollback: healthyAtRollback(a),
+      file: a.file,
+    }
+  })
+
+  const terminalStates = Object.fromEntries(ATTEMPT_TERMINAL_STATES.map((s) => [s, 0]))
+  for (const r of rows) terminalStates[r.terminalState] += 1
+
+  const rcTags = new Set(rows.map((r) => r.rcTag).filter(Boolean))
+  const rolledBack = rows.filter((r) => r.terminalState === 'rolled-back')
+  const metrics = {
+    version: String(version),
+    attempts: rows.length,
+    rcCount: rcTags.size,
+    nonReleased: rows.length - terminalStates.released,
+    terminalStates,
+    rollbacks: rolledBack.length,
+    trafficMutations: rows.reduce((n, r) => n + r.trafficMutations, 0),
+    maxExposure: rows.reduce((m, r) => (r.maxExposure != null && r.maxExposure > m ? r.maxExposure : m), 0),
+    healthyAtRollback: rolledBack.filter((r) => r.healthyAtRollback).map((r) => r.attemptId),
+    healthyAtFullExposure: rolledBack.filter((r) => r.healthyAtRollback && r.maxExposure === 100).map((r) => r.attemptId),
+    otherAtRollback: rolledBack.filter((r) => !r.healthyAtRollback).map((r) => r.attemptId),
+    versionDisposition: versionDisposition(attempts),
+  }
+
+  const findings = []
+
+  // A durable record that cannot be read is a hole in the account this pass exists to keep.
+  if (unreadable.length) {
+    findings.push({
+      id: 'unreadable-version-bundle',
+      severity: 'high',
+      costMinutes: null,
+      headline: `${unreadable.length} bundle(s) for ${version} could not be read`,
+      detail: 'The aggregate is computed from the durable bundles, and a bundle that does not parse is an attempt whose record is unreachable — the same completeness failure the single-manifest pass faults, one level up. The counts above exclude it.',
+      evidence: unreadable,
+      recommendation: 'Read the file by hand and repair or quarantine it. Do not delete it: a damaged durable record is still the only record of its attempt.',
+    })
+  }
+
+  // The finding this pass exists for (#961): one failure owner repeating across attempts. Eight
+  // failed Forex attempts all owned by the release tooling is a systemic signal; the same signal
+  // spread across eight single-manifest post-mortems was eight files that each said nothing
+  // wrong. Threshold: two occurrences is worth a line, three or more is the dominant story.
+  const byOwner = new Map()
+  for (const r of rows.filter((x) => x.failureOwner)) {
+    if (!byOwner.has(r.failureOwner)) byOwner.set(r.failureOwner, [])
+    byOwner.get(r.failureOwner).push(r)
+  }
+  for (const [owner, owned] of [...byOwner.entries()].sort((a, b) => b[1].length - a[1].length)) {
+    if (owned.length < 2) continue
+    findings.push({
+      id: 'repeated-failure-owner',
+      severity: owned.length >= 3 ? 'high' : 'medium',
+      costMinutes: null,
+      headline: `\`${owner}\` owned ${owned.length} of ${rows.filter((r) => r.failureOwner).length} failed attempt(s) of ${version}`,
+      detail: 'One owner repeating across attempts of one version is a systemic signal, not N independent failures: the retry loop is re-entering the same defect with a new candidate each time, and each retry pays the full attempt cost. The classification is derived from the recorded verdicts (references/postmortem.md § failure ownership) — adjudicate the owner, then fix the owner, not the candidate.',
+      evidence: owned.map((r) => `${r.attemptId} (${r.terminalState}${r.maxExposure != null ? `, reached ${r.maxExposure}%` : ''}) — ${r.failureBasis} — ${r.file}`),
+      recommendation: 'Adjudicate each attempt against its bundle before acting: a mis-classified owner sends the fix to the wrong place, and the heuristic is documented so it can be argued with. Where the owner is `release-tooling`, the issue belongs against the release lane, not the application.',
+    })
+  }
+
+  const healthyNote = metrics.healthyAtRollback.length
+    ? ` · ${metrics.healthyAtRollback.length} rolled back while healthy/ready (${metrics.healthyAtFullExposure.length} at 100%)`
+    : ''
+  const summaryLine = rows.length === 0
+    ? `no durable bundles discovered for ${version}`
+    : [
+      `${metrics.attempts} attempt(s)`,
+      `${metrics.rcCount} rc tag(s)`,
+      `${metrics.nonReleased} non-released`,
+      `${metrics.rollbacks} rolled back${healthyNote}`,
+      `${metrics.trafficMutations} traffic mutation(s)`,
+      `max exposure ${metrics.maxExposure}%`,
+      `version ${metrics.versionDisposition}`,
+    ].join(' · ')
+
+  return {
+    kind: 'release-version',
+    runSlug: nonEmpty(runSlug) ? `${runSlug}@${version}` : `version-${version}`,
+    source: `the durable evidence bundles for ${version} under ${dir}`,
+    summaryLine,
+    metrics,
+    attempts: rows,
+    blindSpots: 'attempts that never emitted a bundle (a session that died before a terminal exit), bundles outside this evidence dir, and everything the bundles themselves cannot see — the aggregate is exactly as complete as the durable records it discovered',
+    findings,
+  }
+}
+
+// The per-attempt table, rendered for the handoff and the CLI. The persisted .txt stays
+// renderProfile's (the series format is shared with both other kinds); this table is what makes
+// the aggregate readable at a glance where it is printed.
+export function renderAttemptTable(p) {
+  if (!p.attempts?.length) return ''
+  const lines = p.attempts.map((a) => {
+    const exposure = a.maxExposure == null ? 'no exposure recorded' : `max exposure ${a.maxExposure}%`
+    const owner = a.failureOwner ? ` — owner: ${a.failureOwner}${a.failurePhase ? ` (${a.failurePhase})` : ''}` : ''
+    const healthy = a.healthyAtRollback ? ' [healthy/ready when rolled back]' : ''
+    return `  ${a.attemptId}  ${a.terminalState}  ${exposure}${a.trafficMutations ? `  ${a.trafficMutations} traffic mutation(s)` : ''}${owner}${healthy}`
+  })
+  return `${lines.join('\n')}\n`
+}
+
+export function renderVersionPostmortem(p) {
+  return `${renderAttemptTable(p)}${renderProfile(p)}`
+}
+
+// The same series, the same renderer, the same persistence as the run-level passes — one more
+// `kind` in the shared index, which is what lets the cross-run tooling read it without a new
+// format. NEVER THROWS, on saveProfile's terms.
+export function saveVersionPostmortem(p, env = process.env, now = new Date()) {
+  return saveProfile(p, env, now)
+}
+
+// ---- CLI ----
+
+const USAGE = `version-postmortem — the version-level release post-mortem (#961).
+
+Aggregates every durable evidence bundle one version left behind (<version>-attempt.<n>--<state>.json,
+legacy <version>-rc.<n> keys included), ordered by the immutable attempt id, and reports: attempt
+and rc counts, terminal-state counts, maximum exposure per attempt, traffic mutations, rollback
+count (healthy-at-rollback separately from the rest), reused-vs-burned, and a normalized failure
+owner per failed attempt — ${FAILURE_OWNERS.join(' | ')} — with a finding when one owner repeats.
+
+Usage:
+  version-postmortem --dir <durable-evidence-dir> --version <v> [--run-slug <slug>] [--save] [--issue]
+
+  --save    persist the profile into the shared post-mortem series (kind: release-version)
+  --issue   print {title, body} for filing against resolve-release
+
+Doctrine: resolve-release/references/postmortem.md (the classification table is the stable
+surface #962 consumes).`
+
+function parseArgs(argv) {
+  const opts = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--help' || a === '-h' || a === '--save' || a === '--issue') opts[a.replace(/^--/, '')] = true
+    else if (a.startsWith('--')) opts[a.slice(2)] = argv[++i]
+  }
+  return opts
+}
+
+export function main(argv) {
+  const opts = parseArgs(argv)
+  if (opts.help) {
+    console.log(USAGE)
+    return 0
+  }
+  if (!nonEmpty(opts.dir) || !nonEmpty(opts.version)) {
+    console.error('version-postmortem: usage: --dir <durable-evidence-dir> --version <v> are both required (see --help)')
+    return 2
+  }
+  let p
+  try {
+    p = versionPostmortem({ dir: opts.dir, version: opts.version, runSlug: opts['run-slug'] ?? null })
+  } catch (e) {
+    // Fail closed: an unreadable evidence dir is not an empty history.
+    console.error(`version-postmortem: ${e.message}`)
+    return 2
+  }
+  if (opts.issue) {
+    console.log(JSON.stringify({ title: `resolve-release version post-mortem: ${opts.version} (${p.summaryLine})`, body: renderVersionPostmortem(p) }, null, 2))
+    return 0
+  }
+  process.stdout.write(renderVersionPostmortem(p))
+  if (opts.save) {
+    const written = saveVersionPostmortem(p)
+    if (written.saved) process.stdout.write(`\n  saved: ${written.paths.json}\n  series: ${written.paths.index}\n`)
+    else {
+      console.error(`warn: version post-mortem computed but NOT saved — ${written.error}`)
+      return 1
+    }
+  }
+  return 0
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exitCode = main(process.argv.slice(2))
+}