# 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 executor runs one offline Go suite, optionally with the race detector when selected. When full vet is selected, it disables test-time vet for that suite and runs native `go vet -mod=readonly ./...` after the suite succeeds. It then runs `go build -mod=readonly -o ./...` in static mode for each selected package-compilation target, preserving target order and stopping on the first failure. This compiles source without producing an artifact or executing a target binary. Test, vet, and package-compilation failures retain their `go-test`, `go-vet`, and `package-compile` identities, selected target where applicable, and underlying causes. Its request carries the captured repository directory and commit, output writer, and internal settings. When selected, the Go-format check loads the candidate tree once, reads regular Go blobs from the captured commit, and compares them with go/format output. It includes vendor and nested-module files, skips symlink blobs, reports all unformatted paths, and stops with a contextual cause on parse or inspection errors. It runs before product checks and build callbacks. `Request.ReadCandidateTree` lets selected file checks request candidate contents; the Go-only path does not enumerate the tree. The workspace-file check uses that same candidate inventory and reports blob entries named go.work or go.work.sum, including nested paths and symlink blobs. It does not read workspace contents or depend on the workspace selected for Go commands. The local-replacement check parses every committed go.mod blob with `golang.org/x/mod/modfile`, including nested modules and vendor declarations. It follows committed symlink declarations through the captured tree and fails with an inspection cause when their selected contents are unavailable. A replacement with no parsed version is reported with its go.mod path, line, directive, and target; versioned replacements are allowed. It runs after the workspace-file check using the same candidate inventory. The optional file-size check uses each blob's captured Git size, including symlink link-text bytes, and skips entries without a blob size such as gitlinks. It applies normalized literal file/directory exclusions with path-boundary matching, then returns the first oversized path with `FileSizeMeasurement`. The optional Markdown check follows file-size inspection and uses the same candidate tree. It parses regular Markdown blobs, resolves local destinations, and checks supported anchors; outside-checkout and submodule observations are written to the shared output writer. A nil writer keeps library use quiet. `CandidateTree` gets metadata and bytes from Git objects, reads blob bytes lazily, and resolves destinations without consulting the worktree or neighboring files. The internal Markdown parser uses Goldmark to record inline, reference, and autolinks, images, titles, and their source use sites, and to build heading anchors from visible AST text. It supports ATX and Setext headings, decodes Markdown text through the parser, and assigns collision-free numeric suffixes to repeated anchors. Link locations use one-based line and byte-column values. A per-path cache retains parsed records and anchors for candidate documents. `checkMarkdownLinks` examines regular `.md` blobs from the captured tree. It skips schemed and protocol-relative URIs, strips query components, and decodes percent escapes once in local paths and fragments. It resolves destinations through `CandidateTree.ResolveDestination`; decoded fragments are compared in lowercase against anchors from the resolved regular Markdown document. Missing paths, symlink cycles, and missing anchors produce `markdown-links` findings at the source use site. Outside-checkout links produce out-of-scope observations by default and findings when boundary enforcement is selected. Submodule-content observations remain out of scope under either setting. Observations go to the provided writer; a nil writer keeps library use quiet. Public selection is defined in the [configuration reference](../config.md) and GoDoc. Committed-tree metadata and blob reads disable lazy fetching and Git transports for those child commands. Missing local objects produce inspection errors; source preparation retains its separate network-capable operations. See Git's [lazy-fetch controls](https://git-scm.com/docs/git) for the command mechanism. Public validation errors convert their diagnostic fields to the internal failure model for shared formatting. Converted failures retain their original contextual cause and reuse its rendering when it already contains the same diagnostics. The CLI presents the complete error chain, including candidate context around callback-supplied diagnostics. ## 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. ## Go command environment reuse The current executor uses the [shared Go command environment](gotool.md) for its offline suite, vet pass, and selected-target package compilation. 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. Artifact 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. Resolution walks committed components and symlink targets in order. Active symlink expansion detects cycles, and traversal honors cancellation. Absolute destinations and symlink targets within the repository directory map back to candidate-relative paths; existence still comes from committed entries. The public selection is owned by the facade and profile; the internal checker uses the committed-file and destination-resolution primitives described here.