Check committed Markdown destinations

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 and per-document anchor caching, structured failures, and lazy committed-file access for captured candidates; `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, internal Markdown parsing, destination and fragment checking, and per-document anchor caching; `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. |
@@ -79,7 +79,7 @@ not a separate release matrix:
 | --- | --- | --- |
 | 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 syntax records, source use sites, heading anchors, and candidate-document cache | `internal/validation` | `TestParseMarkdownLinksAndSourceLocations`, `TestParseMarkdownDecodesEntitiesInDestinations`, `TestParseMarkdownHeadingAnchors`, `TestMarkdownCacheKeepsParsedDocumentsPerCandidatePath` |
+| Internal Markdown parsing, committed destinations, fragments, boundary observations, and causes | `internal/validation` | `TestParseMarkdownLinksAndSourceLocations`, `TestParseMarkdownDecodesEntitiesInDestinations`, `TestParseMarkdownHeadingAnchors`, `TestMarkdownCacheKeepsParsedDocumentsPerCandidatePath`, `TestCheckMarkdownLinksResolvesCommittedDestinationsAndFragments`, `TestCheckMarkdownLinksReportsMissingPathsAnchorsAndCycles`, `TestCheckMarkdownLinksUsesResolvedMarkdownIdentity`, `TestCheckMarkdownLinksReportsBoundaryAndSubmoduleObservations`, `TestCheckMarkdownLinksPreservesResolverCauseAndCancellation`, `TestCheckMarkdownLinksPreservesAnchorReadCause` |
 | 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

@@ -50,9 +50,19 @@ 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 the parsed records and anchors for each candidate
-document. The parser remains internal; destination resolution and check selection
-are tracked in the [implementation plan](../roadmap/implementation.md).
+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 remains
+in the [implementation plan](../roadmap/implementation.md).
 
 Committed-tree metadata and blob reads disable lazy fetching and Git transports
 for those child commands. Missing local objects produce inspection errors;
@@ -126,6 +136,6 @@ 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) owns Markdown
-destination checking, diagnostics, and boundary policy. The committed-file and
-destination-resolution primitives are available for that later integration.
+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.

docs/roadmap/implementation.md

@@ -200,9 +200,10 @@ the parser. Code blocks and inline code supply examples rather than link nodes.
 Raw HTML destinations remain outside this Markdown-link capability. Undefined
 references rendered as ordinary text by the parser are not a new Markdown lint
 rule. Decode Markdown escapes/entities through the parser and percent escapes
-once when resolving URI path/fragment components. Ignore URI query components
-for file existence. Empty paths target the source document; an empty fragment
-selects its top. Schemed and protocol-relative URIs receive no availability
+once when resolving URI path/fragment components. Compare decoded fragments in
+lowercase to preserve PromptKit's starting convention. Ignore URI query
+components for file existence. Empty paths target the source document; an empty
+fragment selects its top. Schemed and protocol-relative URIs receive no availability
 request. Fragment checking applies to regular Markdown destinations; other
 existing files/directories receive existence checking.
 
@@ -443,6 +444,11 @@ Undefined references and HTML prose remain governed by parser interpretation.
 
 ## Stage 10: Implement internal destination and fragment checking
 
+**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.
+
 **Outcome:** Committed Markdown navigation is checked with boundary observations.
 
 1. Resolve parsed local URI components through `CandidateTree.ResolveDestination`.
@@ -456,6 +462,10 @@ Undefined references and HTML prose remain governed by parser interpretation.
 4. Reuse remediated symlink/cancellation/local-object behavior. Keep parsing,
    resolution, and rule evaluation in ordinary internal functions.
 
+**Resolution refinement:** URI query components do not participate in path
+checking. Compare fragments after one percent-decoding pass and lowercase them
+to preserve PromptKit's starting anchor matching.
+
 **Verification:** Valid/missing files and anchors, same-document/empty fragments,
 percent-escaped paths and fragments, query strings, directories and non-Markdown
 files, outside links with both settings, and submodule observations. Check how