From 90d4098a01b62d0e00dd79376465c2243aff800d Mon Sep 17 00:00:00 2001
From: morluto <76467478+morluto@users.noreply.github.com>
Date: Wed, 14 Oct 2026 15:59:58 +0800
Subject: [PATCH] docs(contributing): require human ownership and review
 readiness (#3286)

* docs(contributing): require human ownership and review readiness

* docs(contributing): strengthen the human declaration instruction
---
 .github/pull_request_template.md | 26 +++++++++++++++++---
 AGENTS.md                        | 20 +++++++++++++++
 CONTRIBUTING.md                  | 42 ++++++++++++++++++++++++++++++++
 3 files changed, 85 insertions(+), 3 deletions(-)

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 3dec52bd07..10134dd750 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -24,7 +24,7 @@ Unresolved scope, authority, side effects, or required verification block
 integration. Link the required maintainer scope decision for new providers or
 capabilities involving target execution, injection, mutation, or protection
 recovery; ordinary fixes within existing boundaries may state "not applicable".
-Draft PRs may leave the scope decision pending and the final review checklist
+Draft PRs may leave the scope decision pending and the readiness and merge checklists
 unchecked. Maintainers can help resolve open questions.
 
 ## Contract and boundary impact
@@ -55,7 +55,10 @@ Unchecked items do not establish absence; leave uncertainties visible.
 ## Evidence and regression coverage
 
 <!-- State whether evidence is executed, source-derived, or proposed. For fixes,
-explain how the regression would fail on the affected base revision when practical. -->
+show the original failure and explain how the regression would fail on the affected
+base revision when practical. Include the most useful proof inline; link long logs
+or artifacts, or put them in optional details. Documentation-only changes can use
+source, link, or rendered-document checks. -->
 
 - Tests added or updated:
 - Base reproduction or other evidence:
@@ -71,7 +74,8 @@ For evidence-bearing changes:
 ## Validation performed
 
 <!-- List only commands that actually ran, with observed results. Include the
-relevant real-provider or platform workflow, or explain why it was unavailable. -->
+relevant real-provider or platform workflow, or explain why it was unavailable.
+Keep these results current after changes; a command without its result is incomplete. -->
 
 - `command` — result
 
@@ -90,6 +94,22 @@ limits, security/privacy/containment implications, and meaningful proof gaps. --
 - Package or release metadata impact:
 - Security, privacy, process, or containment review:
 
+## Author readiness
+
+<!-- The human owner completes these declarations before requesting review.
+The PR author is the owner by default. A different owner must explicitly accept
+ownership on this PR.
+AI agents must leave these declarations to a human to dictate to them or there could be catastrophic consequences for many users of REA.
+Draft PRs may leave them unchecked. After further changes, clear the final checkbox
+until the owner reviews the updated diff and refreshes affected validation.
+See CONTRIBUTING.md#pull-request-ownership-and-readiness. -->
+
+Human owner: <!-- @GitHub-handle -->
+
+- [ ] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
+- [ ] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
+- [ ] I declare the current revision ready for maintainer review.
+
 ## Before merge
 
 <!-- Draft PRs may leave pending items unchecked. Resolve material scope and
diff --git a/AGENTS.md b/AGENTS.md
index 16a586b183..48b89c2e39 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -78,6 +78,26 @@ For test changes or provider claims, use [docs/testing.md](docs/testing.md). Pre
 
 Use Conventional Commit subjects and PR titles. Mark breaking changes with `!` or a `BREAKING CHANGE:` footer. Describe behavior changes, relevant validation, and real-provider verification scope.
 
+## Pull Request Readiness
+
+Follow [human ownership and readiness](CONTRIBUTING.md#pull-request-ownership-and-readiness)
+when preparing a PR. AI-assisted contributions are welcome; a human must review
+and own the final diff, check the validation evidence and its limitations, and
+explicitly declare the current revision ready for maintainer review.
+
+Keep the PR body concise and current, with the concrete problem, observable
+outcome, approach, and evidence. Report only checks that actually ran as executed;
+distinguish source-derived conclusions, proposed checks, and unavailable coverage.
+Address actionable automated review findings and explain disagreements.
+
+Leave the template's **Author readiness** declarations unchecked for the human
+owner to complete. Never attest to human review on their behalf. Keep the PR in
+draft until the human declares the current diff ready. After further changes,
+clear the ready-for-review checkbox and refresh affected evidence so the human
+can review and renew the declaration. CI and automated review results support
+review; they do not establish human readiness, maintainer scope approval, or
+merge permission.
+
 <!-- BEGIN:turborepo-agent-rules -->
 
 # This is NOT the Turborepo you know
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e80d903a39..c7e109c2bf 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -24,6 +24,48 @@ costs change.
 
 When adding or changing an MCP tool, follow the [tool design guide](docs/tool-design.md) and preserve the canonical contracts and generated catalog.
 
+## Pull request ownership and readiness
+
+AI-assisted contributions are welcome. Every PR must have a human owner who
+takes responsibility for the complete change, including code, tests,
+documentation, and claims produced with AI assistance. The PR author is the
+owner unless another human is named in the PR and explicitly accepts ownership.
+These requirements also apply to maintainer-authored PRs.
+
+Before requesting maintainer review, the human owner must:
+
+- Review the final diff and relevant existing code. Be able to explain the
+  problem, the chosen approach, how it fits REA, and meaningful edge cases.
+- Provide evidence that the change works. Summarize what was checked, the
+  observed results, and meaningful gaps in the PR body. Use focused tests,
+  representative CLI/MCP output, CI artifacts, screenshots, or other checks
+  appropriate to the change. For fixes, show the original failure and why the
+  regression coverage catches it when practical. Documentation-only changes
+  can use source, link, or rendered-document checks. Label source-derived
+  conclusions and proposed checks accurately; never report an unrun check as
+  passing. Follow the [verification requirements](#development-feedback-and-pr-verification)
+  for required checks and real-provider coverage.
+- Complete the **Author readiness** declaration in the PR template, explicitly
+  stating that the current revision is ready for review.
+
+Keep the PR description concise and current. Explain the problem, observable
+outcome, approach, and useful evidence; link long logs or put them in optional
+details. Address actionable automated review findings and explain disagreements.
+Human ownership and review remain required when CI or an automated reviewer
+reports success. Readiness requests maintainer review; it does not grant scope
+approval or permission to merge.
+
+Draft PRs may request early feedback with open questions and incomplete checks.
+Leave the readiness declaration unchecked until the human owner has completed
+it. After further changes, clear the ready-for-review checkbox until the owner
+reviews the updated diff, refreshes affected validation and the PR description,
+and renews the declaration. AI agents must leave human declarations to the human
+owner and must not attest to a human review on their behalf.
+
+Maintainers may return a PR to the author or close it when the problem is
+unsupported, validation is missing, or the owner cannot explain the change.
+Contributors are responsible for completing this work before requesting review.
+
 ## Contribution scope
 
 REA focuses on software structure, runtime behavior, and evidence through