Keep configuration commands native and refine discovery direction

This commit is contained in:
2026-11-20 04:07:40 +00:00
parent 9e5cc60d09
commit f88c679a06
2 changed files with 71 additions and 58 deletions

View File

@@ -114,8 +114,8 @@ references use `--input-file`.
Reuse applicable ckprompt resource, input, and execution bindings for `run`. Reuse applicable ckprompt resource, input, and execution bindings for `run`.
Preserve explicit-value presence, including zero and empty values, and native Preserve explicit-value presence, including zero and empty values, and native
repeated mapping semantics. Do not carry forward comma splitting or obsolete repeated mapping semantics. Do not carry forward comma splitting or obsolete
aliases merely because the old parser accepted them. Keep application source aliases merely because the old parser accepted them. Keep application-only
selectors, server settings, output destinations, and whole-operation deadlines controls, including HTTP settings, reporting, and whole-operation deadlines,
distinct from framework request controls. distinct from framework request controls.
Completion initially uses native command, flag, static-value, and path Completion initially uses native command, flag, static-value, and path
@@ -170,7 +170,11 @@ sources. Adopt native `--overlay` selection and upstream selection presence
semantics. For ConfigKit v1.2.1 the supplied value selects an overlay by name, semantics. For ConfigKit v1.2.1 the supplied value selects an overlay by name,
not an arbitrary file path. Map selections through the application's ConfigKit 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. Keep HTTP-related named flags on `serve`. The `config` family exposes only
upstream commands and flags: add no application selectors or custom
`--against-*` flags. Retain native `--against-config`, `--against-overlay`, and
`--against-set` where supported. Retention of `--promptkit-source` and
`--schema-dir` outside `config` remains under review.
For implicit application configuration discovery, adopt ConfigKit's built-in For implicit application configuration discovery, adopt ConfigKit's built-in
directory presets and their native filename conventions through `SearchConfig`. directory presets and their native filename conventions through `SearchConfig`.
@@ -179,15 +183,18 @@ selection and ordering to the application; settle that choice before completing
the loader migration. Selection, exhaustion, and selected-file errors remain the loader migration. Selection, exhaustion, and selected-file errors remain
native ConfigKit behavior. native ConfigKit behavior.
The recommended preset order is `WorkingDirectory`, `UserConfigDirectory`,
`HomeDirectory`, then `UnixSystemDirectories`, using each preset's native
filename rules. This implements current-directory, user, then system discovery;
the two user presets cover the platform configuration directory and home layout.
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. ConfigKit owns rejection and
be combined for nonconflicting paths. ConfigKit owns rejection and diagnostics diagnostics for duplicate or ancestor/descendant-overlapping records. Do not
for duplicate or ancestor/descendant-overlapping override records; `--set` does filter or merge conflicts locally.
not supersede named selectors. Do not filter or merge conflicts locally.
The reviewed PromptKit scope does not support these overrides; do not emulate The reviewed PromptKit scope does not support these overrides; do not emulate
them locally. Configuration comparison must support independent selections for them locally. Configuration comparison must support independent selections for
both sides in both scopes, including corresponding application selectors where both sides in both scopes through native flags alone.
needed.
Keep the established collection-discovery model: ConfigKit imports discover Keep the established collection-discovery model: ConfigKit imports discover
`collection.yml` and `collection.yaml` entry points; each independently `collection.yml` and `collection.yaml` entry points; each independently
@@ -335,9 +342,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. Discovery preset adapter mappings, verification steps, and sprint status. Confirm the recommended
selection and ordering remain to be settled; the selected-format accessor is discovery order and settle the remaining source/schema interface before completing
not a release prerequisite. the affected stages. 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

@@ -72,27 +72,27 @@ their old counterparts without a compatibility parser.
| --- | --- | | --- | --- |
| `--config` | Application main-source selection on every configuration-consuming command, including the `promptkit` scope and family. Preserve explicit presence, including an empty value. | | `--config` | Application main-source selection on every configuration-consuming command, including the `promptkit` scope and family. Preserve explicit presence, including an empty value. |
| `--overlay` | Pass the supplied value to ConfigKit's `Options.Overlay`. At v1.2.1 this is a name, not a filesystem path: native empty/default selection and `overlays/NAME.yml` lookup apply. Do not add a second overlay interpreter or a fallback root. | | `--overlay` | Pass the supplied value to ConfigKit's `Options.Overlay`. At v1.2.1 this is a name, not a filesystem path: native empty/default selection and `overlays/NAME.yml` lookup apply. Do not add a second overlay interpreter or a fallback root. |
| Repeated `--promptkit-source PATH` | Replace the complete `promptkit_sources` list during ConfigKit loading with the selected files/directories in occurrence order, as a native override. Retain the useful existing file/directory classification, without comma splitting. | | `--promptkit-source`, `--schema-dir` | Retention outside `config` is under review. Do not install either flag on configuration commands. |
| `--schema-dir` | Presence-aware override of application `schema_dir`. | | `--addr`, `--artifact-root`, `--max-request-bytes`, `--max-artifact-bytes`, `--max-response-bytes` | Presence-aware application `server` overrides on `serve` only. |
| `--addr`, `--artifact-root`, `--max-request-bytes`, `--max-artifact-bytes`, `--max-response-bytes` | Presence-aware application `server` overrides; available on `serve` and application-scope configuration inspection. | | `config ... --set POINTER=JSON` | Native override records for `app`, passed directly to ConfigKit with native conflict handling. Enable the feature only on `app`. |
| `config ... --set POINTER=JSON` | Native override records for `app`, passed alongside explicitly supplied named-selector overrides with ConfigKit's native conflict handling. Enable the feature only on `app`. | | Native `config diff --against-config`, `--against-overlay`, `--against-set` | Independent right-side selections and supported native overrides. No application-defined `--against-*` flags. |
| `config diff --against-*` | Independent right-side selections and corresponding application-selector overrides, initialized independently rather than inherited from the left. |
| `--run-timeout DURATION` on `run` | `time.ParseDuration`, then unchanged into `RunRequest.OperationTimeout`. Positive values add the native operation budget; zero and negative values add none under PromptKit v0.23.3. No second application timer or positivity restriction. | | `--run-timeout DURATION` on `run` | `time.ParseDuration`, then unchanged into `RunRequest.OperationTimeout`. Positive values add the native operation budget; zero and negative values add none under PromptKit v0.23.3. No second application timer or positivity restriction. |
| Native `--llm-timeout-seconds` / `--timeout-seconds` | Integer per-attempt timeout through the ckprompt execution binding; no old duration conversion. | | Native `--llm-timeout-seconds` / `--timeout-seconds` | Integer per-attempt timeout through the ckprompt execution binding; no old duration conversion. |
Framework selectors (`promptkit-source`, `schema-dir`) apply to both config Install no application-defined flags or commands under `config`, including
scopes and to the native PromptKit family. Server selectors apply to the `app` source/schema flags, HTTP flags, or their `AgainstName` counterparts. Application
scope only. Provide each config selector with its matching `AgainstName`, such configuration inspection can use native `--set`; framework inspection obtains its
as `against-promptkit-source`, `against-schema-dir`, or `against-addr`. application settings through native `--config` and `--overlay` selection.
`run` accepts the framework selectors, request controls, and delivery controls; `run` accepts native configuration selection, request controls, and delivery
it does not need server-only flags. `serve` accepts framework and server controls; `serve` retains HTTP controls and excludes generation request controls.
selectors, not generation request controls. The configured `transient_retries` Settle any additional source/schema controls before implementing them. The
value remains an engine default; the native execution flag overrides a request. configured `transient_retries` remains an engine default; the native execution
flag overrides a request.
ConfigKit remains responsible for loading and all precedence, resolution, and ConfigKit remains responsible for loading and all precedence, resolution, and
inspection semantics. Named selectors and native `--set` records may be combined inspection semantics. Native `--set` records can address nonconflicting paths;
for nonconflicting paths. Duplicate and ancestor/descendant-overlapping records duplicate and ancestor/descendant-overlapping records are rejected by ConfigKit.
are rejected by ConfigKit; neither record order nor `--set` grants precedence. Record order does not grant 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 and source-relative `--against-set`. Keep cwd-relative application path values and source-relative
@@ -210,16 +210,18 @@ paths against the selected commits. Final composed behavior is checked in Stage
**Status: In progress; override decision resolved.** Adopt ConfigKit v1.2.1's **Status: In progress; override decision resolved.** Adopt ConfigKit v1.2.1's
native conflict behavior; no upstream change or dependency upgrade is required. native conflict behavior; no upstream change or dependency upgrade is required.
The real-library `TestApplicationSelectorsPreservePresenceOrderAndEvidence` The former named-selector/`--set` precedence test is obsolete: configuration
reproduces `override.duplicate` for a named `schema_dir` override and a native commands no longer expose named application overrides. Cover native override
assignment to the same path. Revise its precedence expectation to assert native conflicts directly and HTTP named overrides on `serve`. Previously reported
conflict rejection and complete the stage's remaining checks. Configuration configuration and metadata/selection-error checks do not establish completion
package and metadata/selection-error tests were previously reported passing; of these revised requirements.
the obsolete precedence test has not yet been updated.
**Discovery decision:** use native ConfigKit discovery presets and filename **Discovery decision:** use native ConfigKit discovery presets and filename
conventions. Select the applicable presets and their order before completing conventions. Select the applicable presets and their order before completing
this stage; ConfigKit supplies no implicit universal search order. this stage; ConfigKit supplies no implicit universal search order.
Recommended order: `WorkingDirectory`, `UserConfigDirectory`, `HomeDirectory`,
then `UnixSystemDirectories`, with native filename defaults. Source/schema
flags and the configured framework-source interface remain under review.
**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.
@@ -236,12 +238,12 @@ and CLI application-loading/source-selector helpers.
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
CommandKit bindings retaining `Supplied.Set`. Convert only supplied CommandKit bindings retaining `Supplied.Set`. Convert only supplied
application selectors into correctly labeled ConfigKit overrides and pass HTTP flags on `serve` into correctly labeled ConfigKit overrides. Configuration
them together with native `Selection.Overrides`. Let ConfigKit validate all commands pass only native `Selection.Overrides`; they have no named application
records and report conflicts without selecting a winner locally. Keep overrides. Let ConfigKit validate records and report conflicts. Do not load
source-list order and replacement. Use ordinary OS classification for framework definitions during application inspection. Defer source/schema flag
explicitly supplied source paths; do not load framework definitions during mapping and any change to configured source selection until that interface
application inspection. decision is settled.
Preserve the existing nonnegative `int64` domain for HTTP byte limits, Preserve the existing nonnegative `int64` domain for HTTP byte limits,
including zero as unlimited; do not narrow it to a platform `int` or add a cap. including zero as unlimited; do not narrow it to a platform `int` or add a cap.
3. Keep schema, defaults, normalization, and domain validation inside the 3. Keep schema, defaults, normalization, and domain validation inside the
@@ -252,14 +254,15 @@ and CLI application-loading/source-selector helpers.
`AppSettings.DefaultRenderFormat`, associated normalization/validation, and `AppSettings.DefaultRenderFormat`, associated normalization/validation, and
the resulting `internal/config` dependency on `internal/format`. Strict the resulting `internal/config` dependency on `internal/format`. Strict
ConfigKit decoding handles the retired field; add no compatibility mapping. ConfigKit decoding handles the retired field; add no compatibility mapping.
5. Retain shared engine construction from resolved settings: one ordered 5. The existing engine construction uses one ordered underlay per configured
underlay per app selector, import-enabled file inputs, directory expansion source, import-enabled file inputs, directory expansion
through `promptkit.DirectoryInputs`, no implicit main, existing schema base through `promptkit.DirectoryInputs`, no implicit main, existing schema base
and engine retry setting, and the default upstream bundle. Do not change and engine retry setting, and the default upstream bundle. Retention of the
collection traversal, peer composition, or whole-record replacement. general file/directory source-list interface is under review. Collection
`DirectoryInputs` retains explicit directory-selector support; collection discovery is already satisfied by a framework entry file with ConfigKit import
discovery continues through the file source's ConfigKit import globs for globs for `collection.yml` and `collection.yaml`; it does not require a separate
`collection.yml` and `collection.yaml`. directory-source mechanism or repeated source flag. Preserve native composition
semantics for the selected inputs.
6. Use fresh application input per comparison side and invocation-owned state 6. Use fresh application input per comparison side and invocation-owned state
under the native factory lifecycle; comparison may share that state without under the native factory lifecycle; comparison may share that state without
sharing either side's selected values. Start without an engine/config cache: sharing either side's selected values. Start without an engine/config cache:
@@ -270,10 +273,10 @@ and CLI application-loading/source-selector helpers.
**Evidence:** real ConfigKit-backed tests cover omitted versus explicit-empty **Evidence:** real ConfigKit-backed tests cover omitted versus explicit-empty
config/overlay selection, the selected native discovery presets and filename config/overlay selection, the selected native discovery presets and filename
conventions, a supplied zero or empty app override, individual named conventions, supplied zero or empty HTTP overrides on `serve`, native `--set`
and native overrides, nonconflicting combinations, and native duplicate and records, 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 the settled framework-source mapping, normalized values and their evidence, and removal
of `render_format`. Adapt existing search tests to the selected presets; reuse of `render_format`. Adapt existing search tests to the selected presets; reuse
import/source coverage without reproducing ConfigKit's exhaustive discovery or import/source coverage without reproducing ConfigKit's exhaustive discovery or
composition matrix. composition matrix.
@@ -290,8 +293,8 @@ composition matrix.
2. Mark only the application scope as supporting temporary overrides, passing 2. Mark only the application scope as supporting temporary overrides, passing
those records through Stage 2. Retain the PromptKit scope's native disabled those records through Stage 2. Retain the PromptKit scope's native disabled
override feature, including native capability checks for all-scope requests. override feature, including native capability checks for all-scope requests.
3. Install selectors with their scopes and independent `AgainstName` bindings 3. Install no application selectors or `AgainstName` bindings. Use native
from the mapping above. Use fresh `NewInput` results, not shared pointers. configuration/overlay/override selection and fresh per-side input where needed.
Each comparison loader must consume that side's `Selection` and input; Each comparison loader must consume that side's `Selection` and input;
do not cache the first engine into the second side. Delegate comparisons do not cache the first engine into the second side. Delegate comparisons
to the returned native adapters instead of assembling a synthetic document. to the returned native adapters instead of assembling a synthetic document.
@@ -311,7 +314,8 @@ composition matrix.
framework inspection uses sources selected by `--config`/`--overlay`; native framework inspection uses sources selected by `--config`/`--overlay`; native
show and explain agree with the resolved callback values. Exercise native show and explain agree with the resolved callback values. Exercise native
root/index/escaped-key paths and redaction through representative integration root/index/escaped-key paths and redaction through representative integration
cases, independent left/right configs/overlays/selectors, and diff-check status 3. cases, independent left/right configs/overlays/native overrides, and diff-check
status 3. Verify custom configuration flags and comparison counterparts are absent.
Verify app overrides are available and framework overrides are not emulated. Verify app overrides are available and framework overrides are not emulated.
## Stage 4: Install Native PromptKit Resources, Requirements, And Preview ## Stage 4: Install Native PromptKit Resources, Requirements, And Preview
@@ -366,7 +370,8 @@ upstream analysis or rendering suite.
helpers in `internal/adapter/cli`, and run integration tests. helpers in `internal/adapter/cli`, and run integration tests.
1. Declare exactly one required positional `PROMPT_ID` with CommandKit, using 1. Declare exactly one required positional `PROMPT_ID` with CommandKit, using
shared app config/overlay/framework-selector bindings. Reuse shared native config/overlay selection and any separately agreed source
controls. Reuse
`ckprompt.NewResourceFlags` for profile and session selection, `ckprompt.NewResourceFlags` for profile and session selection,
`NewPromptInputFlags` for variables/text/files, and `NewExecutionFlags` for `NewPromptInputFlags` for variables/text/files, and `NewExecutionFlags` for
all native execution controls. Do not install the reusable prompt flag: all native execution controls. Do not install the reusable prompt flag:
@@ -508,8 +513,8 @@ version output. Test-local fallback deadlines prevent regressions from hanging.
constants, legacy `render`/`inspect` commands, custom source DTOs and constants, legacy `render`/`inspect` commands, custom source DTOs and
inspection writers, custom prepared/definition presentation, and unused inspection writers, custom prepared/definition presentation, and unused
CLI report helpers. Delete `internal/format` if it has no remaining consumers; CLI report helpers. Delete `internal/format` if it has no remaining consumers;
preserve `internal/report` for HTTP. Keep the useful source-to-underlay wiring preserve `internal/report` for HTTP. Implement the settled framework-source
in its new CLI home, not a resurrected framework facade. mapping through native APIs without resurrecting a framework facade.
2. Replace obsolete tests with selected native integration protection from 2. Replace obsolete tests with selected native integration protection from
Stages 2–7. Retain architectural import boundaries and HTTP regression tests. Stages 2–7. Retain architectural import boundaries and HTTP regression tests.
Do not make intentionally retired snapshots or aliases pass by retaining Do not make intentionally retired snapshots or aliases pass by retaining
@@ -520,7 +525,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` | 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/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 imports and describe the settled framework-source settings. |
| `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. |
@@ -604,7 +609,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.
Discovery preset selection and ordering remain to be settled. The optional Confirm the recommended discovery order and settle source/schema controls and
framework-source selection before completing affected stages. The optional
upstream selected-format 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