@1aboveio/skills 0.10.0

package/skills/engineering/resolve-release/references/exposure.md

@@ -0,0 +1,178 @@
+# Step 4: validate the candidate, then expose it
+
+The gate, and the moment users first meet the new code. Previous:
+[candidate.md](candidate.md) · next: [routing.md](routing.md).
+
+### 4 — Validate the candidate, then expose it (skill: smoke)
+Two phases, in this order, and the order is the whole design: **validate at 0% traffic, then shift.** A smoke that runs after traffic has moved is a monitor — the bug is already live when it goes red.
+
+**4a — Validate the candidate (no users exposed).** **Read `<skillsRoot>/smoke/SKILL.md` (absolute — same path resolution as step 2) and run the curated E2E happy-path gate against the candidate URL** — not a from-memory smoke:
+
+```bash
+M=smoke.manifest.json; T=<candidateUrl>
+node <smoke>/scripts/smoke.mjs plan --manifest $M --profile prod-preview --target $T   # what will run
+#   ...drive the planned paths against $T, writing smoke-results.json (smoke/SKILL.md owns how)
+node <smoke>/scripts/smoke.mjs verdict --manifest $M --profile prod-preview --target $T \
+  --results smoke-results.json --out smoke-verdict.json
+```
+
+**Select the profile by name — `prod-preview`, the pre-promotion / production / preview-revision profile.** `$T` is only the address to drive against now; the profile decides the path set and the mutation policy. **Run `plan` first and read what it selected.** `verdict` re-derives the expected set from the same profile, so `plan` is where you see what the gate will actually cover — and on production it can cover *nothing*: `prod-preview` is read-only and excludes every `mutates:true` path, and golden paths are typically signup/checkout/purchase, which are all mutating. A gate that selects zero paths proves zero things. `verdict` returns **EMPTY** (exit 1) rather than a vacuous ALIVE in that case, but treat EMPTY as a **manifest problem to fix before releasing**, not a failing candidate: it means this repo has no read-only golden path worth gating on, and production is currently ungated. Add one (a health route, an authenticated GET of the core object) declared in `prod-preview`, rather than routing traffic on an empty verdict.
+
+The `prod-preview` profile is **read-only** and enforces [principle 4](../SKILL.md#non-negotiable-principles) mechanically: it excludes **every** `mutates:true` path, tenant or not, because the candidate is wired to the real production database — the old `--no-mutations` flag is now a property of the named profile, not something the caller must remember. And because selection is a pure function of the profile name, passing the **same** `--profile` to the run and to `verdict` makes them select one path set *by construction*: the run/verdict mismatch that free-form `--target`/`--no-mutations` once permitted — and the "check the flags before believing a DEAD" warning it needed — is now unrepresentable. This exercises the real image, real secrets, real infra, at zero user exposure. **DEAD → step 5, pre-exposure path.**
+
+**Three not-ALIVE outcomes, and they are about three different things — do not collapse them.** Each names a different defect, so each routes differently, and the routing is the reason the distinction exists:
+
+- **DEAD** — the gate ran and the candidate failed it. Evidence about the **candidate**. → step 5's **pre-exposure path**: delete the 0%-traffic revision, file a normal issue, hand the evidence to `app-debug`/`diagnose`.
+- **EMPTY** — the gate ran and selected zero paths. Evidence about the **manifest**: this repo has no read-only golden path, so production is currently ungated. → fix the manifest (a health route, an authenticated GET of the core object) and re-run. `verdict` returns EMPTY (exit 1) rather than a vacuous ALIVE precisely so it cannot be mistaken for a pass.
+- **CANNOT-RUN / BLOCKED** — the gate itself could not produce a verdict. Evidence about the **gate**. Examples: the smoke harness could not authenticate because a secret env var holds the **resource-name string** (`projects/…/secrets/forex-smoke/versions/latest`) instead of the **secret value**, so every request gets 401/403; an external boundary it drives was unavailable; a fixture had drifted; the runner would not start. Under [principle 13](../SKILL.md#non-negotiable-principles) this is a **failure, not an absence** — so it is not a pass and traffic does not move — and it is equally not a DEAD, so nothing here judged the candidate and nothing here licenses deleting it. → **repair the gate** (fix the secret/config, restore the credential, repair the fixture) and **re-run 4a**. If it cannot be restored, the release stops with the candidate unvalidated; the route is still "the gate is the defect," never a pre-exposure discard of a candidate nothing judged.
+
+The two mis-routings this prevents sit on either side of it. A cannot-run recorded as DEAD deletes a healthy candidate and sends a diagnosis team after an application bug that does not exist. A cannot-run recorded as a skipped step shifts production traffic on a gate that never asked its question — and the artifact it leaves behind reads like a validated release. **And the block stays scoped** (principle 13): this SHA does not release; the queue or PR lane that carries the fix — to the harness, the fixture, the credential, or the secret — is not paused, and the fix arrives through it like any other unit.
+
+**4b — Shift traffic to 100%.** This is the moment users are exposed, so it is **its own authorization** (principle 1; per-step confirm by default, pre-flight item 3) — the promotion approval in step 3 does not carry here.
+
+**Re-probe credentials before any 4b action and on resume when `step` is `validate` or `expose`.** The credential named at pre-flight item 3 can expire while the 4a verdict is pending. Run the same probe command pre-flight item 0 runs:
+
+```bash
+node <resolve-release>/scripts/reprobe-credentials.mjs [--command <cmd>]
+```
+
+It fails closed: exit 0 only when the credential is live. A BLOCKED or UNKNOWN result stops here — apply the same remedy as pre-flight item 0 and do not pause, shift, or resume past it. On resume when `step` is `validate` or `expose`, run this probe before any other read.
+
+**Where pre-flight item 6 declared durable processing, the shift is a sequence and the fence sits inside it** ([principle 14](../SKILL.md#non-negotiable-principles)). Run these five in order, in **both envelope modes** — `auto-when-green`'s condition (e) authorizes *the exposure*, not a shorter one with the ordering removed:
+
+Mechanize steps 1-2 through the validated repository adapter after recording `step: "expose"`:
+
+```bash
+node <resolve-release>/scripts/durable-processing.mjs down \
+  --declaration <repository-release-declaration.json> \
+  --release-state <run-manifest.json> > durable-processing-down.json
+```
+
+Only `state: "ready-to-shift"` licenses the fence. Its `proof.observed` is the durable-state
+reading, and its `shiftFence` is the generation/fencing identity carried into the shift record.
+`blocked`, `refused`, malformed, or partial output takes the pre-shift unwind and never shifts.
+
+1. **Pause, in the declared order** — outermost first, database admission before worker scheduling, so nothing new enters the pipeline while its far end is still draining. Set `step: "expose"` **before the first pause**, not before the shift: the pause is the first action that changes what production *does*, and a crash after it with the manifest still reading `validate` leaves processing stopped and nothing recording that it is.
+2. **Prove quiescent** with the read declared at item 6 — in-flight count at zero, queue depth drained, no active scheduler execution — and **record the reading, not the judgment**: the observed value goes in `release.quiescence.proof`, because `quiesced: true` is the assertion again one field deeper and no second reader can tell it from a check that never ran. The pause command's success is **not** this proof; it is the request this proof checks. **Not yet quiescent is a wait, not a pass** — re-read until it drains or the declared bound elapses, and an elapsed bound ends the attempt down the [pre-shift unwind path](routing.md#5--route-on-the-verdict). A proof that **cannot run** is [principle 13](../SKILL.md#non-negotiable-principles): it fails rather than absents, so it licenses no shift, and it takes that same unwind.
+3. **Fence** — the three assertions below, unchanged and undiluted. They run *after* quiescence because they describe the state the shift is about to act on, and the pause is what stops that state moving underneath them.
+4. **Shift** to the revision the fence just re-established — never "the newest candidate", and never a handle re-read after the fence.
+5. **Resume in the exact reverse of step 1's order** — worker scheduling first, database admission last — against the **revision now serving**, confirming each rather than firing and moving on. The reversal is [principle 14](../SKILL.md#non-negotiable-principles)'s rule, not this repo's example: resuming admission before the workers that drain it re-opens the front of a pipeline whose back end is still stopped, which is the queue-growth incident with the traffic shift subtracted.
+
+Record the sequence as `release.quiescence` = `{ pausedAt, pauseOrder, proof, resumedAt, resumeOrder, servingRevisionAtResume }` — the two orders **as executed**, so a reader checks the reversal instead of trusting it. Where item 6 declared **no** durable processing, none of this runs and the rest of 4b is the whole step.
+
+After the shift's serving-revision proof, drive step 5 against that proven revision and the
+generation/fence from `durable-processing-down.json`:
+
+```bash
+node <resolve-release>/scripts/durable-processing.mjs up \
+  --declaration <repository-release-declaration.json> \
+  --serving-revision <proven-serving-revision> \
+  --incumbent-revision <release.previousRevision> \
+  --candidate-revision <release.candidateRevision> \
+  --generation <shift-fence-generation> --fence <shift-fence> \
+  > durable-processing-up.json
+```
+
+Only `state: "restored"` completes exposure. It proves the named serving revision is exactly
+the declared candidate at 100% with the incumbent at 0%; `ambiguous` stops and pages.
+
+**Floor applicability was decided at preflight, not here** (identity-v0.4.1 / #800; #910).
+`release.productionEndpoints` binds the deploy trigger configured production URL to the
+independently observed Cloud Run service URL. A distinct public/edge hostname requires fresh
+read-only `prod-active` ALIVE targeted exactly at that canonical URL; it cannot skip. Cloud
+Run-only is accepted only through the fingerprint-bound reasoned skip emitted when the two reads
+share a hostname. `green-gate.mjs shift` rechecks topology, target, fingerprint, and freshness and
+HOLDs with `e:floor-not-ready` on any absence, mismatch, stale evidence, or hand-authored bypass.
+On resume, run `production-endpoints.mjs resume` before the credential/fence reads and return to
+preflight when endpoint configuration changed.
+
+**The authorization is not the last check: re-check the coordinates after it (the fence).** 4a's verdict was minted *before* the wait, and the wait is unbounded — a human confirm can arrive four hours later, and under `auto-when-green` the gate fires whenever it happens to be evaluated. In between, the coordinates move: a newer build takes the `candidate` tag, the incumbent stops holding all the traffic, a second release starts. An authorization is permission to shift **these** coordinates, never permission to shift whatever the coordinates have become. So **after** the confirm and **before** the shift, re-read the live state and compare it against what the manifest recorded:
+
+```bash
+node <resolve-release>/scripts/green-gate.mjs shift \
+  --manifest <run-manifest.json> --verdict smoke-verdict.json > fence-verdict.json   # 0 = fresh
+gcloud run services describe <svc> --region <r> --flatten='status.traffic[]' \
+  --format='value(status.traffic.tag,status.traffic.url,status.traffic.revisionName,status.traffic.percent)' \
+  > fence-traffic.txt
+```
+
+**`--flatten` is what makes the second read identity evidence and not just a split.** Unflattened, `value(status.traffic.revisionName,status.traffic.percent)` returns two parallel lists with nothing tying a revision to the tag that points at it — enough to see the percentages, structurally incapable of showing what the candidate URL resolves to. Flattened, each traffic target is one row carrying its `tag`, its `url`, the `revisionName` it currently routes to, and its `percent`, so all three assertions below read off the same observation.
+
+Three assertions, each against observed state, none against the manifest alone — and each one **recorded as the value it read**, never as the judgment it produced:
+
+1. **Freshness** — 4a's verdict is still inside `envelope.verdictFreshnessMinutes` (pre-flight item 3). `green-gate.mjs shift` decides it from the verdict's recorded timestamp and holds on `e:stale-verdict`, or on `e:unstamped-verdict` when the artifact carries no timestamp — absent evidence is not fresh evidence. **An expired verdict routes back to 4a, never onward to the shift**: re-run the candidate validation, then re-enter here. This is cheap and it is the point — the candidate is usually fine; what expired is the *evidence*, and re-minting it costs one smoke run. **Re-run the *run*, not just `verdict`** — `smoke.mjs verdict` stamps `generatedAt` when the verdict is minted, not when the paths were driven, so re-reducing the old `smoke-results.json` produces a gate-fresh artifact over observations nobody re-took, and the gate cannot tell. (`verdict`-only is the right move for a *flag* mismatch, where the observations are good and only the selection was wrong.) *Recorded as* `gate` — the gate's own JSON, which carries the age it computed and the window it compared against.
+2. **Identity** — the flattened row whose `url` is the recorded `release.candidateUrl` (equivalently, whose `tag` is the recorded `release.candidateIdentity.tag`) still names `release.candidateRevision`. **The SHA-keyed tag makes this assertion decisive rather than merely alarming, and does not make it redundant**: step 3 established identity at discovery, and this re-establishes it after an unbounded wait, which is a different question. What changed is the failure it can see — a rival release can no longer take this SHA's tag, so a disagreement here is the tag being deleted, re-pointed by a rebuild, or resolving to a revision that no longer exists, rather than a silent substitution. *Recorded as* `candidateResolvesTo` — **the revision name the URL actually resolved to, copied from the reading**, not a boolean and not the name you expected: an identity check recorded as `true` is the assertion again, one field deeper, and a reader cannot tell it apart from a check that never ran. If it resolves to a different revision — or the candidate revision is absent from the traffic list entirely — **stop**, and read what the disagreement means from the guarantee you are under: with a shared `candidate` tag it is a second release in flight (principle 7) and you are about to shift under another release's identity; with a SHA-keyed tag it is your own handle no longer naming your artifact. Either way what you validated is not what you would expose.
+3. **Traffic** — the candidate still holds **0%**, and `release.previousRevision` still holds **exactly 100%**. Anything else means the split moved while the authorization was pending, so nothing you validated describes what is serving now. *Recorded as* `candidatePercent` and `previousRevisionPercent`, the two numbers as read.
+
+**Any of the three failing ends the attempt without exposure** — do not shift, do not "re-check and proceed anyway." Nobody was exposed, so this is not a failure tier at all: re-establish the coordinates (re-validate at 4a, or resolve the second release in flight) and re-enter 4b under a fresh authorization.
+
+**Run the fence in both envelope modes.** Under `auto-when-green` `green-gate.mjs shift`'s exit code *is* the authorization. Under a per-step confirm it is a **check the human's yes does not substitute for** — the human authorized the shift, the fence establishes that the coordinates are still the ones they authorized. A script never authorizes anything (principle 1); it only turns "still true?" from a claim into a comparison.
+
+Then set `step: "expose"` *before* issuing the shift — on a **plain shift** it means "a shift was started and may or may not have landed," which is exactly the state a crash here leaves behind. Where the sequence above ran, `step` is **already** at `expose` from before the first pause and means "the exposure sequence started"; the re-set is idempotent, and what separates a paused-but-unshifted production from a landed shift is the resume's **two** reads — the traffic split *and* the processing state — never `step` alone. Shift traffic, then **confirm the live service is the candidate you validated — by re-reading the tuple it attested, not by re-deriving identity from a string**, and **assert its display version matches `envelope.displayVersionPolicy`**:
+
+```bash
+LIVE_TARGET=$(node <resolve-release>/scripts/production-endpoints.mjs live-target \
+  --manifest <run-manifest.json>)
+node <resolve-release>/scripts/production-endpoints.mjs verify-live \
+  --manifest <run-manifest.json> --target "$LIVE_TARGET"
+curl -fsS "$LIVE_TARGET/health" > serving-health.json
+curl -fsS "$LIVE_TARGET/settings" > serving-settings.json
+<read the served frontend asset version into frontend-asset-version.json>
+node <resolve-release>/scripts/candidate-identity.mjs serving --sha $SHIPPED \
+  --identity candidate-identity.json --health serving-health.json    # exit 1 = not the candidate
+```
+
+The identity read above is not this step, and neither replaces the other: the attestation says *which* code is serving and nothing about whether it works, while a smoke says the golden paths are alive and nothing about whose build answered — a bare health curl offered as verification passes on any revision that boots, including the old one still serving.
+
+**Run `version-assert.mjs` next as the standalone mandatory publication gate** ([versioning §6](versioning.md#6-display-version-is-not-identity-version)). It must receive `serving-health.json`, `serving-settings.json`, and the frontend asset-version JSON. Its own process exit is recorded as `release.versionAssert`; exit 1 or 2 stops the release before step 5. Do not put a shell separator or any smoke/informational follow-on command after it. Only an exit-0 `decision:"accept"` permits the final-tag and GitHub-Release publication path.
+
+```bash
+node <resolve-release>/scripts/version-assert.mjs serving \
+  --health serving-health.json \
+  --settings serving-settings.json \
+  --frontend-asset frontend-asset-version.json \
+  --policy "$DISPLAY_VERSION_POLICY" \
+  --version "$NEXT_VERSION" \
+  --trigger-tag "$RC_TAG" \
+  --sha "$SHIPPED"
+```
+
+The display-version assertion is a third check: it confirms the `/health`, `/settings`, and frontend asset version strings operators see match the policy declared at pre-flight, closing the rc-tag case where UI and `/api/health` would otherwise keep showing the attempt tag after the final claim. A mismatch refuses unless the envelope recorded a `--record-mismatch <reason>` exception (see [`scripts/version-assert.mjs --help`](../scripts/version-assert.mjs) and [references/versioning.md](versioning.md#6-display-version-is-not-identity-version)).
+
+**`--sha $SHIPPED` is not redundant with the file you are passing.** Without it this check proves the record and the live process agree — a true statement about *whichever release the record describes*, which is worth nothing if a resumed session handed it the previous rc's `candidate-identity.json`. It refuses on `e:identity-sha-mismatch` (the record describes another commit) or `e:identity-guarantee-unbacked` (the record's `guarantee` is contradicted by its own tag or missing digest) **before** it decides anything else — including before it routes to the fallback below, which would otherwise send you off to compare digests against that same wrong record.
+
+**Fallback, only where pre-flight item 3 declared no attesting endpoint**: read the serving revision's image and **compare image digests, not revision names** — platforms name revisions from their own counter (`{service}-prod-00042-abc`), which carries no SHA, so a name comparison silently never matches and degrades into no check at all. The comparison is the same script, handed the digest instead of a tuple:
+
+```bash
+# Select the entry HOLDING the traffic, never the first one in the array. The same flattened read
+# as the fence above, so `revisionName` and `percent` come off one row and the selection is a
+# comparison rather than a position.
+SERVING=$(gcloud run services describe <svc> --region <r> --flatten='status.traffic[]' \
+  --format='value(status.traffic.revisionName,status.traffic.percent)' \
+  | awk -F'\t' '$2 == 100 { print $1 }')
+[ "$(printf '%s' "$SERVING" | grep -c .)" = 1 ] || { echo "no single revision holds 100%: '$SERVING'"; exit 1; }
+SERVING_DIGEST=$(gcloud run revisions describe "$SERVING" --region <r> \
+  --format='value(status.imageDigest)')
+node <resolve-release>/scripts/candidate-identity.mjs serving --sha $SHIPPED \
+  --identity candidate-identity.json --serving-image-digest "$SERVING_DIGEST"   # exit 1 = not the candidate
+```
+
+**Never read `status.traffic[<index>]` — a position is not a routing fact, and reading one inverts this check.** A traffic array is free to list the candidate at 0% first and the incumbent at 100% second, which is exactly the array a **green-but-ineffective shift leaves behind**. The first slot then hands this fallback the *candidate's own* digest, it matches the record it was supposed to be tested against, and `--serving-image-digest` exits 0 while every user is still on the incumbent. That is the failure this step names below in as many words — *"a green shift with traffic still on the old revision is a failed exposure, not a released one"* — made invisible by the read that was supposed to catch it, and it contradicts [principle 5](../SKILL.md#non-negotiable-principles): the loop exits on **observed production state**, and "first in the array" is not a state anything observes. Select by `percent`, and treat "not exactly one revision at 100%" as its own stop: a split means the shift did not take, so there is no serving revision to confirm.
+
+**Both sides of that comparison are real, and that is what the declaration bought.** The recorded `release.candidateIdentity.imageDigest` in this branch is the *candidate revision's* configured digest, supplied at step 3 as `--candidate-image-digest` — the substitute pre-flight item 3 requires precisely so this check has something to compare against. Without it the field would be `null` here, and a fallback pointed at a null field is not a weaker check, it is no check wearing one's clothes. Omitting `--serving-image-digest` therefore refuses with **`e:no-attested-tuple`** — "nothing was compared, take the read and re-run" — rather than passing.
+
+Use the digest rather than the `:$SHIPPED` tag suffix wherever the platform exposes one: a tag is a mutable pointer a registry can re-point, and the honest cost of this fallback is that both digests describe the artifact a revision was *configured with* rather than the code that is *running*. Then **re-run the smoke against `$LIVE_TARGET` under the `prod-active` profile** (the post-promotion / production / active-revision profile — also read-only; the canonical configured production URL now, never an arbitrary equivalent service URL) and set `step: "verify"`. **The identity read above is not this step, and neither replaces the other**: the attestation says *which* code is serving and nothing about whether it works, while a smoke says the golden paths are alive and nothing about whose build answered — a bare health curl offered as verification passes on any revision that boots, including the old one still serving.
+
+**Multi-service releases shift as a set, and a partial shift is its own emergency.** One rc tag can produce one candidate *per service*, so record `candidateRevision`/`candidateUrl`/`previousRevision` **per service**, validate each in 4a, and fence each before its own shift. Shift in dependency order, and if any service fails to shift, **stop and complete the set** — do not debug with production half-shifted. Users are then split across a service boundary, running two versions of a contract that were never validated together; 4a cannot catch it, because it validated each candidate in isolation. Neither failure tier fits (nothing is unhealthy, nothing is un-shipped), so the response is: finish the shift if the remaining service is healthy, or shift the already-moved services **back** to their previous revisions if it is not. Only once the set is consistent do you diagnose.
+
+**A green shift with traffic still on the old revision is a failed exposure, not a released one** — and it is its own outcome, distinct from both failure tiers: production is healthy, users were never exposed, the candidate is fine, and only the routing command failed. Do **not** run the rollback policy (there is nothing to restore, and filing an incident for a non-incident is what principle 6 warns teaches people to route around the gate), and do **not** accept step 4a's ALIVE as verification (it described the candidate, not the live service). Diagnose why routing did not take — most often the revision never became `Ready` — then either re-issue the shift or, if the candidate is at fault, go to the pre-exposure path in step 5. A blind retry just fails again more slowly.
+
+**And where the sequence's own state is ambiguous, stop and page — do not route it at all** ([principle 14](../SKILL.md#non-negotiable-principles); [principle 6](../SKILL.md#non-negotiable-principles)'s third case). The qualifying states are narrow and worth naming, because each one is a *read* that came back unusable rather than a step that failed: the pause was issued and the quiescence read cannot say whether the workers drained; the shift errored and the traffic split reads as neither the old shape nor the new one; a resume was issued and it cannot be confirmed that scheduling or admission is actually back. **None of these is the pre-exposure discard**, and the pull toward filing it as one is strong precisely because that route is cheap, blameless, and explicitly "routine, not an outage" — but that route *asserts production is untouched*, and here production is the thing nobody can describe. Deleting a revision, resuming a worker, or re-issuing a shift against a state you cannot read is a write against durable data on a guess. Page, hand over the readings you **do** have (the last good quiescence proof, the traffic rows as they actually returned, which resumes were issued and which were confirmed), and let a human establish the state before anything further is issued.
+
+**Proof-of-execution:** capture `smoke-results.json`, the ALIVE/DEAD verdict, **the re-check fence's readings**, the serving-revision confirmation, and the post-shift health results (principle 5 — the loop exits on observed state, never a claim; here that state is observed twice, once per phase). The fence is an artifact, not a sentence in the report: record `release.recheckFence` = `{ gate: <green-gate shift JSON>, candidateResolvesTo, candidatePercent, previousRevisionPercent, checkedAt }` in the manifest, written **between** the authorization and the shift. A report that says the coordinates were re-checked, with no recorded reading of what they were, is the prose form of the check this fence replaced. **Where durable processing was declared, `release.quiescence` is owed on the same terms** — the pause order as executed, the quiescence proof's observed value, the resume order, and the revision it was resumed against; a sequence reported as "paused, drained, shifted, resumed" with no reading behind any of it is the same prose failure applied to the one ordering whose cost is durable.
+
+**The post-shift half is recorded the same way.** `release.servingConfirmation` = `{ gate: <candidate-identity serving JSON>, candidatePercent, previousRevisionPercent, checkedAt }` — the decision artifact beside the traffic split as read, never `confirmed: true` — and `release.liveVerdict` = `{ state, artifactPath, generatedAt, target }`, the pointer to the prod-active verdict artifact. Both are what step 5's [finalizer](routing.md#5--route-on-the-verdict) validates before it records the terminal closure; a confirmation held in prose is a release that cannot finalize.
+
+**Every assertion owes a field here and a grading question in [row 4b](regression-checklist.md).** The mapping is one-to-one and deliberate: freshness → `gate`, identity → `candidateResolvesTo`, traffic → `candidatePercent` + `previousRevisionPercent`, all stamped `checkedAt`. An assertion with no field is the one that quietly degrades back into prose, because nothing in the artifact and nothing in the checklist can tell a performed check from a claimed one — and it degrades exactly where it costs most: a fence recorded complete and green while the candidate URL points at another release's revision is a shift under a stolen identity that every downstream reader will read as verified. So a *fourth* assertion added later gets the same two homes in the same edit, and this file's `recheckFence` shape, the fence's command block, and row 4b move together.
+
+If production is unhealthy **after** the shift, that is the post-exposure tier — step 5 rollback, not a candidate deletion.

package/skills/engineering/resolve-release/references/handoff.md

@@ -0,0 +1,24 @@
+# The handoff report — what a finished release owes its reader
+
+Read this when a release reaches a terminal step (`done` / `discard` / `rollback`), or when a stall
+hands back. [SKILL.md](../SKILL.md#definition-of-done-handoff-report) states the bar and names the
+items; this file is each item in full — what to report, in what form, and the cases where the
+report says something even though nothing went wrong.
+
+Three items are unconditional, and the reasoning for that is
+[why.md](why.md#why-the-handoff-reports-a-thing-even-when-nothing-went-wrong).
+
+## Every item
+
+- **Shipped SHA** and the revision verified live, with **evidence from both phases**: the candidate's ALIVE verdict at 0% traffic; the re-check fence's readings taken between the authorization and the shift (verdict age vs the window, **the revision the candidate URL resolved to**, candidate at 0%, incumbent at 100% — the three the manifest's `recheckFence` records); the serving confirmation (the live service re-attesting `release.candidateIdentity`'s tuple, or the declared image-digest fallback); and health after the shift. **Each verdict says which of its evidence was observed fresh and which was carried over** ([principle 11](../SKILL.md#non-negotiable-principles)) — a verdict that cannot say is not evidence this report may quote, and an environment-sensitive observation is never carried over. On a failure, the tier instead: the **candidate-deletion record** (pre-exposure — revision deleted, the previously-serving revision still at 100%, the diagnosis handoff) or the **rollback record** (post-exposure — what was restored, the restoration evidence, the incident issue, the diagnosis handoff).
+- **Quiescence record** — where [pre-flight item 6](preflight.md#pre-flight-gate-confirm-the-authorization-envelope-mandatory) declared durable processing: the **pause order as executed**, the proof's **observed reading** (the value, never `quiesced: true`), the **resume order as executed**, the revision processing resumed against, and that resume was the exact reverse of pause. On either failure path, which unwind ran and in what order. **Where item 6 declared no durable processing, say that too.** → [why](why.md#why-the-handoff-reports-a-thing-even-when-nothing-went-wrong)
+- **Version identity** — the version, the bump **and why**, the **rc tags minted** and how many attempts they represent, the final tag, the CHANGELOG cut commit, the release-notes link, and plainly whether the version was **reused** (both tag-after-verify shapes) or **burned** (legacy final-tag trigger only), with any `Withdrawn` annotation. On a dev release: unversioned, plus the SHA.
+- **ensure-target-green** — `release.ensureGreen` when tip colour was BLOCKED (or the phase ran): outcome, finalHead, durationMs, failingClasses, repair PRs/issues (tip check-runs only; not #800 floor). Absent on a green no-op is fine; a mid-flight repair with no record is incomplete.
+- **Post-release metadata PR** — `release.metadataPr` after the final claim: the PR number/url from [`metadata-sync.mjs open`](../scripts/metadata-sync.mjs), or an explicit `n/a` with reason. A released attempt without that record is **incomplete** (`report.mjs`; identity-v0.4.1 / identity#678).
+- **Closed issues** — closed on verified-done with the version/SHA/evidence comment, or on a rollback **left open** and cross-linked to the incident issue.
+- **Promotion PR link**, its fast-forward status, and the release-readiness checklist outcome.
+- **Assembly record** — the integration/release branch, per-PR merge order, the **integration CI + combined-diff review** on the assembled tip, and anything bounced back to `resolve-issues` at intake.
+- **Authorization audit** — the confirmed envelope, which step authorized each action, and whether the promotion ran on a human confirm or under `auto-when-green` (if the latter: (a)–(d) held, no carve-out). **Name `envelope.exposureIdentity` on every release**, with any pre-flight item 3 weakening declared.
+- **Release-evidence bundle location** on **every** terminal exit — `<durable-evidence-dir>/<attempt-id>--<terminal-state>.json` (one attempt can leave more than one, e.g. a `blocked-manual` hold and its later `released` close) — and, on the verified path, the **GitHub Release** the `released` bundle was attached to.
+- **Post-mortem** — auto-saved by `report.mjs` at `done`/`discard`/`rollback`; **adjudicate each finding in a line** and file the rendered issue (`--issue`). A **stalled** release reaches no terminal step and auto-saves nothing: run `report.mjs <manifest> --postmortem` by hand. With version + `durableEvidenceDir` recorded it also saves the **version-level aggregate** (`kind: "release-version"`). → [references/postmortem.md](postmortem.md), [why](why.md#why-the-post-mortem-is-adjudicated-not-just-saved)
+- Run manifest reflecting the final state.

package/skills/engineering/resolve-release/references/postmortem.md

@@ -0,0 +1,230 @@
+# The release post-mortem (mandatory, at the terminal step)
+
+**It runs on every release and saves itself.** `report.mjs` — which you already run at every
+step transition — computes and persists it the moment the release reaches a terminal step
+(`done` · `discard` · `rollback`). The handoff: [SKILL.md](../SKILL.md#definition-of-done-handoff-report).
+
+```
+report.mjs <manifest>                 # the checkpoint — and saves the profile at a terminal step
+report.mjs <manifest> --postmortem    # print the profile now (the only way to see a STALLED release's)
+report.mjs <manifest> --issue         # {title, body} to file against resolve-release
+report.mjs <manifest> --no-save       # the opt-out, for a release you do not own
+```
+
+It shares its renderer, its persistence and its **cross-run series** with the delivery
+lane's ([resolve-issues/references/postmortem.md](../../resolve-issues/references/postmortem.md)):
+same `$RESOLVER_POSTMORTEM_DIR`, same `index.jsonl`, tagged `kind: "release"`. What differs
+is the questions.
+
+## It is not a speed pass, and that is the whole design
+
+The delivery lane's post-mortem hunts wasted wall-clock, because that is what an epic loses.
+A release does not lose time: measured across the **73 `resolve-release` manifests** on the
+author's machine (2026-06-21 → 2026-08-05), the **median release took 0.4 hours**. Releases
+are fast — the lane is mostly waiting on watchers.
+
+What a release loses is **account**: the record of what happened to production. So every
+finder asks a completeness question, and the severities are about how much of a release's
+own history is unreachable from state.
+
+**This table is the single source for these numbers.** `postmortem.mjs` deliberately does
+not restate them — not in its comments, not in the strings it renders — because a figure
+quoted in four files is a figure that goes stale in three of them. (That is not a
+hypothetical: the delivery lane's `inFlightCap` default was documented as `2` for nine days
+after it became `4`, and a run read the stale copy and lost five hours to it.) Re-measure
+against the current corpus and update here; the thresholds in the module are derived from
+this table and should be revisited with it.
+
+| Finding | Fires when | Measured in the corpus |
+|---|---|---|
+| `step-off-enum` | `step` is not one of the ten release steps | **13/73 (18%)** |
+| `stopped-mid-machine` | last step was non-terminal, no outcome recorded | **11/73** |
+| `no-verification-record` | no `verification`, on a release that reached it | **20/73** |
+| `adhoc-manifest-keys` | keys outside the release schema | **35/73 (48%)**, 125 distinct keys |
+| `long-release` | over 8h — ~20× the median | 4/73 |
+
+Sixteen of the seventy-three come back clean.
+
+**`step-off-enum` is the loudest, and its point is not the typo.** `step` is the resume key —
+the one field a dead session re-enters at — and real manifests carry `verified-done`,
+`5-verified-done`, `done (all 3 merged into dev)`, `verified-dev-alive-ruleset-held`. A
+resumed session cannot route on any of those: it cannot tell whether the release shipped, is
+mid-deploy, or needs a rollback. And `run-state.mjs validate` **already refuses every one of
+them**. So each occurrence is a release on which validate was never run, which is the
+actionable half — the gate is not missing, it is not being invoked. (Exactly the shape of
+the delivery lane's `runnable` finding: a mechanism that exists and is skipped under load.)
+
+## What is reported rather than faulted
+
+**Rollbacks (3/73) and burned versions (0/73).** A rollback that happened and was recorded is
+the machine *working* — the candidate was caught and production was restored. A finder that
+scolded for it would train the reader to ignore the pass. Both appear in the header line
+(`ROLLED BACK`, `version burned`) so they are never invisible.
+
+Likewise `discard` and `rollback` are **terminal and successful** steps, not stalls.
+
+## The step
+
+1. **Read it.** `report.mjs` already saved it at the terminal step; `--postmortem` prints it
+   again. A release that **stalled** never reaches a terminal step and so never auto-saves —
+   run `--postmortem` on it by hand, because "it stalled" is precisely one of the findings.
+2. **Adjudicate each finding in a line.** Some are legitimate: a long release that was
+   waiting on a human is fine and owes no change. An unadjudicated finding is not a result.
+3. **File the issue** (`--issue`), one per release, findings you adjudicated as legitimate
+   dropped with the reason.
+4. **Report the profile in the handoff**, above the evidence.
+
+## What it can and cannot see
+
+The run manifest only — no tree, no live service, no clock. So it can see what the release
+*recorded*, and it cannot see what production actually holds: **a candidate revision it
+reports as recorded may already be deleted, and one it cannot see may still be serving.**
+Where the two disagree, the tree is right and the manifest is the thing to fix. A finding it
+did not raise is not evidence anything was fine.
+
+## Adding a finding
+
+Same bar as the delivery lane's: **a finding ships with the measured runs it would have
+caught**, computed from fields the schema already defines. If it needs a new field, the field
+and its reader land in the same change or neither does.
+
+## The version-level pass (#961): the aggregate a single manifest cannot see
+
+The run-level pass above profiles ONE manifest's record. It cannot see the shape that made
+Forex `v0.1.12` the incident it was: **nine attempts for one version, eight non-released, and
+the release lane's own tooling — never the application — as the repeated failure owner.** The
+terminal post-mortem that release actually generated reported only `long-release`, because
+that is all one manifest can say. `version-postmortem.mjs` is the aggregate reader: it
+discovers **every durable evidence bundle a version left behind** in the durable evidence dir
+(`<version>-attempt.<n>--<state>.json`, legacy `v<version>-rc.<n>` keys included), orders the
+attempts by the immutable attempt id — **numerically**, so attempt.10 follows attempt.9 — and
+reports what only the series of attempts can say:
+
+- attempt and rc-tag counts, terminal-state counts, maximum exposure per attempt, the number
+  of traffic mutations (each recorded shift stage, plus each rollback restore — restoring the
+  incumbent is a traffic mutation too), the rollback count, and whether the version was
+  **reused** (both tag-after-verify shapes — principle 10 makes a failed attempt burn nothing)
+  or **burned** (the legacy final-tag shape, or a bundle-recorded withdrawal);
+- candidates **healthy/ready when rolled back reported separately** from the rest — a healthy
+  candidate rolled back is the lane doubting itself, an unhealthy one is the lane working, and
+  conflating them is how "the tooling cried wolf" reads as "the release failed";
+- a **`repeated-failure-owner` finding** when one failure owner accounts for two or more failed
+  attempts (high severity at three or more), with the bundle file for each attempt as evidence.
+
+It runs where the run-level pass runs: `report.mjs` computes, prints and saves it at a terminal
+step whenever the manifest names the version and `durableEvidenceDir`, and
+`version-postmortem.mjs --dir <d> --version <v>` runs it standalone. It persists into the
+**same series** (`kind: "release-version"` in the shared `index.jsonl`). It reads the durable
+bundles only — never the manifest, never a live service — and it is **tolerant of schema
+drift**: real bundles were written by different releases months apart, so every signal is read
+defensively and an absent one is reported as absent, never invented. A bundle file that cannot
+be parsed is a finding (`unreadable-version-bundle`), not a silent skip; a dir that cannot be
+read refuses, exactly as `evidence-bundle.mjs` does.
+
+### Failure ownership — the normalized classification (#962 consumes this surface)
+
+Every attempt that ended `failed-pre-promotion` or `rolled-back` is assigned exactly one owner
+from **`FAILURE_OWNERS`**: `application`, `configuration`, `platform`, `release-tooling`,
+`gate-environment`. `released` is not a failure; `revoked` and `blocked-manual` are operator
+decisions, not outcomes, and classify neither. **This enum, and the derivation order below,
+are a stable contract** — #962 builds on them; renaming a class or changing a rule's meaning
+is a breaking change, not a refactor. A bundle may **declare** its owner (`failureOwner`,
+top-level or in `disposition`); the declaration wins, because whoever records the failure
+closest to it knows more than any heuristic. Everything else is derived, first match wins:
+
+| # | Rule | Owner |
+|---|---|---|
+| 1 | `failureOwner` declared on the bundle or its disposition, naming one of the five | the declared owner |
+| 2 | `candidateVerdict.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 | `gate-environment` |
+| 3 | live or candidate evidence judged the artifact **unhealthy** (DEAD / non-healthy runtime status) — attributed by the recorded reason: secrets/env/config-shaped → `configuration`; quota/platform/deploy-infrastructure-shaped → `platform`; otherwise → `application` (the observed defect belongs to the artifact until the evidence says otherwise) | `application` / `configuration` / `platform` |
+| 4 | live evidence shows the candidate **healthy** (healthy/* runtime status, ALIVE, probe-succeeded) and the attempt failed anyway — the verifier, the normalization, an adapter, a gate's assumption about a valid platform representation | `release-tooling` |
+| 5 | `candidateVerdict.verdict` ALIVE and the attempt still ended in a failure state — the lane stopped a candidate its own gate judged alive | `release-tooling` |
+| 6 | no verdict evidence at all — the lane ended an attempt it never measured | `release-tooling` |
+
+Live evidence wins over the pre-exposure verdict (rule 3 before rule 5) because what
+production showed after the shift is the stronger observation (principle 5). Each
+classification carries its `basis` — the rule and the signals used — so a reader can
+disbelieve it against the bundle itself. **The pass does not adjudicate** (the issue's
+non-goal): the finding says where to look, and a mis-classified owner is corrected by
+adjudicating the bundle, not by editing the table mid-incident.
+
+Measured against the real Forex `0.1.12` durable bundles at introduction: 9 attempts, 8
+non-released, 6 rolled back, 7 of 8 failures owned by `release-tooling`, 2 candidates rolled
+back at 100% while healthy/ready — the dominant signal the single-manifest pass missed, now
+the headline.
+
+### Failure phase — where the lane stopped (#962)
+
+Beside the owner, every failure bundle records a normalized **phase** from
+**`FAILURE_PHASES`**: `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),
+`post-exposure` (traffic moved and was restored — a rollback, by construction). Derived from
+the bundle's own evidence; a declared `failurePhase` wins, exactly as a declared owner does.
+Same stability rule as the owner enum: the rc circuit breaker records it per qualifying
+attempt, so renaming a phase is a breaking change.
+
+**The close-time stamp (#962's half of this surface).** `evidence-bundle.mjs emit` stamps
+`failureOwner` and `failurePhase` onto a failure bundle at close time — rule 1's "declared"
+extension point, exercised by the mechanism that writes the record. An author-declared owner
+(top-level or in the disposition) always wins over the derived stamp; a non-failure terminal
+state is stamped with neither. The stamp is a pure function of the bundle, so a resumed
+re-emit recomputes the identical record and stays the resume-safe no-op immutability
+promises.
+
+## The rc circuit breaker (#962): holding the loop, not the attempt
+
+Every per-attempt gate fails closed, and that is correct — but a loop of correct per-attempt
+refusals can still be wrong: Forex `0.1.12` minted nine immutable RCs on tooling-only
+retries. `rc-circuit-breaker.mjs` is the gate over the loop. The lane runs it at step 3,
+**before `version.mjs rc` mints the next immutable RC** (including a `--retry-from` retry —
+[candidate.md](candidate.md)), and records the decision JSON at `release.circuitBreaker` on
+the manifest on every outcome, proceed included: this post-mortem reports whether the
+breaker fired and how it resolved, and an unrecorded check is one nobody can prove ran.
+
+**The count.** Prior **non-released** attempts for the same proposed version whose
+normalized failure owner is `release-tooling` or `gate-environment` — the two lane-side
+owners of the table above, read back through the same `classifyFailureOwner`. Application,
+configuration and platform failures are reported in the decision's per-owner breakdown but
+**never consume the threshold** — an artifact defect has its own route, and counting it here
+would hold healthy lanes for the wrong reason.
+
+**The threshold.** Default **2** prior qualifying failures. Configurable: `--threshold <n>`
+beats `$RC_CIRCUIT_BREAKER_THRESHOLD` beats the default, and the decision records which
+source set it — configuration is declared in the record, never silent. What no flag or env
+var can do is **skip the check**: the only way past a hold is the authorization below.
+
+**The hold.** Crossing the threshold returns fail-closed `hold-for-release-design-review`
+(CLI exit 1) with the count, the per-owner breakdown, the qualifying attempt ids, their
+phases, and the bundle files as evidence links. The check is read-only: **a hold deletes
+nothing, moves no immutable rc tag, and burns no version.** Exit 2 is a refusal — an
+unreadable durable dir or an unparseable bundle means the history cannot be established, and
+a gate that cannot read the history does not get to mint (the same reading
+`evidence-bundle.mjs`'s mint takes).
+
+**Continuing** is a human's explicit, recorded decision — not an env bypass. The
+authorization is a structured JSON record passed as `--authorization <file>`:
+
+```json
+{
+  "version": "0.1.12",
+  "againstCount": 2,
+  "authorizedBy": "<the human>",
+  "authorizedAt": "<ISO timestamp>",
+  "rationale": "why another RC is preferable to simplifying, removing, or externally repairing the gate",
+  "alternativesConsidered": { "simplify": "…", "remove": "…", "externalRepair": "…" }
+}
+```
+
+`alternativesConsidered` is optional; every other field is required. `againstCount` binds
+the record to the current qualifying count: **one authorization covers exactly one
+continuation**, and a further qualifying failure re-holds — a stale record never silently
+carries the next retry. A valid record turns the hold into `authorized-continue` (exit 0),
+echoing the record for the manifest; an invalid or stale one leaves the hold standing and
+names why (`authorizationError`).
+
+**In the post-mortem.** The run-level profile reads `release.circuitBreaker`: the summary
+line states `did not fire`, `FIRED (n qualifying) — unresolved`, or `fired —
+authorized-continue by <who>`, and `metrics.circuitBreaker` carries `{fired, resolution}`.
+The metric is absent — not null — when no decision was recorded, because an absent record
+and a breaker that did not fire are different statements.