#Check system

rlsbl includes 76 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.

#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

#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 (14 checks: library-lint, test-suite, dev-overlay-drift, maven-central-metadata, wrapper-producer, strictspec-certificate-gate, stricttest-floor, dep-floors, 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. Release checks form a dependency chain: version-consistency -> local-tag -> remote-tag -> github-release. If an upstream check fails, downstream checks are skipped.

#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.

#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:

#Target applicability

Not all checks apply to all 18 targets. 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: local-tag runs git tag --list, and config-schema can reach go list on its error path. All eleven 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
#   local-tag .................... warn  No tag for v0.5.3
#   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 --path packages/new-lib --target pypi`

#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