From 04f9f16e273d75a673298a4535e6b5cc7c4723a5 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 8 Nov 2026 05:17:43 +0000 Subject: [PATCH] Resolve configuration discovery order and import support --- docs/roadmap/configkit.md | 68 ++++++++++++++++++++++++++++++--------- docs/roadmap/promptkit.md | 8 ++--- 2 files changed, 56 insertions(+), 20 deletions(-) diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index 85e03a4..28a8c38 100644 --- a/docs/roadmap/configkit.md +++ b/docs/roadmap/configkit.md @@ -24,6 +24,34 @@ and [configuration contract](https://forge.maximumdirect.net/base-layer/configki ## Agreed Direction and Migration Work +### Discovery Locations and Import Selection — Resolved + +An explicit `--config` selects exactly that file. A missing, inaccessible, or +invalid explicit file is an error; do not fall back to discovery. + +Without an explicit file, search in this order using ConfigKit's native presets +and filename rules with application name `audita`: + +1. `WorkingDirectory` for project-local configuration. +2. `UserConfigDirectory` for personal configuration. +3. `UnixSystemDirectories` for system configuration. + +Select the first matching file. Do not merge every discovered file or continue +searching after a selected file fails to load. Additional composition is explicit +through native imports and overlays. Recommend explicit configuration paths for +automation so its selection does not depend on the working directory. + +Enable native imports for operator configuration sources, retaining upstream +defaults and declaration-level controls. Imports compose peer documents, not +higher-priority override layers. Missing optional imports may be absent; +operators use `required: true` for essential inputs. Invalid declarations, +unreadable selected files, and composition conflicts retain native errors. + +Behavior when automatic discovery finds no file remains a separate open decision +below. This does not reopen the selected search order or import support. + +### Migration Work + 1. Move imports to `go.maximumdirect.net/configkit` with the coordinated PromptKit cutover. Raise the toolchain as specified by the master roadmap. Replace `Resolution.Record` uses with the appropriate dedicated recording @@ -51,8 +79,8 @@ and [configuration contract](https://forge.maximumdirect.net/base-layer/configki 6. Apply the resolved [PromptKit ownership decision](promptkit.md#backend-and-credential-ownership--resolved): remove Audita's separate backend mapping and LLM credential references from its application schema. Native PromptKit resources own those settings and - their resolution. Coordinate the hard cutover and examples here; file discovery - and import selection remain open, without reopening semantic ownership. + their resolution. Coordinate the hard cutover and examples here, using the + resolved discovery and import policy above. ## Documentation and Acceptance @@ -69,6 +97,11 @@ coverage for generic grammar rather than copying its test matrix. Verify the standard ckconfig surface through the assembled CLI and run the full application suite at the coordinated migration boundary. +Check explicit-file selection without fallback, native working/user/system +search precedence, and terminal errors for a selected invalid file. Verify +optional and required imports and peer-composition errors through Audita's +integration. Cover discovery exhaustion after its behavior is selected below. + The earlier passing configuration suite is useful baseline evidence, not proof that operators see unchanged semantics. Native semantics and clear migration are the target; preserving incidental old output or validation order is not. @@ -81,22 +114,25 @@ requirement and the smallest integration boundary that satisfies it. ## Open Decisions -### Discovery Locations and Import Selection +### No Configuration File Found -**Recommendation:** replace custom discovery with ConfigKit's supported search -API, then select documented paths and import options based on suite conventions. -Evaluate the current system-only search and disabled imports rather than carrying -them forward automatically. Native API adoption is agreed; the exact search -locations and import defaults still need selection before changing operator -behavior. Preserve explicit-path error evidence and distinguish optional from -required imports using native semantics. +**Recommendation:** use ConfigKit's optional-search behavior: continue with +embedded defaults, underlays, and explicit CLI settings, then validate what the +requested command needs. A missing main file alone should not prevent resource +inspection or execution whose required inputs are otherwise supplied. Do not +invent an implicit model/profile choice to make incomplete execution settings +pass validation. Define filesystem context explicitly where overlays or relative +resource inputs need it; do not infer a base from unsuccessful search candidates. -**Alternative:** configure the native API with two system locations and imports -disabled if deployment requirements justify that source-selection policy. This -limits discovery flexibility and must stand on its own merits; compatibility with -today's installations carries no weight. Conversely, enabling all -possible searches/imports without a selected convention can load unintended -sources and is not required for full API adoption. +This follows the native absent-main lifecycle and supports lightweight command +invocations. It requires clear errors for missing command-specific inputs and +inspection that accurately shows that no main file was selected. + +**Alternative:** require a discovered configuration file for configuration-dependent +commands, while keeping help/version independent. This gives deployments a +mandatory configuration anchor, but rejects otherwise sufficient defaults and +CLI settings and adds a requirement without an identified domain need. Explicit +file errors remain terminal under either choice. ### Application Schema Version diff --git a/docs/roadmap/promptkit.md b/docs/roadmap/promptkit.md index 69d335c..ecfe105 100644 --- a/docs/roadmap/promptkit.md +++ b/docs/roadmap/promptkit.md @@ -81,8 +81,8 @@ checks whose purpose was enforcing the removed application backend registry. Remove superseded fields, code, and tests in the major-release cutover and update the affected policies and current contracts with implementation. The ConfigKit -outline still owns decisions about file locations, discovery, and imports; those -choose how native resources are supplied, not who owns their semantics. +outline owns file discovery and import policy; those choices govern how native +resources are supplied, not who owns their semantics. ### Bundled Prompts and Operator Replacements — Resolved @@ -111,8 +111,8 @@ mechanism supports production customization. Standard inspection, provenance, and request preview must make effective prompts and their origins understandable. Audita's response schemas and domain validation continue to apply. -External source selection remains part of the ConfigKit discovery/import -decision. This workflow is required PromptKit adoption scope and should use +External source selection follows the [ConfigKit discovery/import plan](configkit.md). +This workflow is required PromptKit adoption scope and should use native composition rather than a separate prompt loader or override system. ### Profile Inspection and Summary — Resolved