KoalaSync/AGENTS.md

# Repository agent release rules

These rules are mandatory for every automated agent working in this repository.

## Before changing code

- Run `git pull --ff-only` before starting.
- Inspect branch, remote tracking, dirty state, and relevant release workflow.
- Preserve unrelated work and stage only reviewed paths.

## Before claiming a release is ready

- Never treat a host macOS browser run as GitHub Linux parity.
- On a release branch, commit all intended changes and run:
  `npm run release:gate -- MAJOR.MINOR.PATCH --candidate`
- This command must use the official lockfile-matched Playwright image with
  `linux/amd64`, Ubuntu Noble, and `CI=1`; it must run clean installs, full
  verification, all browser E2E tests, the relay image build, and health smoke.
- A failed, interrupted, ARM64, skipped, or partial run is not a passing gate.
- Do not say "release-ready" until the candidate gate and PR required checks
  are green for the exact commit.

## Before pushing a release tag

- Merge through a PR; resolve every review thread.
- Fast-forward local `main` and confirm a clean tree at exact `origin/main`.
- Wait for `verify`, `node20`, and `e2e` on the merged `main` commit.
- Run the final gate: `npm run release:gate -- MAJOR.MINOR.PATCH`.
- Create an annotated tag only after the final gate succeeds.
- Confirm tag target equals `origin/main`, then push the tag once.
- Monitor the complete release workflow. Distinguish tag push, CI, draft assets,
  container publication, attestations, and public GitHub Release status.
- Never call a release complete while any job is pending, failed, or skipped.

The final gate deliberately simulates the release workflow seeing its own
in-progress `preflight` check. This is a permanent regression guard for the
failed first `v3.1.5` release attempt.