Settle native discovery and single-file PromptKit configuration

This commit is contained in:
2026-11-20 04:15:49 +00:00
parent f88c679a06
commit adbe62a1e9
2 changed files with 106 additions and 57 deletions

View File

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