Why would it do this?
There is already mining.suggest_difficulty(difficulty)
Someone didn't read the docs and added it to their non-standard miner clone?

Let me be the first to say thank you first designing, implementing and now collecting this information for all.  Much more concise reading than https://bt.irlbtc.com/view/108533.660 or what else I've found on the pools pages.

Forum posts are not documentation.

Hard to see how I forget something I never read in the first place.
I don't see anything relevant there anyway. Con agreed to implement slush's spec and then never did. How is this relevant?

From a protocol development perspective, stratum being defined in terms of difficulty is an embarrassing flaw of the sort that would have been avoided if it hadn't been developed behind closed doors. ... The fact that it's a floating point value which cannot precisely specify the actual values used in bitcoin is a pretty big facepalm.  All of this really should have been using bits like the bitcoin protocol does both for precision and consistency sake (or an expanded target— to accommodate legacy stupidity, but then again people will just get the byte order confused and complain it wastes bandwidth. ).

In any case, should have beens aside— what am I missing here?  There is no formal specification for stratum at all, slush was apparently sucked into Trezor land before publishing it.  AFAICT nothing is implementing the difficulty based message that was suggested way in the past, but at least luke's stuff has implemented the target based approach.  Whats to debate?

+1, suggest splitting side-discussion off to leave the thread to just the documentation posts.

As someone who's working on a Stratum implementation right now, I must say this is a VERY narrow view of reality.

I've been using the following resources to gain my knowledge of the protocol:
https://bt.irlbtc.com/view/55842.0
https://bt.irlbtc.com/view/108533.0
http://mining.bitcoin.cz/stratum-mining
https://www.btcguild.com/new_protocol.php

Notice how 50% of those links were forum posts   

But, I'm guessing none of the discussion here counts as documentation either and can be entirely ignored 

I DID!!!!

Thank you!

Since we're talking drafts, and implementation. Both that sticky, and I think Slush's website, mention HTTP Poll as an optional transport mechanism. Do any mining apps support HTTP Poll? Standard TCP sockets seems to be the prevailing implementation.

The initial development was secret to the public before it was up on slush's pool along with the python proxy. I'd always understood this to be a (anti- )competitive move.

There remains no BIP describing it, there was no design discussion prior to its release on bitcoin-development. Justifying the closed development, Slush wrote (in the second email my mailbox ever received mentioning stratum mining) "There's no requirement to have BIP for everything what people do. Stratum is NOT related to bitcoin protocol or bitcoin implementation, it is just custom, pooled-mining extension and bitcoin network doesn't need to know about Stratum existence at all."  Perhaps you were somehow an insider on it— if so, why didn't you discourage some of the poor choices in it?  But from my own perspective it really was developed in secret and, in my opinion, carries some of the predictable flaws of a protocol developed without broad input. It's not the end of the world, in any case. Far worse has been done elsewhere.