Stable Release

Stable Release

Read docs/operations/release-process.md before every stable-release execution or workflow change. Treat that runbook and the current release scripts as the canonical command and asset contract. If this skill disagrees with them, stop and report the drift instead of improvising.

Run commands from the repository root. For prerelease versions, use pa-brat-beta-release instead.

Resolve Intent

Classify the current request before changing state:

• prepare: inspect state and show the dry run. Do not create a release commit or tag, push anything, create a GitHub Release, or submit a hosted community review.
• local-release: prepare, then let release automation validate and create the local release commit and annotated tag. Do not push.
• publish: complete the local release when needed, push master and the tag, wait for the workflow, verify the GitHub Release, then verify official recognition through Check for new releases when needed.
• verify: inspect an already-published target and complete only the requested follow-up verification. Do not recreate its release commit or tag or push again. For official recognition, proceed to the section below after verifying the existing GitHub Release.

Treat an explicit current-turn request that names the target version and asks to publish as authorization for the complete publish flow. Do not ask again only because the dry run finished. Ask before mutation only when:

• the target version, branch, or requested intent is ambiguous;
• the proposed version or scope differs from what the user authorized;
• the dry run reveals unexpected commits, release notes, or risk;
• a blocking gate requires a product or risk-acceptance decision; or
• recovery would delete, rewrite, or move a release tag.

Safety Boundaries

• Cut stable releases only from master with a clean worktree.
• Never publish without explicit publish intent in the current turn.
• Never delete, rewrite, or move release tags without an explicit maintainer decision.
• Stop on failed validation, unresolved hosted community Error, or workflow failure. Report the evidence; do not bypass the gate.
• Preserve unrelated user changes. Do not stash, clean, switch branches, or reconcile divergence without authorization.

Inspect State

Run:

git status --short --branch
git branch --show-current
node -p "require('./package.json').version"
git tag --sort=-v:refname | sed -n '1,20p'
git fetch origin master
git rev-parse HEAD
git rev-parse origin/master

Stop if the worktree is dirty or the branch is not master.

Resolve one of these states:

• Fresh source state: the target is greater than package.json, its tag does not exist, and HEAD equals origin/master.
• Existing local-release state: package.json equals the target, the target tag points to HEAD, and HEAD^ equals origin/master. Do not recreate the release commit.

Stop on any other local/remote or version/tag relationship and ask the user how to reconcile it. If no version was supplied, use the read-only changelog preview to propose one, then obtain approval before changing release state:

node scripts/changelog.mjs --target-version <candidate>

Dry Run Fresh Releases

For a fresh source state, always run:

make release-dry-run VERSION=<target-version>

Report the current and target versions, changelog range, commit subjects, and generated section. Continue directly when they match an already-authorized local-release or publish request. A previously created local-release state cannot be dry-run again with the same version; validate its release commit and tag instead.

Community Review Policy

Stable preparation and publication do not run a hosted source Preview, including an optional preview. Release automation retains source validation, eligible CI reuse and final tag/asset checks. Use obsidian-community-check only in release mode after GitHub publication, as described below.

Hosted-only defects may therefore be discovered after GitHub publication. Diagnose them and follow the recovery section; do not claim official recognition while an Error remains unresolved.

Create Local Release

For a fresh local-release or publish flow, run the release automation:

make release VERSION=<target-version>

Do not pass SKIP_CHECKS=1 or --skip-checks. Do not use make deploy as a substitute: make release owns its whitespace, notices and release-critical docs checks. It reuses complete successful CI for the exact synchronized master source when eligible; otherwise it runs local lint, build, coverage and bundle audit. RELEASE_LOCAL_CHECKS=1 forces the full local gate for diagnosis. The final tag always builds versioned assets and runs artifact tests with valid parent CI, or full coverage without it, plus legal/docs/version/bundle/asset checks. Do not prepend another full gate to the automated evidence lookup. Full lifecycle docs:check findings are reported separately and do not block publication.

Trust the successful release command's version, commit/tag and worktree checks. Recheck state only after a concurrent change, an ambiguous command result or a concrete failure.

Stop here for local-release.