docs: complete pull request workflow

.github/pull_request_template.md

@@ -13,6 +13,7 @@
 - [ ] `bun run typecheck`
 - [ ] `bun run test`
 - [ ] `bun run build` when the production package or Web UI is affected
+- [ ] `git diff --check origin/main...HEAD` (`upstream/main...HEAD` for forks)
 
 ## Documentation and security
 

AGENTS.md

@@ -520,11 +520,13 @@ HTTP Streamable only. Built-in: context7, grep.app, exa (hardcoded in `BUILTIN_M
 ## Repository GitHub Workflow
 
 - `main` is protected and accepts changes through pull requests only. Never commit or push directly to `main`.
-- Start repository work from the latest `origin/main` on a focused feature branch. Keep branch creation, commit, push, PR creation, and merge as explicit, separately reported actions.
-- Before opening a PR, run the relevant local validation documented in `CONTRIBUTING.md`.
+- Start repository work from the latest canonical `main` (`origin/main` for collaborators, `upstream/main` for forks) on a focused feature branch. Branch creation, commit, push, opening or marking a PR ready, and merge are distinct state-changing actions: perform only the actions the user requested, unless they explicitly requested the complete end-to-end PR lifecycle, and report each completed state precisely.
+- Before opening a PR, inspect the staged scope and run the relevant local validation documented in `CONTRIBUTING.md`, including `git diff --check origin/main...HEAD` (or `upstream/main...HEAD` for forks). Open a ready PR against `main` and complete the repository PR template when the change is ready for review.
 - The required GitHub gates are the `Verify` status check and the CodeQL code-scanning policy. `Verify` installs with the frozen lockfile, typechecks, runs tests with diagnostics, builds the production binary, and smoke-tests that binary.
-- CodeRabbit and Cubic provide automatic advisory review on ready PRs and incremental pushes. Address actionable findings and resolve every review conversation, but final merge judgment remains human.
-- Merge PRs with squash merge only. Do not bypass repository rules, force-push shared branches, or weaken required checks to unblock a change.
+- CodeRabbit and Cubic provide automatic advisory review on ready PRs and incremental pushes. After every pushed change, wait for checks and reviews on the new head SHA, inspect review conversations again, address or explain actionable findings, rerun relevant validation, and repeat until the latest head is clear. A pending AI reviewer is neither a failure nor permission to merge.
+- Immediately before merge, record the current head SHA and confirm that it is still the reviewed head, the PR is mergeable, `Verify` and CodeQL pass, every review conversation is resolved, and the user has authorized the merge. Merge with squash only. Do not bypass repository rules, force-push shared branches, or weaken required checks to unblock a change.
+- After merge, fetch the canonical remote, switch to local `main`, fast-forward it from that remote's `main`, and verify that both refs match with a clean worktree. Report the merge commit and synchronized state separately from PR creation.
+- Release work follows the same PR loop, then verifies that the release tag points to the exact merged commit, the release workflow succeeds, the public Release and expected assets exist, and local `main` is synchronized. A green PR or a pushed tag alone is not a completed release.
 
 ## Testing Patterns
 

CONTRIBUTING.md

@@ -68,8 +68,12 @@ Validation order is `typecheck` before `test`.
 ```sh
 bun run typecheck
 bun run test
+git diff --check origin/main...HEAD
 ```
 
+The command above uses `origin` for the canonical repository. Replace it with
+`upstream` when contributing from a fork.
+
 For changes that affect the production package or Web UI, also run:
 
 ```sh
@@ -93,8 +97,28 @@ They may add incremental feedback after new commits are pushed. Address
 actionable findings, explain intentional decisions when appropriate, and do not
 treat an AI approval as a substitute for maintainer judgment.
 
-Maintainers merge accepted PRs with squash merge. The merged PR becomes one
-commit on `main`, and GitHub deletes the merged head branch automatically.
+Checks and reviews apply to the current PR head. After every pushed fix, rerun
+the relevant local validation, wait for `Verify`, CodeQL, CodeRabbit, and Cubic
+on the new head commit, and inspect review conversations again. A pending AI
+review is neither a failure nor a merge-ready result.
+
+Immediately before merge, maintainers confirm that the reviewed head commit has
+not changed, the PR is mergeable, required gates pass, and every review
+conversation is resolved. Maintainers merge accepted PRs with squash merge.
+The merged PR becomes one commit on `main`, and GitHub deletes the merged head
+branch automatically.
+
+After merge, synchronize the local default branch without rewriting it:
+
+The commands below use `origin` for the canonical repository. Replace it with
+`upstream` when contributing from a fork.
+
+```sh
+git fetch origin
+git switch main
+git merge --ff-only origin/main
+git status --short --branch
+```
 
 ## Code conventions