Add comments explaining the two-pass condition matching in filterBySpecifiedTypes

Pass 1 uses exact equals() matching. Pass 2 falls back to isSuperTypeOf()
for cases where the condition type is broader than the narrowed expression
type (e.g. union condition types from conditional parameter types or scope
merging). Pass 1 takes priority to prevent broader conditions from degrading
certainty calculations.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: phpstan-bot

src/Analyser/MutatingScope.php

@@ -3217,6 +3217,8 @@ public function filterBySpecifiedTypes(SpecifiedTypes $specifiedTypes): self
 					continue;
 				}
 
+				// Pass 1: Exact match - condition type must equal the specified expression type.
+				// This handles most cases and takes priority over Pass 2.
 				foreach ($conditionalExpressions as $conditionalExpression) {
 					foreach ($conditionalExpression->getConditionExpressionTypeHolders() as $holderExprString => $conditionalTypeHolder) {
 						if (
@@ -3235,6 +3237,22 @@ public function filterBySpecifiedTypes(SpecifiedTypes $specifiedTypes): self
 					continue;
 				}
 
+				// Pass 2: Supertype match - condition type must be a supertype of the specified
+				// expression type. Only runs when Pass 1 found no exact match for this expression.
+				//
+				// This is needed for conditional parameter types with union conditions:
+				// e.g. @param ($p is 'a' ? bool : int) with $p typed as 'a'|'b'|'c'
+				// creates a condition type 'b'|'c' (from TypeCombinator::remove) for the int result.
+				// When $p is narrowed to 'b', equals('b', 'b'|'c') fails but isSuperTypeOf succeeds.
+				//
+				// Also needed for scope merging: e.g. $a=0 then if (is_string||is_int) $a=1
+				// creates a condition type int|string. When narrowed to is_int, the condition
+				// int|string is a supertype of int, so the match succeeds.
+				//
+				// Pass 1 must take priority because when both exact and broader conditions exist
+				// (e.g. from scope merging creating both "$key=2 => $value Yes" and
+				// "$key=0|2 => $value Maybe"), the broader match would degrade certainty
+				// via extremeIdentity (Yes AND Maybe = Maybe), causing false positives.
 				foreach ($conditionalExpressions as $conditionalExpression) {
 					foreach ($conditionalExpression->getConditionExpressionTypeHolders() as $holderExprString => $conditionalTypeHolder) {
 						if (