Document shared validation integration

docs/internal/overview.md

@@ -67,6 +67,8 @@ publication owns endpoint guards, tag creation, push, and recovery around that
 same candidate validation path. `internal/validation.CandidateTree` reads
 committed blobs lazily and resolves local destinations from committed entries;
 it does not consult neighboring files or traverse submodule checkouts.
+See the [shared validation guide](validation.md) for checker, Go command, and
+candidate-file integration mechanics.
 
 ## Capability owners and behavioral evidence
 

docs/internal/validation.md

@@ -0,0 +1,82 @@
+# Shared validation mechanics
+
+`internal/validation` owns reusable checks for one captured candidate.
+`internal/candidate` captures the clean source revision and keeps the
+validation sequence shared by local checking and publication. It calls the
+shared executor, runs product-specific `AdditionalChecks` once, and owns the
+post-validation build callback and local-state recheck. `internal/publish`
+adds its endpoint guards, tag creation, push, and recovery around that same
+candidate path.
+
+The current executor runs the default offline Go suite. Its request carries the
+captured repository directory and commit, output writer, and internal
+settings. `Request.ReadCandidateTree` lets a selected file check request
+candidate contents; the default Go-only path does not enumerate the tree.
+`CandidateTree` gets metadata and bytes from Git objects, reads blob bytes
+lazily, and resolves destinations without consulting the worktree or
+neighboring files.
+
+## Adding a shared check
+
+When an optional check is accepted for implementation:
+
+1. Define its typed Go setting in the root facade and its equivalent CLI-owned
+   JSON field. Specify zero-value and omitted-profile behavior in GoDoc and the
+   configuration reference. Keep future settings in the roadmap until their
+   check is implemented.
+2. Add the corresponding internal setting and explicit conversions. Use the
+   same root request conversion for `Check` and `Publish`, and the shared CLI
+   request conversion for profile-based candidate commands.
+3. Implement a plain check function owned by `internal/validation`. Keep its
+   rule semantics in the capability owner and pass only the captured candidate
+   inputs it needs. A file-oriented check can call `Request.ReadCandidateTree`
+   and read only the blobs it inspects.
+4. Return an internal `*Failure` with the check identity, repository-relative
+   findings, useful locations where available, and the underlying cause. Let
+   the root facade convert those records to its own diagnostic types. Preserve
+   cancellation and process errors through `Unwrap`.
+5. Add the check to the shared executor at the ordering point selected by its
+   capability. Stop on failure. Keep product assertions in `AdditionalChecks`
+   and profile `checks`; keep artifact building in `internal/build`.
+6. Cover observable behavior through both the Go facade and profile path when
+   both are supported. Check default behavior, useful findings, cause
+   preservation, cancellation where relevant, and failure stopping. Reuse the
+   existing local Git and CLI fixtures.
+7. Update only the canonical owners for behavior that has landed: GoDoc for the
+   API, configuration and CLI references for profile behavior, and this
+   inventory for internal ownership. Keep later feature contracts in the
+   product roadmap.
+
+Do not add a public validator registration interface. The public specification
+selects ReleaseKit-owned checks; `AdditionalChecks` remains the extension point
+for product behavior.
+
+## Prospective Go command recipe
+
+The complete planned procedure uses one test invocation. Race selection
+modifies that command. When a separate full vet pass is selected, run tests with
+vet disabled and then run native `go vet`. Selected package-compilation targets
+run after test and vet with the static Go environment, including
+`CGO_ENABLED=0`. Keep these compatibility checks independent of executable
+artifact declarations. These selections become operational as their checkers
+are implemented.
+
+Reuse `internal/gotool` for native and static environments and target handling.
+Keep toolchain and module-cache discovery in `gotool`; do not reproduce its
+environment logic in a checker. Build output names, version injection, native
+smoke checks, and artifact digests remain owned by `internal/build`.
+
+## File-check coordination
+
+File checks consume the captured tree and return findings to the shared error
+model. They do not read sibling worktrees or follow live symlink targets.
+`CandidateTree.ResolveDestination` returns data describing entries,
+directories, missing paths, checkout boundaries, submodule paths, and symlink
+cycles; the caller selects which observations fail validation or are reported
+as out of scope.
+
+The Markdown capability will use PromptKit's current parser and anchor
+conventions as its starting evidence. Supported link syntax, anchors,
+diagnostics, and boundary policy belong to that feature's roadmap and
+implementation prompt. This foundation provides only the committed-file and
+destination-resolution primitives.