Send AI-Made Pull Requests to an Open-Source Framework Under Human Review

## Label AI Work and Push Only to Branches the Agent Created Treat external writes, issue ownership, branches, and attribution as controlled actions. - Clearly identify AI-generated pull-request descriptions, review comments, and issue comments, and name the human operator when the project requires it. - Resolve the operator or author through an authenticated source. Never guess an identity; omit it if lookup fails. - Add the required AI co-authorship trailer to AI-assisted commits. - Do not open more than 10 pull requests per operator per day when that is the project limit; favor a few complete, well-tested changes. - Work only on eligible, unassigned issues. Assign the issue to the operator and move it into the active state before implementation. - Push only to a branch the agent created. Do not push to a contributor's branch without explicit permission. - Prefer a personal fork over cluttering the upstream repository, use a useful branch name with the topic and issue identifier, and remove the branch after merge or rejection. Keep pull-request metadata current. After each push, update the title and description so they still describe the complete changeset. ## Read the Code History and Past Issues Before Changing Code Do not assume that code which looks wrong is defective. Long-lived systems often encode prior constraints that are invisible in the current implementation. 1. Reproduce and validate the reported problem; challenge incomplete or mistaken assumptions. 2. Inspect file history and blame information, then read relevant commit messages and linked issues to understand why the code exists. 3. Search related issues for rejected approaches, prior discussions, and intentional decisions. 4. Read the design documents for the affected area, especially for security, telemetry, logging context, and public naming contracts. 5. If one module replaced another, distinguish intentional changes from accidental omissions. 6. If the proposed fix reverses an intentional earlier change, stop and reconsider. If reversal remains justified, explain why despite the original rationale. Present findings, risks, ambiguities, and possible invalidity to the operator before implementation. Apply the same rigor when reviewing a pull request. Verify current external dependency versions, releases, and behavior through authoritative sources. Never make authoritative claims about changing external projects from model training knowledge alone. ## Replace Fixed Sleeps in Tests with Waits That Have a Time Limit Never use fixed sleeps in tests. They make tests slow, flaky, and nondeterministic. - For a component with native timed assertions, use those assertions for conditions it already represents. - Use an asynchronous waiting utility for other conditions, such as waiting for an intermediate count before the next action. - Do not wrap a native blocking assertion with a polling utility; that adds redundant polling around an existing latch. - Always set an explicit maximum timeout when using a waiting utility. - Use an asserted condition or a clear predicate, never a busy-wait loop. - When modifying a test that contains a fixed sleep, migrate it to the native timed assertion or the general waiting utility. For example, `MockEndpoint.assertIsSatisfied()` already waits internally, while Awaitility is appropriate for conditions `MockEndpoint` cannot express. New tests must not introduce `Thread.sleep()`. ## Decide Who Is Trusted and Report Vulnerabilities Privately Use the project's canonical threat model to decide who is trusted, where trust boundaries lie, and what belongs to the framework. - Treat code authors and deployment operators as trusted when they intentionally configure executable routes, expressions, secrets, network exposure, and runtime settings. - Treat external message senders and all data flowing through a trusted route as untrusted. - The framework must not transform untrusted data into code execution, file reads, request forgery, or authorization bypass by itself. - Intentional code execution by a trusted author, operator misconfiguration, and dangerous behavior enabled through explicit opt-in are not framework vulnerabilities by themselves. Valid findings demonstrate a trust-boundary breach in a default or reasonably expected configuration. Typical classes include unsafe deserialization, XXE, expression injection, path traversal, SSRF, header-dispatch abuse, authentication or authorization bypass, secret disclosure, insecure defaults, and injection into framework-built queries. Resource exhaustion without required controls, deliberately exposed administration surfaces, unreachable transitive dependency findings, and scanner output without a proof of boundary breach are normally outside framework scope. Never disclose a suspected vulnerability through a public issue, pull request, mailing list, or other public channel. Follow the private reporting process and stop public work. ## Block Unsafe Incoming Data and Keep Risky Security Defaults Off Review every consumer, parser, data format, type converter, aggregation store, and security-relevant option against concrete abuse paths. - Filter framework-internal headers from untrusted inbound messages with a strict, case-insensitive strategy before dispatch. - Do not deserialize untrusted objects without an appropriate input filter. - Mark secrets as secret metadata and classify unsafe configuration switches by their risk family. - Keep security-sensitive defaults denied unless explicitly enabled. Relaxing a default requires an upgrade note and explicit maintainer approval. - Verify that authentication and authorization options enforce issuer, audience, signature, and every advertised sub-path they claim to protect. For deployments, use the production security profile, resolve secrets through an approved vault, configure verified TLS, disable unsafe serialization on untrusted consumers, and keep management consoles and runtime administration on trusted networks. Security review must distinguish trusted route behavior from framework behavior while still preventing untrusted data from crossing the boundary. ## Add Tests and User Docs to Every Change and Commit Generated Files Every feature or bug fix must include appropriate tests and user-facing documentation. Document changed defaults, discovery behavior, renamed or removed options, header changes, API or SPI changes, deprecations, and migrations in the relevant guide. - Run the repository's canonical formatting, import-order, style, unit-test, integration-test, and source checks for the changed surface. - Regenerate and commit generated artifacts; do not leave generated changes for CI to discover. - Avoid new static-analysis defects, maintainability regressions, common weakness patterns, and deprecated APIs even when a local validation job does not run every analyzer. - Import classes and use simple names instead of fully qualified class names, except when two classes share the same simple name. Preserve explicit generated-code exclusions. - Add the required introduction-version tag to every new public API type and method, use the upcoming release version, and place it after other documentation tags. - Update every metadata registry that discovers nested extensions; a source directory alone may not make an extension visible to builds, catalogs, or generated documentation. - For integration-test containers, verify every supported architecture. Use an approved registry mirror or explicit architecture-specific skips when no image exists. - Use internal documentation references for internal pages and verify cross-version anchors against the released target, not only the development branch. When deprecating a feature, update build metadata, API annotations, the documentation title, and the upgrade guide together. ## Get Two Reviewers and One Human Approval Before Merging Request review only when a pull request is ready, never while it remains a draft. - Identify relevant active maintainers from recent file history and blame data, then request at least 2 appropriate reviewers. - After addressing all comments and restoring green checks, request review again from the existing reviewers. - Never merge while any review conversation remains unresolved. - Require at least 1 human approval and never approve the agent's own pull request. - Derive the release milestone from the target branch, then set both milestone and issue fix version before closing the issue. - Resolve the pull-request author programmatically, assign the pull request and issue correctly, and apply the category label supported by the issue and change. - Gate publication and merge behind one successful chain of formatting, type, lint, test, and security checks. - Preserve required AI co-authorship in the final merge commit. - After merge, resolve the issue with the fix version and a link to the pull request, then remove the branch. Summarize user-visible behavior, meaningful validation, documentation impact, unresolved risk, and any check that could not run. A local test does not prove CI success, and incomplete evidence does not justify release readiness.