feat: implement prerelease channels

Branch-based prerelease lines where prerelease versions are never
committed to git — derived at publish time from bump files (targets),
the registry (counters), and git tags/gitHead (idempotency).

Core:
- channels config block (+ JSON schema): branch, preid, tag, versionPr
  with automerge; names validated as .bumpy/ subdirectory-safe
- bump file location is the only channel state: pending at .bumpy/ root
  (or other channels' dirs), shipped in .bumpy/<channel>/; the general
  pending rule gives alpha -> beta graduation for free
- release plan gains a prerelease mode: range satisfaction is checked
  against <target>-<preid>.0, so every dependent joins the cycle at
  proportional bump levels (prereleases never satisfy stable ranges)
- prerelease versions: registry-floor counters (max published + 1),
  per-package gitHead skip for re-runs/resume, exact-pinned in-cycle
  deps written transiently into the working tree and restored after

Commands:
- version: on a channel, only moves pending files into .bumpy/<channel>/
- publish: channel flow computes + rewrites + publishes to the channel
  dist-tag; stable flow refuses suffixed versions when channels exist
- ci release: channel branches get publish-on-move-detection (push
  range diff) + file-move release PRs with computed versions in the
  title/commit message; unknown branches are refused
- ci plan/check, status, check: channel-aware (status shows the cycle;
  check skips channel branches and gains --base)
- promotion needs no special mode: main consumes channel dirs as
  pending, bumps stable-to-stable, writes the consolidated changelog
- GitHub releases for prerelease versions are marked --prerelease

Docs updated to match (banner removed, trigger/notes/check rows
aligned); changesets comparison moved to Implemented.

Author: theoephraim

.bumpy/prerelease-channels.md

@@ -0,0 +1,5 @@
+---
+'@varlock/bumpy': minor
+---
+
+Add prerelease channels — branch-based prerelease lines (e.g. `next` → `@next` dist-tag) where prerelease versions are never committed to git. Targets derive from bump files, counters from the registry; shipped bump files are tracked by moving them into `.bumpy/<channel>/`. Includes channel-aware `version` / `publish` / `status` / `ci release` flows, exact-pinned lockstep cycle publishes, and promotion-by-merge to stable.

docs/cli.md

@@ -53,9 +53,12 @@ bumpy status --verbose
 | `--bump <types>`   | Filter by bump type, e.g. `"major"` or `"minor,patch"`         |
 | `--filter <names>` | Filter by package name or glob                                 |
 | `--verbose`        | Show bump file details and summaries                           |
+| `--channel <name>` | Channel override (default: inferred from the current branch)   |
 
 Exits with code `0` if releases are pending, `1` if none.
 
+On a [prerelease channel](prereleases.md) branch, status shows the cycle instead: shipped vs pending bump files and the derived `-<preid>.N` versions (counters come from the registry; offline they render as `.?`).
+
 ## `bumpy version`
 
 Consume all pending bump files and apply the release plan:
@@ -72,9 +75,12 @@ bumpy version
 bumpy version --commit
 ```
 
-| Flag       | Description                       |
-| ---------- | --------------------------------- |
-| `--commit` | Commit the version changes to git |
+| Flag               | Description                                                  |
+| ------------------ | ------------------------------------------------------------ |
+| `--commit`         | Commit the version changes to git                            |
+| `--channel <name>` | Channel override (default: inferred from the current branch) |
+
+On a [prerelease channel](prereleases.md) branch, `bumpy version` does something much smaller: it **moves pending bump files into `.bumpy/<channel>/`** and writes no versions and no changelogs — prerelease versions are derived at publish time and never committed.
 
 ## `bumpy publish`
 
@@ -87,12 +93,15 @@ bumpy publish --tag beta
 bumpy publish --filter "@myorg/*"
 ```
 
-| Flag               | Description                                               |
-| ------------------ | --------------------------------------------------------- |
-| `--dry-run`        | Preview what would be published without actually doing it |
-| `--tag <tag>`      | npm dist-tag (e.g., `next`, `beta`)                       |
-| `--no-push`        | Skip pushing git tags to the remote                       |
-| `--filter <names>` | Only publish matching packages (supports globs)           |
+| Flag               | Description                                                  |
+| ------------------ | ------------------------------------------------------------ |
+| `--dry-run`        | Preview what would be published without actually doing it    |
+| `--tag <tag>`      | npm dist-tag (e.g., `next`, `beta`)                          |
+| `--no-push`        | Skip pushing git tags to the remote                          |
+| `--filter <names>` | Only publish matching packages (supports globs)              |
+| `--channel <name>` | Channel override (default: inferred from the current branch) |
+
+On a [prerelease channel](prereleases.md) branch, publish derives prerelease versions (targets from the cycle's bump files, counters from the registry), transiently writes them into the working tree so pack/build see them, publishes the whole cycle to the channel's dist-tag with exact-pinned inter-cycle deps, then restores the files. Nothing version-shaped is ever committed.
 
 **How bumpy detects unpublished packages:**
 
@@ -114,12 +123,15 @@ bumpy check --hook pre-commit
 bumpy check --hook pre-push
 ```
 
-| Flag                | Description                                                |
-| ------------------- | ---------------------------------------------------------- |
-| `--strict`          | Fail if any changed package is not covered by a bump file  |
-| `--no-fail`         | Warn only, never exit non-zero (useful for advisory hooks) |
-| `--hook pre-commit` | Only count staged + committed bump files                   |
-| `--hook pre-push`   | Only count committed bump files                            |
+| Flag                | Description                                                                                                                           |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `--strict`          | Fail if any changed package is not covered by a bump file                                                                             |
+| `--no-fail`         | Warn only, never exit non-zero (useful for advisory hooks)                                                                            |
+| `--hook pre-commit` | Only count staged + committed bump files                                                                                              |
+| `--hook pre-push`   | Only count committed bump files                                                                                                       |
+| `--base <branch>`   | Branch to compare against (default: `baseBranch`) — use the channel branch for feature branches targeting a [channel](prereleases.md) |
+
+The check is skipped automatically on channel branches and release PR branches (they move/consume bump files by design).
 
 ### Hook context
 
@@ -240,6 +252,8 @@ bumpy ci release --auto-publish --tag beta
 
 Requires `GH_TOKEN`. When `BUMPY_GH_TOKEN` is set, it is automatically used to push the version branch and create/edit the PR so that PR workflows trigger (see [GitHub Actions setup](github-actions.md#token-setup)).
 
+**Channel branches:** when run on a branch configured as a [prerelease channel](prereleases.md), `ci release` switches to the channel flow — it publishes the cycle when the triggering push moved bump files into `.bumpy/<channel>/` (a release PR merge), and creates/updates the file-move release PR when pending bump files exist. When channels are configured and the branch is neither `baseBranch` nor a channel branch, the command exits with an error instead of guessing.
+
 ## `bumpy ci setup`
 
 Interactive guide to set up `BUMPY_GH_TOKEN` for CI. Walks through creating a fine-grained PAT or GitHub App token and storing it as a repository secret.

docs/configuration.md

@@ -25,6 +25,7 @@ Bumpy is configured via `.bumpy/_config.json`, created by `bumpy init`. Per-pack
 | `versionPr`                  | `{ title, branch, preamble }`          | see below                        | Customize the version PR                                                                         |
 | `allowCustomCommands`        | `boolean \| string[]`                  | `false`                          | Allow per-package custom commands from `package.json` (see below)                                |
 | `packages`                   | `object`                               | `{}`                             | Per-package config overrides (keyed by package name)                                             |
+| `channels`                   | `object`                               | `{}`                             | Prerelease channels, keyed by channel name (see below)                                           |
 
 ### Dependency bump rules
 
@@ -99,6 +100,29 @@ The `versionPr` object customizes the PR that `bumpy ci release` creates:
 | `branch`   | `string` | `"bumpy/version-packages"` | Branch name for the version PR        |
 | `preamble` | `string` | —                          | HTML content prepended to the PR body |
 
+### Prerelease channels
+
+The `channels` object maps long-lived branches to prerelease lines. See [prereleases.md](prereleases.md) for the full workflow.
+
+```jsonc
+{
+  "channels": {
+    "next": {
+      "branch": "next", // required — branch that triggers this channel
+      "preid": "rc", // version suffix (default: channel name)
+      "tag": "next", // npm dist-tag (default: channel name)
+      "versionPr": {
+        "title": "🐸 Versioned release (next)", // default: "<base title> (<name>)"
+        "branch": "bumpy/version-packages-next", // default: "<base branch>-<name>"
+        "automerge": false, // enable auto-merge on the release PR
+      },
+    },
+  },
+}
+```
+
+Channel names become `.bumpy/<name>/` subdirectories (holding bump files that shipped on the channel), so they must be filesystem-safe and can't start with `_` or collide with reserved entries.
+
 ## Per-package config
 
 Per-package settings can be defined in two places:

docs/differences-from-changesets.md

@@ -147,6 +147,18 @@ Bumpy replaces all of this with two CLI commands you run directly in standard wo
 - [changesets#1242](https://github.com/changesets/changesets/issues/1242) — bot/action version upgrade issues
 - [changesets#43](https://github.com/changesets/changesets/issues/43) — can't customize bot messages
 
+### Prerelease channels that actually work
+
+Changesets' prerelease mode is described in their own docs as "very complicated" with "mistakes that can lead to repository and publish states that are very hard to fix." Key problems: global mode state poisons unrelated merges, exiting pre bumps ALL packages, counters require committed state, dist-tags can't be controlled.
+
+Bumpy replaces the mode with **branch-based channels** ([docs/prereleases.md](./prereleases.md)): a long-lived branch (e.g. `next`) maps to a prerelease line. Bump file location (`.bumpy/<channel>/`) is the only state; prerelease versions are never committed — targets derive from bump files, counters from the registry. Promotion to stable is just a merge.
+
+- [changesets#729](https://github.com/changesets/changesets/issues/729) — exiting pre mode bumps all versions (14 comments)
+- [changesets#786](https://github.com/changesets/changesets/issues/786) — can't control dist-tag in pre mode (13 comments)
+- [changesets#635](https://github.com/changesets/changesets/issues/635) — prerelease workflow problems
+- [changesets#239](https://github.com/changesets/changesets/issues/239) — prerelease mode design issues
+- [changesets#381](https://github.com/changesets/changesets/issues/381) — prerelease counters require committed state
+
 ### Local bump file verification
 
 `bumpy check` verifies that changed packages on the current branch have corresponding bump files. Compares your branch to the base branch, maps changed files to packages. By default it only fails if no bump files exist at all (matching changesets behavior). Use `--strict` to require every changed package to be covered, `--no-fail` for advisory-only mode, or `--hook pre-commit`/`--hook pre-push` to control which bump files count based on their git status. No GitHub API needed.
@@ -157,15 +169,6 @@ Changesets has no built-in equivalent — users rely on the CI bot comment to ca
 
 ## Planned / Not Yet Implemented
 
-### Prerelease mode that actually works
-
-Changesets' prerelease mode is described in their own docs as "very complicated" with "mistakes that can lead to repository and publish states that are very hard to fix." Key problems: no target on bump files, multi-branch corruption, exiting pre bumps ALL packages, bad interactions with linked/fixed groups.
-
-- [changesets#729](https://github.com/changesets/changesets/issues/729) — exiting pre mode bumps all versions (14 comments)
-- [changesets#786](https://github.com/changesets/changesets/issues/786) — can't control dist-tag in pre mode (13 comments)
-- [changesets#635](https://github.com/changesets/changesets/issues/635) — prerelease workflow problems
-- [changesets#239](https://github.com/changesets/changesets/issues/239) — prerelease mode design issues
-
 ### Root workspace / non-package changes
 
 Track changes to CI, tooling, and monorepo-root-level config in changelogs — not just workspace packages.