From 1c6f97d758a7c0b7eefe26f46e2544a454284d04 Mon Sep 17 00:00:00 2001
From: Ed Burns <edburns@microsoft.com>
Date: Mon, 4 May 2026 16:47:34 -0400
Subject: [PATCH] Add guardrails to prevent reference-impl-sync agent from
 skipping deterministic scripts

.github/workflows/reference-impl-sync.md
  - Replace vague "Follow the prompt" instruction in the issue body template
    with explicit mandates: read the prompt file in full, do not clone the
    reference implementation manually, do not update .lastmerge manually,
    do not skip the finish script.

.github/workflows/build-test.yml
  - Add "Validate reference-impl-sync completeness" step to the java-sdk job.
    Only runs on PRs labeled reference-impl-sync.
  - Check 1: .lastmerge must appear in the PR diff (proves finish script ran).
  - Check 2: if scripts/codegen/ changed, src/generated/java/ must also have
    changed (proves codegen ran when the schema version was bumped).
---
 .github/workflows/build-test.yml         | 33 ++++++++++++++++++++++++
 .github/workflows/reference-impl-sync.md |  8 +++++-
 2 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/build-test.yml b/.github/workflows/build-test.yml
index 1143634f6..9154375a9 100644
--- a/.github/workflows/build-test.yml
+++ b/.github/workflows/build-test.yml
@@ -89,6 +89,39 @@ jobs:
           COPILOT_CLI_PATH: ${{ steps.setup-copilot.outputs.path }}
         run: mvn verify
 
+      - name: Validate reference-impl-sync completeness
+        if: >-
+          github.event_name == 'pull_request' &&
+          contains(github.event.pull_request.labels.*.name, 'reference-impl-sync')
+        run: |
+          git fetch origin main --depth=1
+          CHANGED=$(git diff --name-only origin/main...HEAD)
+
+          # 1. .lastmerge must be updated (proves finish script ran)
+          if echo "$CHANGED" | grep -q '^\\.lastmerge$'; then
+            echo "✅ .lastmerge was updated (finish script ran)"
+          else
+            echo "❌ .lastmerge was not updated. The merge-reference-impl-finish.sh script"
+            echo "   must be run before this PR can merge. This script updates .lastmerge,"
+            echo "   syncs the CLI version in pom.xml, and syncs scripts/codegen/package.json."
+            exit 1
+          fi
+
+          # 2. If codegen inputs changed, generated output must also have changed
+          if echo "$CHANGED" | grep -q '^scripts/codegen/'; then
+            if echo "$CHANGED" | grep -q '^src/generated/java/'; then
+              echo "✅ Codegen inputs changed and generated files were regenerated"
+            else
+              echo "❌ scripts/codegen/ was updated but src/generated/java/ has no changes."
+              echo "   The Codegen Check workflow should regenerate these files automatically."
+              echo "   If it hasn't run yet, wait for it to complete and push regenerated files."
+              echo "   Or run manually: cd scripts/codegen && npm ci && npm run generate"
+              exit 1
+            fi
+          else
+            echo "✅ No codegen input changes — regeneration not needed"
+          fi
+
       - name: Upload test results for site generation
         if: success() && github.ref == 'refs/heads/main'
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
diff --git a/.github/workflows/reference-impl-sync.md b/.github/workflows/reference-impl-sync.md
index 15e66abef..8e77f1a18 100644
--- a/.github/workflows/reference-impl-sync.md
+++ b/.github/workflows/reference-impl-sync.md
@@ -104,7 +104,13 @@ Go to Step 3b.
 
      ### Instructions
 
-     Follow the [agentic-merge-reference-impl](.github/prompts/agentic-merge-reference-impl.prompt.md) prompt to port these changes to the Java SDK.
+     **You MUST follow these steps in order. Do NOT improvise or skip scripts.**
+
+     1. ✅✅Read [.github/prompts/agentic-merge-reference-impl.prompt.md](.github/prompts/agentic-merge-reference-impl.prompt.md) in full before starting✅✅
+
+     ❌❌Do NOT clone the reference implementation manually — the start script does this.❌❌
+     ❌❌Do NOT update .lastmerge manually — the finish script does this.❌❌
+     ❌❌Do NOT skip the finish script — it syncs codegen versions and updates .lastmerge.❌❌
      ```
 4. After creating the issue, use the `assign_to_agent` safe-output tool to assign Copilot to the newly created issue.