Restructure upstream merge prompt steps and enforce docs update gate

Co-authored-by: brunoborges <129743+brunoborges@users.noreply.github.com>

Author: Copilot

.github/prompts/agentic-merge-upstream.prompt.md

@@ -31,11 +31,15 @@ All scripts write/read a `.merge-env` file (git-ignored) to share state (branch
 1. Run `./.github/scripts/upstream-sync/merge-upstream-start.sh` (creates branch, clones upstream, shows summary)
 2. Run `./.github/scripts/upstream-sync/merge-upstream-diff.sh` (analyze changes)
 3. Update README with minimum CLI version requirement
-4. Port changes to Java SDK (commit as you go)
-5. Run `./.github/scripts/build/format-and-test.sh` frequently while porting
-6. Update documentation
-7. Run `./.github/scripts/upstream-sync/merge-upstream-finish.sh` (final test + push)
-8. Finalize Pull Request (see note below about coding agent vs. manual workflow)
+4. Identify upstream changes to port
+5. Apply changes to Java SDK (commit as you go)
+6. Port/adjust tests from upstream changes
+7. Run `./.github/scripts/build/format-and-test.sh` frequently while porting
+8. Build the package
+9. Update documentation (**required for every user-facing upstream change**)
+10. Run `./.github/scripts/upstream-sync/merge-upstream-finish.sh` (final test + push)
+11. Finalize Pull Request (see note below about coding agent vs. manual workflow)
+12. Perform final review before handing off
 
 ---
 
@@ -104,7 +108,7 @@ For each change in the upstream diff, determine:
 
 > **⚠️ Important:** When adding new documentation pages, always update `src/site/site.xml` to include them in the navigation menu.
 
-## Step 7: Apply Changes to Java SDK
+## Step 5: Apply Changes to Java SDK
 
 When porting changes:
 
@@ -168,7 +172,7 @@ Follow the existing Java SDK patterns:
 - **Match the style of surrounding code** - Consistency with existing code is more important than upstream patterns
 - **Prefer existing abstractions** - If the Java SDK already solves a problem differently than .NET, keep the Java approach
 
-## Step 7.5: Port Tests
+## Step 6: Port Tests
 
 After porting implementation changes, **always check for new or updated tests** in the upstream repository:
 
@@ -215,7 +219,7 @@ If tests fail with errors like `TypeError: Cannot read properties of undefined`,
 
 Commit tests separately or together with their corresponding implementation changes.
 
-## Step 8: Format and Run Tests
+## Step 7: Format and Run Tests
 
 After applying changes, use the convenience script:
 
@@ -246,7 +250,7 @@ Or for quicker iteration during porting:
 - **Null handling**: Add null checks where C# had nullable types
 - **JSON serialization**: Verify Jackson annotations are correct
 
-## Step 9: Build the Package
+## Step 8: Build the Package
 
 Once tests pass, build the complete package:
 
@@ -259,9 +263,11 @@ Verify:
 - No warnings (if possible)
 - JAR file is generated in `target/`
 
-## Step 10: Update Documentation
+## Step 9: Update Documentation
 
 **Documentation is critical for new features.** Every new feature ported from upstream must be documented before the merge is complete.
+Do not proceed to the finish/push step until this documentation checklist is complete.
+If you determine no docs changes are needed, explicitly document that decision and rationale in the PR body.
 
 ### Documentation Checklist
 
@@ -316,7 +322,7 @@ Ensure consistency across all documentation files:
 - Code examples should use the same patterns and be tested
 - Links to Javadoc should use correct paths (`apidocs/...`)
 
-## Steps 11-12: Finish, Push, and Finalize Pull Request
+## Steps 10-11: Finish, Push, and Finalize Pull Request
 
 Run the finish script which updates `.lastmerge`, runs a final build, and pushes the branch:
 
@@ -378,7 +384,7 @@ Ports changes from the official Copilot SDK ([github/copilot-sdk](https://github
 - Code formatted with Spotless
 ```
 
-## Step 13: Final Review
+## Step 12: Final Review
 
 Before finishing:
 
@@ -411,6 +417,7 @@ Before finishing:
   - [ ] `src/site/markdown/documentation.md` updated for new basic usage
   - [ ] `src/site/markdown/advanced.md` updated for new advanced features
   - [ ] Javadoc added/updated for new public APIs
+- [ ] If no documentation files were changed, PR body explicitly explains why documentation changes were not needed
 - [ ] `src/site/site.xml` updated if new documentation pages were added
 - [ ] `.lastmerge` file updated with new commit hash
 - [ ] Branch pushed to remote
@@ -429,4 +436,3 @@ Before finishing:
 - Uses JUnit 5 for testing
 - **Java SDK design decisions take precedence over upstream patterns**
 - **Adapt upstream changes to fit Java idioms, not the other way around**
-