Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

docs(contributing): require human ownership and review readiness (#3286)

morluto90d4098a01b6
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 3dec52bd0..10134dd75 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 16a586b18..48b89c2e3 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 e80d903a3..c7e109c2b 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