# ADR 0003: Declare optional validation through a shared specification

## Status

Accepted.

## Date

2026-10-07

## Context

Consumers have different release-validation needs. Their additional checks
include reusable mechanics such as formatting inspection and Go toolchain
invocations, alongside assertions about product behavior. Maintaining the
reusable mechanics in each application duplicates code and coordination work.

[ADR 0001](0001-public-facade.md) establishes facade ownership of public
contracts. [ADR 0002](0002-routine-releases.md) prioritizes routine releases
with little application-owned code or recurring developer effort. Optional
validation needs a common selection and execution model that supports these
decisions as shared capabilities grow.

## Decision

Consumers select shared validation through a typed, facade-owned specification
and equivalent release-profile settings. Related settings belong together.
Omitted optional settings preserve existing default validation behavior.

`Check` and `Publish` use one internal validation path bound to the captured
candidate. ReleaseKit owns execution, ordering, coordination between selected
checks, and propagation of failures and cancellation. The CLI maps profile
settings to the facade and owns presentation.

Shared validation exposes consistent diagnostics through facade-owned errors.
Findings identify the check and provide actionable detail where applicable.
Error wrapping preserves underlying causes and cancellation semantics.
Validation failures and publication outcomes retain their distinct meanings.

The existing `AdditionalChecks` callback and profile `checks` support
product-specific assertions. Publication guards, artifact builds, and delivery
retain their separate configuration and responsibilities. Validation execution
and coordination remain internal implementation responsibilities.

Evaluate optional capabilities by the application maintenance they remove,
their clarity of scope, configuration burden, and maintenance cost. A
capability can serve a small subset of consumers when those benefits justify
shared support. Consumers select the checks appropriate to their products.

GoDoc owns exact public API contracts, and the configuration reference owns
profile settings. Roadmaps own feature scope and implementation sequencing.

## Alternatives considered

- Consumer-owned commands preserve local control and leave applications
  maintaining reusable inspection, invocation, and coordination code.
- Independently configured check and publication paths allow separate
  validation choices and require consumers to keep those choices aligned.
- A public validator-registration framework supports custom composition and
  expands the public lifecycle and ordering contracts. The existing
  additional-check extension point supports current product-specific needs.

## Consequences

Applications can replace repeated release mechanics with small declarations.
Go callers and CLI users receive equivalent selected validation through the
same release operations. Existing consumers retain their default behavior and
additional-check integration as optional capabilities are introduced.

ReleaseKit assumes responsibility for maintaining shared checks, coordinating
their interactions, and presenting useful diagnostics. Public selections and
error contracts carry compatibility obligations. Verification must cover
default behavior, equivalent API and profile selections, and failure propagation.

Internal execution can evolve within the facade boundaries. Each new capability
requires a clear scope and evidence that shared ownership reduces consumer work.