I have no idea what the right thing to do here is since each distribution uses its own numbering scheme for PKGVERS (in particular PKGVERS_BRANCH).

For example, if somebody was to obsolete system/kernel, then picking a couple of IPS distributions we have:

pkg://omnios/system/kernel@0.5.11-151030.0:20190426T224620Z
pkg://openindiana.org/system/kernel@0.5.11-2018.0.0.18384:20190507T024548Z

and there's no one hard-coded value of PKGVERS that would cover both. It seems that the best we can do is what has been done here, which will result in a new obsoleted package being published whenever PKGVERS changes.

Because illumos-gate isn't a distribution that ships to folks, we have been leaving $(PKGVERS) there.  The expectation is that distributions will manage their version numbering as they see fit, and that would include obsolescence.  It's definitely true that we don't provide a great framework for doing this today, especially if you want something that doesn't involve patching the manifests downstream.

OK. Maybe we should update the README.

As others have noted, there is no valid static PKGVERS that can be set.
As for removing the legacy manifests, that's likely to be safe - the only use they have is for people upgrading from OpenSolaris build 133 or earlier (also, we got rid of a lot of the old package names in 8002, for instance).