From 02c85329019f879864b0f30b72262a8ba4671e75 Mon Sep 17 00:00:00 2001
From: morluto <76467478+morluto@users.noreply.github.com>
Date: Fri, 23 Oct 2026 15:54:00 +0800
Subject: [PATCH] docs: require buy-in for speculative hardening complexity

---
 .github/pull_request_template.md | 5 ++++-
 AGENTS.md                        | 2 ++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 1c1ef2bd76..3c6c0ca03e 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -17,7 +17,10 @@ describe the use case and observable outcome. -->
 ## Change and scope
 
 <!-- Explain the chosen approach, why it fits REA's architecture, and what is
-intentionally not included. -->
+intentionally not included. If adding complexity for a speculative or vanishingly
+unlikely race or security edge case, record the concrete failure mode, likelihood,
+complexity cost, and the user's buy-in obtained before implementation. Do not
+silently expand scope for theoretical robustness. -->
 
 Follow the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope).
 Unresolved scope, authority, side effects, or required verification block
diff --git a/AGENTS.md b/AGENTS.md
index 8b6846ea64..47a6efacad 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -22,6 +22,8 @@ Keep proof of ownership separate from validity, editability, and readiness. Malf
 
 For lifecycle changes, follow [ownership and completion invariants](docs/tool-design.md#own-the-lifecycle) and select the applicable [lifecycle regressions](docs/testing.md#lifecycle-regressions). Include late handshakes, cancellation during final cleanup, mixed child outcomes, and cleanup retry where those stages exist; active-execution cancellation alone does not cover finalization.
 
+Before adding complexity for a speculative or vanishingly unlikely race or security edge case, explain the concrete failure mode, likelihood, and complexity cost to the user and get their buy-in. Do not silently expand scope for theoretical robustness.
+
 Assess brittleness in touched code during implementation, debugging, review, and maintenance. Fix the producing representation or ownership rule before adding downstream repairs. Normalize once at the owning boundary using format-aware parsers. Remove superseded representations, aliases, wrappers, and redundant tests after verifying affected consumers. Introduce abstractions only when they remove observed complexity.
 
 When fixing a bug, inspect the producing boundary and affected consumers for duplicated interpretation or unclear ownership. Complete any directly related refactor in the same change and remove superseded code. Passing regression tests alone does not establish that the brittleness is resolved. If related cleanup remains, explain what remains and why.