vibey releasing

vibey-gh owns the release (ADR-0028). There is no release-please step and no hand-run publish. The version is derived, not chosen: vibey-gh version reads what changed against [version] content_paths and code_paths in .vibey-gh.toml and answers major, minor, patch, or nothing. vibey-gh promote applies that answer. The changelog is written as fragments, one file per change, and the release commit folds them in.

Every workflow on the release path installs the tree's own vibey-gh from the declared [install] self_source = "src/vibey_tools/gh", and falls back to installing vibey-engine from PyPI -- which carries vibey-gh (ADR-0037) -- only when that path does not hold the package. A change to vibey-gh therefore changes the release path on the next push.

Where a release goes

PyPI is not the finish line. These are command-line applications, and someone installing a CLI reaches for brew install or winget install -- that it is written in Python is an implementation detail they should not have to care about.

Publish to every registry that can carry it, and treat the channel as part of shipping rather than a follow-up. Every packaging definition -- formula, PKGBUILD, snapcraft.yaml, nuspec, winget manifest -- is to live in this repository and be published by automation, never hand-edited in a tap (ADR-0018, ADR-0019, sub-doctrine 2.b). A stale formula is worse than no formula: it installs an old version silently.

As of 2026-09-15 none of those packaging definitions exist yet. The channels this repository publishes today are:

• vibey-engine on PyPI (from main) and on TestPyPI (from develop) — vibey-engine.yml. It carries the whole engine family (ADR-0037, renamed by ADR-0069)
• krypton-app, the apps and the krypton command, on the same two channels — krypton-app.yml. Exactly these two packages publish (sub-doctrine 9.e, ADR-0069); no vibey package does
• An OCI release bundle of the exact wheel and sdist at ghcr.io/<owner>/<repo>/python — release-surfaces.yml
• The documentation site, book and paper — release-surfaces.yml (below)
• A Git tag and GitHub Release per released version — github-release.yml

The container image (deploy/docker/Dockerfile) and Helm chart (deploy/helm/vibey) are defined and tested in CI (image, cluster-smoke) but not pushed to a registry by any workflow. ADR-0019 is the backlog for the rest.

Note what publishing does and does not mean per target. dpkg, rpm and apk-tools are formats, not registries. podman wants an OCI image, which this repository already builds. npm, Maven, Cargo and the rest cannot carry a Python library at all -- only a wrapper that fetches the CLI, which is a different promise and has to say so. See ADR-0019 for the grouping and the order.

The workspace tenants (claudeloop, codexloop, qwenloop — which ships the gptossloop and qwenloop scripts — vibey-gh, vibey-skills, vibey-bootstrap) are no longer separate PyPI distributions. Their source lives in this repository (ADR-0021) and they ship inside the vibey-engine wheel (ADR-0037, ADR-0069), so vibey-engine.yml publishes vibey-engine and that one package is the whole engine family. A tenant's own version in its pyproject.toml is an in-tree marker, not a release.

Conventional Commits (enforced)

Every commit message must follow Conventional Commits format. A commit-msg hook rejects anything else:

feat: add support for GitHub Actions deployment
fix: prevent race condition in lease renewal
docs: update handoff protocol spec
chore: bump dependencies
test: add property test for rotation fairness

Scopes are optional but recommended for large changes:

feat(domain): add media provider round-robin cursor
fix(cli): correct --cwd handling in run command

Breaking changes carry a ! or a BREAKING CHANGE: footer:

feat!: require Python 3.12+

BREAKING CHANGE: Python 3.12 is now required.

Why this matters: commit messages reach the version in exactly one way — a breaking marker — and nothing else about them is read. The minor/patch/nothing part of the answer is derived from which paths changed, never from commit types. Conventional Commits are still enforced for a legible history and because the provenance gate reads every commit in a range — which is why the automation's own release commit is chore(release): x.y.z.

A breaking change is derived, and this is the one place commit text reaches the version: a BREAKING CHANGE: / BREAKING-CHANGE: footer, or a ! before the colon in a subject, anywhere in the released range escalates the answer to major. vibey-gh reads that marker with the same parser it uses when it flattens a branch, so the commit it writes and the version it derives can never disagree. Nothing else about the message is read: the minor/patch/nothing part of the answer is still derived from which paths changed.

How the version is derived

uv run vibey-gh version --since origin/main --explain prints the answer and why. It compares origin/main to HEAD, ignores files whose only change is the provenance header, and then:

• any changed file under [version] content_paths → minor
• otherwise, any changed file under [version] code_paths → patch
• otherwise (docs, workflows, tooling only) → nothing to release
• and then, only if one of the first two matched, a breaking marker anywhere in the range escalates that answer to major

The order is the implementation's, not a presentation choice. A marker never creates a release: docs!: … still answers "nothing to release", because a break is a promise about an interface somebody installed and a range that ships nothing has no interface to break.

Since the whole tree ships as one package, vibey-engine (ADR-0037, ADR-0069), content_paths must cover every prefix whose content reaches an installed user: src/vibey/, each runner's and tool's package root, and the skills marketplace tree. It deliberately does not cover a tenant's docs/ or tests/, which change nothing a user installs. code_paths must include pyproject.toml, because the root manifest now decides what ships, and clients/, because every release attaches the clients' builds, so a change to the clients alone derives a patch (#1348). Left narrower than that, a release that touches only tenants classifies as "nothing to release" and republishes the current version into skip-existing — a green run that publishes nothing. The literal prefixes are in .vibey-gh.toml; read them there rather than from memory, because startswith matching cannot express a glob and the list is spelled out. If the version on HEAD already differs from origin/main, the derivation leaves it alone.

[version] files lists what a bump writes: pyproject.toml and src/vibey/__init__.py. vibey-gh's apply_version also re-runs uv lock when uv.lock is present, because the lock carries vibey's own version and CI's uv-lock job runs uv lock --check before the other jobs.

Release workflow

1. PRs land on develop through the merge train. pr-evaluate.yml re-evaluates a PR each time CI or Provenance completes, and dispatches pr-review.yml when a review is called for; merge-train.yml runs each time a PR review run completes, deliberately whatever its conclusion (with a weekly Monday cron and manual dispatch as backstops); vibey-gh merge-train merges only PRs whose head carries a successful PR automation / gate. PRs into develop are squash-merged. Never implement on main.
2. Every push to develop publishes a dev build. vibey-engine.yml stamps x.y.z.devN (vibey-gh version --dev <run number> --apply), checks that the project is named vibey-engine (pyproject.toml says so itself; nothing is renamed in the runner), publishes to TestPyPI via OIDC trusted publishing (environment testpypi), and verify-testpypi installs that exact version and runs vibey --version. krypton-app.yml does the same for clients/krypton-app whenever that tree changes, and its verify job runs krypton --help.

3. Promotion is automatic. promote-to-main.yml runs after the merge train completes (weekly Monday cron backstop; manual dispatch with dry_run). It runs vibey-gh promote, which:

   • compares develop and main by tree content and stops if they are identical;
   • derives the version on develop and, when a bump is due, commits chore(release): x.y.z (version files plus uv.lock, and the changelog: fragments folded in and deleted, ## [Unreleased] cut to ## [x.y.z] (date)) and pushes it to develop, raising if the push fails;
   • opens or reuses the develop → main promotion PR, titled chore(release): <version>.

   The PR-automation gate and merge train then merge the promotion PR once its checks pass, with rebase (promote.DEFAULT_METHOD = "rebase"; the merge train uses rebase for any PR based on main). Because main is rebase-merged, its commits are rewritten copies with new SHAs.

4. Every push to main publishes to PyPI. vibey-engine.yml builds the wheel and sdist and publishes vibey-engine to PyPI via OIDC trusted publishing (environment pypi, skip-existing: true); krypton-app.yml publishes krypton-app the same way.
5. main realigns develop. The realign job runs vibey-gh realign, which converges develop onto main only when the two trees are identical. It skips with a notice when AUTOMERGE_TOKEN is not set — harmless, since promotion compares branches by content.
6. After a successful Release run on main, github-release.yml runs vibey-gh github-release --target <sha>: it creates the immutable tag <tag_prefix><version> ([github_release] tag_prefix is vibey-v here, so vibey-v3.3.0; the default is v) and the GitHub Release, and never moves an existing tag. A manual dispatch must prove the target SHA is on main and has a successful Release run.
7. After a successful Release run on develop or main, release-surfaces.yml publishes the documentation surfaces and the OCI bundle (see "The workflows").
8. After a successful Release run on main, release-binaries.yml builds every client target scripts/release_binaries.toml declares, writes SHA256SUMS, attests each file's build provenance and attaches them to that GitHub Release (docs/guides/downloads.md lists them); openvsx.yml publishes the VS Code extension to Open VSX. Both are workflows of their own, so neither can fail the release.

To preview what the next promotion will do, run uv run vibey-gh version --since origin/main --explain, or dispatch promote-to-main.yml with dry_run.

A ratified change to the doctrine canon is also a release event: Article V.4 of the constitution (src/vibey_tools/gh/docs/constitution.md) requires every prior release to be yanked. See the vibey-architecture skill.

The changelog

Never edit CHANGELOG.md by hand. Every PR editing the same ## [Unreleased] lines made concurrent PRs conflict on every merge, and the old merge=union attribute never helped on GitHub, whose mergeability does not run it. The changelog is written as fragments instead ([changelog] in .vibey-gh.toml): the PR that lands a user-visible change adds one new file, changelog.d/<slug>.<type>.md beside the changelog it belongs to (src/vibey_tools/gh/changelog.d/ for vibey-gh's own), holding the entry exactly as it should read, bullet included:

* **gh:** what changed, for whom, and why it matters
  ([#1303](https://github.com/the-vibey-project/vibey/pull/1303)).

The slug is letters, digits, - and _ (the PR number or a short name); the type is one of breaking, feature, fix, perf, refactor, removed, docs, chore, which files it under ### BREAKING CHANGES, ### Features, ### Bug Fixes and so on. No heading inside a fragment.

vibey-gh promote folds every fragment into ## [Unreleased] under its heading in the release commit, deletes it, and cuts the section to ## [x.y.z] (date) with a fresh ## [Unreleased] above (vibey-gh's own changelog is folded but never cut: its releases are the GitHub Releases). No hand step. uv run vibey-gh changelog assemble does the fold alone, idempotently, if you want to preview it.

The Changelog fragment check (changelog.yml) refuses a PR into develop that changes a shipped path ([changelog] require_for) without adding a fragment, adds a malformed one, or edits an unreleased section directly. Label the PR no-changelog when no reader of the changelog would miss the change; the label never excuses a malformed fragment or a hand edit. The check creates the label itself (vibey-gh changelog ensure-label), so it always exists.

Entries 0.2.0 through 0.6.0 were reconstructed from the release commits on 2026-09-15; a released version without an entry is a documentation bug.

Documentation surfaces

The documentation ships with every release channel, so treat it as release content:

• Site: properdocs.yml at the repository root drives the ProperDocs build of docs/. docs/plans/** is excluded on purpose (working material, not reference). A page not listed under nav is still built but is not reachable from the navigation.
• ADRs: a new decision record is docs/architecture/decisions/NNNN-slug.md with the next contiguous number and a **Status:** · **Date:** line. It must be added to the properdocs.yml nav, and the "(N ADRs" count in CLAUDE.md, AGENTS.md, GEMINI.md, README.md and docs/index.md must match the files on disk. tests/meta/test_adr_counts.py enforces all three.
• The AI-reader index: docs/llms.txt is generated from the properdocs.yml nav by python scripts/llms_txt.py (configuration in scripts/llms_txt.toml), so every nav edit -- a new page, a new ADR -- is followed by that command in the same change. tests/meta/test_llms_txt.py runs --check and fails until it is (ADR-0076).
• Per-page descriptions: a page's description: front matter becomes its meta description through docs-theme/main.html; a page without one is described by the publishing workflow's site-wide sentence.
• Paper: docs/paper.md is the source for both the HTML page (/paper/) and paper.pdf. Every update to the paper passes python scripts/paper_publishability.py check before it lands and before it is published: tests/meta/test_paper_publishability.py runs it on every pull request, and release-surfaces.yml runs it again, as the [documentation] paper_gate declared in .vibey-gh.toml, before the paper's figures are rendered. The criteria it checks, and the reviewer's rubric for what no script can judge, are the journal-publishability-criteria skill in vibey-skills' writing-craft plugin.
• Book: generated from the built channel site by vibey-gh book; there is no separate book source. A page added to the site is in the next book.
• Agent surfaces: every skill exists in four trees — .claude/skills/, .agents/skills/, .cursor/rules/, .agent/rules/ — and a change to one lands in all four in the same PR.

A deliberate bump

Use this only when the train is down. A major bump is not a reason: derive it with a breaking marker, so the number the repository carries is one the machine can reproduce.

1. uv run vibey-gh version --since origin/main --explain to see the derived answer.
2. Pass --apply so the tool writes it. apply_version also re-runs uv lock and re-renders every managed workflow whose pip install pin this repository's version decides — both are functions of that number, and a bump that leaves either stale fails the very gates the promotion needs. It folds and cuts the changelog too, exactly as promote does. Editing the two files by hand means doing uv lock and vibey-gh install yourself, in the same commit.
3. Commit with chore(release): x.y.z — the exact subject vibey-gh promote writes.
4. Land it on develop through a PR. vibey-gh promote sees that develop already differs from main in version, leaves the bump alone, and still opens the promotion PR.

Verifying the publish

After main builds:

1. Check the Release run in GitHub Actions, then GitHub Release, Release surfaces, Release binaries and Open VSX.
2. Verify PyPI: https://pypi.org/project/vibey-engine/ and https://pypi.org/project/krypton-app/
3. Install and test:

uv venv --python 3.12
source .venv/bin/activate
pip install vibey-engine==x.y.z
vibey --version
# the bundle is the contract now (ADR-0037): every console script must be there
for c in vibey vibey-gh vibey-skills vibe-skills vibey-bootstrap azbootstrap \
         claudeloop codexloop gptossloop qwenloop; do
  command -v "$c" >/dev/null || echo "MISSING: $c"
done

4. Check the published surfaces for the main channel:
   • Documentation: https://the-vibey-project.github.io/vibey/main/
   • Paper: https://the-vibey-project.github.io/vibey/main/paper/ and https://the-vibey-project.github.io/vibey/main/paper.pdf
   • Book: https://the-vibey-project.github.io/vibey/main/book.pdf, https://the-vibey-project.github.io/vibey/main/book.epub, https://the-vibey-project.github.io/vibey/main/book-print.html
5. Check the release's files: every file docs/guides/downloads.md lists is attached (a target built only while a credential is set may be missing, with its tracking issue open), and in a folder holding them all:

gh release download vibey-vx.y.z --repo the-vibey-project/vibey
shasum -a 256 --check --ignore-missing SHA256SUMS
for f in $(awk '{print $2}' SHA256SUMS); do
  gh attestation verify "$f" --repo the-vibey-project/vibey >/dev/null || echo "UNATTESTED: $f"
done

The attestation is per listed file, not on SHA256SUMS itself. Then check that Open VSX lists the-vibey-project.krypton at the extension's version.

For a develop push, the verify-testpypi job already installs the dev build. On TestPyPI, read the release history of vibey-engine and krypton-app, not their "latest" version: dev builds (x.y.z.devN) are pre-releases, so a project page shows the last final version uploaded there while dev builds keep landing. (vibey-dev is the retired TestPyPI name of the builds before ADR-0069.)

Common issues

Nothing ran on main after a promotion: a commit message carrying a GitHub skip marker (a bracketed skip-ci spelling, or a skip-checks trailer) makes GitHub run no push workflow for it -- no CI, no publish, no tag, no documentation, and nothing red. 3.0.0 hit this when #1244 was squashed by hand and GitHub's default body concatenated old estimate subjects that quoted the marker. Recover by dispatching vibey-engine.yml and krypton-app.yml on main (every publishing job is gated on github.ref, so a dispatch publishes exactly what the push would have). Three things now keep it from recurring: main accepts rebase merges only ([rulesets.release] allowed_merge_methods), a squash proposes the pull request's own title and body ([repository_profile] squash_merge_commit_*), and skip-markers.yml ("No skip markers") refuses a marker in any commit, title or body on its way into develop or main. Write about the marker in prose; never quote it in a message.

The PyPI publish succeeded but there is no tag, GitHub Release or docs: github-release.yml and release-surfaces.yml follow only a successful Release run, so any failing job of vibey-engine.yml withholds all three. Optional channels therefore live in workflows of their own: the Open VSX publish is openvsx.yml, run after a successful Release on main; without OVSX_PAT it warns and keeps one tracking issue open rather than failing anything. With the token it first creates the publisher's Open VSX namespace (the-vibey-project) when it is missing, treating only "already exists" as success, so the first publish of the-vibey-project.krypton needed no hand step (0.2.0, with 3.3.0).

develop is red: branch-health.yml keeps one issue per permanent branch open while a CI push run fails one of its required checks, and closes it when the tip is green. Fix the branch before merging over it.

Version didn't change on PyPI: the derivation found nothing under [version] content_paths or code_paths (docs, workflow and test changes release nothing), or the bump was never pushed. An unbumped version with skip-existing: true is a green run that publishes nothing.

uv-lock fails after a version change: the lock carries vibey's own version. Run uv lock and commit it with the bump.

Publish failed: check the Release run. Common causes: OIDC trusted publisher not configured for the pypi/testpypi environment, wheel build failed, or the in-tree vibey-gh rejected .vibey-gh.toml.

Promotion PR does not merge: the checks must pass on the promotion head, and a ruleset that requires an approving review needs AUTOMERGE_TOKEN (a token whose owner holds the required ruleset role).

develop didn't realign after a release: check whether AUTOMERGE_TOKEN is set — the realign job skips (not fails) without it. To realign by hand, and only when the trees match: git push --force-with-lease origin main:develop.

CHANGELOG.md doesn't mention the shipped version: the release commit cuts ## [x.y.z] (date) from whatever fragments had landed; a change that shipped without one was merged without a fragment (labelled no-changelog, or before fragments existed). Add the entry as a fragment in a follow-up PR; it lands in the next version's section (see "The changelog").

The workflows

• .github/workflows/pr-evaluate.yml and pr-review.yml — the split PR automation: pr-evaluate.yml triages the exact head on each CI/Provenance completion and publishes PR evaluate / gate; pr-review.yml, which it dispatches, runs the exact-head review and publishes PR review / gate.
• .github/workflows/merge-train.yml — merges ready PRs (squash into develop, rebase into main).
• .github/workflows/promote-to-main.yml — vibey-gh promote.
• .github/workflows/vibey-engine.yml — build on every push to develop/main; testpypi/verify-testpypi on develop; pypi and realign on main.
• .github/workflows/krypton-app.yml — build (tests and wheel) for clients/krypton-app; testpypi/verify-testpypi on develop, pypi on main.
• .github/workflows/github-release.yml — tag and GitHub Release after a successful Release on main.
• .github/workflows/release-surfaces.yml — after a successful Release on develop or main (or manual dispatch per channel):
  • the ProperDocs site for that channel at https://the-vibey-project.github.io/vibey/<channel>/, all channels on one GitHub Pages deployment with a channel chooser at the root;
  • the book (vibey-gh book → book.epub and book-print.html, plus book.pdf when Chromium is available on the runner);
  • the paper (docs/paper.md, served as paper/, and vibey-gh paper → LaTeX → paper.pdf);
  • the OCI bundle ghcr.io/<owner>/<repo>/python:<version>, also tagged with the channel and sha-<commit>, and latest on main.
• .github/workflows/provenance.yml — the server-side provenance check on every push and PR.
• .github/workflows/automation-bootstrap.yml — the admin-only recovery path for a PR that repairs a broken privileged gate.
• .github/workflows/openvsx.yml — the VS Code extension to Open VSX, after a successful Release on main; outside Release so it can never fail the tag.
• .github/workflows/release-binaries.yml — every client's build for the release, after a successful Release on main: the targets in scripts/release_binaries.toml, SHA256SUMS, a provenance attestation per file, attached to the GitHub Release; python scripts/release_binaries.py check holds the workflow and the downloads page to that file.
• .github/workflows/skip-markers.yml — No skip markers, on every pull request and merge-queue group into develop or main.
• .github/workflows/changelog.yml — Changelog fragment, vibey-gh changelog check on every pull request into develop.
• .github/workflows/branch-health.yml — one tracking issue per red permanent branch.
• .github/workflows/ruleset-drift.yml — vibey-gh rulesets --check, read-only, daily and on every change to .vibey-gh.toml.

All but automation-bootstrap.yml (manual dispatch only) are triggered by pushes, pull requests, workflow completions or schedules. Dispatch one by hand only to recover or debug -- vibey-engine.yml and krypton-app.yml accept a dispatch for exactly that.