I am somewhat unsure as to this PR.
Because we haven't locked a v3 spec what harm is there in just making changes directly to the spec document instead?

If the goal is for this to become part of a migration guide then the correct space for that to exist is the documentation site whose content can be found at YarnSpinnerTool/YSDocs.

Or have I misunderstood?

So, the idea here is the following: currently we have some language enhancement proposals, which are submitted as GitHub issues (as they should be). Once submitted, such proposal stays open for some time, there is some discussion, some back-and-forth. But for a very long time the status of a proposal remains uncertain: do we feel good about it? are there some unresolved questions? are we still thinking it over?

At some point though, the proposal gets implemented, a PR is merged, and then it's all done.

What I'm suggesting is to add an intermediate step into this process, whereas the proposal gets formally accepted before it can be implemented. And by "accepted" I mean that the author submits a PR with the description of the feature, that PR is reviewed one last time, approved by the team, and merged -- but this is a documentation only PR. At this point the original proposal issue can be closed.

After that, the new feature can be implemented, either by the original author, or by someone from the YS team, or by an outside contributor. There could be a separate issue tracking the implementation of the feature.

Why this extra step is beneficial?

• It gives the users a preview of what future holds.
• It makes it easier for the team to plan the implementation of the features. For example, if there are 10 feature proposals currently in the queue, it could be decided that only 5 of them will make it into YS3.
• It makes implementing features easier, because when there's the initial proposal, and then many-many-many pages of discussion afterwards, it may be hard to figure out what the ultimate conclusion was, and what actually needs to be implemented.
• It gives heads up to the maintainers of non-official YS libraries about what features will be added in the future, so that they can start planning on how to support them.

Also, this extra step isn't much of a burden -- since the documentation for the new feature needs to be written anyway.

This being said, this PR isn't necessarily the best solution. It's merely a solution. Some projects use a different organizational structure: each proposal becomes a separate markdown document (for example: https://github.com/dart-lang/language/tree/master/accepted).

what harm is there in just making changes directly to the spec document instead?

The changes to a spec document should be done after the feature is implemented; whereas the proposal document should be written before the feature is implemented. This proposal document can be used as:

• reference for what exactly needs to be implemented;
• source for the "here's what's new in YS3" document;