Plan configuration discovery implementation

docs/roadmap/discovery.md

@@ -2,8 +2,9 @@
 
 Status: proposal with OD-1 through OD-5 and the final review clarifications
 settled and integrated below.
-This document describes future work, not an implemented contract. A staged
-implementation plan will follow review of the complete roadmap.
+This document describes future work, not an implemented contract. The
+[implementation plan](implementation.md) owns the staged work and concrete API
+decisions.
 
 ## Purpose And Ownership
 
@@ -144,7 +145,9 @@ between all presets. Selecting one does not automatically select any others.
 
 ### Illustrative Consumer API
 
-Names below are illustrative and are not implemented Go API:
+Names below are illustrative and are not implemented Go API. The
+[implementation plan](implementation.md#public-api) fixes the concrete signatures
+and the `Searches` constructor for concatenating several searches:
 
 ```go
 // A simple system-wide application.
@@ -155,9 +158,11 @@ source := configkit.SearchConfig("myapp", configkit.UnixSystemDirectories())
 // A consumer-selected working-directory, user, then system search.
 source := configkit.SearchConfig(
     "myapp",
-    configkit.WorkingDirectory(),
-    configkit.UserConfigDirectory(),
-    configkit.UnixSystemDirectories(),
+    configkit.Searches(
+        configkit.WorkingDirectory(),
+        configkit.UserConfigDirectory(),
+        configkit.UnixSystemDirectories(),
+    ),
 )
 ```
 
@@ -165,8 +170,10 @@ source := configkit.SearchConfig(
 // Explicit custom candidates followed by a selected conventional fallback.
 source := configkit.SearchConfig(
     "myapp",
-    configkit.Paths("/run/myapp/config.yml", "/opt/myapp/config.yaml"),
-    configkit.UnixSystemDirectories(),
+    configkit.Searches(
+        configkit.Paths("/run/myapp/config.yml", "/opt/myapp/config.yaml"),
+        configkit.UnixSystemDirectories(),
+    ),
 )
 ```
 
@@ -340,41 +347,20 @@ final validation, and frozen inspection after selection. Search-list order does
 not change precedence among underlays, the main input, an overlay, and CLI values.
 An explicitly selected overlay is not another main-file fallback candidate.
 
-## Work Needed From The Baseline
+## Target Integration And Documentation
 
-The subsequent implementation plan should cover:
+Discovery belongs at the source-acquisition boundary. A selected file retains
+the existing file-loading behavior and optional exhaustion shares the absent-main
+lifecycle above. Public search descriptions remain root-owned while private
+implementation handles selection and loading. The feature's implemented
+configuration contract and maintained consumer examples will explain the
+three-part discovery model, ordering, and context behavior.
 
-- Define filename-group, directory-search, preset, and search-source representations,
-  slug validation, and a search-wide requiredness option. Keep construction
-  separate from acquisition and the simple preset selection concise. Distinguish
-  omitted and explicitly empty directory-search filename selections.
-- Implement ordered expansion and concatenation for presets, filename groups,
-  custom searches, and explicit file candidates, followed by first-match selection
-  through existing file access. Resolve each source once per consumption before
-  entering its parse and composition lifecycle.
-- Integrate selected and absent outcomes with ordinary and layered main inputs,
-  placement, imports, application version checking, and overlay contexts according
-  to OD-3, including root-only host contexts for absent main inputs and normal
-  file-context checks when a file is selected. Preserve ownership and close
-  acquired handles on success and failure.
-- Preserve real selected-source metadata and safe diagnostics without treating
-  absent candidates as configuration contributions.
-- Exercise preset, directory, filename-group, and filename ordering, reversed
-  group precedence, the Unix system preset's 14 candidates and named-only `/etc`
-  search, custom-list composition, both filename extensions, no-match behavior,
-  empty components and searches, omitted versus empty filename selections,
-  skipped directory resolution for empty filename selections, slug-dependent and
-  slug-independent searches, literal custom paths and filename components,
-  required searches, unavailable preset bases, errors that must stop fallback,
-  repeated loads, and untouched explicit `File`
-  behavior. Cover imports, overlays, underlays, defaults, CLI, source versions,
-  source contexts, and source-list/inspection evidence at their boundaries.
-- Clarify the architecture policy's consumer-selected discovery boundary. Record
-  any warranted durable ownership decision in an ADR; keep preset filenames and
-  API mechanics in their canonical contract when implemented. Update consumer
-  examples and the configuration contract when the feature lands. Explain the
-  three-part discovery model and its mathematical terminology in the eventual
-  documentation, with simple preset selection and custom composition examples.
+The architecture policy should recognize explicitly consumer-selected discovery
+conventions while preserving consumer ownership of search policy. An ADR records
+that durable responsibility boundary; preset filenames and API mechanics belong
+in their canonical contracts once implemented. Execution steps and validation
+coverage are defined in the [implementation plan](implementation.md).
 
 This roadmap does not change implementation, policy, or ADRs by itself. The
 released v0.9.0 code, including the completed sequence integration and remediation