diff --git a/docs/roadmap/next-release-considerations.md b/docs/roadmap/next-release-considerations.md index 308eab9..46ea0b9 100644 --- a/docs/roadmap/next-release-considerations.md +++ b/docs/roadmap/next-release-considerations.md @@ -1,9 +1,8 @@ # Feature Considerations Before The Next Release -Status: item 1 records accepted design decisions; item 2 remains a discussion -candidate. Review these items before the next release; this document does not -authorize implementation or commit either item to that release. Implemented schema -support is documented in the +Status: items 1 and 2 record accepted design decisions. Review these items before +the next release; this document does not authorize implementation or commit either +item to that release. Implemented schema support is documented in the [format reference](../formats.md#schemas). ## 1. Enable One Structured-Output Repair Attempt By Default @@ -39,18 +38,48 @@ unchanged; the change does not promise successful correction. ## 2. Place Configuration Under A Root-Level `promptkit` Key -Consider moving PromptKit-owned configuration beneath `promptkit`, for example -from `prompts` to `promptkit.prompts`. This would give applications a distinct -configuration section for PromptKit alongside their other settings. +**Accepted:** move all PromptKit-owned configuration beneath the fixed root-level +`promptkit` key. This gives applications a distinct configuration section for +PromptKit alongside their other settings. Do not add a configurable mounting key. -Before accepting, settle: +The resolved structure includes `promptkit.backends`, `promptkit.profiles`, +`promptkit.prompts`, `promptkit.collections`, and `promptkit.schema_root`. +Collection-local fields remain inside their collection. ConfigKit-owned source +headers and directives retain their native semantics and locations; they do not +automatically move inside `promptkit`. -- The complete field scope, including backends, profiles, collections, and schema - roots; ConfigKit-owned source headers and directives retain ConfigKit semantics. -- Whether to make a clean breaking migration or support a transition period. -- How collection imports, bundled defaults, typed configuration helpers, and - inspection use the new location through normal ConfigKit composition. -- Migration guidance accounting for the implemented schema-source changes. +Make a clean breaking migration with one canonical resolved location. Do not +support legacy root-level resource locations through aliases, automatic detection, +or a second merge/precedence pass. Runtime resource IDs and namespace selection +remain unchanged; the configuration wrapper is not part of a resource ID. + +Preserve convenient standalone files. Individual resource files can still begin +with `id`, and collection files can still contain local `prompts`, `profiles`, +`backends`, and `schema_root` fields without a `promptkit` wrapper. Native ConfigKit +import destinations and PromptKit source helpers mount those fragments at the +appropriate nested location. This is fragment composition, not support for two +alternative application configuration layouts. Source-relative resource context +must continue to follow the effective contributing field. + +PromptKit owns validation of its section, not sibling application settings. +Implementation planning must verify the ConfigKit loading boundary so that +unrelated application sections can coexist without PromptKit interpreting or +rejecting their contents. Keep field validation within PromptKit's section. + +Implementation planning must cover: + +- Updating bundled underlays, source helpers, import destinations, identity + registrations, normalization, and validation to the new paths using ordinary + ConfigKit composition. +- Reflecting nested paths in configuration inspection and diagnostics while + preserving resource inspection and runtime IDs. +- Migration guidance for application documents and explicit import destinations, + including schema roots; standalone fragments should not need extra wrappers. +- Focused coverage for sibling application settings, mounted collections and + resources, default overlays, and source-relative message/schema resolution. + +No product decisions remain open for these two items. Concrete API shapes and +loader integration remain implementation-planning work. ## Further Candidates