#Check system

rlsbl includes 85 checks across 9 tags.

Run checks via the rlsbl check command. Checks are organized across 6 primary tags (project, release, changelog, workspace, quality, prepush) and validate project metadata, release state, changelog structure, workspace integrity, code quality, and pre-push enforcement. Four additional untagged checks run only with --all or --name. Three further tags exist for pipeline and target-specific grouping: preflight and preflight-changelog are run internally by rlsbl release run, and maven groups the Maven-specific check. A few more checks come from strictcli rather than from rlsbl's own checks.toml and are therefore outside every count on this page; they are documented under framework checks.

#Running checks

# Run all checks
rlsbl check --all

# Run all checks in a tag
rlsbl check --tag changelog

# Run a single check by name
rlsbl check --name version-consistency

# Scope a run to one releasable (required at a monorepo workspace root)
rlsbl check --tag changelog --releasable core

#Where a check run is scoped

In a standalone repository, and in a workspace member's directory, the cwd names exactly one project and every check answers for it.

A workspace ROOT does not: it names the workspace. The checks that answer for one project -- the whole project, changelog and release families, and every quality check that is not workspace-scoped -- therefore refuse there with an error result naming both routes, rather than reading the root as a project of its own (which reported SKIP "no targets detected" and demanded config keys in a .rlsbl/config.json a workspace root must not have). Name the releasable with --releasable <name> to scope the run to it, or run rlsbl check from a member directory.

Two families are untouched at the root, because it is the position they are meant to be run from: the workspace-scoped checks (--tag workspace), and the prepush family, which the pre-push hook runs at the repository root of every workspace.

--releasable is refused anywhere the directory already answers -- a member directory, or a standalone repository.

check is strictcli's own auto-registered command and its flags are the framework's, so rlsbl lifts --releasable out of argv before the app parses it, exactly as it does for the positional arguments strictcli cannot express. It is therefore absent from rlsbl check --help and from the dumped CLI schema; this page and the refusal itself are where it is documented.

#Check results

Each check returns one of four statuses that determine how the result is displayed and whether it blocks the release pipeline. The severity level (error or warn) is declared per-check in the check metadata stored in checks.toml and controls which status is reported on failure versus advisory findings:

Severity is declared per-check in metadata. A check with severity = "error" reports fail on failure; one with severity = "warn" reports warn.

#Tags

Some checks carry multiple tags, so they appear in multiple tag counts: test-suite is tagged prepush and quality, test-suite-workspace is tagged prepush and workspace, and scaffold-conflicts is tagged project, prepush, and release. Four checks (layers-violations, deps-unused, deps-undeclared, deps-stale) have no tag and only run with --all or --name. Internal tags used by the release pipeline: preflight (21 checks: library-lint, test-suite, dev-overlay-drift, maven-central-metadata, wrapper-producer, strictspec-certificate-gate, stricttest-floor, dep-floors, dep-locks, go-module-identity, ldflags-symbol, strictspec-generated-floor, target-matrix-fresh, router-filters-fresh, workspace-unbuildable, and the six path-capable tool checks lint, lint-scope-guard, format, format-scope-guard, type-check, type-check-scope-guard) and preflight-changelog (9 checks: the structural changelog checks, i.e. all changelog checks except changelog-entry and changelog-format-version). The maven tag groups maven-central-metadata.

#Project checks

#Release checks

scaffold-conflicts (see project checks) is also tagged release. unpublished-refs depends on version-consistency; if it fails, unpublished-refs is skipped.

Every check in this tag reads something outside the working tree -- the remote's refs, the GitHub API, the Go module proxy. That is why they carry release rather than project: the offline tags (project, changelog, quality, prepush) stay answerable with no network, and a networked check placed in one of them would fail an offline run for a reason that has nothing to do with the repository. All of them are fail-closed: a probe that cannot answer is a hard error, never a pass. None is in preflight -- the release pipeline's own steps already authenticate against GitHub and the registries, and a probe failure there would block a release for a network condition rather than for anything about the repository.

#unpublished-refs

The ref set it renders against reality is expected_refs, the target protocol's single authority for what one version owns -- the same derivation the release's tag step acts on, so a ref the release creates can never be a ref the check does not look for.

Each failure it reports names rlsbl release reconcile as the remedy:

It is fail-closed: a probe that cannot answer -- an unreadable local tag namespace, an ls-remote that fails, a Release listing that errors or that gh cannot make because it is absent or unauthenticated -- is an error, never a pass. A repository with no origin remote at all is a different state: the remote half is skipped and the outcome says so. So is a repository whose origin resolves to no GitHub repository: the Release half is skipped, because there is no forge for a Release to be missing from.

A version the release record records as unrecoverable has no recoverable commit, so a ref it is missing cannot be recreated and rlsbl release reconcile has nothing to point at -- and no release commit to take a rlsbl-ci-sha marker from either, so a Release it lacks cannot be materialized. Both absences are counted and named in the outcome message instead of reported as fixable errors. Every other finding for such a version -- a ref that exists locally but not on origin -- is still reported.

A version the release record records as never_released is a version NUMBER no release ever used, so it owns no ref and no Release at all. It is skipped, named in the outcome message, and excluded from the released-version count -- reporting a phantom as a release would be the check agreeing with the mistake it exists to surface.

A Release is judged on the version's primary tag, the one the release flow attaches it to, and only when that tag is on origin. A tag that never reached the forge is already reported as missing on origin, and a Release cannot exist without it.

No version window. Every half covers every archived release, not a recent slice. The whole local tag namespace comes from one for-each-ref, the whole remote namespace from one ls-remote, and every Release from one gh release list, so probing two hundred releases costs the same as probing one. A per-version probe would have forced a bound and left older releases unchecked.

It replaced three narrower checks (local-tag, remote-tag, github-release) that each looked at the primary tag of the current version only, and so saw neither companion tags, nor recorded aliases, nor any past release.

GitHub Release presence, and its repair. The retired github-release check asked whether the current version's Release exists; this check asks it of every archived version, from the same listing, and reports an absence as an error. The repair is rlsbl release reconcile: --plan gives such a version a materialize verdict, and --apply creates the Release with the same body the release flow itself writes (the changelog section, the rlsbl-ci-sha marker taken from the recorded release commit, and the pre-release flag the version earns). The check finds the gap; the reconcile closes it. See Reconciling published metadata.

#Changelog checks

Dependencies: changelog-range and changelog-coverage depend on changelog-hashes (hash resolution must succeed first).

#Workspace checks

test-suite-workspace (see prepush checks) is also tagged workspace.

#Quality checks

test-suite (see prepush checks) is also tagged quality.

#Prepush checks

scaffold-conflicts (see project checks) is also tagged prepush. Dependencies: test-suite and test-suite-workspace both depend on prepush-changelog-coverage -- fast checks fail first, so the test suite is skipped if changelog coverage fails. test-suite is also tagged quality, so it runs under both rlsbl check --tag prepush and rlsbl check --tag quality.

Both test-suite checks are overlay-preserving: when the project runs on rlsbl dev sync overlays, their uv sync excludes every overlaid package and the suite runs with uv run --no-sync. See the dev workflow for why a bare sync would otherwise wipe the overlays it is about to test.

#Untagged checks

These 4 checks have no tag assignment and run only when explicitly requested via --all or --name. They are excluded from tag-based runs because they require specific project configurations (layer rules, workspace manifests) or have longer execution times:

#Framework checks

Every check above is declared in rlsbl's own checks.toml, and so are the counts on this page. The checks below are not: strictcli registers them into the same registry when rlsbl builds its CLI, so they run under rlsbl check --all and under the tags they carry, but no rlsbl-side count includes them. They carry the framework's own tags (test, effects), and the three effects lints also carry quality, so rlsbl check --tag quality runs them.

#Target applicability

Not every check applies to every release target. Each check declares its applicability as one of three categories, which determines whether it runs for a given project based on the project's detected targets:

• Universal (None): runs for any target -- most project, release, and changelog checks
• Workspace-only ("workspace"): runs only in monorepo workspaces, target-agnostic
• Target-specific (frozenset): requires specific language targets with import scanners or AST analysis

#Excluded targets

Some checks explicitly exclude specific targets where the compiler or language toolchain already enforces the same constraint natively, making rlsbl's check redundant. These exclusions prevent false positives and unnecessary warnings:

#Check metadata

Checks are declared in rlsbl/data/checks.toml with metadata that controls execution order, dependency resolution, and result severity. Each check entry has the following fields that the check runner uses to determine when and how to execute the check:

Checks are implemented via the @app.error_check("<name>") and @app.warn_check("<name>") decorators in the rlsbl/checks/ package (one module per tag, e.g. project.py, release.py, workspace.py), which register the function with strictcli's check system. The name passed to the decorator must match the key in checks.toml, and the decorator chosen must match that entry's severity.

#Purity

A pure check starts only read-only programs on the observe allowlist. The allowlist is rlsbl/observe_allowlist.py, whose written standard is no user-visible mutation: ref updates, index writes and credential emission are refused there, so any program that reaches the list changes nothing a user would notice. A check that starts no program at all is trivially pure.

A check is impure when it starts a program that is not on that list. Every impure check today runs a tool that writes: ruff rewrites files, uv sync materializes an environment, the test suites and gradle build.

Purity decides what a preview does. Under rlsbl release run --dry-run the preflight runs its pure checks for real and lists the impure ones as would run: <name> (impure) -- so a preview reports real findings from everything that can be run without changing anything, and is honest about the rest.

This rule replaced an older one, "the check starts no program at all". That rule forced nine checks that spawn only read-only local git (the changelog validators, the two pre-push checks, workspace-unregistered, go-companion-tags) to be declared impure, and it quietly declared two checks pure that do spawn: the retired local-tag ran git tag --list, and config-schema can reach go list on its error path. All of them are pure under the current rule, and are now declared so deliberately rather than by accident.

The declaration is verified, not trusted: tests/test_check_purity.py executes every pure-declared check under an effects observer and fails on any spawn whose argv matches no allowlist prefix.

needs_network is orthogonal: it says whether a check needs the network to answer at all, never whether it may mutate. A pure check may be a network read.

#Examples

#Running all checks before a release

rlsbl check --all
#   lock .......................... pass
#   version-consistency ........... pass
#   config-schema ................. pass
#   license-file .................. pass
#   scaffold-conflicts ............ pass
#   cross-repo-path-sources ....... pass
#   changelog-hashes .............. pass
#   changelog-range ............... pass
#   changelog-coverage ............ FAIL
#     Uncovered commits:
#       a1b2c3d  Add retry logic
#       e4f5g6h  Fix timeout bug
#   changelog-schema .............. pass
#   changelog-user-facing ......... warn  No user-facing entries
#   unpublished-refs ............. fail  v0.5.2: the ref v0.5.2 exists locally but not on origin
#   test-suite ................... pass
#
#   12 passed, 1 failed, 2 warnings

#Investigating a specific check failure

# Run just the failing check to see detailed output
rlsbl check --name changelog-coverage
#   changelog-coverage ............ FAIL
#     Uncovered commits:
#       a1b2c3d  Add retry logic
#       e4f5g6h  Fix timeout bug
#     Fix: run `rlsbl changelog add --commits <hash> ...` for each

# Fix it
rlsbl changelog add --commits a1b2c3d --description "Add retry logic to HTTP client" --type feature
rlsbl changelog add --commits e4f5g6h --description "Fix timeout crash on slow connections" --type fix

# Verify the fix
rlsbl check --name changelog-coverage
#   changelog-coverage ............ pass

#Checking workspace integrity in a monorepo

rlsbl check --tag workspace
#   workspace-ci-router ........... pass
#   workspace-ci-synced ........... pass
#   workspace-targets ............. pass
#   workspace-unregistered ........ FAIL
#     packages/new-lib/ has pyproject.toml but is not in workspace.toml
#   workspace-stale-entries ....... pass
#   dev-only-boundary ............. pass
#   dead-workspace-packages ....... warn  library 'old-utils' not imported by any workspace package
#
#   Fix: run `rlsbl monorepo add packages/new-lib --target pypi --releasable new-lib`

#Pre-push check output

# Triggered automatically by git push, or run manually:
rlsbl check --tag prepush
#   prepush-changelog-coverage .... pass
#   prepush-gitignore-guard ....... pass
#   prepush-manual-warning ........ skip  (not a release branch push)
#   test-suite .................... pass
#   scaffold-conflicts ............ pass