docs(contributing): add contribution volume and batching guidance

Documents expectations for keeping contribution flow sustainable during the
stabilization phase: one issue per bug (no bundled multi-finding audits), keep
only a few items open at a time, and hold AI-assisted contributions to the same
per-item verification bar. Complements the existing issue-approved gate, which
already covers PR-to-issue linkage and scope; the gap was submission volume.

CONTRIBUTING.md

@@ -67,6 +67,28 @@ An approved issue means only that the specific issue has been accepted for work.
 It does not approve unrelated future work, future pull requests, or future issues
 from the same author. Each issue is reviewed case by case.
 
+## Contribution Volume and Batching
+
+To keep triage and review sustainable while the project stabilizes, please keep
+your contribution flow to a size the core team can realistically work through:
+
+- One issue per bug. File each defect as its own issue with its own
+  reproduction. Please do not bundle several unrelated findings into a single
+  "audit" issue; separate issues are far easier to triage, approve, and close
+  individually.
+- Keep only a few items open at a time. If you already have several issues or
+  pull requests awaiting review, let those move through the queue before opening
+  more. A large simultaneous burst from one contributor slows review for
+  everyone, even when each item is valid.
+- AI-assisted contributions are welcome, held to the same bar. Automated audits
+  and generated patches are fine, but each issue and pull request must be
+  individually verified, scoped, and reproducible before you open it. Please do
+  not post bulk machine-generated findings unfiltered.
+
+These apply to all contributors and are about review bandwidth, not the value of
+any single report. Maintainers may ask you to consolidate, split, or hold
+submissions to keep the queue manageable.
+
 ## Pull Request Requirements
 
 Before opening a community pull request, make sure all of the following are true:

internal/tools/file_tools_test.go

@@ -829,3 +829,61 @@ func TestGlobSkipsWorkspaceExcludedDirectoriesAndBinaryFiles(t *testing.T) {
 		t.Fatalf("expected only keep.txt, got:\n%s", res.Output)
 	}
 }
+
+// A backwards range (end_line < start_line) is a caller-arithmetic slip, not a
+// fatal error: read_file recovers by reading just start_line and surfaces a note
+// explaining the adjustment, matching how an end_line past EOF is auto-clamped.
+// It must never hard-error the way it used to.
+func TestReadFileToolRecoversBackwardsRange(t *testing.T) {
+	root := t.TempDir()
+	writeTestFile(t, filepath.Join(root, "notes.txt"), "alpha\nbeta\ngamma\ndelta\nepsilon")
+
+	result := NewReadFileTool(root).Run(context.Background(), map[string]any{
+		"path":       "notes.txt",
+		"start_line": 3,
+		"end_line":   2, // backwards
+	})
+
+	if result.Status != StatusOK {
+		t.Fatalf("backwards range must recover, not error; got %s: %s", result.Status, result.Output)
+	}
+	if strings.Contains(result.Output, "must be greater than or equal to start_line") {
+		t.Fatalf("backwards range still hard-errors: %q", result.Output)
+	}
+	for _, want := range []string{
+		"end_line 2 was before start_line 3", // the note
+		"only line 3 was read",
+		"3 | gamma",
+	} {
+		if !strings.Contains(result.Output, want) {
+			t.Fatalf("expected %q in output, got %q", want, result.Output)
+		}
+	}
+	// It read exactly start_line, nothing adjacent.
+	if strings.Contains(result.Output, "beta") || strings.Contains(result.Output, "delta") {
+		t.Fatalf("recovery read the wrong lines: %q", result.Output)
+	}
+}
+
+// A valid range with end_line >= start_line is byte-for-byte unchanged: the
+// recovery path must not touch normal reads (no stray note, exact same window).
+func TestReadFileToolValidRangeUnchangedByRecovery(t *testing.T) {
+	root := t.TempDir()
+	writeTestFile(t, filepath.Join(root, "notes.txt"), "alpha\nbeta\ngamma\ndelta\nepsilon")
+
+	result := NewReadFileTool(root).Run(context.Background(), map[string]any{
+		"path":       "notes.txt",
+		"start_line": 2,
+		"end_line":   4,
+	})
+	if result.Status != StatusOK {
+		t.Fatalf("valid range failed: %s: %s", result.Status, result.Output)
+	}
+	// Byte-for-byte: header, blank separator, the exact selected lines, and no
+	// recovery note or trailing content. An altered header/separator or a stray
+	// out-of-range line would fail this where a substring check would not.
+	const want = "File: notes.txt (lines 2-4 of 5)\n\n2 | beta\n3 | gamma\n4 | delta"
+	if result.Output != want {
+		t.Fatalf("valid-range output changed by the recovery path:\n got: %q\nwant: %q", result.Output, want)
+	}
+}

internal/tools/read_file.go

@@ -106,8 +106,18 @@ func renderReadFileRange(absolutePath string, relativePath string, total int, st
 	if endLine == 0 || endLine > total {
 		endLine = total
 	}
+	// A backwards range (end_line < start_line) is a caller slip, not a fatal
+	// error. Recover the way an end_line past EOF is already recovered a few lines
+	// up (clamped down to the last line): clamp end_line UP to start_line and read
+	// just that one line. Erroring here instead cost the caller a whole retry for
+	// an off-by-arithmetic mistake, and it was inconsistent — start_line past EOF
+	// and end_line past EOF both recover gracefully; only this case hard-failed.
+	// The recovery is surfaced in the output (rangeNote) so it is never silent: the
+	// caller sees it read a different range than it asked for and why.
+	rangeNote := ""
 	if endLine < startLine {
-		return errorResult("Error: Invalid arguments for read_file: end_line must be greater than or equal to start_line")
+		rangeNote = fmt.Sprintf("(note: end_line %d was before start_line %d, so only line %d was read — pass end_line >= start_line to read a wider range)", endLine, startLine, startLine)
+		endLine = startLine
 	}
 
 	truncated := false
@@ -135,7 +145,12 @@ func renderReadFileRange(absolutePath string, relativePath string, total int, st
 		budgetedOutput = newHeadTailOutputBudgetBuilder(readOutputBudgetBytes, "use start_line/end_line or max_lines to continue with a smaller range")
 	}
 	budgetedOutput.WriteString(header)
-	budgetedOutput.WriteString("\n\n")
+	budgetedOutput.WriteString("\n")
+	if rangeNote != "" {
+		budgetedOutput.WriteString(rangeNote)
+		budgetedOutput.WriteString("\n")
+	}
+	budgetedOutput.WriteString("\n")
 	if err := appendReadFileRange(budgetedOutput, absolutePath, startLine, selectedLines, width); err != nil {
 		return errorResult("Error reading file " + relativePath + ": " + err.Error())
 	}