render attention first: unresolved sections, activity order

Output splits into an unresolved and a resolved section — a file with
both kinds of threads appears in each — so what needs action reads
first. Inside a section, files order as the change screen names them
(patchset level, commit message, then paths); threads within a file
follow the time of their latest comment; comments within a thread
follow history. Comment ids break ties only on equal timestamps.

Thread grouping and resolved state stay the change screen's replica;
only the presentation order is the tool's own.

Author: xobotyi

internal/tools/get-change-comments.go

@@ -40,9 +40,10 @@ func getChangeComments(c *gerritclient.Client) Tool {
 					"shows — grouped by file and reconstructed into threads with their resolved " +
 					"state. The calling account's unpublished draft comments are included, marked " +
 					"draft=\"true\" and invisible to anyone else; thread state accounts for them, " +
-					"matching what this account's Gerrit UI shows. Comment ids are the reply " +
-					"anchors for post_comments; filter status=unresolved to see what still needs " +
-					"action.",
+					"matching what this account's Gerrit UI shows. Unresolved threads render " +
+					"before resolved ones; threads follow their latest activity and comments " +
+					"their history. Comment ids are the reply anchors for post_comments; filter " +
+					"status=unresolved to see what still needs action.",
 			}, func(ctx context.Context, _ *mcp.CallToolRequest, in getChangeCommentsInput,
 			) (*mcp.CallToolResult, any, error) {
 				if in.Status == "" {
@@ -132,11 +133,16 @@ func draftCount(all []changeComment) int {
 type thread struct {
 	comments   []changeComment
 	unresolved bool
+	// root is the comment that anchors the thread in the UI's grouping; its
+	// path and timestamp place the thread in the output.
+	root changeComment
 }
 
-// pathPatchsetLevel is Gerrit's virtual path for patchset-level comments;
-// the change screen pins it before every real file.
-const pathPatchsetLevel = "/PATCHSET_LEVEL"
+// Gerrit's virtual file paths; the change screen pins them before real files.
+const (
+	pathPatchsetLevel = "/PATCHSET_LEVEL"
+	pathCommitMsg     = "/COMMIT_MSG"
+)
 
 // buildThreads groups comments the way the change screen does — a
 // bug-compatible replica of polygerrit's createCommentThreads (stable-3.13
@@ -177,17 +183,34 @@ func buildThreads(all []changeComment) []thread {
 	threads := make([]thread, 0, len(acc))
 
 	for _, members := range acc {
+		// State and grouping follow the UI's ordering; only after both are
+		// fixed do the comments re-sort chronologically for display.
 		last := members[len(members)-1]
+		root := members[0]
+
+		slices.SortStableFunc(members, compareChrono)
 
 		threads = append(threads, thread{
 			comments:   members,
 			unresolved: last.Unresolved != nil && *last.Unresolved,
+			root:       root,
 		})
 	}
 
 	return threads
 }
 
+// compareChrono orders comments by time, falling back to comment id only on
+// equal timestamps — the display order of comments within a thread and of
+// threads within a file.
+func compareChrono(a, b changeComment) int {
+	if c := compareUpdated(a.Updated, b.Updated); c != 0 {
+		return c
+	}
+
+	return strings.Compare(a.ID, b.ID)
+}
+
 // sanitiseRanges mirrors polygerrit's pre-sort pass: a rangeless reply
 // inherits its parent's range so same-location comments sort together. The
 // pass is deliberately order-dependent — a reply processed before its parent
@@ -353,62 +376,121 @@ func matchesStatus(t thread, status string) bool {
 	}
 }
 
-// renderComments groups threads under the file path of their root comment,
-// in sorted path order.
+// renderComments emits attention first: an unresolved section, then a
+// resolved one — a file with both kinds of threads appears in each. Inside a
+// section files order as the change screen names them (patchset level, then
+// the commit message, then paths); threads within a file follow the time of
+// their latest comment; comments within a thread follow history. Comment ids
+// break ties everywhere.
 func renderComments(in getChangeCommentsInput, threads []thread, drafts int) string {
-	byFile := map[string][]thread{}
+	var unresolved, resolved []thread
 
 	for _, t := range threads {
-		path := t.comments[0].path
+		if !matchesStatus(t, in.Status) {
+			continue
+		}
 
-		byFile[path] = append(byFile[path], t)
+		if t.unresolved {
+			unresolved = append(unresolved, t)
+		} else {
+			resolved = append(resolved, t)
+		}
 	}
 
-	paths := make([]string, 0, len(byFile))
-	for path := range byFile {
-		paths = append(paths, path)
+	var sections []string
+
+	if s := renderSection("unresolved", unresolved); s != "" {
+		sections = append(sections, s)
 	}
 
-	slices.Sort(paths)
+	if s := renderSection("resolved", resolved); s != "" {
+		sections = append(sections, s)
+	}
 
-	var (
-		rendered    []string
-		threadCount int
+	root := llmxml.NewElement("comments",
+		llmxml.Attr("change", in.Change),
+		llmxml.Attr("filter", in.Status),
+		llmxml.Attr("threads", len(unresolved)+len(resolved)),
+		llmxml.Attr("drafts", drafts),
 	)
 
-	for _, path := range paths {
-		var fileThreads []string
+	if len(sections) == 0 {
+		return root.String()
+	}
 
-		for _, t := range byFile[path] {
-			if !matchesStatus(t, in.Status) {
-				continue
-			}
+	return root.WrapText(strings.Join(sections, "\n")).String()
+}
 
-			threadCount++
+// renderSection wraps one resolution state's threads, grouped by the file
+// path of each thread's root comment.
+func renderSection(name string, threads []thread) string {
+	if len(threads) == 0 {
+		return ""
+	}
 
-			fileThreads = append(fileThreads, renderThread(t))
-		}
+	byFile := map[string][]thread{}
+	for _, t := range threads {
+		byFile[t.root.path] = append(byFile[t.root.path], t)
+	}
 
-		if len(fileThreads) == 0 {
-			continue
+	paths := make([]string, 0, len(byFile))
+	for path := range byFile {
+		paths = append(paths, path)
+	}
+
+	slices.SortStableFunc(paths, compareRenderPaths)
+
+	rendered := make([]string, 0, len(paths))
+
+	for _, path := range paths {
+		fileThreads := byFile[path]
+		slices.SortStableFunc(fileThreads, compareThreads)
+
+		lines := make([]string, 0, len(fileThreads))
+		for _, t := range fileThreads {
+			lines = append(lines, renderThread(t))
 		}
 
 		rendered = append(rendered, llmxml.NewElement("file", llmxml.Attr("path", path)).
-			WrapText(strings.Join(fileThreads, "\n")).String())
+			WrapText(strings.Join(lines, "\n")).String())
 	}
 
-	root := llmxml.NewElement("comments",
-		llmxml.Attr("change", in.Change),
-		llmxml.Attr("filter", in.Status),
-		llmxml.Attr("threads", threadCount),
-		llmxml.Attr("drafts", drafts),
-	)
+	return llmxml.NewElement(name, llmxml.Attr("count", len(threads))).
+		WrapText(strings.Join(rendered, "\n")).String()
+}
 
-	if len(rendered) == 0 {
-		return root.String()
+// Display ranks for file paths: the change level first, the commit message
+// second, everything else by path.
+const (
+	rankPatchsetLevel = iota
+	rankCommitMsg
+	rankFilePath
+)
+
+// compareRenderPaths orders files for display by rank, then by path.
+func compareRenderPaths(a, b string) int {
+	rank := func(p string) int {
+		switch p {
+		case pathPatchsetLevel:
+			return rankPatchsetLevel
+		case pathCommitMsg:
+			return rankCommitMsg
+		default:
+			return rankFilePath
+		}
 	}
 
-	return root.WrapText(strings.Join(rendered, "\n")).String()
+	if ra, rb := rank(a), rank(b); ra != rb {
+		return ra - rb
+	}
+
+	return strings.Compare(a, b)
+}
+
+// compareThreads orders threads within a file by the time of their latest
+// comment — the conversation in the order it last moved.
+func compareThreads(a, b thread) int {
+	return compareChrono(a.comments[len(a.comments)-1], b.comments[len(b.comments)-1])
 }
 
 func renderThread(t thread) string {

internal/tools/post-comments.go

@@ -222,7 +222,7 @@ func validateReplyTargets(ctx context.Context, c *gerritclient.Client, in postCo
 // commentable on every change.
 func magicPath(path string) bool {
 	switch path {
-	case "/COMMIT_MSG", "/PATCHSET_LEVEL", "/MERGE_LIST":
+	case pathCommitMsg, pathPatchsetLevel, "/MERGE_LIST":
 		return true
 	default:
 		return false

internal/tools/read-tools_test.go

@@ -278,6 +278,34 @@ func Test_GetChangeComments(t *testing.T) {
 		golden(t, "change-comments-ui-fork", out)
 	})
 
+	t.Run("threads follow their latest comment, not their root", func(t *testing.T) {
+		t.Parallel()
+
+		// Thread A starts first but its reply is the newest activity; thread
+		// B started later and never moved. B's conversation last moved
+		// earlier, so B renders first.
+		const published = ")]}'\n" + `{
+		  "core/scanner.go": [
+		    {"id": "a-root", "line": 1, "patch_set": 1, "message": "First opened", "unresolved": false,
+		     "updated": "2026-07-01 10:00:00.000000000",
+		     "author": {"_account_id": 8, "name": "Bob", "username": "bob"}},
+		    {"id": "a-reply", "in_reply_to": "a-root", "line": 1, "patch_set": 1, "message": "Late reply",
+		     "unresolved": false,
+		     "updated": "2026-07-01 15:00:00.000000000",
+		     "author": {"_account_id": 7, "name": "Alice", "username": "alice"}},
+		    {"id": "b-root", "line": 2, "patch_set": 1, "message": "Second opened", "unresolved": false,
+		     "updated": "2026-07-01 11:00:00.000000000",
+		     "author": {"_account_id": 8, "name": "Bob", "username": "bob"}}
+		  ]
+		}`
+
+		cs := commentsSession(t, published, emptyDraftsJSON)
+
+		out := callTool(t, cs, "get_change_comments", map[string]any{"change": "123"})
+
+		golden(t, "change-comments-latest-order", out)
+	})
+
 	t.Run("same-timestamp fork orders by comment id", func(t *testing.T) {
 		t.Parallel()
 

internal/tools/testdata/change-comments-all.golden

@@ -1,4 +1,14 @@
 <comments change="123" filter="all" threads="3" drafts="0">
+<unresolved count="1">
+<file path="core/scanner.go">
+<thread resolved="false">
+<comment id="c3" author="Bob (bob)" date="2026-07-02T09:00:00Z" patch_set="2" lines="20-25">
+This block races
+</comment>
+</thread>
+</file>
+</unresolved>
+<resolved count="2">
 <file path="core/scanner.go">
 <thread resolved="true">
 <comment id="c1" author="Bob (bob)" date="2026-07-01T10:00:00Z" patch_set="1" line="10">
@@ -8,11 +18,6 @@ Is this nil-safe?
 Fixed in ps2
 </comment>
 </thread>
-<thread resolved="false">
-<comment id="c3" author="Bob (bob)" date="2026-07-02T09:00:00Z" patch_set="2" lines="20-25">
-This block races
-</comment>
-</thread>
 </file>
 <file path="docs/readme.md">
 <thread resolved="true">
@@ -21,4 +26,5 @@ Orphan reply
 </comment>
 </thread>
 </file>
+</resolved>
 </comments>

internal/tools/testdata/change-comments-drafts.golden

@@ -1,4 +1,5 @@
 <comments change="123" filter="unresolved" threads="1" drafts="1">
+<unresolved count="1">
 <file path="core/scanner.go">
 <thread resolved="false">
 <comment id="c1" author="Bob (bob)" date="2026-07-01T10:00:00Z" patch_set="1" line="10">
@@ -12,4 +13,5 @@ Still crashes on empty input
 </comment>
 </thread>
 </file>
+</unresolved>
 </comments>

internal/tools/testdata/change-comments-latest-order.golden

@@ -0,0 +1,19 @@
+<comments change="123" filter="all" threads="2" drafts="0">
+<resolved count="2">
+<file path="core/scanner.go">
+<thread resolved="true">
+<comment id="b-root" author="Bob (bob)" date="2026-07-01T11:00:00Z" patch_set="1" line="2">
+Second opened
+</comment>
+</thread>
+<thread resolved="true">
+<comment id="a-root" author="Bob (bob)" date="2026-07-01T10:00:00Z" patch_set="1" line="1">
+First opened
+</comment>
+<comment id="a-reply" author="Alice (alice)" date="2026-07-01T15:00:00Z" patch_set="1" line="1" in_reply_to="a-root">
+Late reply
+</comment>
+</thread>
+</file>
+</resolved>
+</comments>

internal/tools/testdata/change-comments-renamed.golden

@@ -1,16 +1,20 @@
 <comments change="123" filter="all" threads="2" drafts="0">
-<file path="core/new-name.go">
-<thread resolved="true">
-<comment id="r2" author="Alice (alice)" date="2026-07-02T10:00:00Z" patch_set="2" line="5" in_reply_to="r1">
-Done
-</comment>
-</thread>
-</file>
+<unresolved count="1">
 <file path="core/old-name.go">
 <thread resolved="false">
 <comment id="r1" author="Bob (bob)" date="2026-07-01T10:00:00Z" patch_set="1" line="5">
 Rename this too
 </comment>
 </thread>
 </file>
+</unresolved>
+<resolved count="1">
+<file path="core/new-name.go">
+<thread resolved="true">
+<comment id="r2" author="Alice (alice)" date="2026-07-02T10:00:00Z" patch_set="2" line="5" in_reply_to="r1">
+Done
+</comment>
+</thread>
+</file>
+</resolved>
 </comments>

internal/tools/testdata/change-comments-tiebreak.golden

@@ -1,4 +1,5 @@
 <comments change="123" filter="all" threads="1" drafts="0">
+<unresolved count="1">
 <file path="core/scanner.go">
 <thread resolved="false">
 <comment id="c1" author="Bob (bob)" date="2026-07-01T10:00:00Z" patch_set="1" line="10">
@@ -12,4 +13,5 @@ Not fixed
 </comment>
 </thread>
 </file>
+</unresolved>
 </comments>