Document topic-branch PRs + sync main into develop

AGENTS.md

@@ -36,7 +36,8 @@ Install tooling to `$GOBIN`: `make tools` (govulncheck, gocyclo).
 
 ## Git flow
 
-- **Branches:** Day-to-day work on **`develop`**. Topic branch → **PR into `develop`** (green CI, merge, delete branch). Production: **PR `develop` → `main`**, then annotated tag **`v<semver>`** on **`main`** only.
+- Work on **topic branches** opened from `develop`; merge via **PR into `develop`**. **Never** commit or push directly to `develop` or `main`.
+- Release: **PR `develop` → `main`**, then annotated tag **`v<semver>`** on **`main`** only. After every merge into `main`, sync **`main` → `develop`** (see `.cursor/rules/git-flow.mdc` locally) so the next release PR is not **"out-of-date with the base branch"**.
 - **Never** merge to **`main`**, create/push a release tag, or run **`make release`** / trigger GoReleaser **without explicit user approval** in the current conversation — even if `release-check` is green.
 - **Commits:** Show the proposed commit message and wait for user approval before `git commit` (see `.cursor/rules/commit-message-review.mdc` locally).
 - **Language:** English only for code, comments, commit messages, docs, and UI strings.
@@ -55,7 +56,7 @@ Do the **VERSION bump as a dedicated change on `develop`** after feature work la
 | 6 | **BSD ports** | `make port-freebsd-sync` and/or `make port-openbsd-sync` |
 | 7 | **`docs/ROADMAP.md`** | **Last reviewed** date; shipped highlights; tick completed bands |
 | 8 | **Gate** | `make release-check` — run only after user asks |
-| 9 | **Ship** | Merge `develop` → `main`, annotated tag `v<semver>`, push tag — **only after user explicitly approves** |
+| 9 | **Ship** | Open **PR `develop` → `main`**, merge on GitHub, annotated tag `v<semver>`, push tag — **only after user explicitly approves**. Then sync **`main` → `develop`**. |
 
 **Follow-ups (other repos, after GitHub Release is green):** pin app version in **[kzero-selfhosted](https://github.com/hrodrig/kzero-selfhosted)**; marketing/install sites on GitLab (`kzero-hermesrodriguez-com`, `get-kzero-hermesrodriguez-com`) if they hard-code a release.
 

CHANGELOG.md

@@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Branch policy matches pgwd / gghstats: topic branch → PR into `develop`; no direct push to `develop` or `main`. After `develop` → `main`, sync `main` into `develop` so the next release PR is not out-of-date.
+
 [↑ Back to top](#top)
 
 ## [1.1.1] - 2026-09-02

CONTRIBUTING.md

@@ -1,6 +1,9 @@
 # Contributing
 
-- Default branch for work: **`develop`**. **`main`** is production-ready; releases are tagged from `main` only (see [.cursor/rules/git-flow.mdc](.cursor/rules/git-flow.mdc) if present in your clone).
+- **Branch policy:** `develop` is integration; `main` is production. Releases are tagged from `main` only.
+- **Code:** From an up-to-date `develop`, create a **topic branch** (`feat/…`, `fix/…`, `chore/…`, `security/…`, `docs/…`), push it, and open a pull request **into `develop`**. Wait for green CI, then merge.
+- **No direct push** to `develop` or `main` (GitHub rulesets `protect-develop` / `protect-main` — same pattern as [pgwd](https://github.com/hrodrig/pgwd) / [gghstats](https://github.com/hrodrig/gghstats)).
+- **Release:** PR **`develop` → `main`**, then annotated tag `vX.Y.Z` on `main`. After every merge into `main`, sync **`main` → `develop`** so the next release PR is not **"out-of-date with the base branch"**.
 - Before opening a PR: **`make lint`**, **`make test`**, and **`make cover-check`** (total statement coverage must be **≥ 80%** unless you temporarily set `COVERAGE_MIN=` for a documented reason).
 - Before a release tag: **`make release-check`** (lint, tests, govulncheck, Grype on the built image — requires Docker). Sync **`contrib/man/man1/kzero.1`**: update **`.TH`** date and `kzero vX.Y.Z` to match **`VERSION`**, and document new CLI flags/commands; `release-check` fails if `.TH` version drifts.