docs: flag backward-incompatible changes in code review (#542)

* docs: flag backward-incompatible changes in code review

Add a Breaking Changes section to AGENTS.md so code review catches
changes that compile and pass tests but break a running cluster on
upgrade or break existing clients: persisted Raft/WAL state and
snapshots, gRPC proto, spur.conf/config, and user-facing CLI/REST.
Require appending `!` to the PR title type when a break is unavoidable.

Co-Authored-By: Claude <noreply@anthropic.com>

* Address Copilot comments

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* docs: drop redundant fixture prescription from breaking-changes note

* docs: drop serde(default) prescription from config breaking-changes note

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: 3 people

AGENTS.md

@@ -43,6 +43,15 @@ Do not use `#N` to reference numbered points within a PR or issue description 
 
 A pre-commit hook is available in `.githooks/` (activate with `git config core.hooksPath .githooks`). It enforces formatting and SPDX license headers.
 
+## Breaking Changes
+
+Some changes compile and pass tests but break a running cluster on upgrade or break existing clients. Code review MUST flag these. Prefer the compatible option (add, don't remove/rename/retype); when a break is genuinely unavoidable, append `!` to the PR title type/scope (e.g. `fix(spur-core)!: ...`, `feat(proto)!: ...`) so it is called out. Watch for:
+
+- **Persisted state (Raft/WAL log, snapshots)** — `WalOperation` and every type it reaches (`JobSpec`, `JobStep`, `Reservation`, `NodeState`, resource/alloc types, `AdmissionToken`, k0s state) serialize to JSON in the Raft log; `PersistedSnapshot` likewise. A new field without `#[serde(default)]` or `Option`, or a renamed/removed field or enum variant, makes a new controller crash replaying old entries.
+- **gRPC proto (`proto/slurm.proto`)** — renumbering, removing, or retyping a field breaks FFI, REST, and cross-version wire compat. Only append fields with new tags; never reuse or renumber tags.
+- **Config (`/etc/spur/spur.conf`, `config.rs`)** — removing/renaming a field or changing its type breaks deployed configs.
+- **User-facing CLI/REST** — removing a flag, subcommand, or response field, or changing its meaning, breaks Slurm-compatible scripts.
+
 Validate your changes before submitting:
 
 ```bash