Document why manual block-param tracking is used instead of scope manager

Author: johanrd

lib/rules/template-no-obsolete-elements.js

@@ -50,6 +50,19 @@ module.exports = {
   },
   create(context) {
     const obsolete = new Set(OBSOLETE);
+
+    // Manual block-param tracking is intentional here. The ESLint scope manager
+    // cannot be used as a drop-in replacement because:
+    //
+    // 1. In GJS/GTS, an element's own `as |x|` block params are already
+    //    visible in the scope at the element node itself, so getScope(node) on
+    //    `<marquee as |marquee|>` would incorrectly skip flagging it.
+    //
+    // 2. In HBS mode the scope manager only creates a minimal top-level scope;
+    //    block params from `{{#let ... as |x|}}` are not registered, so
+    //    getScope would not see them at all.
+    //
+    // The push/pop approach handles both edge cases correctly.
     const blockParamsInScope = [];
 
     return {