---
title: "ALNEAS Release Policy"
description: "Shared rules for release notes, changelogs, candidate identity, verified artifacts, publication and recovery."
sidebar:
  order: 12
archetype: explanation
project: portal
tags: [governance, release]
---

# ALNEAS Release Policy

Status: Active Baseline Standard, 2026-10-21.
Scope: ALNEAS software releases. Apply the same principles across registry and deployment destinations.

## Terminology conventions

Consistent with the [development policy](https://tech-docs.alneas.com/policies/development-policy.md#glossary-and-terminology-conventions):
- A **check** is an individual inspection command; a **gate** is an aggregate barrier required before publication.
- An **archive** or **tarball** (`.tgz`) is the packaged payload file; a **bundle** is the commit-bound collection of archives and verification receipts transferred to the publishing stage.
- **Verification** establishes candidate contracts; **publication** is the separately authorized write that registers or deploys the verified bundle.

## Release contract

Use common requirements for candidate identity, verification, artifact handoff, authorization and recovery. Read concrete source/target names, visibility, toolchain and commands from existing manifests, scripts and workflows. Apply the subsequent-npm trigger default below; inspect existing triggers and preserve explicitly retained contracts until an authorized migration. Existing `RELEASING.md` explains how to execute them; it should not restate the common policy or require a new project-specific release configuration.

Differences in registry APIs and deployment mechanisms are implementation facts, not optional versions of the shared principles. Apply conditional requirements based on actual artifacts and integrations. Keep an exception only for a demonstrated requirement, with narrow scope, rationale and review condition. Preserve stronger existing gates during adoption. Investigate a conflict between prose and implementation; do not silently choose the weaker requirement.

Package publication, GitHub tags/Releases, deployment records and documentation deployment are separate outcomes. Determine which outcomes the user authorized and which writes the selected trigger causes. Publishing a GitHub Release normally starts package publication; pushing a tag prepares source identity only. Inspect legacy triggers during adoption because a tag push may still cause writes. Preparation never implies authorization for either action. Existing authorization remains valid within its stated scope.

## GitHub Release publication entrypoint

Use `release: types: [published]` as the standard GitHub Actions entrypoint for package publication. A tag push must not also register the same packages. Prepare the immutable tag and review the Release as a draft; publish that Release only with authorization for the registry writes it starts. Publishing the Release starts verification and publication; it does not prove that package registration has completed.

For stable releases, require a published, non-draft, non-prerelease event from the expected repository. Private distribution additionally requires a private repository and private package checks. Verify the event's Release ID and tag, the Actions SHA, the checked-out commit and the resolved tag commit before staging and again before registration. Derive target selection and version constraints from owning manifests and scripts; do not force independently versioned owners to share a version solely to adopt this entrypoint. Prerelease channels require an explicitly reviewed local contract.

Keep verification separate from registry writes. Transfer the exact commit-bound, verified archives within the same workflow run; preserve existing quality, integrity, visibility, dependency and recovery gates. Grant registry credentials only to the jobs that need them, using `GITHUB_TOKEN` for private GitHub Packages and the required package Actions access for cross-repository reads. Public npm bootstrap, staging and human 2FA requirements below still apply.

After registration, attach evidence or completion results to the original Release. Do not create a replacement Release, overwrite reviewed notes or replace mismatched assets. A retry must verify existing package versions and asset bytes, then complete only missing work. Preserve the original tag, commit and verified bundle; an already published Release is not authorization to rebuild a different candidate.

Do not rely on a Release created with a workflow's `GITHUB_TOKEN` to trigger another workflow: GitHub normally suppresses that event chain. When an authorized automation needs to start publication, use an explicit supported dispatch bound to the original Release, source commit and verified artifacts, or a separately reviewed credential mechanism. Do not add a second implicit publication path. Existing trigger exceptions require a concrete rationale and review condition; adoption must not silently weaken stronger project gates. See [GitHub Release events](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#release) and [workflow event chaining](https://docs.github.com/en/actions/how-tos/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#triggering-a-workflow-from-a-workflow).

## Select release candidates from changes

**Extract candidates from changed paths, correct them using dependency and artifact impact, and state version increments explicitly in the PR.** A candidate is a target for release review, not an instruction to publish it.

Compare the intended source against an explicit release baseline. For independently versioned packages, account for each package's last released source and accumulated unreleased changes; the current PR diff alone may omit earlier changes awaiting release. Map paths to owning packages through existing workspace/package manifests and build inputs. For renames and deletions, inspect ownership at both the baseline and candidate revision.

| Observed change | Initial candidate selection |
| --- | --- |
| One package's implementation | That package |
| Multiple packages' implementations | Those packages |
| Documentation or maintainer-only tooling | Normally no package release |
| Shared build configuration, generator or dependency input | Inspect every package that consumes the changed input |

Correct this selection by inspecting actual outputs and dependencies. A README, generated consumer metadata or CLI that ships in a package may need a release when its correction must reach users; a directory label does not override distribution impact. Conversely, do not publish solely because a changed path sits under a package when the change affects only its tests or maintainer tooling.

For a changed dependency, check both compatibility with existing consumers and whether a required fix must reach them. Passing compatibility tests do not prove that consumers receive a security, correctness or required behavioral fix. If the dependent's pinned version or range would exclude the needed version, include its dependency update and release as necessary. A new dependency release alone does not automatically require every dependent to release. Keep any explicit impact requirement with the change's rationale in the existing review/versioning mechanism.

In the PR, record selected targets, dependency corrections and version increments with reasons: patch for compatible fixes, minor for compatible additions, major for breaking changes under stable semantic versioning. Follow the repository's declared pre-1.0/prerelease scheme where applicable. Explain deliberate no-release decisions and migrations for breaking changes. Path classification can be automated; semantic impact and the required delivery of a fix need explicit review. Prefer existing manifests, dependency graphs and Changesets or equivalent records over a new per-project policy file. Add a small mapping only where existing ownership/build metadata cannot express the needed relationship.

## Coordinated public/private delivery

Apply the development policy's
[coordinated maintenance contract](https://tech-docs.alneas.com/policies/development-policy.md#coordinated-publicprivate-project-maintenance)
when selecting targets across a project's public/private repositories. In the
same task, assess both sides, prepare all necessary changes and verify affected
contracts; record each side's release impact or reason no release is needed.
Repository visibility alone is not a reason to omit a dependent or required fix.

Simultaneous publication, equal versions and matching tags are not required.
Plan each target's order, registry prerequisites and compatibility checkpoints in
existing restricted release/task records. When private consumers require a new
public package, verify the public publication first, then adopt its exact published
version in private production manifests/lockfiles and run the dependent's required
checks before its publication. Use isolated temporary candidate archives for early
compatibility testing only; do not commit unreleased registry constraints or local
cross-repository links to bypass a staged prerequisite.

Keep source preparation, compatibility verification, registry adoption and actual
delivery status distinct for each target. A public release alone does not prove
that private consumers received a required fix. If a stage is pending, report the
remaining dependency update/check or delivery action with its prerequisite and
owner; do not claim the coordinated work is complete while required implementation
or verification remains. Complete preparation that can proceed, and retain the
remaining stages in the same tracked task rather than silently dropping one side.
A pending separately authorized release may remain after development verification
is complete, but must be reported as pending delivery.

Preserve each target's existing release gates, immutable versions, artifact binding,
visibility and authorization. Shared maintenance does not itself authorize any
publication. Keep private targets, internal links and evidence out of public
release notes and artifacts; expose only approved public behavior and guidance.

## Release notes and changelog lifecycle

Give consumers enough information to decide whether and how to update. Record
notable user-visible behavior, public API/type/export changes, required dependency
adoption, security fixes and distributed documentation/tooling changes in the PR
that introduces them. State the affected release targets, version increments and
reasons. Maintainer-only work may use an explicit no-release rationale in the
existing review mechanism; do not invent user-facing changes to fill a note.

Use the following ownership and lifecycle:

| Record | Purpose and lifetime |
| --- | --- |
| `.changeset/*.md` or an existing equivalent | Reviewed, unreleased change fragments naming affected targets and version impact. Release preparation consumes the selected fragments into the release history and removes only those fragments from the working tree; Git retains their history. |
| Each independently versioned package's `CHANGELOG.md` | Durable, cumulative user-facing history. Add the new version above older versions and preserve earlier entries. A single-target application may use one root changelog. |
| Package `README.md` | Installation/usage guidance and an obvious link to that package's complete change history. A latest-release summary is optional. |
| GitHub Release or equivalent release page | The target/version-specific presentation of the same reviewed changelog entry, with relevant upgrade instructions and links. |

### Record changes during development

Prefer [Changesets](https://github.com/changesets/changesets/blob/main/docs/intro-to-using-changesets.md)
for independently versioned JavaScript/TypeScript packages. Use the existing
reviewed equivalent for other ecosystems or repositories with an adequate release
record mechanism; this common policy does not impose a Node.js toolchain on them.
Record semantic impact explicitly rather than deriving the whole note from commit
titles or a squash-merge message. Automated commit lists may assist review but are
not a substitute for a consumer-oriented explanation.

The owning repository must verify through its existing PR/release checks that
release-impacting changes have the required change record or reviewed no-release
rationale, and that selected releases have matching notes. A policy URL does not
install this enforcement. If checks are missing, record the integration gap and
implement them in an authorized owning-project change; do not claim enforcement
from prose alone or introduce a second policy profile to adopt this requirement.

### Prepare cumulative history

Prefer a dedicated release-preparation PR, separate from feature and bug-fix PRs.
Where the repository's established review workflow does not use a separate PR,
keep preparation in a distinct commit. Group the selected version and dependency
updates, lockfile and generated metadata changes, cumulative changelog entries
and consumed-fragment removals into that reviewable change. Keep unrelated runtime
changes out of it. For staged releases, prepare each dependent only after its
registry prerequisites are available.

After the required checks and review, attach the authorized release tag to the
reviewed commit on the release branch. A GitHub Release references that tag and
does not require an additional placeholder commit. Preparing or merging the PR
alone does not authorize publication; follow the owning repository's actual
publication triggers and the user's authorization.

At release preparation, collect only the fragments for the selected targets and
review the generated version/dependency changes and notes together. In an
independently versioned repository, keep one cumulative changelog per package;
start with a single file and do not split or rotate history preemptively. If a
large history later needs archival, retain explicit links and access to every
released version rather than silently dropping old entries.

Follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) principles: newest
version first; clear version headings and known release dates; and applicable
Added, Changed, Deprecated, Removed, Fixed and Security sections without empty
placeholders. Explain consumer impact, compatibility and migration steps; identify
which dependency update delivers a required fix. Include issue/PR and comparison
links when useful. Never expose private implementation or operational evidence in
public notes. Unknown historical release dates must not be fabricated.

`Unreleased` or pending fragments describe future work. A versioned entry produced
by preparation is still a candidate until publication succeeds; do not describe
it as delivered solely because a heading, tag or GitHub Release exists. Preserve
existing released entries. Make factual corrections explicitly without rewriting
which behavior or source was shipped. During partial publication, keep each
package's prepared/published status distinct and retain the prepared versioned
entry so recovery does not depend on already-consumed fragments.

Versioning tools do not replace dependency-order checks. If a dependent needs a
predecessor's registry version, follow staged preparation/publication in the
owning release procedure. Review automatic dependency bumps before merging; do
not let a bulk versioning command require an unpublished predecessor in a gate
that expects a registry install.

### Make notes discoverable to package consumers

For npm packages, place a visible change-history link in the package README, for
example in a concise Documentation section or its existing Next Steps section. Use a stable, package-specific HTTPS
link to the canonical changelog or release history that works on npm as well as
GitHub. Do not rely solely on a relative path whose target exists only in the
repository. The [npm README documentation](https://docs.npmjs.com/about-package-readme-files/)
explains the package-page entry point consumers see.

The npm README may remain concise and English-only under the
[compact README contract](https://tech-docs.alneas.com/policies/documentation-policy.md#compact-npm-package-readmes).
Neither a Japanese README nor the five-section project layout is required in the
package payload. Link the migration guide when consumers must act on breaking
changes; detailed release notes remain in the changelog. Inspect the packed README
and confirm that extra language variants were not accidentally included when the
package intends an English-only README.

Include the package's `CHANGELOG.md` in its published archive, keeping private
package history limited to the intended audience. A `files` allowlist must include
it explicitly where needed; changelogs are not among npm's always-included files.
Inspect the actual archive and the release-specific README links under the
[npm package-file rules](https://docs.npmjs.com/cli/v11/configuring-npm/package-json/#files).
Do not ship `.changeset/` fragments or maintainer-only release evidence. Changelog
history does not replace current API/usage guides.

A latest-release summary in README is an optional convenience, not a baseline
requirement. If provided, derive it from the reviewed release entry or verify that
it matches, label the relevant version and keep unreleased changes distinct.
The baseline README contains usage guidance and the history link; it need not
accumulate release entries or change its established section structure.

### Reuse notes without changing publication authorization

Create GitHub Release bodies or equivalent release-page notes from the same
reviewed package/version entry. Keep content consistent without maintaining two
independent histories. Templates may add distribution links and current workflow
status without changing the documented package behavior. If one release page
covers multiple targets, label each package/version explicitly and respect the
owning repository's release-trigger contract.

Prepare and review notes before publication. If publishing a GitHub Release starts
a registry deployment, keep it as a draft until that external write is authorized.
Generating fragments, changelogs or draft notes does not authorize a commit, tag,
Release publication or registry write. After publication, verify the delivered
changelog and README history link and any authorized release-page notes. Do not
republish an immutable package version merely to update release notes.

### Independent package adoption

Keep independent package versions, tags, release notes and registry status distinct.
A shared initial tag need not be rewritten when later releases become package-specific.
For an internal dependency update, verify the predecessor's exact public version
and content identity before preparing a dependent that needs a registry install.
Test the dependent against its declared registry dependency and the candidate
archive where applicable; compatibility does not itself deliver a required fix.
Retain reviewed adoption requirements until the dependent's actual constraint
includes the fix. An unchanged, already-published predecessor is not republished
merely because a dependent or the publication workflow changes.

## Candidate identity and immutability

Select the reviewed source revision before final release verification. Working-tree verification is useful preparation but does not prove that an archive belongs to a committed release. Bind final artifacts to a real commit, exact target names/versions, artifact digests and required supporting evidence. Identify the toolchain and relevant source inputs in retained records.

Any source, version, dependency, build or packed-content change invalidates the affected identity and checks. Amending a commit invalidates a commit-bound bundle even if version strings match. Regenerate and reverify against the selected commit. A version string or tag alone does not prove source-to-archive identity.

Published versions are immutable. Preserve existing release tags. Fix changed contents with a new version under the project's versioning contract; do not overwrite, retag or delete historical releases as a routine retry operation.

## Verify the distributable

Pass the mandatory gates for each target and stage before its registration or deployment. Verify the candidate artifacts before starting writes; when a dependent target additionally needs a predecessor's registered version, confirm that prerequisite before the dependent write. Use clean-install verification where the existing procedure requires it; local workspace success cannot prove a clean install works. A CI package gate, full UI suite, documentation validation and live-agent evaluation establish different facts. Retain applicable gates without assuming one substitutes for another.

Inspect and test the actual selected payload: package identity, exports, declarations, peers, styles, documentation, licenses/notices and dependency constraints as applicable. Exclude secrets, private sources, unintended assets and operational logs. Public sourcemaps and source content are a project-owned disclosure decision; check actual packed bytes against it.

Audit included third-party material and its required notices/source retrieval evidence under the project's reviewed distribution rules. Keep installed-dependency diagnostics and consuming-application distribution checks distinct from library archive checks. Preserve exact-version exceptions and unresolved flags locally; a project-specific exception does not become ecosystem-wide approval. This is an engineering evidence requirement, not a legal conclusion.

Retain source archives outside npm payloads when the local notice/source-retrieval scheme requires them. Keep necessary retrieval metadata available to recipients. Recheck external availability under the local release procedure.

### Reuse source quality without repeating the release suite

A trusted successful source-quality run for the exact selected commit can satisfy
unchanged unit, type and browser requirements. Validate its repository, maintained
workflow, event/branch, source SHA and required job outcomes before accepting it;
missing, running, failed, cancelled, superseded or unverifiable evidence blocks
that reuse. Do not substitute an arbitrary green PR, feature or manual run for the
owning workflow's required evidence. Incremental runs must cover all outstanding
changes since a trusted passing ancestor under the development policy.

Validate the latest run attempt's actual required jobs and matching runtime/platform/runner identity as well as its source SHA. If evidence is transferred as an artifact, verify its run/attempt binding and immutable digest before accepting the receipt. PR/untrusted cache entries, skipped jobs, missing/expired receipts and environment mismatches do not satisfy release reuse. See the development policy's cache-trust and execution-identity rules.

Hosted runner labels can serve multiple image revisions concurrently. After validating the required authoritative source run, latest attempt and immutable receipt for the exact candidate, a verification job may satisfy incompatible execution conditions by running the full required source checks on its current runner before staging archives. Never relabel the older receipt as a pass in the new environment. Fresh-check failure blocks publication; report fresh execution separately from reuse. This fallback does not replace missing, failed, expired or unauthenticated authoritative evidence where the project requires it.

Treat reuse as satisfying the gate, not bypassing it. Build-cache reuse still needs
matching inputs and outputs. Verify the selected release archive, identity,
payload/notices/metadata, applicable exact-archive consumers and current registry
prerequisites. Do not infer that a new archive passed because another build of the
same commit passed. Completion of an approved unchanged bundle does not rebuild or
repeat source tests; revalidate the binding and remote state. Keep benchmark or
live-model requirements limited to the explicit local release contract.

Share validated build-task caches between source quality and release verification, retaining their source, dependency, output and execution bindings. If fresh source verification already built the selected workspaces on the same runner, retain that exact output instead of building it again. Prepare one final commit-bound archive bundle and run the applicable exact-archive consumers against it once; publication transfers and revalidates that bundle without repacking. Time-sensitive registry, visibility and prerequisite checks remain fresh.

## Handoff and publication

Publish or deploy the exact verified artifacts. Transfer them between verification and publication stages with a manifest binding commit, artifact hashes, target names/versions and required detached evidence. Validate that binding before any write. Do not rebuild in the publishing stage and substitute new bytes for the reviewed artifacts.

Allowlist the intended destinations and visibility. Use least-privilege authentication and CI permissions. Do not apply a public npm workflow to a restricted GitHub Packages release by analogy.

### Two-stage release execution in CI

Workflows that publish packages or perform external deployments must separate the **verification stage** from the **publication stage**:
1. **Verification Job (Unprivileged)**:
   - Checks out the candidate commit, satisfies required quality/security gates through execution or validated evidence reuse, and prepares candidate distribution archives.
   - Tests the exact candidate archives in isolated consumer fixtures.
   - Generates and uploads the verified archive along with sanitized identity manifests (`release.json` with commit SHA, archive cryptographic digest, target version) as an immutable CI workflow artifact.
   - This verification job must **not** possess elevated publication credentials, OIDC tokens (`id-token: write`), or registry write permissions.
2. **Publish Job (Privileged, Minimal Scope)**:
   - Runs only after the verification job succeeds completely.
   - Receives the exact verified archive artifact from the verification job (verifying digest integrity upon download).
   - Never re-executes build scripts or compiles new source in this stage.
   - Obtains scoped registry credentials (e.g. GitHub OIDC `id-token: write` for npm Trusted Publisher, or `NODE_AUTH_TOKEN` for GitHub Packages) and submits only the verified bytes through the authorized publication or staging path.
   - Concurrency must be serialized per release target group (e.g. `concurrency.cancel-in-progress: false`) to prevent race conditions during multi-package releases.

### Private distribution: GitHub Packages and minimal payload footprint

For private or internal packages, **GitHub Packages (`https://npm.pkg.github.com`) is the interim publishing destination**.

To maintain registry health, minimize storage consumption, and prevent accidental data leakage, enforce strict payload minimization rules for all packages published to GitHub Packages:

- **Keep distributed tarball sizes strictly minimal**:
  - Distribute only compiled runtime code, type declarations, bundled CSS/assets, canonical `LICENSE`, `README.md`, the package's consumer-facing `CHANGELOG.md`, and mandatory machine-readable consumer AI or third-party notice summaries.
  - Exclude development files, tests, fixtures, intermediate build seals/caches, coverage reports, build configuration files (`tsconfig.json`, `vite.config.ts`), and unbundled source files (`src/`) unless explicitly intended as a public sourcemap contract.
  - Implement and enforce strict package archive size budgets in automated audit gates according to project-configured size thresholds. Any budget violation must block release until reviewed and justified.
- **Third-party notices and source retrieval separation**:
  - Consolidate third-party notices into clean, single-document files (e.g. `THIRD_PARTY_LICENSES.html` or `THIRD_PARTY_STATUS.json`).
  - Do not pack bulk upstream third-party source tarballs or font binaries into private npm archives. Retain necessary source archives in maintainer offline storage or commit-bound release sidecars outside the package payload.
- **Audit packaged files before registration**:
  - Automated release gates (e.g. `audit-packed-distribution` or equivalent package audit) must inspect actual packed tarball contents against explicit file allowlists before any upload to GitHub Packages.
  - Explicitly reject unexpected payload files, non-runtime artifacts, and bundled `node_modules` folders.

Package REST metadata can differ between maintainer and installation tokens. Distinguish an omitted optional repository field from an explicit invalid or conflicting link. Require exact package owner/name/type, private visibility, npm repository URL/directory and registered archive integrity; reject explicit conflicts. Independently confirm the actual repository association after first registration or a linkage migration. Keep package writes on `GITHUB_TOKEN`; do not add a personal-token publication fallback.

### npm workflow filename

Use `.github/workflows/publish.yml` as the canonical npm registry-writing workflow
for ALNEAS projects, including both staging and completion. Register the exact
filename `publish.yml` in npm Trusted Publisher settings and use it consistently
in workflow dispatch, evidence validation, tests and maintainer instructions.
Keep read-only approval observation in `complete-approved.yml` when enabled; it
must dispatch `publish.yml` and must not receive npm write credentials or OIDC.

Renaming an existing writer requires coordinated updates to its npm Trusted
Publisher, source identity assertions, dispatch/recovery paths and documentation.
Preserve an existing operational binding until that migration is authorized; a
repository rename alone does not update npm trust. Do not stage another release
under an incomplete migration, rebuild retained artifacts or republish existing
versions to test the new filename.

### npm: Trusted Publisher, with manual first publication

The [standalone first-publication guide](https://tech-docs.alneas.com/templates/verification/first-npm-publication.md) provides local command examples and verification steps without requiring another project's checkout. The reviewed archive and owning project's actual gate commands remain prerequisites; a generic sample must not invent passing evidence or bootstrap account trust.


Publish to npm through **GitHub Actions using npm Trusted Publishing (OIDC)**. This is the shared default, not a per-project authentication choice. Do not use a long-lived npm write token for routine publishing.

Before package-specific Trusted Publishing is configured, each genuinely new npm package uses the agreed **manual maintainer bootstrap**. Do not assume an unconfigured Release workflow can establish that trust. npm also supports staging a new package with a public `0.0.0-stage` placeholder; that placeholder is not publication of the verified release. Choose the reviewed interactive bootstrap path under current npm capabilities. This exception covers only establishing that package's initial registry version; it does not apply to an existing package's first release from a new workflow, repository or maintainer. Confirm that the exact package is genuinely new rather than inaccessible. Use an authorized maintainer session and the same reviewed, commit-bound archive with the same checks and post-publication integrity verification. Manual publication is a separate external write and requires the applicable authorization. Keep credentials out of retained receipts.

Publish the real initial release version directly with `npm publish` from the maintainer's interactive session, complete 2FA, and use the exact reviewed archive with lifecycle scripts disabled. Do not bootstrap a new package with `npm stage publish` or a dummy version. [npm staged publishing](https://docs.npmjs.com/staged-publishing/) creates a publicly visible `0.0.0-stage` placeholder when the package does not yet exist; it does not promise automatic removal after approval. Avoid creating that placeholder rather than relying on later cleanup. Existing placeholders require a separately reviewed decision under the [npm unpublish policy](https://docs.npmjs.com/policies/unpublish/); deleting or deprecating them is not part of routine publication.

After the first publication, configure and verify the package's Trusted Publisher against the intended GitHub repository, exact workflow filename and environment when used. Give the publishing job its required OIDC permission, use supported publishing tooling and verify provenance where supported. Account/package configuration and an executable publishing workflow are both required; a repository edit alone does not complete adoption. Subsequent versions must use the configured GitHub Actions **staged publishing** path: submit the exact verified archive with `npm stage publish`, require an authenticated maintainer's 2FA approval, then complete the release through Actions. Use an inspection-only initial tag such as `staged`; after approval, the completion workflow verifies public archive integrity and version ordering before assigning the required consumer tags and recording any successful Deployment. Approval does not automatically change `staged` into `beta` or `latest`. Do not rebuild, republish, or repeat unchanged tests during completion. A failing or unavailable Actions/Trusted Publisher setup is a blocker to repair, not automatic permission to publish manually.

Inspect existing publication triggers against the subsequent-npm default below; other destinations retain their reviewed trigger contracts. Serialize writes to overlapping release targets and preserve required dependency order. Preflight all intended targets before starting writes, then satisfy each target's staged prerequisites before writing that target. Version dependencies together only as required by their actual constraints; a tag version does not require every package to share that version.

### npm staged approval and completion

Use [staged publishing](https://docs.npmjs.com/staged-publishing/) for subsequent
npm publications under this shared default: CI submits the verified archive, a maintainer reviews it
and approves with npm 2FA, then automation confirms the public result. Retain a
deliberate existing direct-publication contract until a separately authorized
migration; adding this guidance does not change account settings or workflows.
Stage submission, human approval and completed publication are different states.

Start verification and staging for a subsequent npm version when its
**package-specific GitHub Release is published**, using `release: types: [published]`.
Accept only a stable, non-draft Release (`draft: false`, `prerelease: false`) from
the owning repository. Validate the selected package, its exact prepared manifest
version and package-specific tag under the repository's existing naming contract;
resolve the tag to the reviewed source commit on the required release branch and
retain that original SHA in the verified bundle. Reject mismatched identity or
source before any staging write. A Release's display title or `target_commitish`
alone is not source evidence.

Main-branch pushes, tag pushes and manual `workflow_dispatch` are not the shared
default for starting staging. Publishing the package-specific Release is the
release-start action and requires its applicable authorization. Keep Releases in
draft during preparation. Preserve an explicitly retained existing trigger
contract until its migration is separately authorized; this policy does not
silently change running workflows or the manual first-publication exception.

Reserve `workflow_dispatch` in this staged path for completion or recovery after
human npm approval. It must resolve the original successful `release` / `published`
staging run, its successful attempt and immutable artifact, validate their
repository/workflow, package/version/tag, original source SHA and required evidence,
and resume only confirmed missing completion work. A completion dispatch or
completion-job rerun must never create a fresh stage or substitute a rebuilt
archive for the original bundle. An ambiguous stage submission requires maintainer
inspection before any retry under the recovery rules below.

```mermaid
flowchart LR
  V[Verified archive] --> S[OIDC staging]
  S --> A[Maintainer review and npm 2FA]
  A --> C[Verify public bytes and required tags]
  C --> D[Record successful Deployment]
```

Use an inspection-only initial dist-tag for staging, for example `staged`, rather
than `beta` or `latest`. Approval can apply the stage's immutable tag out of order;
a separate channel prevents an older approval from moving consumer channels back.
Completion checks ordering before attaching required consumer tags. Do not present
the inspection tag as a recommended install channel or completed publication.

Keep direct `npm publish` disabled for the staged path. Allow `npm dist-tag` only
when needed for completion, independently of staging/direct-publish permission;
pin tooling supporting those OIDC operations. Require maintainer 2FA and appropriate
package access controls. Review/list/download/approve/reject are maintainer-session
operations, not unattended OIDC approval. Check current
[npm Trusted Publisher permissions](https://docs.npmjs.com/trusted-publishers/).
Repository edits do not grant or revoke npm permissions.

Completion must recover the original trusted staging run and immutable artifact,
validate its successful staging job, source/tag, package/version and digest, then
compare public registry integrity. A caller-supplied run ID, version or artifact
name alone is insufficient. Completion can repair missing tags and records without
re-staging or substituting new bytes. Define artifact retention and expiry recovery;
expired evidence requires review, not a newly built archive relabeled as original.

For phase-by-phase commands, run/artifact validation inputs and expected outcomes,
see the [subsequent-publication recipe](https://tech-docs.alneas.com/templates/verification/staged-npm-publication.md).
The [read-only archive comparison example](https://tech-docs.alneas.com/templates/verification/archive-integrity.md)
includes a standalone Node helper and mismatch tests; neither requires another project checkout.

### Automatic completion after human npm approval

For staged workflows, completion may start automatically after the maintainer's
npm approval. Approval remains a maintainer-session operation with 2FA; do not
expand the Trusted Publisher to direct publication for this automation. Staging
and permitted dist-tag operations are sufficient. The observer only reads public
registry metadata and requests the existing trusted completion workflow.

A recommended implementation is a bounded `workflow_run` observer: require an
original successful release-event staging run from the owning repository, execute
trusted default-branch code, resolve its successful attempt and immutable artifact,
and compare the approved public package/version/integrity with that archive before
dispatching completion. Exclude completion's own dispatch runs to prevent loops.
Use minimal `actions: write` for dispatch; the observer needs neither npm write
credentials nor OIDC. Keep registry writes and Deployment creation inside the
existing completion gate and its publication concurrency group; waiting observers
must not occupy that group. Preserve original source-SHA quality evidence and
Deployment identity; dispatching from main does not change the release source.

Default observation budget: 30 minutes with 30-second reads, including bounded
registry request time. Set an explicit containing-job timeout (for example 35
minutes). Waiting uses Actions runner time. At the deadline, report approval
pending rather than publication success and retain manual completion using the
original staging run ID. API errors, changed attempts, expired evidence or digest
mismatches must block automatic dispatch. Do not retry uncertain dispatches until
checking whether completion already started. A successful observer only means
completion was requested; verify the separate completion result, required tags
and Deployment before reporting release success. Do not rebuild, re-stage or
repeat unchanged tests to recover a completion-only failure.

See the [self-contained adoption guide](https://tech-docs.alneas.com/templates/npm-release/automatic-completion.md)
for permissions, event selection, script contracts and recovery steps. This pattern
is optional; retain manual completion when runner cost or approval timing makes
observation unsuitable.

### npm distribution tags before 1.0.0

For every npm version below `1.0.0` under SemVer ordering, **both `beta` and `latest`
must point to that same released version** before publication is reported complete.
This is a completion condition, not a permanent tag on each historical version.
A superseded pending release cannot satisfy it by rolling current channels back.
This dual-tag strategy ensures that initial early-adopter consumers installing via
default `npm install <pkg>` (which resolves to `latest`) receive the latest verified
pre-1.0.0 build, while consumers explicitly requesting a pre-release channel (`beta`)
resolve to identical bytes without channel divergence.
This applies to manual first publication as well as Actions, and to prerelease
versions below `1.0.0` when the owning workflow supports them. These are npm
distribution tags, not Git tags or a requirement to add `-beta` to version strings.
For versions at or above `1.0.0`, require `latest`; this rule does not advance or
delete an existing `beta` channel.

Submit the verified archive once with the path's explicit initial tag, then verify its
registry integrity and attach any missing required tag to that exact version.
Confirm all required tag mappings from the registry. A partial tag failure is an
incomplete release; retry only missing tag operations after verifying existing
content, without republishing. Check for newer versions before writes and never
roll a channel backwards during an older retry. A newer channel is a conflict to
report, not permission to overwrite it or claim the old tag mapping was restored.

Configure the Trusted Publisher to allow staging and `npm dist-tag` operations,
with direct `npm publish` disabled. Staging, direct publishing and dist-tag permissions
are independent; a maintainer performs the initial direct publication in their own
interactive session before configuring this routine Actions path. Use a supported OIDC-capable CLI;
repair missing permissions rather than introducing a write token or manual fallback.
Changing tags on previously published versions is still an external write requiring
the applicable authorization; adopting this policy does not perform a backfill.

## Partial publication and recovery

On a timeout or ambiguous registry response, stop further writes and inspect remote state through read-only queries. A failed client request may already have succeeded. Do not automatically republish, delete versions or roll back successful targets.

Before retrying, establish which exact targets/versions exist, their visibility and whatever artifact/content identity the registry and local tooling can verify. Resume only missing work under the existing authorization and local procedure. If a registry exposes integrity, compare it with the reviewed artifact. A mismatch requires investigation; never treat matching version names as matching bytes.

Some existing tools can only skip already registered versions after confirming existence and visibility. State that limitation: it does not certify content identity. Improve missing identity verification as a separate scoped change rather than claiming the existing tool already performs it. Initial registration must distinguish absence from inaccessible state; a 404 alone may be ambiguous.

Use bounded read-only polling sized for observed registry propagation, and report
approval-pending, propagation-pending, superseded, permission rejection and content conflict
separately. A superseded release has newer consumer channels; stop its writes
without rolling them back or claiming completion. A successful upload followed by a short-lived 404 is not proof that
nothing was written. On ambiguity, stop mutations and inspect state before deciding
whether to resume. A completion retry verifies existing bytes and performs only
confirmed missing work; an ambiguous staging retry first needs maintainer inspection
because the version may already be reserved. Poll timeouts do not authorize
re-staging, deleting a pending version or changing reviewed content.

## Post-publication verification and reporting

Confirm target versions, visibility, relevant dependency resolution and the delivered artifacts or exact registry installation. Compare integrity where supported. Verify distribution-specific metadata and links when relevant.

Report preparation, verification, publication and post-publication results separately, including partial failures. Preserve sanitized handoff evidence in the approved location. A retrospective deployment record documents a remote observation; it does not retroactively establish a build provenance attestation. Documentation ingestion, translation and portal deployment remain separately authorized workflows.


### Deployment records and display

A successful Deployment describes confirmed publication, not merely uploaded or
approval-pending bytes. Bind the record to the original release SHA and registry
URL; a completion dispatch's newer default-branch SHA is not the released source.
When GitHub environment identity is needed before publication, consider
[`environment.deployment: false`](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idenvironment)
and create or resume the public-success record only after integrity and required
tags match. Check compatibility with environment protection rules.

Enabling a repository's Deployment display later does not require republishing.
Inspect existing records and statuses first; a retrospective record is a separate
write and does not create provenance. A display problem is not permission to rerun
publication. If failed-record cleanup is explicitly authorized, enumerate and
recheck the exact failed records, preserve successful/current records, follow the
[Deployment deletion API](https://docs.github.com/en/rest/deployments/deployments#delete-a-deployment),
and verify the survivors. An inactive record may be a previous success; inspect
its status history rather than treating inactivity as a failed attempt.
Record cleanup does not delete registry versions, tags,
Releases or workflow runs; deleting those requires its own authorization.

## Shared and project-owned release automation

Private workflow supply uses the [maintained templates](https://tech-docs.alneas.com/templates/private-actions/README.md) and the development policy's visible ownership boundary. `Publish private packages` invokes shared verification before a separate write-capable publication job; `Shared:` steps own orchestration and immutable transfer, while `Project:` phases own supported target/tag validation, current artifact gates, registration and recovery. Keep these parts separate in files, the Actions UI and owning documentation. A project adapter cannot change shared entrypoint/permission rules or weaken existing checks. Generated-output and bundle-integrity checks are read-only.

Transfer archives within their exact source/run/attempt and wait for every required runtime job. A primary-runtime archive does not waive another runtime's failure. Publication revalidates the same bytes and never rebuilds. Additional attachment privileges require an explicit project phase; projects that do not attach assets retain read-only contents permission. Preserve automatic GITHUB_TOKEN authentication, private visibility/first-registration safeguards and reviewed partial-release recovery. Template adoption does not authorize any release, package write, shared-branch push or portal deployment.

Attach assets to the fixed original Release ID, rechecking the live Release and resolved remote tag/source before each upload. Compare existing and newly uploaded asset bytes; conflicting assets stop recovery without replacement. After an incident, move generally useful safeguards into the normal project-owned path and remove one-off executable recovery capsules, preserving historical commits and private audit evidence. Keep any general recovery entrypoint explicit, reviewed and bound to the original verified bundle.