Plan native ConfigKit discovery conventions

This commit is contained in:
2026-11-20 03:56:11 +00:00
parent d903a1aa4e
commit 9e5cc60d09
2 changed files with 34 additions and 14 deletions

View File

@@ -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. loader rather than retaining the old flag parser as a compatibility layer.
Preserve useful application source and server controls through appropriate selectors. 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, Enable temporary configuration overrides where the loader supports them,
passing native override records into loading. Named selectors and `--set` may passing native override records into loading. Named selectors and `--set` may
be combined for nonconflicting paths. ConfigKit owns rejection and diagnostics 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. report availability, quiet behavior, and changed exit statuses.
The [implementation plan](implementation.md) owns task sequencing, concrete The [implementation plan](implementation.md) owns task sequencing, concrete
adapter mappings, verification steps, and sprint status. There are no unresolved adapter mappings, verification steps, and sprint status. Discovery preset
product decisions or selected-format accessor release prerequisite. 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 [release policy](../policy/release.md#versioning-and-compatibility) governs
the eventual breaking release version. This migration does not itself select the eventual breaking release version. This migration does not itself select

View File

@@ -95,8 +95,10 @@ for nonconflicting paths. Duplicate and ancestor/descendant-overlapping records
are rejected by ConfigKit; neither record order nor `--set` grants precedence. are rejected by ConfigKit; neither record order nor `--set` grants precedence.
Preserve native diagnostics without local conflict filtering, deduplication, or Preserve native diagnostics without local conflict filtering, deduplication, or
merging. This also applies independently to each comparison side, including merging. This also applies independently to each comparison side, including
`--against-set`. Keep cwd-relative application path values, the existing discovery `--against-set`. Keep cwd-relative application path values and source-relative
locations, and source-relative PromptKit resources. 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 ### 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; package and metadata/selection-error tests were previously reported passing;
the obsolete precedence test has not yet been updated. 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, **Primary files:** `internal/config/{load,document,settings}.go`, their tests,
and CLI application-loading/source-selector helpers. and CLI application-loading/source-selector helpers.
1. Retain one `configkit.Load` boundary returning its actual 1. Retain one `configkit.Load` boundary returning its actual
`*configkit.Result[Document]`. Adapt selection into `LoadOptions` or its `*configkit.Result[Document]`. Adapt selection into `LoadOptions` or its
replacement: explicit config presence chooses `File`, omission chooses the replacement: explicit config presence chooses `File`; omission chooses
existing ordered `SearchConfig`, imports remain enabled, and overlay and `SearchConfig` with the agreed native directory presets and their filename
override records go directly into ConfigKit. Preserve wrapped error identity. 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 Respect the invocation context at the application boundary without claiming
ConfigKit's synchronous work can be forcibly interrupted. ConfigKit's synchronous work can be forcibly interrupted.
2. Replace `flag.FlagSet.Visit` and parser-owned override collection with typed 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. acceptable and must not alter effective configuration.
**Evidence:** real ConfigKit-backed tests cover omitted versus explicit-empty **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 and native overrides, nonconflicting combinations, and native duplicate and
ancestor/descendant conflict rejection with diagnostic evidence. Also cover ancestor/descendant conflict rejection with diagnostic evidence. Also cover
ordered source replacement, normalized values and their evidence, and removal ordered source replacement, normalized values and their evidence, and removal
of `render_format`. Reuse existing import/search/source tests; do not reproduce of `render_format`. Adapt existing search tests to the selected presets; reuse
ConfigKit's exhaustive composition matrix. import/source coverage without reproducing ConfigKit's exhaustive discovery or
composition matrix.
## Stage 3: Install Native Configuration Scopes And Independent Comparison ## 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 | | 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/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/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/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. | | `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 4. Add a focused CLI migration guide under `docs/consumers/`, linked from the
CLI/consumer overview. Cover positional prompt selection; `render` and CLI/consumer overview. Cover positional prompt selection; `render` and
`inspect` replacements; file versus literal inputs; repeated mappings without `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, stdout redirection in place of output-file flags; separate native reports,
optional report-format selection and upstream automatic rendering, and result optional report-format selection and upstream automatic rendering, and result
availability; quiet behavior (omit quiet to capture main output); status 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 policy and report checks, commits, and any remaining work accurately. Do
not mark the migration complete while required acceptance behavior is missing. not mark the migration complete while required acceptance behavior is missing.
There are no unresolved product questions. The optional upstream selected-format Discovery preset selection and ordering remain to be settled. The optional
accessor is not a migration dependency or completion gate. 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-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 [upstream-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md