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

@@ -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