Expose Markdown validation selection

docs/cli.md

@@ -44,6 +44,14 @@ modifying files. When `validation.module_distribution.workspace_files` is true,
 and symlink entries, as `workspace-files`. This inspection is independent of
 `GOWORK` and ignores uncommitted files. Any artifact build selected by the
 separate `build` setting runs after shared validation and configured checks.
+When `validation.markdown` is a non-null object, `check` checks committed local
+Markdown destinations and supported heading fragments after file-size
+inspection. An empty object enables the check; omission or `null` disables it.
+Outside-checkout links are written as out-of-scope observations to standard
+error by default. Setting `validation.markdown.enforce_checkout_boundary` to
+true makes those links fail; submodule-content observations remain
+nonfailures. Failures use the `markdown-links` identity with the source location
+and target.
 
 `check` writes errors and diagnostics to standard error. It returns status 0
 after local validation, 1 after a candidate validation failure, and 2 for usage,
@@ -64,8 +72,9 @@ candidate: the single standard offline Go test suite runs first, with `-race`
 when `validation.go.race` is true. When `validation.go.full_vet` is true,
 test-time vet is disabled and `go vet -mod=readonly ./...` runs after successful
 tests. Selected package compilation and committed Go formatting follow. The
-selected workspace-file check then runs, followed by configured checks in
-profile order. It then creates an annotated local tag
+selected file checks then run in order: workspace files, local replacements,
+file size, and Markdown. Configured checks run afterward in profile order. It
+then creates an annotated local tag
 and pushes only its exact tag object. It prints the confirmed version,
 candidate commit, and tag object
 on success. Validation
@@ -97,6 +106,11 @@ disables the check; an empty object enables the 1,000,000 decimal-byte default.
 Oversized files use the `file-size` identity and report their path and measured
 size against the limit. See the [configuration reference](config.md) for
 literal exclusions and the current-candidate scope.
+When `validation.markdown` is a non-null object, `publish` checks committed
+Markdown destinations after file-size inspection and before configured checks.
+It reports outside-checkout links to standard error unless boundary enforcement
+is selected; submodule contents remain out of scope. Markdown failures stop
+publication before product checks or tag creation.
 
 The optional profile field `expected_push_url` applies only to `publish`. A
 nonempty value must exactly match the effective push URL resolved by Git;

docs/config.md

@@ -46,6 +46,26 @@ change under formatting. It never writes formatted bytes back. Omitted or false
 disables the check. It runs after tests, selected full vet, and selected package
 compilation, before configured product checks.
 
+When `validation.markdown` is an object, ReleaseKit checks local destinations
+and supported heading fragments in committed regular Markdown files. Omission
+or `null` disables the check; `{}` enables it. Schemed and protocol-relative
+links are skipped, URI query components do not affect path checks, and other
+existing files or directories receive existence checks only. Missing local
+destinations, symlink cycles, and missing Markdown headings fail with the
+`markdown-links` identity. Outside-checkout destinations are reported as out
+of scope by default. Set
+`validation.markdown.enforce_checkout_boundary` to `true` to fail those links;
+submodule contents remain out of scope under either setting.
+
+The parser recognizes inline links, images, reference links, and CommonMark
+autolinks; link-like text in code is ignored, and raw HTML destinations are
+outside this check. Relative paths resolve from the source document in the
+captured commit. Query components are ignored for file existence, and percent
+escapes in local paths and fragments are decoded once. Fragments are compared
+in lowercase with anchors derived from visible ATX or Setext heading text.
+Anchors keep Unicode letters and numbers, underscores, and hyphens; spaces
+become hyphens, and repeated headings receive numeric suffixes.
+
 When `validation.module_distribution.workspace_files` is true, it reports
 committed blob entries whose basename is `go.work` or `go.work.sum`, including
 nested paths and symlinks. It checks candidate distribution contents regardless
@@ -71,6 +91,7 @@ For example:
       "compile_targets": ["linux/amd64", "linux/arm64"]
     },
     "go_format": true,
+    "markdown": {},
     "module_distribution": {
       "workspace_files": true,
       "local_replacements": true
@@ -130,6 +151,10 @@ preserve their causes.
 When `validation.file_size` is selected, shared validation checks committed
 blob sizes after module-distribution checks and reports the first oversized
 path with the `file-size` identity and measured and limit byte counts.
+When `validation.markdown` is selected, Markdown checking follows file-size
+inspection and runs before configured product checks. Out-of-scope observations
+are written to the command's standard error and do not fail validation unless
+the checkout boundary is enforced. Submodule observations remain nonfailures.
 Configured `checks` commands run afterward, once each in order, as additional
 product checks. Artifact builds selected by the separate `build` setting run
 after shared validation and product checks.

docs/consumers/check.md

@@ -62,6 +62,20 @@ directories; excluded directories include descendants. Symlink blobs are
 measured by link-text bytes, and gitlinks are omitted. The check applies to the
 captured candidate and reports one oversized file with its measurement as
 `file-size`; it does not measure historical or aggregate size.
+Set `Validation.Markdown` to check committed local Markdown destinations and
+supported heading fragments. Nil disables the check; an empty object enables
+it with outside-checkout destinations reported as out of scope. Set
+`EnforceCheckoutBoundary` to fail outside-checkout links. Submodule contents
+remain out of scope under either setting. The checker runs after file-size
+inspection and before `AdditionalChecks`; its nonfailure observations use the
+request's output writer. Markdown failures use the `markdown-links` identity
+and include the source location and destination.
+
+Use these selections for ReleaseKit-owned validation rather than repeating the
+standard suite, selected vet/format/distribution checks, or Markdown navigation
+checks in `AdditionalChecks` or profile `checks`. Keep release-note rules and
+consumer-specific assertions—such as tests of maintained examples—in those
+product-owned checks.
 ReleaseKit calls `AdditionalChecks` once after shared validation when supplied.
 It does not download a different toolchain automatically. If race prerequisites
 are unavailable, the `go-test` check fails rather than being skipped; a selected

docs/consumers/publish.md

@@ -78,6 +78,19 @@ blob size is its link text; gitlinks are omitted. This check measures only the
 captured candidate and reports one oversized file with its measurement as
 `file-size`; it stops publication before product checks or tag creation.
 
+Set `Validation.Markdown` to check committed local Markdown destinations and
+supported heading fragments during publication. Nil disables the check; an
+empty object enables it with outside-checkout links reported as out of scope.
+Set `EnforceCheckoutBoundary` to fail those links. Submodule contents remain
+out of scope under either setting. Observations use the request's output writer;
+failures use `markdown-links` and stop publication before product checks or tag
+creation.
+
+ReleaseKit-owned selections replace duplicate generic suite, vet, formatting,
+distribution, and Markdown checks in configured product checks. Keep
+release-note rules and consumer-specific assertions, such as maintained-example
+tests, in `AdditionalChecks` or profile `checks`.
+
 If `Build` selects targets, ReleaseKit verifies them after the standard suite
 and additional checks, before creating the tag. The operation then rechecks the
 candidate and remote guards, creates an annotated tag for the captured commit,

docs/internal/overview.md

@@ -46,7 +46,7 @@ reports these implemented packages:
 | `internal/tempdir` | Disposable system temporary storage outside source worktrees. |
 | `internal/process` | Cancellable child-process execution with per-command environment overlays and removals. |
 | `internal/preparation` | Coordination for expected-commit tag checkout and Go module dependency preparation. |
-| `internal/validation` | Shared Go validation with optional race, full-vet, and static package-compilation target selections, formatting, workspace-file and filesystem-replacement checks, per-blob size limits, internal Markdown parsing, destination and fragment checking, and per-document anchor caching; `internal/candidate` retains capture, callback sequencing, and local-state rechecks. |
+| `internal/validation` | Shared Go validation with optional race, full-vet, and static package-compilation target selections, formatting, workspace-file and filesystem-replacement checks, per-blob size limits, and selected Markdown destination and fragment checking; `internal/candidate` retains capture, callback sequencing, and local-state rechecks. |
 | `internal/publish` | Publication guards, one validation run, annotated tag creation, push, and recovery state. |
 | `internal/runtimeinfo` | Private version lookup used by the runtime facade. |
 | `internal/versioncontract` | Shared stable-version rules and linker-symbol identity. |
@@ -78,8 +78,8 @@ not a separate release matrix:
 | Capability | Implementation owner | Existing evidence |
 | --- | --- | --- |
 | Runtime version lookup and injected application version | `buildinfo`, `internal/runtimeinfo`, `internal/versioncontract`, `internal/build` | `TestVersionInConsumerExecutable`, `TestVersion` |
-| Candidate capture, shared validation, public diagnostics, additional checks, and rechecks | `releasekit.Check`, `releasekit.Publish`, `internal/candidate`, `internal/validation`, `cmd/releasekit/internal/cli` | `TestRunUsesOneSuiteWithSelectedRaceSetting`, `TestRunReportsRacePrerequisiteFailureWithoutFallback`, `TestRunExecutesRaceEnabledSuiteOnHost`, `TestRunCompilesTargetsAfterTestAndVetInSelectionOrder`, `TestRunAttributesTargetCompileFailureAndStops`, `TestRunCompilesSourceOnlyAndExecutablePackagesWithoutArtifacts`, `TestCandidateRequestMapsGoValidation`, `TestLoadSettingsReadsGoValidation`, `TestCheckUsesSelectedRaceSuiteBeforeAdditionalChecks`, `TestCheckCapturesCandidateAndCallsAdditionalChecksOnce`, `TestCheckReturnsPublicValidationError`, `TestPublishPushesOnlyTheCapturedAnnotatedTag`, `TestPublishFailedStandardSuiteSkipsAdditionalChecksAndTagCreation`, `TestPublishAdditionalCheckFailurePreservesCauseAndPreventsTagCreation`, `TestCheckCommandBindsConfiguredChecksToCapturedCandidate`, `TestPublishCommandPublishesConfiguredCandidate`, `TestCandidateCommandsPresentValidationDiagnosticsOnce`, `TestDeliverPageOnlyCreatesAndReusesRelease` |
-| Internal Markdown parsing, committed destinations, fragments, boundary observations, and causes | `internal/validation` | `TestParseMarkdownLinksAndSourceLocations`, `TestParseMarkdownDecodesEntitiesInDestinations`, `TestParseMarkdownHeadingAnchors`, `TestMarkdownCacheKeepsParsedDocumentsPerCandidatePath`, `TestCheckMarkdownLinksResolvesCommittedDestinationsAndFragments`, `TestCheckMarkdownLinksReportsMissingPathsAnchorsAndCycles`, `TestCheckMarkdownLinksUsesResolvedMarkdownIdentity`, `TestCheckMarkdownLinksReportsBoundaryAndSubmoduleObservations`, `TestCheckMarkdownLinksPreservesResolverCauseAndCancellation`, `TestCheckMarkdownLinksPreservesAnchorReadCause` |
+| Candidate capture, shared validation, public diagnostics, additional checks, and rechecks | `releasekit.Check`, `releasekit.Publish`, `internal/candidate`, `internal/validation`, `cmd/releasekit/internal/cli` | `TestRunUsesOneSuiteWithSelectedRaceSetting`, `TestRunReportsRacePrerequisiteFailureWithoutFallback`, `TestRunExecutesRaceEnabledSuiteOnHost`, `TestRunCompilesTargetsAfterTestAndVetInSelectionOrder`, `TestRunAttributesTargetCompileFailureAndStops`, `TestRunCompilesSourceOnlyAndExecutablePackagesWithoutArtifacts`, `TestCandidateRequestMapsGoValidation`, `TestCandidateRequestPreservesMarkdownObjectSelection`, `TestLoadSettingsReadsGoValidation`, `TestLoadSettingsPreservesMarkdownObjectSelection`, `TestCheckUsesSelectedRaceSuiteBeforeAdditionalChecks`, `TestCheckCapturesCandidateAndCallsAdditionalChecksOnce`, `TestCheckReturnsPublicValidationError`, `TestMarkdownValidationRunsThroughCheckAndPublish`, `TestCheckStopsBeforeProductAndBuildCallbacksWhenMarkdownBoundaryFails`, `TestCheckCommandBindsConfiguredChecksToCapturedCandidate`, `TestPublishCommandPublishesConfiguredCandidate`, `TestCandidateCommandsPresentValidationDiagnosticsOnce`, `TestDeliverPageOnlyCreatesAndReusesRelease` |
+| Internal Markdown parsing, committed destinations, fragments, boundary observations, and public selection | `releasekit.Check`, `releasekit.Publish`, `internal/candidate`, `internal/validation`, `cmd/releasekit/internal/cli` | `TestParseMarkdownLinksAndSourceLocations`, `TestParseMarkdownDecodesEntitiesInDestinations`, `TestParseMarkdownHeadingAnchors`, `TestMarkdownCacheKeepsParsedDocumentsPerCandidatePath`, `TestCheckMarkdownLinksResolvesCommittedDestinationsAndFragments`, `TestCheckMarkdownLinksReportsMissingPathsAnchorsAndCycles`, `TestCheckMarkdownLinksUsesResolvedMarkdownIdentity`, `TestCheckMarkdownLinksReportsBoundaryAndSubmoduleObservations`, `TestCheckMarkdownLinksPreservesResolverCauseAndCancellation`, `TestCheckMarkdownLinksPreservesAnchorReadCause`, `TestRunSelectsMarkdownWithCombinedGoChecksAndReportsOutOfScopeLinks`, `TestMarkdownValidationRunsThroughCheckAndPublish`, `TestLoadSettingsPreservesMarkdownObjectSelection`, `TestValidationSpecPreservesMarkdownObjectSelection` |
 | Shared Go settings for validation and builds | `internal/gotool`, `internal/process`, `internal/candidate`, `internal/build` | `TestDefaultValidationDoesNotInheritGOFLAGSRunFilter`, `TestNativeAndStaticCommandsUseOwnedBaseline`, `TestPersistentSettingsPreserveCachesAndNativeCTools`, `TestBuildIgnoresAmbientAndPersistentArchitectureTuning` |
 | Authoritative endpoint and exact annotated tag publication | `releasekit.Publish`, `internal/publish`, `internal/git` | `TestPublishPushesOnlyTheCapturedAnnotatedTag`, `TestPublishRejectsUnexpectedPushURLBeforeValidation`, `TestPublishComparesExpectedURLWithResolvedInsteadOfDestination`, `TestPublishExpectedPushURLUsesPushURLWhenFetchAndPushDiffer`, `TestCheckIgnoresExpectedPushURL`, `TestResolveUsesPushURLAndQueriesWithoutMutation` |
 | Publication partial and uncertain recovery | `internal/publish`, `internal/git` | `TestPublishRejectedPushKeepsLocalTagAndReportsNotPublished`, `TestPublishLostAcknowledgmentConfirmsExactRemoteObject`, `TestPublishLostAcknowledgmentWithChangedEndpointRemainsUnknown`, `TestPublishUnavailableReconciliationRemainsUnknownAndPreservesPushError` |

docs/internal/validation.md

@@ -41,6 +41,10 @@ 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.
@@ -61,8 +65,8 @@ 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 remains
-in the [implementation plan](../roadmap/implementation.md).
+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;
@@ -136,6 +140,7 @@ 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 [implementation plan](../roadmap/implementation.md) records the remaining
-public Markdown selection and integration work. The internal checker uses the
-committed-file and destination-resolution primitives described here.
+The [implementation plan](../roadmap/implementation.md) records the completed
+Markdown integration. The public selection is owned by the facade and profile;
+the internal checker uses the committed-file and destination-resolution
+primitives described here.

docs/roadmap/implementation.md

@@ -446,8 +446,8 @@ Undefined references and HTML prose remain governed by parser interpretation.
 
 **Completion:** Complete. The internal checker resolves committed destinations,
 checks supported fragments, preserves inspection errors, and reports distinct
-outside-checkout and submodule observations. Public selection and shared executor
-wiring remain in Stage 11.
+outside-checkout and submodule observations. Stage 11 exposes this checker
+through public and profile selections and the shared executor.
 
 **Outcome:** Committed Markdown navigation is checked with boundary observations.
 
@@ -477,6 +477,14 @@ missing-object, and traversal-cancellation cases.
 
 ## Stage 11: Expose Markdown selection and complete validation integration
 
+**Completion:** Complete. `ValidationSpec.Markdown` and
+`validation.markdown` select the shared committed-link checker through both
+public operations and CLI profile commands. Omitted/null settings disable the
+check; an empty object enables it, and the boundary option maps explicitly.
+Warnings use the shared output writer, while Markdown failures stop product
+checks and builds. GoDoc, profile, consumer, CLI, and internal documentation
+now describe the operational behavior.
+
 **Outcome:** All agreed validation selections work through both public operations.
 
 1. Add `MarkdownValidationSpec`, `ValidationSpec.Markdown`, and their JSON fields.