From d081199aa3874df68a5e487cb2192656e0f2bf18 Mon Sep 17 00:00:00 2001 From: Uriah Finkel Date: Tue, 25 Aug 2026 12:27:55 +0300 Subject: [PATCH] Add agent PR completion protocol --- AGENTS.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 319c1053..989c8ec0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -83,3 +83,36 @@ This project uses `ty` for type checking. Run: ```bash uv run ty check src tests ``` + +## PR completion protocol + +Do not consider an implementation task complete merely because code has been pushed or a pull request has been opened. + +After creating or updating a pull request: + +1. Inspect all required GitHub Actions checks for the current PR head. +2. If checks are still running, re-check them while the session is active rather than handing the PR back to the user for manual monitoring. +3. If a required check fails, inspect the failing job and logs and determine whether the failure is caused by the PR. +4. If the fix is within the stated task scope, make the fix, push it, and inspect CI again. +5. Repeat the diagnose/fix/re-check loop until all required checks pass or a genuine blocker requires user input. + +Escalate to the user only when resolving the failure would require one or more of the following: + +- changing frozen statistical semantics, contracts, or architecture; +- broadening the agreed task scope; +- weakening or removing a meaningful test or quality gate; +- changing a public API or backward-compatibility promise beyond the task; +- making a product or technical decision with multiple legitimate choices; +- resolving an external service, permissions, infrastructure, or credential problem that the agent cannot fix safely. + +Routine failures such as lint errors, formatting errors, test regressions caused by the PR, snapshots/fixtures that legitimately need updating, packaging errors, documentation-build errors, and similar mechanical issues should be fixed without asking the user to manually inspect GitHub Actions. + +The final handoff should include: + +- pull request link; +- final PR head commit; +- tests/checks run locally when applicable; +- final GitHub Actions status; +- any remaining caveats or blockers. + +Do not ask the user to manually check whether CI passed.