chore: adopt changesets for release management

.changeset/README.md

@@ -0,0 +1,15 @@
+# Changesets
+
+This folder is managed by [@changesets/cli](https://github.com/changesets/changesets).
+
+Each PR that changes user-facing behavior should include a changeset file. Create one by adding a markdown file here with the following format:
+
+```md
+---
+"jumbo-cli": patch
+---
+
+Description of the change.
+```
+
+Use `patch` for fixes, `minor` for new features, `major` for breaking changes.

.changeset/adopt-changesets.md

@@ -0,0 +1,2 @@
+---
+---

.changeset/config.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": [
+    "@changesets/changelog-github",
+    { "repo": "jumbocontext/jumbo.cli" }
+  ],
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.github/workflows/pr-gate.yml

@@ -10,11 +10,11 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # intended version: actions/checkout v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # intended version: actions/setup-node v4
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'npm'
 
       - run: npm ci
@@ -26,11 +26,11 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # intended version: actions/checkout v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # intended version: actions/setup-node v4
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'npm'
 
       - run: npm ci
@@ -44,17 +44,35 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # intended version: actions/checkout v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # intended version: actions/setup-node v4
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'npm'
 
       - run: npm ci
 
       - run: npm run build
 
+  changeset:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - run: npm ci
+
+      - run: npx changeset status --since=origin/main
+
   # Guards the evals/jumbo CLI contract: builds jumbo from THIS commit's source
   # and runs the evals against it (not a published binary), so a primitive
   # refactor that breaks the CLI surface the evals depend on fails the PR here.
@@ -63,11 +81,11 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # intended version: actions/checkout v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # intended version: actions/setup-node v4
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'npm'
 
       # Build jumbo from source → dist/cli.js (the binary the evals will exercise).

.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+
+      - run: npm ci
+
+      - name: Create release PR or publish
+        id: changesets
+        uses: changesets/action@a45c4d594aa4e2c509dc14a9f2b3b67ba3780d0d # v1.9.0
+        with:
+          title: "ci: Version Packages & Release"
+          publish: npm run release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          POSTHOG_API_KEY: ${{ vars.POSTHOG_API_KEY }}
+          POSTHOG_HOST: ${{ vars.POSTHOG_HOST }}

AGENTS.md

@@ -3,3 +3,26 @@
 ## Instructions for Agents on how to collaborate with Jumbo
 
 See JUMBO.md and follow all instructions. If the file does not exist, then ignore this instruction.
+
+## Changesets
+
+When a PR changes user-facing behavior, add a changeset file in `.changeset/` with a short kebab-case name (e.g. `.changeset/fix-goal-output.md`):
+
+```md
+---
+"jumbo-cli": patch
+---
+
+Description of the change.
+```
+
+Use `patch` for fixes, `minor` for new features, `major` for breaking changes.
+
+For PRs that don't need a release note (docs, CI), add an empty changeset instead:
+
+```md
+---
+---
+```
+
+Every PR needs a changeset file; the CI gate enforces this.

CONTRIBUTING.md

@@ -21,6 +21,30 @@ Pull requests are welcome. Before submitting:
 2. Keep PRs focused - one feature or fix per PR
 3. Follow existing code style and patterns
 4. Include tests for new functionality
+5. Add a changeset if your change affects users (see below)
+
+### Changesets
+
+We use [changesets](https://github.com/changesets/changesets) to track what changed and generate release notes. If your PR changes user-facing behavior, add a changeset file in `.changeset/`:
+
+```md
+---
+"jumbo-cli": patch
+---
+
+Short description of the change.
+```
+
+Use `patch` for fixes, `minor` for new features, `major` for breaking changes.
+
+For PRs that don't need a release note (docs, CI), add an empty changeset instead:
+
+```md
+---
+---
+```
+
+Every PR needs a changeset file; the CI gate enforces this.
 
 ### Contributor License Agreement