kixelated · Nov 13, 2026 · Nov 13, 2026 · Nov 13, 2026 · Nov 13, 2026 · coderabbitai
diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
@@ -66,7 +66,8 @@ jobs:
         run: nix build --out-link "$RUNNER_TEMP/quest-lifecycle-install" .#quest
       - name: Verify the installed CLI lifecycle
         shell: bash
-        run: nix develop --command bash scripts/lifecycle-check.sh "$RUNNER_TEMP/quest-lifecycle-install/bin/quest"
+        # A flake build reports its commit, as Nix abbreviates it.
+        run: nix develop --command bash scripts/lifecycle-check.sh "$RUNNER_TEMP/quest-lifecycle-install/bin/quest" "${GITHUB_SHA::7}"
       # Work outside the job holds a fresh macOS runner's load above its CPUs.
       - name: Check that the gate admits and owns its command's descendants
         shell: bash

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -1,33 +1,86 @@
 name: Release
 
-# A pushed version tag compiles, publishes, and then install-checks the release.
-# Pull requests that could change the compiled binaries, and manual runs (even
-# from a tag), only build and check them. Check runs the installer's own tests.
+# Every run on `main` (each push, a daily schedule, or a manual run) compares
+# `main` with the latest published release, and cuts the next one when that
+# range changes what ships. It builds and checks every binary first, then
+# uploads them to a draft release and publishes it, which creates the tag, so
+# no tag exists without its complete release. A failed or cancelled run needs
+# no recovery: the next run sees the same unreleased range and replaces any
+# draft it left. Pull requests that change what ships, and manual runs on other
+# branches, only build and check. scripts/release-plan.sh holds both decisions.
 on:
   push:
-    tags: ["v[0-9]+.[0-9]+.[0-9]+*"]
+    branches: [main]
   pull_request:
-    paths:
-      - .github/workflows/release.yml
-      - package.json
-      - bun.lock
-      - bunfig.toml
-      - src/**
-      - scripts/**
-      - flake.lock
+  schedule:
+    - cron: "17 6 * * *"
   workflow_dispatch:
 
 permissions:
   contents: read
 
+# Runs on `main` queue rather than cancel each other; a pending run that a newer
+# one replaces loses nothing, since the newer one sees its range too.
 concurrency:
   group: release-${{ github.ref }}
-  cancel-in-progress: ${{ github.ref_type != 'tag' }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
+  plan:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      build: ${{ steps.plan.outputs.build }}
+      release: ${{ steps.plan.outputs.release }}
+      released: ${{ steps.plan.outputs.released }}
+      version: ${{ steps.plan.outputs.version }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Plan the release
+        id: plan
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          EVENT: ${{ github.event_name }}
+          BASE: ${{ github.event.pull_request.base.sha }}
+          HEAD: ${{ github.event.pull_request.head.sha }}
+        run: |
+          # The latest published release; drafts and prereleases don't count.
+          if ! released=$(gh api "repos/$GH_REPO/releases/latest" --jq .tag_name 2>"$RUNNER_TEMP/latest"); then
+            grep -q 'HTTP 404' "$RUNNER_TEMP/latest" || { cat "$RUNNER_TEMP/latest" >&2; exit 1; }
+            released=
+          fi
+          plan=$(bash scripts/release-plan.sh next "$released" "$GITHUB_SHA")
+          echo "$plan"
+          version=$(sed -n 's/^version=//p' <<<"$plan")
+          ships=$(sed -n 's/^release=//p' <<<"$plan")
+          release=false
+          if [[ $EVENT == pull_request ]]; then
+            build=false
+            if git diff --name-only --no-renames "$BASE...$HEAD" | bash scripts/release-plan.sh ships; then build=true; fi
+          elif [[ $GITHUB_REF == refs/heads/main ]]; then
+            release=$ships
+            build=$ships
+            if [[ $EVENT == workflow_dispatch ]]; then build=true; fi
+          else
+            build=true
+          fi
+          {
+            echo "build=$build"
+            echo "release=$release"
+            echo "released=$released"
+            echo "version=$version"
+          } >>"$GITHUB_OUTPUT"
+          echo "build=$build release=$release version=$version released=${released:-none}"
+
   # Bun cross-compiles every target from one Linux runner, since the pinned
   # nixpkgs no longer evaluates on Intel macOS.
   build:
+    needs: plan
+    if: needs.plan.outputs.build == 'true'
     runs-on: ubuntu-latest
     timeout-minutes: 20
     steps:
@@ -44,7 +97,10 @@ jobs:
       - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
         with:
           bun-version-file: package.json
+      # Each binary embeds the version it releases as, which `quest --version` prints.
       - name: Compile
+        env:
+          VERSION: ${{ needs.plan.outputs.version }}
         run: |
           declare -A bun_targets=(
             [aarch64-apple-darwin]=bun-darwin-arm64
@@ -54,12 +110,12 @@ jobs:
           )
           mkdir release
           for target in "${!bun_targets[@]}"; do
-            bun run compile --target="${bun_targets[$target]}"
+            bun run compile --target="${bun_targets[$target]}" --define "QUEST_VERSION=\"$VERSION\""
             tar -czf "release/quest-$target.tar.gz" -C dist quest
           done
           for pair in x86_64-pc-windows-msvc:bun-windows-x64 aarch64-pc-windows-msvc:bun-windows-arm64; do
             target=${pair%%:*}
-            bun run compile --target="${pair#*:}"
+            bun run compile --target="${pair#*:}" --define "QUEST_VERSION=\"$VERSION\""
             zip -j "release/quest-$target.zip" dist/quest.exe
           done
           cd release
@@ -72,7 +128,7 @@ jobs:
 
   check:
     name: check (${{ matrix.target }})
-    needs: build
+    needs: [plan, build]
     strategy:
       fail-fast: false
       matrix:
@@ -104,25 +160,11 @@ jobs:
         env:
           TARGET: ${{ matrix.target }}
         run: bash scripts/arch-check.sh "$RUNNER_TEMP/quest" "$TARGET"
-      - name: Check the version
+      - name: Check the binary's version and lifecycle
         shell: bash
         env:
-          REF_TYPE: ${{ github.ref_type }}
-          TAG: ${{ github.ref_name }}
-        run: |
-          actual=$("$RUNNER_TEMP/quest" --version)
-          expected="quest $(jq -r .version package.json)"
-          if [[ $actual != "$expected" ]]; then
-            echo "::error::the binary reports $actual, not $expected"
-            exit 1
-          fi
-          if [[ $REF_TYPE == tag && $actual != "quest ${TAG#v}" ]]; then
-            echo "::error::$TAG builds $actual; bump package.json first"
-            exit 1
-          fi
-      - name: Check the binary's lifecycle
-        shell: bash
-        run: bash scripts/lifecycle-check.sh "$RUNNER_TEMP/quest"
+          VERSION: ${{ needs.plan.outputs.version }}
+        run: bash scripts/lifecycle-check.sh "$RUNNER_TEMP/quest" "$VERSION"
       # The binary gates real commands. Work outside the job holds a fresh macOS
       # runner's load above its CPUs, which must not keep a lone command waiting.
       # Ubuntu 22.04's systemd 249 is too old for Quest's scopes, so it checks the
@@ -132,12 +174,12 @@ jobs:
         run: bash scripts/gate-check.sh "$RUNNER_TEMP/quest"
 
   # Hosted macOS runners can queue past the timeout, which then reports a job
-  # that never ran as failed. Pull requests skip these; tags, which publish the
-  # artifacts, and manual runs still check them. Check covers macOS on main.
+  # that never ran as failed. Pull requests skip these; releases, which publish
+  # the artifacts, and manual runs still check them. Check covers macOS on main.
   macos:
     name: check (${{ matrix.target }})
     if: github.event_name != 'pull_request'
-    needs: build
+    needs: [plan, build]
     strategy:
       fail-fast: false
       matrix:
@@ -151,14 +193,15 @@ jobs:
     steps: *check-steps
 
   # Check's suite runs on Linux and Windows only, so the gate's macOS owner is
-  # tested natively before a tag publishes.
+  # tested natively before a release publishes.
   gate-macos:
-    if: github.event_name != 'pull_request'
+    needs: plan
+    if: github.event_name != 'pull_request' && needs.plan.outputs.build == 'true'
     uses: ./.github/workflows/gate-macos.yml
 
   windows:
     name: check (${{ matrix.target }})
-    needs: build
+    needs: [plan, build]
     strategy:
       fail-fast: false
       matrix:
@@ -185,15 +228,12 @@ jobs:
         shell: pwsh
         env:
           TARGET: ${{ matrix.target }}
-          REF_TYPE: ${{ github.ref_type }}
-          TAG: ${{ github.ref_name }}
-        run: |
-          $tag = if ($env:REF_TYPE -eq 'tag') { $env:TAG } else { 'v' + (Get-Content package.json | ConvertFrom-Json).version }
-          ./scripts/install-check.ps1 -Method archive -Target $env:TARGET -Tag $tag -ReleaseDirectory (Resolve-Path release).Path
+          TAG: v${{ needs.plan.outputs.version }}
+        run: ./scripts/install-check.ps1 -Method archive -Target $env:TARGET -Tag $env:TAG -ReleaseDirectory (Resolve-Path release).Path
 
   publish:
-    needs: [check, macos, gate-macos, windows]
-    if: github.event_name == 'push' && github.ref_type == 'tag'
+    needs: [plan, check, macos, gate-macos, windows]
+    if: needs.plan.outputs.release == 'true'
     runs-on: ubuntu-latest
     timeout-minutes: 10
     permissions:
@@ -210,18 +250,29 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
           GH_REPO: ${{ github.repository }}
-          TAG: ${{ github.ref_name }}
+          TAG: v${{ needs.plan.outputs.version }}
+          RELEASED: ${{ needs.plan.outputs.released }}
         run: |
+          # A run that failed after uploading leaves a draft, which this replaces.
+          gh api --paginate "repos/$GH_REPO/releases" --jq '.[] | select(.draft) | "\(.id) \(.tag_name)"' |
+            while read -r id tag; do
+              if [[ $tag == v[0-9]* ]]; then gh api -X DELETE "repos/$GH_REPO/releases/$id"; fi
+            done
           sed "s/@TAG@/$TAG/" scripts/installer.sh > release/quest-installer.sh
           cd release
           sha256sum quest-*.tar.gz quest-*.zip quest-installer.sh > SHA256SUMS
-          prerelease=()
-          if [[ $TAG == *-* ]]; then prerelease=(--prerelease); fi
-          gh release create "$TAG" --verify-tag --title "$TAG" --generate-notes "${prerelease[@]}" \
+          notes=(--generate-notes)
+          if [[ -n $RELEASED ]]; then notes+=(--notes-start-tag "$RELEASED"); fi
+          gh release create "$TAG" --draft --target "$GITHUB_SHA" --title "$TAG" "${notes[@]}" \
             quest-*.tar.gz quest-*.zip quest-installer.sh SHA256SUMS
+          # Publishing the draft creates its tag at this run's commit, with every asset already attached.
+          id=$(gh api --paginate "repos/$GH_REPO/releases" --jq ".[] | select(.draft and .tag_name == \"$TAG\") | .id")
+          gh api -X PATCH "repos/$GH_REPO/releases/$id" -F draft=false -f make_latest=true --jq .html_url
 
+  # Mise and the installer need the published release, so they check it last and
+  # fail loudly; their fix ships as the next release.
   install-check:
-    needs: publish
+    needs: [plan, publish]
     uses: ./.github/workflows/install-check.yml
     with:
-      tag: ${{ github.ref_name }}
+      tag: v${{ needs.plan.outputs.version }}
diff --git a/.github/workflows/windows.yml b/.github/workflows/windows.yml
@@ -41,4 +41,4 @@ jobs:
         run: bun run test
       - run: bun run build
       - name: Verify native setup and removal without symlinks
-        run: bun scripts/lifecycle-check.mjs dist/quest.js
+        run: bun scripts/lifecycle-check.mjs dist/quest.js dev
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -51,14 +51,29 @@ The package stays `private`; GitHub releases will ship the `quest` binary.
 
 ## Releases
 
-Pushing a `vX.Y.Z` tag that matches `package.json`'s version runs the Release
-workflow. It compiles `quest` with Bun for macOS, Linux, and Windows (arm64 and
-x64), runs the lifecycle check on each binary's native runner, and publishes the
-macOS/Linux tarballs, Windows ZIPs, `SHA256SUMS`, and `quest-installer.sh` to a
-GitHub release. It then checks that mise and the installer (or, on Windows, the
-ZIP archive) install the tag on every platform. A tag with a
-prerelease suffix publishes a prerelease. `just compile` builds a binary for
-this machine; the Bun in the Nix shell is the version releases use.
+The Release workflow cuts every release; no person or agent tags one. Each
+push to `main`, a daily schedule, and a manual run on `main` compare `main`
+with the latest published release, and cut the next one when that range
+changes what ships, as `scripts/release-plan.sh` decides: everything the
+binaries and the flake package build from, every file Release publishes, and
+the workflows that build and check them. Its pull request runs use the same
+predicate to decide whether to build. The next version is greater than every
+`vX.Y.Z` tag: a minor bump (a major one from 1.0) when a commit subject in the
+range has `!` before its colon, a patch bump otherwise.
 
-Do not push release tags or publish GitHub releases from ordinary development
-work; that is a maintainer action after review.
+A run compiles `quest` with Bun for macOS, Linux, and Windows (arm64 and x64),
+each binary embedding its version, and runs the lifecycle and archive install
+checks on each binary's native runner. Only then does it upload the
+macOS/Linux tarballs, Windows ZIPs, `SHA256SUMS`, and `quest-installer.sh` to
+a draft release and publish it, which creates the tag. A run that fails or is
+cancelled needs no recovery: the next one sees the same unreleased range and
+replaces the draft. After publishing, it checks that mise and the installer
+install the release on every platform; a failure there ships its fix as the
+next release.
+
+`package.json` carries no version. A release binary reports its tag in
+`quest --version`, a flake build its commit, and a checkout run from source
+`dev`. `just compile` builds a binary for this machine; the Bun in the Nix
+shell is the version releases use.
+
+Do not push release tags or publish GitHub releases by hand.
diff --git a/SETUP.md b/SETUP.md
@@ -12,6 +12,8 @@ line in its root instructions.
 ## Install and pin
 
 Pin the latest [release](https://github.com/moq-dev/quest/releases) tag.
+Every merge that changes what Quest ships becomes a release, so a release tag
+is never far behind `main`; prefer it to pinning a commit.
 Releases ship binaries for macOS, Linux, and native Windows on arm64 and x64.
 Check that the chosen release includes the Windows archives and the
 `quest worktree hook` command that `quest init`'s Claude Code hooks call;

diff --git a/docs/windows.md b/docs/windows.md
@@ -113,7 +113,7 @@ explicitly choose to discard it.
 
 [Bun](https://bun.sh) is required for a source build. From the checkout, run
 `bun install --frozen-lockfile`, `bun run check`, `bun run test`, and
-`bun run build`. Then run `bun scripts/lifecycle-check.mjs dist/quest.js`. The shared lifecycle checks
+`bun run build`. Then run `bun scripts/lifecycle-check.mjs dist/quest.js dev`. The shared lifecycle checks
 paths containing spaces, actual Git worktrees, CRLF plans/instructions, existing
 custom skills, conflicts, and repeated setup/removal without remote writes.
 Windows tests do not require symlink privileges; symlink-specific legacy cases

diff --git a/flake.nix b/flake.nix
@@ -42,8 +42,15 @@
             inherit system;
             overlays = [ (_: _: { inherit (nixpkgs-bun.legacyPackages.${system}) bun; }) ];
           };
-          quest = pkgs.callPackage ./nix/package.nix { };
-          questPinned = pkgs.callPackage "${quest-pinned}/nix/package.nix" { };
+          # A flake build cannot see tags, so it reports its commit.
+          quest = pkgs.callPackage ./nix/package.nix { rev = self.shortRev or self.dirtyShortRev or null; };
+          # A pin from before builds took `rev` reads its version from package.json instead.
+          pinnedPackage = "${quest-pinned}/nix/package.nix";
+          questPinned = pkgs.callPackage pinnedPackage (
+            pkgs.lib.optionalAttrs (pkgs.lib.functionArgs (import pinnedPackage) ? rev) {
+              rev = quest-pinned.shortRev;
+            }
+          );
           manifest = pkgs.lib.importJSON ./package.json;
           # package.json's packageManager pins Bun for CI runners without Nix.
           bunVersion = pkgs.lib.removePrefix "bun@" manifest.packageManager;

diff --git a/justfile b/justfile
@@ -32,10 +32,11 @@ _test:
     bun run test
     bash scripts/install-check.test.sh
     bash scripts/installer.test.sh
+    bash scripts/release-plan.test.sh
     bun run build
-    bash scripts/lifecycle-check.sh "$PWD/dist/quest.js"
+    bash scripts/lifecycle-check.sh "$PWD/dist/quest.js" dev
     bun run compile
-    bash scripts/lifecycle-check.sh "$PWD/dist/quest"
+    bash scripts/lifecycle-check.sh "$PWD/dist/quest" dev
 
 # Check that `quest review` runs nothing a reviewed head plants, with the real
 # Codex and Claude Code CLIs. Uses each CLI's login and spends its usage; run it