configkit/docs/roadmap/documentation.md

Documentation Consistency Audit

Reviewed revision: b4477a236aa01e60c17ee353bccaebca7ce919d7.

This audit compares current documentation with the implementation, maintained examples, tests, and architectural decisions. It records proposed corrections; it does not change the public contract or implement the corrections.

1. Discovery reference names a removed public constructor

Documentation: Configuration discovery, line 34, tells consumers to construct a search from literal Paths.

Discrepancy: The public constructor is now SearchPaths, declared in discovery.go, lines 55–56. There is no public Paths compatibility alias. The private engine retains that name, but consumers cannot use it through the supported public package. The same reference section already uses SearchPaths() when explaining empty searches, and the migration table correctly records the rename.

Impact: A consumer following the introductory instruction can attempt to call an unavailable public API. This is a documentation defect, not a missing API.

Potential remediation: Change the introductory constructor name to SearchPaths. Preserve the historical old-name entry in the migration table and the private engine name; neither needs changing for this finding.

2. Four focused-test instructions are truncated in rendered documentation

Documentation: The development test map, lines 276, 277, 283, and 290, contains these affected rows:

• Explicit main-file discovery and absent-input loading.
• Import defaults, empty-selection evidence, and dependency-ready ordering.
• Input and relative-import destinations, mounted sources, and source ownership.
• Effective configuration diff.

Discrepancy: These rows put unescaped regex alternation pipes inside inline code in Markdown table cells. GitHub-flavored Markdown treats those pipes as cell separators even inside backticks. The table has three columns, so the remainder of each instruction falls outside the displayed command cell. For example, the discovery command renders as the incomplete text `go test ./internal/engine -run 'Discovery rather than the complete command and its two companion commands.

The intended Go regexes are valid: | separates alternatives. Rendering the current guide with the already module-selected Goldmark v2.1.6 GFM parser and renderer reproduced all four truncated cells. Neighboring older rows escape their pipes and render complete commands. Existing tests referenced by these instructions run successfully in the complete suite; their implementation is not the problem.

Impact: Readers of the rendered contributor guide lose the complete test selection instructions and can copy an unterminated shell command. The existing documentation-link check does not validate rendered table cells.

Potential remediation: Escape the table pipes consistently with adjacent rows, or move the affected commands into fenced blocks outside the table. Inspect the rendered result and execute the resulting shell commands with ordinary regex alternation. Markdown escaping should not introduce literal escaped pipes into the command users copy. No new release gate or production change is needed.

Review Coverage and Validation

Reviewed the root README and package/API documentation, the configuration reference, consumer guide and executable examples, development instructions, internal component/import documentation, and release procedure against their corresponding implementation and tests. Checked module identity, declared Go and ReleaseKit versions, release-profile wiring, and licensing/attribution navigation. No additional actionable discrepancy was identified in those areas. This was not an upstream licensing review or an attempted release.

Historical release notes, dated extraction records, superseded ADR decisions, explicitly proposed ADRs, migration tables, and deferred roadmap candidates were treated according to their stated status. Their historical terminology and proposed behavior are not findings merely because current behavior differs.

Validation used Go 1.26.10 with local toolchain selection and dependency downloads disabled:

GOTOOLCHAIN=local GOPROXY=off go test ./... -count=1
GOTOOLCHAIN=local GOPROXY=off go test . -run 'TestLocalDocumentationLinks|TestDependencyImportBoundary|TestPublicFacadeBoundary|^Example' -count=1

Both passed, including maintained consumer examples. An external disposable GFM rendering probe substantiated finding 2. No production code, existing tests, current documentation contracts, release tags, or consumer dependencies were changed during the audit.