pa-brat-beta-release

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# 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.

From edonyzpc/personal-assistant, AGPL-3.0.

More from edonyzpc/personal-assistant