@1aboveio/skills 0.10.0

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

@@ -0,0 +1,202 @@
+# Versioning, tagging, and the CHANGELOG
+
+The release lane assigns a **version** to what it ships, records it in the **CHANGELOG**, and marks the shipped SHA with an immutable **tag**. [`scripts/version.mjs`](../scripts/version.mjs) is the mechanism and the **source of truth** for subcommands, flags, and exit codes — run `node <resolve-release>/scripts/version.mjs --help` for the authoritative list (the file header carries the invariants and points at `--help` for the case list, so there is no second copy to drift) rather than hand-rolling `git tag`. This file holds the **doctrine the script does not encode**: the policy behind the mechanism, and the judgment an agent still owns. Several rules below are unrecoverable once violated on a remote.
+
+## 1. Versions exist only on production
+
+**A version, a tag, and a CHANGELOG cut are created only when promoting into the production branch.** A dev/staging release is **unversioned** — identified by its **SHA** (and the platform's revision id), which the deploy, the smoke run, and any rollback already reference.
+
+This is not style. A version is a **public promise about an immutable artifact**: consumers pin it, incident reports cite it, rollback targets it. `dev` redeploys many times a day, so versioning it either produces meaningless churn (`v1.5.0-dev.47`) or mints a version that later diverges from the `v1.5.0` that actually reaches production. `version.mjs` enforces this: `plan`, `changelog`, `rc`, and `tag` **exit 3** (a normal outcome the loop branches on, not an error) when the target is not the production branch.
+
+### Exit codes
+
+An agent branches on these, so each carries exactly one meaning; an overloaded code — 3 meaning both "skip versioning" and "already cut" — would make a resuming run silently ship production untagged. That one-meaning-per-code invariant is the judgment this file owns; the four codes and their exact triggers are the script's — `node <resolve-release>/scripts/version.mjs --help` is the authoritative case list (**exit 3** is "not a production promotion, and nothing else", the normal dev-release outcome §1 branches on).
+
+## 2. The CHANGELOG has two zones — that is why dev needs no version
+
+A CHANGELOG is not a list of versions. It has an **unversioned zone** (`## [Unreleased]`, where changes accumulate as they merge to dev) and a **versioned zone** (`## [1.5.0] — 2026-07-10`, minted once at the promotion). A change is written down when it lands and *versioned* when it ships — different moments, and the two zones are how one file holds both. At the promotion the **cut** renames the accumulated content under a `## [1.5.0] — <date>` heading and leaves `Unreleased` empty.
+
+Two ways to populate the section, both supported by `version.mjs changelog`, and they compose:
+
+- **Derived** (default, zero per-PR discipline) — the cut renders entries from the constituent PRs' conventional-commit titles (`feat(billing): partial refunds` → `### Added`), linking each PR and the issues it closes.
+- **Accumulated** (opt-in per repo) — PRs hand-write entries under `Unreleased`; the cut **carries that body into the versioned section**, merged with the derived entries.
+
+**Carrying is an invariant, not a nicety.** A hand-written note that no PR title captured must survive the cut; discarding the `Unreleased` body would silently delete the most considered lines in the file.
+
+## 3. The cut lands on the release branch, before the promotion
+
+The version bump + CHANGELOG cut is a **commit on the assembled release branch** (step 1b), never a commit onto the production branch after merging. This is forced by [principle 3](../SKILL.md#non-negotiable-principles): **promotions fast-forward**. A commit created on `main` *after* the promotion merges puts a commit on the base that the head lacks, so the next promotion is no longer fast-forwardable and `review-pr`'s promotion mode (correctly) rejects it. Cutting on the release branch keeps this promotion a clean fast-forward and makes the shipped SHA the exact SHA whose CHANGELOG says it shipped.
+
+Under the pinned-candidate model ([principle 11](../SKILL.md#non-negotiable-principles)) the release branch is cut at the candidate SHA while `dev` keeps moving, so the cut commit reaches `main` but **not** `dev` — which is why the post-release back-merge `main → dev` is a standard step-5 action, and until it lands the next promotion cannot fast-forward. Anything else the repo carries a version in (`package.json`, `pyproject.toml`, a `VERSION` file, chart/image tags) is bumped **in that same commit**.
+
+## 4. Tags are immutable
+
+The tag is **annotated** (`git tag -a`, carrying a releaser and date), created on the promoted SHA, and never touched again.
+
+- **Never move a tag.** Re-tagging the *same* SHA is a resume-safe no-op; a *different* SHA exits 1. There is deliberately no `--force`.
+- **Never delete a published tag.** Anyone who fetched, pinned, or built from it now disagrees with the repo about what `v1.5.0` means.
+- **Never reuse a burned version** (§5).
+- A tag must name a SHA that is an **ancestor of the production branch** — `tag --production-branch main` refuses otherwise, so a tag can never name a revision that was never promoted. The ancestry check **fetches the remote tip first** and resolves against `origin/<production-branch>` (identity-v0.4.1): a stale local `main` is not evidence the promotion has not landed. A **failed fetch fails closed** — a pre-existing (possibly stale) remote-tracking ref is never trusted as a stand-in for a fresh tip.
+- **Tag pushes are not stack pushes.** `version.mjs rc|tag --push` pushes the fully-qualified `refs/tags/<tag>` with `--no-verify`, because a Mergify stacks pre-push hook that rewrites `git push` into `mergify stack push` is correct for branch heads and wrong for immutable release tags (identity-v0.4.1). Do not re-discover `git push --no-verify origin refs/tags/…` by hand; the script owns that path.
+
+### Trigger-owned builds are probed before RC mint
+
+A tag-triggered production build and a controller-submitted build are distinct topologies. Passing `_DEPLOYED_VERSION` to `gcloud builds submit` does not establish that Cloud Build receives it when its **`TAG_NAME` trigger** fires. Before `version.mjs rc` can create an immutable tag, `preflight-probes.mjs check --json` must contain a ready `rc-tag-topology` record with `prodBuildTrigger: "tag-trigger"`, `versionSource: "TAG_NAME"`, and `candidateTagSource: "TAG_NAME"`. Its representative substitutions prove the exact path: `TAG_NAME` is an RC tag; `_DEPLOYED_VERSION` is that tag's final SemVer; and `_CANDIDATE_TAG` is that RC tag. The RC command consumes this file with `--topology-probe` and fails closed on a missing, unreadable, unknown, or mismatched record.
+
+That record is about the **trigger-owned** candidate. A dev image keyed only by source SHA may be useful diagnostic information, but it is not RC candidate evidence and cannot refuse a candidate lane as already published. RC candidate evidence begins only after the immutable RC tag, its triggered build, and the candidate revision/tag are bound together.
+
+## 5. The invariant, the trigger, and the burn
+
+**The invariant: the final tag is created after verification.** `v<version>` is minted once post-deploy verification passes ([step 5](routing.md#5--route-on-the-verdict)), so **it always names a revision observed serving production** — [principle 5](../SKILL.md#non-negotiable-principles) (the loop exits on observed state) applied to the version.
+
+What varies between repos is not *when* the version tag is cut but **how the production deploy is triggered** — four shapes, declared at the pre-flight gate ([item 5](preflight.md#pre-flight-gate-confirm-the-authorization-envelope-mandatory)) as `envelope.deployTrigger`. **Undeclared is a refusal**, not a default: the fourth shape exists precisely so a repo that fits none of the first three has something to declare instead of sliding onto the legacy row.
+
+| Deploy trigger | `envelope.deployTrigger` | rc at step 3 | Final `v<version>` tag | If the release fails |
+|---|---|---|---|---|
+| **Branch push** (`main`) | `branch-push` | none | after verification | No version claim was published — the retry **reuses** the version. |
+| **`v*-rc.*` tag** (default where a tag must trigger the deploy) | `rc-tag` | minted | after verification | Same: rc tags carry no promise, so the retry **reuses** the version at the next rc. |
+| **Final `v<version>` tag** *(legacy)* | `final-tag` | none | before deploy — it *is* the trigger | **The version is burned.** |
+| **No deployed surface** — a versioned artifact nobody deploys (library consumed by tag, skills installed by symlink, schema package) | `no-deploy` | none | after verification | Nothing was deployed, so nothing is burned — the retry **reuses** the version. |
+
+**The `no-deploy` shape makes [steps 3–4](candidate.md#3--promote-then-build-the-candidate-no-exposure-yet) a decided `n/a`** — no rc, no candidate revision at 0%, no 4a smoke against a candidate URL, no traffic shift, no 4b serving confirmation — and it owes `envelope.deployTriggerReason` naming *what* the artifact is and *how* consumers take it, so the `n/a` is checkable rather than a skip. Everything outside those two steps is unchanged: the promotion is authorized, the Release Attempt Lease opens and closes, the final tag is still cut only after verification, and every terminal exit still emits its evidence bundle. What stands in for the deploy observation is the consumer-facing read — the artifact resolvable at the tag the way consumers take it — because [principle 5](../SKILL.md#non-negotiable-principles) has no topology exemption.
+
+**And the bundle this shape emits carries *that* evidence, not a deployment's** (#604). The required set is a property of `(terminal state × trigger shape)`: on `no-deploy`, `released` owes the immutable final tag (`releaseTag`), the Release reference (`releaseRef`) and the verification standing in for the two observations (`verification` — CI plus the full suite on the tagged SHA, and the consumer-facing read above); a failed attempt owes the verification that stopped it and the cleanup record, and no tag at all, because the tag is cut only *after* verification on this shape. It must carry **none** of the five deployment artifacts (`candidateReceipt`, `candidateVerdict`, `approval`, `trafficTransition`, `liveVerdict`) — asserting a traffic transition on a shape with no traffic is the fabrication the bundle already refuses, read per shape instead of per state. The deployed shapes are untouched: requiring what a shape cannot produce made the bundle unemittable there, and that is what was fixed — **not** the requirement itself, which is exactly as strict on every shape that deploys.
+
+**Release-candidate tags** exist to solve one problem: a pipeline triggerable only by a tag would otherwise force the version tag to precede verification, burning a version on every failed attempt. `v<version>-rc.<n>` decouples the two — a **deploy trigger, not a version claim**. Minted at [step 3](candidate.md#3--promote-then-build-the-candidate-no-exposure-yet) with `version.mjs rc`, once per candidate SHA by default (a same-SHA re-run prints the existing rc rather than firing a second build). After a verified terminal failure, use `--retry-from <prior-rc-tag>` to mint the next immutable RC for the same eligible SHA; a repeated invocation with that predecessor resumes the retry tag instead of minting another one. An rc is **never a baseline**, never published as a Release, never a collision against the final tag. The trigger pattern must match `v*-rc.*` and **not** the final tag, or minting `v1.5.0` at step 5 fires a pointless second build against an already-verified release.
+
+**A burned version** is one whose tag reached a remote but never survived to serve production. Under the three shapes that tag after verification (`rc-tag`, `branch-push`, `no-deploy`) this **cannot happen** — that is their whole point. It applies only to the legacy shape, where two doors burn identically: the **build failed** (nothing deployed) or the **verification failed** (deployed, unhealthy, rolled back) — "prod was never touched" is true of the first and irrelevant, because the tag is public regardless. A burned version is never reused, never deleted, never re-pointed; the next attempt takes the next patch (`v1.5.0` burned → the fix ships as `v1.5.1`). Nothing extra tracks this — **tag immutability enforces the burn**: `plan` exits 1 when the computed final tag already exists, so the human decides resume vs bump. A burn is *visible*: the tag exists, but no GitHub Release was ever published (the Release is created only on verified-done, [step 5](routing.md#5--route-on-the-verdict)).
+
+**Withdrawn CHANGELOG entries.** On the legacy path the cut commit is already on `main` when a rollback happens, so the CHANGELOG claims `v1.5.0` shipped and it didn't. **Do not delete the section** — the CHANGELOG is append-only, and deleting it erases the only public record that the version existed. `version.mjs withdraw --version 1.5.0 --incident '#77'` annotates it in place, in the same commit that cuts the *next* version. (Under the three tag-after-verify shapes the cut commit is on `main` too, but no tag or Release claims the version shipped, so the retry simply reuses it and no annotation is needed.)
+
+### Adopting the lane in a repo that already releases
+
+The pre-flight *declares* the trigger shape; **changing** it is where a repo is more exposed than during any release it will ever run. For an interval, the old trigger and the new one are both armed — one push, two production builds, finishing in whatever order they finish and leaving prod on an arbitrary revision — principle 8's out-of-order-builds hazard, arriving from a trigger no authorization covers. The sequence below exists to make that interval **zero-length**, and that is the invariant it protects: **never two live production triggers.**
+
+1. **Land the new machinery inactive.** Workflow, pipeline changes, tests — merged while the existing production trigger stays exactly as it was. Nothing new can fire yet.
+2. **Verify the new deploy identity read-only.** Whatever authenticates the new path (OIDC/workload-identity federation, a service account, a deploy key) proves it can *read* before it is capable of mutating anything.
+3. **Make tag immutability real — before the trigger moves.** [Principle 10](../SKILL.md#non-negotiable-principles) and §4 state it, and `version.mjs` refuses to violate it — but neither can stop anything *else* in the repo from moving or deleting a tag. A **tag ruleset over `v*` — creation allowed, update and deletion blocked** — can, and it covers both tag classes: an rc is a trigger, not a disposable label. The ordering is the point, and it holds in either direction: tags are load-bearing under every shape — firing production under the tag shapes, standing as the sole version claim under branch push and no-deploy — so the switch always changes what the lane leans on tags for, and it must not do that while anything else can still move or delete one. The ruleset precedes the switch, never follows it.
+4. **Switch the trigger atomically.** One change that disarms the old path and arms the new one, never two changes with a window between them.
+5. **Prove the whole path with one controlled release** — a real promotion carried through candidate, validation, exposure, and verification. A dry run proves the pieces, not the path.
+6. **Retire the old controls only after that proof** — legacy trigger config, superseded branch rules, obsolete promotion workflows.
+
+Three ways this goes wrong, each of them reopening the interval: switching the trigger first, tolerating overlapping production triggers "briefly", and deleting the old rules before step 5 has proven what replaced them.
+
+## 6. Display version is not identity version
+
+A release carries **two** version strings, and conflating them is what leaves UI and `/api/health` showing the attempt tag after the final claim has been verified:
+
+- **Identity version** — the immutable tag or SHA that names what is running. Under rc-tag topology this is often `v<version>-rc.<n>`, because that tag is the **deploy trigger**. It is what `candidate-identity.mjs` attests (`sourceSha`, `revision`, `imageDigest`) and what the release lane uses for routing, rollback, and the final tag.
+- **Display version** — the string the running service prints in UI and `/api/health` for operators. After a verified release this should be the **final semver** (`v<version>`), not the rc trigger tag, unless the repo deliberately chooses otherwise.
+
+The release lane declares which one the service should show via `envelope.displayVersionPolicy`:
+
+| Policy | Meaning | Default context |
+|---|---|---|
+| `final-semver` | UI/health show the final release version (`vX.Y.Z`). | **Default for `rc-tag` topology**, where the trigger tag is not the public version. |
+| `trigger-tag` | UI/health show the tag that fired the deploy (`vX.Y.Z-rc.N`). | Opt-in for repos that want dashboards to name the attempt. |
+| `short-sha` | UI/health show the short SHA. | Opt-in for repos whose meaningful identity is the commit. |
+
+The default is **per topology**: `rc-tag` defaults to `final-semver`; other topologies have no default — the pre-flight gate must declare the policy, or the lane refuses. On `rc-tag` an omitted `displayVersionPolicy` resolves to `final-semver`, and the assertion script still checks the result: a service that shows the attempt tag is refused unless a declared exception is recorded.
+
+**Asserting the policy.** After the traffic shift, step 4b's serving confirmation already reads `/health` for the identity tuple. The same health JSON is passed to [`scripts/version-assert.mjs`](../scripts/version-assert.mjs). Pass `--policy` explicitly, or, under `rc-tag`, pass `--deploy-trigger rc-tag` and let the script resolve the default:
+
+```bash
+node <resolve-release>/scripts/version-assert.mjs serving \
+  --health serving-health.json \
+  --settings serving-settings.json \
+  --frontend-asset frontend-asset-version.json \
+  --policy final-semver \
+  --version "$NEXT_VERSION" \
+  --trigger-tag "$RC_TAG" \
+  --sha "$SHIPPED"
+
+# Equivalent under rc-tag: --deploy-trigger rc-tag resolves to --policy final-semver
+node <resolve-release>/scripts/version-assert.mjs serving \
+  --health serving-health.json \
+  --settings serving-settings.json \
+  --frontend-asset frontend-asset-version.json \
+  --deploy-trigger rc-tag \
+  --version "$NEXT_VERSION" \
+  --trigger-tag "$RC_TAG" \
+  --sha "$SHIPPED"
+```
+
+### Standalone mandatory publication gate
+
+`version-assert.mjs serving` is a **standalone mandatory gate** between post-shift serving confirmation and step 5 publication. Its three JSON inputs are the post-shift `/health` version, the post-shift `/settings` version, and the frontend asset version; under `final-semver`, **all three must equal the final SemVer**. Capture the command's JSON result and exit code as `release.versionAssert`. Exit **0** is the only result that permits step 5. Exit **1** is a refusal: **stop immediately** and do not mint the final tag or create the GitHub Release. Exit **2** is an unrunnable gate and also stops the release under principle 13.
+
+Run the assertion as its own process. **Do not place `&&`, `||`, `;`, or `|` after `version-assert.mjs`, and do not combine it with smoke, status, or informational commands in a shell chain.** A JSON `decision:"refuse"` is not a prompt for human interpretation or a successful command result; the nonzero exit is the release decision. The tag mint and GitHub Release publication path must refuse unless the recorded gate result is `decision:"accept"` with exit code 0.
+
+A repo that genuinely needs a mismatch records an explicit exception at pre-flight:
+
+```bash
+node <resolve-release>/scripts/version-assert.mjs serving \
+  --health serving-health.json \
+  --settings serving-settings.json \
+  --frontend-asset frontend-asset-version.json \
+  --policy final-semver \
+  --version 0.5.0 \
+  --record-mismatch "legacy UI embeds rc tag until next major; accepted per #822-exception"
+```
+
+The exception is part of the authorization envelope (`envelope.displayVersionPolicyException`) and is emitted into the evidence bundle so a post-incident read can see that the mismatch was declared, not accidental.
+
+**Consumer pipeline: strip, do not fire twice.** Under `rc-tag` topology the consumer build pipeline (e.g. Cloud Build) receives `vX.Y.Z-rc.N` as the trigger and must set `DEPLOYED_VERSION` to the final `vX.Y.Z` for the service to display — **without also firing a deploy on the final `vX.Y.Z` tag**. The pattern that does this is the consumer pipeline's responsibility, not this skill's; it is documented at `skyee#1558`. Do not re-implement it here. The release lane's only job is to assert that the resulting display version matches `envelope.displayVersionPolicy`.
+
+## 7. The bump is computed from the release content, then confirmed
+
+`version.mjs plan` reads the constituent PRs and derives the bump — it never guesses, and never decides alone: the computed version is proposed at the [pre-flight gate](preflight.md#pre-flight-gate-confirm-the-authorization-envelope-mandatory) and enters the authorization envelope.
+
+| Release contains | Bump | Under `0.x` |
+|---|---|---|
+| a breaking change (`feat!:`, `BREAKING CHANGE:` in the body, or a `breaking` label) | **major** | minor |
+| a new feature (`feat:`) | **minor** | minor |
+| fixes / internal changes only | **patch** | patch |
+
+Before 1.0, breaking changes take a minor bump (the public contract is still unstable) and non-breaking features also take a minor bump (a new capability is never presented as a patch fix); `--strict` disables only that pre-1.0 convention. The baseline is the highest release tag **merged into the production branch** — prerelease tags (`v1.5.0-rc.1`) are never a baseline, because an rc names an attempt, not a shipped release, so treating one as the baseline would advance the version on a release that may never have survived validation.
+
+**A major bump always forces a human confirm**, even under [`auto-when-green`](auto-when-green.md): breaking a published contract is irreversible for consumers who have already pinned it.
+
+## 8. Artifacts carry the same version
+
+If the pipeline builds a container image or a package, it is tagged with the **same version string and the same SHA** the git tag names. A `v1.5.0` tag pointing at `abc123` while the deployed image is `:latest` built from `def456` means the version identifies nothing — and rollback has no target.
+
+`version.mjs verify` ties tag, shipped SHA, and live revision together. **It only applies where the final tag already exists** — the legacy path, at [step 4](exposure.md#4--validate-the-candidate-then-expose-it-skill-smoke). Under the three tag-after-verify shapes there is no final tag at step 4 (`verify` would exit 1), because it is created in step 5 after the live revision is confirmed; there the equivalent check is step 4b's serving-revision confirmation against the promoted SHA.
+
+## 9. Monorepos
+
+A single repo-wide version is the default and is what `version.mjs` implements. If the repo publishes independently-versioned packages, the release lane still cuts **one** release (principle 8 — one promotion, one deploy); per-package versions are the packaging tool's job (changesets, Lerna, `uv`), invoked from the same cut commit. Do not fan out N promotions to version N packages.
+
+## Output contracts
+
+`version.mjs rc` and `version.mjs tag` have the same output modes. Their default stdout is exactly one tag followed by a newline, which is safe for command substitution. Pass `--json` when a caller needs the stable object `{tag, sha, pushed, resumed}`: `sha` is the resolved commit, `pushed` says whether this invocation pushed the tag, and `resumed` says whether the desired immutable tag already existed. First execution, local resume, pushed convergence, cross-clone resume, and dry-run all retain those four keys. Human diagnostics go to stderr and never contaminate either stdout payload.
+
+`version.mjs changelog --dry-run` requires an explicit output mode. `--format markdown` writes the complete planned CHANGELOG file to stdout. `--format json` writes `{version, file, noop, markdown}`, where `markdown` is that same complete file and `noop` identifies a resume-safe already-cut plan. Diagnostics, including an already-cut resume notice, use stderr. Neither dry-run mode writes the file.
+
+```bash
+RC_TAG=$(node <resolve-release>/scripts/version.mjs rc --version <v> --sha <shipped> \
+  --target-branch <prod> --production-branch <prod> --push)
+node <resolve-release>/scripts/version.mjs tag --version <v> --sha <shipped> \
+  --target-branch <prod> --production-branch <prod> --push --json \
+  > final-tag.json
+node <resolve-release>/scripts/version.mjs changelog --version <v> --date <YYYY-MM-DD> \
+  --changes <prs.json> --target-branch <prod> --production-branch <prod> \
+  --dry-run --format json > changelog-plan.json
+```
+
+## Command reference
+
+The subcommands, flags, and exit codes are the script's own — run `node <resolve-release>/scripts/version.mjs --help` (the file header points there too, rather than restating them); do not transcribe them here, where they drift. (Recall §1: `--target-branch`/`--production-branch` are required on `plan`, `changelog`, `rc`, and `tag`, and `--target-branch` is the branch you are *promoting into* — production on a promotion, staging on a dev release, where those commands exit 3.)
+
+Two related scripts live beside `version.mjs` rather than inside it, because each owns a distinct release-lane check:
+
+- [`scripts/build-changes.mjs`](../scripts/build-changes.mjs) — builds the `--changes` JSON `version.mjs plan` consumes from raw `gh pr view --json` output. Do **not** hand-transform `gh pr view --json` for this; run `node <resolve-release>/scripts/build-changes.mjs --help` for the flags. Pipe it straight into `plan`/`changelog`:
+
+```bash
+node <resolve-release>/scripts/build-changes.mjs <pr>… \
+  | node <resolve-release>/scripts/version.mjs plan --target-branch <b> --production-branch <b> --changes -
+```
+
+- [`scripts/version-assert.mjs`](../scripts/version-assert.mjs) — asserts the running service's **display version** matches the `envelope.displayVersionPolicy` declared at pre-flight (or the `rc-tag` default resolved by `--deploy-trigger rc-tag`). Run `node <resolve-release>/scripts/version-assert.mjs --help` for the policy list and the mismatch-exception flag.
+
+**Why a script and not a `gh`→`jq` one-liner** — the hand recipe fails *silently* two ways while `plan` still looks correct: it drops every `closes #n` link (gh emits no `issues` field for the notes to link from; the `number`→`pr` rename is a separate fix), and it lets a `BREAKING CHANGE:` living only in a PR body escape the bump (it never fetches `body`) — a silently under-versioned release. `build-changes.mjs --help` carries the full #407/#408 rationale (the rename + `issues` derivation, and the `body` fetch); it is the source of truth for what the script fixes.

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

@@ -0,0 +1,53 @@
+# Why — the reasoning behind the release rules
+
+**Not a runtime file. Never read this during a release.** It is the archive: the derivations, the measurements, and the incidents that produced the rules, kept so a rule can be re-judged rather than re-litigated and so an edit knows what it is deleting. Read it when you **edit this skill** or audit a decision. The runtime files state what to do; this one says why, and a release that stops to read it is spending its context on history. Keeping it off the loop is also what lets it grow — nothing here competes for the budget the runtime files live under.
+
+The rules themselves are [principles.md](principles.md) (the non-negotiables) and the phase files. This is only their reasoning.
+
+## Why the handoff reports a thing even when nothing went wrong
+
+Three items in the [definition of done](../SKILL.md#definition-of-done-handoff-report) are reported unconditionally, and each is unconditional for the same reason: **a record that appears only when something is wrong is indistinguishable from one nobody kept.**
+
+- **The exposure identity.** `envelope.exposureIdentity` is named on every release, not only the weakened ones. An audit that names the identity only when a weakening applies reads exactly like an audit that never looked — the reader cannot tell "checked, and it was clean" from "not checked".
+- **The release-evidence bundle location.** Reported on every terminal exit, not only the verified one. A failed attempt's bundle is what makes that failure reachable months later without this session; an unstated location reopens the session-scoped hole #441 closed.
+- **The quiescence record, including its absence.** Where pre-flight item 6 declared *no* durable processing, the report says so. An absent record and a declared-absent one read identically otherwise, and only one of them means the question was asked.
+
+The quiescence record also states plainly that the resume order was the exact reverse of the pause order. That sentence is the one claim a reader can check against the two lists the report just gave them — everything else in the record has to be taken on trust.
+
+## Why the post-mortem is adjudicated, not just saved
+
+`report.mjs` computes and saves the post-mortem at every terminal step, so the artifact is never the missing piece — the *adjudication* is. **An unadjudicated finding is not a result**: it is a sentence somebody may read. Each finding gets a line and the rendered issue gets filed (`--issue`).
+
+A release that **stalled** never reaches a terminal step, so nothing auto-saves — which is exactly the case worth profiling, because "it stalled" is one of the findings. Run `report.mjs <manifest> --postmortem` by hand there.
+
+It profiles **completeness, not speed**. What this lane loses when it goes wrong is not minutes; it is the record of what happened to production.
+
+## Why this file exists at all
+
+`resolve-release` had no archive: every rule carried its own derivation inline, so the checklist rows and the phase files each grew a chain of *because* clauses — "the key is the attempt id, not the rc tag, because three of the four declarable shapes mint no rc"; "that scope is exact, not hedged". The reasoning is worth keeping and worth citing. It is not worth re-reading on every release, and a rule stated with three sentences of defence takes longer to find than one stated plainly with a pointer.
+
+## Why the bundle key is the attempt, not the version
+
+The release-evidence bundle is keyed `(attempt id, terminal state)`, and the id is `<version>-attempt.<n>` rather than the rc tag or the version. Three separate pressures put it there, and each was found the hard way:
+
+**An rc-keyed bundle was unemittable on most shapes (#599).** Three of the four declarable trigger shapes mint no rc at all, so a key derived from the rc tag left those releases with no key — and therefore no record — at every terminal exit.
+
+**A version-keyed bundle loses the retry it exists to explain.** A retry re-cuts the same version at the same terminal state, so a version key collides with the attempt it is retrying, and immutability then refuses the *second* failure's diagnosis. The record that survives is the one nobody needed.
+
+**The collision had four routes, not one, and fixing them singly is how the class survived two review rounds.** A `validate` that accepts a key `emit` cannot write tells the operator a durable record is good by the only command that could have warned them. A mint that fails **open** on an unreadable durable dir hands back an ordinal already spent. A `path` that reports "no bundles" off a dir it never read is how an operator concludes a spent key is free. And `emit` backstops none of them, because `(id, state)` immutability is deliberately permissive *across* states — one attempt legally reaches two — so two different attempts sharing an id and exiting at different states are written with no refusal anywhere.
+
+**The scope is stated exactly rather than hedged**, and that honesty is load-bearing: the mint is collision-free against **closed** attempts, because a bundle exists only after a terminal exit. In-flight attempts do not move the ordinal — the lease precondition (mint only on `free`) is what closes that route — and genuinely concurrent mints before either emits are #509's deferred atomicity. A blanket "collision-free by construction" would be a claim the code cannot deliver, and a checklist grades the claim.
+
+**The required set is per `(terminal state × trigger shape)`, not per state (#604)** — otherwise principle 5's "every terminal exit" quietly excludes a shape the pre-flight itself offers: a no-rc, no-deploy shape owing five artifacts only a deployment produces can satisfy no exit, so the release ships with no bundle at all. The widening that fix invites is the mirror failure, which is why an unknown or undeclared shape takes the **deployed** set rather than the smaller one.
+
+## Why the pin grades differently per topology
+
+The candidate pin means three different things depending on the branch topology, and the checklist grades it three ways because grading it one way marks correct runs wrong.
+
+**GitFlow** is the shape the rule was written in: the promotion head is a release branch cut at a candidate SHA, and `main → dev` back-merges after every production release so the next candidate descends from it.
+
+**Generic GitHub Flow (`release/<slug>`)** has no `dev` to back-merge into, and the shipped SHA is the release branch *rebased* onto `main` — so it carries commits that never earned a verdict. The pin is therefore only a pre-filter there, and step 4a's candidate validation is the real gate. Claiming the GitFlow-strength guarantee for that SHA overclaims evidence nobody produced.
+
+**Trunk + merge queue** looks like the same single-branch shape and is not: nothing is rebased, so the SHA that earned the verdict is the SHA that ships. The pin is a Trunk Integration Verdict on that exact trunk SHA and does **not** demote. Reading "single-branch" off the shape and demoting it is the mirror error — a correct run graded wrong — and demanding a back-merge into a branch that does not exist is the same mistake pointed the other way.
+
+Underneath all three sits principle 11's split: a SHA determines the *tree*, so build and test evidence survives the branch moving on. It does not determine the environment, so identity, remote-service, scheduler, deployment, preview and active-endpoint observations are never inherited across a matching SHA. A verdict that cannot say which half it is carrying is not evidence — an absent observation counted as a satisfied one is exactly how a green verdict ends up unable to name what anybody saw.