From 9b20ef73e3bf7880de609dc0256966518816905e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 18 May 2026 18:54:00 +0000 Subject: [PATCH 1/2] Initial plan From 2b7c8d587ce4155c60c0bd8790731145811e2c01 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 18 May 2026 19:02:15 +0000 Subject: [PATCH 2/2] fix: add scope-guard, acceptance criteria, and version-bump constraints to prevent PR scope drift - Add Checkpoint 2b (Scope-Guard) to AGENTS.md Critical Requirements: agents must verify branch name, changed files, and PR title all match issue scope before calling report_progress; call report_incomplete if any diverge - Add Acceptance Criteria and Scope Anchoring mandatory section to AGENTS.md: agents extract files/tests/reviewer question from issue before writing code - Update Quick Reference section in AGENTS.md to include Checkpoint 2b - Add Version-Bump Scope Constraint best practice to upgrade-agentic-workflows.md: only update the target version constant and recompile; do not regenerate unrelated artifacts Closes #[this issue] Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .github/aw/upgrade-agentic-workflows.md | 7 +++++ AGENTS.md | 35 ++++++++++++++++++++++++- 2 files changed, 41 insertions(+), 1 deletion(-) diff --git a/.github/aw/upgrade-agentic-workflows.md b/.github/aw/upgrade-agentic-workflows.md index 624195efd90..ee81ffbadd7 100644 --- a/.github/aw/upgrade-agentic-workflows.md +++ b/.github/aw/upgrade-agentic-workflows.md @@ -316,6 +316,13 @@ Attempted to upgrade workflows to gh-aw version [VERSION] but encountered compil - Summarize complex changes clearly - Provide actionable next steps +6. **Version-Bump Scope Constraint** + - When the upgrade task is a version bump (updating the gh-aw version constant or a dependency version), **only** update the target version identifier and recompile + - ❌ Do NOT regenerate agent files, prompt templates, or other artifacts unless the changelog explicitly lists them as changed + - ❌ Do NOT update unrelated workflows or dependencies discovered during the upgrade + - ✅ Limit changes to: the version constant, any `.lock.yml` files produced by recompilation, and files explicitly listed in the changelog as requiring migration + - If recompilation produces unexpected diffs beyond lock files, stop and document what changed before including those diffs in the PR + ## Important Notes - When running in GitHub Copilot Cloud, use the **agentic-workflows** MCP tool for all commands diff --git a/AGENTS.md b/AGENTS.md index 52f5925fa05..48320e268f8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -86,6 +86,16 @@ make agent-finish # Runs build, test, recompile, fmt, lint (full validation) - The formatting check (`go fmt`) is strict and cannot be disabled - PRs that fail CI immediately after opening are closed without merging — a wasted session +#### Checkpoint 2b — Scope-Guard (Before Every `report_progress`) + +**🚨 DO NOT call `report_progress` until you have confirmed scope alignment. Verify all three:** + +1. ✅ The **branch name** reflects the change you actually made +2. ✅ The **changed files** match what the original issue or task description asked for +3. ✅ The **PR title and description** describe the same change as the issue + +**If any of these diverge — stop. Do NOT open the PR.** Call `report_incomplete` instead with a clear explanation of what drifted and why. Scope-mismatched PRs are closed without merging, wasting the entire session. + **If you're in a hurry** and `make agent-finish` takes too long, use the dedicated fast gate: ```bash make agent-report-progress # build + fmt + lint + test-unit @@ -173,6 +183,23 @@ func TestCompile(t *testing.T) { } ``` +### ⚠️ MANDATORY: Acceptance Criteria and Scope Anchoring ⚠️ + +**Before writing a single line of code, establish your acceptance criteria from the issue.** + +When you receive a task (issue, PR comment, or request), extract and write down: + +1. **What files must change** — list the files the issue explicitly mentions or implies. Only touch files in scope. +2. **What tests must pass** — identify which tests cover the changed area; ensure they pass after your changes. +3. **What the reviewer needs to see** — restate the issue's core request in one sentence; your PR description must directly answer that request. + +**Scope anchoring rules:** + +- ❌ Do NOT fix unrelated bugs you discover during implementation (open a separate issue instead) +- ❌ Do NOT regenerate or update files not mentioned in the issue (e.g., compiled artifacts, lock files, generated docs) unless the issue explicitly asks for it +- ❌ Do NOT rename, refactor, or clean up code outside the direct change path +- ✅ If you realize mid-session that the correct fix requires touching more files than originally scoped, stop and document the expanded scope in a comment before proceeding + **ALWAYS USE GITHUB MCP FOR GITHUB API ACCESS WITH COPILOT ENGINE:** The Copilot coding agent **cannot directly access api.github.com**. When using the `copilot` engine, you **must** configure the GitHub MCP server to access GitHub information (repositories, issues, pull requests, etc.). @@ -1244,7 +1271,13 @@ Use **report_progress** to commit, push, and update the PR. Never leave changes 3. ✅ Confirm lint reported zero errors 4. ✅ Only then call `report_progress` -**This is NOT optional** — PRs that fail CI immediately after opening are closed without merging, wasting the entire agent session. +**Checkpoint 2b — Scope-Guard** — Before every `report_progress` call: +1. ✅ Branch name matches what you changed +2. ✅ Changed files match the original issue scope +3. ✅ PR title/description directly answers the original issue +4. ✅ If any of the above diverge, call `report_incomplete` instead + +**This is NOT optional** — PRs that fail CI or diverge from scope are closed without merging, wasting the entire agent session. ### Development Guidelines - Go project with Makefile-managed build/test/lint