docs(cmd,github): clarify type assertion and parameter usage in review superseding

Address sonnet-review feedback on PR #106:

- Document that the type assertion in supersedeOldReviews is guaranteed to
  succeed given the caller's provider switch, with the !ok branch guarding
  against future refactors (comment 18889).
- Clarify that vcsURL is only used in the Gitea path for constructing
  review permalink URLs (comment 18890).
- Add note explaining why the page-limit warning in ListReviews only fires
  when the final page is full, confirming the logic is intentional
  (comment 18891).

cmd/review-bot/main.go

@@ -531,8 +531,12 @@ func verdictToEvent(verdict string) vcs.ReviewEvent {
 }
 
 // supersedeOldReviews marks old reviews as superseded.
-// For GitHub: dismisses old reviews.
-// For Gitea: edits the review body and resolves inline comments.
+// 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":
@@ -553,6 +557,11 @@ func supersedeOldReviews(ctx context.Context, client vcs.Client, provider, vcsUR
 		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)

github/reviews.go

@@ -140,6 +140,10 @@ func (c *Client) ListReviews(ctx context.Context, owner, repo string, number int
 		if len(reviews) < reviewsPerPage {
 			break
 		}
+		// NOTE: This warning only fires when the final page was full (the short-page
+		// break above did not trigger), meaning additional reviews likely exist beyond
+		// our page limit. The loop naturally exits after this iteration since page
+		// increments past maxReviewPages.
 		if page == maxReviewPages {
 			slog.Warn("ListReviews hit page limit; results may be truncated",
 				"owner", owner, "repo", repo, "pr", number,