/bump-surfaces-version

name: bump-surfaces-version
description: 'Ship a change to a file setup-project copies or emits into projects (ADR_FORMAT.md, NORTH_STAR_FORMAT.md, the verification harness and this repo''s scripts/verify copies) with its new surfaces version, changes entry, eval-case moves and upgrade guide. Use when editing one of those files.'
user-invocable: true
metadata:
  internal: true

Setup-project surfaces version

Every file setup-project copies or emits into projects — `figure-out/references/ADR_FORMAT.md`, `setup-project/references/NORTH_STAR_FORMAT.md`, and the verification harness under `setup-project/references/harness/` (the tool and its example settings and recipes) — is pinned to the latest surfaces version. `setup-project/references/CHANGES.md` lists one line per version and `setup-project/references/changes/vN.md` holds each version's items, so an update reads only the versions it offers and the always-read list grows by a line, not by every version's items. A change to any emitted file needs a new `changes/vN.md` and its line in `CHANGES.md` in the same change. The file lists what an installed project gains and carries the digest the version test prints on failure, and the version comment in the surfaces template of `NORTH_STAR_FORMAT.md` moves to `vN`. Installed projects record the version they carry, and an update offers only the entries after it, so a change shipped without a version never reaches them. HTML comments are outside the digest, so maintainer notes need no version. Each change that adds a version moves the one-behind eval case to the version before it — replacing that case, never adding one beside it, since every such case tests the same offer and each run is paid — graded on offering only the entries after that version, and moves `45-current-setup-offers-nothing` to the newest. `tests/test_setup_project_versions.py` fails when `45` does not record the newest version, when no case records the version before it, and when a case records an older version or two cases record that one. The upgrade guides in `setup-project/references/upgrades/` hold one `vN-to-current.md` per older version, each saying only what the next version gives a project at vN; setup-project follows a project's own guide and every later one, and adds them up so the project goes straight to the newest shape (`setup-project/SKILL.md` → *The update pass*). A new version therefore adds the guide for the version it supersedes and edits no other version guide; `MOVE_TO_HARNESS.md`, the move of a pre-v4 surface into the harness, changes only when the new version changes that move. The same test fails when a guide is missing, exists for the newest version, names a version after the one it gives, or records a version. This repository's `scripts/verify` and `scripts/verify.mts` are copies of the shipped tool, and the eval scaffolds that seed a harness embed it, so edit the shipped copy and run `python3 scripts/sync_dist.py`, which copies it to the others; `tests/test_verify.py` and `sync_dist.py --check` fail when any differs. `scripts/tsconfig.json` type-checks both `verify.mts` copies in strict mode (`npm --prefix scripts run typecheck`), with its dev dependencies in `scripts/package.json`, never in the root `package.json`, which Pi installs from.