Fix: clang-tidy on macOS resolve Apple SDK headers

[ChaoWao]

Summary

• Homebrew clang-tidy on macOS bakes in a default sysroot path that often
  doesn't match the installed SDK, causing 'algorithm' file not found
  errors on fresh checkouts (the underlying issue is the libc include
  cascade triggered by libc++ internals, not <algorithm> itself).
• tests/lint/clang_tidy.py now injects -isysroot $SDK and
  -isystem $SDK/usr/include/c++/v1 on macOS via --extra-arg=.
  No-op on Linux. Works whether phase 1 was built with Apple Clang
  or Homebrew Clang.
• New docs/troubleshooting/macos-build.md documents the three-phase
  build toolchain matrix, the Apple-vs-Homebrew Clang asymmetry
  (xcrun runtime resolution vs baked default), the <algorithm> cascade
  failure mode, and an optional fully-Homebrew phase 1 setup
  (LDFLAGS pointing at Homebrew libc++ runtime, source-installs of
  nanobind/pybind11).
• Move docs/macos-libomp-collision.md →
  docs/troubleshooting/macos-libomp-collision.md so macOS-specific
  troubleshooting docs live in one place; update all in-repo cross
  references (conftest.py, docs/ci.md, docs/python-packaging.md,
  examples/workers/l3/*/main.py).

Why two flags

Flag	Purpose
-isysroot $SDK	Lets the libc cascade (<algorithm> → <wchar.h> via libc++ #include_next) resolve. Without this clang-tidy cannot lint any C++ file.
-isystem $SDK/usr/include/c++/v1	Forces clang-tidy onto Apple SDK's libc++ headers (matching what the Apple-Clang build sees) instead of Homebrew's bundled libc++. Eliminates "lint sees one libc++, build sees another" version drift.

xcrun --show-sdk-path returns the version-stable symlink
(MacOSX.sdk), so the patch survives SDK upgrades without code change.

Testing

• pre-commit run --all-files (clang-tidy and markdownlint pass)
• Spot-check mixed_example and spmd_starvation sim ST tests
  still pass
• Linux CI green (no behavior change on non-Darwin)

Notes

This PR is intentionally narrow: only the lint + docs changes. A
follow-up PR refactors the dep computation in submit_task
(compute_task_fanin / register_task_outputs); discovering the
clang-tidy issue was a side effect of trying to land that refactor
through pre-commit on macOS.

[gemini-code-assist]

Code Review

This pull request introduces a new macOS troubleshooting guide and updates documentation paths across the repository. It also implements a fix in the linting script to handle macOS-specific header resolution for clang-tidy by injecting sysroot flags. Feedback indicates that the documentation snippet for the new logic should be updated to match the actual, more robust implementation in the code.