test: add state invariants for refactor safety

1 files changed, 2 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 2d81c48e..3c7d158b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -49,6 +49,8 @@ Run `just check` before committing unless Can explicitly accepts narrower valida
 
 Unit tests live next to the code (`#[cfg(test)] mod tests`). New `AppState` or `Workspace` behavior should be testable with `AppState::test_new()` and `Workspace::test_new()` without PTYs.
 
+For broad refactors or release-risk regressions, classify the risk before editing. Treat changes as refactor-risk when they touch two or more core surfaces, persisted state, protocol/API IDs, workspace/tab/pane identity, restore/handoff, agent detection authority, or UI/input state projection. Before moving code, identify the protected behavior and add or name characterization tests. Identity/state refactors should use the test-only invariants `AppState::assert_invariants_for_test()` or `Workspace::assert_invariants_for_test()` with adversarial state from `AppState::test_with_adversarial_identity_state()` or `Workspace::test_adversarial_identity_state()`. Run a roundtable for broad refactors and release-risk regressions, not for routine local fixes.
+
 When testing a new Herdr build from inside an existing Herdr session, use
 `cargo run -- ...` and clear inherited Herdr socket overrides so the debug
 binary talks to the debug `herdr-dev` server instead of the installed stable