From 4f851371da59b8611fc5916a958d488542dbf176 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 4 Nov 2026 16:54:29 +0000 Subject: [PATCH] Record PromptKit capability options and scope decisions --- docs/roadmap/future.md | 11 ++- docs/roadmap/promptkit-v0.18.0.md | 125 ++++++++++++++++++++++++++++-- 2 files changed, 124 insertions(+), 12 deletions(-) diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 895349c..13b8b1a 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -25,10 +25,11 @@ an idea here does not select its syntax, API, priority, or delivery date. 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 choices. 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. +release, example, and capability scope choices. 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. ## Future capability targets @@ -138,6 +139,8 @@ 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) +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 published API/CLI contracts and deliberate compatibility decisions. diff --git a/docs/roadmap/promptkit-v0.18.0.md b/docs/roadmap/promptkit-v0.18.0.md index 50aa594..9ef85bf 100644 --- a/docs/roadmap/promptkit-v0.18.0.md +++ b/docs/roadmap/promptkit-v0.18.0.md @@ -2,8 +2,9 @@ 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 and the maintained example's -bundle policy have recommendations under [Open Decisions](#open-decisions). +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. ## Purpose and authority @@ -23,8 +24,10 @@ The [architecture](../policy/architecture.md), [agent](../policy/agents.md), [release](../policy/release.md), and [OSS](../policy/oss.md) policies govern the work. Current behavior remains owned by Go declarations and GoDoc, the [CLI reference](../cli.md), and the [consumer guide](../consumers/guide.md). -The other inspection proposals in [future work](future.md#configuration-inspection-extensions) -remain separate from this dependency adoption. +The shared inspection proposals in +[future work](future.md#configuration-inspection-extensions) retain their own +scope. This roadmap records how PromptKit could use that work and identifies +additional capabilities without selecting them as adoption requirements. ## Baseline and review evidence @@ -65,6 +68,42 @@ code or using local dependency replacements: - The full suite still needs version-fixture, configuration-shape, and report expectation changes. These diagnostics do not establish completed adoption. +## API coverage and capability candidates + +A follow-up review compared the published v0.18.0 API with ckprompt at +CommandKit revision `69cc642`. Existing report shapes cover the current prompt, +profile, requirements, catalog, and smoke inspection results after removing +obsolete prompt-version fields. Smoke reports already carry the native facts, +timing, attempts, and usage; the review found no additional report fields to add +in those operations. + +Three capabilities merit consideration beyond compatibility migration: + +| Capability | Current integration | Recommendation and scope decision | +| --- | --- | --- | +| Configuration metadata and history | Native `ConfigurationInspection.Metadata()` returns ConfigKit metadata. `ConfigScope` connects effective configuration, sources, explanations, and comparison, but has no metadata facet. | Extend the shared optional ckconfig capability first, then connect PromptKit's native metadata. Keep this as the next shared enhancement following adoption; see OD-3. | +| Prepared-request inspection | Native `Engine.Prepare` returns a `PreparedRun` snapshot. ckprompt exposes concrete request validation but has no operation returning preparation results. | Consider an optional provider capability and report as the next substantive ckprompt enhancement. This extends standard inspection into rendering and needs an explicit scope choice; see OD-4. | +| Namespace selection helpers | Native `Engine.WithNamespaces` supplies separate prompt, profile, and backend namespace defaults for unqualified selections. Applications can already return that view from an engine loader. Existing standard namespace selectors filter catalogs. | Begin with documented loader wiring; consider reusable helpers or standard selectors when consumers demonstrate repeated wiring. Keep name resolution distinct from catalog filtering; see OD-5. | + +The released [configuration inspection API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/configuration_inspection.go), +[preparation API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/engine.go), +[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) +own those capabilities. They are available in v0.18.0; this review does not imply +that each was introduced in that release. + +Request execution and output-validation overrides, session IDs, appended +messages, and retry settings are already reachable through application request +builders. Engine construction and bundle options remain available through +loaders. Consider reusable bindings where consumers repeat the same wiring; +adoption does not require a standard flag for every native option. + +`Run`, `PrepareExecution`, `RunPrepared`, and execution observers serve the +application-owned execution workflow. Prepared-request inspection can use +`Prepare` without adding model generation or prepared-handle lifecycle to the +standard suite. Execution, serving, and session operations retain their current +ownership. OD-4 addresses only the proposed rendering-inspection extension. + ## Targeted end state ### Modules and Go compatibility @@ -188,11 +227,19 @@ version or select new release gates. 6. Update current contract owners, dependency notices and pinned license/source references, and the candidate release note. Review links, examples, and whitespace. Record final validation and publication status separately from - the earlier disposable review evidence. + the earlier disposable review evidence. Under OD-5's recommendation, include + native namespace-view loader guidance while keeping standard selector design + separate. -The native adapter structure remains the starting point. The deferred metadata, -detailed-comparison, failed-load-inventory, and structured-diagnostic proposals -in future work are not completion conditions for this adoption. +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. ## Upstream remediation boundary @@ -245,3 +292,65 @@ 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. + +### 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.