It does. It trusts the templates rather than parsing the configuration file.
discourse-setup always sets a value (it won’t leave the line commented out); those who use discourse-setup will never have a problem with the default SMTP port being “wrong”; that’s why this seems the be the first time this has come up. (And it would seem that even before discourse-setup existed, no one decided to leave the port commented out and expect the default to be 587; it just makes more sense to set the port rather than hoping that the default works). Changing it to 25 in standalone.yml and web_only.yml will encourage people who do use discourse-setup to use port 25, which will likely mean that a bunch of people will have to type 587 rather than just hitting enter, and some others, who don’t know what a port is, will blindly accept the default and probably have problems figuring that out. I think that there will be more people in the set than those who know how to edit a text file and choose leave the SMTP port commented out rather than entering the value that they actually want.
The only time this “bug” can occur is if someone edits standalone.yml by hand and chooses to leave the SMTP port commented out rather than providing a value. Whether the templates are wrong or the actual default is wrong is unclear.