diff --git a/docs/roadmap/commandkit-adoption.md b/docs/roadmap/commandkit-adoption.md index b60e9da..85eb6b4 100644 --- a/docs/roadmap/commandkit-adoption.md +++ b/docs/roadmap/commandkit-adoption.md @@ -172,6 +172,13 @@ not an arbitrary file path. Map selections through the application's ConfigKit loader rather than retaining the old flag parser as a compatibility layer. Preserve useful application source and server controls through appropriate selectors. +For implicit application configuration discovery, adopt ConfigKit's built-in +directory presets and their native filename conventions through `SearchConfig`. +Replace the legacy two-file search. ConfigKit deliberately leaves preset +selection and ordering to the application; settle that choice before completing +the loader migration. Selection, exhaustion, and selected-file errors remain +native ConfigKit behavior. + Enable temporary configuration overrides where the loader supports them, passing native override records into loading. Named selectors and `--set` may be combined for nonconflicting paths. ConfigKit owns rejection and diagnostics @@ -328,8 +335,9 @@ documentation and examples describe the shipped interface. In particular: report availability, quiet behavior, and changed exit statuses. The [implementation plan](implementation.md) owns task sequencing, concrete -adapter mappings, verification steps, and sprint status. There are no unresolved -product decisions or selected-format accessor release prerequisite. +adapter mappings, verification steps, and sprint status. Discovery preset +selection and ordering remain to be settled; the selected-format accessor is +not a release prerequisite. The [release policy](../policy/release.md#versioning-and-compatibility) governs the eventual breaking release version. This migration does not itself select diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index efdbd0c..de28483 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -95,8 +95,10 @@ for nonconflicting paths. Duplicate and ancestor/descendant-overlapping records are rejected by ConfigKit; neither record order nor `--set` grants precedence. Preserve native diagnostics without local conflict filtering, deduplication, or merging. This also applies independently to each comparison side, including -`--against-set`. Keep cwd-relative application path values, the existing discovery -locations, and source-relative PromptKit resources. +`--against-set`. Keep cwd-relative application path values and source-relative +PromptKit resources. Replace the legacy discovery paths with ConfigKit's native +directory presets and filename conventions; preset selection and ordering are +an explicit application choice still to be settled. ### Outcomes And Delivery @@ -215,14 +217,21 @@ conflict rejection and complete the stage's remaining checks. Configuration package and metadata/selection-error tests were previously reported passing; the obsolete precedence test has not yet been updated. +**Discovery decision:** use native ConfigKit discovery presets and filename +conventions. Select the applicable presets and their order before completing +this stage; ConfigKit supplies no implicit universal search order. + **Primary files:** `internal/config/{load,document,settings}.go`, their tests, and CLI application-loading/source-selector helpers. 1. Retain one `configkit.Load` boundary returning its actual `*configkit.Result[Document]`. Adapt selection into `LoadOptions` or its - replacement: explicit config presence chooses `File`, omission chooses the - existing ordered `SearchConfig`, imports remain enabled, and overlay and - override records go directly into ConfigKit. Preserve wrapped error identity. + replacement: explicit config presence chooses `File`; omission chooses + `SearchConfig` with the agreed native directory presets and their filename + defaults. Replace the two literal legacy paths instead of preserving their + precedence or limiting filenames to `config.yml`. Keep native optional-search + exhaustion and selected-file error behavior. Imports remain enabled; overlay + and override records go directly into ConfigKit. Preserve wrapped error identity. Respect the invocation context at the application boundary without claiming ConfigKit's synchronous work can be forcibly interrupted. 2. Replace `flag.FlagSet.Visit` and parser-owned override collection with typed @@ -260,12 +269,14 @@ and CLI application-loading/source-selector helpers. acceptable and must not alter effective configuration. **Evidence:** real ConfigKit-backed tests cover omitted versus explicit-empty -config/overlay selection, a supplied zero or empty app override, individual named +config/overlay selection, the selected native discovery presets and filename +conventions, a supplied zero or empty app override, individual named and native overrides, nonconflicting combinations, and native duplicate and ancestor/descendant conflict rejection with diagnostic evidence. Also cover ordered source replacement, normalized values and their evidence, and removal -of `render_format`. Reuse existing import/search/source tests; do not reproduce -ConfigKit's exhaustive composition matrix. +of `render_format`. Adapt existing search tests to the selected presets; reuse +import/source coverage without reproducing ConfigKit's exhaustive discovery or +composition matrix. ## Stage 3: Install Native Configuration Scopes And Independent Comparison @@ -509,7 +520,7 @@ version output. Test-local fallback deadlines prevent regressions from hanging. | Owner | Required changes | | --- | --- | | `docs/cli.md` | New command tree, applicable flags/aliases, native selection/reporting, stdout redirection, separate report files with optional format selection, statuses, completion, explicit smoke tests. Link upstream for standard family details. | - | `docs/config.md` | Removed render default; native overlay-name selection; application overrides and loader authority; app/framework scopes and native comparison. Preserve collection/source/default semantics. | + | `docs/config.md` | Native discovery presets and filename conventions; removed render default; native overlay-name selection; application overrides and loader authority; app/framework scopes and native comparison. Preserve collection/source/default semantics. | | `docs/integrations/subprocess.md` | Artifact-first execution, native reports and result availability, content-bearing metadata reports, stream capture, partial delivery, cancellation, and caller responsibility. Link exact CLI syntax rather than duplicate it. | | `docs/operations.md` | Updated discovery/preview/execution workflow, explicit smoke-test effects, potentially sensitive reports, file retention, server process lifecycle, unchanged HTTP limits. | | `docs/internal/overview.md`, `adapters.md`, `sources.md` | Actual component inventory and data flow, native acquisition boundaries, CLI result versus retained HTTP observation report, selector/engine lifecycle. | @@ -519,7 +530,8 @@ version output. Test-local fallback deadlines prevent regressions from hanging. 4. Add a focused CLI migration guide under `docs/consumers/`, linked from the CLI/consumer overview. Cover positional prompt selection; `render` and `inspect` replacements; file versus literal inputs; repeated mappings without - comma splitting; `--overlay` names; endpoint and timeout spelling/units; + comma splitting; native configuration discovery; `--overlay` names; endpoint + and timeout spelling/units; stdout redirection in place of output-file flags; separate native reports, optional report-format selection and upstream automatic rendering, and result availability; quiet behavior (omit quiet to capture main output); status @@ -592,8 +604,8 @@ current documentation links resolve. Migration examples match the built CLI. policy and report checks, commits, and any remaining work accurately. Do not mark the migration complete while required acceptance behavior is missing. -There are no unresolved product questions. The optional upstream selected-format -accessor is not a migration dependency or completion gate. +Discovery preset selection and ordering remain to be settled. The optional +upstream selected-format accessor is not a migration dependency or completion gate. [upstream-guide]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/consumers/guide.md [upstream-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md