@1aboveio/skills 0.10.0

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

@@ -0,0 +1,149 @@
+# Step 5: route on the verdict
+
+What happens after validation or exposure returns an answer - tag and publish, or
+delete the candidate, or roll back. Previous: [exposure.md](exposure.md).
+
+### 5 — Route on the verdict
+
+**Every terminal exit emits a durable release-evidence bundle — the run manifest is the working state, the bundle is the durable record** ([principle 5](../SKILL.md#non-negotiable-principles); #441). The manifest is session-scoped (`run-state.mjs`'s job) and its verification evidence dies with the temp dir; the bundle is a first-class artifact written **once**, at the terminal exit, **keyed to the immutable attempt id and its terminal state** ([principle 10](../SKILL.md#non-negotiable-principles)) so a **failed** attempt is as reachable months later as a successful one. **The key is the attempt id, not the rc tag** — three of the four declarable trigger shapes mint no rc, so an rc-keyed bundle was unemittable on them, and inventing a key would fabricate the artifact the bundle exists to make trustworthy (#599). The attempt id exists on every shape by construction, because the lease opens at the promotion authorization, and it is **unique per attempt** — `<version>-attempt.<n>` ([step 3](candidate.md#3--promote-then-build-the-candidate-no-exposure-yet)) — so a retry that re-cuts the same version and fails the same way writes its **own** record instead of colliding with the attempt it is retrying. `rcTag` stays a **recorded field** — required wherever an rc exists, an absent one declared by the shape rather than merely omitted, and a declared no-rc shape carrying one refused as the self-contradicting record it is. Bundles written **before** #599 are unaffected: they key off their `rcTag`, so `v1.2.0-rc.1--released.json` is byte-identical. It binds what principle 5 rests on: the attempt id, the rc tag where one exists, the shipped SHA, the build identity, the candidate receipt and validation verdicts **when that attempt reached a candidate**, the exposure approval/traffic transition when it exposed, the cleanup-or-rollback record, and the **terminal attempt state — #432's `ATTEMPT_TERMINAL_STATES`, the same enum the lease closes on, never a parallel one.** **What each exit owes is a property of `(terminal state × trigger shape)`, not of the state alone** (#604) — because "what evidence exists" is a property of both. On the three shapes that **deploy** (`rc-tag`, `branch-push`, `final-tag`) nothing changes: `released` still owes the candidate receipt, both verdicts, the approval and the traffic transition, and a deployed release that cannot produce them is still not releasable. On **`no-deploy`** those five are artifacts only a deployment produces — a 0%-traffic candidate, a smoke against it, an exposure authorization, a traffic shift, a live service — so requiring them made that shape's every terminal exit **unsatisfiable**, and this repo's own `v0.5.0` shipped with **no bundle at all** for exactly that reason. There it owes instead what the shape does produce: the **immutable final tag** (`releaseTag` — the only version claim there is, so it is bound to the attempt's version), the **Release reference** (`releaseRef`), and the **verification evidence standing in for principle 5's two observations** (`verification` — CI plus the full suite on the tagged SHA, and the consumer-facing read of [references/versioning.md](versioning.md) §5). **This makes the requirement satisfiable; it does not make it optional** — a `no-deploy` bundle **carrying** any of the five is refused as the fabrication it is, at every terminal state, exactly as a `failed-pre-promotion` bundle carrying a post-shift live verdict is. And **a field written `null` is a field that is absent** — `"rcTag": null` is *no rc tag*, not an unusable one; null is never a way to satisfy something required. It is **emitted at every terminal record**, so each `record-release-attempt` below is paired with an emit — including the `blocked-manual` hold, which emits a bundle while *holding* the lease rather than closing it: **A hand-written bundle is forbidden on the normal path.** It is a recovery artifact only, and its very next operation must be `evidence-bundle.mjs validate --bundle <recovery-bundle.json>`; an invalid recovery artifact is not emitted, copied, attached, or reported.
+
+Non-released terminal paths continue to use the direct emit below:
+
+```bash
+node <resolve-release>/scripts/evidence-bundle.mjs emit --bundle release-evidence.json \
+  --dir <durable-evidence-dir>   # validates then writes <attemptId>--<terminalState>.json; exit 1 = invalid or immutability violation
+```
+
+**Immutable once written** — a mutable summary is not evidence. `emit` refuses to overwrite an existing bundle for an `(attempt id, terminal state)` with *different* content; an evidence-identical re-emit (a resumed session re-running the same close) is a resume-safe no-op. The bundle is validated and **fails closed**: an incomplete bundle, or one **claiming an observation its state never took** (a pre-exposure discard carrying a post-shift live verdict), refuses rather than writing a durable record that looks complete. Explicit non-goals it must not degrade into: **workflow logs alone, a mutable summary, or final-tag-only evidence** — the last would lose every failed attempt, which is the whole point of emitting on the failure paths. On the **verified path** the bundle is additionally **attached to the GitHub Release** (long-term retention, co-located with the version claim it evidences); failed attempts stay indexed by their attempt id in `<durable-evidence-dir>`, reachable with `evidence-bundle.mjs path --attempt-id <id>` (`--rc-tag` is the pre-#599 spelling and still resolves on the rc shape).
+
+**Verified** → four actions, then report. In [`verified-sha-github-flow`](verified-sha-github-flow.md#final-claim-and-metadata-ordering), use that mode's final-tag/GitHub-Release ordering and invoke its post-release metadata adapter after the final claim; the generic CHANGELOG cut/back-merge fields below do not apply. Metadata sync is complete only when `release.metadataPr.source` is `metadata-sync.mjs`. Any noncanonical manual completion is a recovery artifact: adjudicate it, file and link the adapter tooling issue, and retain that adjudication before treating metadata as complete. A manually merged PR without that record does not satisfy final closeout.
+
+**Publication hard precondition.** Before any final-tag mint or GitHub Release creation, read the recorded standalone `release.versionAssert` result from step 4b. It must be `decision:"accept"` with exit code 0 and evidence that `/health`, `/settings`, and the frontend asset version each match the final SemVer (or the envelope's explicit recorded exception). An exit 1 refusal or exit 2 cannot-run result **refuses this entire Verified path**: do not tag, do not create a GitHub Release, and do not treat the JSON refusal as an advisory. The assertion ran in step 4b as its own process; no shell chain may bridge its nonzero exit into either publication command.
+
+1. **Tag the shipped SHA** (production only; skip on a dev release). The rc tags from step 3 were triggers; **this** tag is the version claim, and it is born here — so **a tag only ever names a revision observed serving production** (principle 10). Re-tagging the same SHA is a resume-safe no-op; a different SHA is refused, and no `--force` exists.
+   ```bash
+   FINAL_TAG=$(node <resolve-release>/scripts/version.mjs tag --version <v> --sha <shipped> \
+     --target-branch <prod> --production-branch <prod> --push)
+   node <resolve-release>/scripts/version.mjs notes --version <v> > release-notes.md
+   gh release create "$FINAL_TAG" --title "$FINAL_TAG" --notes-file release-notes.md
+   ```
+2. **Back-merge `main → dev`** — a **standard step after every production release** where an integration branch exists, done promptly: under principle 11 the step-1b cut commit lives only on the release branch, so `main` now holds a commit `dev` lacks and the *next* promotion cannot fast-forward until this lands. It is a **regular merge into `dev`** (allowed: principle 3 protects the *production* branch, not `dev`). If `dev` moved on, expect conflicts in the two places the cut touched — the CHANGELOG's `Unreleased` region and the version files; resolve mechanically: keep the new version heading from `main`, keep `dev`'s newer entries under a fresh empty `Unreleased` above it, keep the bumped version numbers. If `dev` hasn't moved, it's a fast-forward no-op — do it anyway. **Record the back-merge commit** (`release.backMerge`): the next release's candidate must descend from it (principle 11). (**Skip this action entirely** in the two single-branch topologies — GitHub Flow and `release/<slug>` — where there is no `dev`: under GitHub Flow the cut commit reached `main` by being merged there, so there is nothing to back-merge and `release.backMerge` stays null.)
+3. **Close the originating issue(s)** confirmed in the [pre-flight scope](preflight.md#pre-flight-gate-confirm-the-authorization-envelope-mandatory) — a deliberate step, not a no-op: in a GitFlow repo the PRs merged into `dev`, not the default branch, so GitHub's `Closes #<n>` auto-close **never fired**. Close each with an auditable comment — *why* it's done, not just that it is: `gh issue close <n> --reason completed --comment "Shipped in v<version> (<sha>) via <promotion-pr>; verified live: <evidence>"`.
+4. **Close only on verified-done, never on merge.** A merged-but-unverified PR is not a shipped issue (principle 5), so neither failure tier closes anything — a discarded candidate never shipped, and a rolled-back release was un-shipped.
+
+**Then record the terminal closure as ONE durable transition** ([principle 5](../SKILL.md#non-negotiable-principles); #963) — [`finalize-release.mjs`](../scripts/finalize-release.mjs) validates every observation the released path owes — the checked isolated-adapter completion artifact against finalizer-owned exact suite identities and trusted positive minima, the 4a candidate verdict, the post-authorization fence readings, the serving identity/digest confirmation, the durable-processing quiescence/resume where declared, and the live prod-active verdict — and, in a single atomic manifest write, closes the Release Attempt Lease as `released`/`verified-release` (when it is still open), assembles the top-level `verification` block, and advances `step` to `done`:
+
+```bash
+node <resolve-release>/scripts/finalize-release.mjs <run-manifest.json> \
+  --adapter-completion-artifact <immutable-completion.json> \
+  --adapter-component-head <40-hex-component-head> \
+  --adapter-completion-sha256 <64-hex-sha256>
+```
+
+Completion acquisition retains `O_NOFOLLOW | O_NONBLOCK`, read-only regular <=1 MiB, stable identity, exact bounded read with growth probe, fatal UTF-8, SHA-256 binding, and descriptor cleanup. Zero or caller-weakened counts/floors and unsupported suite identities fail closed. Any observation missing, stale, mismatched, or internally inconsistent **refuses and writes nothing** — a refusal is a statement about the evidence, never a partial record. Re-running after success re-validates and no-ops; a crash before or after the write resumes from exactly one recorded state (`verify` with no `verification`, or `done` with it), and a hand-assembled in-between refuses. Until this lands, either the lease stays **held** or the step sits short of `done` — both correct: an unverified or crashed attempt must not read as free, and a verified one must not read as mid-machine (the Forex v0.1.12 hole: attempt closed `released`, `step: verify`, no `verification` — the post-mortem faulted a release production had already verified). The close the finalizer records is what lets the next release's step-3 `check-release-lease` return free. **The final tag, the GitHub Release above, and the bundle emit/attach below stay outside this filesystem transaction** — the finalizer is the manifest's terminal record, not the release's outward claims. And **`report.mjs` runs after this transition on the released path**: its step-5 evidence is the finalization record, so an unfinalized released attempt renders as owed, never as done.
+
+**Run the verified closeout command before any final response.** It is the required released-path sequence: it invokes `finalize-release.mjs`, assembles the released bundle from the finalized manifest plus the machine-readable build and approval receipts, emits it, validates the emitted durable file, copies that validated file to the aggregate bundle path, and saves both run-level and version-level post-mortems. It prints a success response only after every step passes; any failure exits nonzero, so do not report the release as complete.
+
+```bash
+node <resolve-release>/scripts/closeout-release.mjs \
+  --manifest <run-manifest.json> \
+  --adapter-completion-artifact <immutable-completion.json> \
+  --adapter-component-head <40-hex-component-head> \
+  --adapter-completion-sha256 <64-hex-sha256> \
+  --build-identity <machine-generated-build-identity.json> \
+  --approval <machine-generated-exposure-approval.json> \
+  --aggregate-bundle <release-evidence.json> \
+  --postmortem-dir <postmortem-dir>
+```
+
+`--build-identity` and `--approval` are observed receipts, not prose copied into a bundle. When durable processing was declared, add `--durable-processing <canonical-durable-processing-receipts.json>` before `--aggregate-bundle`; when declared absent, the command writes `{present:false}`. The command writes `<durable-evidence-dir>/<attempt-id>--released.json`; `--aggregate-bundle` is a byte-for-byte copy of that file for the release attachment. **Do not substitute a shell chain or a hand-written `release-evidence.json` for this command.**
+
+**Then attach the validated aggregate bundle to the GitHub Release** — `terminalState: "released"`, `closedBy: "verified-release"`, carrying both principle-5 verdicts, the approval, the traffic transition, and the candidate receipt. The Release is its long-term home (co-located with the version claim it evidences):
+```bash
+gh release upload v<v> <release-evidence.json>   # aggregate copy made by closeout-release.mjs
+```
+The upload targets the `released` bundle specifically — never a bare `<attempt-id>.json`. The bundle is keyed by `(attempt id, terminal state)`, so an attempt that parked at `blocked-manual` and then recovered has *two* bundles under this id; attaching `<attempt-id>--released.json` puts the verified-release evidence on the Release, not the stale hold.
+
+**Candidate failed validation** (step 4a **DEAD** — the gate ran and the candidate failed it; traffic never moved) → set `step: "discard"` (its own value precisely so a resume cannot mistake it for a production rollback), then **check the traffic split before deleting anything**:
+
+```bash
+gcloud run services describe <svc> --region <r> \
+  --format='value(status.traffic.percent,status.traffic.revisionName)'
+```
+
+**The candidate must be at 0% before you delete it.** This ordering is the whole safeguard, not a formality: the `candidate` tag URL keeps resolving after a traffic shift, so a resumed session can re-run 4a against a revision that is now serving *every user*, get a DEAD, and arrive here — where deleting it takes production down. If the candidate holds any traffic, you are in the post-exposure tier; stop and route below. Only once it reads 0% is deletion free, because no request can reach it.
+
+Then delete by **revision name** (never by the `candidate` tag, which moves), and confirm afterwards that the previously serving revision still holds 100%. **That confirmation is the verified candidate cleanup that closes the lease as `failed-pre-promotion`** ([principle 7](../SKILL.md#non-negotiable-principles)) — a failed build/validation on its own does *not* close it (that is the workflow-failure the lease refuses); only the verified cleanup does. Close and emit through one command, never as two manually remembered operations:
+```bash
+node <resolve-release>/scripts/close-attempt.mjs <run-manifest.json> \
+  --bundle release-evidence.json --dir <durable-evidence-dir> \
+  --state failed-pre-promotion \
+  --evidence "candidate revision deleted; incumbent confirmed at 100%"
+```
+For a candidate-validation failure, the bundle carries the candidate receipt, the 4a verdict that stopped it (DEAD/EMPTY/cannot-run), and the cleanup disposition. It owes **no** live verdict or traffic transition (nothing was exposed). For a failure **before any candidate existed**, it instead carries the attempt id, SHA, build identity and verified disposition; its derived `failurePhase: "pre-candidate"` forbids candidate and exposure observations. In either case `close-attempt.mjs` refuses an incomplete or contradictory bundle before writing the terminal manifest close, and the emitted top-level artifact is indexed by attempt id for `version-postmortem.mjs` and `rc-circuit-breaker.mjs`.
+Then hand the captured evidence to `app-debug`/`diagnose` and file a **normal issue**, not an incident — nothing was un-shipped because nothing shipped. **Leave the originating issue(s) open.** The fix returns through `resolve-issues` and re-enters this loop at **step 0** — a code fix means a new SHA, so it needs a fresh candidate, a fresh promotion, and the assembly gates again. Note what does *not* change: the **version is reused**, and the new SHA takes the **next rc number** (principle 10 — no tag carrying a promise was ever created, so nothing is burned). Re-cut the version only if the fix changes the computed bump.
+
+**A step-4a CANNOT-RUN or BLOCKED verdict is not a DEAD candidate.** It means the gate itself could not produce a verdict (e.g. a smoke secret resolved to its resource-name string, not its value, producing 401/403). Do **not** delete the candidate on it; the candidate was never judged. Instead, **repair the gate** (fix the secret/config, restore the credential, repair the fixture/driver) and **re-run 4a against the same 0%-traffic candidate**. Only after a repaired gate returns DEAD does the pre-exposure discard above apply. If the gate cannot be restored, the release stops with the candidate unvalidated and the lease stays held until the repair lands through the normal PR lane; the evidence bundle records the gate as the defect, not the build.
+
+Resist inflating this into an outage. It is the pipeline working as designed, and treating a caught bug as an incident teaches people to route around the gate.
+
+**Failure after a pause but before traffic shifts** (durable processing declared, and the attempt ended at 4b: the quiescence bound elapsed, the quiescence proof could not run, the fence failed, or the human declined) → **nothing was exposed, and production is nevertheless not intact: its processing is stopped.** Unwind in reverse, proving *before* each step rather than reporting after it:
+
+Mechanize the proof and reverse unwind as one typed operation:
+
+```bash
+node <resolve-release>/scripts/durable-processing.mjs unwind-pre-shift \
+  --declaration <repository-release-declaration.json> \
+  --incumbent-revision <release.previousRevision> \
+  --candidate-revision <release.candidateRevision> \
+  --generation <shift-fence-generation> --fence <shift-fence> \
+  > durable-processing-unwind.json
+```
+
+Only `state: "unwound"` licenses candidate discard. `ambiguous` stops and pages.
+
+1. **Prove the previous revision still serves** — `release.previousRevision` at exactly 100% and the candidate at 0%, read from the platform with the same flattened traffic read the fence uses. Resuming processing hands live durable work to whatever revision is serving, so **which** revision that is has to be established, not inferred from "we never issued a shift". A shift can have been issued and failed; a resumed session may not know which.
+2. **Then resume in the reverse of the declared pause order** — worker scheduling first, database admission last — **against that revision**, confirming each resume rather than issuing it.
+3. **Only then treat the candidate.** It is at 0%, so the ordinary discard above applies unchanged, and this stays the routine, no-incident case (principle 6) — precisely *because* production was left described and intact, which is what the ordering buys.
+
+If step 1 cannot establish which revision serves, this is not the path: that is the ambiguous state, so **stop and page** ([principle 14](../SKILL.md#non-negotiable-principles)) rather than resuming processing into a revision nobody has identified.
+
+**Verification failed after exposure** (traffic shifted, then production went unhealthy) → execute the **confirmed rollback policy** (principle 6, post-exposure tier): restore production, confirm restoration with the same smoke, file the **incident** issue with the captured evidence, and hand diagnosis to `app-debug`/`diagnose`. **The confirmed restoration is the verified rollback that closes the lease as `rolled-back`** ([principle 7](../SKILL.md#non-negotiable-principles)) — the proof that the previous revision serves 100% again, not the fact that a rollback command was issued:
+```bash
+node <resolve-issues>/scripts/run-state.mjs record-release-attempt <run-slug> \
+  '{"state":"rolled-back","closedBy":"verified-rollback","evidence":"<previous revision restored to 100%; smoke ALIVE against live service>"}'
+```
+Then **emit the evidence bundle** — `terminalState: "rolled-back"`, `closedBy: "verified-rollback"`, carrying the traffic transition, the live verdict that went unhealthy, and the rollback disposition (previous revision restored to 100%, smoke ALIVE). **Leave the originating issue(s) open** and cross-link the incident — the work was un-shipped, so it is not done. The fix returns through `resolve-issues` and a fresh release; this loop never retries on prod.
+
+**When floor smoke cannot go ALIVE after a correct restore** (identity-v0.4.1 / #800) — traffic and attestation prove the previous revision is back at 100%, but the read-only `prod-active` smoke against the **public host** stays DEAD for a reason that also fails the incumbent (edge inject, CSP, env gate). Do **not** invent a lease state and do **not** claim the candidate code is bad. Classify with the pure helper, then close with an explicit smoke marker and a **required** incident. The `--traffic` JSON must carry a concrete `attestation` object (revision and/or sourceSha/resource, or `verified:true`) — percents alone fail closed as `attestation-missing`:
+```bash
+node <resolve-release>/scripts/rollback-floor.mjs payload \
+  --traffic '{"previousRevision":"<rev>","previousPercent":100,"candidatePercent":0,"attestation":{"revision":"<rev>"}}' \
+  --smoke '{"verdict":"DEAD","profile":"prod-active","floorAlsoDead":true,"reason":"<pre-existing gate>"}' \
+  --incident '{"number":<n>,"url":"<issue-url>"}'
+# → {state:"rolled-back", closedBy:"verified-rollback", smoke:"blocked-by-preexisting-gate", ...}
+node <resolve-issues>/scripts/run-state.mjs record-release-attempt <run-slug> "$(…payload…)"
+```
+`smoke: blocked-by-preexisting-gate` is still `closedBy: verified-rollback` — the lease closes on the verified traffic+attestation restore, and the marker says the golden-path smoke could not prove ALIVE because the **floor** fails the same check. Without `traffic.attestation`, the payload path fails closed (`attestation-missing`) rather than emitting a close that claims attestation was verified. Without `floorAlsoDead` evidence, a DEAD after restore is **not** this path: stop and page. Without a filed incident, the close is incomplete. Regression: identity#677 (CF Insights vs app CSP).
+
+**A `blocked-manual` hold and revocation** ([principle 7](../SKILL.md#non-negotiable-principles)) cover the two states these three exits do not. When an attempt stalls on something only an operator can clear — a rotated credential, an ambiguous state that paged (step 4b) — record `blocked-manual` with the `reason`; it **holds the lease** until the operator records recovery (`recovery.operator` + `recovery.evidence`), never reading as free in the meantime. When an in-flight attempt is deliberately abandoned without shipping — a superseding release, a withdrawn change — record `revoked` with `tagDisposition:"retained"`: revocation revokes the *attempt*, never the tag ([principle 10](../SKILL.md#non-negotiable-principles) — the rc tag is immutable). Neither is `workflow-*` closing the lease; both are recorded, verified transitions. **Each emits a bundle too** — `terminalState: "blocked-manual"` (carrying the `reason` and no close cause, since it holds the lease) or `terminalState: "revoked"` (carrying `tagDisposition: "retained"`) — so these two exits are as durably evidenced as the three above. The bundle is keyed by `(attempt id, terminal state)` (`<attemptId>--<state>.json`), so a `blocked-manual` hold that later recovers and closes `released` on the *same* attempt writes a second, distinct bundle rather than colliding with the first — the immutability guarantee holds per `(id, state)`, and no new rc is minted for a recovery (principle 10). A `revoked` attempt's id remains the key its bundle is indexed by, and — having abandoned without shipping — its bundle must carry no `liveVerdict`/`trafficTransition` (a `blocked-manual` hold parked at 4b *may*, since it can be post-shift).
+
+**Where durable processing was declared, the rollback is ordered too, and the order inverts the intuitive one: traffic first, processing second** ([principle 14](../SKILL.md#non-negotiable-principles)). Roll traffic back to `release.previousRevision`; **prove the restoration** — that revision at exactly 100%, and the read-only `prod-active` smoke profile ALIVE against the live service; and **only then** restore worker scheduling and database admission, in the reverse of the declared pause order and **against that restored revision**. Restoring processing first hands the durable queue back to the revision you have just judged unfit, on state the incumbent will then have to live with — the two-versions-on-one-state failure principle 14 exists to prevent, re-created by the recovery itself. And an ambiguous traffic or restoration state at any point stops and pages rather than proceeding: a rollback executed against a state nobody can read is how an ordinary bad release becomes a data incident.
+
+After traffic and smoke prove the incumbent restored, run `durable-processing.mjs up` against
+that incumbent and the last proven generation/fence. Its status receipt must itself observe the
+named revision at exactly 100%, with `--serving-revision <release.previousRevision>`,
+`--incumbent-revision <release.previousRevision>`, and
+`--candidate-revision <release.candidateRevision>`; the repository job enforces
+scheduling-before-admission. A split, unknown third revision, missing release identity, invalid
+total, or stale generation/fence stops before either resume.
+
+Every terminal bundle records the durable path under canonical `durableProcessing`:
+`{present:false}` for a decided stateless target, or `{present:true, preflight, down, up}` /
+`{present:true, preflight, down, unwind}` using writer-stamped sequence receipts.
+`evidence-bundle.mjs validate` rejects a boolean/prose claim, a missing preflight or sequence
+receipt, a nonzero blocker proof, a missing generation/fence, the wrong reverse order, or an
+absent serving revision. Thus the terminal record cannot preserve traffic evidence while
+dropping whether processing was safely restored.
+
+- **The version, on either failure.** Under the rc scheme the final tag is minted only at step 5, after verification — so on **both** failure paths no version claim was ever published and the retry **reuses the version**. A version is burned only in the legacy shape where the pipeline fires on the *final* tag (pre-flight item 5); there the tag is already on the remote, so it is never moved, deleted, or reused, no Release is published, the retry takes the **next patch**, and the stranded CHANGELOG entry is annotated in the commit that cuts the next version rather than erased — the file is append-only, and deleting the entry destroys the only public record the version existed: `node <resolve-release>/scripts/version.mjs withdraw --version <v> --incident <#n>`.

package/skills/engineering/resolve-release/references/verified-sha-github-flow.md

@@ -0,0 +1,285 @@
+# Verified-SHA GitHub Flow mode contract
+
+This reference defines an **opt-in release mode** for repositories that use
+GitHub Flow and want a release to preserve an already eligible `main` commit as
+the exact release identity. It is self-contained: an operator or reviewer can
+determine the required release ordering from this file without a checkout of
+another repository.
+
+The mode is derived from a consumer product repo's ADR 0034, "Separate validation
+gates from smoke targets in GitHub Flow", at merge
+`2420a0910487c87c4e6458f7203925cde0b54eff`.
+
+## Authority and selection
+
+Call this mode **`verified-sha-github-flow`**. It applies only when the human
+selects it in the pre-flight authorization envelope for a single-branch GitHub
+Flow release. Selection is per release; adopting GitHub Flow does not select
+this mode implicitly.
+
+When selected, this reference is authoritative over the general GitHub Flow
+prose in `resolve-release` for these deliberate differences:
+
+- tag the already-merged selected `main` SHA directly, with no release branch,
+  promotion PR, promotion merge, rebase, or retargeting when `main` advances;
+- create no pre-deployment CHANGELOG or package-version commit; and
+- synchronize release metadata through the post-release adapter only after the
+  final release claim exists.
+
+The general `resolve-release` doctrine still governs authorization, read-only
+production validation, candidate identity, validation-before-exposure,
+rollback, and evidence wherever this reference does not vary it. If this mode
+is not selected, every existing topology, trigger shape, versioning path, and
+release mode keeps its current behavior by default.
+
+This reference defines decision, identity, ordering, durable-state, and resume
+boundaries needed by the mode. It does not absorb the implementation ownership
+of adjacent release-lane issues #431 through #442: deployment receipts, smoke
+profiles, workflow identities, Cloud Build polling, traffic controls,
+concurrency mechanisms, cleanup jobs, and metadata-PR mechanics remain with
+their owning contracts and producers. Their implementations may supply this
+mode's evidence, but may not weaken the invariants below.
+
+## Terms
+
+- **Eligible `main` SHA**: an exact commit that is on `main` and has a green
+  Trunk Integration Verdict for that exact SHA. Branch greenness, a verdict for
+  another SHA, and an unverified commit at the current tip are not eligibility.
+- **Production floor**: the exact commit currently verified as active in
+  production and named by the current final Release Tag. It is an observed
+  deployment boundary, not merely the highest SemVer string.
+- **Selected SHA**: the eligible `main` SHA the human authorizes for the next
+  normal release.
+- **Proposed version**: the `MAJOR.MINOR.PATCH` value computed from the release
+  content between the production floor and selected SHA and confirmed by the
+  human before the first attempt tag is created.
+- **Release Attempt Tag**: an immutable tag
+  `vMAJOR.MINOR.PATCH-rc.N`. It pins one Release Attempt to one selected SHA and
+  is the only tag class in this mode that may trigger production deployment.
+- **Release Attempt**: the durable record joining the proposed version, attempt
+  number, immutable attempt tag and SHA, workflow/check identity, candidate
+  receipt, validation evidence, traffic evidence, and terminal outcome.
+- **Nonterminal Release Attempt**: an attempt whose lease is still held because
+  release, verified zero-traffic cleanup, verified rollback, or verified
+  revocation cleanup has not completed. `blocked-manual` remains nonterminal
+  for single-flight purposes even if its workflow has stopped.
+- **Final Release Tag**: the immutable `vMAJOR.MINOR.PATCH` tag created on the
+  selected SHA only after that SHA is verified at `prod/active`. It records a
+  release; it never requests a deployment.
+- **Post-release metadata adapter**: the deterministic process that opens a
+  normal PR against current `main` after the final claim, adding the released
+  CHANGELOG section and synchronizing package version metadata while preserving
+  newer unreleased work.
+
+## Candidate selection and the production floor
+
+Candidate discovery returns eligible SHAs on `main`, ordered newest first. The
+newest eligible SHA is the default selection. The human may explicitly confirm
+an earlier SHA, but only when that exact commit is still eligible and is a
+strict descendant of the production floor.
+
+A normal release therefore requires both of these ancestry checks immediately
+before `rc.1` is created:
+
+1. the selected SHA is reachable from current `main`; and
+2. the production floor is an ancestor of, and not equal to, the selected SHA.
+
+Equal or older code is never assigned a higher normal-release version. A request
+to return production to the floor or one of its ancestors routes to the
+explicit rollback procedure, with its own authorization and evidence; it does
+not create a new Release Attempt or reinterpret rollback as a normal release.
+Missing or ambiguous production-floor evidence refuses selection.
+
+## Version confirmation and the immutable pin
+
+Compute SemVer from the content that would actually release: changes after the
+production floor through the selected SHA. Present the bump, its reason, and
+the proposed version to the human. Human confirmation is required before
+creating `vMAJOR.MINOR.PATCH-rc.1`; neither a green verdict nor the general
+release authorization silently accepts the version.
+
+Creating the first Release Attempt Tag pins both the selected SHA and proposed
+version. After that point:
+
+- advancing `main` does not retarget, rebase, cancel, or invalidate the attempt;
+- later `main` commits do not enter this release unless the current attempt
+  reaches a terminal outcome and a new candidate is explicitly selected;
+- the attempt tag is never moved, deleted, reused, or force-written — and the push that publishes it is a tag-ref push (`refs/tags/*` with hook-safe `--no-verify`), never a Mergify stack push (identity-v0.4.1); and
+- every retry of this proposed version uses the next unused immutable rc number.
+
+A failed attempt does not burn the proposed version because no final Release
+Tag exists. After the attempt reaches a verified terminal outcome, a retry may
+pin the same SHA or a newly selected eligible SHA, but it keeps the confirmed
+version and takes `rc.N+1`. Recompute and reconfirm only when the release content
+changes the required SemVer bump. Attempt numbers are monotonic for the
+proposed version; gaps or an ambiguous next number fail closed rather than
+reusing a tag.
+
+## Single flight and revocation
+
+Before creating any Release Attempt Tag, prove from durable repository and
+workflow state that there is no nonterminal Release Attempt for production.
+Exactly one lease-holding attempt is allowed. A second or ambiguous attempt is
+refused; it is not queued by cancelling, replacing, or mutating the first
+attempt or its tag. Workflow completion, failure, timeout, and cancellation do
+not by themselves release the lease.
+
+Newly discovered risk may revoke an attempt only through an explicit,
+human-authorized revocation transition recorded against that attempt. Revocation
+never moves or deletes its Release Attempt Tag and never creates a final tag. A
+revocation before exposure verifies and removes only the recorded 0%-traffic
+candidate, then proves the prior production revision still serves 100%.
+Revocation after exposure uses the authorized one-hop rollback and verifies the
+restored revision. Only that verified cleanup or restoration makes `revoked` a
+terminal outcome; ambiguous traffic or cleanup state becomes `blocked-manual`
+and continues to hold the lease.
+
+## Final claim and metadata ordering
+
+The final claim has a strict order:
+
+1. read the selected attempt's pinned SHA and candidate identity from durable
+   state;
+2. verify `prod/active` is serving that exact SHA and the recorded revision and
+   image identity at 100% traffic, with the required active smoke verdict;
+3. create the immutable Final Release Tag on that exact SHA;
+4. create the GitHub Release for that tag and attach or link the verified
+   attempt evidence; and
+5. invoke the post-release metadata adapter against current `main`.
+
+A deploy/check success, a preview verdict, an approval, or a traffic-shift
+request is not `prod/active` verification. Missing, stale, mismatched, or
+ambiguous active evidence refuses both final tag and GitHub Release. A rolled
+back, failed, revoked, or `blocked-manual` attempt receives neither.
+
+The final tag pattern must be excluded from every production deployment trigger.
+Only `vMAJOR.MINOR.PATCH-rc.N` requests a deployment in this mode. Creating or
+replaying `vMAJOR.MINOR.PATCH` must therefore be incapable of starting a second
+build, migration, deployment, or traffic shift.
+
+Do not commit a CHANGELOG cut, package-version bump, generated release metadata,
+or release-only identity change before deployment. Such a commit would create
+a different SHA from the green selected SHA and destroy the verified-SHA pin.
+The authoritative release notes are the post-verification GitHub Release.
+
+Afterward, the post-release metadata adapter opens a required PR from the final
+release evidence against current `main`. It deterministically adds the released
+version section to `CHANGELOG.md`, synchronizes package version fields, and
+preserves all commits and unreleased entries that arrived after the selected
+SHA. The PR follows the normal review and merge-queue path. A subsequent
+verified-SHA release is blocked while any existing final tag lacks its merged
+metadata-sync PR; the adapter never rewrites the released SHA or either tag
+class.
+
+**Mechanized:** `node <resolve-release>/scripts/metadata-sync.mjs open
+--manifest <run> --version <v> --sha <shipped> --date <YYYY-MM-DD>
+[--changes <json>] [--package-file <path>]…
+[--lock-file <path> --lock-command <cmd>]` branches off current `main`, cuts
+the CHANGELOG section, bumps declared package files, opens the PR, and records
+`release.metadataPr` on the manifest (`status:"opened"` + number/url + `source:"metadata-sync.mjs"`,
+or `status:"n/a"` with a reason via `metadata-sync.mjs na`). Only entries written by
+`metadata-sync.mjs open|na|migrate` satisfy the gate; a hand-written `release.metadataSync`
+or a `metadataPr` from another source is rejected by `report.mjs`. A released attempt
+without a valid record is incomplete in `report.mjs` and the handoff. Use
+`metadata-sync.mjs migrate` to convert a legacy `release.metadataSync` record under
+adapter control. Regression: identity-v0.4.1 shipped without the adapter; metadata
+landed as identity#678 (and the v0.5.0 skyee cut used a hand-rolled PR recorded as
+`metadataSync`, so the completeness gate never saw it — #821).
+
+### Isolated metadata synchronization
+
+`metadata-sync.mjs open` fetches current `main`, creates a disposable detached
+worktree, and consumes only `version.mjs changelog --dry-run --format json` with
+the validated CHANGELOG bytes on stdin. Before planning or staging, every declared
+CHANGELOG, package, lock, and file-form `--changes` path is validated as normalized
+and relative. Existing paths must be single-link regular files reached through
+contained real parents; symlinks, hardlinks, non-regular entries, escaping parents,
+and identity changes during descriptor validation fail closed.
+
+Package metadata is supported only as JSON `version` or TOML `[project]` /
+`[tool.poetry]` version data (#960, forex-v0.1.12). A requested package that is
+missing, unparseable, or unsupported makes `plan`, dry-run `open`, and live
+`open` fail. A missing CHANGELOG is the only declared metadata path created by the
+plan. Planned bytes are written as Git blobs and staged directly in the disposable
+index; the caller workspace is never checked out, stashed, cleaned, staged, committed,
+or used as a metadata write target.
+
+The staged index is materialized into a second private execution tree. A declared lock
+moves only through its paired repository `--lock-command` (for example, `uv lock`)
+in that tree. For an npm root lockfile, declare
+`--lock-file package-lock.json --lock-command "npm install --package-lock-only"`; its
+top-level and root-package metadata must identify the package and hold the target
+version. Every requested package and the lock's root entry must hold the target version
+before commit. Ordinary commit hooks then run in the same private tree. After commit,
+the adapter verifies both private disk and committed blobs,
+so a hook that rewrites either disk or staged content fails before push, PR creation,
+or manifest recording. Push is ordinary; only output identifying the known Mergify
+pre-push hook receives one `--no-verify` retry. Any unrelated local or remote failure
+stops without retry.
+
+An existing local branch, remote branch, manifest record, commit, or PR is adopted only
+when repository, base, branch, version, shipped SHA, expected content, message, parent,
+and exact head commit agree. Divergence or ambiguity refuses without force. A failed
+unpublished push preserves the exact commit on its local branch ref and cleans the
+disposable trees. On every success or failure the caller branch, HEAD, index, tracked,
+staged, unstaged, and untracked bytes remain exact; the manifest therefore must live
+outside the caller repository.
+
+After `watch-pr-delivery.mjs` reaches a terminal result, run `metadata-sync.mjs
+record-delivery --manifest <run> --watch-result <json>`. A watcher
+`outcome:"MERGED"` is necessary but not sufficient: the adapter independently
+re-reads the exact PR, fetches fresh `main`, proves metadata commit to merge commit
+to fresh-main ancestry, and verifies every expected merged file hash before recording
+`release.metadataPr.status="merged"` through the canonical state contract.
+
+## Fail-closed state and resume boundaries
+
+Persist state before and after every outward action. At minimum the durable
+record must make these boundaries distinguishable:
+
+1. mode selection, production floor, eligible set, selected SHA, ancestry
+   result, computed bump, human version confirmation, and single-flight proof;
+2. intent to create an attempt tag, followed by the observed immutable tag name,
+   tag SHA, attempt number, and workflow/check identity;
+3. candidate receipt at 0%, exact candidate identity, previous 100%-traffic
+   revision, and preview verdict/freshness;
+4. authorization or revocation intent, followed by a fresh identity/traffic
+   fence immediately before mutation;
+5. observed post-mutation traffic, `prod/active` verification or verified
+   cleanup/rollback, and terminal outcome; and
+6. final-tag intent and observation, GitHub Release identity, metadata-adapter
+   invocation, PR identity, and merged result.
+
+On resume, observe immutable tags, workflows/checks, candidate identity, and
+live traffic before acting; never infer that an outward action did or did not
+happen from the last local step alone. Reconcile every observation with the
+pinned attempt. Missing state, malformed evidence, multiple matches, a SHA or
+identity mismatch, stale evidence, an impossible transition, or an uncertain
+outward-action result fails closed. Preserve the attempt lease and route to
+`blocked-manual` when safety cannot be proved. Resume must be idempotent: it
+may observe an existing correct artifact, but may not create a second attempt,
+repeat a traffic mutation, reuse an rc number, or create a final claim early.
+
+## Required implementation test matrix
+
+The #428 implementation producer must prove these as behavioral tests at the
+state/adapter boundary. These are future implementation obligations, not prose
+checks for this contract-only slice:
+
+| Case | Required outcome |
+|---|---|
+| Newest candidate | Candidate discovery defaults to the newest eligible green `main` SHA. |
+| Earlier candidate | A human-confirmed earlier eligible SHA strictly above the production floor is accepted and pinned exactly. |
+| Production floor | A SHA equal to or older than the production floor, or an unknown/ambiguous floor, is refused and the equal/older request routes to rollback. |
+| Moving `main` | New commits after rc creation neither retarget nor cancel the pinned attempt and are absent from its release identity. |
+| Retry numbering | A terminal failed attempt reuses the confirmed version at the next unused immutable rc number; same-number reuse, movement, deletion, and ambiguity are refused. |
+| Single flight | A second attempt is refused while any attempt is nonterminal, including `blocked-manual`; workflow termination alone does not release the lease. |
+| Revocation | Explicit revocation preserves the rc tag, creates no final tag, and becomes terminal only after verified zero-traffic cleanup or verified rollback. |
+| Final tag after verification | Final tag and GitHub Release are impossible before matching `prod/active` verification and name the exact verified SHA afterward; the final tag cannot trigger deployment. |
+| Metadata ordering | No pre-deploy metadata commit changes the selected SHA; successful finalization invokes a deterministic metadata-sync PR that preserves newer `main` work. |
+| Resume boundaries | A crash on either side of every outward action resumes by observation, is idempotent, and refuses missing, stale, mismatched, duplicate, or ambiguous state. |
+
+The durable tests added by this contract slice may check only structural facts:
+that this reference exists, is reachable from `SKILL.md`, and exposes its named
+contract anchor. Regex vocabulary checks do not prove these prose invariants
+and must not be presented as semantic coverage.