Improve agent context: boundaries, decisions, test norms, idempotency

[Mpdreamz]

Summary

Improves how well an AI agent can work in this repo without prior context: explicit safety boundaries, cross-cutting architectural rationale, a real test-alongside-change norm, module-scoped context for two core subsystems, and a fixed inaccuracy in the testing stack description. Also adds a genuine idempotency test and a lightweight "write a short plan first" norm for non-trivial work.

• AGENTS.md (symlinked from CLAUDE.md):
  • Added a "Boundaries: never touch / human-gated" section naming real destructive surfaces: production-targeting essc indices commands, [CommandIntent(Intent.Destructive)]-tagged docs-builder commands, environment-gated Lambda deploys, and config/assembler.yml's public-bucket allowlist blast radius.
  • Added a "Cross-cutting decisions" section: the AOT/JsonSerializerContext registration rule, and why the search contract is a separate shared project.
  • Added a test-alongside-change norm with the real change→test-project→command mapping.
  • Fixed an inaccuracy: the doc claimed "TUnit" was in use for testing — no project actually references it. Corrected to the real stack (xUnit v3 + AwesomeAssertions + FakeItEasy) while noting TUnit as the org's intended future migration target.
• New module-scoped AGENTS.md for src/Elastic.Markdown/ and src/services/search/Elastic.Documentation.Search.Contract/, modeled on the existing src/Elastic.ApiExplorer/AGENTS.md (structure map, named patterns, "where do I put X" table).
• New test: Applying_the_plan_then_replanning_yields_no_further_deletions in IndicesCleanupPlannerTests.cs — proves IndicesCleanupPlanner.Plan converges on retry (safe to re-run after a partial apply).
• CONTRIBUTING.md: added a short "Working on non-trivial changes" section asking for a brief plan/definition-of-done before non-trivial implementation.

Why

The repo was already in good shape going into this — a clean, real AGENTS.md/CLAUDE.md, disciplined commit/PR history, fast unit tests, environment-gated prod deploys, and a scoped context file for the one subsystem (ApiExplorer) that had already been deliberately restructured. None of that changed here. What moved the score was almost entirely encoding more of what's already true about this codebase into AGENTS.md — explicit boundaries, decision rationale, and module-scoped conventions that previously lived only in people's heads or in scattered PRs — plus one small, genuine gap (an idempotency test) and one real inaccuracy (the TUnit claim).

Before / after

Self-scored against a 6-pillar rubric (Context Legibility, Blast Radius & Boundaries, Verification Determinism, Task Decomposability, Tool & Environment Reachability, Idempotency & Retry Safety), each 0–100:

Pillar	Before	After
A. Context Legibility	87.50	100.00
B. Blast Radius & Boundaries	83.33	100.00
C. Verification Determinism	75.00	87.50
D. Task Decomposability	50.00	66.67
E. Tool & Environment Reachability	50.00	50.00
F. Idempotency & Retry Safety	83.33	100.00
Overall (weighted)	73.13	85.80

D and E are mostly gated by things outside this repo's docs (issue-tracker practice, an upstream UI-only content source) and weren't expected to move much from a doc-only PR — left as-is rather than overclaimed.

Test plan

• dotnet build — 0 errors
• dotnet format --verify-no-changes — clean
• dotnet test tests/Elastic.SiteSearch.Tests/ — 172/172 passed (including the new idempotency test)
• ./build.sh unit-test — full suite green (~50s)
• Spot-checked every path/command/type name cited in the new/edited docs against the actual source

🤖 Generated with Claude Code