diff --git a/Tests/Objective-J/Preprocessor/BehaviorTests/IvarTest.j b/Tests/Objective-J/Preprocessor/BehaviorTests/IvarTest.j
index 4cbeb713f..d9259ba76 100644
--- a/Tests/Objective-J/Preprocessor/BehaviorTests/IvarTest.j
+++ b/Tests/Objective-J/Preprocessor/BehaviorTests/IvarTest.j
@@ -1,5 +1,24 @@
 @import <Foundation/Foundation.j>
 
+/*
+ * NOTE: INTENTIONAL COMPILER WARNINGS
+ *
+ * The shadowing warnings generated by this file (e.g., "Local declaration
+ * of 'ivar1' hides instance variable") are an expected artifact of the test.
+ *
+ * The objective of these methods is to validate the compiler's code generation
+ * during a shadowing event. In standard Objective-J, unqualified instance
+ * variables are transformed into explicit accessors (e.g., self.ivar1). When a
+ * local variable shares the same identifier, the AST transformation must
+ * intentionally suppress this behavior to maintain proper lexical scope.
+ *
+ * Modifying the static Objective-J declarations to avoid the warning would
+ * remove the shadowing condition from the AST, fundamentally invalidating
+ * the runtime verification of the compiler's output. Until explicit block-level
+ * diagnostic suppression is implemented in the parser, these specific warnings
+ * must be tolerated to ensure the structural integrity of the code generator.
+ */
+
 @implementation IvarTestClass : CPObject
 {
     id ivar1 @accessors;