Harden reviewer branch parity checks

Author: mekilis

.agents/archive/2026-06-16-001-reviewer-branch-parity-discipline/decisions/2026-06-16T103705Z-scope-is-reviewer-branch-parity-discipline-add-full-diff-first-pass-behavior-f.md

@@ -0,0 +1,6 @@
+# Decision: Scope is reviewer branch-parity discipline: add full-diff first-pass behavior, f
+
+Status: proposed
+By: smart
+
+Scope is reviewer branch-parity discipline: add full-diff first-pass behavior, finding-scoped surrounding-function/sibling-branch verification, explicit branch checklist output, ordered reviewer config documentation, and fixture coverage for a sibling branch missing a guard.

.agents/archive/2026-06-16-001-reviewer-branch-parity-discipline/summary.md

@@ -0,0 +1,36 @@
+# reviewer branch parity discipline
+
+status: archived
+previous_status: active
+archived_at: 2026-06-16T10:52:57Z
+
+Summary:
+- decisions: 1
+- handoffs: 4
+- verification records: 1
+- run activity records: 4
+- findings open: 0
+- findings fixed: 0
+- findings verified: 1
+
+## Scope
+
+Recent handoffs:
+- Fixed reviewer full-diff packet untracked-file coverage. Reviewer prompts and local AI reviewer input now include bounded untracked-file diff content plus stat/list context. Added focused tests proving untracked source files appear in both ...
+- Fix the open medium finding: reviewer full-diff packet omits untracked files. The new reviewer/local AI diff helpers use `git diff --no-ext-diff HEAD`, which excludes untracked additions. Preserve surgical scope. Include untracked files ...
+
+Decisions:
+- Scope is reviewer branch-parity discipline: add full-diff first-pass behavior, finding-scoped surrounding-function/sibling-branch verification, explicit branch checklist output, ordered reviewer config documentation, and fixture coverage for a sibling branch missing a guard.
+
+Verification:
+- Reviewed working diff, task chunks, fixed finding evidence, reviewer/local reviewer prompt paths, untracked diff handling, and tests. Verified fixed finding 2026-06-16T104338Z-reviewer-full-diff-packet-omits-untracked-files.md. No unresolved issues found. ## Command $ [cache env] go test ...
+
+## Final Status
+
+Implemented reviewer branch-parity discipline in reviewer packets and local first-pass review; focused tests, go vet ./..., and GOCACHE-isolated go test ./... pass.
+
+## Reviewer Verification
+
+- Reviewed working diff, task chunks, fixed finding evidence, reviewer/local reviewer prompt paths, untracked diff handling, and tests. Verified fixed finding 2026-06-16T104338Z-reviewer-full-diff-packet-omits-untracked-files.md. No unresolved issues found. ## Command $ [cache env] go test ...
+
+Detailed transient chunks remain available in git history.

README.md

@@ -355,6 +355,26 @@ openai_compatible` for local chat completion servers. Per-role
 `model`/`reasoning` values override the named provider for that role only. Set
 `cmd: my-agent {prompt_file}` as an advanced escape hatch, or put provider
 flags directly in a custom role command.
+
+For review-heavy projects, prefer an ordered reviewer pipeline: a local coder or
+local reviewer first pass for fast branch-parity checks, followed by Codex with
+high reasoning for the independent review. Reviewer list entries run in order;
+per-entry `model` and `reasoning` overrides apply only to that reviewer:
+
+```yaml
+providers:
+  local-reviewer:
+    type: openai_compatible
+    base_url: http://127.0.0.1:1234/v1
+    model: your-local-review-model
+roles:
+  reviewer:
+    - local-reviewer
+    - provider: codex
+      model: gpt-5.5
+      reasoning: high
+```
+
 Legacy `settings.local_ai_*`, `settings.codex_*`, `settings.claude_*`, and
 `settings.cursor_model` keys still work, but new config should prefer
 `providers` and `roles.reviewer`.

internal/app/app.go

@@ -6135,12 +6135,14 @@ func buildRolePrompt(e env, state loopState) (string, error) {
 		appendPromptDir(&b, e.cwd, state.Task.Path, "handoffs", "Handoffs")
 		appendPromptDir(&b, e.cwd, state.Task.Path, "findings", "Findings")
 		appendPromptDir(&b, e.cwd, state.Task.Path, "verification", "Verification")
+		appendGitDiffPrompt(&b, e.cwd)
 		fmt.Fprintln(&b, "Working agreement:")
 		if state.NextAction == "review plan before implementation" {
 			fmt.Fprintln(&b, "- This is a plan review gate before implementation. Review `plan.md` for readiness; do not review or request implementation changes unless they are needed to make the plan actionable.")
 			fmt.Fprintln(&b, "- If the plan is shallow, stale, missing evidence, incorrect, or omits validation or constraints, record findings against the plan so the implementer can fix it before code changes.")
 			fmt.Fprintln(&b, "- If the plan is ready, record review evidence. The human must still approve the plan before implementation proceeds.")
 		}
+		appendReviewerBranchParityDiscipline(&b)
 		fmt.Fprintln(&b, "- Review the working tree, tests, and task chunks; verify claims against the code, not the handoff text.")
 		fmt.Fprintln(&b, "- Review the current task plan in `plan.md` when present. Check for substantive objective, repo-relative evidence, assumptions or open questions, implementation shape, validation, risks, and constraints; do not require exact section headings.")
 		fmt.Fprintln(&b, "- Check whether the implementation and review scope match the approved or draft plan.")
@@ -6170,6 +6172,108 @@ func buildRolePrompt(e env, state loopState) (string, error) {
 	return b.String(), nil
 }
 
+func appendGitDiffPrompt(b *strings.Builder, cwd string) {
+	if stat := gitDiffStat(cwd); strings.TrimSpace(stat) != "" {
+		fmt.Fprintf(b, "## Git diff stat\n\n%s\n\n", stat)
+	}
+	if diff := gitDiff(cwd); strings.TrimSpace(diff) != "" {
+		fmt.Fprintf(b, "## Git diff\n\n```diff\n%s\n```\n\n", diff)
+	}
+}
+
+func gitDiff(cwd string) string {
+	out, err := exec.Command("git", "-C", cwd, "diff", "--no-ext-diff", "HEAD").CombinedOutput()
+	if err != nil {
+		return "(no git diff available)"
+	}
+	text := strings.TrimSpace(string(out))
+	if untracked := gitUntrackedDiff(cwd); strings.TrimSpace(untracked) != "" {
+		if text == "" {
+			text = untracked
+		} else {
+			text += "\n\n" + untracked
+		}
+	}
+	if text == "" {
+		return "(working tree clean)"
+	}
+	const maxDiffBytes = 120_000
+	if len(text) > maxDiffBytes {
+		return text[:maxDiffBytes] + "\n...[diff truncated; inspect the working tree directly before verifying]..."
+	}
+	return text
+}
+
+func gitUntrackedDiff(cwd string) string {
+	files := gitUntrackedFiles(cwd)
+	if len(files) == 0 {
+		return ""
+	}
+	const (
+		maxFiles      = 50
+		maxFileBytes  = 20_000
+		maxTotalBytes = 80_000
+	)
+	var b strings.Builder
+	for i, file := range files {
+		if i >= maxFiles {
+			fmt.Fprintf(&b, "\n...[untracked diff truncated; %d more files]...\n", len(files)-i)
+			break
+		}
+		if b.Len() >= maxTotalBytes {
+			fmt.Fprintln(&b, "\n...[untracked diff truncated; inspect the working tree directly before verifying]...")
+			break
+		}
+		data, err := os.ReadFile(filepath.Join(cwd, file))
+		if err != nil {
+			fmt.Fprintf(&b, "diff --git a/%s b/%s\nnew file mode 100644\n--- /dev/null\n+++ b/%s\n@@\n+[untracked file unreadable: %v]\n", file, file, file, err)
+			continue
+		}
+		if strings.ContainsRune(string(data), '\x00') {
+			fmt.Fprintf(&b, "diff --git a/%s b/%s\nnew file mode 100644\n--- /dev/null\n+++ b/%s\n@@\n+[binary untracked file omitted]\n", file, file, file)
+			continue
+		}
+		text := string(data)
+		truncated := false
+		if len(text) > maxFileBytes {
+			text = text[:maxFileBytes]
+			truncated = true
+		}
+		fmt.Fprintf(&b, "diff --git a/%s b/%s\nnew file mode 100644\n--- /dev/null\n+++ b/%s\n@@\n", file, file, file)
+		for _, line := range strings.Split(strings.TrimRight(text, "\n"), "\n") {
+			fmt.Fprintf(&b, "+%s\n", line)
+		}
+		if truncated {
+			fmt.Fprintln(&b, "+...[untracked file truncated; inspect the working tree directly before verifying]...")
+		}
+	}
+	return strings.TrimRight(b.String(), "\n")
+}
+
+func gitUntrackedFiles(cwd string) []string {
+	out, err := exec.Command("git", "-C", cwd, "ls-files", "--others", "--exclude-standard", "-z").Output()
+	if err != nil || len(out) == 0 {
+		return nil
+	}
+	parts := strings.Split(strings.TrimRight(string(out), "\x00"), "\x00")
+	files := make([]string, 0, len(parts))
+	for _, part := range parts {
+		if part != "" {
+			files = append(files, part)
+		}
+	}
+	return files
+}
+
+func appendReviewerBranchParityDiscipline(b *strings.Builder) {
+	fmt.Fprintln(b, "- Start every reviewer run with a full-diff review before considering seeded findings fixed or verified.")
+	fmt.Fprintln(b, "- Enumerate the changed functions and their sibling branches or paths, including success, error, early-return, 404, fallback, read counterpart, and write counterpart paths when they exist.")
+	fmt.Fprintln(b, "- Check branch parity across those sibling paths: shared guards, validation, persistence, cleanup, user-visible errors, task-state writes, and tests should be intentionally consistent or intentionally different.")
+	fmt.Fprintln(b, "- When verifying a provided finding, inspect the whole enclosing function and sibling branches before emitting `agents finding verify`; open new findings for any parity gap you discover.")
+	fmt.Fprintln(b, "- Record one finding per real issue independent of seeded findings; do not merge unrelated parity problems into a single finding and do not pass because only the seeded finding was fixed.")
+	fmt.Fprintln(b, "- Include an explicit branch checklist in your response naming each changed function and sibling path you reviewed, with the parity result for each.")
+}
+
 func applyRoleOutputDirectives(e env, actor, output string) (string, error) {
 	cleaned := output
 	seenHandoffs := map[string]bool{}

internal/app/app_test.go

@@ -8,6 +8,7 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"strings"
 	"sync"
@@ -4308,6 +4309,146 @@ func TestReviewerPromptIncludesPlanReviewInstructionsAndOmitsLocalAIReviewNotes(
 	}
 }
 
+func TestReviewerPromptIncludesBranchParityChecklistAndFullDiff(t *testing.T) {
+	code := withTempProcessEnv(t, func(home, cwd string) int {
+		e := env{cwd: cwd, home: home, trustPath: filepath.Join(home, ".agents", "trust.json")}
+		task, err := openTask(e, []string{"Branch Parity"}, time.Date(2026, 6, 5, 10, 0, 0, 0, time.UTC))
+		if err != nil {
+			t.Fatal(err)
+		}
+		if _, err := addHandoff(e, []string{"--to", "reviewer", "Review sibling command branches; add branch checklist."}, time.Date(2026, 6, 5, 10, 1, 0, 0, time.UTC)); err != nil {
+			t.Fatal(err)
+		}
+		writeReviewerParityFixture(t, cwd)
+		if err := os.WriteFile(filepath.Join(cwd, "new_command.go"), []byte(strings.Join([]string{
+			"package fixture",
+			"",
+			"func newCommand() error {",
+			"	return nil",
+			"}",
+			"",
+		}, "\n")), 0o644); err != nil {
+			t.Fatal(err)
+		}
+
+		prompt, err := buildRolePrompt(e, loopState{
+			Task:       task,
+			NextRole:   "reviewer",
+			NextAction: "review latest handoff",
+		})
+		if err != nil {
+			t.Fatal(err)
+		}
+		for _, want := range []string{
+			"## Git diff",
+			"func runCommand(name string, trusted bool) error",
+			`case "write":`,
+			`case "read":`,
+			"Untracked files:",
+			"new_command.go",
+			"diff --git a/new_command.go b/new_command.go",
+			"func newCommand() error",
+			"Start every reviewer run with a full-diff review",
+			"Enumerate the changed functions and their sibling branches or paths",
+			"success, error, early-return, 404, fallback, read counterpart, and write counterpart paths",
+			"When verifying a provided finding, inspect the whole enclosing function and sibling branches",
+			"Include an explicit branch checklist",
+		} {
+			if !strings.Contains(prompt, want) {
+				t.Fatalf("reviewer prompt missing %q:\n%s", want, prompt)
+			}
+		}
+		return 0
+	})
+	if code != 0 {
+		t.Fatalf("withTempProcessEnv code=%d", code)
+	}
+}
+
+func TestLocalAIReviewInputIncludesUntrackedFiles(t *testing.T) {
+	code := withTempProcessEnv(t, func(home, cwd string) int {
+		e := env{cwd: cwd, home: home, trustPath: filepath.Join(home, ".agents", "trust.json")}
+		task, err := openTask(e, []string{"Local Reviewer Untracked"}, time.Date(2026, 6, 5, 10, 0, 0, 0, time.UTC))
+		if err != nil {
+			t.Fatal(err)
+		}
+		writeReviewerParityFixture(t, cwd)
+		if err := os.WriteFile(filepath.Join(cwd, "untracked_review.go"), []byte(strings.Join([]string{
+			"package fixture",
+			"",
+			"func untrackedReviewPath() error {",
+			"	return nil",
+			"}",
+			"",
+		}, "\n")), 0o644); err != nil {
+			t.Fatal(err)
+		}
+
+		input := localAIReviewInput(e, loopState{
+			Task:       task,
+			NextAction: "review latest handoff",
+		})
+		for _, want := range []string{
+			"Git diff stat:",
+			"Untracked files:",
+			"untracked_review.go",
+			"Git diff:",
+			"diff --git a/untracked_review.go b/untracked_review.go",
+			"func untrackedReviewPath() error",
+		} {
+			if !strings.Contains(input, want) {
+				t.Fatalf("local AI reviewer input missing %q:\n%s", want, input)
+			}
+		}
+		return 0
+	})
+	if code != 0 {
+		t.Fatalf("withTempProcessEnv code=%d", code)
+	}
+}
+
+func writeReviewerParityFixture(t *testing.T, cwd string) {
+	t.Helper()
+	runGit(t, cwd, "init")
+	runGit(t, cwd, "config", "user.email", "agents@example.test")
+	runGit(t, cwd, "config", "user.name", "Agents Test")
+	before := strings.Join([]string{
+		"package fixture",
+		"",
+		"func runCommand(name string, trusted bool) error {",
+		"	switch name {",
+		`	case "write":`,
+		"		return writeData()",
+		`	case "read":`,
+		"		return readData()",
+		"	default:",
+		"		return nil",
+		"	}",
+		"}",
+		"",
+		"func writeData() error { return nil }",
+		"func readData() error { return nil }",
+		"",
+	}, "\n")
+	if err := os.WriteFile(filepath.Join(cwd, "commands.go"), []byte(before), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	runGit(t, cwd, "add", "commands.go")
+	runGit(t, cwd, "commit", "-m", "base")
+	after := strings.Replace(before, "\t\treturn writeData()", "\t\tif !trusted {\n\t\t\treturn nil\n\t\t}\n\t\treturn writeData()", 1)
+	if err := os.WriteFile(filepath.Join(cwd, "commands.go"), []byte(after), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func runGit(t *testing.T, cwd string, args ...string) {
+	t.Helper()
+	cmd := exec.Command("git", append([]string{"-C", cwd}, args...)...)
+	if out, err := cmd.CombinedOutput(); err != nil {
+		t.Fatalf("git %v failed: %v\n%s", args, err, out)
+	}
+}
+
 func TestLocalAIFirstPassFindingsSkipConfiguredReviewer(t *testing.T) {
 	old := runFirstPassReviewWithLocalAI
 	defer func() { runFirstPassReviewWithLocalAI = old }()

internal/app/local_ai.go

@@ -344,6 +344,8 @@ func runLocalAIReviewerItem(e env, state loopState, rc roleConfig, settings agen
 func runFirstPassReviewWithOpenAICompat(settings agentSettings, input string) (localAIReviewResult, error) {
 	content, err := localAIChat(settings,
 		"You are a reviewer in an ordered Agents review pipeline. Review only the provided task context. "+
+			"Start from the full diff, enumerate changed functions and sibling branches/paths, check parity across success/error/early-return/404/fallback and read/write counterparts, and include that branch checklist in the summary. "+
+			"When reviewing a provided finding, inspect the enclosing function and sibling branches before passing; return fail with one finding per real issue for any parity gap independent of seeded findings. "+
 			"Return only JSON: {\"result\":\"pass|fail|escalate\",\"summary\":\"...\",\"findings\":[{\"severity\":\"low|medium|high\",\"text\":\"...\",\"evidence\":\"...\"}]}. "+
 			"Use fail only for concrete, grounded issues. Use pass when there are no blocking issues. Use escalate when the context is insufficient or uncertain.",
 		strings.TrimSpace(input),
@@ -364,6 +366,14 @@ func localAIReviewInput(e env, state loopState) string {
 	if stat := gitDiffStat(e.cwd); strings.TrimSpace(stat) != "" {
 		fmt.Fprintf(&b, "\nGit diff stat:\n%s\n", stat)
 	}
+	if diff := gitDiff(e.cwd); strings.TrimSpace(diff) != "" {
+		fmt.Fprintf(&b, "\nGit diff:\n%s\n", diff)
+	}
+	fmt.Fprintln(&b, "\nReviewer branch checklist requirements:")
+	fmt.Fprintln(&b, "- Start from the full diff before judging seeded findings.")
+	fmt.Fprintln(&b, "- Enumerate changed functions and sibling branches/paths.")
+	fmt.Fprintln(&b, "- Check parity across success, error, early-return, 404, fallback, read counterpart, and write counterpart paths.")
+	fmt.Fprintln(&b, "- Record one finding per real issue independent of seeded findings.")
 	return b.String()
 }
 

internal/app/local_ai_test.go

@@ -5,6 +5,7 @@ import (
 	"net"
 	"net/http"
 	"net/http/httptest"
+	"strings"
 	"testing"
 )
 
@@ -180,6 +181,16 @@ func TestRunFirstPassReviewWithOpenAICompat(t *testing.T) {
 		if req.Model != "google/gemma-3-4b" || len(req.Messages) != 2 || req.Messages[1].Content != "review context" {
 			t.Fatalf("unexpected request: %+v", req)
 		}
+		for _, want := range []string{
+			"Start from the full diff",
+			"enumerate changed functions and sibling branches/paths",
+			"success/error/early-return/404/fallback and read/write counterparts",
+			"one finding per real issue",
+		} {
+			if !strings.Contains(req.Messages[0].Content, want) {
+				t.Fatalf("review system prompt missing %q:\n%s", want, req.Messages[0].Content)
+			}
+		}
 		_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"{\"result\":\"pass\",\"summary\":\"clean\",\"findings\":[]}"}}]}`))
 	}))
 	defer server.Close()