diff --git a/docs/roadmap/commandkit-adoption.md b/docs/roadmap/commandkit-adoption.md index e9f0e25..1364952 100644 --- a/docs/roadmap/commandkit-adoption.md +++ b/docs/roadmap/commandkit-adoption.md @@ -3,7 +3,7 @@ ## Status And Intent Initial roadmap, prepared 2026-11-19. The product direction is agreed; -implementation has not begun. This document owns the target and product intent, +implementation is underway. This document owns the target and product intent, incorporating the decisions in the [migration notepad](commandkit-notepad.md). The notepad remains the discussion record. The [Narratio proposal](narratio-feature-request.md) supplies consumer @@ -173,20 +173,18 @@ loader rather than retaining the old flag parser as a compatibility layer. 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. +`--against-set` where supported. Remove `--promptkit-source` and `--schema-dir` +from all commands. Native resource IDs select loaded prompts and profiles; +installation configuration supplies their definitions and schema source. 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. - -The recommended preset order is `WorkingDirectory`, `UserConfigDirectory`, -`HomeDirectory`, then `UnixSystemDirectories`, using each preset's native +Replace the legacy two-file search. The selected 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. +ConfigKit selects one main file, with native optional-search exhaustion and +selected-file error behavior; this is not a merge of all discovered files. Enable temporary configuration overrides where the loader supports them, passing native override records into loading. ConfigKit owns rejection and @@ -196,13 +194,26 @@ 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 through native flags alone. -Keep the established collection-discovery model: ConfigKit imports discover -`collection.yml` and `collection.yaml` entry points; each independently +Use an application `promptkit` settings section containing `configuration`, the +path to one external framework entry file, and `schema_dir`, the output-schema +root. Replace the general `promptkit_sources` file/directory list and top-level +`schema_dir`. Pass the selected file to PromptKit as its native main input with +ConfigKit imports enabled. Keep the bundled upstream defaults. + +Keep the established collection-discovery model: that entry file's ConfigKit +glob imports discover `collection.yml` and `collection.yaml` entry points; each independently maintained collection declares its namespace and imports its own definitions through relative references. Retain the [discovery example](../../examples/config.discovery.yml) and representative -multi-definition collection documentation. No Git update manager or custom -collection traversal is part of this migration. +multi-definition collection documentation, updating the application example to +the new settings. No repeated source flag, separate directory-source mechanism, +Git update manager, or custom collection traversal is part of this migration. + +Embedding actual PromptKit definitions under the application's `promptkit` key +is deferred pending suitable upstream support. The current section contains +application settings for acquiring the separate framework document. Do not +extract, reserialize, or reload a resolved application subtree as a substitute +for a native upstream handoff. This deferred capability does not block adoption. Use native prompt, profile, and backend namespace selectors independently on applicable commands. Short caller-supplied IDs use their selected namespace; @@ -342,9 +353,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. 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. +adapter mappings, verification steps, and sprint status. The discovery and +source/schema decisions are settled. Neither the selected-format accessor nor +embedded framework configuration is a migration 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 81b4879..a8346c2 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -72,7 +72,7 @@ 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. | -| `--promptkit-source`, `--schema-dir` | Retention outside `config` is under review. Do not install either flag on configuration commands. | +| `--promptkit-source`, `--schema-dir` | Removed from every command; framework entry-file and schema-root settings come from application configuration. | | `--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. | @@ -85,9 +85,8 @@ configuration inspection can use native `--set`; framework inspection obtains it 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. +Do not add source/schema convenience flags. 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. Native `--set` records can address nonconflicting paths; @@ -97,8 +96,40 @@ 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 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. +directory presets and filename conventions in this order: `WorkingDirectory`, +`UserConfigDirectory`, `HomeDirectory`, `UnixSystemDirectories`. Retain each +preset's native filename rules, optional exhaustion, and terminal selected-file +errors. One main file is selected; the discovered candidates are not layers. + +### Framework Configuration Settings + +Use the following application settings shape: + +```yaml +promptkit: + configuration: ./promptkit/collections.yml + schema_dir: ./schemas +``` + +`promptkit.configuration` selects one external framework file. An omitted or +empty value supplies no external main, preserving defaults-only engine loading. +`promptkit.schema_dir` retains the existing schema-root default and semantics. +Application path values remain cwd-relative; imports and resource references +within the framework document retain their native source contexts. The existing +`transient_retries` setting continues to supply the engine retry default. + +Replace `promptkit_sources` and top-level `schema_dir`; do not retain aliases or +a compatibility conversion. Load the external file as an import-enabled +`configkit.Input` in `promptkit.ConfigurationSources.Main`. Its glob imports +discover collection entry files; no application-managed source list or directory +classification is needed. PromptKit retains its bundled configuration underlay. + +The `promptkit` application section is acquisition settings, not an embedded +PromptKit definition document. Embedding profiles, prompts, backends, or +collections there is deferred until upstream supports a native handoff with the +required resource context and inspection evidence. Do not emulate it by +extracting and reloading application values; no upstream change is required for +this migration. ### Outcomes And Delivery @@ -216,15 +247,13 @@ 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. +**Discovery and source decisions: Settled.** Implement the ordered native search +and single external framework entry file specified above. Remove source/schema +CLI flags and the general source-list interface. Embedded framework definitions +remain deferred; they are not an upstream prerequisite for this stage. **Primary files:** `internal/config/{load,document,settings}.go`, their tests, -and CLI application-loading/source-selector helpers. +and CLI application-loading/engine-construction helpers. 1. Retain one `configkit.Load` boundary returning its actual `*configkit.Result[Document]`. Adapt selection into `LoadOptions` or its @@ -241,9 +270,9 @@ and CLI application-loading/source-selector helpers. 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. + framework definitions during application inspection. Remove source/schema + flag bindings, source-list override construction, and file/directory + classification used by those flags. 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,17 +281,20 @@ and CLI application-loading/source-selector helpers. of completed values, not another resolver or merger. 4. Remove `Document.Defaults`, `DefaultsDocument`, `defaults.render_format`, `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. 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. 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. + the resulting `internal/config` dependency on `internal/format`. Replace the + source-selector list and top-level schema root with the typed `promptkit` + settings above; move their applicable defaults, normalization, validation, + and evidence paths into the new schema. Strict ConfigKit decoding handles + retired fields; add no compatibility mapping. +5. Build the shared engine from completed application settings. When configured, + construct `configkit.File` from the resolved `promptkit.configuration` and + pass it in an import-enabled native main input; otherwise leave `Sources.Main` + nil. Supply the configured schema + root and existing retry default, retaining PromptKit's bundled underlay. + Remove application use of `DirectoryInputs` and one-underlay-per-source + construction. The framework entry file imports both collection-entry globs; + each collection supplies its namespace and relative imports. Keep native + acquisition, composition, validation, and inspection evidence intact. 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: @@ -276,9 +308,11 @@ config/overlay selection, the selected native discovery presets and filename 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 -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 +the new settings shape, optional versus selected framework file loading, +imported collection resources and their source contexts, normalized values and +their evidence, and removal of retired fields and flags. 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 @@ -370,8 +404,7 @@ 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 native config/overlay selection and any separately agreed source - controls. Reuse + shared native config/overlay selection. 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: @@ -513,8 +546,9 @@ 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. Implement the settled framework-source - mapping through native APIs without resurrecting a framework facade. + preserve `internal/report` for HTTP. Retire source/schema flags and the old + file/directory selector machinery; acquire the single framework document + 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 @@ -525,7 +559,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 imports and describe the settled framework-source settings. | + | `docs/config.md` | Selected native discovery order and filenames; `promptkit.configuration` and `promptkit.schema_dir` replacing the source list and top-level schema root; removed render default; native overlay selection, overrides, scopes, and comparison. Preserve collection imports and document the separate framework file. | | `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. | @@ -535,7 +569,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; native configuration discovery; `--overlay` names; endpoint + comma splitting; native configuration discovery; the new `promptkit` settings + and removal of source/schema CLI flags; `--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 @@ -545,7 +580,10 @@ version output. Test-local fallback deadlines prevent regressions from hanging. editing published notes, tagging, pushing, or adding release gates. Eventual release notes must summarize the breaking change and link the guide under the existing release/OSS policies. -5. Update maintained application configs to remove the retired render default. +5. Update maintained application configs to the new `promptkit` settings and + remove retired fields. Where an example previously selected multiple files + or directories, revise it to use a framework entry file and native import + semantics. Do not recreate the retired source-list precedence locally. Update `examples/render-markdown-summary.sh`, `render-v0.9-features.sh`, README/config examples, and collection workflows to native prepared preview, inspection, positional IDs, and preferred aliases. Existing example script @@ -609,9 +647,9 @@ 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. -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. +Discovery, source selection, and schema controls are settled. The optional +selected-format accessor and deferred embedded framework configuration are not +migration dependencies or completion gates. [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