Document macro maintenance workflow

Author: fatbobman

AGENTS.md

@@ -67,6 +67,14 @@ Most changes are correctness-sensitive because public behavior is generated by m
 ## Testing Expectations
 
 - Run `swift test` before finishing any behavioral change.
+- Preserve the macro guardrail suite in `Tests/ObservableDefaultsMacroTests`. It exists to catch generated-code regressions before runtime tests do.
+- When changing macro generation, run `swift test --filter ObservableDefaultsMacroTests` in addition to any affected runtime suites.
+- Keep macro coverage split by responsibility:
+  - `MacroExpansionSnapshotTests.swift` for expanded-source and formatted-source snapshots
+  - `MacroStructureTests.swift` for syntax/shape assertions that should survive harmless formatting changes
+  - `MacroDiagnosticTests.swift` for diagnostics and invalid-argument coverage
+- Add or update fixtures in `Tests/ObservableDefaultsMacroTests/Fixtures` when a macro change introduces a new meaningful expansion scenario.
+- Update files under `Tests/ObservableDefaultsMacroTests/__Snapshots__` only when the expanded output intentionally changes. Treat snapshot diffs as generated-code behavior changes unless proven otherwise.
 - If a change touches external notifications, fallback logic, or equality checks, at minimum run:
   - `swift test --filter ExternalChangeEqualityTests`
   - `swift test --filter ObservableDefaultsTests`
@@ -77,16 +85,31 @@ Most changes are correctness-sensitive because public behavior is generated by m
   - `swift test --filter PrefixTests`
   - `swift test --filter WhitespaceTests`
   - `swift test --filter StringParameterTests`
+- If a change touches macro parameter parsing or diagnostics, also run:
+  - `swift test --filter ObservableDefaultsMacroTests`
 - If a change touches storage format or overload resolution, run:
   - `swift test --filter RawRepresentableCodableTests`
   - `swift test --filter Issue26OverloadAmbiguityTests`
+- If a change touches observer lifetime, notification registration, or external notification teardown, also run:
+  - `swift test --filter ObservableDefaultsTests`
+  - `swift test --filter ObservableCloudTests`
+  - verify the runtime regression tests covering model deallocation and post-release notifications still pass
 
 ### Test Isolation Rules
 
 - `UserDefaults` tests should use isolated suite names. Prefer `UserDefaults.getTestInstance(suiteName:)`, and use a unique suite per test when cross-test interference is possible.
 - Cloud `.testMode` tests use per-test mock suite isolation through `NSUbiquitousKeyValueStoreWrapper.testSuiteName`. Preserve that mechanism.
 - If a suite relies on shared notifications or shared storage state, make it `.serialized`.
 - Do not “fix” flaky tests by weakening expectations if the real issue is shared storage or notification interference.
+- Prefer running `swift test` commands serially when changing macro/plugin code. Parallel SwiftPM test runs can contend on `.build` and produce misleading cache or lock failures.
+
+### Macro Test Workflow
+
+- Use `swift-testing` by default for new repository tests. Keep `XCTest` only where macro-testing APIs still require it.
+- Prefer structure assertions plus snapshots over snapshots alone. Snapshot tests catch whole-output drift; structure tests catch semantic shape changes with less formatting sensitivity.
+- Snapshot files are intentionally not reformatted by the pre-commit hook. Do not manually reformat files under `Tests/ObservableDefaultsMacroTests/__Snapshots__`.
+- Macro string parameters are valid only when they are plain string literals composed entirely of `StringSegmentSyntax` segments. Interpolated strings must be diagnosed, not partially accepted.
+- Macro boolean parameters must diagnose invalid non-literal expressions rather than silently falling back to defaults.
 
 ## Documentation Rules
 
@@ -105,8 +128,9 @@ When reviewing changes, prioritize:
 2. missing tests for external changes and fallback paths
 3. `MainActor` and `defaultIsolationIsMainActor` coverage
 4. `observeFirst` correctness
-5. storage format compatibility for RawRepresentable/Codable hybrids
-6. test isolation and notification scope
+5. observer lifecycle and notification token teardown
+6. storage format compatibility for RawRepresentable/Codable hybrids
+7. test isolation and notification scope
 
 ## Release Workflow