diff --git a/AGENTS.md b/AGENTS.md index baef988a85..1d10fb44ea 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Start here -Read the [contributor guide](CONTRIBUTING.md) for setup and contribution procedures. +Read and follow all guidance in [CONTRIBUTING.md](CONTRIBUTING.md). Use the [documentation map](docs/README.md) to select current SDK guidance and Foundation validation commands. Follow the module rules and validation tasks below. @@ -274,6 +274,47 @@ To inspect the events the SDK emits from the sample app, use the `android-sdk-ev - When preparing a release changelog: tags reflect customer impact, not change size. Internal-only changes are `[MAINTENANCE]`, not `[IMPROVEMENT]`. Follow the existing entry format: `* [TAG] Description. See [#N](link)`. - When reviewing a release preparation PR (version bump and `CHANGELOG.md` update for a new release), review only the changes the PR itself makes. The release includes changes from PRs that were already reviewed and merged, so don't flag breaking changes or binary incompatibilities that come from them (e.g. a public API diff against the previous release): those were approved in their own PRs. +## Handoff to human review + +Follow the [contributor handoff guidance](CONTRIBUTING.md#handoff-to-human-review) +and the additional agent requirements below when checking whether to prompt the +user to add `ready-for-human-review`. Check at these checkpoints: + +- After opening a PR, pushing changes to it, or marking it ready for review. +- After replying to or resolving the remaining agentic feedback. +- When an agentic review finishes and you inspect its result. +- When the user asks about PR status or readiness for human review. + +After opening a PR, pushing changes, or marking a draft ready, agents must allow +at least five minutes for asynchronous reviews to start before assessing +eligibility. Measure from the latest of these actions and restart the grace period +if the head changes. The grace period alone does not establish eligibility. + +Prompt for the label only when all of these conditions are met: + +- At least one agentic or bot review has completed against the current PR head. No feedback is not evidence that a review occurred; a review of an older revision does not qualify. +- No observed agentic reviews remain queued or running. If an expected review has not appeared, eligibility remains unconfirmed. +- All agentic feedback has been addressed or explicitly dispositioned with evidence, each feedback item has a posted reply, and all associated review threads are resolved, including outdated threads. + +Refresh the current PR head, review activity, feedback, and thread status. Check +all pages of results; if retrieval fails or is incomplete, eligibility remains +unconfirmed. Local fixes, draft replies, or a clean bot summary alone are not +sufficient. Do not resolve unaddressed feedback solely to qualify for the label. + +If eligible and the label is absent, ask: "All agentic feedback has been addressed. +Shall I add `ready-for-human-review`?" Apply the label only after user confirmation, +then recheck the current head and eligibility immediately before labelling. If the +label is already present, do not prompt or add it again. + +If eligibility is unconfirmed, report what remains pending. If the task ends +before the grace period or reviews complete, report the deferred check; do not +claim readiness or imply that monitoring will continue without a separately +arranged follow-up. + +This instruction does not independently authorise posting replies, resolving +threads, pushing, or merging; follow the applicable approval requirements for +those actions. Carry this rule into delegated PR work and PR automations. + # Dogfooding Branch `dogfooding` is managed only through the scripts in `ci/scripts/dogfooding/`; read `ci/scripts/dogfooding/README.md` before helping with it. Never push to `dogfooding`, open a PR from a feature branch into it, or merge into it with squash or rebase: use `feature.sh`, `sync.sh` and `reset.sh`, which open the PRs. The only change made by hand is reverting a feature's dogfood merges, as described in the README's "Remove a single feature". Show the command and ask before running the scripts, since they push branches and open PRs. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4072bc6cb4..2f233d33be 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -181,6 +181,27 @@ Make sure that your code is clean and readable, that your commits are small and atomic, with a proper commit message. We tend to use [gitmoji](https://gitmoji.carloscuesta.me/), but this is not mandatory. +### Handoff to human review + +Before applying the `ready-for-human-review` label, verify that at least one +agentic or bot review has completed against the current PR head and that no +agentic reviews remain queued or running. No feedback does not prove that a +review occurred, and a review of an older revision does not qualify. If an +expected review has not appeared, eligibility remains unconfirmed. + +Address all agentic review feedback or explain with evidence why a suggestion +does not apply. Reply to each feedback item and resolve its associated review +thread, including outdated threads. +Check the latest PR revision, feedback, and thread status before applying the label; +local fixes, draft replies, or a clean bot summary alone are not sufficient. + +Apply the existing label once these conditions are met so reviewers know it is +their turn. If you do not have permission to label the PR, ask a maintainer to +apply it. Do not resolve un-addressed feedback solely to qualify for the label. + +The label indicates that agentic feedback has been addressed. It does not replace +human approval or required CI and merge checks. + ## Coding Conventions Our repository uses Kotlin, as it is now the recommended language for Android.