docs: reconcile rule 8 with the System::Linq surface, and correct a claim the header could not support

Both queues empty, so this turn audited the mechanically checkable rules in
CLAUDE.md. Three came back clean and one exposed an apparent contradiction.

CLEAN: rule 4 (SPDX) -- 1,273 production files, 0 missing. Rule 6 (C++17 nested
namespace form) -- 0 old-form sites. And the porting checklist's "no bare
NotImplementedException stub" -- 6 production throw sites, every one carrying an
explanatory comment. (A looser first count said 9; the extra three are
doc-comments saying @throws, not code.)

THE CONTRADICTION: rule 8 read "No LINQ. Use std::ranges in ported code
instead", unqualified -- while modules/core/include/System/Linq.hpp is a
508-line System::Linq with Where, Select, FirstOrDefault and ~17 more. Read
alone, the rule says the tree violates it.

It does not: the rule governs code THIS project writes, and the header is a
compatibility surface for ported C#/XNA call sites. That reconciliation existed
only in the header, so it is now in CLAUDE.md too, where it is loaded every
session.

AND THE HEADER'S OWN JUSTIFICATION WAS TOO STRONG. It said the class "exists
only to support already-ported C#/XNA call sites that use these operators",
which implies such sites exist. Measured with a strict search for
`System::Linq::`: ZERO uses in this repository's production code, ZERO in cna,
ZERO in mobile-eggbert. Its only users are its own two test files. A first,
looser grep suggested four production sites; all four were Xml::Linq, a
different namespace.

So it is a capability offered IN ADVANCE of a caller rather than a response to
one. Both the header and rule 8 now say that, and both record that removing it
would be a public-surface decision rather than a cleanup -- which is why this
change corrects the wording and touches no code.

Comment and documentation only; the full build is clean and the gate is
unaffected at 17,585.

Author: robertvokac

CLAUDE.md

@@ -18,7 +18,16 @@
    parameterized-property case, applied across every indexer in the codebase.
 6. **Namespace syntax:** `namespace System::Collections::Generic {` (C++17 nested form).
 7. **Use `SharpRuntime::intcs`, not `int`** in public APIs that mirror .NET `int` parameters.
-8. **No LINQ.** Use `std::ranges` in ported code instead.
+8. **No LINQ** in the code this project writes — use `std::ranges` in ported bodies instead.
+   **This does not mean the tree contains no LINQ surface, and the distinction is worth stating
+   here because the two look like a contradiction otherwise**: `modules/core/include/System/Linq.hpp`
+   is a 508-line `System::Linq` providing `Where`, `Select`, `FirstOrDefault` and ~17 more over
+   `std::vector<T>`. It exists as a **compatibility surface for ported C#/XNA call sites**, not as
+   a licence to use those operators in new code. Measured 2026-08-19: a strict search for
+   `System::Linq::` finds **zero** uses in this repository's production code, **zero** in `cna` and
+   **zero** in `mobile-eggbert` — its only users are its own two test files. So it is a capability
+   offered *in advance* of a caller; removing it would be a public-surface decision rather than a
+   cleanup.
 9. **No merge to master or tags** without explicit per-action user approval.
 10. **No broad header refactor** — naming conventions touch 449+ files and would break CNA.
 11. **Copy doc-comments from .NET source** — when porting a type, if the `.NET` source (`/rv/tmp/runtime/src/libraries/`) has XML doc comments and the sharp-runtime header has none, copy them as Doxygen `/** */` comments where the meaning translates cleanly to C++.

modules/core/include/System/Linq.hpp

@@ -31,9 +31,24 @@ namespace System::Linq {
      * Concat, Contains. Not implemented (real .NET's Enumerable surface is 100+ methods):
      * GroupBy, Join, Zip, SelectMany, ToDictionary, ToHashSet, Average, Aggregate, ElementAt,
      * SkipWhile, TakeWhile, Except, Intersect, Union, SequenceEqual, Single/SingleOrDefault,
-     * DefaultIfEmpty, Chunk, and more -- add on demand as ported code needs them, per
-     * CLAUDE.md's "No LINQ" policy for code THIS project writes (this class exists only to
-     * support already-ported C#/XNA call sites that use these operators).
+     * DefaultIfEmpty, Chunk, and more -- add on demand as ported code needs them.
+     *
+     * @note **How this squares with CLAUDE.md rule 8, "No LINQ".** That rule governs the code
+     * THIS project writes: ported bodies use `std::ranges`, not these operators. This header is
+     * the other side of it -- a compatibility surface for ported C#/XNA call sites that already
+     * spell `Where`/`Select`/`FirstOrDefault`.
+     *
+     * @note **Measured 2026-08-19, because the previous wording claimed more than is true.** It
+     * said this "exists only to support already-ported C#/XNA call sites that use these
+     * operators", which implies such sites exist. They do not, anywhere: a strict search for
+     * `System::Linq::` finds **zero** uses in this repository's production code, **zero** in
+     * `cna` and **zero** in `mobile-eggbert`. Its only users are its own two test files
+     * (`LinqTests.cpp` and `ComparisonContractTests.cpp`).
+     *
+     * So this is a capability offered **in advance** of a caller rather than a response to one.
+     * That is a deliberate position and not a defect -- the surface is what lets a future port
+     * land without first re-litigating rule 8 -- but it should be read as such, and its removal
+     * would be a public-surface decision rather than a cleanup.
      *
      * @note Status: PARTIAL
      */