publish-npm-release

name	publish-npm-release
description	Publish a completed npm package from the current repository. Use when code changes are finished and npm authentication is ready, and Codex should inspect the registry, synchronize release versions, validate, commit, tag, push, and publish a new stable npm version.

Publish an npm release

Treat invocation as authority to perform the complete stable release workflow, including a Git commit, annotated tag, remote push, and npm publish. The caller has already completed product changes and updated npm authentication.

Version policy

1. Read package.json to obtain the package name and local version. Read AGENTS.md, package scripts, and existing release scripts before changing anything.
2. Run npm whoami, then query the registry for the package's latest version and complete published-version list. Handle a 404 as a first release.
3. Select the target version from registry evidence, never by incrementing an arbitrary local value:
   • Keep the local version when it is valid SemVer, unpublished, and greater than npm latest.
   • Otherwise use the next patch version after npm latest.
   • If the caller explicitly requests minor or major, increment that component from npm latest instead.
   • Stop for prereleases unless the caller explicitly supplies the intended npm dist-tag. Do not publish a prerelease as latest by default.
4. Update package.json and every current release-metadata surface that repository validation requires to equal the target version. Prefer a repository-provided version-sync command. Otherwise inspect exact-version references and update only manifests or runtime client metadata, never historical documentation, fixtures, or changelogs.

Validate and commit

1. Run all release-relevant checks documented by AGENTS.md, package scripts, and existing release scripts. Include repository tests, syntax checks, plugin validation when present, npm pack --dry-run, and git diff --check.
2. Stop before committing if any validation fails. Diagnose and fix only release/version issues; do not alter completed product behavior without asking.
3. Review git status --short. Stage only the caller's completed changes plus the release-version updates. Stop if unrelated or ambiguous changes cannot be separated safely.
4. Commit with Release v<target-version> if the target-version changes are not already committed. Push the current branch and require its push to succeed before tagging.

Tag and publish

1. Require a clean working tree and confirm the current branch is not detached.
2. Refuse to reuse, move, delete, or force-push an existing v<target-version> tag.
3. Create git tag -a v<target-version> -m "Release v<target-version>" at current HEAD.
4. Run any repository release verifier after tagging. It must confirm that version metadata matches and that the tag resolves to HEAD.
5. Push the tag, then use git ls-remote --tags origin to confirm the remote contains it before publishing.
6. Run npm publish without an npm dist-tag for a stable release. Never confuse npm dist-tags with Git tags.
7. Verify npm view <package>@<target-version> version and inspect npm dist-tags. Report the package name, published version, commit, Git tag, validations, and npm verification result.

Stop conditions

Stop without publishing if npm authentication fails, the target npm version already exists, version metadata cannot be synchronized, validation fails, branch/tag push fails, or remote tag verification fails. Do not use npm version, git tag -f, git push --force, or npm unpublish as a fallback.