Guard incomplete clangd references

AGENTS.md

@@ -76,9 +76,13 @@ The helper talks to `clangd` using an existing `compile_commands.json`. It
 defaults to `out/build/windows-clangcl-asan` and then `out/build/android-arm64`;
 pass `--compile-commands-dir` or set `PP_CLANGD_COMPILE_COMMANDS_DIR` when using
 another Ninja build tree. Use `--name` and `--max-results` to keep output small.
-References are fast/current-translation-unit by default; add
-`--background-index` only when broader cross-file references are worth the extra
-indexing work.
+Treat symbol, hover, declaration, definition, and implementation lookups as the
+reliable path. Reference lookups are riskier because a one-shot clangd process
+may not have a complete project index; the helper refuses reference queries
+unless callers pass `--background-index` for broader best-effort results or
+`--allow-incomplete-references` for explicitly current-translation-unit-only
+results. Do not use incomplete reference output as proof that a symbol has no
+other users.
 
 ## Current Architecture Direction
 

docs/modernization/build-inventory.md

@@ -94,10 +94,13 @@ Known local toolchain state:
   `scripts/dev/clangd_nav.py` provides agent-friendly symbol, definition,
   declaration, implementation, reference, and hover lookup through clangd using
   the current `compile_commands.json` from `windows-clangcl-asan`,
-  `android-arm64`, or a caller-provided build directory. It disables clangd
-  background indexing by default for quick current-translation-unit lookups; pass
-  `--background-index` when broader cross-file references are worth the extra
-  indexing work.
+  `android-arm64`, or a caller-provided build directory. Symbol, hover,
+  declaration, definition, and implementation lookups are the reliable use case.
+  Reference lookup is guarded because a one-shot clangd process may not have a
+  complete project index: pass `--background-index` for broader best-effort
+  results or `--allow-incomplete-references` for explicitly
+  current-translation-unit-only results, and do not treat incomplete references
+  as proof that no other users exist.
 - Android arm64 headless configure/build passes through root CMake and the
   `platform-build` automation wrapper for `pp_foundation`, `pp_assets`,
   `pp_paint`, `pp_document`, `pp_renderer_api`, `pp_renderer_gl`,

scripts/dev/clangd_nav.py

@@ -324,6 +324,13 @@ def run(args: argparse.Namespace) -> int:
     compile_commands_dir = _find_compile_commands_dir(repo_root, args.compile_commands_dir)
     file_path = _resolve_file(repo_root, args.file)
 
+    if args.command == "references" and not args.background_index and not args.allow_incomplete_references:
+        raise SystemExit(
+            "references may be incomplete without clangd background indexing. "
+            "Pass --background-index for a broader best-effort query or "
+            "--allow-incomplete-references for current-translation-unit lookup."
+        )
+
     client = ClangdClient(args.clangd, compile_commands_dir, args.timeout, args.background_index)
     try:
         client.request(
@@ -391,6 +398,11 @@ def run(args: argparse.Namespace) -> int:
                 "command": command,
                 "file": str(file_path),
                 "compileCommandsDir": str(compile_commands_dir),
+                "backgroundIndex": args.background_index,
+                "referenceCompleteness": (
+                    "not-applicable" if command != "references"
+                    else ("best-effort-background-index" if args.background_index else "current-translation-unit-only")
+                ),
                 "resultCount": result_count,
                 "truncated": truncated,
                 "result": result,
@@ -424,6 +436,11 @@ def main(argv: list[str]) -> int:
         action="store_true",
         help="Allow clangd to build/use its background index for broader cross-translation-unit references.",
     )
+    parser.add_argument(
+        "--allow-incomplete-references",
+        action="store_true",
+        help="Permit current-translation-unit-only references when --background-index is not enabled.",
+    )
     parser.add_argument(
         "--hierarchical",
         action="store_true",