Adds FileCoveredByDocMap(cfg *DocMapConfig, file string) bool — a thin wrapper
over the existing unexported mappingMatches that lets cmd/ check per-file docmap
coverage without duplicating glob logic.

Also adds unit tests covering matched globs, non-matching paths, empty file,
and empty config.

@@ -0,0 +93,4 @@
+		}
+	}
+
+	if failed {

@@ -0,0 +125,4 @@
+	return stale
+}
+
+// readLines reads all non-empty trimmed lines from r.

@@ -0,0 +70,4 @@
+	// Provide stdin via the global os.Stdin would require process tricks.
+	// The implementation reads os.Stdin directly; for tests we need a different approach.
+	// See TestRunValidateDocmap_WithStdin_* below which use a helper that replaces os.Stdin.
+	// This case: empty stdin (no changed files) → clean.

@@ -0,0 +116,4 @@
+			}
+			seen[docPath] = struct{}{}
+
+			fullPath := filepath.Join(repoRoot, filepath.FromSlash(docPath))

@@ -0,0 +77,4 @@
+	if len(uncovered) > 0 {
+		failed = true
+		fmt.Fprintln(errWriter, "ERROR: changed files with no docmap coverage:")
+		for _, f := range uncovered {

@@ -0,0 +93,4 @@
+		}
+	}
+
+	if failed {

@@ -0,0 +41,4 @@
+	outWriter = &outBuf
+	errWriter = &errBuf
+	defer func() {
+		outWriter = origOut

@@ -0,0 +115,4 @@
+				continue
+			}
+			seen[docPath] = struct{}{}
+

@@ -0,0 +71,4 @@
+	var uncovered []string
+	for _, f := range changedFiles {
+		if !review.FileCoveredByDocMap(cfg, f) {
+			uncovered = append(uncovered, f)

@@ -0,0 +86,4 @@
+	// checkStaleDocs validates each path before touching the filesystem; see
+	// its documentation for the path-traversal hardening applied.
+	repoRoot := filepath.Clean(*repoRootFlag)
+	staleDocs := checkStaleDocs(cfg, repoRoot)

@@ -0,0 +155,4 @@
+	})
+	return
+}
+

@@ -0,0 +103,4 @@
+	return 0
+}
+
+// checkStaleDocs returns deduplicated docs: entries that do not exist under

@@ -0,0 +115,4 @@
+	seen := make(map[string]struct{})
+	var stale []string
+
+	for _, mapping := range cfg.Mappings {

@@ -0,0 +83,4 @@
+	}
+
+	// --- Check 2: Stale docs ---
+	// checkStaleDocs validates each path before touching the filesystem; see

@@ -0,0 +134,4 @@
+
+			// Guard 2: verify the cleaned joined path does not escape repoRoot.
+			// filepath.Clean resolves any remaining ".." after the join; the
+			// filepath.Rel check confirms the path is still under repoRoot.

@@ -306,3 +317,4 @@
+func ValidateDocPath(p string) error {
 	if filepath.IsAbs(p) {
 		return fmt.Errorf("absolute paths not allowed")
 	}

@@ -0,0 +40,4 @@
+	if err := fs.Parse(args); err != nil {
+		// flag.ContinueOnError already wrote the error to errWriter.
+		return 2
+	}

@@ -0,0 +54,4 @@
+	// Parse docmap YAML.
+	cfg, err := review.ParseDocMapConfig(*docmapFlag)
+	if err != nil {
+		fmt.Fprintf(errWriter, "Error: failed to parse docmap %q: %v\n", *docmapFlag, err)

@@ -0,0 +144,4 @@
+	}
+	if _, err := f.Seek(0, 0); err != nil {
+		t.Fatalf("Seek for stdin: %v", err)
+	}

@@ -298,11 +310,15 @@ func readFileBytes(path string) ([]byte, error) {
 	return os.ReadFile(path)

@@ -1,42 +1,47 @@
-## Dev Loop Status: 2026-05-15 04:35 UTC
+## Dev Loop Status: 2026-05-15 07:02 UTC

@@ -0,0 +83,4 @@
+	}
+
+	// --- Check 2: Stale docs ---
+	// Resolve repoRoot to an absolute, symlink-free path before any Rel checks

@@ -0,0 +98,4 @@
+	}
+	// checkStaleDocs validates each path before touching the filesystem; see
+	// its documentation for the path-traversal hardening applied.
+	staleDocs := checkStaleDocs(cfg, resolvedRoot)

@@ -0,0 +188,4 @@
+	// docs/foo.md intentionally missing
+
+	docmap := makeDocmapYAML(t, `
+mappings:

@@ -306,0 +316,4 @@
+// to avoid any quirk in backend path handling. Backslashes are rejected
+// explicitly to prevent Windows platform edge cases.
+func ValidateDocPath(p string) error {
+	if strings.Contains(p, "\\") {

@@ -0,0 +70,4 @@
+	// --- Check 1: Coverage ---
+	var uncovered []string
+	for _, f := range changedFiles {
+		if !review.FileCoveredByDocMap(cfg, f) {

@@ -0,0 +151,4 @@
+			// filepath.Rel check confirms the path is still under repoRoot.
+			fullPath := filepath.Clean(filepath.Join(repoRoot, filepath.FromSlash(docPath)))
+			rel, err := filepath.Rel(repoRoot, fullPath)
+			if err != nil || strings.HasPrefix(rel, "..") {

@@ -0,0 +45,4 @@
+	if *docmapFlag == "" {
+		fmt.Fprintln(errWriter, "Error: --docmap is required")
+		fmt.Fprintln(errWriter, "")
+		fmt.Fprintln(errWriter, "usage: review-bot validate-docmap --docmap <path> [--repo-root <dir>]")

@@ -0,0 +89,4 @@
+		}
+	}
+
+	// --- Check 2: Stale docs ---

@@ -0,0 +152,4 @@
+		t.Fatalf("Seek for stdin: %v", err)
+	}
+
+	origStdin := os.Stdin

@@ -66,6 +66,18 @@ func ParseDocMapConfig(localPath string) (*DocMapConfig, error) {
 	return &cfg, nil
 }
 

@@ -296,6 +296,40 @@ review-bot \
   --conventions-file CONVENTIONS.md
 ```

@@ -0,0 +164,4 @@
+			rel, err := filepath.Rel(repoRoot, fullPath)
+			if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(os.PathSeparator)) {
+				stale = append(stale, docPath)
+				continue

@@ -66,6 +66,18 @@ func ParseDocMapConfig(localPath string) (*DocMapConfig, error) {
 	return &cfg, nil

@@ -0,0 +52,4 @@
+	}
+
+	// Parse docmap YAML.
+	cfg, err := review.ParseDocMapConfig(*docmapFlag)

@@ -0,0 +65,4 @@
+	return nil
+}
+
+// runValidateDocmap implements the `review-bot validate-docmap` subcommand.

@@ -0,0 +152,4 @@
+
+	// --- Check 1: Coverage ---
+	// Note: an empty docmap (no mappings) means every changed file is
+	// uncovered — there are no patterns to match against. This is intentional:

@@ -0,0 +174,4 @@
+	os.Stdin = f
+	defer func() { os.Stdin = origStdin }()
+
+	stdout, stderr = captureOutput(func() {

@@ -0,0 +320,4 @@
+
+	// Baseline: a valid doc that exists.
+	makeDocFile(t, dir, "docs/valid.md")
+

@@ -305,1 +313,3 @@
-func validateDocPath(p string) error {
+// ValidateDocPath rejects doc paths that could cause path traversal
+// (absolute paths, any ".." segment, backslashes). Defense-in-depth: callers
+// must also confine the joined path to the repo root via filepath.Rel before

@@ -0,0 +30,4 @@
+//
+// resolvedRoot must already be an absolute, symlink-free path (obtained from
+// filepath.Abs + filepath.EvalSymlinks).
+func validateDocmapPath(localPath, resolvedRoot string) error {

@@ -0,0 +10,4 @@
+	"strings"
+
+	"gitea.weiker.me/rodin/review-bot/review"
+)

@@ -0,0 +90,4 @@
+	docmapFlag := fs.String("docmap", "", "Path to doc-map YAML file (required)")
+	repoRootFlag := fs.String("repo-root", ".", "Repo root for resolving docs: paths (default: cwd)")
+
+	if err := fs.Parse(args); err != nil {

@@ -0,0 +165,4 @@
+	defer f.Close()
+	if _, err := f.WriteString(stdinContent); err != nil {
+		t.Fatalf("WriteString for stdin: %v", err)
+	}

@@ -306,0 +318,4 @@
+func ValidateDocPath(p string) error {
+	if strings.Contains(p, "\\") {
+		return fmt.Errorf("backslashes not allowed in doc paths")
+	}

@@ -0,0 +57,4 @@
+		return fmt.Errorf("path must be within --repo-root")
+	}
+
+	// Enforce size cap before reading to prevent memory exhaustion.

@@ -0,0 +221,4 @@
+			if err := review.ValidateDocPath(docPath); err != nil {
+				stale = append(stale, docPath)
+				continue
+			}

@@ -0,0 +38,4 @@
+	}
+
+	// Lstat: do NOT follow symlinks. We want to inspect the entry itself.
+	fi, err := os.Lstat(absPath)

@@ -0,0 +45,4 @@
+
+	// Reject symlinks outright — a symlink can point to /dev/zero or arbitrary
+	// host paths, bypassing both the confinement check and the size check.
+	if fi.Mode()&os.ModeSymlink != 0 {