Pa Brat Beta Release

PA BRAT Beta Release

Use this skill for Personal Assistant prerelease builds intended for BRAT beta testers. The detailed repo SOP is docs/operations/brat-beta-testing.md; read it before changing the workflow or executing a beta release.

Branch Model

Keep these roles distinct:

• master: the sole integration and release-source branch. All accepted runtime code, tests, research/design docs, governance and release-tooling changes land here through a PR merge or an explicitly authorized direct commit.
• Work branch: optional isolation/review transport. It has no beta or stable release authority; accepted commits must enter master first.
• Beta packaging branch: temporary branch named exactly beta/<target-version>, created from the exact verified master HEAD.

A beta branch may contain only the generated [release] vX.Y.Z-beta.N packaging commit and tag above master. Do not add feature/fix/docs commits there, and do not merge or rebase the beta release commit back to master.

Safety Boundaries

• Treat make release, make publish, tag creation, branch pushes, GitHub Releases, and sending BRAT tester instructions to others as release-side effects.
• Do not publish, push branches, push tags, create GitHub Releases, or hand off BRAT tester instructions/URLs to others unless the user clearly asks for that action in the current turn. Reporting a verified published URL to the user in this conversation is read-only and does not require separate authorization.
• If the target version, master baseline, or baseline tag is ambiguous, stop and ask before creating release state.
• Prefer make release-dry-run VERSION=x.y.z-beta.N before any local release commit/tag.

Preparation Workflow

Choose the lane from the user's request:

• Explain/status/inspect: read local state, the runbook, and remote status when needed. Do not fetch, switch, pull, create branches, or write release state.
• Dry run only: inspect scripts/release.mjs and run the existing dry-run command when its prerequisites already hold. It writes no release files, but currently requires a clean matching beta/<version> branch at master HEAD and a tagged baseline. Report unmet prerequisites; a dry-run request alone does not authorize creating branches or changing the checkout to satisfy them.
• Prepare: perform the workflow below within the requested scope. Preparing the baseline/packaging branch does not authorize a release commit, tag, or push.

When asked to prepare a beta:

1. Inspect current state:
   • git status --short --branch
   • git branch --show-current
   • node -p "require('./package.json').version"
   • git tag --sort=-v:refname | sed -n '1,20p' If git status --short --branch shows any uncommitted changes, stop before switching or creating beta branches. Ask the user to commit, stash, clean, or explicitly confirm the intended dirty-worktree scope.
2. Confirm all accepted work is already in master. A work branch with commits not reachable from master must be merged by PR or authorized direct commit before beta preparation continues.
3. Refresh and verify the local integration baseline:
   • git fetch origin master
   • git switch master
   • git pull --ff-only
   • git rev-list --left-right --count master...origin/master Require both counts to be zero before creating the packaging branch. This one preparation check is necessary: make release treats a live master mismatch as unavailable CI evidence and falls back to local checks; only make publish rejects it. A successful git pull --ff-only alone does not exclude local commits ahead of origin.
   • do not run another full gate here: make release obtains exact-master CI evidence or runs the full local fallback after the packaging branch is ready If local master is ahead, beta preparation must stop until the user explicitly authorizes pushing master and the two refs match. Rely on release/publish scripts for their remaining source/ref/version checks instead of repeating them manually.
4. Choose the next prerelease version, usually <next-stable>-beta.N.
5. Create the packaging branch from the exact current master HEAD:
   • git switch -c beta/<target-version>
6. Run or recommend:
   • make release-dry-run VERSION=<target-version>
   • make release VERSION=<target-version> only when the user asked to create local release state.
   • make publish VERSION=<target-version> only when the user asked to publish and the publish preflight below passes.

The release command uses the release-critical documentation gate. Full docs:check lifecycle/status findings remain a separate CI and maintenance signal and must not block beta or stable publication.

Validation Reuse And Cost

Use ordinary make release VERSION=<beta> once. It automatically tries to reuse the latest same-repository master push CI for the exact clean, synchronized source SHA. The current attempt must have passed the full validate job, including dependencies, Lint, Build, Test and Audit bundle; docs-only success, skipped steps, old SHA/run/attempt or incomplete API data cannot substitute. The script prints the accepted run URL/SHA or fallback reason.

Reuse retains local diff, third-party notice and release-doc checks. Missing evidence, unsupported origin, missing gh or a bounded API timeout falls back to the existing local full gate. RELEASE_LOCAL_CHECKS=1 make release VERSION=... forces full local checks for diagnosis. Stable uses the same evidence rules; dry-run does not query CI or execute checks. Do not use SKIP_CHECKS as a substitute for this evidence check.

Beta publication follows completed functionality acceptance on master. For normal generated packaging, tag CI independently reuses successful full master push CI for the exact release parent, with the same repository/current attempt and required full steps above. Normal master advances are allowed while that parent remains in master history. It installs dependencies, builds versioned assets, runs artifact tests, and retains metadata, notice, release-doc, bundle audit and asset checks; it does not repeat source lint/full Jest/coverage. Missing, invalid, failed, docs-only, incomplete or unavailable evidence falls back to the full gate; invalid source/packaging identity rejects publication. Stable also uses exact parent CI reuse under the release runbook. This replaces the earlier always-full beta tag rule.

Reused CI does not prove this machine's node_modules or old dist is valid for deployment. Do not add another test/build before or after make release, or while waiting on tag CI, without changed inputs or a concrete failure. Normal beta packaging does not require redeployment or repeated functionality smoke.

scripts/release.mjs enforces both the matching beta/<target-version> name and the pre-release HEAD == master source invariant.