Outline the shared validation model for v0.2.0

docs/roadmap/model.md

@@ -0,0 +1,131 @@
+# Validation API and profile model
+
+Status: Agreed direction for v0.2.0; detailed API design and implementation
+planning remain to be completed.
+
+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. A staged implementation plan will follow the
+finalized release scope.
+
+## Rationale and current 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 currently have no structured selection for shared optional
+validation. Race testing, full vet, package compilation, formatting, and
+Markdown checks need a coherent home as they are added.
+
+The model should let 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.
+
+## Target end state
+
+### One validation specification
+
+Add a facade-owned `ValidationSpec` to `ReleaseRequest`, with a corresponding
+`validation` object in the release profile. Use typed Go fields and ordinary
+JSON settings to express the same supported selections. Group related choices,
+including base-test and vet settings, so their relationship is clear.
+
+The specification accommodates the agreed race, full-vet, package-compilation,
+Go-formatting, and Markdown-link capabilities. 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. Exact field names and representations
+will be settled together during implementation planning.
+
+### 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.
+
+### Clear responsibility boundaries
+
+| Concern | Model owner |
+| --- | --- |
+| Base tests, full vet, package compilation, formatting, and Markdown links | 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. 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 will be selected for the agreed capabilities during API
+design.
+
+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.
+
+## Work needed
+
+- Design the Go validation specification and profile representation together,
+  covering defaults, related selections, and their mapping to shared execution.
+- Consolidate request conversion and validation coordination where needed so
+  `Check`, `Publish`, and their CLI forms use the same decisions.
+- Define check identity, useful diagnostic detail, error wrapping, and CLI
+  presentation as one small model for the accepted capabilities.
+- Preserve the additional-check extension point and the separate publication,
+  build, and delivery responsibilities while integrating the new specification.
+- Update GoDoc, configuration and CLI references, consumer examples, and
+  internal guidance as the model is implemented. Explain any migration needed
+  for existing additional commands that become shared selections.
+- Verify unchanged default behavior, equivalent API/profile selections, one
+  base suite execution, coordinated test/vet behavior, and failure/cancellation
+  propagation. Individual feature work supplies its own behavioral coverage.
+
+## Adoption evidence
+
+Evaluate the design against 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.
+
+Completion should give each consumer a small declaration and the same routine
+release operation. The model should support the agreed v0.2.0 capabilities with
+shared execution and clear diagnostics while keeping product-specific work in
+the existing extension point.

docs/roadmap/v0.2.0.md

@@ -10,7 +10,39 @@ The priorities in [ADR 0002](../adr/0002-routine-releases.md) guide this work:
 minimize application-owned release code, duplicated mechanics, and routine
 developer decisions through a standard, minimal API.
 
-## 1. Use the application's module-selected ReleaseKit version in CI
+## 1. Establish the shared validation API and profile model
+
+### Rationale and current baseline
+
+ReleaseKit has a shared candidate workflow and a product-specific additional
+check extension point. The optional validation capabilities planned for v0.2.0
+need a coherent selection and diagnostic model across the Go API and profile.
+
+The [validation-model roadmap](model.md) records this enabling work and its
+rationale. A common model lets consumers declare choices once and receive
+ReleaseKit's shared execution and coordination.
+
+### Target end state
+
+A facade-owned validation specification and corresponding profile object
+express the agreed optional checks with consistent defaults and behavior.
+ReleaseKit owns coordination and diagnostics through the existing `Check` and
+`Publish` operations. Product-specific checks, publication expectations,
+artifact builds, and delivery retain their distinct responsibilities.
+
+### Work needed
+
+- Design and integrate the shared specification, profile mapping, execution,
+  and error model described in [model.md](model.md).
+- Preserve existing default behavior and additional-check support, and align
+  GoDoc, profile guidance, and CLI reporting as the model lands.
+- Evaluate the model against Audita, ConfigKit, and PromptKit before finalizing
+  the interfaces used by the individual validation features.
+
+Completion should provide a common foundation for the validation capabilities
+below, with small consumer declarations and reusable execution.
+
+## 2. Use the application's module-selected ReleaseKit version in CI
 
 ### Rationale and current baseline
 
@@ -63,7 +95,7 @@ installed tool remain supported use cases.
 Completion should leave downstream maintainers with one ReleaseKit dependency
 update for this integration and a maintained template they can adopt directly.
 
-## 2. Select one base test invocation, including race testing
+## 3. Select one base test invocation, including race testing
 
 ### Rationale and current baseline
 
@@ -100,7 +132,7 @@ unavailable prerequisites clearly and preserves the selected validation.
 Completion should let ConfigKit and PromptKit select a race-enabled suite once
 and remove the corresponding consumer-owned test invocation.
 
-## 3. Offer a separate full vet pass
+## 4. Offer a separate full vet pass
 
 ### Rationale and current baseline
 
@@ -130,7 +162,7 @@ ReleaseKit owns the offline command and its coordination with base testing.
 Completion should replace ConfigKit's and PromptKit's separate vet commands and
 manual test-time vet settings with one declarative choice.
 
-## 4. Verify package compilation for selected targets
+## 5. Verify package compilation for selected targets
 
 ### Rationale and current baseline
 
@@ -165,7 +197,7 @@ separate concern. Consumers select targets for their support commitments.
 Completion should let ConfigKit declare its two Linux targets and remove its
 release-specific compilation loop.
 
-## 5. Check an optional expected publication endpoint
+## 6. Check an optional expected publication endpoint
 
 ### Rationale and current baseline
 
@@ -198,7 +230,7 @@ Consumers that omit the expectation keep the current remote-selection model.
 Completion should let consumers declare the intended push destination without
 maintaining their own publication preflight logic.
 
-## 6. Offer Go formatting validation
+## 7. Offer Go formatting validation
 
 ### Rationale and current baseline
 
@@ -230,7 +262,7 @@ unchanged when the option is unset.
 Completion should let PromptKit remove its local formatting loop and select
 the shared check through its release profile.
 
-## 7. Offer offline Markdown-link validation
+## 8. Offer offline Markdown-link validation
 
 ### Rationale and current baseline