base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Record PromptKit adoption scope and completion criteria

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-04 17:09:47 +00:00
parent 4f851371da
commit ee0debe4fb
2 changed files with 145 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
docs/roadmap/future.md
View File

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

208
docs/roadmap/promptkit-v0.18.0.md
View File

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