From ac5bf29ddc9ccea38f84e4664d61230c45d7db0f Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 24 Oct 2026 01:58:48 +0000 Subject: [PATCH] Settle discovery slug and custom path rules --- docs/roadmap/discovery.md | 48 +++++++++++++++++---------------------- 1 file changed, 21 insertions(+), 27 deletions(-) diff --git a/docs/roadmap/discovery.md b/docs/roadmap/discovery.md index f4033ef..713cd85 100644 --- a/docs/roadmap/discovery.md +++ b/docs/roadmap/discovery.md @@ -1,10 +1,8 @@ # Composable Configuration Discovery Roadmap -Status: proposal with the agreed direction, filename groups, and search presets -captured below. Remaining behavioral choices are under -[Open Decisions](#open-decisions). +Status: proposal with OD-1 through OD-5 settled and integrated below. This document describes future work, not an implemented contract. A staged -implementation plan will follow once the decisions are settled. +implementation plan will follow review of the complete roadmap. ## Purpose And Ownership @@ -280,6 +278,24 @@ represent both intentions clearly. Presets retain their specified filename group Selecting a single preset keeps the simple case concise. Search-wide requiredness provides the check for consumers that must find a configuration file. +### Slugs And Custom Path Interpretation (OD-5 — Settled) + +Require a nonempty single-component application slug whenever a selected search +uses it to construct a directory or filename. Reject path separators, `.` and +`..`, and forms unusable as that component on the target platform. Preserve +spelling and case; do not trim, lowercase, or impose a kebab-case naming scheme. +Validation keeps the slug from changing the intended directory structure without +imposing a separate naming style. + +Searches that do not use the slug do not require one. Examples include explicit +file candidates and a custom directory searched with only Generic filenames. + +Treat custom paths as literal host paths. Resolve relative paths against the +working directory at load time. Do not expand shell variables, `~`, or wildcard +syntax. Consumers can construct expanded paths themselves; User and Home presets +provide the common directory-resolution conveniences. These rules keep custom +paths consistent with explicit file loading. + ### Placement, Provenance, And Existing Features The selected file participates as the actual file source. Preserve its physical @@ -320,6 +336,7 @@ The subsequent implementation plan should cover: 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, + slug-dependent and slug-independent searches, literal custom paths, 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, @@ -334,26 +351,3 @@ The subsequent implementation plan should cover: This roadmap does not change implementation, policy, or ADRs by itself. Coordinate implementation with the ongoing sequence integration audit rather than assuming its in-progress changes are part of a fixed implementation baseline. - -## Open Decisions - -### OD-5 — Slugs And Custom Path Interpretation - -**Recommendation:** require a nonempty single-component slug when a selected -preset uses it to construct filenames. Reject path separators, `.` and `..`, -and other forms that cannot be used as that component on the target platform. -Preserve spelling; do not silently lowercase, trim, or impose a kebab-case naming -scheme. A composition made only of explicit custom paths need not require an -application slug. - -Treat custom paths as literal host file paths. Resolve relative paths against -the working directory at load time; do not expand shell variables, `~`, or glob -syntax. Consumers can construct expanded paths themselves. Selected presets -provide the convenience for user and working-directory bases. - -**Alternative:** require a restricted portable slug grammar, such as lowercase -ASCII letters, digits, and hyphens. This is easy to document and portable, but -unnecessarily excludes otherwise usable application names. Automatic shell-like -custom-path expansion is also viable, but adds escaping and environment semantics -that ordinary `File(path)` does not supply. Literal paths keep both interfaces -consistent.