Add backwards-compatibility principle to AGENTS.md AI brief #262

Problem

AGENTS.md and docs/agents/release-and-versioning.md document how to handle a breaking change (the breaking-change label, the ⚠️ Breaking change callout, the version.json major bump, the CHANGELOG entry) — but neither states the principle: prefer backwards compatibility; break deliberately, not incidentally.

That gap matters: AI coding tools (Claude, Copilot, Cursor) reading the brief get a procedural checklist for the breaking case but no signal that the breaking case is the exception. Same for first-time human contributors. Without an explicit stance, the implicit default becomes "go ahead and rename / change signature / restructure — just add the label."

Proposal

Add an explicit principle to the Critical rules section of AGENTS.md as rule #2 (right after the PR-creation flow rule):

• Default to backwards-compatible changes: additive APIs, [Obsolete] markers with migration guidance, transition shims (like src/Shims/), feature flags.
• A breaking change is a deliberate decision with a stated reason — not something that emerges from "the API would be cleaner this way."
• When a break is truly necessary, follow the documented PR-creation flow.

A first PR adds the rule. Leaving this issue open for discussion of the surrounding policy:

Open questions

1. What counts as "backwards compatible" for Fallout?
   • Public-API consumers (Fallout.Common, Fallout.Build, Fallout.Components) — clearly yes, semver applies.
   • On-disk formats (parameters.json, .fallout/build.schema.json, version.json) — also consumer-facing.
   • CI workflow shape from the [GitHubActions] generator — consumers regenerate, so not breaking-on-update, but it changes their generated YAML.
   • dotnet fallout :setup scaffolding (build.ps1 / build.sh templates) — one-time generation, low impact.
   • The Nuke.* transition shims — LTS policy or sunset date?
2. Tools we should encourage / require:
   • [Obsolete] with a DiagnosticId for per-call-site suppression.
   • [EditorBrowsable(Never)] for soft-hiding.
   • The transition-shim generator (src/Fallout.SourceGenerators/TransitionShimGenerator.cs) — when is it the right answer?
   • Symbol-level analyzers (Fallout.Migrate.Analyzers) for guided migration.
3. When is breaking actually OK?
   • Security-driven (e.g. the AES-GCM v2 secret format in fix(security)!: AES-GCM v2 secret format with per-secret salt+nonce, 600K PBKDF2 (#212) #214 — v1: decryption preserved, only the encrypt path changed).
   • Removing already-[Obsolete]-since-vN code after N+1 releases.
   • Internal-only types (no InternalsVisibleTo to non-test assemblies).
4. Cross-reference with the v11/v12 split. v11 = rebrand completion + internal foundation; v12 = public Fallout.Plugin.Sdk. Once the SDK ships, the cost of breaking changes rises sharply. Stronger LTS stance for v12+?

Definition of done

• First PR adds the principle to AGENTS.md. ✓ initial step
• Follow-up discussion (this thread) drives a detailed docs/agents/backwards-compatibility.md once the open questions settle.