RFC: Versioned releases with changesets, and automatic changesets in the loop

[SamuelDenani]

Summary

Two connected changes:

1. Loopwright versions itself with changesets. Releases get tags and changelogs, and the installer installs a pinned version instead of whatever is on main.
2. Automatic changesets in the loop. When changesets.auto is on in the config, every task PR the loop opens carries a changeset, so hosts that version their code get release notes as a by-product of the RFC flow.

Motivation

• Loopwright has no releases. install.sh downloads refs/heads/main on every install and update, the repo has no tags and no releases, and package.json says 0.2.0 without anything behind it. A host cannot pin a version, cannot read what changed between updates, and an update can pull in a half-finished change. Decisions like bumping the bundled mise version (connectors RFC) are supposed to be release decisions, which requires releases to exist.
• Version notes are work agents can do. The loop already knows, per task, what changed and why (the issue, the spec, the diff). Writing the changeset is a natural last step of a task, not a separate chore.

Goals / Non-goals

Goals:

• Changesets adopted in this repo, with a release workflow that tags versions and writes CHANGELOG.md.
• install.sh installs a tagged release by default (latest, or a pinned version), with main only as an explicit opt-in.
• A changesets section in the config. When auto is on, /execute-issue writes a changeset in each task PR.

Non-goals:

• Publishing loopwright to npm (it is vendored, not installed as a package).
• Supporting every release tool hosts might use. Changesets first; others behind the same section later.

Proposed approach

Releases for loopwright itself. Add @changesets/cli to this repo. The release workflow versions, writes CHANGELOG.md and creates a git tag and GitHub release. install.sh resolves latest from the releases API (or a version passed as LOOPWRIGHT_VERSION) and downloads that tag. LOOPWRIGHT_SOURCE stays as the local override for development.

Automatic changesets in the loop.

changesets:
  auto: true

• The bump type (patch/minor/major) is a human decision made during /grill-rfc and recorded on each task sub-issue. Agents never choose it.
• The summary is written by the orchestrator at the end of /execute-issue, from the task issue and the final diff, as .changeset/<slug>.md in the task PR.
• The reviewer agent checks the changeset matches the diff.
• With auto off, nothing changes in the loop.

Alternatives considered

• release-please (conventional commits) instead of changesets. Derives versions from commit messages. Weaker fit: the loop writes one commit per plan step, so commit messages describe steps, not user-facing changes.
• knope as the release tool for non-JS hosts. A single binary that reads changeset files and does not need Node. Worth evaluating once connectors land (see risks).

Risks

• Changesets is a JS tool. @changesets/cli assumes a package.json. Fine for this repo and for JS hosts, but conflicts with the connectors RFC for non-JS hosts. The changeset file format is simple and tool-independent; the release tool that consumes it should be pluggable (changesets on JS, a single-binary tool such as knope elsewhere, installed through the toolchain provider).
• Changeset noise. A changeset per task PR inside a multi-task RFC may produce a fragmented changelog (open question 2).
• Agent-written summaries can be vague or wrong. The reviewer check mitigates, but the human still reads it at merge.

Task breakdown (link sub-issues)

To be produced by /grill-rfc.

Open questions

1. Should the gate treat a missing changeset as a warning when changesets.auto is on?
2. One changeset per task PR, or one per RFC written on the feature branch?
3. Does install.sh default to latest or require an explicit version?

---

Generated by Claude Code

---

Boundary document

The core/detail boundary this RFC is argued against is #5, refined into
docs/loopwright/principles.md (task #11). Core opinions are cited as P<n>,
detail territory as T<n>.

One claim in this RFC is superseded. It states that the bump type is a human
decision and that "Agents never choose it". P8 makes the human mandatory for
irreversible actions, and a version bump is reversible inside the PR — the
human still sees it in the same act as the merge — so the mediator may decide it.
Reconcile when this RFC is grilled.