Record documentation audit findings

docs/roadmap/documentation.md

@@ -0,0 +1,90 @@
+# 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](../config.md#configuration-discovery),
+line 34, tells consumers to construct a search from literal `Paths`.
+
+**Discrepancy:** The public constructor is now `SearchPaths`, declared in
+[discovery.go](../../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](../consumers/README.md#pre-v1-public-api-cleanup) 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](../development.md#task-to-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:
+
+```sh
+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.