Merge pull request #7 from gaelic-ghost/release/release-docs-v3-2-4

release: prepare v3.2.4

Author: gaelic-ghost

AGENTS.md

@@ -21,6 +21,7 @@
 - Treat `main` as the release branch for this repository unless a future repo-local change says otherwise.
 - Use `scripts/repo-maintenance/release-prepare.sh` from feature branches and worktrees when the job is to validate a release candidate, push the branch, open or update the pull request, and queue auto-merge.
 - Use `scripts/repo-maintenance/release-publish.sh` only from local `main` after the release PR has merged when the job is to cut the annotated tag and GitHub release.
+- If local `main` is ahead of `origin/main`, do not try to publish from that unsynced checkout. Move that work onto a feature branch or keep it on the existing branch, run `release-prepare.sh`, merge the PR, fast-forward local `main`, and only then run `release-publish.sh`.
 - Do not publish release tags or GitHub releases directly from a feature branch or feature worktree in this repository.
 - Treat the resolved `SpeakSwiftly` dependency declared in `Package.swift` and locked in `Package.resolved` as the source of truth for normal `xcrun swift build` and `xcrun swift test` runs here.
 - Do not retarget this package to a local `../SpeakSwiftly` checkout unless the manifest is being changed intentionally for a specific local-integration task.

README.md

@@ -408,7 +408,7 @@ If you are integrating against the server rather than just running it locally, u
 
 Use [CONTRIBUTING.md](CONTRIBUTING.md) for the maintainer workflow, validation path, live end-to-end coverage, release flow, and monorepo handoff rules.
 
-The maintainer release contract is now intentionally split by checkout context: use `scripts/repo-maintenance/release-prepare.sh` from a feature branch or worktree when the job is "push this release candidate, open or update the PR, and queue auto-merge," then use `scripts/repo-maintenance/release-publish.sh` from local `main` after the PR merges when the job is "cut the actual tag and GitHub release." The current details live in [docs/maintainers/release-workflow.md](docs/maintainers/release-workflow.md).
+The maintainer release contract is now intentionally split by checkout context: use `scripts/repo-maintenance/release-prepare.sh` from a feature branch or worktree when the job is "push this release candidate, open or update the PR, and queue auto-merge," then use `scripts/repo-maintenance/release-publish.sh` from local `main` after the PR merges when the job is "cut the actual tag and GitHub release." If local `main` is ahead of `origin/main`, that still counts as branch-side release-candidate work for this contract: get those commits onto a PR path first, then fast-forward `main` and publish from the synced release branch. The current details live in [docs/maintainers/release-workflow.md](docs/maintainers/release-workflow.md).
 
 ## Development
 

docs/maintainers/release-workflow.md

@@ -11,6 +11,8 @@ The release surface is intentionally split by checkout authority:
 
 That split keeps branch and worktree automation convenient without letting an unmerged feature branch publish a release tag accidentally.
 
+One practical rule follows from that split: if the commits you want to release are not already on `origin/main`, you are still on the prepare side of the workflow even if those commits currently live in a local `main` checkout. Protected-branch policy and `release-publish.sh` both assume the release tip has already been merged and synced back down to local `main`.
+
 ## Context Rules
 
 ### Local `main`
@@ -23,6 +25,8 @@ scripts/repo-maintenance/release-publish.sh --version vX.Y.Z --skip-live-service
 
 That path is the only supported tagged-release publisher. It syncs local `main` with `origin/main`, validates the repo unless told not to, stages the release artifact, creates the annotated tag, pushes the branch and tag, creates the GitHub release, and optionally refreshes the local LaunchAgent-backed live service.
 
+If local `main` is ahead of `origin/main`, stop there. Do not try to force the publish path through that unsynced checkout. Put those commits on a feature branch if needed, run `release-prepare.sh`, merge the PR, fast-forward local `main`, and only then return to `release-publish.sh`.
+
 ### Local Feature Branch
 
 Run:
@@ -111,6 +115,8 @@ Behavior:
 4. let GitHub checks run
 5. let auto-merge land the PR
 
+If you accidentally made the release-candidate commits directly on local `main`, branch from that tip before continuing so the rest of the workflow still goes through `release-prepare.sh` and a normal PR merge.
+
 ### Main Publish
 
 1. switch to `main`
@@ -135,4 +141,5 @@ Current defaults:
 - `release-publish.sh` refuses to run from any branch other than the configured release branch
 - `release-publish.sh` syncs the local release branch with the remote before tagging
 - `release-publish.sh` refuses to publish if local release-branch commits are ahead of the remote
+- protected `main` policies are expected to force release-candidate commits through a PR before publish
 - both flows require a clean worktree