Findings 1-3 from self-review (4dce8e4):

Finding 1 [NIT]: remove dead ModeSymlink check and its misleading
'defense-in-depth' comment. After filepath.EvalSymlinks, resolvedPath
is guaranteed symlink-free; fi.Mode()&os.ModeSymlink can never be set.
Dropped the unreachable branch; updated Lstat comment to say so.

Finding 2 [MINOR]: update validateDocmapPath godoc — invariant #2 now
reads 'The resolved path is within resolvedRoot' instead of 'The path
is not a symlink'. In-repo file-level symlinks whose resolved target
stays within the root are allowed; the confinement check enforces the
actual invariant.

Finding 3 [MINOR]: update inline comment in runValidateDocmap — the
bulleted list item now says 'Resolved target stays within the root
(in-repo symlinks allowed...)' instead of 'Is not a symlink'.

@@ -1509,0 +1540,4 @@
+// same validateDocmapPath that is invoked when --doc-map is provided to the
+// main review-bot command.
+func TestMainSubprocess_InvalidDocMapFile(t *testing.T) {
+	if os.Getenv("TEST_SUBPROCESS_MAIN") == "1" {

@@ -42,2 +53,4 @@
+	// ModeSymlink will never be set. We keep the check as defense-in-depth.
+	fi, err := os.Lstat(resolvedPath)
 	if err != nil {
 		return fmt.Errorf("cannot stat file: %w", err)

@@ -465,23 +465,34 @@ mappings:
 }

@@ -42,0 +46,4 @@
+	// path is inside the root while the actual destination is not.
+	resolvedPath, err := filepath.EvalSymlinks(absPath)
+	if err != nil {
+		return fmt.Errorf("cannot resolve path (symlink): %w", err)

@@ -37,22 +37,33 @@ func validateDocmapPath(localPath, resolvedRoot string) error {
 		return fmt.Errorf("cannot resolve path: %w", err)

@@ -46,3 +59,2 @@
-	// Reject symlinks outright — a symlink can point to /dev/zero or arbitrary
-	// host paths, bypassing both the confinement check and the size check.
+	// Defense-in-depth: reject any remaining symlink indicator.
 	if fi.Mode()&os.ModeSymlink != 0 {

@@ -490,10 +501,10 @@ mappings:
 		[]string{"--docmap", symlinkPath, "--repo-root", dir},

@@ -42,2 +53,4 @@
+	// ModeSymlink will never be set. We keep the check as defense-in-depth.
+	fi, err := os.Lstat(resolvedPath)
 	if err != nil {
 		return fmt.Errorf("cannot stat file: %w", err)

@@ -465,23 +465,34 @@ mappings:
 }

@@ -37,22 +37,33 @@ func validateDocmapPath(localPath, resolvedRoot string) error {
 		return fmt.Errorf("cannot resolve path: %w", err)

@@ -59,3 +57,1 @@
-	// Defense-in-depth: reject any remaining symlink indicator.
-	if fi.Mode()&os.ModeSymlink != 0 {
-		return fmt.Errorf("symlinks are not allowed")
+		return "", fmt.Errorf("cannot stat file: %w", err)

@@ -23,18 +23,19 @@ const maxDocmapBytes int64 = 10 * 1024 * 1024 // 10 MB
 //  1. The path resolves to a regular file within resolvedRoot (path

@@ -141,3 +138,3 @@
 	//   3. Does not exceed maxDocmapBytes (prevent memory exhaustion from an
 	//      oversized committed file).
-	if err := validateDocmapPath(*docmapFlag, resolvedRoot); err != nil {
+	// validateDocmapPath returns the resolved path; use it directly to

@@ -63,4 +59,4 @@
 
 	// Reject anything that is not a regular file (directories, FIFOs, device
 	// nodes, etc.) — ParseDocMapConfig expects a plain YAML file and would
 	// produce a confusing error on non-regular entries.

@@ -157,1 +155,4 @@
+	// Parse docmap YAML using the resolved path — eliminates any TOCTOU race
+	// between validation and use.
+	cfg, err := review.ParseDocMapConfig(resolvedDocmap)
 	if err != nil {

@@ -23,18 +23,19 @@ const maxDocmapBytes int64 = 10 * 1024 * 1024 // 10 MB
 //  1. The path resolves to a regular file within resolvedRoot (path

@@ -52,2 +53,2 @@
-	// Lstat the resolved path — at this point resolvedPath is symlink-free, so
-	// ModeSymlink will never be set. We keep the check as defense-in-depth.
+	// Lstat the resolved path — EvalSymlinks guarantees resolvedPath is
+	// symlink-free, so ModeSymlink can never be set here; this is unreachable.

@@ -652,0 +690,4 @@
+	if resolved == symlinkPath {
+		t.Errorf("expected resolved path to differ from symlink path")
+	}
+}

@@ -157,0 +157,4 @@
+	// here. The limit is maxDocmapBytes+1 so we can detect a file that grew past
+	// the cap after the stat without reading unbounded bytes.
+	f, err := os.Open(resolvedDocmap)
+	if err != nil {

@@ -66,3 +62,3 @@
 	// produce a confusing error on non-regular entries.
 	if !fi.Mode().IsRegular() {
-		return fmt.Errorf("docmap must be a regular file")
+		return "", fmt.Errorf("docmap must be a regular file")

@@ -154,3 +154,2 @@
 
-	// Parse docmap YAML.
-	cfg, err := review.ParseDocMapConfig(*docmapFlag)
+	// Open and read the docmap with a LimitedReader — closes the residual TOCTOU

@@ -67,3 +63,3 @@
 	if !fi.Mode().IsRegular() {
-		return fmt.Errorf("docmap must be a regular file")
+		return "", fmt.Errorf("docmap must be a regular file")
 	}

@@ -144,16 +140,59 @@ func runValidateDocmap(args []string) int {
 	// may reference a PR-controlled file (e.g. .review-bot/doc-map.yml).