Release

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

.claude/agents

.claude/skills

.github/CLAUDE.md

CLAUDE.md

apps/backend/CLAUDE.md

import { test, expect } from "../../fixtures/test-base";

apps/web/generated/licenses.json

Audit 0.4.1 · source sha 786d4817799e · 18 Oct 2026Report an issue or request a re-scan

• Publisherkdlbs GitHub organizationOwner of the repository this skill is read from
• Source folderkdlbs/kandev/.agents/skills/releaseThe exact folder we audited
• LicenceAGPL-3.0As the repository states it
• Commit pinned for this verdict786d4817799eA new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Kandev release and version-channel conventions — unified Stable SemVer plus deterministic npm-only Nightlies. Use when cutting a release, changing channels, debugging artifacts, or answering version-channel questions.

---
name: release
description: Kandev release and version-channel conventions — unified Stable SemVer plus deterministic npm-only Nightlies. Use when cutting a release, changing channels, debugging artifacts, or answering version-channel questions.
---

# Release & Versioning

Kandev Stable releases use a **single SemVer** `X.Y.Z` shared across all distribution channels.
npm also has an explicit prerelease-only `nightly` channel; it is not part of the unified Stable
artifact set.

## Version targets

- `apps/cli/package.json` version → `X.Y.Z`
- npm main package: `[email protected]`
- npm runtime packages: `@kdlbs/runtime-{platform}@X.Y.Z` (5 platforms; declared as `optionalDependencies` in main package)
- Git tag: `vX.Y.Z` (three-part; legacy `vM.m` tags normalize to `M.m.0`)
- Homebrew formula: `kdlbs/homebrew-kandev` `Formula/kandev.rb` `version "X.Y.Z"`
- Scoop bucket: `kdlbs/scoop-kandev` `bucket/kandev.json` version, URL, and hash
- GitHub release: `vX.Y.Z` with standard platform archives `kandev-{platform}.tar.gz`, full offline archives `kandev-{platform}-full.tar.gz`, checksums, Windows ZIP equivalents, remote helper assets, and `runtime-size-report.md`

Stable default archive names contain the standard runtime: host `kandev`, host `agentctl`, and
`remote-helpers.json`. The `-full` archives also contain all four remote helper executables. Stable
npm packages, Homebrew, Scoop, winget, Chocolatey, and Desktop use standard archives. Containers
and npm Nightlies stay full. Desktop keeps one standard installer and updater track.

**npm, Homebrew, and Scoop are sibling channels**, not chained. All three consume the same GitHub release artifacts; none depends on another package-manager channel.

For npm Nightly, Stable `X.Y.Z` plus a full `main` SHA produces
`X.Y.(Z+1)-nightly.sha<first-12-lowercase-hex>`. `kandev` and all five runtime packages publish at
that exact version under npm's `nightly` dist-tag. Nightly never moves `latest` and creates no Git
tag, GitHub Release, Homebrew formula, Scoop bucket update, Desktop feed/build, or container tag.

## Release flow

Stable runs entirely in CI via `.github/workflows/release.yml`, triggered by a maintainer from the GitHub Actions UI:

1. Maintainer clicks "Run workflow" → keeps `channel=stable` → picks `bump` (patch/minor/major) → optional `dry_run` or `desktop_validation_only`.
2. `prepare` job bumps version + regenerates CHANGELOG, opens release PR, squash-merges, tags `vX.Y.Z`.
3. `build-web`, `build-bundles`, `build-remote-helpers`, `build-desktop`, and both Docker builds create the channel inputs.
4. `publish-release` promotes staged standard archives to the existing default names, publishes full archives and helper assets, then attaches checksums, the size report, desktop artifacts, and notes.
5. `publish-npm` publishes 5 `@kdlbs/runtime-*` packages + main `kandev` package to npmjs.
6. `update-homebrew-tap` pushes updated `Formula/kandev.rb` to `kdlbs/homebrew-kandev` via SSH deploy key.
7. `update-scoop-bucket` pushes updated `bucket/kandev.json` to `kdlbs/scoop-kandev` via its SSH deploy key.

## Contributor notices

The `Release` workflow has a `notify_contributors` checkbox. It defaults to false. When selected, the workflow calls the reusable notification workflow after GitHub Release, npm, Homebrew, and Scoop publication all succeed. Dry runs, desktop validation, Nightly, cancellation before the notification job starts, and publication errors skip the call. Cancellation after posting starts can leave partial notices; rerun with the exact tag to complete safely.

For manual notices or recovery, run **Notify release contributors** from the `main` ref. Leave `release_tag` empty to select the latest published Stable release. Enter an exact tag to select another release. The `dry_run` checkbox previews the same PR selection and comment text without posting.

The helper reads PR links from the release notes. It posts only to merged PRs from this repository that belong to the selected release tag. It excludes bots and maintainers from `cliff.toml`. The job token posts as `github-actions[bot]`. Only notices from that bot or a listed maintainer count as already sent.

Each comment includes a hidden release ID marker. Repeat runs skip comments with that marker and the exact unmarked notice used for `v0.97.0`. After a partial run, use the separate workflow with the exact tag. It skips confirmed notices and retries only missing notices. Wait for GitHub rate limits to clear before retrying.

## Release PR ruleset bypass

A normal Stable release creates its branch and pull request with `GITHUB_TOKEN`.
It uses `RELEASE_PR_BYPASS_TOKEN` only for an exact-head `gh pr merge --admin`.

Store this fine-grained personal access token in the protected `release`
environment. Its owner must remain an organization administrator. Select only
`kdlbs/kandev` and grant `contents: write` repository permission.

Record the token owner and expiration date. Rotate the environment secret before
the token expires or the owner loses administrator access. The workflow must
stop before tag creation when the token is missing or cannot bypass the ruleset.

After the merge, use `GITHUB_TOKEN` to read the PR state. Tag only the merge
commit that GitHub reports after it appears on `origin/main`.

**Workflow-control invariant:** When a channel intentionally skips a job, every
downstream job reachable through that dependency chain must use a status function
such as `!cancelled()` plus explicit `needs.<job>.result == 'success'` checks.
For a partial Stable release, preserve the existing signed tag and rerun with
`backfill_tag`; never run a normal bump against an existing tag. Declare Stable
complete only after `publish-release`, `publish-npm`, `update-homebrew-tap`, and
`update-scoop-bucket` each succeed and their artifacts are verified—an aggregate
green run can hide skipped publication jobs.

Required web, runtime, and desktop artifact uploads attempt up to three times,
with w

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/kdlbs/kandev
git -C kandev checkout 786d4817799e

Works in

1. 2026-10-18
   !CAUTION B 89 / 100

   first audit · source 786d4817799e

Questions about Release

• github.com/kdlbs/kandev/tree/main/.agents/skills/release — the audited source at commit 786d4817799e and every finding aboveObserved · 18 Oct 2026

Spotted something wrong? Report a correction · Methodology