test(pull-requests): harden merge SHA pinning

Make the schema and unpinned compatibility coverage explicit, and verify stale-head conflicts surface without a retry.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: SamMorrowDrums

docs/feature-flags.md

@@ -357,7 +357,7 @@ runtime behavior (such as output formatting) won't appear here.
 ### `thread_resolution_reason`
 
 - **pull_request_review_write** - Write operations (create, submit, delete) on pull request reviews
-  - **Required OAuth Scopes**: `repo`
+  - **OAuth Challenge Scopes**: `repo`
   - `body`: Review comment text (string, optional)
   - `commitID`: SHA of commit to review (string, optional)
   - `event`: Review action to perform. (string, optional)

pkg/github/pullrequests_sha_pinning_test.go

@@ -7,18 +7,13 @@ import (
 
 	"github.com/github/github-mcp-server/pkg/translations"
 	"github.com/google/go-github/v89/github"
-	"github.com/google/jsonschema-go/jsonschema"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
 func Test_MergePullRequestSHAPinning(t *testing.T) {
 	serverTool := MergePullRequest(translations.NullTranslationHelper)
 
-	schema := serverTool.Tool.InputSchema.(*jsonschema.Schema)
-	require.Contains(t, schema.Properties, "expectedHeadSha")
-	assert.Equal(t, "string", schema.Properties["expectedHeadSha"].Type)
-
 	const pinnedSHA = "0123456789abcdef0123456789abcdef01234567"
 
 	mockMergeResult := &github.PullRequestMergeResult{
@@ -44,7 +39,7 @@ func Test_MergePullRequestSHAPinning(t *testing.T) {
 			"owner":           "owner",
 			"repo":            "repo",
 			"pullNumber":      float64(42),
-			"merge_method":     "merge",
+			"merge_method":    "merge",
 			"expectedHeadSha": pinnedSHA,
 		})
 
@@ -81,7 +76,7 @@ func Test_MergePullRequestSHAPinning(t *testing.T) {
 			"owner":           "owner",
 			"repo":            "repo",
 			"pullNumber":      float64(42),
-			"merge_method":     "merge",
+			"merge_method":    "merge",
 			"expectedHeadSha": pinnedSHA,
 		})
 
@@ -92,6 +87,7 @@ func Test_MergePullRequestSHAPinning(t *testing.T) {
 
 		require.NoError(t, err)
 		require.True(t, result.IsError)
+		assert.Contains(t, getErrorResult(t, result).Text, "Head branch was modified")
 		assert.Equal(t, 1, calls, "merge must not retry after a head-SHA mismatch")
 	})
 }

pkg/github/pullrequests_test.go

@@ -760,6 +760,7 @@ func Test_MergePullRequest(t *testing.T) {
 	assert.Contains(t, schema.Properties, "commit_title")
 	assert.Contains(t, schema.Properties, "commit_message")
 	assert.Contains(t, schema.Properties, "merge_method")
+	assert.Contains(t, schema.Properties, "expectedHeadSha")
 	assert.ElementsMatch(t, schema.Required, []string{"owner", "repo", "pullNumber"})
 
 	// Setup mock merge result for success case
@@ -778,7 +779,7 @@ func Test_MergePullRequest(t *testing.T) {
 		expectedErrMsg      string
 	}{
 		{
-			name: "successful merge",
+			name: "successful merge without expected head SHA",
 			mockedClient: MockHTTPClientWithHandlers(map[string]http.HandlerFunc{
 				PutReposPullsMergeByOwnerByRepoByPullNumber: expectRequestBody(t, map[string]any{
 					"commit_title":   "Merge PR #42",