ReleaseKit/docs/roadmap/model.md

# Validation API and profile model

Status: Complete for the agreed v0.2.0 shared validation model. Every selection
and execution path described here is implemented and locally verified; broader
consumer adoption remains in the product roadmap.

This roadmap describes the shared model that enables the optional validation
capabilities in the [v0.2.0 roadmap](v0.2.0.md). It owns their common API,
configuration, execution, and diagnostic design. The release roadmap owns each
capability's purpose and scope. The [implementation plan](implementation.md)
owns the stages and the agreed API rollout.

## Rationale and v0.1.0 baseline

ReleaseKit v0.1.0 exposes `Check` and `Publish` through the root facade. Both
accept `ReleaseRequest` and use shared candidate-validation machinery. Validation
runs the standard offline Go suite, followed by `AdditionalChecks` when supplied.
Selected executable builds follow validation. The CLI maps profile `checks`
commands to the additional-check callback.

This provides a common procedure and a product-specific extension point. The
request and profile have structured selections for race testing, separate full
vet, package compilation, formatting, Markdown, module distribution, and file
size. Publication also supports an expected push endpoint.

The model lets consumers declare their choices once while ReleaseKit owns
execution and coordination. This follows [ADR 0002](../adr/0002-routine-releases.md):
shared capabilities should reduce application code and routine developer
decisions. The facade boundaries in [ADR 0001](../adr/0001-public-facade.md)
provide the existing architectural foundation.

Optional capabilities can serve a small subset of consumers when they remove
application-owned release mechanics and have clear scope, compact configuration,
and proportionate maintenance costs.

## Target end state

### One validation specification

The facade-owned `ValidationSpec` on `ReleaseRequest` has a corresponding
`validation` object in the release profile. Typed Go fields and ordinary JSON
settings express the same supported selections. Related choices, including
base-test and vet settings, are grouped so their relationship is clear.

The specification includes the agreed capabilities in the
[release roadmap](v0.2.0.md), including optional Markdown boundary enforcement,
independent module-distribution rules, and file-size settings. Its zero value
and an omitted profile object preserve current default validation. Consumers
enable optional checks according to their product needs.

Go callers and CLI users receive equivalent validation behavior. The CLI owns
profile parsing and presentation; the facade owns the public types and contracts;
internal implementation owns execution. The [implementation plan](implementation.md)
records the selected field names, representations, and completed rollout.

### Shared coordination

`Check` and `Publish` pass the same specification through one internal validation
path bound to the captured candidate. ReleaseKit constructs the selected Go
commands, manages its shared environment, determines execution order, and
propagates failures and cancellation.

Race selection changes the one base suite invocation. Selecting a separate
full-vet pass automatically omits test-time vet. Package-compilation targets
express compatibility checks independently of executable artifact selection.
Consumers obtain this coordination through their declarations.

Keep the executor straightforward and internal, with ordinary functions for
the selected capabilities. The public model expresses validation choices;
ReleaseKit maintains their execution procedure. Existing candidate rechecks,
offline validation, and source-publication outcomes retain their meaning.

### Candidate-content inspection

File-oriented checks share candidate-file enumeration and inspection where
useful. Their scope is the captured candidate, and inspection remains offline
and read-only. Inspect committed candidate contents and define symlink and
submodule handling explicitly in the shared inspection model. Module-distribution
rules inspect the files being released independently of the environment used
to run Go commands. Markdown boundary
validation operates independently of neighboring checkout contents.

Keep each check's settings together: Markdown validation owns its optional
boundary rule; module-distribution validation owns its independent rule
selections; file-size validation owns its limit and path exclusions. The
[release roadmap](v0.2.0.md) defines the scope and defaults of each capability.

### Clear responsibility boundaries

| Concern | Model owner |
| --- | --- |
| Base tests, full vet, and package compilation | Shared validation specification |
| Formatting, Markdown links, module distribution, and file size | Shared validation specification |
| Product-specific assertions and example checks | Existing `AdditionalChecks` callback and profile `checks` |
| Expected authoritative push destination | Publication settings and endpoint handling |
| Executable package, binary name, and artifact targets | Build declaration |
| Hosted destination and credentials | Delivery settings |

`AdditionalChecks` and profile `checks` remain available for substantive
consumer behavior. Shared capabilities use the validation specification.
Preserve the current behavior of existing declarations as the new options land.

The expected-endpoint feature remains a publication guard, and `Check` remains
local-only. Selecting package-compilation checks leaves a source-only consumer's
deliverable selection unchanged. Tool installation and dependency preparation
remain separate from offline candidate validation.

### Consistent diagnostics

Shared validation failures identify the check and expose useful details to Go
callers. File-oriented checks provide source locations and actionable findings
where applicable, including relevant paths, directives, and measured values.
The CLI presents those details consistently through the ordinary candidate-check
and publication commands.

Use a small facade-owned error model with stable check identity and support for
underlying error causes and cancellation. Preserve `errors.Is` and `errors.As`
behavior across internal conversions and facade wrapping. Exact error types
and diagnostic fields are proposed in the [implementation plan](implementation.md).

Validation failures and publication outcomes have distinct meanings. Existing
publication states continue to describe whether publication was attempted,
confirmed, conflicted, or remains uncertain. The model preserves the existing
failure-stopping behavior of the candidate workflow.

## Implementation

The [implementation plan](implementation.md) records the completed rollout and
verification. The facade and CLI profile expose equivalent selections for the
single test suite, separate full vet, package compilation, formatting, Markdown,
module distribution, file size, and the expected publication endpoint. Shared
execution, ordering, diagnostics, cancellation, and failure stopping are
implemented by the owners described above. The maintained Woodpecker template
and Audita's local wrapper use the module-selected ReleaseKit version; see the
[v0.2.0 roadmap](v0.2.0.md) and [delivery guide](../consumers/delivery.md).

## Adoption evidence

Self-contained integration fixtures evaluate all three known consumer shapes:
Audita's default validation and executable builds; ConfigKit's selected test,
vet, and library compilation checks; and PromptKit's shared validation plus
substantive example assertions. Audita's module-selected CI migration is
committed at `17421bc`; the other consumer migrations remain separate adoption
work.

The model gives each adopting consumer a small declaration and the same routine
release operation. Shared execution and diagnostics cover the agreed v0.2.0
capabilities while product-specific work remains in the existing extension
point.