@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/resolve-release/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: resolve-release
+description: "Slash/explicit-only (/resolve-release). Full GitHub Flow release from main: freeze the latest CI-green trunk SHA, write the changelog, choose SemVer, merge the metadata cut through a verified PR, publish npm artifacts, or validate a Cloud Run candidate at 0% and expose it fully or as a canary. Asks its choices once at preflight (exposure full|canary, dark launch on|off, project-flow questions), follows a release flow (a predefined flow shipped with the skill, or the project's .release/flow.md extending one), then runs unattended. /rush-release is its no-questions shortcut. Do not auto-select. Use only on explicit user/orchestrator invoke. NOT for GitFlow/release-branch promotion and NOT for implementing a spec (resolve-issues)."
+disable-model-invocation: true
+metadata:
+  workflow-role: coordinator
+release-version: 0.36.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Resolve release
+
+Cut a **GitHub Flow** release from **main**. Freeze one already-green trunk
+SHA, write a metadata-only version cut on that parent, merge it through a
+verified PR, and publish. When the human explicitly approved keeping an unused
+final version after a failed RC, the cut stage can instead verify already-merged
+prepared metadata without writing another cut. A tag-driven repository tags the
+verified release source; a package-scoped dispatcher owns its own tags. For Cloud Run, validate one
+candidate at 0% and expose it **fully** (0% -> 100%) or as a **canary**
+(0% -> declared steps -> 100%). With **dark launch** on, features that ship
+behind a default-off flag are listed in the plan and must still read off after
+the release.
+
+The skeleton below is fixed. What varies is chosen once at preflight or read
+from the project's stored flow; after preflight the run asks nothing.
+
+```text
+preflight (main + publisher + release flow)
+  -> choices: exposure, dark launch, flow questions  (full mode asks; shortcut never does)
+  -> latest CI-green HEAD on main
+  -> changelog + SemVer plan (show as a record, write the receipt)
+  -> create + deliver metadata cut OR verify human-approved prepared metadata
+  -> root-tag npm: final tag -> watch publish
+  -> workspace npm: dispatch each package -> verify registry, provenance, tag
+  -> Cloud Run: rc tag -> candidate at 0% -> validate -> full or canary exposure
+     -> verify live (+ dark flags off) -> final tag
+```
+
+This file is the workflow and index. Read the linked procedure immediately
+before its stage; do not invent an unlinked substitute.
+
+| Stage / concern | Procedure |
+|---|---|
+| Trunk, publisher, version files, choices | [references/preflight.md](references/preflight.md) |
+| Release flows: predefined (`flows/`), project (`.release/flow.md`), `extends` | [references/flows.md](references/flows.md) |
+| Independently versioned npm workspaces with a package-scoped dispatch publisher | [references/workspace-npm.md](references/workspace-npm.md) |
+| Latest CI-green HEAD | [references/candidate.md](references/candidate.md) |
+| Changelog, SemVer, file bump, commit | [references/cut.md](references/cut.md) |
+| Human-approved reuse after a failed RC (no new metadata cut) | [references/prepared-metadata.md](references/prepared-metadata.md) |
+| Tag, push, watch publisher | [references/publish.md](references/publish.md) |
+| Cloud Run 0% -> 100%, verification, rollback | [references/promotion.md](references/promotion.md) |
+| Canary exposure (0% -> steps -> 100%) | [references/canary.md](references/canary.md) |
+| Dark launch (flags ship off, stay off) | [references/dark-launch.md](references/dark-launch.md) |
+
+Run every script as
+`node <skillsRoot>/resolve-release/scripts/<name>.mjs …` with the absolute skill
+root this file was loaded from. A CWD-relative `scripts/…` path resolves in the
+target repo and will not find these files.
+
+## Modes
+
+| | Full mode (`/resolve-release`) | Shortcut mode (`/rush-release`) |
+|---|---|---|
+| Exposure | `full` or `canary` | always `full` |
+| Dark launch | `on` or `off` | always `off` |
+| Release flow | project flow, else `--flow <name>`, else none | same, with exposure full and dark off |
+| Questions | once, at preflight, only for unresolved choices | none, ever |
+
+Precedence for every choice: **invocation option > release flow > preflight
+answer**. Full-mode options: `--exposure full|canary`, `--canary-steps 10,50`,
+`--hold-minutes N`, `--dark on|off`, `--save-flow`; both modes accept
+`--flow <predefined>` when the project has no flow of its own. Shortcut mode accepts none of
+these; it refuses and points to `/resolve-release` when one is passed, when the
+flow's `required` lists canary or dark, or when a flow question has no default.
+
+## Run invariants
+
+- Trunk is `main`. Another default branch is a different workflow.
+- The candidate is the newest SHA on `main` with green CI evidence for its
+  exact tree — not "the tip looks fine" and not a commit that is still pending.
+- For an approved `metadata.mode: reuse-prepared` plan, the new frozen CI-green
+  main SHA is the RC/final source. Historical metadata cut/merge SHAs remain
+  separate provenance. Follow [prepared-metadata.md](references/prepared-metadata.md)
+  for mandatory provider/review/notes verification, a fresh distinct receipt and
+  no metadata-write permissions; never reuse the failed attempt's authority.
+- For a newly created cut, its parent is that frozen SHA. Do not rebase, merge, or cherry-pick
+  later `main` onto the cut branch; the provider merge is a separate identity.
+- Never publish an off-main cut. Use the configured queue when one exists;
+  otherwise require the repository's PR checks and permitted merge method.
+  Verify its exact merged SHA is reachable from `origin/main` and its Git tree
+  equals the approved cut tree (for reused metadata, require historical cut/merge
+  equality and the new source gates in `prepared-metadata.md`). Any post-freeze trunk content requires a new
+  plan; an unconfigured queue is not release evidence.
+- Tags are immutable release identities: `vMAJOR.MINOR.PATCH` for root-tag
+  releases, or package-scoped names when the publisher owns tagging. Do not
+  move, delete, or force-push a remote tag.
+- A Cloud Run release uses one immutable `vMAJOR.MINOR.PATCH-rc.N` tag to build
+  the candidate at 0%. The final tag is created only after that exact candidate
+  serves 100% and passes live verification; it must not trigger another deploy.
+- Questions happen only in full mode's preflight choice step, and only for
+  choices (exposure, canary steps and hold, dark launch, flow `ask:` items) —
+  never for detected facts, never for authorization. The invocation plus those
+  answers authorizes the listed branch/commit, metadata PR delivery, candidate
+  build, conditional traffic shifts, rollback, final tag, optional GitHub
+  Release, and publisher watch as one operation. Show the complete plan before
+  the first mutation so the user can interrupt, then proceed. Do not ask cut,
+  merge, RC, exposure-step, tag, finalization, or publish questions, and do not
+  ask "shall I proceed".
+- Before the first mutation, write `.git/<invoked-skill>-authorization.json`
+  (`rush-release-authorization.json` or `resolve-release-authorization.json`;
+  prepared-metadata reuse instead exclusively creates a fresh receipt at the
+  distinct path in [prepared-metadata.md](references/prepared-metadata.md)).
+  Bind the repository, SHA, version, tags, mode, separate mutations, gate
+  coordinates, freshness, the invocation time as the authorization time, expiry,
+  and permission status; record `authorizedBy: invocation`. Full mode also
+  records `choices` (with their sources), and any run with a release flow
+  records `flowSha256`; a normal-cut shortcut run without a flow writes exactly the
+  original receipt. Resume and callbacks act only on the receipt's exact plan.
+  Never store secrets or reconstruct the plan from chat.
+- Preflight facts are detected, not confirmed by the user. Every non-choice has
+  a deterministic default (SemVer from conventional commits, the derived
+  changelog, every changed package); a value the user stated at invocation wins.
+  If the plan's frozen SHA, version/tag, metadata diff, publisher, choices, or
+  outward actions later change, record one replacement plan, show it, and
+  continue under the same invocation. Hand back only when no valid plan exists,
+  never to ask permission.
+- On callback or resume, re-read the receipt, provider evidence, live
+  coordinates, and the release flow's hash. Exact matches become `executable`,
+  then `consumed` immediately before mutation. Otherwise record `invalidated` or
+  `failed` and do nothing. Never infer one permission from another or replay a
+  consumed permission.
+- A pre-exposure failure is a hand-back with production untouched. A known
+  post-exposure failure (including a dark flag found on) automatically restores
+  and verifies the recorded incumbent. Ambiguous production state is a stop for
+  operator recovery.
+- The cut is metadata only (changelog + version identity files). Refuse a
+  cut that changes product code.
+- Turning a flag on is never part of a release. A release flow can fill slots
+  and add steps; it cannot change this skeleton, these invariants, or the
+  manual-only invocation of either mode.
+
+## Workflow
+
+### 1. Preflight and choices
+
+Load and validate the release flow, verify `main` is the trunk, detect npm
+and/or the staged Cloud Run contract, and identify whether version/publish
+authority is at the root or per workspace. Then resolve the choices with
+`flow.mjs resolve`: full mode asks the returned questions once, shortcut mode
+takes the preset and refuses what it cannot answer. Details:
+[preflight.md](references/preflight.md), [flows.md](references/flows.md).
+
+For a package-scoped dispatch publisher, follow [workspace-npm.md](references/workspace-npm.md)
+from candidate selection through final verification. Do not run the root-tag
+candidate/plan/apply scripts on a private monorepo root or synthesize a `v*`
+tag for a workflow that publishes only by package dispatch.
+
+### 2. Candidate (root-tag / Cloud Run)
+
+Fetch `origin/main` and pick the newest green SHA. Freeze it. Details:
+[candidate.md](references/candidate.md).
+
+### 3. Plan and record (root-tag / Cloud Run)
+
+Derive the changelog and SemVer bump from `baselineTag..frozenSHA`, unless the
+human explicitly approved the prepared-metadata route. That route passes
+`--prepared-metadata <file>`, preserves the unused version with `bump: none`, and
+reads notes from the reviewed new target, not from the old attempt. For Cloud
+Run, pass `--cloud-run` so the plan also identifies the next unused RC tag. With
+dark launch on for a new cut, pass the listed flags with `--dark-flags`; reuse
+instead verifies the notes already reviewed in the target
+([dark-launch.md](references/dark-launch.md)). Show SHA, bump, version, tags,
+files, publisher, choices, notes, and every outward action, write the receipt,
+and proceed. Details: [cut.md](references/cut.md).
+
+### 4. Cut (root-tag / Cloud Run)
+
+Choose one route. For a normal cut, run the flow's `before-cut` steps, then
+branch from the frozen SHA, apply the changelog and version files, and commit;
+keep the diff metadata-only. For `reuse-prepared`, perform all mandatory
+[prepared-metadata.md](references/prepared-metadata.md) checks and output its
+verified source and evidence bindings without `apply`, metadata writes, cut
+hooks or a new PR.
+
+### 5. Merge and publish (root-tag / Cloud Run)
+
+Push the cut ref, merge its PR using the repository's delivery policy, and
+verify the exact merged SHA on `main`. The verified-prepared route skips that
+new PR delivery and converges here using its new frozen target as the release
+source, not its historical metadata merge. A root-tag artifact release pushes the
+final tag and watches npm. A v2 `pre-tag` npm reuse attempt has no RC and must
+first pass the fresh read-only registry-absence and final-ref gates described in
+[publish.md](references/publish.md#node-pre-tag-registry-gate). This does not
+recover an artifact attempt whose immutable final tag already exists.
+A staged Cloud Run release pushes its RC tag, executes
+[promotion.md](references/promotion.md) (with [canary.md](references/canary.md)
+for canary exposure), and creates the final tag only after live verification.
+Details: [publish.md](references/publish.md).
+
+## Done
+
+Success is the planned version tagged at the verified release source on `main`
+(the newly frozen target for reuse) and
+visible on the remote. npm must report the version when selected. Cloud Run
+must report the exact candidate serving 100%, the incumbent at 0%, an ALIVE
+`prod-active` verdict, and — with dark launch on — every dark flag reading off.
+Hand back the cut SHA, merged SHA, RC/final tags, changelog excerpt, choices,
+publisher and traffic evidence, and the merged metadata PR. For reuse also
+hand back the new release source, both notes digests, historical metadata
+identities, fresh receipt path and mandatory verification outputs. With `--save-flow`,
+open the flow PR after the release ([flows.md](references/flows.md)).
+On final handoff, close the run in the harness: mark the goal complete
+(`update_goal` with `complete`), which also releases the workflow, whether the
+release is done or hands back a blocker; never pause it for a reply. A blocker's
+handoff names what failed, its evidence, and what a rerun needs; a later
+invocation picks it up.

package/skills/engineering/resolve-release/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Resolve Release"
+  short_description: "Slash/explicit-only GitHub Flow release: full or canary exposure, dark launch, project flow"
+
+policy:
+  # Codex counterpart to SKILL.md disable-model-invocation: true.
+  # Keeps $resolve-release / explicit invoke while blocking description-based selection.
+  allow_implicit_invocation: false

package/skills/engineering/resolve-release/flows/cloud-run-canary.md

@@ -0,0 +1,13 @@
+---
+description: Cloud Run service built from an RC tag at 0% traffic, validated, then exposed through canary steps before 100%
+route: cloud-run
+exposure: canary
+canary:
+  steps: [10, 50]
+  holdMinutes: 15
+---
+
+# Cloud Run release (canary exposure)
+
+A project extending this flow sets `canary.healthCheck` to its read-only
+command that judges each hold; without it the canary is refused.

package/skills/engineering/resolve-release/flows/cloud-run.md

@@ -0,0 +1,7 @@
+---
+description: Cloud Run service built from an RC tag at 0% traffic, validated, then shifted to 100% in one step
+route: cloud-run
+exposure: full
+---
+
+# Cloud Run release (full exposure)

package/skills/engineering/resolve-release/flows/root-tag-npm.md

@@ -0,0 +1,13 @@
+---
+description: One version for the repository, published by pushing a vX.Y.Z tag (for example a single npm package)
+route: root-tag
+exposure: n/a
+---
+
+# Root-tag npm release
+
+## before-cut
+- run the repository's documented verify command on the frozen SHA
+
+## after-publish
+- `npm view <package>@<version> version` prints the planned version

package/skills/engineering/resolve-release/flows/workspace-npm.md

@@ -0,0 +1,22 @@
+---
+description: Independently versioned npm workspaces, published one package at a time by a package-scoped dispatch workflow that owns its tags
+route: workspace-npm
+changelog: package-scoped
+registry: https://registry.npmjs.org/
+exposure: n/a
+---
+
+# Workspace npm release
+
+A project extending this flow names its `publisher` (workflow and package input)
+and any `packages` to exclude or publish last.
+
+## before-cut
+- run the repository's documented verify command on the frozen SHA
+- `npm publish --dry-run -w <workspace> --registry=<registry>` for each selected package
+
+## after-publish
+- `npm view <package> version --registry=<registry>` prints the planned version
+
+## hand-back-if
+- a selected package has never been published on npm (a trusted-publishing first publish needs a human npm login)

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

@@ -0,0 +1,51 @@
+# Canary exposure
+
+> Read when: exposure is `canary` and the Cloud Run candidate has passed its 0% validation in [promotion.md](promotion.md).
+
+A canary moves a slice of real traffic to the candidate, holds, judges it, and
+widens, before the final 100% shift. It replaces only the single shift in
+[promotion.md](promotion.md) section 3; binding, 0% validation, live
+verification, and failure routing are unchanged. Full mode only — the shortcut
+never runs this.
+
+## Preconditions
+
+Preflight recorded, from the repository and never improvised:
+
+- `steps`: strictly increasing percentages below 100 (for example `10, 50`);
+- `holdMinutes`: how long each step holds before it is judged;
+- `healthCheck`: a read-only repository command that judges a hold, run against
+  the live service with the candidate serving that step's share;
+- the exact command that splits traffic between the candidate revision and the
+  recorded incumbent by percentage, per service, in dependency order.
+
+A missing item is a refusal at preflight, before anything is tagged.
+
+## Sequence
+
+For each step `p` in order:
+
+1. Re-read candidate identity and traffic. Require the candidate at the
+   previous step's share (0% for the first) and the incumbent holding the rest;
+   anything else is ambiguous state.
+2. Consume that step's traffic-shift permission, then split every affected
+   service to candidate `p%` / incumbent `(100-p)%` in dependency order. Read
+   traffic back after each command.
+3. Hold `holdMinutes` with one background wait — no foreground polling.
+4. Run `healthCheck`. Require a passing, read-only result stamped for this
+   step. Record step, share, start/end, and the verdict.
+
+After the last step passes, perform the full 100% shift exactly as
+[promotion.md](promotion.md) section 3 describes, then section 4's live
+verification. Only that state permits the final tag.
+
+## Failure
+
+- A failed split or health check at any step is a known post-exposure failure:
+  restore every service to its recorded incumbent at 100% in reverse dependency
+  order, restore durable processing, and verify incumbent 100%, candidate 0%,
+  and `prod-active` ALIVE before hand-back.
+- A traffic reading that matches neither the planned step nor the incumbent is
+  ambiguous: stop all writes and hand back the last known-good evidence.
+- Never skip a step, lengthen or shorten a hold, retry a failed step, or widen
+  past a failed judgment. A new attempt is a new plan with a new RC tag.

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

@@ -0,0 +1,41 @@
+# Candidate
+
+> Read when: picking the SHA to freeze; how CI evidence is checked per exact tree and why a pending tip is never a candidate.
+
+This picker is for root-tag and staged Cloud Run releases. For independently
+versioned npm workspaces with a package-scoped dispatcher, use the exact-tree
+PR-CI candidate gate in [workspace-npm.md](workspace-npm.md); a PR-only CI
+repository need not have checks on the merge commit itself.
+
+The release candidate is the newest commit that is on `main` and already green.
+The current tip is eligible only when that exact SHA is green.
+
+## Procedure
+
+1. Fetch `origin/main`.
+2. Walk first-parent history of `origin/main`, newest first.
+3. Run the picker:
+
+```bash
+node <skillsRoot>/resolve-release/scripts/green-head.mjs --trunk main --json
+```
+
+4. Freeze `candidateSha` from the JSON. Do not keep walking after a green SHA
+   in the hope of a "nicer" commit.
+5. If the script exits 1 (`no-green-head`), stop. Repair CI or wait; do not
+   release a pending or failed SHA, and do not treat "no checks configured" as
+   green.
+
+## Why freeze
+
+`main` keeps moving. The changelog, the bump, and the tag all describe one
+commit. If a later commit lands while you write notes, including it would ship
+code that never passed this candidate check.
+
+The frozen SHA is normally the **parent of the cut**, not yet the tag. Version
+files still need a metadata commit on top; that child is what gets tagged
+([cut.md](cut.md)). For explicitly approved prepared-metadata reuse, this newly
+frozen SHA is instead the release source itself: the metadata is already in
+its reviewed tree. All exact-tree CI/main gates still apply; old cut/merge/RC
+identities are provenance, never substitutes for this target's green evidence
+([prepared-metadata.md](prepared-metadata.md)).

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

@@ -0,0 +1,131 @@
+# Cut
+
+> Read when: turning the frozen SHA into the plan record and the metadata-only version commit (root-tag and Cloud Run routes).
+
+This root-tag cut does not bump independently versioned npm workspaces. For
+package-scoped dispatch publishing, use [workspace-npm.md](workspace-npm.md).
+
+Turn the frozen SHA into a versioned commit without taking later trunk commits
+along for the ride. The cut stage has two routes: the normal create-and-deliver
+procedure below, or, only with explicit human keep-version/reuse approval,
+[verify already-prepared metadata](prepared-metadata.md). A `metadata.mode:
+reuse-prepared` plan follows that reference's mandatory checks and fresh receipt
+rules instead of section 3: no `apply`, new metadata commit, empty PR or cut
+write permissions. Both routes converge on the existing publish stage.
+
+## 1. Plan
+
+```bash
+node <skillsRoot>/resolve-release/scripts/plan.mjs --sha <candidateSha> --json \
+  > /tmp/release-plan.json
+# Add --cloud-run when preflight selected cloud-run-staged.
+# Add --dark-flags <list.json> when dark launch is on (dark-launch.md).
+```
+
+The plan names `baselineTag`, `currentVersion`, `bump`, `reason`,
+`nextVersion`, final `tag`, optional `candidateTag`, `changelogMarkdown`, and
+`versionFiles`; with dark launch on, also `darkFlags` and a `### Shipped dark`
+changelog section. Without `--dark-flags` the plan is byte-for-byte what the
+shortcut has always produced.
+
+For approved reuse, add `--prepared-metadata <file>` with the versioned schema
+in [prepared-metadata.md](prepared-metadata.md). Its `--sha` is the newly frozen
+CI-green main target; its `bump` is `none`. The notes are read and digested from
+that target's reviewed version section, never rendered as a new cut. Its
+historical notes digest and cut/merge/previous-attempt identities remain
+separate. Local planner success does not establish provider CI or PR status.
+
+Before showing the plan, use `git ls-remote --tags origin` to prove the proposed
+candidate and final tags are both unused remotely. Local tag discovery chooses
+the next RC ordinal; remote absence is the collision authority.
+
+SemVer (0.x treats breaking as minor unless the invocation asks for strict):
+
+| Content since baseline | Bump |
+|---|---|
+| breaking (`feat!:`, `BREAKING CHANGE:`) | major (minor under 0.x) |
+| `feat:` | minor |
+| otherwise | patch |
+
+Changelog entries come from conventional-commit subjects in
+`baselineTag..candidateSha` (or the recent first-parent log when there is no
+tag). Keep an existing `## [Unreleased]` body — derived entries merge with it,
+they do not replace it.
+
+## 2. Record the plan
+
+Show the frozen SHA, proposed version/tag(s), bump reason, changelog, version
+files, publisher/deployment mode, and the complete outward-action sequence: create the cut
+branch/commit, push it, deliver its metadata PR through the queue, push the
+immutable tag(s), validate and conditionally promote Cloud Run when applicable,
+create a GitHub Release when required, and watch the publisher. Full mode also
+shows the resolved choices (exposure, canary steps and hold, dark launch and its
+flags, flow answers), and any run with a release flow shows its steps per stage.
+This is a record, not a question: the invocation (plus full mode's preflight
+answers) already authorized the entire sequence. Do not ask whether to proceed.
+Every non-choice has a deterministic default: the bump from the table above,
+the derived changelog merged with `## [Unreleased]`, the next unused tags. A
+bump or notes the user stated at invocation win, as long as the bump is still
+SemVer.
+
+Do not create a branch, edit files, or tag before the plan is shown and the
+receipt below is written; after that, proceed through publication without
+asking cut, merge, RC, exposure, tag, finalization, or publish questions.
+Repository/provider checks are gates the orchestrator evaluates, not reasons to
+ask the human to confirm facts. When the frozen SHA, version/tag, metadata
+diff, publisher, or outward actions change, replace the whole plan, show the
+replacement, and continue under the same invocation. A retry or resume of the
+unchanged plan inherits the original receipt.
+
+For reuse, show only the applicable action sequence: verify prepared metadata
+and the new source, publish, and promote if applicable. Show both notes digests,
+new source, historical provenance and previous receipt digest; do not list cut
+writes or PR delivery as permissions. Follow the distinct exclusive receipt
+path and required stage outputs in [prepared-metadata.md](prepared-metadata.md),
+not the normal fixed-path receipt below. Never read or reset the old receipt.
+
+Before the first mutation, write `.git/<invoked-skill>-authorization.json` with
+`authorizedBy: invocation` and the invocation time as the authorization time.
+Record the plan coordinates, predicates, expiry, and separate candidate,
+traffic-shift, rollback, final-tag, and GitHub Release permissions. A canary
+records one traffic-shift permission per step. Full mode adds `choices` and
+their `sources`; a run with a release flow adds `flowSha256`.
+Start each permission as `pending-conditions`. Add later coordinates only from
+the named provider evidence; once added, they are immutable. Plan drift
+invalidates the receipt. Store no secrets, callback URLs, or protected data.
+
+## 3. Apply and commit
+
+Branch from the frozen SHA only:
+
+```bash
+git switch -c release/<tag> <candidateSha>
+jq -r '.changelogMarkdown' /tmp/release-plan.json | \
+  node <skillsRoot>/resolve-release/scripts/apply.mjs \
+    --version <nextVersion> --date <YYYY-MM-DD> \
+    --changelog-section - --json
+git add -- <paths from apply>
+git commit -m "chore(release): <nextVersion>"
+```
+
+`apply.mjs` requires the recorded plan's `changelogMarkdown` on stdin, writes
+that section, and bumps the discovered identity files. It refuses a missing or
+empty changelog section rather than silently replacing the plan with a bare
+version heading. When the plan names `skills/distribution/manifest.json`, it
+delegates to `distribution.mjs version-cut`; that operation updates the repository
+release identity, stamps it and the generated release checker into every active
+first-party skill, and regenerates deterministic artifacts. If any step fails it
+restores every touched file.
+If the invocation supplied notes, write that markdown to stdin instead of the
+raw plan field.
+
+Then:
+
+- Diff must be metadata only. If product code changed, reset and stop.
+- `git rev-parse HEAD^` must equal the frozen SHA.
+- Do not rebase onto a newer `main`, merge `main` in, or squash onto a moved
+  tip. Any of those would tag commits this candidate check never saw.
+
+The cut SHA is `HEAD` after the commit. It is the immutable PR-head identity;
+the release identity is the provider's verified merged SHA on `main`.
+Proceed to [publish.md](publish.md).

package/skills/engineering/resolve-release/references/dark-launch.md

@@ -0,0 +1,66 @@
+# Dark launch
+
+> Read when: dark launch is `on` — listing the flags that ship off in this release, adding them to the plan and changelog, and proving they are still off after it.
+
+Dark launch separates **shipping code** from **exposing behavior**: a new
+feature merges behind a feature flag whose default is off, the release puts
+the code live, and turning the flag on is a later, separate decision. A release
+never turns a flag on. Full mode only — the shortcut runs with dark launch off.
+
+## Flag registry
+
+The repository declares one registry file (JSON or YAML), named by the flow's
+`flagRegistry` or `--flag-registry`:
+
+```json
+{ "flags": { "bulk-refunds": { "default": false, "description": "Bulk refunds" } } }
+```
+
+Every flag has a `default`. Off means `false`, `0`, `"off"`, `"false"`, or
+`"disabled"`. The repository also documents a read-only command that reports
+each flag's **live** value in production (Cloud Run); without it, the live check
+cannot run and dark launch is refused at preflight for Cloud Run.
+
+## 1. List the flags shipping dark
+
+```bash
+node <skillsRoot>/resolve-release/scripts/dark-flags.mjs list \
+  --registry <path> --base <baselineTag> --sha <candidateSha> --json > /tmp/dark-flags.json
+```
+
+A flag ships dark when it is in the registry at the candidate but not at the
+baseline, or when a commit in the range carries a `Dark-Launch: <flag>`
+trailer. Exit 1 — a trailer naming an unregistered flag, or a dark flag whose
+default is not off — is a pre-cut hand-back: the release would expose
+behavior it claims to hide.
+
+## 2. Plan and changelog
+
+Pass the list to the plan:
+
+```bash
+node <skillsRoot>/resolve-release/scripts/plan.mjs --sha <candidateSha> --json \
+  --dark-flags /tmp/dark-flags.json [--cloud-run] > /tmp/release-plan.json
+```
+
+The plan gains `darkFlags` and a `### Shipped dark` changelog section, one line
+per flag. The SemVer bump is unchanged: the code did ship. Show the flags in the
+plan record and record them in the receipt.
+
+## 3. Verify they stayed off
+
+After the release is live (Cloud Run: in [promotion.md](promotion.md)'s live
+verification, before the final tag), read each flag's live value with the
+repository command into `{ "<flag>": <value> }`, then:
+
+```bash
+node <skillsRoot>/resolve-release/scripts/dark-flags.mjs check \
+  --flags /tmp/dark-flags.json --observed /tmp/dark-flags-live.json
+```
+
+A flag that is on, or has no reading, is a failed live check: roll back per
+[promotion.md](promotion.md) section 5 and hand back. Do not turn the flag off
+yourself — that is an operator decision outside the release.
+
+For npm routes there is no live service; step 1's default-off check is the
+proof, and the published package carries the registry as shipped.