Record PromptKit adoption scope and completion criteria
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user