From ee0debe4fb6cf6732057f4dfd2ae97480efa3882 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 4 Nov 2026 17:09:47 +0000 Subject: [PATCH] Record PromptKit adoption scope and completion criteria --- docs/roadmap/future.md | 66 +++++++++- docs/roadmap/promptkit-v0.18.0.md | 208 ++++++++++++------------------ 2 files changed, 145 insertions(+), 129 deletions(-) diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 13b8b1a..5539ac6 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -24,13 +24,21 @@ an idea here does not select its syntax, API, priority, or delivery date. ### ckprompt dependency migration and workspace alignment The [PromptKit v0.18.0 adoption roadmap](promptkit-v0.18.0.md) owns the proposed -dependency set, API/report and fixture migration, workspace alignment, and open -release, example, and capability scope choices. The current ckprompt v0.2.0 still +dependency set, API/report and fixture migration, workspace alignment, scope +decisions, and completion evidence. The current ckprompt v0.2.0 still uses published ckconfig v0.2.0 and old-path ConfigKit v0.8.0; it does not compose with local ckconfig v0.3.0. See the [consumer guide](../consumers/guide.md#module-selection) and [development guide](../development.md) for current module and workspace use. +### Later PromptKit release review + +The current adoption develops only against PromptKit v0.18.0 as released. +Review v0.19.0 separately once it is published; do not inspect or monitor +unreleased upstream work in anticipation of that review. A later released +version requires its own contract and compatibility assessment before selection +and does not delay completion of the v0.18.0 adoption. + ## Future capability targets ### Comparison extensions @@ -58,7 +66,11 @@ ConfigKit's public APIs own the evidence and its semantics. records without recreating upstream provenance logic. Historical enumeration is not an exhaustive inventory of possible schema fields. This gives the earlier field-origin inventory proposal a concrete, upstream-backed scope; - command names, selectors, and report shapes remain to be designed. + command names, selectors, and report shapes remain to be designed. For + PromptKit, design this shared optional ckconfig capability first, then wire + `ConfigurationInspection.Metadata()` through `ckprompt.ConfigScope`. This is + PromptKit adoption OD-3; it does not require a separate provenance model or a + new core API. - **Failed-load source inventory (OD-4).** Present acquired source evidence from `LoadError.Sources()` while retaining the failed outcome and diagnostics. Design how an adapter returns its source facet on error and how result output @@ -84,6 +96,52 @@ recording remain available through application loaders. Standard inspection of resource contexts or secrets-directory bootstrap has no immediate proposal; those capabilities primarily serve application loading and startup. +### PromptKit inspection and selection extensions + +The [PromptKit adoption scope](promptkit-v0.18.0.md#scope-decisions) defers these +capabilities beyond the v0.18.0 compatibility migration. Shared configuration +metadata remains the recommended next functional sprint, under +[configuration inspection extensions](#configuration-inspection-extensions). +The OD identifiers below belong to the PromptKit adoption roadmap, separately +from the ConfigKit review identifiers above. + +- **Prepared-request inspection (PromptKit OD-4).** Consider an optional provider + and report based on the released native `Engine.Prepare` and `PreparedRun`, + reusing the concrete request-builder pattern. This would extend standard + inspection into rendering and needs an explicit scope decision. The snapshot + offers selected resource IDs, effective settings, output/schema metadata, + messages, session ID, hashes, and timing without a model call. Its `Messages` + contain complete rendered and appended messages; its effective execution + settings exclude resolved API-key values. Select report content and document + those upstream semantics rather than treating the complete snapshot as an + existing inspection report. Command grammar, callback shape, formats, and the + relationship to request validation remain open. Validate capability + availability, forwarding, projection, and report delivery at CommandKit's + boundary. PromptKit retains preparation and rendering semantics. Keeping this + operation application-owned remains an alternative; model execution and + prepared-handle lifecycle are outside this proposal. +- **Namespace helpers or standard selectors (PromptKit OD-5).** Begin with the + adoption's consumer guidance for loaders returning `Engine.WithNamespaces`. + Consider reusable bindings or helpers when consumers demonstrate repeated + wiring. Design independent prompt/profile/backend defaults, applicable + operations, and their interaction with existing catalog filters together. + Namespace views resolve unqualified caller selections; they do not rewrite + captured configuration references or global configuration inspection, and + namespace/collection inventories remain global. Preserve the distinction + between name resolution and catalog filtering. No flag names or changed + filtering meanings are selected. +- **Other reusable request bindings.** Consider helpers for native request + options only where consumers repeat wiring. Execution/output-validation + overrides, session IDs, appended messages, and retry settings are already + reachable through application request builders; engine options remain + available through loaders. API availability alone does not select a standard + flag or a new core abstraction. + +The released [prepared snapshot](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/types.go) +and [namespace API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/namespaces.go) +provide the reviewed upstream contracts. These proposals establish no new +provider requirement, delivery date, or adoption completion condition. + ### Alias completion and discovery The delivered [shell completion feature](../cli.md#shell-completion) provides @@ -139,7 +197,7 @@ operator or consumer need and an appropriate ownership/behavior decision: injection, and concurrent-dispatch guarantees. Execution, rendering, serving, and session operations remain application-owned. -The [prepared-request inspection proposal](promptkit-v0.18.0.md#od-4-add-prepared-request-inspection-to-the-standard-suite) +The [prepared-request inspection proposal](#promptkit-inspection-and-selection-extensions) would extend standard inspection into rendering and remains an open scope choice. Shared vocabulary is guidance under [ADR 0006](../adr/0006-command-grammar.md). Backend replacement remains possible behind the accepted facade, subject to the diff --git a/docs/roadmap/promptkit-v0.18.0.md b/docs/roadmap/promptkit-v0.18.0.md index 9ef85bf..22ff710 100644 --- a/docs/roadmap/promptkit-v0.18.0.md +++ b/docs/roadmap/promptkit-v0.18.0.md @@ -1,10 +1,11 @@ # PromptKit v0.18.0 adoption -Status: proposed; implementation has not begun. This roadmap captures the -ckprompt migration and workspace alignment target. PromptKit v0.18.0 is the -reviewed working baseline. Final release selection, the maintained example's -bundle policy, and optional capability scope have recommendations under -[Open Decisions](#open-decisions); those choices remain open. +Status: adoption scope recorded; implementation has not begun. Released +PromptKit v0.18.0 is the sole development target, as directed by the user. +[Scope decisions](#scope-decisions) record that dependency choice and the +recommended example policy and capability scope. The +[completion checklist](#completion-checklist) separates implementation evidence +from publication and deferred enhancements. ## Purpose and authority @@ -108,12 +109,11 @@ ownership. OD-4 addresses only the proposed rendering-inspection extension. ### Modules and Go compatibility -Prepare ckprompt v0.3.0 with this dependency set, subject to OD-1 for the final -PromptKit release pin: +Prepare ckprompt v0.3.0 against this released dependency set under OD-1: | Requirement | Target | | --- | --- | -| PromptKit | `go.maximumdirect.net/promptkit v0.18.0` as reviewed baseline | +| PromptKit | `go.maximumdirect.net/promptkit v0.18.0` as released | | ConfigKit | `go.maximumdirect.net/configkit v1.1.0` | | ckconfig | `go.maximumdirect.net/ckconfig v0.3.0` | | Core | Retain `go.maximumdirect.net/commandkit v0.3.0` | @@ -175,7 +175,13 @@ profiles as a lowest-priority underlay. Catalogs, namespaces, configuration, and source reports follow the supplied engine's native inventory. The integration does not silently filter those definitions or disable the bundle. Applications can select `WithBundledOpenRouter(false)` in their own engine loaders. -OD-2 addresses that choice for the maintained composed example and fixtures. +Under OD-2, retain the default bundle in the maintained composed example. +Focused fixture loaders may explicitly opt out when their purpose requires a +minimal application-only inventory. Include focused coverage showing that +bundled records and their source evidence reach CommandKit output; assertions +about application records alone would not detect accidental bundle filtering. +Use returned native evidence without duplicating the full bundled catalog or +fixing expectations to its count. Existing offline test and smoke-example boundaries remain applicable. Use explicit native selections and injected clients/transports as appropriate to @@ -204,8 +210,8 @@ version or select new release gates. ## Work from the baseline -1. Record the working dependency baseline and resolve OD-2's example policy; - carry OD-1's final shipping choice into release preparation. Prepare the +1. Use released PromptKit v0.18.0 under OD-1 and the recommended default-bundle + example policy under OD-2. Prepare the ckprompt dependency/import and Go-minimum changes with the selected Go 1.27 toolchain, then tidy and inspect authentic metadata with workspace discovery off. Review the effective graph for attribution, including tool requirements. @@ -216,8 +222,9 @@ version or select new release gates. inheritance references, list-index paths, and composed-example plumbing. Apply the selected bundle policy explicitly in fixture-owned loaders. 4. Update focused tests for request forwarding and faithful native-result - projection. Account for normalized inspection values and native inventories; - test the CommandKit adaptation rather than independently establishing bundle + projection, including bundled records and source evidence reaching output. + Account for normalized inspection values and native inventories; test the + CommandKit adaptation rather than independently establishing bundle contents, normalization rules, inheritance, or provider behavior. 5. Run the full ckprompt suite and maintained example tests against its own declared dependencies. Validate the restored local workspace and composed @@ -231,126 +238,77 @@ version or select new release gates. native namespace-view loader guidance while keeping standard selector design separate. -The native adapter structure remains the starting point. OD-3 through OD-5 are -unselected scope choices, not additional adoption completion conditions. The -recommended sequence is dependency/report and workspace migration, then shared -metadata inspection, followed by separately selected prepared-request -inspection. Namespace loader guidance can accompany migration documentation. -The detailed-comparison, failed-load-inventory, and structured-diagnostic -proposals in future work remain separate too. If capability scope is expanded -into this release, revise the dependency target, implementation work, validation, -and release documentation to match that decision before implementation. +The native adapter structure remains the starting point. This sprint covers +dependency, API/report, fixture, and workspace migration plus namespace-loader +guidance. Core APIs and its Go minimum remain unchanged. Shared metadata, +prepared-request inspection, and reusable namespace helpers or standard selectors +are deferred to [future work](future.md#promptkit-inspection-and-selection-extensions). +The shared detailed-comparison, failed-load-inventory, and structured-diagnostic +proposals remain separate too. -## Upstream remediation boundary +## Released upstream baseline -Post-release audit notes in the sibling PromptKit checkout identify issues in -the same production source as v0.18.0. Relevant examples include unrestricted -authentication-response buffering in the -[native authentication probe](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/internal/usecase/smoke_authentication.go) -and inference request-construction errors reported as concluded diagnostics by -the [native smoke tester](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/internal/usecase/smoke_tester.go). -Those findings inform OD-1; the disposable CommandKit review did not reproduce -the full upstream audit set. +Develop and validate only against PromptKit v0.18.0 as released. Unreleased +upstream branches, sibling-checkout changes, audit notes, and proposed fixes do +not inform this adoption's implementation, scope, or release criteria. The +migration does not wait for upstream development or introduce local workarounds +for anticipated changes. -Keep domain corrections upstream. This adoption does not add local response -limits, duplicate request validation, or replacement error classification to -compensate for those defects. Evaluate any published corrective release for -compatibility and adapt to its public contract using ordinary change review. +PromptKit v0.19.0 may be reviewed once it is available as a published release. +That is a separate dependency review of its released contracts and changes; +it does not automatically change this roadmap's v0.18.0 target. No investigation +or monitoring of unreleased work is part of this adoption. -## Open Decisions +## Scope decisions -### OD-1: Ship on v0.18.0 or await relevant upstream corrections? +OD-1 records the user's explicit dependency direction. OD-2 through OD-5 record +the recommended scope for this sprint; deferred capabilities still require +focused API and CLI design. These decisions do not describe implemented features +or authorize publication. -**Recommendation:** develop the migration now against the published v0.18.0 -baseline and prefer a published corrective release addressing the relevant -native diagnostic issues for the final shipping pin. That keeps integration -work concrete while keeping fixes with their upstream owner. Taking a newer -release requires reviewing its actual changes and rerunning affected checks; -waiting for corrections can delay ckprompt publication. Whether to publish on -v0.18.0 if those corrections are not yet available remains a release choice. +| Decision | Disposition | Implementation consequence | +| --- | --- | --- | +| OD-1: Upstream baseline | Develop only against released PromptKit v0.18.0. Review v0.19.0 separately once published. | Use the pinned released dependency set; do not consider unreleased upstream work or wait for it. | +| OD-2: Example bundle policy | Retain the upstream default bundle in the composed example; opt out explicitly in focused minimal fixtures. | Verify bundled records and source evidence reach output, without asserting the complete catalog or count. Keep smoke fixtures on explicit offline targets. | +| OD-3: Shared metadata | Defer to the next shared functional sprint. | Design the optional ckconfig capability first, then forward PromptKit's native metadata. Retain ckconfig v0.3.0 for adoption. | +| OD-4: Prepared-request inspection | Defer to a separate design decision after adoption and shared metadata. | Select report content and the rendering scope explicitly before adding a provider or command. | +| OD-5: Namespace support | Include loader guidance now; defer reusable helpers and standard selectors. | Explain independent namespace defaults and keep unqualified-name resolution distinct from catalog filtering. | -**Viable alternative:** finish and publish the ckprompt migration with exactly -v0.18.0 using the existing release workflow, then adopt an upstream correction -separately. This restores the compatible module set without an upstream-dependent -schedule. It ships with the recorded native defects still present and requires -a later dependency update. Neither option selects local workarounds or makes -completion of every upstream audit finding a new release prerequisite. +The [future capability record](future.md#promptkit-inspection-and-selection-extensions) +owns the deferred PromptKit feature proposals and their design considerations. +Application loaders continue to own engine construction and bundle choices; +request builders continue to expose native request options without requiring a +standard flag for each one. -### OD-2: Which bundle policy should the maintained example demonstrate? +## Completion checklist -**Recommendation:** retain upstream's default bundle in the composed example -and make catalog/report assertions about the application-defined records and -returned native evidence rather than duplicating the complete bundled catalog. -Use explicit opt-out in focused fixture loaders when their purpose is a minimal -application-only inventory. This demonstrates the current native default while -keeping adapter tests focused. Example inventories and list-index paths need -updating, and offline smoke wiring must still select the intended fixture target. +Record evidence against the final implementation, separately from the earlier +disposable review. Implementation is complete when: -**Viable alternative:** opt out explicitly in the composed example with -`WithBundledOpenRouter(false)`. This is a supported application-loader choice -that keeps the example's inventory small and its resource positions simple. -It does not demonstrate the default-on inventory; documentation should state -the example's choice, and focused adoption coverage should still show that the -integration exposes a default-constructed engine's returned bundle evidence. +- [ ] ckprompt declares PromptKit v0.18.0, ConfigKit v1.1.0, ckconfig v0.3.0, + and core v0.3.0 through their vanity paths, with Go 1.27.0 and authentic sums. + Production code, tests, and the composed example exchange matching types. +- [ ] Reports omit removed descriptive prompt-version fields while preserving + collection release labels, source headers, and unrelated application versions. + Native normalized inspection values and source evidence remain faithfully + projected through existing adapters. +- [ ] Fixtures and resource builders use the adopted configuration shapes; + the composed example retains the default bundle, focused output checks cover + bundle evidence, and smoke tests use their intended offline targets. +- [ ] The full ckprompt suite and maintained example tests pass independently + with workspace discovery off and read-only module metadata on Go 1.27.0. +- [ ] The aligned three-module workspace and composed consumer pass validation, + with appropriate core/ckconfig regression checks. Preserve the ignored local + workspace, update its Go version as needed, and restore development guidance. + No workspace files or local dependency replacements enter the release. +- [ ] Current GoDoc, CLI report contracts, consumer/example guidance (including + namespace views), notices, and the ckprompt v0.3.0 candidate note match the + implemented migration. Markdown links, fragments, examples, and whitespace + have been reviewed. +- [ ] Final validation evidence and remaining deferred features are recorded. + Source publication and hosted delivery are tracked separately under the + existing release procedure. -### OD-3: Include shared metadata inspection in adoption or a later sprint? - -**Recommendation:** retain metadata inspection as the next shared functional -sprint after dependency adoption. The -[configuration inspection proposal](future.md#configuration-inspection-extensions) -owns the field metadata, path discovery, and history scope. Design the optional -ckconfig provider capability and reports once, then connect PromptKit's native -`Metadata()` result. Existing providers remain usable without the new facet. -Preserve upstream field presence, explicitness, origins, and history, including -history for removed paths; do not recreate provenance logic within ckprompt. - -**Viable alternative:** include the shared capability and PromptKit wiring in -this adoption release. That expands the work beyond dependency alignment and -requires a newly released ckconfig version containing the capability, replacing -the current v0.3.0 target. Command grammar, selectors, report shapes, and provider -design remain open under the shared proposal. The adoption can ship without -this extension while retaining ckconfig v0.3.0. - -### OD-4: Add prepared-request inspection to the standard suite? - -**Recommendation:** treat this as the next substantive ckprompt enhancement -after adoption and shared metadata inspection, with an explicit decision to -extend standard inspection into rendering. Add an optional provider capability -and report based on native `Engine.Prepare` and `PreparedRun`, reusing the -concrete request-builder pattern. The native snapshot supplies selected -prompt/profile/backend IDs, effective execution settings, rendered messages and -session ID, output contract and schema metadata, input and rendered hashes, and -preparation timing without calling an LLM. PromptKit owns preparation semantics. - -Command grammar, callback shape, selected report content and formats, and the -relationship to existing request validation remain open. Any selected feature -needs acquisition/availability, request forwarding, native-result projection, -and report-delivery coverage at CommandKit's boundary; upstream retains tests -of preparation and rendering. Selecting snapshot inspection would not select -model execution or prepared-handle management. - -**Viable alternatives:** retain preparation inspection in application-owned -commands, or deliberately include the optional feature in ckprompt v0.3.0 after -resolving that design. The latter expands the release scope and validation; -neither alternative requires local template resolution or a parallel preparation -implementation. No new command or provider contract is selected here. - -### OD-5: Document namespace views or add standard selection support? - -**Recommendation:** begin with consumer guidance showing an application engine -loader returning `Engine.WithNamespaces` with independently chosen prompt, -profile, and backend defaults. Applications can already combine their typed -selectors and loaders for this purpose. Include that guidance with migration -documentation; consider a reusable helper or standard selectors when concrete -consumers show repetition that CommandKit could remove. - -Namespace views resolve unqualified caller selections. Qualified selections -retain their native treatment; captured configuration references and global -configuration inspection are not rewritten, and namespace/collection inventories -remain global. Existing catalog filtering keeps its current meaning. - -**Viable alternative:** design standard namespace-selection bindings or a helper -as part of this release. The public API, applicable operations, independent -resource defaults, and interaction with catalog filtering would need explicit -decisions and focused forwarding coverage. No new flag names or changed meaning -for existing namespace filters are selected by this roadmap. +The checklist records completion evidence; it does not add publication gates +or require implementing deferred features. No core API change is planned for +this adoption.