@1aboveio/skills 0.10.0

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

@@ -0,0 +1,137 @@
+# Steps 0-2: intake, assemble, promotion PR
+
+From the `resolve-issues` handoff to an open promotion PR. Nothing is exposed in
+this phase and no candidate exists yet. Next phase:
+[candidate.md](candidate.md).
+
+## Watching PR delivery
+
+Sequential execution is not a reason to pause the release. A build, queue, deploy,
+or post-deploy gate is watched by one launch of its background watcher, not a poll
+loop that spends a turn per check. When it fires, the notification is a continuation
+trigger: read and record the result, then carry straight on in the same turn. Stop
+only for a decision: an authorization the envelope did not pre-approve, a terminal
+verdict that hands back, or an ambiguous state nobody can describe. In pi session
+`019faea6`, three of five human interventions were needless pauses after a watcher
+had already reported success.
+
+For a promotion PR or the metadata-sync PR opened by the verified-SHA flow, launch
+[`watch-pr-delivery.mjs`](../../../cicd-pipeline/mergify/scripts/watch-pr-delivery.mjs)
+from `<skillsRoot>/mergify/scripts/watch-pr-delivery.mjs`. It emits one terminal JSON
+verdict on stdout, heartbeats on stderr, and bounds stalls rather than elapsed time.
+It observes only: it never enqueues, merges, or takes merge authorization. Its
+contract is [`watch-contract.md`](../../../cicd-pipeline/mergify/references/watch-contract.md).
+Do not use the resolve-issues manifest-writing wrapper. Upstream PR delivery is a
+finished input re-verified below, not re-watched; builds, deploys, and post-deploy
+gates use their own watchers under the same one-launch rule.
+
+### 0 — Intake: verify merge-readiness (principle 2)
+Collect the PR set (from the resolve-issues handoff or as named) — for an **epic, that is one combined PR per component** (some may already be on `dev` if the upstream run merged them under `mergeShippable` — those need no re-collection, only re-verification that `dev`'s tip carries them); for a batch of independent issues, the N PRs. For each: fresh APPROVE on current HEAD, CI green on current HEAD, Review Contract present, no unresolved blocking findings, branch up to date with its base. For an epic's combined PR, also confirm its `integration-verdict.json` is `ALIVE` and its CI is green on the *current* HEAD (the combination was verified upstream — re-check it, don't inherit it). Anything failing re-check goes **back to `resolve-issues`** — this skill releases finished work; it does not finish it.
+
+### 1 — Assemble the release (integration / release branch)
+**N independently-implemented PRs become one combined, atomically-promotable release here** — the single combining point (principle 8). Five cases, and the last one is *not to run this step at all*:
+
+- **Already combined** (a `resolve-issues` **epic** handoff): each component is one integration-verified PR whose branch *is* an assembled release slice. **Do not re-assemble** a component — re-verify its tip (principle 2). A single-component epic goes straight to step 2 with that branch; a multi-component epic assembles the components in dependency order (step 1), each already internally verified. (Where the integration branch auto-deploys, or a component was merged under `mergeShippable`, it lands on `dev` like any other and the next case applies.)
+- **An integration branch exists** (the GitFlow `dev` the features targeted): merge any not-yet-integrated PRs into it in dependency order, then **pin the candidate** (principle 11) — a specific SHA, normally the post-merge tip once the integration environment's post-deploy smoke recorded **ALIVE for that exact SHA**, that **descends from the last release's back-merge commit**. Cut `release/<version>` at it and **record `release.candidateSha`** in the manifest; step 2 promotes that branch, not `dev`. A wanted SHA with no recorded verdict gets one deliberately (wait for the recorder, or deploy it to a no-traffic revision and smoke it) — never promote on "dev looked fine."
+- **One branch does both jobs** (**GitHub Flow**: `main` is the integration branch *and* the production source): the PRs already merged to `main`, so cut `release/<version>` at a validated SHA on `main` and cut the version there (step 1b) — but understand what changes about the guarantee. The release branch **merges back into `main`**, and if `main` moved while you were releasing, principle 3 still applies — **rebase the release branch onto `main`'s tip and re-run step 2** rather than merge-resolving. The branch is one cut commit, so this is cheap. But rebasing means the **shipped SHA now carries commits that never earned a staging verdict**, so here the SHA-keyed verdict is a **pre-filter, not the release gate** — the gate is the step-4a candidate validation, which exercises the *exact shipped SHA* at 0% traffic before any user reaches it. Two more mechanical consequences: **merge before you tag** (`version.mjs` refuses a SHA that is not an ancestor of the production branch, so the rc cannot be minted on an unmerged release branch), and **there is no back-merge in step 5** — the cut commit reached `main` by being merged there. Trigger set: `cloud-build` → GitHub Flow variant. **This is the generic GitHub Flow path.** When pre-flight selected [`verified-sha-github-flow`](verified-sha-github-flow.md#candidate-selection-and-the-production-floor), that mode is authoritative: pin the eligible `main` SHA directly, never rebase it onto a moving tip, and follow its attempt and finalization order.
+- **No integration branch at all** (PRs target prod directly, or are independent feature branches): **assemble `release/<slug>`** off the production base and merge the PRs into *it* in dependency order.
+- **A merge queue already did it** (`deliveryMode: "queue"`, read from the handoff at [pre-flight item 2](preflight.md#pre-flight-gate-confirm-the-authorization-envelope-mandatory)): **do not assemble — there is nothing here to combine.** Every unit reached trunk through the queue with a `mergedSha` proved contained in the freshly-fetched `origin/<targetBranch>`, so the combining this step exists to perform already happened, upstream, one batch at a time. **Queue mechanics are `resolve-issues`' contract, not this skill's** — enqueue eligibility, the stall-bounded watch, the dequeue routing table and the rule that *a merge tool's return code, a queue acknowledgement and an auto-merge flag are all requests; only ancestry is a result* live in [references/delivery.md](../../resolve-issues/references/delivery.md) (`<skillsRoot>/resolve-issues/references/delivery.md`). Do not restate them here, and do not run them: by the time this lane starts, delivery is a finished fact and the only queue artifact it consumes is the merged SHA. What this step does instead is **select**, and the selection rule is the [eligible trunk SHA](verified-sha-github-flow.md#terms) — a commit that is on trunk *and* carries a green **Trunk Integration Verdict for that exact SHA**. Branch greenness is not eligibility, a verdict for a neighbouring SHA is not eligibility, and the current tip is not eligibility just for being the tip. **Record the selection as `release.candidateSha`** exactly as the integration-branch case does — it is the same field and the same job, and it is the only thing that tells a resumed session which of trunk's commits this release is about.
+
+    **The SHA the queue tested is, by construction, never the SHA that landed.** A queue validates a temporary **batch candidate** — this PR merged with the base, and usually with the batch's other PRs — and then the merge method writes a *different* commit onto trunk. The batch's green therefore describes a tree that exists at no ref you can release. **That costs this lane nothing, because it never inherits it**: eligibility is a verdict observed *after* the merge, on the commit that actually shipped, so the question "does the tested SHA's evidence transfer to the landed SHA?" is never asked. Naming the trade rather than assuming it away: preserving the tested SHA instead — fast-forward batching — buys evidence portability at the price of a repository-ruleset bypass, and the banked contract this rule comes from rejected that boundary deliberately. Fresh validation of what shipped is cheaper than a bypass, and it is the only reading under which a green batch is *not* a release-grade artifact. **A trunk commit with no post-merge verdict is ineligible however green its batch was** — get it one (wait for the recorder, or deploy it to a no-traffic revision and smoke it) exactly as the integration-branch case does; never promote on "the batch was green."
+
+    **Three principles change shape here, and none of them relaxes:**
+    - **[Principle 3](../SKILL.md#non-negotiable-principles) (promotions fast-forward)** — there is no promotion PR to fast-forward, because there is nothing to promote *from*. A promotion PR would itself be enqueued, and the queue would produce a *third* trunk commit — the pin destroyed by the act of promoting it. The rule's failure mode (a merge resolution into prod silently reverting hotfixes) cannot occur when this lane merges nothing; what survives is the ancestry the eligible-SHA selection already establishes.
+    - **[Principle 8](../SKILL.md#non-negotiable-principles) (combine into one promotion)** — one combined promotion becomes **one selected trunk SHA**. The guarantee is untouched, and this is exactly where it bites: a queue that landed six units is still released as *one* commit, one candidate, one rc. Releasing each merged unit separately would be the N-promotions failure with the assembly step removed.
+    - **[Principle 11](../SKILL.md#non-negotiable-principles) (a promotion promotes a pinned candidate SHA)** — the pin becomes a **trunk-integration verdict on an exact trunk SHA** rather than a release branch cut at a verdict-carrying integration tip. It does **not** demote to a pre-filter the way generic GitHub Flow's does: nothing is rebased, so the SHA that earned the verdict is the SHA that ships, and step 4a's candidate validation gates a commit the pin already covers. The GitFlow consequences are simply absent — no `dev`, so no step-5 back-merge and no descent constraint.
+
+    **And the version cut cannot follow the pin.** Step 1b commits the version identity onto an assembled branch *before* the promotion; with no branch and no promotion, a cut is a change to trunk, which is a queued PR, which is a new trunk SHA that is not the one selected. That is the ordering [`verified-sha-github-flow`](verified-sha-github-flow.md#final-claim-and-metadata-ordering) exists to solve, and this topology does **not** select it implicitly — pre-flight item 2 records whether the human did. Absent that selection, where the version identity lands is settled **before** the SHA is pinned, not discovered at step 1b.
+
+Either way — except the merge-queue case, where this lane merges nothing and both bullets are answered upstream (see [row 2a](regression-checklist.md)):
+- **Merge in dependency order, watching CI between merges** — incremental so a break is *attributed* to its merge. A textual conflict is resolved here; one needing a real code decision **bounces back to `resolve-issues`**.
+- **The combined tree is a new artifact — verify it, don't inherit it (principle 2).** Each PR was reviewed individually; their union was not. Run **integration CI on the tip** *and* a **`review-pr` pass on the net combined diff vs the production base**, hunting cross-PR interactions no single review saw: a module two PRs both edited, conflicting symbols, migration ordering across PRs, a contract one PR changed and another consumed. A red build or blocking finding **stops the queue**.
+
+**Bound the combined-review input, never the review.** Before the step-1 `review-pr` pass on a
+large combined diff, fetch the named target branch and pin both sides of the range, then run
+[`scripts/review-packet.mjs`](../scripts/review-packet.mjs):
+
+```bash
+git fetch --no-tags origin <target-branch>
+target_ref=refs/remotes/origin/<target-branch>
+target_head=$(git rev-parse --verify "$target_ref^{commit}")
+head=$(git rev-parse --verify '<pinned-tip>^{commit}')
+base=$(git merge-base "$target_head" "$head")
+node <resolve-release>/scripts/review-packet.mjs collect \
+  --base "$base" --head "$head" --head-ref <release-ref> \
+  --target-ref "$target_ref" --target-head "$target_head" \
+  --target-repository github.com/<owner>/<repo> \
+  --evidence <per-pr-evidence.json> --ci <exact-head-ci.json>
+```
+
+The explicit target is part of the packet's authority, not a convenience flag. The command
+requires a fully-qualified remote-tracking branch, binds it to the expected normalized repository
+identity, rechecks target/head drift before output, computes the authoritative merge-base from the
+pinned target head and exact review head, and requires `--base` to equal it. An older ancestor,
+implicit `main`, symbolic remote `HEAD`, unavailable or stale target ref, or unrelated repository
+fails closed before any stat, name-status, high-risk, per-PR or hunk evidence can be accepted.
+
+The public CLI grammar is schema-defined. Every option accepts either `--key <value>` or
+`--key=<value>`, but a separate token beginning with ASCII `-` is ambiguous and is never
+consumed as data. Repository-relative evidence and CI filenames that legitimately begin with
+`-` therefore use the equals form, for example `--evidence=-evidence.json` and
+`--ci=-ci.json`. Those file operands may otherwise contain spaces or Unicode. Absolute paths,
+Windows drive-absolute paths, traversal (`..`), dot or empty segments, and control characters
+fail during argument validation, before either file is read or any Git command runs.
+
+`--base`, `--head`, and `--target-head` are full 40-character lowercase commit SHAs.
+`--target-ref` is a fully-qualified, explicit, non-symbolic `refs/remotes/<remote>/<branch>`;
+`--target-repository` is normalized `host/owner/repository` identity. Optional `--head-ref` is
+either a full lowercase SHA or an exact fully-qualified `refs/heads/...`, `refs/tags/...`, or
+non-symbolic `refs/remotes/...` revision. Omitting it disables only named-head movement
+detection; exact head, target repository/ref/SHA, merge-base, and exact-head CI checks remain.
+`--max-bytes` is a decimal integer from 1 through 16,777,216. Unknown, duplicate, malformed,
+or empty options, Unicode/single-dash option spellings, extra positionals, and unsupported
+commands fail before I/O or Git; diagnostics identify the schema field without echoing supplied
+command, option-name, positional, or value payloads. `--help` is generated from the same schema.
+
+The JSON carries the exact range and target identity, short diff stat, name-status entries, every
+high-risk path group (including rename/copy preimages), relevant constituent-PR evidence, and CI at
+the exact head. It emits hunk coordinates rather than patch lines and records every omitted
+ordinary name-status row under `truncation`; it fails if required metadata or any high-risk path
+cannot fit the declared byte bound. Give that packet to the independent reviewer, who must inspect
+the targeted hunks in the actual tree, check cross-PR interactions, and return one bounded complete
+verdict. A packet is navigation evidence, not a replacement for source inspection and never
+authorization to accept target or head drift.
+
+The release branch's tip is the **single source** for the promotion in step 2. Two explicit exceptions, for the same reason: the opt-in `verified-sha-github-flow` mode, whose selected SHA is already on `main`, so [the pinned SHA itself is the source](verified-sha-github-flow.md#version-confirmation-and-the-immutable-pin), with no release branch or promotion merge — and the **merge-queue topology**, where the selected eligible trunk SHA is the source on the same terms.
+
+### 1b — Cut the version and CHANGELOG (production promotions only)
+**Skip this step for a `dev`/staging release** — it is unversioned, identified by its SHA (principle 10). Also skip it when [`verified-sha-github-flow`](verified-sha-github-flow.md#final-claim-and-metadata-ordering) is selected: changing CHANGELOG or package metadata before deployment would change the verified SHA, so that mode synchronizes metadata after the final release claim. `version.mjs` enforces the dev/staging case itself: `plan`, `changelog` and `tag` exit **3** ("not a production promotion"), a normal outcome to branch on rather than an error to work around. Exit 3 has that one meaning only ([exit codes](versioning.md#exit-codes)).
+
+Commit the version identity **onto the assembled release branch, before opening the promotion PR** — never onto the production branch afterward ([principle 3](../SKILL.md#non-negotiable-principles): a post-merge commit on `main` leaves the base ahead of the head, breaking the *next* promotion's fast-forward). Cutting here also makes the shipped SHA the exact SHA whose CHANGELOG says it shipped.
+
+Inspect a machine-readable plan before writing it; use `--format markdown` instead when the review artifact should be the complete planned file:
+
+```bash
+node <resolve-release>/scripts/version.mjs changelog \
+  --version <confirmed> --date <YYYY-MM-DD> --changes <prs.json> \
+  --repo <owner/name> --target-branch <target> --production-branch <prod> \
+  --dry-run --format json > changelog-plan.json
+node -e 'const p=require("./changelog-plan.json"); if (p.noop) console.error("CHANGELOG already cut")'
+
+node <resolve-release>/scripts/version.mjs changelog \
+  --version <confirmed> --date <YYYY-MM-DD> --changes <prs.json> \
+  --repo <owner/name> --target-branch <target> --production-branch <prod>
+```
+
+The cut **carries the `## [Unreleased]` body into the new version heading**, merged with entries derived from the PRs' titles, leaving `Unreleased` empty for the next cycle — so hand-written notes no PR title captured survive. In the *same commit*, bump any file carrying a version (`package.json`, `pyproject.toml`, `VERSION`, chart/image tags). Do not tag here; that is step 3 or step 5, per the confirmed mode.
+
+**Record the cut commit** in the run manifest (`release.cutCommit`) as soon as it lands — the `step` enum has no value between `merge` and `promote`, so `cutCommit` is what tells a resumed session that 1b is done, and a non-null `cutCommit` means **skip this step**. It must be recorded, not re-derived: re-running `changelog` is a harmless no-op (exit 0), but the hand-applied version-file bumps beside it have no such guard — a resume that repeats them double-bumps.
+
+### 2 — Promotion PR (skill: review-pr, promotion mode)
+Open (or update) the promotion PR from the assembled release branch into the production branch. **Skip this generic promotion-PR step in [`verified-sha-github-flow`](verified-sha-github-flow.md#candidate-selection-and-the-production-floor): the selected SHA is already an eligible commit on `main`, and its ancestry, version confirmation, and single-flight gates authorize the attempt tag.** **Skip it under the merge-queue topology too, for the reason step 1 gives — a promotion PR would be enqueued and would land a different SHA.** What is *not* skipped there is the release-readiness checklist: run it against the selected trunk SHA, with the fast-forward row recorded as `n/a — no promotion merge under a merge queue` rather than left blank. A blank row is not a cheaper `n/a`; it withholds the green the `auto-when-green` gate reads. Otherwise, this is the highest-stakes review in the pipeline — it gates production — so run the real skill, not a remembered checklist: read `<skillsRoot>/review-pr/SKILL.md` (the **absolute** skills directory this skill was loaded from — `<repo>/skills/engineering` in the skills repo, the resolved `~/.claude/skills` when globally installed; a relative `skills/engineering/...` path silently fails in a consumer repo) and apply its [Promotion PRs](../../review-pr/SKILL.md#promotion-prs-eg-dev--main) mode. A from-memory "fast-forward plus some release checks" silently drops items that mode enforces.
+
+Concretely: **`fastForwardable` must be true** (else back-merge first, principle 3), then the **release-readiness checklist** — migrations/backfills ordered and reversible, secrets/config present in prod, flag defaults sane, version/changelog (the step-1b cut commit is that row's evidence; on a dev release the row is `n/a — unversioned`), rollback plan, and **candidate validation** — green CI **and** the recorded ALIVE smoke verdict on the exact promoted SHA (principle 11; SHA-keyed — a verdict from any other SHA is not evidence). This is release-readiness, **not** a re-review of the code: each PR was reviewed individually and the integration in step 1.
+
+**Proof-of-execution:** record the `fastForwardable` boolean and the completed checklist — every row decided, none blank — as the promotion PR's verdict artifact. A prose "looks good to promote" is not it. These are exactly the inputs the `auto-when-green` gate ([principle 9](../SKILL.md#non-negotiable-principles)) reads, so a blank row doesn't merely leave the checklist incomplete: it withholds the green that would let the promotion run unattended.
+
+**A row nobody could decide is not a decided row** ([principle 13](../SKILL.md#non-negotiable-principles)). The check whose secret was missing, whose staging service was down, whose migration dry-run would not start — that row reads exactly like a blank one here, and for the same reason: no result was produced, so no green was earned. It is emphatically **not** the `n/a` shape, which says *this row does not apply under this topology* and carries a checkable reason; a row that applies and could not be decided says *the release is not ready to be judged*. Do not resolve it by widening the `n/a`. Restore the check's ability to produce a result and re-run it, or the promotion stops here — while the merge lane that carries the repair keeps running.

package/skills/engineering/resolve-release/references/auto-when-green.md

@@ -0,0 +1,56 @@
+# `auto-when-green` — the conditional promotion envelope
+
+The `auto-when-green` mode (selected by the human at the [pre-flight gate](preflight.md#pre-flight-gate-confirm-the-authorization-envelope-mandatory), item 3) lets the promotion run **unattended** — but only behind a real gate, never on CI color alone. It shifts the human's authorization from *per-promotion* to *the policy confirmed at pre-flight*; it makes the gate **mechanical**, it never removes it. "CI was green, ship it" without the conditions below is the exact failure this mode exists to forbid.
+
+**The gate is a script, not a reading.** Each condition below is decidable from an artifact the release lane already records, and an agent evaluating them from prose — at an unattended production traffic shift with no human present — is the worst possible place for a judgment call. Run [`scripts/green-gate.mjs`](../scripts/green-gate.mjs); it compares each condition against its artifact, **fails closed** on any missing or malformed input, and names the specific failing condition. `green-gate.mjs --help` is the authoritative synopsis. This doc is the **doctrine behind each condition** — the judgment `--help` does not encode — not a second copy of the checks.
+
+## Two authorization points, two subcommands
+
+Under [principle 12](../SKILL.md#non-negotiable-principles) the release crosses two outward-facing gates, and `auto-when-green` gates both — so the script has two subcommands, run at the two points:
+
+```
+green-gate.mjs promote --manifest <run-manifest.json>
+green-gate.mjs shift   --manifest <run-manifest.json> --verdict <smoke-verdict.json>
+```
+
+Each exits **0 = fire** (proceed unattended), **1 = hold** (fall back to a per-step human confirm, with the failing condition named), **2 = usage / unreadable-input error**. On any `hold`, **fall back to the human** — that is the whole safety property; do not route around it.
+
+Selecting `auto-when-green` covers both points. Choosing it for the promotion but wanting a human on the shift is a legitimate configuration — say so explicitly at pre-flight item 3, because the default reading is that it covers both, and run only `promote` unattended.
+
+## The promotion gate (`green-gate.mjs promote`) — all of (a)–(d) must hold
+
+The promotion + rc mint (step 3) fires automatically **only while every one** of these holds. `green-gate.mjs --help` names the manifest field for (a) and describes (b)–(d) in prose (it names a field again only for the carve-out major bump); the fields those prose conditions read live in the bullets below, alongside the doctrine `--help` doesn't carry — why each condition is what it is:
+
+- **(a)/(b) — liveness on the *exact* promoted SHA, not CI color.** Fast-forwardability (`release.fastForwardable === true`, else back-merge first, principle 3), and green gates — PR-lane, integration CI, and (where the integration environment records one, principle 11) the SHA-keyed smoke verdict (`release.integrationSmoke`, keyed to `release.candidateSha`) — all keyed to the promoted SHA. A verdict from any other SHA, or a missing one, is **not** green: "CI passed" on a different tree is precisely the trap unattended promotion must reject. An environment with **no** such recorder declares that explicitly — `release.integrationSmoke: "not-recorded"` — rather than leaving it inferable from a blank field.
+- **(c) — a collision is a human's call, never an auto-bump.** Release-readiness fully decided — every row PASS with a locator, **no blank/TODO row**, `coverage-checklist.mjs validate`'s bar (a row that needs human judgment is, by definition, not green) — including the [step-1b version/changelog cut](assembly.md#1b--cut-the-version-and-changelog-production-promotions-only) committed (`release.cutCommit`) with **no collision on the final tag** (`release.versionPlan.collision === false`; an existing `-rc.*` tag is not a collision). An unresolved collision is a human decision, never an automatic bump past it.
+  On HOLD, `green-gate.mjs promote` reports **every** failing readiness row in one
+  `diagnostics.readiness` array with row/index, evidence value (secret-shaped values redacted),
+- **(d) — artifact-checked, not re-asserted.** The integration-review's blocking-finding count is read from the manifest (`release.blockingFindings === 0`), so the gate never re-litigates the review's verdict at fire time.
+
+A blank checklist row is not merely incomplete: it withholds the green that would let the promotion proceed unattended. **So does a row that could not be decided** — the check whose credential was missing, whose service was unavailable, whose fixture had drifted ([principle 13](../SKILL.md#non-negotiable-principles): an applicable gate that cannot run is a failure, not an absence). It reaches the gate as the same withheld green a blank row does, and it must: the gate has no way to tell "nobody filled this in" from "nobody could", and neither one is a result. The condition is over **decided** rows — PASS with a checkable locator, or the `n/a` shape a topology's inapplicability earns — and an undecidable row is neither, however good the locator it cites for the attempt.
+
+### Carve-outs that force the human even when (a)–(d) hold
+
+`promote` also refuses to auto-fire — even on a full green — when any of these mechanically-checkable overrides trips:
+
+- **Major version bump** — a major bump is a breaking change reaching consumers who already pinned the version, irreversible for them whatever the rollback does. `version.mjs plan` names the bump (`release.versionPlan.bump === "major"`), so this is checkable, not a judgment call.
+- **Rollback not armed** — the policy must be **auto-rollback, not page-first** (`envelope.rollbackPolicy`), and the candidate revision must be deletable without confirmation (`envelope.candidateDeletableWithoutConfirm`). The validate→expose→verify→rollback loop (steps 4–5) is the only thing that makes an unattended promotion safe, so without it `auto-when-green` is **not available**.
+- **Irreversible content** — a destructive or non-reversible migration/backfill, a secret/config change that cannot be verified before deploy, or a service's first-ever deploy each override the automatic path. The gate requires a positive `envelope.reversibilityConfirmed` to clear this carve-out and holds on its absence (the safe default: force the human), rather than silently passing an unverifiable claim.
+
+## The traffic-shift gate (`green-gate.mjs shift`) — condition (e)
+
+The traffic shift (step 4b) is the moment users are exposed. It is separately authorized (principle 1), and under this mode it fires automatically on one further condition:
+
+- **(e) the candidate's step-4a verdict is ALIVE on that exact candidate** — produced by a smoke run under the read-only `prod-preview` profile against the candidate URL (the verdict's `noMutations` flag is derived from that read-only profile), **and still fresh**.
+
+**(e) must be checked against the artifact, not asserted** — this is the crux the whole gate exists for. `smoke-verdict.json` records the `target` it ran against and whether `noMutations` was set, so the gate is: `verdict === "ALIVE"` **and** `target === candidateUrl` **and** `noMutations === true`. Without comparing the recorded target against `release.candidateUrl`, "on that exact candidate" is a claim the agent makes about its own prior work — an unfalsifiable input gating the one production traffic shift that happens with no human present, which is the worst possible place for one. A **DEAD**, **missing**, or wrong-`target` verdict is not green, and an **EMPTY** verdict is specifically not green: it means the run selected zero paths and proved nothing, which is the failure mode most likely to look like success. A **CANNOT-RUN** or **BLOCKED** verdict is also not green: it means the gate itself could not run (e.g. a secret env var held the secret *name* string instead of the secret *value*, so every request got 401/403) — the gate, not the candidate, is the defect. [Step 4a](exposure.md#4--validate-the-candidate-then-expose-it-skill-smoke) routes that case as its own state (the **gate** is the defect there, not the candidate, so nothing about it licenses deleting a revision); what this gate contributes is only that it never reads a missing answer as a satisfied one.
+
+**Evidence expires — the target comparison bounds *which*, not *when*.** A verdict names the candidate it validated; it says nothing about how long ago. That gap matters because step 4b's shape is validate-at-0% → **wait for an authorization** → shift, and nothing bounds the wait: a human confirm can arrive hours later, and an unattended gate fires whenever it is evaluated. Meanwhile the coordinates drift — a newer build takes the `candidate` tag, the incumbent stops holding all the traffic, a second release starts — and an old ALIVE describes a world that no longer exists while looking exactly like a current one. So the envelope declares a **freshness window** (`envelope.verdictFreshnessMinutes`, pre-flight item 3; conservative default in `green-gate.mjs --help`) and the gate compares the verdict's recorded generation time against it.
+
+Two properties are deliberate. First, **absence is not freshness**: a verdict carrying no timestamp cannot be aged, so it can never be shown to be current, and the gate holds rather than assuming the best — the same fail-closed reading every other condition takes on a missing input. Second, **expiry routes backward, not forward**: a stale verdict is not a failing candidate and must not be read as one. The candidate is usually fine; what aged out is the *evidence*. The response is to re-run step 4a and mint a current verdict — one smoke run — never to shift on the old one and never to delete the candidate. The whole point of the window is that re-validating is cheap and exposure on unre-checked coordinates is not.
+
+The gate is only half of it: freshness is one of three assertions in step 4b's **post-authorization re-check fence**, alongside candidate identity and the live traffic split, which the gate cannot see from artifacts. See [SKILL.md step 4b](exposure.md#4--validate-the-candidate-then-expose-it-skill-smoke).
+
+## Where each condition reads from
+
+The script's inputs are exactly the artifacts the release lane already records — the run manifest (`envelope` + `release`, via `resolve-issues`'s [`run-state.mjs`](../../resolve-issues/references/run-state.md)), the recorded `version.mjs plan` output, and `smoke-verdict.json` from the `smoke` skill. Run `green-gate.mjs --help` for (a)'s field, the carve-out bump, and the full exit-code contract — the per-condition fields for (b)–(d) are named in the bullets above; the script is the source of truth, this doc is the why.

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

@@ -0,0 +1,167 @@
+# Step 3: promote, then build the candidate (no exposure yet)
+
+The promotion lands and the pipeline builds a candidate revision at **0% traffic**.
+Still nothing exposed. Previous: [assembly.md](assembly.md) · next:
+[exposure.md](exposure.md).
+
+### 3 — Promote, then build the candidate (no exposure yet)
+In [`verified-sha-github-flow`](verified-sha-github-flow.md#version-confirmation-and-the-immutable-pin), skip the generic merge below: create the next immutable rc tag directly on the selected eligible `main` SHA only after its human-confirmed SemVer and single-flight proof. **Under the merge-queue topology, skip it too and for the same reason** — the units are already on trunk, so `SHIPPED` is the eligible trunk SHA step 1 selected, not a post-merge tip, and the rc tag is minted directly on it. The authorization is unchanged: no merge to confirm does not mean no promotion to authorize, since minting the rc is what fires the production build. Otherwise, on the promotion authorization — the human's per-step confirm, or, under `auto-when-green`, automatically once the [principle 9](../SKILL.md#non-negotiable-principles) gate holds against step 2's artifacts (any miss or irreversible-content carve-out falls back to a confirm) — **take the lease first, then merge the promotion as a fast-forward, mechanically.**
+
+**Open the Release Attempt Lease on that authorization — before anything else in this step** ([principle 7](../SKILL.md#non-negotiable-principles)). The authorization is the moment a release becomes in-flight, and it is the one moment **every trigger shape** shares, so the lease opens here on all four rather than at an rc mint three of them never perform:
+
+```bash
+node <resolve-issues>/scripts/run-state.mjs check-release-lease <run-slug>   # 0 free · 1 held · 2 ambiguous · 3 no-manifest
+# on free — mint the attempt id, then open the attempt under it. No rc tag exists yet on ANY
+# shape; the mint records one later.
+ATTEMPT_ID=$(node <resolve-release>/scripts/evidence-bundle.mjs next-attempt-id \
+  --version <version> --dir <durable-evidence-dir>)          # -> v0.5.0-attempt.1
+node <resolve-issues>/scripts/run-state.mjs merge <run-slug> \
+  "{\"step\":\"promote\",\"release\":{\"attempt\":{\"id\":\"$ATTEMPT_ID\",\"state\":\"open\"}}}"
+```
+
+Only **exit 0 (free)** authorizes the promotion. **Held, ambiguous, and no-manifest all refuse and fail closed** — never wait, never supersede, never delete or move another attempt's tag. A held lease means a prior attempt is `open` or `blocked-manual`: resolve it (verify, roll back, revoke, or clear the block) before starting another release. Ambiguous or absent means the state cannot be read (a candidate on record with no attempt, a `step` past the mint with no attempt, a reaped manifest): **re-establish the real state from artifacts** — the rc tags on the remote, the live traffic split — before proceeding, rather than reading absence as freedom.
+
+The **attempt id** is *this attempt's* identity, not the release's — **`<version>-attempt.<n>`**, on all four trigger shapes. It keys the durable evidence bundle at step 5, so it is chosen once, here, and never rewritten; a generic writer that tries to re-key, erase, or **reopen a spent id** is refused.
+
+**Why the ordinal, and why it is minted rather than typed.** The version alone is *not* unique per attempt: a retry deliberately re-cuts the same version, and both failure tiers reuse the same terminal state — so attempt 1 and its retry would key the same bundle, and immutability (working exactly as designed) would refuse the second, **losing that failure's durable record**. `next-attempt-id` reads the ordinal off the bundles already written, and the id it returns is legal by construction rather than by your remembering the rules. Composing one by hand still works, and `run-state.mjs` refuses it if it cannot key a file (`v2.0.0#2` cannot) or if it reuses a closed attempt's id — but the mint is the path this step points at.
+
+**What the mint guarantees, and what guards the rest.** A bundle exists only after a *terminal exit*, so reading the durable dir makes the minted id free of collision with every attempt that has **closed** — and only that. Two routes are outside it, and both are covered above rather than by the mint: an attempt still **in flight** has emitted no bundle and would not shift the ordinal, which is exactly why the lease check comes **first** and why only `free` authorizes the mint (in-flight reads `held`, a reaped manifest reads `unknown`); and two sessions minting **concurrently** before either emits is the advisory-not-atomic gap tracked in **#509**. The order in the block above is therefore load-bearing, not stylistic — minting before the lease answers `free` reintroduces the collision the ordinal exists to prevent. The mint also **fails closed on a directory it cannot read** (exit 2, nothing on stdout): only a dir that does not exist yet means "no attempt has emitted", because the first emit creates it. An unreadable one — a permissions change, a `--dir` typo landing on a file — is *reading absence as freedom*, the same error this step refuses two paragraphs down, and it would hand back an ordinal that is already spent.
+
+**Not the rc tag, on any shape** — including the rc shape, which is what pre-#599 releases used. The lease now opens at the authorization, *before* the mint, so there is no rc tag in existence at the moment this id is written. Bundles written under the old convention are untouched: they key off their `rcTag` and keep their exact filenames.
+
+**The accepted cost of opening here, stated so it is not later discovered as a bug:** a session that **crashes between the authorization and the mint** now leaves the lease reading **held**, not free. That is the correct reading — an authorized-but-unfinished promotion *is* in flight — and it is what a resumed session should see. Resolve it the way any held lease is resolved.
+
+**This check is advisory, not atomic** — it is a check-then-act read, and making the take safe under two truly concurrent releases is tracked in **#509**; here single-flight rests on this precondition plus principle 8's one-combined-promotion rule.
+
+```bash
+git checkout <prod> && git merge --ff-only <release-branch> && git push origin <prod>
+SHIPPED=$(git rev-parse <prod>)   # the post-merge tip — this is <shipped> everywhere below
+```
+
+`--ff-only` is the point, not a preference. `gh pr merge --merge` and the green button both create a **merge commit**, and every downstream guarantee is written assuming they do not: the shipped SHA would stop being `release.candidateSha`, the image would build from a commit that never carried a verdict, and step 2's recorded `fastForwardable: true` would describe a merge that was not performed as one. All three fail silently. **Assert `SHIPPED == release.candidateSha`** wherever the promotion was expected to fast-forward (both GitFlow and, after the rebase, GitHub Flow) — if they differ, a merge commit was created and the release must stop here.
+
+Merging is not deploying: under [principle 12](../SKILL.md#non-negotiable-principles) the production pipeline fires on an rc tag, not on the push to `<prod>`.
+
+**Prove trigger-owned topology before the RC circuit breaker and mint.** The production build may be a Cloud Build `TAG_NAME` trigger, while a controller-submitted `gcloud builds submit` is only an alternate path. Run the preflight probe's repository-specific, read-only topology command and persist its complete JSON output:
+
+```bash
+node <resolve-release>/scripts/preflight-probes.mjs check \
+  --repo <owner/name> --target-branch <prod-branch> \
+  --exposure-gate-probe '<repo exposure capability check>' \
+  --topology-probe '<read trigger config and emit the representative RC substitution record>' \
+  --json > preflight-probes.json
+```
+
+The `rc-tag-topology` result must be ready and record `prodBuildTrigger: "tag-trigger"`, `versionSource: "TAG_NAME"`, and `candidateTagSource: "TAG_NAME"`; its representative substitution record proves `TAG_NAME -> _DEPLOYED_VERSION` (final SemVer) and `TAG_NAME -> _CANDIDATE_TAG` (the RC candidate tag). `version.mjs rc --topology-probe preflight-probes.json` rechecks this artifact at the mutation boundary and refuses before creating or pushing any RC otherwise. Do not substitute a controller-provided `_DEPLOYED_VERSION`: it proves only the controller path, not the production trigger. A dev-published source-SHA image is informational, **not** RC candidate evidence; candidate evidence requires the immutable RC tag, the build it triggered, and the candidate revision/tag binding for that RC.
+
+**Run the rc circuit breaker before the mint — before EVERY immutable rc, including a `--retry-from` retry** ([principle 15](../SKILL.md#non-negotiable-principles); #962). The mint fires a production build, and a version whose prior attempts kept failing under the lane's own tooling is the loop that minted Forex v0.1.12 nine RCs: each attempt's fail-closed behavior was correct, and nothing stopped the loop. The breaker reads the durable evidence bundles for the proposed version, counts prior **non-released** attempts whose normalized failure owner is `release-tooling` or `gate-environment` (#961's taxonomy, reused — never re-derive it by hand), and holds when the count reaches the threshold:
+
+```bash
+node <resolve-release>/scripts/rc-circuit-breaker.mjs check \
+  --dir <durable-evidence-dir> --version <v> > rc-breaker.json
+# exit 0 proceed / authorized-continue · 1 hold-for-release-design-review · 2 cannot evaluate
+node <resolve-issues>/scripts/run-state.mjs merge <run-slug> \
+  "{\"release\":{\"circuitBreaker\":<the decision JSON from rc-breaker.json>}}"
+```
+
+The decision JSON is recorded at `release.circuitBreaker` on EVERY outcome — proceed included — because the post-mortem reports whether the breaker fired and how it was resolved, and an unrecorded check is a check nobody can prove ran. The threshold defaults to **2** and is configurable (`--threshold`, or `$RC_CIRCUIT_BREAKER_THRESHOLD`; flag beats env beats default, and the decision records the source). Application, configuration and platform failures are counted and reported but never consume this threshold — the breaker exists for the lane's own machinery, and an artifact defect already has its own route. The check is **read-only**: a hold deletes nothing, moves no immutable rc tag, and burns no version. **Exit 2 is a refusal, not a proceed** — 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.
+
+**On `hold-for-release-design-review`, stop for a human.** Continuing is an explicit, recorded authorization — a structured JSON record (`version`, `againstCount`, `authorizedBy`, `authorizedAt`, `rationale` naming why another RC is preferable to simplifying, removing, or externally repairing the gate; schema in [references/postmortem.md](postmortem.md)) — passed via `--authorization <file>`. The record binds to the current count: one authorization covers exactly one continuation, and a further qualifying failure re-holds. There is deliberately **no env var or flag that skips the check** — a silent bypass is the failure this gate exists to end.
+
+**Mint the rc tag on the merged promotion SHA** — this is what triggers the build, on the `rc-tag` shape only. (**Skip the mint on the other three shapes**, pre-flight item 5: under `branch-push` the merge you just did is the trigger, so go straight to watching the build; under `final-tag` the version tag at step 5 is; under `no-deploy` there is no build to fire and the rest of this step is a decided `n/a`. The rc exists only to give a tag-triggered pipeline something to fire on that is not the version tag.) **The mint records its tag onto the attempt that is already open** — it does not open one, and skipping it never leaves the lease untaken:
+
+```bash
+RC_TAG=$(node <resolve-release>/scripts/version.mjs rc --version <v> --sha <shipped> \
+  --target-branch <prod> --production-branch <prod> --topology-probe preflight-probes.json --push)
+node <resolve-issues>/scripts/run-state.mjs merge <run-slug> \
+  "{\"release\":{\"attempt\":{\"rcTag\":\"$RC_TAG\"}}}"   # onto the OPEN attempt
+```
+
+It prints the tag it minted (`v<v>-rc.1`, then `-rc.2` on a later attempt at a different SHA). Re-running it on the **same** SHA is a resume-safe no-op that prints the existing tag rather than firing a second build — so a resumed session cannot spam rc tags. A stalled build is re-run from the platform, not by minting another tag. Recording the tag is idempotent for the same reason; **moving** it is refused (principle 10 — an attempt records its rc tag once).
+
+**Watch candidate delivery with one bounded launch**, keyed by the immutable RC tag and selected SHA:
+
+```bash
+node <resolve-release>/scripts/watch-candidate-delivery.mjs \
+  --rc-tag <rc-tag> --sha "$SHIPPED" --service <svc> --region <r>
+```
+
+The watcher writes one heartbeat per poll to stderr and exactly one terminal structured verdict to stdout. Its progress and terminal states are `not-triggered`, `building`, `ready-at-0`, `failed`, `timed-out`, and `ambiguous`. Build receipts, when readable, supply progress and classified build failure, but they are optional evidence: Cloud Run is authoritative for success when it exposes exactly one candidate keyed to the selected SHA at 0%, reports that revision Ready, and its health endpoint attests the SHA/revision/digest tuple. Therefore a candidate already Ready terminates promptly even when the build-list response omits substitutions or other filtered fields; the watcher never uses unsupported server-side fields to decide identity.
+
+This watcher **observes only**. It never mints or moves an RC tag, deploys or deletes a revision, shifts traffic, writes the run manifest, or closes the Release Attempt Lease. A `failed`, `timed-out`, or `ambiguous` verdict is evidence for the main loop to route and record; it is not authorization for the watcher to recover or finalize anything. On `ready-at-0`, record its candidate identity and continue immediately to validation. Mechanics remain the platform skill's (`cloud-build` → Post-deploy smoke gate), while this step confirms the contracted output: a candidate revision at **0% traffic** under its **SHA-keyed tag**, with its **revision name** and **candidate URL**. A build that reports success while traffic already moved is a **pipeline defect**, not a release to continue.
+
+**A terminal pre-candidate failure closes through one command, before the candidate lane returns.** When the delivery evidence proves this attempt produced no candidate revision (for example, a failed RC-triggered build), construct the failed-pre-promotion bundle with its attempt id, SHA, build identity and verified disposition, then run:
+
+```bash
+node <resolve-release>/scripts/close-attempt.mjs <run-manifest.json> \
+  --bundle release-evidence.json --dir <durable-evidence-dir> \
+  --state failed-pre-promotion \
+  --evidence "build failed before candidate creation; incumbent remained at 100%"
+```
+
+`close-attempt.mjs` validates the bundle and release-attempt transition, emits the top-level immutable bundle, and only then writes the terminal close. The emitted record stamps `failurePhase: "pre-candidate"`, so `version-postmortem.mjs` and `rc-circuit-breaker.mjs` discover it without a manual follow-up emit. A `timed-out` or `ambiguous` verdict is not this path until the main loop has proved no candidate exists; unknown platform state continues to hold the lease.
+
+**Take delivery with a comparison, not a lookup — discovery fails closed (principle 12).** Three reads in order, all read-only against the candidate (principle 4: it is wired to the real production database, so nothing here may be anything but a GET), and the middle one is yours because a platform read is the release lane's job, not a script's:
+
+```bash
+# Prefer JSON: Cloud Run omits percent on zero-traffic tagged rows. The shared parser reconstructs every
+# omitted row as 0 only when the complete observation has valid explicit percentages totaling
+# 100%; partial, overfull, invalid, or otherwise ambiguous observations still refuse.
+gcloud run services describe <svc> --region <r> --format=json > candidate-service.json
+node <resolve-release>/scripts/candidate-identity.mjs locate \
+  --sha $SHIPPED --traffic candidate-service.json \
+  [--candidate-tag-prefix <repo-prefix>] > candidate-locate.json   # exit 1 = REFUSED, stop
+CAND_URL=$(node -p 'JSON.parse(require("fs").readFileSync("candidate-locate.json","utf8")).evidence.candidate.url')
+curl -fsS "$CAND_URL/health" > candidate-health.json
+node <resolve-release>/scripts/candidate-identity.mjs attest \
+  --sha $SHIPPED --locate candidate-locate.json --health candidate-health.json \
+  > candidate-identity.json                                               # exit 1 = REFUSED, stop
+```
+
+**Where pre-flight item 3 declared no attesting endpoint**, the third read is the candidate revision's *configured* image digest instead of its health tuple, and it is passed as the declaration's substitute — `attest` refuses with `e:no-fallback-digest` without it, because that digest is the entire remaining check at step 4b:
+
+```bash
+CAND_DIGEST=$(gcloud run revisions describe <candidate-revision> --region <r> \
+  --format='value(status.imageDigest)')
+node <resolve-release>/scripts/candidate-identity.mjs attest \
+  --sha $SHIPPED --locate candidate-locate.json \
+  --declare-no-attestation "<reason from pre-flight item 3>" \
+  --candidate-image-digest "$CAND_DIGEST" > candidate-identity.json      # exit 1 = REFUSED, stop
+```
+
+`--candidate-tag-prefix` defaults to `candidate-`. Supply it when the repository's reviewed
+pipeline contract uses another SHA-keyed namespace such as `a-`; the accepted locate artifact
+records the prefix, and `attest` plus post-shift `serving` revalidate the tag against that recorded
+namespace. It changes only the namespace, never the exact-SHA, single-entry, 0%-traffic, or
+attestation requirements.
+
+A refusal is the release **stopping**, not a diagnostic to weigh: `e:candidate-absent` (the pipeline did not publish this SHA's candidate), `e:ambiguous-candidate`, `e:incomplete-traffic-entry` (revision, URL and percent would have come from different deployments), `e:candidate-traffic-moved` (the delivery above, mechanized — the candidate is not at 0%, so the pipeline shifted traffic and this is a pipeline defect, not a release to continue), `e:sha-mismatch` / `e:revision-mismatch` (the running process is not what the coordinates claim), `e:locate-sha-mismatch` (the `locate` artifact you passed describes a **different commit** — a stale `candidate-locate.json` from an earlier rc, which a resumed session is exactly how you get), and **`e:second-candidate-in-flight`** — the case that used to be a warning to notice. That last one *is* principle 7 violated, and it is now the script's exit code rather than the agent's recollection: one of the two candidates was about to be validated under the other's identity. Route it like any other pre-exposure stop — nothing was exposed, nothing needs deleting yet, and the second release is resolved before this one resumes. `--help` names every id and its route (`candidate-identity.mjs --help`); the declared-weakening flags come from [pre-flight item 3](preflight.md#pre-flight-gate-confirm-the-authorization-envelope-mandatory).
+
+**Pre-locate hygiene (#819).** Before running `locate`, clean traffic tags left by previous releases. A successful promotion can leave a `<repo-prefix><sha>` tag (by default `candidate-<sha>`) on the revision that is now serving 100% (the incumbent), or an orphan 0% revision from a release that already closed. Those tags are not a true second release, but they still make `locate` refuse. Run the hygiene check against the same traffic capture and pass the repository's reviewed prefix to both hygiene and `locate`:
+
+```bash
+node <resolve-issues>/scripts/run-state.mjs check-release-lease-scoped \
+  <run-slug> --repo <owner/name> [--service <svc>] > product-leases.json
+node <resolve-release>/scripts/candidate-hygiene.mjs locate \
+  --sha $SHIPPED --traffic candidate-service.json \
+  --lease-report product-leases.json \
+  --terminal-evidence prior-release-evidence.json \
+  --candidate-tag-prefix <repo-prefix> > candidate-hygiene.json
+# If decision is "clean", run the emitted gcloud command and re-capture traffic before locate:
+gcloud run services update-traffic <svc> --region <r> --remove-tags <stale-tags>
+# If decision is "refuse", e:second-candidate-in-flight is still a hard stop.
+```
+
+`candidate-hygiene.mjs` and `candidate-identity.mjs` consume one shared parser and normalization. A foreign tag in the selected namespace is cleanable only when the full capture proves it has **0% traffic**, canonical terminal evidence (a resolve-release manifest or immutable evidence bundle) matches its exact tag and revision, and `check-release-lease-scoped` returns a valid empty report for the same product. Nonzero or ambiguous traffic, missing/nonterminal/mismatched evidence, and held or unknown matching leases still refuse with `e:second-candidate-in-flight`. Without the lease report after the other proofs, the script reports `needs-lease-report` so the operator does not guess. The release lane may pre-authorize this hygiene in the envelope ([pre-flight item 3](preflight.md#pre-flight-gate-confirm-the-authorization-envelope-mandatory)); otherwise it stops for human confirm before executing the cleanup command.
+
+**Record `release.candidateIdentity` — the identity, not just the coordinates.** `attest`'s output is the field verbatim: `sourceSha`, `revision`, `imageDigest`, `imageDigestSource`, plus the `url`/`tag` it was read from and the `guarantee`/`weakenings` it was established under. **Every one of those fields is populated in every branch that accepts** — `imageDigestSource` is `attestation` under the full guarantee and `candidate-revision-spec` under the declared weakening, which is what tells a later reader (and step 4b) which comparison they are getting without inferring it from which fields happen to be set. **A populated record is not a verified one, though.** `attest` re-derives the coordinates it copies out of the `locate` artifact, but it finds what to re-derive by matching the record against that artifact, so a field the record carries under a *different* name from the one it was read under is copied across without a second look. Read the fields you are about to act on — row 4a's identity question is a check you run, not one this script has already run for you. `candidateRevision`/`candidateUrl` say *where* the candidate is; the tuple says *what it is*, and it is what step 4b's serving confirmation re-reads after the shift instead of re-deriving identity from an image string.
+
+**Record `release.candidateRevision`, `release.candidateUrl`, and `release.previousRevision` in the manifest as soon as the build lands** — and **copy the first two out of `release.candidateIdentity` verbatim, never re-read them from the platform.** A second read is a second observation and can name a different deployment, which puts the fence in step 4b (assertion 2 reads `candidateUrl` and `candidateIdentity.tag` as if they were the same reading) in the position of comparing two artifacts nothing cross-checked. One reading, copied, keeps them one artifact. `previousRevision` is the exception and is read from the platform: it is the revision serving 100% right now, which `candidateIdentity` says nothing about — read, not assumed. This is load-bearing, not bookkeeping: between here and the step-4 traffic shift, production carries a revision no user reaches, and if the session dies now, only the manifest says it exists. `previousRevision` is what step 4b's re-check fence and step 5's failure paths compare the live traffic split against — without it recorded *before* the shift, "the incumbent still holds 100%" is a claim with nothing to check it against. A resumed run reads those fields and either completes the validation or deletes the revision — an orphan 0% revision left on prod indefinitely is the failure mode this step is designed to prevent.
+
+**On resume, observe before you act — never infer exposure from the manifest alone.** The manifest write can lag the outward action by one crash, so `step` tells you what was *started*, not what landed. Any resume at `deploy`/`validate`/`expose` begins by reading the **live traffic split** from the platform and comparing it against `candidateRevision`. That reading, not the manifest, decides the branch: candidate at 0% → continue validating; candidate at 100% → you are past exposure, go to `verify`; anything in between → a partial shift (see step 4b). Choosing a branch without this is how a resumed session deletes the revision currently serving production.
+
+**Where pre-flight item 6 declared durable processing, that resume reading is two reads, not one** — the traffic split *and* the processing state (is scheduling enabled? is admission open?). Under the [step-4b sequence](exposure.md#4--validate-the-candidate-then-expose-it-skill-smoke) the pause precedes the shift, so "candidate at 0%" no longer identifies one state: it is what a resume finds both when validation never finished *and* when a crash landed **between the pause and the shift**, with production serving the incumbent and its processing stopped. The split alone cannot tell those apart, and taking the first reading is a silent outage — the release lane paused production and then walked away from it. Read the processing state, and if it cannot be read, that is the ambiguous state ([principle 14](../SKILL.md#non-negotiable-principles)), not a branch to pick.
+
+**The revision name is still the durable handle.** A tag — even a SHA-keyed one — is a pointer the platform owns, so deletion and every retry target the **revision name**, which names one immutable artifact. What the SHA-keyed tag changed is the *discovery*, not the handle: under a shared `candidate` tag the URL meant "the newest candidate" and a disagreement was something to notice, whereas now a rival release cannot take this SHA's tag and shows up as `e:second-candidate-in-flight` above.
+
+A failed **build** never produced a candidate: route to `cloud-debug`, fix forward or abandon. Prod was never touched, no rollback, and — because no final tag exists — **no version is burned**; the retry reuses the version at the next rc.