diff --git a/docs/roadmap/commandkit-adoption.md b/docs/roadmap/commandkit-adoption.md index 85eb6b4..e9f0e25 100644 --- a/docs/roadmap/commandkit-adoption.md +++ b/docs/roadmap/commandkit-adoption.md @@ -114,8 +114,8 @@ references use `--input-file`. Reuse applicable ckprompt resource, input, and execution bindings for `run`. Preserve explicit-value presence, including zero and empty values, and native repeated mapping semantics. Do not carry forward comma splitting or obsolete -aliases merely because the old parser accepted them. Keep application source -selectors, server settings, output destinations, and whole-operation deadlines +aliases merely because the old parser accepted them. Keep application-only +controls, including HTTP settings, reporting, and whole-operation deadlines, distinct from framework request controls. 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, 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. +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 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 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, -passing native override records into loading. Named selectors and `--set` may -be combined for nonconflicting paths. ConfigKit owns rejection and diagnostics -for duplicate or ancestor/descendant-overlapping override records; `--set` does -not supersede named selectors. Do not filter or merge conflicts locally. +passing native override records into loading. ConfigKit owns rejection and +diagnostics for duplicate or ancestor/descendant-overlapping records. Do not +filter or merge conflicts locally. The reviewed PromptKit scope does not support these overrides; do not emulate them locally. Configuration comparison must support independent selections for -both sides in both scopes, including corresponding application selectors where -needed. +both sides in both scopes through native flags alone. Keep the established collection-discovery model: ConfigKit imports discover `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. The [implementation plan](implementation.md) owns task sequencing, concrete -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. +adapter mappings, verification steps, and sprint status. Confirm the recommended +discovery order and settle the remaining source/schema interface before completing +the affected stages. 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 de28483..81b4879 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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. | | `--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. | -| `--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; available on `serve` and application-scope configuration inspection. | -| `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`. | -| `config diff --against-*` | Independent right-side selections and corresponding application-selector overrides, initialized independently rather than inherited from the left. | +| `--promptkit-source`, `--schema-dir` | Retention outside `config` is under review. Do not install either flag on configuration commands. | +| `--addr`, `--artifact-root`, `--max-request-bytes`, `--max-artifact-bytes`, `--max-response-bytes` | Presence-aware application `server` overrides on `serve` only. | +| `config ... --set POINTER=JSON` | Native override records for `app`, passed directly to ConfigKit with 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. | | `--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. | -Framework selectors (`promptkit-source`, `schema-dir`) apply to both config -scopes and to the native PromptKit family. Server selectors apply to the `app` -scope only. Provide each config selector with its matching `AgainstName`, such -as `against-promptkit-source`, `against-schema-dir`, or `against-addr`. -`run` accepts the framework selectors, request controls, and delivery controls; -it does not need server-only flags. `serve` accepts framework and server -selectors, not generation request controls. The configured `transient_retries` -value remains an engine default; the native execution flag overrides a request. +Install no application-defined flags or commands under `config`, including +source/schema flags, HTTP flags, or their `AgainstName` counterparts. Application +configuration inspection can use native `--set`; framework inspection obtains its +application settings through native `--config` and `--overlay` selection. +`run` accepts native configuration selection, request controls, and delivery +controls; `serve` retains HTTP controls and excludes generation request controls. +Settle any additional source/schema controls before implementing them. The +configured `transient_retries` remains an engine default; the native execution +flag overrides a request. ConfigKit remains responsible for loading and all precedence, resolution, and -inspection semantics. Named selectors and native `--set` records may be combined -for nonconflicting paths. Duplicate and ancestor/descendant-overlapping records -are rejected by ConfigKit; neither record order nor `--set` grants precedence. +inspection semantics. Native `--set` records can address nonconflicting paths; +duplicate and ancestor/descendant-overlapping records are rejected by ConfigKit. +Record order does not grant 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 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 native conflict behavior; no upstream change or dependency upgrade is required. -The real-library `TestApplicationSelectorsPreservePresenceOrderAndEvidence` -reproduces `override.duplicate` for a named `schema_dir` override and a native -assignment to the same path. Revise its precedence expectation to assert native -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. +The former named-selector/`--set` precedence test is obsolete: configuration +commands no longer expose named application overrides. Cover native override +conflicts directly and HTTP named overrides on `serve`. Previously reported +configuration and metadata/selection-error checks do not establish completion +of these revised requirements. **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. +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, 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. 2. Replace `flag.FlagSet.Visit` and parser-owned override collection with typed CommandKit bindings retaining `Supplied.Set`. Convert only supplied - application selectors into correctly labeled ConfigKit overrides and pass - them together with native `Selection.Overrides`. Let ConfigKit validate all - records and report conflicts without selecting a winner locally. Keep - source-list order and replacement. Use ordinary OS classification for - explicitly supplied source paths; do not load framework definitions during - application inspection. + HTTP flags on `serve` into correctly labeled ConfigKit overrides. Configuration + commands pass only native `Selection.Overrides`; they have no named application + overrides. Let ConfigKit validate records and report conflicts. Do not load + framework definitions during application inspection. Defer source/schema flag + mapping and any change to configured source selection until that interface + decision is settled. 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. 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 the resulting `internal/config` dependency on `internal/format`. Strict ConfigKit decoding handles the retired field; add no compatibility mapping. -5. Retain shared engine construction from resolved settings: one ordered - underlay per app selector, import-enabled file inputs, directory expansion +5. The existing engine construction uses one ordered underlay per configured + source, import-enabled file inputs, directory expansion through `promptkit.DirectoryInputs`, no implicit main, existing schema base - and engine retry setting, and the default upstream bundle. Do not change - collection traversal, peer composition, or whole-record replacement. - `DirectoryInputs` retains explicit directory-selector support; collection - discovery continues through the file source's ConfigKit import globs for - `collection.yml` and `collection.yaml`. + and engine retry setting, and the default upstream bundle. Retention of the + general file/directory source-list interface is under review. Collection + discovery is already satisfied by a framework entry file with ConfigKit import + globs for `collection.yml` and `collection.yaml`; it does not require a separate + 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 under the native factory lifecycle; comparison may share that state without 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 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 +conventions, supplied zero or empty HTTP overrides on `serve`, native `--set` +records, 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 +the settled framework-source mapping, normalized values and their evidence, and removal of `render_format`. Adapt existing search tests to the selected presets; reuse import/source coverage without reproducing ConfigKit's exhaustive discovery or composition matrix. @@ -290,8 +293,8 @@ composition matrix. 2. Mark only the application scope as supporting temporary overrides, passing those records through Stage 2. Retain the PromptKit scope's native disabled override feature, including native capability checks for all-scope requests. -3. Install selectors with their scopes and independent `AgainstName` bindings - from the mapping above. Use fresh `NewInput` results, not shared pointers. +3. Install no application selectors or `AgainstName` bindings. Use native + configuration/overlay/override selection and fresh per-side input where needed. Each comparison loader must consume that side's `Selection` and input; do not cache the first engine into the second side. Delegate comparisons 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 show and explain agree with the resolved callback values. Exercise native 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. ## 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. 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, `NewPromptInputFlags` for variables/text/files, and `NewExecutionFlags` for 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 inspection writers, custom prepared/definition presentation, and unused CLI report helpers. Delete `internal/format` if it has no remaining consumers; - preserve `internal/report` for HTTP. Keep the useful source-to-underlay wiring - in its new CLI home, not a resurrected framework facade. + preserve `internal/report` for HTTP. Implement the settled framework-source + mapping through native APIs without resurrecting a framework facade. 2. Replace obsolete tests with selected native integration protection from Stages 2–7. Retain architectural import boundaries and HTTP regression tests. 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 | | --- | --- | | `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/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. | @@ -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 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-guide]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/consumers/guide.md