fix(nit): align CommitID field in vcs/types.go and document no-op in github/review.go

Add CommitID field to vcs.ReviewRequest so the commit anchor propagates
through the vcs.Client interface to platform adapters.

Changes:
- vcs/types.go: Add CommitID string field to ReviewRequest
- gitea/client.go: Add commitID parameter to PostReview, include in API payload
- gitea/adapter.go: Pass req.CommitID to underlying client
- github/review.go: Use req.CommitID as primary, fall back to comment-level
- cmd/review-bot/main.go: Set CommitID on ReviewRequest from pr.Head.SHA

Fixes #114

cmd/review-bot/main.go

@@ -2,7 +2,6 @@ package main
 
 import (
 	"context"
-	"errors"
 	"flag"
 	"fmt"
 	"log/slog"
@@ -85,16 +84,9 @@ func main() {
 	aicoreAPIURL := flag.String("aicore-api-url", envOrDefault("AICORE_API_URL", ""), "SAP AI Core API URL (for provider=aicore)")
 	aicoreResourceGroup := flag.String("aicore-resource-group", envOrDefault("AICORE_RESOURCE_GROUP", "default"), "SAP AI Core resource group (for provider=aicore)")
 
-	// Register --gitea-url as a backward-compatible alias for --vcs-url.
-	// StringVar shares the *string pointer with vcsURL, so whichever flag is
-	// set last by flag.Parse wins — both point to the same underlying value.
-	// NOTE: If a user passes both --vcs-url and --gitea-url, the last one on
-	// the command line takes effect (standard flag package behavior). This is
-	// acceptable since --gitea-url is deprecated and both serve the same purpose.
-	//
-	// ORDERING: This must remain AFTER vcsURL's flag.String declaration and BEFORE
-	// flag.Parse(). The *vcsURL dereference captures the env-var-resolved default
-	// at registration time; moving flag.Parse() above this line would break it.
+	// Backward-compatible alias: --gitea-url shares vcsURL's pointer (last flag wins).
+	// Must use *vcsURL as default: StringVar sets *p=value at registration, so empty
+	// string would overwrite the env-resolved value from the --vcs-url declaration.
 	flag.StringVar(vcsURL, "gitea-url", *vcsURL, "Deprecated: use --vcs-url instead")
 
 	flag.Parse()
@@ -110,10 +102,8 @@ func main() {
 	slog.Info("review-bot starting", "version", version)
 
 	// Validate VCS provider
-	switch *provider {
-	case "gitea", "github":
-		// valid
-	default:
+	vcsProvider := vcs.VCSProvider(*provider)
+	if !vcsProvider.Valid() {
 		fmt.Fprintf(os.Stderr, "Error: invalid --provider %q (valid: gitea, github)\n", *provider)
 		os.Exit(1)
 	}
@@ -126,7 +116,7 @@ func main() {
 		os.Exit(1)
 	}
 	// --vcs-url is required only for gitea provider
-	if *provider == "gitea" && *vcsURL == "" {
+	if vcsProvider == vcs.ProviderGitea && *vcsURL == "" {
 		fmt.Fprintf(os.Stderr, "Error: --vcs-url (or --gitea-url) is required for provider=gitea\n")
 		os.Exit(1)
 	}
@@ -169,18 +159,16 @@ func main() {
 
 	// Initialize VCS client
 	var client vcs.Client
-	switch *provider {
-	case "gitea":
+	switch vcsProvider {
+	case vcs.ProviderGitea:
 		giteaClient := gitea.NewClient(*vcsURL, *reviewerToken)
 		client = gitea.NewAdapter(giteaClient)
-	case "github":
-		ghBaseURL := *baseURL
-		if ghBaseURL == "" {
-			ghBaseURL = "https://api.github.com"
-		}
-		client = github.NewClient(*reviewerToken, ghBaseURL)
+	case vcs.ProviderGitHub:
+		client = github.NewClient(*reviewerToken, *baseURL)
+	default:
+		panic("unreachable: provider validation should have caught " + vcsProvider.String())
 	}
-	slog.Info("VCS client initialized", "provider", *provider)
+	slog.Info("VCS client initialized", "provider", vcsProvider)
 
 	// Initialize LLM client
 	llmClient := llm.NewClient(*llmBaseURL, *llmAPIKey, *llmModel)
@@ -497,6 +485,7 @@ func main() {
 	reviewReq := vcs.ReviewRequest{
 		Body:     reviewBody,
 		Event:    event,
+		CommitID: pr.Head.SHA,
 		Comments: inlineComments,
 	}
 	posted, err := client.PostReview(ctx, owner, repoName, prNumber, reviewReq)
@@ -506,11 +495,15 @@ func main() {
 	}
 	slog.Info("review posted", "review_id", posted.ID, "user", posted.User.Login, "pr", prNumber)
 
-	// Supersede all old reviews
+	// Supersede all old reviews via optional interface
 	if len(oldReviews) > 0 {
-		if err := supersedeOldReviews(ctx, client, *provider, *vcsURL, owner, repoName, prNumber, oldReviews, posted.ID, sentinel); err != nil {
-			slog.Error("failed to supersede old reviews", "error", err)
-			os.Exit(1)
+		if superseder, ok := client.(vcs.ReviewSuperseder); ok {
+			if err := superseder.SupersedeReviews(ctx, owner, repoName, prNumber, oldReviews, posted.ID, *vcsURL, sentinel); err != nil {
+				slog.Error("failed to supersede old reviews", "error", err)
+				os.Exit(1)
+			}
+		} else {
+			slog.Error("provider does not support review superseding", "provider", vcsProvider)
 		}
 	}
 }
@@ -527,88 +520,6 @@ func verdictToEvent(verdict string) vcs.ReviewEvent {
 	}
 }
 
-// supersedeOldReviews marks prior reviews as superseded so only the latest review is visible.
-// For GitHub: dismisses old reviews (vcsURL is unused in this path).
-// For Gitea: edits the review body with a link to the new review and resolves inline comments.
-//
-// The vcsURL parameter is only used in the Gitea path to construct review permalink URLs;
-// it is accepted unconditionally to keep the function signature uniform across providers.
-func supersedeOldReviews(ctx context.Context, client vcs.Client, provider, vcsURL, owner, repoName string, prNumber int, oldReviews []vcs.Review, newReviewID int64, sentinel string) error {
-	switch provider {
-	case "github":
-		// Best-effort dismissal: attempt all reviews, join any errors.
-		var errs []error
-		for _, old := range oldReviews {
-			if err := client.DismissReview(ctx, owner, repoName, prNumber, old.ID, "Superseded by new review"); err != nil {
-				slog.Warn("failed to dismiss review", "id", old.ID, "error", err)
-				errs = append(errs, fmt.Errorf("dismiss review %d: %w", old.ID, err))
-			} else {
-				slog.Info("dismissed old review", "review_id", old.ID, "new_review_id", newReviewID, "pr", prNumber)
-			}
-		}
-		return errors.Join(errs...)
-	case "gitea":
-		// Continue to Gitea-specific logic below the switch.
-	default:
-		return fmt.Errorf("supersedeOldReviews: unsupported provider %q", provider)
-	}
-
-	// The type assertion below is guaranteed to succeed: the caller's provider switch
-	// ensures we only reach this point when provider == "gitea", and the gitea provider
-	// always constructs a *gitea.Adapter. The !ok branch guards against future refactors
-	// (e.g. wrapping the adapter in a decorator) that would silently break this path.
-	giteaAdapter, ok := client.(*gitea.Adapter)
-	if !ok {
-		return fmt.Errorf("expected gitea.Adapter for gitea provider, got %T", client)
-	}
-	underlying := giteaAdapter.Underlying()
-
-	// Validate vcsURL scheme before embedding in Markdown link (defense-in-depth).
-	if !strings.HasPrefix(vcsURL, "http://") && !strings.HasPrefix(vcsURL, "https://") {
-		return fmt.Errorf("supersedeOldReviews: vcsURL must have http or https scheme, got %q", vcsURL)
-	}
-	newReviewURL := fmt.Sprintf("%s/%s/%s/pulls/%d#pullrequestreview-%d", strings.TrimRight(vcsURL, "/"), owner, repoName, prNumber, newReviewID)
-	for _, oldReview := range oldReviews {
-		cid, err := underlying.GetTimelineReviewCommentIDForReview(ctx, owner, repoName, prNumber, oldReview.ID)
-		if err != nil {
-			slog.Warn("could not find comment ID for old review", "review_id", oldReview.ID, "error", err)
-			continue
-		}
-		supersededBody := buildSupersededBody(oldReview.Body, oldReview.CommitID, newReviewURL, sentinel)
-		if err := underlying.EditComment(ctx, owner, repoName, cid, supersededBody); err != nil {
-			slog.Warn("could not mark old review as superseded", "review_id", oldReview.ID, "comment_id", cid, "error", err)
-			continue
-		}
-		slog.Info("marked old review as superseded", "review_id", oldReview.ID, "new_review_id", newReviewID, "pr", prNumber)
-
-		// Resolve old review's inline comments
-		oldComments, err := underlying.ListReviewComments(ctx, owner, repoName, prNumber, oldReview.ID)
-		if err != nil {
-			slog.Warn("could not list old review comments for resolution", "review_id", oldReview.ID, "error", err)
-			continue
-		}
-		resolved, failed := 0, 0
-		for _, c := range oldComments {
-			if c.ID == 0 {
-				continue
-			}
-			if err := underlying.ResolveComment(ctx, owner, repoName, c.ID); err != nil {
-				slog.Debug("could not resolve inline comment", "comment_id", c.ID, "error", err)
-				failed++
-			} else {
-				resolved++
-			}
-		}
-		if resolved > 0 {
-			slog.Info("resolved old inline comments", "review_id", oldReview.ID, "count", resolved, "pr", prNumber)
-		}
-		if failed > 0 {
-			slog.Warn("some inline comments could not be resolved", "review_id", oldReview.ID, "failed", failed, "pr", prNumber)
-		}
-	}
-	return nil
-}
-
 // fetchFileContext fetches the full content of modified files from the PR branch.
 func fetchFileContext(ctx context.Context, client vcs.PRReader, owner, repo, ref string, files []vcs.ChangedFile) string {
 	var sb strings.Builder
@@ -636,7 +547,7 @@ func fetchFileContext(ctx context.Context, client vcs.PRReader, owner, repo, ref
 // patternsRepo is comma-separated list of owner/name repos.
 // patternsFiles is comma-separated list of file paths or directories.
 // If a path ends with / or is a directory, all files within it are fetched recursively.
-// If patternsFiles is empty, all files from the repo root are fetched.
+// Empty entries in patternsFiles are skipped (no implicit repo-root fetch).
 func fetchPatterns(ctx context.Context, client vcs.FileReader, patternsRepo, patternsFiles string) string {
 	var sb strings.Builder
 
@@ -812,31 +723,6 @@ func validateWorkspacePath(path, pathName string) (string, error) {
 	return resolvedPath, nil
 }
 
-// buildSupersededBody creates the body for a superseded review: struck-through banner
-// with collapsed original content and the commit it was evaluated against.
-func buildSupersededBody(originalBody, commitSHA, newReviewURL, sentinel string) string {
-	shortSHA := commitSHA
-	if len(shortSHA) > 8 {
-		shortSHA = shortSHA[:8]
-	}
-	var sb strings.Builder
-	sb.WriteString("~~Original review~~\n\n")
-	sb.WriteString("**Superseded** \u2014 [see current review](")
-	sb.WriteString(newReviewURL)
-	sb.WriteString(") for up-to-date findings.\n\n")
-	if shortSHA != "" {
-		sb.WriteString("<details><summary>Previous findings (commit ")
-		sb.WriteString(shortSHA)
-		sb.WriteString(")</summary>\n\n")
-	} else {
-		sb.WriteString("<details><summary>Previous findings</summary>\n\n")
-	}
-	sb.WriteString(originalBody)
-	sb.WriteString("\n\n</details>\n\n")
-	sb.WriteString(sentinel)
-	return sb.String()
-}
-
 // hasSharedToken detects if another review-bot role posted under the same
 // VCS user. This indicates misconfiguration where two roles share a token
 // instead of having separate accounts. Returns true if shared token

cmd/review-bot/main_test.go

@@ -162,54 +162,6 @@ func makeReview(id int64, login, state string, stale bool, body string) vcs.Revi
 	}
 }
 
-func TestBuildSupersededBody(t *testing.T) {
-	original := "# Review\n\nLooks good.\n\n<!-- review-bot:sonnet -->"
-	sentinel := "<!-- review-bot:sonnet -->"
-	newURL := "https://gitea.example.com/owner/repo/pulls/1#pullrequestreview-99"
-
-	result := buildSupersededBody(original, "abcdef1234567890", newURL, sentinel)
-
-	// Should contain the struck-through banner
-	if !strings.Contains(result, "~~Original review~~") {
-		t.Error("missing struck-through banner")
-	}
-	// Should contain superseded notice with link
-	if !strings.Contains(result, "**Superseded**") {
-		t.Error("missing superseded notice")
-	}
-	if !strings.Contains(result, "[see current review]("+newURL+")") {
-		t.Error("missing link to new review")
-	}
-	// Should contain collapsed original
-	if !strings.Contains(result, "<details>") {
-		t.Error("missing details/collapse")
-	}
-	// Should contain short commit SHA
-	if !strings.Contains(result, "abcdef12") {
-		t.Error("missing short SHA")
-	}
-	// Should NOT contain full SHA
-	if strings.Contains(result, "abcdef1234567890") {
-		t.Error("should truncate SHA to 8 chars")
-	}
-	// Should contain the original body inside details
-	if !strings.Contains(result, original) {
-		t.Error("original body not preserved in collapsed section")
-	}
-	// Should end with sentinel
-	if !strings.Contains(result, sentinel) {
-		t.Error("missing sentinel")
-	}
-}
-
-func TestBuildSupersededBodyShortSHA(t *testing.T) {
-	// Short SHA should pass through without panic
-	result := buildSupersededBody("body", "abc", "https://example.com/review", "<!-- review-bot:x -->")
-	if !strings.Contains(result, "abc") {
-		t.Error("short SHA not preserved")
-	}
-}
-
 func TestHasSharedToken(t *testing.T) {
 	tests := []struct {
 		name     string

gitea/adapter.go

@@ -3,6 +3,8 @@ package gitea
 import (
 	"context"
 	"fmt"
+	"log/slog"
+	"strings"
 
 	"gitea.weiker.me/rodin/review-bot/vcs"
 )
@@ -168,9 +170,9 @@ func (a *Adapter) PostReview(ctx context.Context, owner, repo string, number int
 			if err != nil {
 				return nil, fmt.Errorf("translate position %d in %s: %w", c.Position, c.Path, err)
 			}
-			// CommitID from vcs.ReviewComment is intentionally not forwarded:
-			// Gitea review comments are pinned to the PR head SHA automatically,
-			// and the CreatePullReview API has no per-comment commit_id field.
+			// Per-comment CommitID is not forwarded to Gitea inline comments:
+			// Gitea's CreatePullReview API has no per-comment commit_id field.
+			// The review-level commit anchor is set via req.CommitID instead.
 			giteaComments = append(giteaComments, ReviewComment{
 				Path:        c.Path,
 				NewPosition: int64(lineNum),
@@ -179,7 +181,7 @@ func (a *Adapter) PostReview(ctx context.Context, owner, repo string, number int
 		}
 	}
 
-	review, err := a.client.PostReview(ctx, owner, repo, number, event, req.Body, giteaComments)
+	review, err := a.client.PostReview(ctx, owner, repo, number, event, req.Body, req.CommitID, giteaComments)
 	if err != nil {
 		return nil, fmt.Errorf("post review: %w", err)
 	}
@@ -237,3 +239,78 @@ func (a *Adapter) GetAuthenticatedUser(ctx context.Context) (string, error) {
 func (a *Adapter) RequestReviewerSelf(ctx context.Context, owner, repo string, number int, user string) error {
 	return a.client.RequestReviewer(ctx, owner, repo, number, user)
 }
+
+// Compile-time interface conformance assertion for ReviewSuperseder.
+var _ vcs.ReviewSuperseder = (*Adapter)(nil)
+
+// SupersedeReviews marks prior reviews as superseded by editing their body with a
+// link to the new review and resolving their inline comments. This is Gitea-specific
+// behavior that has no GitHub equivalent (GitHub uses DismissReview instead).
+//
+// baseURL is the Gitea instance URL used to construct review permalink URLs.
+// sentinel is the HTML comment sentinel that identifies reviews belonging to this reviewer.
+func (a *Adapter) SupersedeReviews(ctx context.Context, owner, repo string, prNumber int, oldReviews []vcs.Review, newReviewID int64, baseURL, sentinel string) error {
+	// Validate baseURL scheme before embedding in Markdown link (defense-in-depth).
+	if !strings.HasPrefix(baseURL, "http://") && !strings.HasPrefix(baseURL, "https://") {
+		return fmt.Errorf("SupersedeReviews: baseURL must have http or https scheme, got %q", baseURL)
+	}
+
+	underlying := a.client
+
+	newReviewURL := fmt.Sprintf("%s/%s/%s/pulls/%d#pullrequestreview-%d",
+		strings.TrimRight(baseURL, "/"), owner, repo, prNumber, newReviewID)
+
+	for _, oldReview := range oldReviews {
+		cid, err := underlying.GetTimelineReviewCommentIDForReview(ctx, owner, repo, prNumber, oldReview.ID)
+		if err != nil {
+			slog.Warn("could not find comment ID for old review", "review_id", oldReview.ID, "error", err)
+			continue
+		}
+		supersededBody := buildSupersededBody(oldReview.Body, oldReview.CommitID, newReviewURL, sentinel)
+		if err := underlying.EditComment(ctx, owner, repo, cid, supersededBody); err != nil {
+			slog.Warn("could not mark old review as superseded", "review_id", oldReview.ID, "error", err)
+			continue
+		}
+
+		// Resolve old review's inline comments
+		oldComments, err := underlying.ListReviewComments(ctx, owner, repo, prNumber, oldReview.ID)
+		if err != nil {
+			slog.Warn("could not list old review comments for resolution", "review_id", oldReview.ID, "error", err)
+			continue
+		}
+		for _, c := range oldComments {
+			if c.ID == 0 {
+				continue
+			}
+			if err := underlying.ResolveComment(ctx, owner, repo, c.ID); err != nil {
+				slog.Debug("could not resolve inline comment", "comment_id", c.ID, "error", err)
+			}
+		}
+	}
+	return nil
+}
+
+// buildSupersededBody creates the body for a superseded review: struck-through banner
+// with collapsed original content and the commit it was evaluated against.
+func buildSupersededBody(originalBody, commitSHA, newReviewURL, sentinel string) string {
+	shortSHA := commitSHA
+	if len(shortSHA) > 8 {
+		shortSHA = shortSHA[:8]
+	}
+	var sb strings.Builder
+	sb.WriteString("~~Original review~~\n\n")
+	sb.WriteString("**Superseded** \u2014 [see current review](")
+	sb.WriteString(newReviewURL)
+	sb.WriteString(") for up-to-date findings.\n\n")
+	if shortSHA != "" {
+		sb.WriteString("<details><summary>Previous findings (commit ")
+		sb.WriteString(shortSHA)
+		sb.WriteString(")</summary>\n\n")
+	} else {
+		sb.WriteString("<details><summary>Previous findings</summary>\n\n")
+	}
+	sb.WriteString(originalBody)
+	sb.WriteString("\n\n</details>\n\n")
+	sb.WriteString(sentinel)
+	return sb.String()
+}

gitea/adapter_test.go

@@ -408,3 +408,73 @@ func TestAdapter_RequestReviewerSelf(t *testing.T) {
 		t.Fatalf("RequestReviewerSelf() error = %v", err)
 	}
 }
+
+func TestAdapter_PostReview_CommitID_Threading(t *testing.T) {
+	var gotPayload struct {
+		Body     string `json:"body"`
+		Event    string `json:"event"`
+		CommitID string `json:"commit_id"`
+	}
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		json.NewDecoder(r.Body).Decode(&gotPayload)
+		json.NewEncoder(w).Encode(map[string]any{
+			"id":        1,
+			"body":      "test",
+			"user":      map[string]any{"login": "bot"},
+			"commit_id": "abc123def456",
+		})
+	}))
+	defer server.Close()
+
+	client := gitea.NewClient(server.URL, "token")
+	adapter := gitea.NewAdapter(client)
+
+	review, err := adapter.PostReview(context.Background(), "owner", "repo", 1, vcs.ReviewRequest{
+		Body:     "LGTM",
+		Event:    vcs.ReviewEventApprove,
+		CommitID: "abc123def456",
+		// No comments → no diff fetch needed
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotPayload.CommitID != "abc123def456" {
+		t.Errorf("commit_id = %q, want %q", gotPayload.CommitID, "abc123def456")
+	}
+	if review.CommitID != "abc123def456" {
+		t.Errorf("review.CommitID = %q, want %q", review.CommitID, "abc123def456")
+	}
+}
+
+func TestAdapter_PostReview_EmptyCommitID_Omitted(t *testing.T) {
+	var gotRawPayload map[string]any
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		json.NewDecoder(r.Body).Decode(&gotRawPayload)
+		json.NewEncoder(w).Encode(map[string]any{
+			"id":   1,
+			"body": "test",
+			"user": map[string]any{"login": "bot"},
+		})
+	}))
+	defer server.Close()
+
+	client := gitea.NewClient(server.URL, "token")
+	adapter := gitea.NewAdapter(client)
+
+	_, err := adapter.PostReview(context.Background(), "owner", "repo", 1, vcs.ReviewRequest{
+		Body:  "looks good",
+		Event: vcs.ReviewEventComment,
+		// CommitID intentionally empty
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	// With empty CommitID and omitempty tag, the field should not appear in JSON
+	if _, exists := gotRawPayload["commit_id"]; exists {
+		t.Errorf("commit_id should be omitted when empty, but was present: %v", gotRawPayload["commit_id"])
+	}
+}

gitea/client.go

@@ -186,18 +186,22 @@ func (c *Client) GetFileContentRef(ctx context.Context, owner, repo, filepath, r
 }
 
 // PostReview submits a review to a PR and returns the created review.
-// event should be "APPROVED" or "REQUEST_CHANGES".
+// event should be one of "APPROVED", "REQUEST_CHANGES", or "COMMENT".
+// commitID anchors the review to a specific commit SHA. If empty, Gitea
+// defaults to the current PR head.
 // comments are optional inline comments attached to specific lines.
-func (c *Client) PostReview(ctx context.Context, owner, repo string, number int, event, body string, comments []ReviewComment) (*Review, error) {
+func (c *Client) PostReview(ctx context.Context, owner, repo string, number int, event, body, commitID string, comments []ReviewComment) (*Review, error) {
 	reqURL := fmt.Sprintf("%s/api/v1/repos/%s/%s/pulls/%d/reviews", c.baseURL, url.PathEscape(owner), url.PathEscape(repo), number)
 
 	payload := struct {
 		Body     string          `json:"body"`
 		Event    string          `json:"event"`
+		CommitID string          `json:"commit_id,omitempty"`
 		Comments []ReviewComment `json:"comments,omitempty"`
 	}{
 		Body:     body,
 		Event:    event,
+		CommitID: commitID,
 		Comments: comments,
 	}
 

gitea/client_test.go

@@ -135,7 +135,7 @@ func TestPostReview(t *testing.T) {
 	defer server.Close()
 
 	client := NewClient(server.URL, "test-token")
-	review, err := client.PostReview(context.Background(), "owner", "repo", 3, "APPROVED", "LGTM", nil)
+	review, err := client.PostReview(context.Background(), "owner", "repo", 3, "APPROVED", "LGTM", "", nil)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -182,7 +182,7 @@ func TestPostReview_Non200(t *testing.T) {
 	defer server.Close()
 
 	client := NewClient(server.URL, "test-token")
-	_, err := client.PostReview(context.Background(), "owner", "repo", 1, "APPROVED", "test", nil)
+	_, err := client.PostReview(context.Background(), "owner", "repo", 1, "APPROVED", "test", "", nil)
 	if err == nil {
 		t.Fatal("expected error for 403, got nil")
 	}
@@ -1144,3 +1144,62 @@ func TestSanitizeErrorForLog(t *testing.T) {
 		})
 	}
 }
+
+func TestPostReview_CommitID_InPayload(t *testing.T) {
+	var gotPayload struct {
+		Body     string `json:"body"`
+		Event    string `json:"event"`
+		CommitID string `json:"commit_id"`
+	}
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		json.NewDecoder(r.Body).Decode(&gotPayload)
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(200)
+		json.NewEncoder(w).Encode(map[string]any{
+			"id":        200,
+			"body":      "LGTM",
+			"user":      map[string]any{"login": "bot"},
+			"state":     "APPROVED",
+			"commit_id": "deadbeef1234",
+		})
+	}))
+	defer server.Close()
+
+	client := NewClient(server.URL, "test-token")
+	review, err := client.PostReview(context.Background(), "owner", "repo", 5, "APPROVED", "LGTM", "deadbeef1234", nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotPayload.CommitID != "deadbeef1234" {
+		t.Errorf("sent commit_id = %q, want %q", gotPayload.CommitID, "deadbeef1234")
+	}
+	if review.CommitID != "deadbeef1234" {
+		t.Errorf("response commit_id = %q, want %q", review.CommitID, "deadbeef1234")
+	}
+}
+
+func TestPostReview_EmptyCommitID_OmittedFromPayload(t *testing.T) {
+	var gotRaw map[string]any
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		json.NewDecoder(r.Body).Decode(&gotRaw)
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(200)
+		json.NewEncoder(w).Encode(map[string]any{
+			"id":   201,
+			"body": "ok",
+			"user": map[string]any{"login": "bot"},
+		})
+	}))
+	defer server.Close()
+
+	client := NewClient(server.URL, "test-token")
+	_, err := client.PostReview(context.Background(), "owner", "repo", 5, "COMMENT", "ok", "", nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if _, exists := gotRaw["commit_id"]; exists {
+		t.Errorf("commit_id should be omitted when empty, but was present: %v", gotRaw["commit_id"])
+	}
+}

gitea/post_review_comments_test.go

@@ -37,7 +37,7 @@ func TestPostReview_WithComments(t *testing.T) {
 		{Path: "util.go", NewPosition: 10, Body: "[MINOR] Style issue"},
 	}
 
-	_, err := client.PostReview(context.Background(), "owner", "repo", 1, "REQUEST_CHANGES", "summary", comments)
+	_, err := client.PostReview(context.Background(), "owner", "repo", 1, "REQUEST_CHANGES", "summary", "", comments)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -72,7 +72,7 @@ func TestPostReview_NilComments(t *testing.T) {
 	defer server.Close()
 
 	client := NewClient(server.URL, "test-token")
-	_, err := client.PostReview(context.Background(), "owner", "repo", 1, "APPROVED", "all good", nil)
+	_, err := client.PostReview(context.Background(), "owner", "repo", 1, "APPROVED", "all good", "", nil)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}

gitea/supersede_test.go

@@ -0,0 +1,54 @@
+package gitea
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestBuildSupersededBody(t *testing.T) {
+	original := "# Review\n\nLooks good.\n\n<!-- review-bot:sonnet -->"
+	sentinel := "<!-- review-bot:sonnet -->"
+	newURL := "https://gitea.example.com/owner/repo/pulls/1#pullrequestreview-99"
+
+	result := buildSupersededBody(original, "abcdef1234567890", newURL, sentinel)
+
+	// Should contain the struck-through banner
+	if !strings.Contains(result, "~~Original review~~") {
+		t.Error("missing struck-through banner")
+	}
+	// Should contain superseded notice with link
+	if !strings.Contains(result, "**Superseded**") {
+		t.Error("missing superseded notice")
+	}
+	if !strings.Contains(result, "[see current review]("+newURL+")") {
+		t.Error("missing link to new review")
+	}
+	// Should contain collapsed original
+	if !strings.Contains(result, "<details>") {
+		t.Error("missing details/collapse")
+	}
+	// Should contain short commit SHA
+	if !strings.Contains(result, "abcdef12") {
+		t.Error("missing short SHA")
+	}
+	// Should NOT contain full SHA in summary (it's truncated to 8)
+	if strings.Contains(result, "abcdef1234567890") {
+		t.Error("should truncate SHA to 8 chars")
+	}
+	// Should contain the original body inside details
+	if !strings.Contains(result, original) {
+		t.Error("original body not preserved in collapsed section")
+	}
+	// Should end with sentinel
+	if !strings.Contains(result, sentinel) {
+		t.Error("missing sentinel")
+	}
+}
+
+func TestBuildSupersededBodyShortSHA(t *testing.T) {
+	// Short SHA should pass through without panic
+	result := buildSupersededBody("body", "abc", "https://example.com/review", "<!-- review-bot:x -->")
+	if !strings.Contains(result, "abc") {
+		t.Error("short SHA not preserved")
+	}
+}

github/conformance_test.go

@@ -9,3 +9,6 @@ import (
 // This verifies github.Client satisfies the full vcs.Client interface
 // (PRReader, FileReader, Reviewer, Identity).
 var _ vcs.Client = (*github.Client)(nil)
+
+// Verify github.Client implements ReviewSuperseder.
+var _ vcs.ReviewSuperseder = (*github.Client)(nil)

github/review.go

@@ -82,21 +82,25 @@ func translateGitHubReviewState(state string) string {
 // (via the omitempty tag on postReviewRequest.Comments).
 //
 // The GitHub API accepts a single commit_id per review submission. PostReview
-// extracts it from the first comment with a non-empty CommitID. If any subsequent
-// comment specifies a different CommitID, PostReview returns ErrConflictingCommitIDs.
-// Comments with an empty CommitID are allowed and inherit the review-level value.
+// uses req.CommitID as the primary commit anchor. If req.CommitID is empty,
+// it falls back to extracting from the first comment with a non-empty CommitID.
+// If any subsequent comment specifies a different CommitID, PostReview returns
+// ErrConflictingCommitIDs. Comments with an empty CommitID are allowed and
+// inherit the review-level value.
 func (c *Client) PostReview(ctx context.Context, owner, repo string, number int, req vcs.ReviewRequest) (*vcs.Review, error) {
 	reqURL := fmt.Sprintf("%s/repos/%s/%s/pulls/%d/reviews",
 		c.baseURL, url.PathEscape(owner), url.PathEscape(repo), number)
 
 	payload := postReviewRequest{
-		Body:  req.Body,
-		Event: string(req.Event),
+		Body:     req.Body,
+		Event:    string(req.Event),
+		CommitID: req.CommitID,
 	}
 
 	// Build the payload in one pass. The GitHub API accepts a single commit_id
-	// per review; we extract it from the first comment that supplies one and
-	// reject the request if any other comment disagrees.
+	// per review. req.CommitID is the primary source; if empty, we extract from
+	// the first comment that supplies one. Reject if any comment disagrees with
+	// the resolved commit_id.
 	for _, comment := range req.Comments {
 		if comment.CommitID != "" {
 			if payload.CommitID == "" {
@@ -104,6 +108,7 @@ func (c *Client) PostReview(ctx context.Context, owner, repo string, number int,
 			} else if payload.CommitID != comment.CommitID {
 				return nil, ErrConflictingCommitIDs
 			}
+			// else: matching SHA is a no-op by design
 		}
 		payload.Comments = append(payload.Comments, reviewCommentEntry{
 			Path:     comment.Path,
@@ -210,3 +215,16 @@ func (c *Client) DismissReview(ctx context.Context, owner, repo string, number i
 	}
 	return nil
 }
+
+// SupersedeReviews marks prior reviews as superseded by dismissing them.
+// This implements vcs.ReviewSuperseder for the GitHub adapter.
+// The baseURL and sentinel parameters are unused for GitHub (dismissal is the mechanism).
+func (c *Client) SupersedeReviews(ctx context.Context, owner, repo string, prNumber int, oldReviews []vcs.Review, newReviewID int64, _, _ string) error {
+	var errs []error
+	for _, old := range oldReviews {
+		if err := c.DismissReview(ctx, owner, repo, prNumber, old.ID, "Superseded by new review"); err != nil {
+			errs = append(errs, fmt.Errorf("dismiss review %d: %w", old.ID, err))
+		}
+	}
+	return errors.Join(errs...)
+}

github/review_test.go

@@ -389,3 +389,96 @@ func TestPostReview_ConflictingCommitIDs(t *testing.T) {
 		t.Errorf("expected ErrConflictingCommitIDs, got: %v", err)
 	}
 }
+
+func TestPostReview_RequestCommitID_TakesPriority(t *testing.T) {
+	var gotPayload struct {
+		CommitID string `json:"commit_id"`
+		Body     string `json:"body"`
+	}
+
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		json.NewDecoder(r.Body).Decode(&gotPayload)
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]any{
+			"id":        42,
+			"body":      "LGTM",
+			"state":     "APPROVED",
+			"commit_id": "req-level-sha",
+			"user":      map[string]any{"login": "bot"},
+		})
+	})
+
+	review, err := c.PostReview(context.Background(), "owner", "repo", 1, vcs.ReviewRequest{
+		Body:     "LGTM",
+		Event:    vcs.ReviewEventApprove,
+		CommitID: "req-level-sha",
+		Comments: []vcs.ReviewComment{
+			{Path: "a.go", Position: 1, CommitID: "req-level-sha", Body: "looks good"},
+		},
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotPayload.CommitID != "req-level-sha" {
+		t.Errorf("sent commit_id = %q, want %q", gotPayload.CommitID, "req-level-sha")
+	}
+	if review.CommitID != "req-level-sha" {
+		t.Errorf("review.CommitID = %q, want %q", review.CommitID, "req-level-sha")
+	}
+}
+
+func TestPostReview_RequestCommitID_ConflictsWithComment(t *testing.T) {
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		t.Fatal("request should not be sent when commit IDs conflict")
+	})
+
+	// req.CommitID is set, and a comment has a different CommitID → conflict
+	_, err := c.PostReview(context.Background(), "owner", "repo", 1, vcs.ReviewRequest{
+		Body:     "Review",
+		Event:    vcs.ReviewEventComment,
+		CommitID: "req-sha",
+		Comments: []vcs.ReviewComment{
+			{Path: "a.go", Position: 1, CommitID: "different-sha", Body: "nit"},
+		},
+	})
+	if err == nil {
+		t.Fatal("expected error for conflicting commit IDs")
+	}
+	if !errors.Is(err, ErrConflictingCommitIDs) {
+		t.Errorf("expected ErrConflictingCommitIDs, got: %v", err)
+	}
+}
+
+func TestPostReview_RequestCommitID_FallbackToComment(t *testing.T) {
+	var gotPayload struct {
+		CommitID string `json:"commit_id"`
+	}
+
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		json.NewDecoder(r.Body).Decode(&gotPayload)
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]any{
+			"id":        43,
+			"body":      "ok",
+			"state":     "COMMENTED",
+			"commit_id": "comment-sha",
+			"user":      map[string]any{"login": "bot"},
+		})
+	})
+
+	// req.CommitID is empty, so it falls back to the comment's CommitID
+	_, err := c.PostReview(context.Background(), "owner", "repo", 1, vcs.ReviewRequest{
+		Body:  "ok",
+		Event: vcs.ReviewEventComment,
+		// CommitID intentionally empty
+		Comments: []vcs.ReviewComment{
+			{Path: "a.go", Position: 1, CommitID: "comment-sha", Body: "note"},
+		},
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotPayload.CommitID != "comment-sha" {
+		t.Errorf("sent commit_id = %q, want %q (fallback from comment)", gotPayload.CommitID, "comment-sha")
+	}
+}

vcs/interfaces.go

@@ -49,3 +49,12 @@ type Client interface {
 type ReviewerSelfRequester interface {
 	RequestReviewerSelf(ctx context.Context, owner, repo string, number int, user string) error
 }
+
+// ReviewSuperseder is an optional interface implemented by adapters that support
+// marking old reviews as superseded. For Gitea this means editing the review body
+// with a link to the new review and resolving inline comments. For GitHub this
+// means dismissing old reviews.
+// Consumers should use interface assertion: if rs, ok := client.(ReviewSuperseder); ok { ... }
+type ReviewSuperseder interface {
+	SupersedeReviews(ctx context.Context, owner, repo string, prNumber int, oldReviews []Review, newReviewID int64, baseURL, sentinel string) error
+}

vcs/provider.go

@@ -0,0 +1,26 @@
+package vcs
+
+// VCSProvider identifies a VCS platform. Using a typed string instead of bare
+// strings makes provider values compiler-checkable and prevents typos from
+// silently passing validation.
+type VCSProvider string
+
+const (
+	ProviderGitea  VCSProvider = "gitea"
+	ProviderGitHub VCSProvider = "github"
+)
+
+// Valid reports whether p is a known VCS provider.
+func (p VCSProvider) Valid() bool {
+	switch p {
+	case ProviderGitea, ProviderGitHub:
+		return true
+	default:
+		return false
+	}
+}
+
+// String returns the string representation of the provider.
+func (p VCSProvider) String() string {
+	return string(p)
+}

vcs/types.go

@@ -93,6 +93,11 @@ type ReviewRequest struct {
 	// Body is the top-level review comment.
 	Body string `json:"body"`
 	// Event is the review action (approve, request changes, or comment).
-	Event    ReviewEvent     `json:"event"`
+	Event ReviewEvent `json:"event"`
+	// CommitID anchors the review to a specific commit SHA.
+	// If empty, the platform defaults to the current PR head.
+	// Adapters use this as the primary commit anchor for the review submission.
+	CommitID string `json:"commit_id,omitempty"`
+
 	Comments []ReviewComment `json:"comments,omitempty"`
 }