Adopters should track a moving major tag, not an exact version

[charlesgreen]

The ask

An adopter's caller workflow should not have to name an exact patch version. Today init --workflow writes:

uses: simplycubed/code/.github/workflows/simplycubed.yml@v0.2.0

so every adopter is frozen on the release they installed under until someone edits their workflow. Worse, that file lives in .github/workflows/, which the App cannot push, so the agent can never upgrade its own caller. Every upgrade is manual, forever.

What is not possible

There is no latest for uses:. GitHub Actions resolves a tag, a branch, or a SHA and nothing else.

@main would float, which is not the same thing as latest-release: adopters would silently receive unreleased and breaking changes. v0.2.0 renamed two configuration values; on @main that would have broken every install with no warning and no version to point at.

What is possible

A moving major tag, republished on each release. actions/checkout@v4 works exactly this way, and it is what most adopters already expect from an Action.

uses: simplycubed/code/.github/workflows/simplycubed.yml@v0

Fixes reach adopters without them touching their workflow. A breaking change becomes a deliberate move to @v1, which is a decision they make rather than one that happens to them.

The cost is a release step: after tagging vX.Y.Z, force-update v0 to the same commit. Worth automating in tag-release.yml rather than remembering.

Not the same as the Go install pin

go install ...@v0 is not valid. Go modules need a real version, and proxy.golang.org records them immutably, which is the whole reason the release process refuses to retag. The CLI install command stays @<release-tag> with a link to Releases.

So the two pins deliberately diverge: the CLI is pinned exactly, the reusable workflow tracks a major. That is worth stating in docs/release.md, because it looks like an inconsistency until you know why.

Decide first

• Is @v0 the right level, given pre-1.0 minors may still break? v0.2 moving within the minor is stricter and more honest about that.
• Should init --workflow write the moving tag, the exact tag, or offer both?

Work

1. Publish and maintain the moving tag from tag-release.yml.
2. Point latestKnownWorkflowTag and docs/templates/simplycubed-caller.yml at it.
3. Teach scripts/verify-release.sh what to enforce once the pins no longer all name the same string.
4. Say in docs/release.md why the CLI pin and the workflow pin differ.

Acceptance

• A caller generated by init --workflow keeps working across a patch release with no edit
• A breaking release does not reach an adopter who has not moved major
• verify-release.sh still refuses a release whose pins disagree