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.

Release verification

• Never treat a host macOS browser run as GitHub Linux parity.
• Run checks proportionate to the changed files. Markdown-only changes do not require browser E2E or release:gate.
• npm run release:gate -- MAJOR.MINOR.PATCH [--candidate] remains available when release code itself needs Linux/AMD64 parity validation. It prepares the requested version only inside its isolated clone.
• All OCI image references must use the canonical lowercase ghcr.io/shik3i/koalasync; never construct Docker references from the case-preserving ${{ github.repository }} value. The local gate enforces this.

Before pushing a release tag

• Fast-forward local main and confirm a clean tree at exact origin/main.
• Wait for verify, node20, and e2e on that exact main commit.
• Do not edit release-version sources manually. The tag workflow owns the atomic version update.
• Create an annotated exact SemVer tag such as v3.1.6.
• Confirm tag target equals origin/main, then push the tag once.
• The workflow must extract the version, update and validate every version source, commit chore(release): update versions to vX.Y.Z [skip ci], and push that commit directly to main before building release outputs.
• Chrome, Firefox, website, and relay outputs must use the exact prepared commit.
• 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.
• Never reuse, move, or force-push a published tag.