@1aboveio/skills 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,150 @@
+# Release flows
+
+> Read when: choosing a predefined flow, the target repository has `.release/flow.md`, a run was invoked with `--flow` or `--save-flow`, or a flow failed validation.
+
+A release flow records how a repository varies the release, so a run follows it
+without rediscovering or re-asking it. It fills slots of the fixed skeleton in
+[../SKILL.md](../SKILL.md). It cannot add, remove, or reorder stages, relax a
+run invariant, or change either skill's manual-only invocation.
+
+## Predefined flows (shipped with this skill)
+
+The skill ships templates in `flows/`. List them with:
+
+```bash
+node <skillsRoot>/resolve-release/scripts/flow.mjs list
+```
+
+| Flow | For |
+|---|---|
+| `root-tag-npm` | one repository version, published by pushing `vX.Y.Z` |
+| `workspace-npm` | independently versioned npm workspaces, package-scoped dispatch publisher |
+| `cloud-run` | Cloud Run candidate at 0%, validated, shifted to 100% in one step |
+| `cloud-run-canary` | Cloud Run candidate at 0%, validated, exposed through canary steps (10%, 50%; 15-minute holds) |
+
+A predefined flow carries only what is true for every repository of its kind.
+Repository facts — publisher workflow names, package names, the canary health
+check — come from the project.
+
+## Which flow a run uses
+
+1. **The project's `.release/flow.md`**, when present. It usually starts from a
+   predefined flow with `extends: <name>` and adds only its own slots and steps.
+2. Otherwise **`--flow <name>`** at invocation: that predefined flow as is.
+3. Otherwise **no flow**: preflight detection alone, exactly as before flows
+   existed. A predefined flow is never picked by guessing.
+
+`--flow` with a project flow present is a hand-back: the project flow wins, and
+choosing a different base is an edit to its `extends`. Both modes accept
+`--flow`.
+
+## File format
+
+YAML frontmatter of **settings**, then optional `##` sections of **steps**.
+Text before the first `##` is free prose. Validate the effective flow with:
+
+```bash
+node <skillsRoot>/resolve-release/scripts/flow.mjs validate [--flow <name>] --json
+```
+
+Validation rejects unknown settings, unknown sections, skeleton or invocation
+keys (`trunk`, `releaseBranch`, `stages`, `skip`, `confirm`,
+`disable-model-invocation`, …), an unknown `extends`, a predefined flow that
+extends another, and inconsistent values in the merged flow. An invalid flow is
+a hand-back; never run against it.
+
+## Settings (slots)
+
+| Setting | Values | Fills |
+|---|---|---|
+| `extends` | a predefined flow name (project flows only) | the base this flow starts from |
+| `description` | text | what the flow is for |
+| `route` | `root-tag` · `workspace-npm` · `cloud-run` | the release type preflight must find |
+| `publisher` | mapping of scalars, e.g. `workflow`, `input`, `ownsTags` | the publisher and its inputs |
+| `packages` | `exclude: [...]`, `publishLast: [...]` (workspace-npm only) | package set and dispatch order |
+| `changelog` | `root` · `package-scoped` | heading format |
+| `registry` | `https://…` | `--registry` for every npm command |
+| `ask` | list of `{ id, question, options?, default? }` | extra preflight choices |
+| `exposure` | `full` · `canary` · `n/a` | default exposure (`n/a`: no traffic to split) |
+| `canary` | `{ steps: [10, 50], holdMinutes: 15, healthCheck: <cmd> }` | canary plan (cloud-run only) |
+| `dark` | `on` · `off` · `n/a` | default dark launch |
+| `flagRegistry` | repository path | flag registry for dark launch |
+| `required` | `[canary]`, `[dark]` | choices the shortcut must not override |
+
+When a project extends a predefined flow, its settings override the base;
+`publisher`, `packages`, and `canary` merge key by key; `ask` items merge by
+`id`. A slot pins a fact the run would otherwise infer; the pinned value is
+still verified against the tree and provider. A flow that names a publisher the
+repository does not have is a refusal, not an override.
+
+## Steps
+
+Sections, each a list of `- ` steps (repository commands or checks, in order).
+With `extends`, the base flow's steps at a point run first, then the project's.
+
+| Section | Runs | A failure is |
+|---|---|---|
+| `before-cut` | before the cut commit | a hand-back, nothing changed remotely |
+| `after-merge` | after the merged `main` SHA is verified | a hand-back, nothing published or exposed |
+| `before-exposure` | before the first traffic shift | pre-exposure: production untouched |
+| `after-publish` | after each artifact's registry proof | a hand-back naming what already shipped |
+| `after-live` | after live verification, before the final tag | a failed live check: automatic rollback |
+| `hand-back-if` | conditions, checked at preflight and before each outward action | a stop before that action |
+
+Run only commands the repository documents; a step never authorizes an action
+the skeleton does not already contain (no extra deploys, tag moves, or flag
+flips).
+
+## Choices and precedence
+
+Invocation option > flow > preflight answer. Full mode asks only what is still
+unresolved, plus every `ask:` item not answered by the invocation. Shortcut
+mode (`/rush-release`) asks nothing: exposure `full`, dark `off`, each `ask:`
+item takes its `default`; `required` canary/dark, or an `ask:` item with no
+default, is a refusal that points to `/resolve-release`.
+
+## Identity
+
+Record the effective flow's `sha256` (it covers the predefined base and the
+project file) in the plan and receipt. On resume, a different hash invalidates
+the receipt: a run never continues under a flow it did not show — including one
+whose base changed in a skills update.
+
+## Saving a flow
+
+`--save-flow` (full mode) writes the **project** file: `extends` for the base in
+use, the project's own slots and steps, and this run's exposure, canary, dark,
+and flag-registry choices. Base slots and steps stay in the skill; per-release
+`ask:` answers are not saved:
+
+```bash
+node <skillsRoot>/resolve-release/scripts/flow.mjs resolve --mode full --json … > /tmp/release-choices.json
+node <skillsRoot>/resolve-release/scripts/flow.mjs render [--flow <name>] < /tmp/release-choices.json > .release/flow.md
+```
+
+Write it only after the release finishes, on its own branch from the new
+`main`, and open a separate PR. It is never part of the metadata cut.
+
+## Example: extending `workspace-npm`
+
+```markdown
+---
+extends: workspace-npm
+publisher: { workflow: publish.yml, input: package, ownsTags: true }
+packages:
+  exclude: [pi-better-read-aloud, navigator, sandbox-core]
+  publishLast: [pi-better-harness]
+ask:
+  - id: bundle-bump
+    question: Should pi-better-harness bundle the new component versions?
+    options: [yes, no]
+---
+
+## after-publish
+- `pi install npm:<pkg>` succeeds
+```
+
+The base supplies the route, package-scoped changelog, registry, verify and
+pack dry-run steps, the `npm view` proof, and the first-publish hand-back. With
+this flow, `/rush-release` refuses (the `bundle-bump` question has no default)
+and `/resolve-release` asks it once at preflight.

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

@@ -0,0 +1,154 @@
+# Preflight
+
+> Read when: starting a run; loading the release flow, detecting trunk, publisher, deployment mode, and the files that carry the version, then resolving the release choices.
+
+Preflight outputs trunk `main`, publishers, deployment mode, release commands,
+the files that carry the version, the release flow, and the resolved choices. It
+does not pick the SHA, bump the version, or push. Resolve **facts** from
+repository and provider state without asking the human to confirm any of them.
+A non-choice that cannot be inferred takes its deterministic default in
+[cut.md](cut.md), or the value the user stated at invocation; never a preflight
+question. Only the **choices** in section 5 are ever asked, and only in full mode.
+
+## 0. Release flow
+
+```bash
+node <skillsRoot>/resolve-release/scripts/flow.mjs validate [--flow <name>] --json
+```
+
+The effective flow is the project's `.release/flow.md` (merged with the
+predefined flow it `extends`), else the predefined flow named by `--flow`.
+Neither is normal: continue with detection alone, and never pick a predefined
+flow by guessing. An invalid flow
+is a hand-back naming each error; never run a release against a flow that
+failed validation or guess what it meant. A valid flow's slots pin what the
+sections below would otherwise infer, and are still verified against the
+repository: a `route` or `publisher` the tree does not support is a refusal.
+Record its `sha256`. Details: [flows.md](flows.md).
+
+## 1. Trunk
+
+Fetch `origin/main` and all remote tags. Verify the release trunk is `main` from those fetched refs
+(`origin/main` exists). A repo whose production branch is `master` or `release`
+is not this workflow.
+
+## 2. Publisher
+
+Detect how a tag becomes a shipped artifact. Prefer what the human named;
+otherwise look at the tree:
+
+Before treating a root `package.json` as the release identity, inspect its
+`private` and `workspaces` fields, the workspaces' versions and exact bundle
+pins, and the publish workflow's parsed triggers and package inputs. If the
+root is private, packages are independently versioned, and a package-scoped
+`workflow_dispatch` publishes them from their manifests, select the
+**workspace npm** route in [workspace-npm.md](workspace-npm.md). A dispatcher
+is not a tag-triggered publisher: do not infer one from the presence of npm or
+`publishConfig`. If the package input, publish order, or tag ownership is
+unclear, stop rather than cut a private root tag. This route handles its own
+candidate, versions, plan record, cut, merge, and publish gates.
+
+| Signal | Publisher |
+|---|---|
+| Cloud Build production trigger matching only `v*-rc.*`, whose prod path emits immutable candidate coordinates after `--no-traffic` | `cloudbuild`, mode `cloud-run-staged` |
+| public root `package.json` with a tag/release-triggered publish workflow, `publishConfig`, or an explicit root npm release | `npm` |
+| both | watch both |
+| neither, and the human did not name one | refuse — nothing to watch |
+
+Cloud Build presence alone is not a staged contract. For `cloud-run-staged`,
+verify from repository policy and live trigger configuration:
+
+- the production trigger matches RC tags and excludes the final `vX.Y.Z` tag;
+- each affected service deploys an immutable revision with `--no-traffic` and
+  publishes one receipt binding RC tag, merged SHA, revision, image digest, and
+  candidate URL;
+- `golden-paths.json` defines read-only `prod-preview` and `prod-active`
+  profiles with at least one eligible path;
+- exact inspect, traffic-shift, rollback, and candidate-delete commands are
+  documented, including service dependency order;
+- any durable processing affected by a shift has exact pause, quiescence,
+  resume, and restoration checks;
+- for canary exposure only: an exact command that splits traffic between the
+  candidate and the incumbent by percentage, and a read-only health check to
+  judge each hold ([canary.md](canary.md)).
+
+Refuse staged release when any applicable item is absent; never improvise
+production commands. Record `publisher` as `cloudbuild`, `npm`, or `both` and
+`deploymentMode` as `artifact-only` or `cloud-run-staged`. If a GitHub Actions
+workflow publishes on `release: published` rather than on tag push, note that
+`gh release create` is required at publish time.
+
+## 3. Version files
+
+The root identity list below applies only to root-tag and staged Cloud Run
+releases. Workspace npm uses the selected package manifests, exact bundle pins,
+lockfile, and repository changelog as described in [workspace-npm.md](workspace-npm.md).
+
+First check for `skills/distribution/manifest.json` with an exact `releaseVersion`
+and `skills/distribution/scripts/distribution.mjs`. That manifest is the repository
+release identity when present; record it and use the distribution-aware cut in
+`apply.mjs`. It takes precedence over a private root `package.json` with no version.
+
+Otherwise, list identity files present at the repo root (and only those):
+
+- `package.json` (and `package-lock.json` when it exists)
+- `pyproject.toml`
+- `VERSION`
+
+Do not bump other nested workspace packages unless the human names them. The cut
+must stay metadata-only. A distribution-aware cut may also update trusted runtime
+identity constants, test fixtures that pin that identity, and deterministic generated
+policy/inventory artifacts; those are version metadata, not product behavior.
+
+## 4. Baseline
+
+Read the current version from those files when present. List annotated/lightweight
+release tags matching `vMAJOR.MINOR.PATCH` with no prerelease. The highest such
+tag is the changelog baseline. A prerelease (`v1.2.0-rc.1`) is not a baseline.
+
+## Prepared-metadata reuse
+
+Only an explicit human keep-version/reuse instruction selects this route; a
+failed RC or an input file does not. Record the instruction and the supplied
+`prepared-release-metadata/v1` RC provenance, or v2's explicit `pre-tag` /
+`cloudRunRC` provenance. A v2 `pre-tag` input requires artifact-only root npm
+publishing, no private/workspace root, and separately verified stopped-before-
+tagging/publication evidence. Record the exact effective registry from the
+existing flow or publisher configuration; if it cannot be established, stop
+rather than guessing or reading credential payloads. Keep the new CI-green
+target separate
+from historical cut/merge identities. No reuse-specific provider verification
+is delegated to local git: the cut stage must establish the mandatory fresh
+PR, main, CI and reviewed-notes bindings in
+[prepared-metadata.md](prepared-metadata.md). Neither this input nor a previous
+attempt grants execution permission. Existing publisher and flow gates apply.
+
+## 5. Choices
+
+Detect the repository hints first: canary support (the Cloud Run contract
+declares percentage-split commands, hold, and a health check) and a flag
+registry. Then resolve:
+
+```bash
+node <skillsRoot>/resolve-release/scripts/flow.mjs resolve --mode <full|shortcut> [--flow <name>] --json \
+  [--exposure …] [--canary-steps …] [--hold-minutes …] [--dark …] \
+  [--health-check <repo-declared cmd>] [--flag-registry <path>] \
+  [--repo-canary] [--repo-flag-registry] [--answer <id>=<value>]…
+# exit 0 resolved · 4 questions pending · 3 refused · 1 invalid flow
+```
+
+- **Shortcut mode** (`/rush-release`) asks nothing: exposure `full`, dark `off`,
+  flow questions answered by their defaults. Exit 3 is a hand-back that points
+  to `/resolve-release`.
+- **Full mode** (`/resolve-release`): exit 4 returns `questions`, each with its
+  options and a suggested default. Ask them together, once, as choices; rerun
+  with `--answer` until exit 0. Canary steps and hold are asked only after
+  canary is chosen. Exit 3 is a hand-back with the refusals.
+
+Precedence is invocation option > release flow > answer. Canary needs the
+repository-declared health check and split commands; dark launch needs a flag
+registry — without them the choice is refused, not improvised. Record the
+resolved `choices` and `sources` in the plan and receipt.
+
+Preflight succeeds when trunk, publisher, version files, baseline, flow, and
+choices are recorded. Proceed to [candidate.md](candidate.md).

package/skills/engineering/resolve-release/references/prepared-metadata.md

@@ -0,0 +1,260 @@
+# Reuse prepared metadata
+
+> Read when: the human explicitly chose to keep an unused final version after a failed RC or a Node/npm attempt stopped before tagging/publication, and approved reusing its already-merged metadata. This is a branch of the existing cut stage, not a release executor or a resume of the failed attempt.
+
+Do not infer consent from a failed RC, a file, a flow default, or a prior receipt.
+Without explicit human approval for reuse, follow the normal create-and-deliver
+cut. This capability does not authorize release execution when the task only
+asked to implement or plan it.
+
+## Input
+
+After preflight and candidate selection, supply this JSON to
+`plan.mjs --sha <full frozen new target SHA> --prepared-metadata <file> --json`
+(add `--cloud-run` for the staged route). The API equivalent is
+`planRelease({ sha, preparedMetadata, ... })`. No version override is added.
+
+V1 retains the existing strict RC provenance below. For a genuine Node/npm
+attempt without an RC, use the explicit v2 `pre-tag` variant described next;
+do not fabricate an RC identity.
+
+```json
+{
+  "schema": "prepared-release-metadata/v1",
+  "repository": "owner/repo",
+  "version": "0.7.0",
+  "metadataPr": 123,
+  "cutSha": "1111111111111111111111111111111111111111",
+  "mergeSha": "2222222222222222222222222222222222222222",
+  "previousAttempt": {
+    "receiptId": "failed-attempt-1",
+    "receiptSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "candidateTag": "v0.7.0-rc.1",
+    "candidateSha": "2222222222222222222222222222222222222222"
+  }
+}
+```
+
+All fields are required; unknown fields refuse. `metadataPr` is a positive PR
+number in `repository`. SHAs are full lowercase 40-hex commit identities;
+`receiptSha256` is a lowercase 64-hex historical digest supplied with the
+previous attempt's provenance, not a path to load. `receiptId` is a safe opaque
+identifier (1-128 ASCII letters, digits, dots, underscores or hyphens, beginning
+with a letter or digit). `version` is canonical `x.y.z`. The previous RC must
+be for that version and its source must equal the historical `mergeSha`.
+
+The new `--sha` is the release source, not the historical cut or merge. Select
+it through the existing exact-tree CI-green main candidate gate. New code and
+reviewed changelog corrections may have landed since the old metadata merge.
+Never pass an arbitrary unreviewed SHA just because it descends from that merge.
+
+## Node/npm Before Tagging
+
+For a publishable root npm package whose prior attempt stopped before final
+tagging or publication, use this v2 input without `--cloud-run`:
+
+```json
+{
+  "schema": "prepared-release-metadata/v2",
+  "repository": "owner/node-package",
+  "version": "1.3.0",
+  "metadataPr": 42,
+  "cutSha": "1111111111111111111111111111111111111111",
+  "mergeSha": "2222222222222222222222222222222222222222",
+  "previousAttempt": {
+    "kind": "pre-tag",
+    "receiptId": "stopped-before-tagging-1",
+    "receiptSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "sourceSha": "3333333333333333333333333333333333333333"
+  }
+}
+```
+
+V2 has exactly two previous-attempt variants. `pre-tag` requires only `kind`,
+`receiptId`, `receiptSha256`, and `sourceSha`. `cloudRunRC` requires only `kind`,
+`receiptId`, `receiptSha256`, `candidateTag`, and `candidateSha`, with the same RC
+binding and ordinal rules as v1. Missing, null, mixed, or unknown fields refuse.
+V1 remains backward compatible; its RC fields are not made optional.
+
+The pre-tag planner resolves the previous full source commit and proves
+`metadata.mergeSha -> previousAttempt.sourceSha -> plan.sha` ancestry; equality
+is allowed. It returns `candidateTag: null` and a named npm artifact, not a
+synthetic RC. Preflight must independently prove artifact-only, root-tag npm
+publishing and the previous failed/canceled attempt's pre-publication state.
+The input's claim alone proves neither failure nor absence of publication.
+
+Require a publishable root `package.json`, not a private or workspace root.
+Bind its package name across the original cut, previous source, and new target.
+When present, `package-lock.json` must use integer format 2 or 3, with top-level
+and `packages[""]` name/version identities matching that root. The supported
+identity-file set remains unchanged. Original-cut scripts, dependency edges,
+resolved versions, integrity values and other non-version metadata cannot
+change; later reviewed code and dependency fixes remain eligible. Node-only
+inspection must not require Python. It requires Node 22+ with JSON parser
+numeric-source support: strict UTF-8 blobs are compared through fully tagged
+JSON trees that retain original numeric tokens before JavaScript rounding.
+Equivalent ordinary decimal/exponent spellings compare exactly, while underflow
+and rounded-fraction changes cannot disappear. Signed zero remains distinct;
+nonzero tokens with explicit exponents outside the safe-integer range require
+identical numeric source text. Nonfinite values and unsafe integer Numbers
+refuse. Input and package/lock versions use canonical safe-integer semantic
+version components, matching the npm gate. Independently versioned workspaces
+remain on their existing dispatcher route, not this capability.
+
+An existing final tag blocks a new-source attempt even if the npm version is
+absent or the tag points at the historical source. An npm publish failure after
+final tagging is not a pre-tag attempt; preserve the tag and use the existing
+failure/resume policy rather than retagging or claiming this route can recover it.
+
+The planner makes no npm or credential calls. Before final tagging, the publish
+stage must separately establish registry-version absence using the bounded
+[read-only npm gate](publish.md#node-pre-tag-registry-gate). Registry and Git
+observations do not reserve names or authorize publication.
+
+## Planner checks and limits
+
+The planner is read-only, apart from its stdout. It proves from real git objects:
+
+- the declared GitHub `origin` identity matches `repository` (canonical HTTPS,
+  SCP-style SSH or `ssh://git@github.com/` URL);
+- the original single-parent cut changes only root version identities and
+  `CHANGELOG.md`, with no package scripts, dependency, lock dependency or other
+  non-version edits hidden in identity files;
+- the cut is an ancestor of its merge and their whole trees are equal;
+- that merge is an ancestor of the new frozen target;
+- the supported root identity file set is unchanged and every version agrees
+  at the historical cut and new target, including the lock's top-level version,
+  `packages[""].version` when present, and package/lock name identity; for Python,
+  the actual project name and exactly one matching uv editable or virtual root
+  at `.` with the requested version;
+- there is one nonempty dated release section for that version at both sources;
+- a successful fresh `git ls-remote --tags origin` inspection proves the exact
+  final tag absent. Remote, local and historical RC ordinals all count as spent.
+  For staged releases, a second exact-ref inspection proves both final and
+  proposed RC tags absent. Errors, timeouts and ambiguous output block.
+
+Supported identity files are root `package.json`, `package-lock.json`, `VERSION`,
+static `[project]` / `[tool.poetry]` versions in `pyproject.toml`, and a root
+`uv.lock` (lock format version 1) belonging to that Python project. TOML is parsed
+structurally, including project name and uv package source; adding a lock filename
+to the metadata paths alone is not proof. The uv root must have the exact project
+name and exactly `source = { editable = "." }` or `source = { virtual = "." }`.
+Missing, duplicate, foreign, mixed, extra-key or non-root sources refuse at the
+parent, cut and target. Both representations prove the same root identity;
+accepting a virtual root does not grant execution authority or change context
+policy. The historical parent may have a stale root version (for example, project
+`0.6.2` with lock root `0.4.0` repaired to `0.7.0` at the cut). Only that identified
+root's version is excluded from the historical lock comparison: every other
+package, dependency edge, requirement, source, hash and lock field must remain
+structurally unchanged, including the root source. Switching between editable
+and virtual across the historical cut refuses even though each shape is valid
+individually. Cut and target root versions must equal the requested
+version. The target must retain the historical prepared project name and exact
+root source mode; a coordinated rename or editable/virtual switch is not part of
+this reuse capability. Reviewed dependency changes after the historical cut are allowed;
+they do not exempt the target from root identity validation.
+
+Python metadata reuse requires `python3` 3.11+ with standard-library `tomllib`
+on `PATH`. Prepared TOML blobs are acquired from Git as raw bytes with a
+five-second timeout and an 8 MiB output limit, then decoded as strict UTF-8 before
+TOML parsing. Invalid octets refuse rather than becoming replacement characters.
+The planner starts only fixed parser code with `-I -S`, passes raw bytes through
+stdin, and bounds each parse to five seconds and 8 MiB of input/output.
+Metadata-only comparison uses a type-tagged tree for every scalar and container;
+integer-to-float changes cannot disappear through JSON serialization, while
+unchanged finite floats remain valid. The uv lock format must be integer `1`, not
+float `1.0`. Missing Python/tomllib, malformed TOML, process errors, non-JSON TOML
+values, nonfinite numbers, integers outside the lossless JSON range and exceeded
+bounds all refuse with sanitized acquisition/parser errors. No Python is invoked
+for npm-only reuse, and normal create-cut planning and application are unchanged.
+
+Identity files must be regular non-executable files. Workspace npm is not this route.
+Distribution-aware cuts (`skills/distribution/manifest.json`) have a wider
+generated metadata surface and refuse reuse until a dedicated verifier exists;
+normal distribution cuts are unchanged. `--dark-flags` refuses in reuse mode:
+notes must already be reviewed in the target, not generated on this path.
+
+The planner does **not** prove GitHub PR state, approval, required checks, CI,
+remote main membership, publisher configuration, old receipt authenticity, or
+execution authorization. A successful local plan is not permission to tag.
+Tag absence is an observation, not a reservation; re-inspect immediately before
+any tag creation. Do not delete or move an old RC even when it failed.
+
+## Mandatory Cut-Stage Verification
+
+The existing cut stage chooses exactly one route: create and deliver new metadata,
+or verify already-prepared metadata. For `metadata.mode: reuse-prepared`, do all
+of the following before publication, and record the named stage output:
+
+1. `preparedMetadataApproval`: record the human's explicit keep-version/reuse
+   instruction and the exact repository, version, new target SHA and plan it
+   covers. Metadata input and `previousAttempt` are provenance, not authorization.
+2. `historicalMetadataVerification`: use fresh provider evidence in the canonical
+   repository to prove `metadataPr` merged into main, its head equals `cutSha`,
+   its merge identity equals `mergeSha`, and it passed the repository's required
+   review/delivery policy. Record provider coordinates and observation time.
+3. `releaseSourceVerification`: fetch main and use the existing candidate/CI
+   gate for the exact new `plan.sha`. Record remote main SHA, ancestry result,
+   required CI/queue run identities, tree/proof binding and freshness. Never
+   substitute green evidence from the old cut, failed RC or another target.
+4. `preparedNotesVerification`: independently extract the version section from
+   the exact reviewed new target and compare it with `plan.changelogMarkdown`
+   and `metadata.preparedSectionSha256`. The canonical section is the heading
+   through just before the next `## [..]` heading, with trailing whitespace
+   removed and one final LF. Verify review/delivery evidence covers that target's
+   notes, including corrections since the old cut. Record the review coordinates,
+   target SHA and digest. `originalSectionSha256` is historical provenance only;
+   it is intentionally separate, not an equality claim for updated notes.
+5. `previousAttemptVerification`: establish the named prior attempt's terminal
+   failed/canceled state and matching repository, source, version and receipt
+   identity/digest from retained or provider evidence. For v2 `pre-tag`, require
+   proof it stopped before final tagging/publication; do not invent an RC or
+   treat an input claim as evidence. Do not reopen or consume the old receipt.
+6. `preparedCutVerification`: rerun the read-only planner checks against the
+   same frozen input and match source, identities, notes digests and tags to the
+   recorded plan (ignore only the newly generated receipt ID and inspection
+   time). Record exact-ref remote absence evidence and time. Any drift blocks;
+   never quietly choose a new target, version or note body.
+
+If evidence cannot establish these facts, hand back the missing gate. Do not
+create an empty metadata PR, run `apply.mjs`, run `before-cut` mutation steps,
+create a branch/commit, or rewrite changelog/version files in the reuse route.
+The current reviewed target already contains the prepared metadata.
+
+## Fresh Receipt and Publish Convergence
+
+The planner supplies a fresh `receiptId` for every reuse plan. The stage writes
+an exclusively created, distinct receipt at
+`.git/<invoked-skill>-<receiptId>-authorization.json`; never overwrite the fixed
+legacy path or another receipt. Bind the complete new plan and its SHA-256,
+`releaseSourceSha` (= `plan.sha`), all stage outputs above, historical cut/merge/PR,
+`previousAttempt.receiptId` and `previousAttempt.receiptSha256`, both notes
+digests, tags, choices, flow hash, invocation authorization, expiry and separate
+permissions. A new plan is not a retry/reset of the old receipt.
+
+Do not read, mutate, reset, copy permissions from, or grant authority through the
+old receipt. Start only this invocation's applicable publish/promotion permissions
+at `pending-conditions`. Omit metadata branch/commit/write/PR-delivery permissions.
+On resume use this new receipt's exact path and plan, with the existing
+executable/consumed checks. Do not fall back to the old fixed receipt path.
+
+Once these checks pass, output `metadataVerification: verified-prepared`,
+`releaseSourceSha: <new target>`, `receiptPath` and the evidence bindings. For the
+existing publish/promotion procedures, bind their operational `<mergedSha>` to
+this verified **new target**. Keep `metadata.mergeSha` as historical provenance;
+never overwrite it or tag it. Skip publish section 1 (new metadata PR) and the
+new-cut tree equality comparison in section 2: historical cut/merge equality
+was already verified, and later reviewed product fixes intentionally change the
+new target's tree. All remaining exact-source CI, main ancestry, tag absence,
+publisher, candidate, preview, traffic and live verification gates still apply.
+Run `after-merge` flow validation on the verified source as usual. For v2
+`pre-tag`, also bind the named npm artifact and explicit effective registry into
+the new receipt. The final-tag permission requires a fresh registry-absence
+observation from the existing publish stage as well as fresh remote tag absence.
+The read-only npm probe itself never grants or consumes a permission.
+
+Both cut routes now converge on the same existing publish and promotion stages.
+For Cloud Run, the next unused RC builds from the new target; after the exact
+candidate serves 100% and passes live verification, the still-unused final tag
+names that same source. Neither historical provenance nor this planner may
+reuse an old candidate, relax a golden path, or trigger any effect by itself.

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

@@ -0,0 +1,82 @@
+# Cloud Run staged promotion
+
+> Read when: a Cloud Run candidate is built at 0% and must be validated, shifted to 100%, verified live, or rolled back.
+
+Promote one immutable candidate from 0% to 100% under the invocation's
+authorization, as recorded in the plan receipt. Load `golden-path` for both validation
+profiles and the applicable platform skill for repository-declared Cloud Run
+commands. Do not restore the archived `resolve-release` state machine or
+introduce a confirmation.
+
+## 1. Bind the candidate
+
+After the RC-tag build reports `SUCCESS`, read its durable candidate receipt.
+For every affected service, independently verify from one fresh Cloud Run
+snapshot that:
+
+- receipt RC tag and source SHA equal the approved plan and `<mergedSha>`;
+- the named immutable revision runs the receipt's image digest;
+- the candidate URL resolves to that revision;
+- the candidate has exactly 0% traffic and the recorded incumbent exactly 100%;
+- no second release or unknown traffic-bearing revision is in flight.
+
+Missing, duplicate, stale, or contradictory identity is a pre-exposure failure.
+Delete the candidate by immutable revision only when the preflight contract
+declared that deletion safe; otherwise leave it at 0% and hand back. Never move
+the RC tag.
+
+## 2. Validate at 0%
+
+Run the repository's smoke workflow against the exact candidate URL with
+`--profile prod-preview`. Accept only a non-empty `ALIVE` verdict whose stamped
+target is that URL, profile is `prod-preview`, and `noMutations` is `true`.
+Record its `generatedAt`. A failed or unavailable gate leaves production on the
+incumbent and does not consume the final tag.
+
+## 3. Recheck and shift
+
+Immediately before exposure, re-read candidate identity and traffic. Require
+the candidate still at 0%, incumbent still at 100%, and the ALIVE verdict still
+within the plan's declared freshness window. If durable processing is affected,
+run the preflight-declared pause order and prove quiescence before traffic moves.
+
+Run the release flow's `before-exposure` steps; a failure there is still
+pre-exposure. With exposure `canary`, the shift below is replaced by the
+stepped sequence in [canary.md](canary.md), which ends at this same 100% state.
+
+Shift all affected services to the candidate in the declared dependency order.
+After each command, read traffic back. If a later service cannot shift, restore
+already-shifted services in reverse order before doing anything else. The
+invocation already authorized this conditional shift and restoration.
+Record traffic-shift and rollback permissions separately. Before either action,
+match its candidate revision/digest, target, profile, gate, and mutation set.
+
+## 4. Verify live
+
+From fresh control-plane and service observations, require for every service:
+
+- the exact candidate revision holds 100% and the incumbent 0%;
+- serving source SHA and image digest equal the candidate receipt;
+- the live URL passes a non-empty, read-only `prod-active` smoke as `ALIVE`;
+- with dark launch on, every planned dark flag reads off in production
+  ([dark-launch.md](dark-launch.md)). A flag found on is a failed live check.
+
+Resume durable processing only against the verified serving candidate, then
+prove scheduling/admission and any required publication advancement are healthy.
+Run the release flow's `after-live` steps; a failure there is a failed live
+check. Only this state permits the final release tag.
+
+## 5. Failure routing
+
+- **Before any traffic moved:** production is untouched. Delete or retain the
+  0% candidate according to the recorded policy and hand back.
+- **After a known failed shift or live check:** automatically restore every
+  service to its recorded incumbent in reverse dependency order, restore
+  durable processing against that incumbent, and verify incumbent 100%,
+  candidate 0%, and `prod-active` ALIVE before hand-back.
+- **Ambiguous traffic, identity, or processing state:** stop all writes and hand
+  back the last known-good evidence for operator recovery. Never guess, retry a
+  shift, delete a revision, or claim rollback succeeded.
+
+The final tag remains unused on every failure path. An RC tag is immutable and
+remains as attempt evidence.