---
name: preparing-releases
description: Use when preparing or verifying an ALNEAS release, handling staged npm approval/completion, or investigating partial publication and Deployment records. Readiness review and partial-publication investigation do not themselves authorize publication.
---

# Preparing ALNEAS Releases

Apply the [release policy](https://tech-docs.alneas.com/policies/release-policy.md) and local `RELEASING.md`. A reviewed local copy is available at `public/policies/release-policy.md`.

When using a reviewed offline snapshot, resolve public `https://tech-docs.alneas.com/` references under `policies/`, `skills/` and `templates/` to the matching repository-root `vendor/alneas-standards/` paths, preserving the remaining path and fragment. Keep skill bytes unchanged and use the recorded snapshot revision; report missing vendored references instead of inventing their content.


## Stop conditions (affected action only)

| If | Then |
| --- | --- |
| Only preparation is authorized | Finish concrete preparation; use existing authorization before any Git/publication writes. |
| A write times out or its result is uncertain | Stop writes; inspect remote identity/state read-only before recovery. |

For repeated unexplained gate failures, missing prerequisites and resumption,
apply the [shared stop conditions](https://tech-docs.alneas.com/policies/development-policy.md#stop-conditions-and-escalation).
Continue independent authorized work and preserve existing session authorization.

## Identify the requested outcome

Read applicable agent instructions, manifests, release scripts and workflow triggers. Record the requested outcome and existing authorization: preparation, commit/tag/push, package registration, GitHub Release or deployment. Include automatic writes caused by a tag/branch push. Proceed with already authorized work; request missing authorization only when needed for the concrete next action.

Establish the actual repository, target names, registry/environment, visibility, package version constraints, toolchain, mandatory gates, artifact locations and authentication mechanism. Use verified local commands. Use the shared Release publication entrypoint while retaining project-specific target selection and stronger gates. Do not transplant a public npm OIDC example into a private registry workflow.

Use `release: types: [published]` for package publication; tag pushes prepare identity without registry writes. Review a draft Release before authorized publication. Require the expected repository, stable published event, Release ID/tag and matching Actions/checkout/tag commit. Transfer verified archives between jobs without rebuilding. Attach results to the original Release and preserve reviewed notes and matching existing assets. Keep public npm first-publication and 2FA/staged-approval requirements. Do not rely on a `GITHUB_TOKEN`-created Release to trigger another workflow; an explicitly authorized dispatch must retain the original candidate identity. Inspect legacy triggers for duplicate writes during migration.

For private packages deploying to GitHub Packages (`npm.pkg.github.com`), follow the payload minimization and size threshold verification rules defined in the [release policy](https://tech-docs.alneas.com/policies/release-policy.md#private-distribution-github-packages-and-minimal-payload-footprint).

If shared references are unavailable, identify any reviewed local revision used. Report missing policy access rather than claiming to have read it. Investigate contradictions between local prose and scripts before the affected release action.

## Select targets and version increments

Compare changed paths with an explicit release baseline using existing workspace/package manifests and build inputs. For independent versions, include accumulated changes since each target's last release. Include deleted/renamed paths using both revisions. Start with the owning packages, then inspect shared configuration/generators/dependencies for their affected outputs.

Documentation and maintainer-only tools normally do not require a package release. Check whether an affected README, consumer metadata, CLI or generated output actually ships and needs delivery to users. Review dependency edges: test compatibility, and separately decide whether a required fix needs a dependent's dependency/version update. A passing compatibility lane does not prove fix delivery.

Record targets, dependency corrections, proposed version increments and reasons in the PR or existing Changeset/release record. Distinguish fix, addition and breaking change under the declared versioning scheme. State why an affected target needs no release. Do not create a new policy profile when existing manifests and review records supply the facts.

## Coordinate public/private delivery

Follow the [coordinated delivery contract](https://tech-docs.alneas.com/policies/release-policy.md#coordinated-publicprivate-delivery).
Within the same task, inspect both sides of the project, prepare necessary
changes and verify affected contracts. Record each side's target/version impact,
required dependency adoption or justified no-release decision in existing records.
Do not omit private consumers because the task began in a public checkout.

Plan dependent stages with their prerequisites, owners and status. Verify a
required public registry publication before adopting its exact version in private
production manifests/lockfiles; run dependent gates before that side's delivery.
Use isolated candidate archives only for early compatibility checks. Keep versions,
tags and publication times independent; coordinated maintenance does not require
simultaneous release or authorize publication. Report incomplete access, adoption
or verification explicitly, keep pending stages tracked in the same task, and
distinguish completed development checks from pending delivery. Keep private
targets, internal links and evidence out of public release records and artifacts.

The [shared paired-maintenance kit](https://tech-docs.alneas.com/templates/paired-maintenance/README.md)
can check revision-bound local evidence in a restricted coordination gate. Its
delivery fields are declarations, not registry/deployment proof. Connect actual
publication/adoption checks and trusted artifact provenance in the owning release
workflow; public CI does not retrieve private receipts.

## Prepare consumer-facing release notes

Follow the [release-note lifecycle](https://tech-docs.alneas.com/policies/release-policy.md#release-notes-and-changelog-lifecycle).

1. Collect reviewed `.changeset/*.md` fragments or the repository's equivalent for
   only the selected targets. Reconcile them with accumulated changes since each
   target's last release; explain any no-release decisions. Prefer Changesets for
   independent JavaScript/TypeScript packages, preserving adequate existing tools
   and non-JavaScript workflows.
2. Use the maintained preparation command after checking its side effects. Review
   version and dependency changes against staged registry prerequisites. Merge the
   selected fragments into each package's cumulative `CHANGELOG.md`, newest first;
   remove only consumed fragments and retain earlier published entries. A prepared
   version heading is not evidence of successful publication.
3. Review additions/fixes, compatibility/security impact and upgrade instructions.
   Keep useful links, avoid raw commit-list dumps and do not fabricate dates. Keep
   one changelog per independent package until actual scale warrants linked archives.
4. Verify the README's visible, npm/GitHub-compatible history link and include the
   changelog in the actual archive; exclude unreleased fragments and operational
   evidence. A README latest-release summary is optional; if present, keep it bound
   to the reviewed release entry without duplicating the full history.
5. Prepare the corresponding GitHub Release body or equivalent notes from that
   same package/version entry. Keep publication-triggering Releases in draft until
   authorized. Record any missing PR/release note checks as an integration gap.
   After authorized publication, confirm delivered notes/links and each target's
   actual published state; handle partial publication without republishing versions.

## Prepare a verifiable candidate

1. Review intended version/dependency changes and release notes under the local versioning contract. Run preparation commands only with their understood side effects; preparation must preserve unrelated edits and does not imply staging or committing them.
2. Complete affected checks and the required gates for the current target/stage. Record clean-install, packed-consumer, browser, documentation and live-evaluation evidence separately where required. If a dependent gate needs a predecessor's registered version, record the staged prerequisite and run that gate before the dependent write. A tooling self-test is not a live evaluation.
3. After the authorized source commit exists, finalize artifacts for that commit. Check target names/versions, packed contents, relevant dependency order, checksums and supporting evidence. An amended commit requires a new commit-bound bundle. If commit authorization is missing, finish working-tree preparation and report the remaining binding step.
4. Retain the exact tested artifacts and manifest/evidence handoff. Validate commit and artifact binding before publication; do not rebuild in the publication stage. Recheck required source retrieval and disclosure/notices for included material.

### Reuse completed source verification

Validate the authoritative quality run for the exact source SHA, including its
repository/workflow/event/branch and required successful outcomes. Reject missing
or newer failed evidence rather than falling back to an older green attempt.
Verify the latest attempt's actual required jobs and matching execution identity. For transferred receipts, validate exact run/attempt/source bindings and the immutable artifact digest; expired or incompatible receipts cannot satisfy reuse.
Reuse unchanged source suites under the development policy; still verify the
selected archive, exact consumers, payload and current registry prerequisites.
Completion of the same approved bundle does not rebuild or repeat source suites.
State which checks ran now and which prior successes satisfied the gate.

Use `.github/workflows/publish.yml` for npm staging and completion, matching the
exact `publish.yml` filename registered in npm Trusted Publisher. Keep optional
read-only approval observation in `complete-approved.yml`. On a writer rename,
update identity assertions, dispatch/recovery, tests and guides together; changing
an existing npm binding requires its own authorization and verification. Preserve
an operational old binding until the coordinated migration is ready.

If the authoritative receipt is valid but its execution environment differs, run the full required source checks on the current verification runner before staging. Keep the authoritative run/attempt/digest guards; do not use this fallback for missing or failed evidence. Reuse workspace outputs produced by that fresh verification, and test one final archive bundle rather than repacking it for a second identical consumer matrix. Recheck the original Release ID and remote tag/source before each asset upload; compare asset bytes and preserve existing matching files. Retire one-off recovery code after folding necessary safeguards into the normal project-owned path.

## Publish or investigate a partial result

For npm, use GitHub Actions with npm Trusted Publishing. Only a new package's first publication uses the agreed manual bootstrap: confirm new-package status, use an authorized maintainer session and the exact verified archive, then verify the registry integrity. Configure/verify its Trusted Publisher before any later release. An existing package changing workflows does not qualify as a first publication. Do not fall back to manual publishing when the Actions/OIDC setup fails. This npm rule does not change GitHub Packages authentication.

When publication is authorized, use the required mechanism and exact verified bundle. Preflight all targets, follow dependency order and serialize overlapping writes. Check registered versions and visibility after each write as the local procedure requires.

Apply the release policy's npm distribution-tag rule: before `1.0.0`, both `beta`
and `latest` must resolve to the exact verified version, including a manual first
publication. At or above `1.0.0`, require `latest` without changing `beta` under this
rule. Confirm the Trusted Publisher permits the selected staging/publication operation
and the separate `npm dist-tag` operation needed for tag completion.
Check tag state before writes and verify it afterwards. If publication succeeded
but tagging did not, verify registry integrity and repair only missing tags; do not
republish or overwrite a newer channel. Report incomplete or conflicting tag state.

On a timeout or partial failure, stop writes and inspect remote state read-only. Discover existing targets before any retry. Compare remote integrity/content where available; report when local tooling verifies only existence/visibility. Matching version lists cannot certify matching bytes. Do not republish existing versions or delete successful ones to repair a partial run. If content identity conflicts, investigate and prepare a new version where necessary.

### Staged npm execution and recovery

For subsequent npm versions, start verification and staging only from the
package-specific GitHub Release's `release: types: [published]` event under the
shared default. Require a stable, non-draft Release from the owning repository;
validate package/version/tag and resolve the tag to the reviewed source commit on
the required release branch. Retain the original SHA. Main/tag pushes and manual
`workflow_dispatch` do not start staging under this default. Keep preparation
Releases in draft until publication is authorized. Preserve explicitly retained
existing contracts until an authorized migration; first publication retains its
manual bootstrap exception.

Manual `workflow_dispatch` is completion/recovery only: restore the original
successful `release` / `published` staging run, successful attempt and immutable
artifact, validating their repository/workflow, source/tag, package/version and
digest. It must never stage again or replace that evidence with a rebuilt archive.

1. Confirm authorization for staging, the exact package, repository/workflow and
   optional environment identity. Keep direct publish disabled for the staged
   path; check dist-tag permission and supported tooling separately. Initial
   package bootstrap remains the reviewed interactive exception, not a fallback
   when configured OIDC fails.
2. Submit only the verified archive on an inspection-only tag, not `beta`/`latest`.
   Report awaiting approval and the original run/artifact identity. The maintainer
   inspects name/version, source, archive integrity and tag, then approves with npm
   2FA; do not automate or impersonate that approval through OIDC.
3. On completion, resolve and validate the successful original staging run and
   unexpired immutable bundle. Recheck source/tag, required quality evidence and
   public registry bytes. Check every required consumer channel for newer versions
   before writes, repair only missing tags, confirm mappings, then record public
   Deployment success against the original release SHA and registry URL.
4. Use bounded propagation polling. Distinguish permission failure from pending
   approval/visibility, superseded channels and content mismatch. Never repeat an ambiguous stage upload
   blindly: have the maintainer inspect reserved stages. Resume the same bundle;
   expired artifacts or different bytes require review rather than silent rebuild.
5. If Deployment display is missing, inspect existing records first; do not
   republish. Failed-record deletion requires explicit authorization, exact-ID and
   status/history checks (inactive does not imply failed), preservation of
   successful/current records and post-delete
   verification. Keep record cleanup separate from registry or Release deletion.

## Report the result

List candidate commit and target versions; gates passed, reused or blocked; exact artifacts/evidence; writes actually performed; remote confirmation and its limits; and the next outstanding action. Keep package publication, retrospective deployment recording, provenance and documentation deployment distinct.

## Shared workflow supply ownership

For maintained private Actions, use the reviewed [supply](https://tech-docs.alneas.com/templates/private-actions/README.md). Keep shared tools/templates, project adapters and generated workflows in distinct owned files. Preserve the standard role names and use `Shared:`/`Project:` step labels and separate guide/summary sections. Verify the local bundle digest and generated output read-only; update and generate explicitly, never during a check. An adapter cannot waive shared guards or stronger project checks. Preserve supported runtime matrices, exact tested bytes, target/tag guards, GITHUB_TOKEN and minimal permissions. Document actual selection/reuse capability; absence requires conservative execution. Do not claim that local adoption has been published or verified remotely.


Use the [four-field handoff template](https://tech-docs.alneas.com/templates/agent-handoff.md#verification-receipt-summary):
**Executed checks**, **Reused evidence**, **Unverified / blocked**, and
**Authorization scope**. Include this skill's required report details in those
fields; use explicit None/Not applicable with a reason rather than omitting a field.