Plan PromptKit 0.18 adoption
This commit is contained in:
@@ -23,22 +23,12 @@ an idea here does not select its syntax, API, priority, or delivery date.
|
||||
|
||||
### ckprompt dependency migration and workspace alignment
|
||||
|
||||
Review the upstream PromptKit vanity release and select compatible ConfigKit
|
||||
and PromptKit dependencies before migrating ckprompt's adapters and maintained
|
||||
composed consumer. The new ckconfig uses vanity ConfigKit types; ckprompt v0.2.0
|
||||
still uses published ckconfig v0.2.0 and old-path ConfigKit v0.8.0. Their local
|
||||
sources do not currently compose in the three-module workspace. See the
|
||||
[consumer guide](../consumers/guide.md#module-selection) for the current module
|
||||
relationship.
|
||||
|
||||
The follow-up includes migrating affected imports and public type boundaries,
|
||||
selecting real released dependency versions and the required Go minimum,
|
||||
updating notices and migration guidance, and validating both ckprompt's
|
||||
independent graph and the aligned composed consumer. Restore three-module
|
||||
workspace guidance when those dependencies align, updating the ignored workspace
|
||||
Go version as needed. Until then, preserve local workspace files and validate
|
||||
with workspace discovery off as described in the [development guide](../development.md).
|
||||
No unreviewed PromptKit version or new compatibility bridge is selected here.
|
||||
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.
|
||||
|
||||
## Future capability targets
|
||||
|
||||
|
||||
247
docs/roadmap/promptkit-v0.18.0.md
Normal file
247
docs/roadmap/promptkit-v0.18.0.md
Normal file
@@ -0,0 +1,247 @@
|
||||
# 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 and the maintained example's
|
||||
bundle policy have recommendations under [Open Decisions](#open-decisions).
|
||||
|
||||
## Purpose and authority
|
||||
|
||||
Adopt PromptKit's vanity module and current public APIs in the embedded
|
||||
`ckprompt` integration, using the now-published ckconfig v0.3.0. Restore a
|
||||
compatible three-module development workspace and composed consumer.
|
||||
|
||||
PromptKit and ConfigKit own their domain functionality and semantics.
|
||||
CommandKit owns faithful adaptation, command selection and coordination,
|
||||
presentation, and invocation outcomes. Expose upstream capabilities in a
|
||||
neutral, consistent way, without adding independent guarantees or qualifying
|
||||
upstream limitations. Application loaders retain engine construction and
|
||||
configuration choices.
|
||||
|
||||
The [architecture](../policy/architecture.md), [agent](../policy/agents.md),
|
||||
[testing](../policy/testing.md), [documentation](../policy/documentation.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.
|
||||
|
||||
## Baseline and review evidence
|
||||
|
||||
Reviewed CommandKit revision: `eeae10fa0558bce8de963010fdcea2c40ef68691`.
|
||||
|
||||
| Component | Current state |
|
||||
| --- | --- |
|
||||
| ckprompt | `go.maximumdirect.net/ckprompt v0.2.0`; Go 1.26.0 minimum |
|
||||
| PromptKit dependency | `gitea.maximumdirect.net/eric/promptkit v0.16.0` |
|
||||
| ConfigKit dependency | `gitea.maximumdirect.net/eric/ConfigKit v0.8.0` |
|
||||
| CommandKit dependencies | Core v0.3.0 and ckconfig v0.2.0 |
|
||||
| Available ckconfig | v0.3.0, with vanity ConfigKit v1.1.0 and Go 1.27.0 |
|
||||
| Maintainer toolchain | Go 1.27.0; root ReleaseKit v0.9.0 |
|
||||
|
||||
Direct module discovery verified PromptKit v0.18.0 at published commit
|
||||
`d9f6aad30509e538fc73ea16710df3a3ec084502`. Its module requires Go 1.27.0 and
|
||||
vanity ConfigKit v1.1.0. Published ckconfig v0.3.0 downloads through its vanity
|
||||
path and selects that same ConfigKit identity. The current ckprompt still
|
||||
selects ckconfig v0.2.0 independently and cannot compose with local ckconfig
|
||||
v0.3.0 in the development workspace.
|
||||
|
||||
The upstream [v0.17 migration notes](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/docs/releases/v0.17.0.md),
|
||||
[v0.18 release notes](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/docs/releases/v0.18.0.md),
|
||||
and [configuration/API migration guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/docs/consumers/configuration-migration.md)
|
||||
own the upstream changes crossed by this upgrade.
|
||||
|
||||
A disposable migration established the following, without changing repository
|
||||
code or using local dependency replacements:
|
||||
|
||||
- Changing dependencies and imports alone fails at four production accesses to
|
||||
removed prompt-version metadata.
|
||||
- After removing that metadata, production packages build on Go 1.27.0 against
|
||||
published ckconfig v0.3.0, ConfigKit v1.1.0, and PromptKit v0.18.0.
|
||||
- After converting the composed example's PromptKit resources to identified
|
||||
lists, its profile catalog, source inventory, requirements inspection, and
|
||||
configuration validation run successfully. The native bundle appears in
|
||||
catalogs and as source evidence through ckconfig's current report path.
|
||||
- The full suite still needs version-fixture, configuration-shape, and report
|
||||
expectation changes. These diagnostics do not establish completed adoption.
|
||||
|
||||
## Targeted end state
|
||||
|
||||
### Modules and Go compatibility
|
||||
|
||||
Prepare ckprompt v0.3.0 with this dependency set, subject to OD-1 for the final
|
||||
PromptKit release pin:
|
||||
|
||||
| Requirement | Target |
|
||||
| --- | --- |
|
||||
| PromptKit | `go.maximumdirect.net/promptkit v0.18.0` as reviewed baseline |
|
||||
| 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` |
|
||||
| ckprompt consumer minimum | Go 1.27.0 |
|
||||
|
||||
Production code, tests, and the maintained composed example use the matching
|
||||
vanity identities. Public callbacks and provider values exchange those types
|
||||
consistently. Authentic module metadata and sums select released dependencies;
|
||||
an old-path bridge or a permanent local replacement is unnecessary.
|
||||
|
||||
Core remains independent of the optional libraries and retains its own Go
|
||||
minimum. The already-migrated ckconfig and root ReleaseKit selection need no
|
||||
upgrade for this target. The existing Go 1.27.0 maintainer toolchain is suitable.
|
||||
|
||||
### Existing commands and faithful report adaptation
|
||||
|
||||
Keep the existing engine adapters, five catalogs, named inspections, requirements
|
||||
discovery, request validation, smoke testing, and configuration scope/comparison.
|
||||
The reviewed public methods remain suitable; adopting v0.18.0 does not require
|
||||
a new command family or a second domain implementation.
|
||||
|
||||
Remove the descriptive prompt-version output that upstream removed:
|
||||
|
||||
- Prompt-catalog entries retain prompt ID and lose their optional `version`.
|
||||
- Prompt inspection and requirements inspection lose their `version` member;
|
||||
prompt text inspection also loses the prompt-version line.
|
||||
- Smoke-target reports lose their optional prompt `version` member.
|
||||
|
||||
Remove the associated DTO fields and projection logic rather than manufacturing
|
||||
replacement values. Prompt IDs and opaque hashes retain their native meanings.
|
||||
Collection release labels, source specification headers, and unrelated
|
||||
application version fields are distinct and retain their owning semantics.
|
||||
This is a deliberate pre-v1 report/API migration, described in the release note.
|
||||
|
||||
Configuration inspection now supplies recorded normalized values and derived
|
||||
defaults through ConfigKit v1.1.0. Existing config reports, explanation, and native
|
||||
comparison expose that evidence through ckconfig v0.3.0, including source
|
||||
fallback, version evidence, and empty-import selections. Preserve the returned
|
||||
history and values; do not reconstruct the former authored-only view. Native
|
||||
effective-value diffs retain atomic lists. Configuration inspection, profile
|
||||
inspection, and request preparation remain their respective upstream views.
|
||||
|
||||
### Configuration, bundle behavior, and maintained consumers
|
||||
|
||||
Migrate PromptKit-owned root and collection `prompts`, `profiles`, and `backends`
|
||||
to lists with explicit `id` values. Convert calls to `ProfileSource` and
|
||||
`BackendSource` to ordered record slices where used. Update inheritance and
|
||||
configuration-inspection paths to the new shapes. Link consumer guidance to
|
||||
upstream for whole-record replacement, source-root `config` controls, import
|
||||
requiredness, and optional version-2 specification headers.
|
||||
|
||||
Remove maintained-example plumbing whose only role was carrying PromptKit's
|
||||
removed descriptive version. Preserve independently meaningful application
|
||||
fields and collection `release_version` labels. Do not globally delete every
|
||||
configuration member named `version` or rewrite application schema versions.
|
||||
|
||||
PromptKit v0.18.0 includes a default-on OpenRouter backend and seventeen root
|
||||
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.
|
||||
|
||||
Existing offline test and smoke-example boundaries remain applicable. Use
|
||||
explicit native selections and injected clients/transports as appropriate to
|
||||
the fixture; account for bundled diagnostic fallback rather than accidentally
|
||||
directing a default test at a live provider. This changes fixture wiring, not
|
||||
the native capabilities made available to operators.
|
||||
|
||||
### Workspace, documentation, and release preparation
|
||||
|
||||
Independent module validation uses the real downloaded dependency graph with
|
||||
workspace discovery off. Once ckprompt's types align, the ignored workspace can
|
||||
again compose root, ckconfig, and ckprompt, with a workspace Go version that
|
||||
supports its Go 1.27.0 members. Restore aligned-workspace development guidance
|
||||
and validate the maintained composed consumer with that local module set too.
|
||||
|
||||
Current GoDoc, CLI reports, README/module-selection guidance, maintained example
|
||||
instructions, and attribution describe the implemented dependency set and
|
||||
migration. Preserve published notes and historical records. Prepare a ckprompt
|
||||
v0.3.0 note and full tag `integrations/ckprompt/v0.3.0`, subject to the existing
|
||||
fresh-version guards. A pre-v1 minor accommodates the deliberate type-identity,
|
||||
configuration, report, and minimum-Go changes.
|
||||
|
||||
Publication and hosted Gitea delivery remain separate operations under the
|
||||
[release procedure](../release.md). Preparing this roadmap does not publish a
|
||||
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
|
||||
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.
|
||||
2. Update native API uses and remove prompt-version DTOs, output, and obsolete
|
||||
version-only tests. Preserve meaningful adapter assertions and the remaining
|
||||
report fields, provider capabilities, diagnostics, and outcome coordination.
|
||||
3. Migrate maintained configuration fixtures, programmatic resource builders,
|
||||
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
|
||||
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
|
||||
consumer, and perform appropriate core/ckconfig regression checks. Preserve
|
||||
checks of help/preflight acquisition, selectors, aliases, repeated invocation
|
||||
state, cancellation, writer failures, and supported native error identity.
|
||||
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 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.
|
||||
|
||||
## Upstream remediation boundary
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Open Decisions
|
||||
|
||||
### OD-1: Ship on v0.18.0 or await relevant upstream corrections?
|
||||
|
||||
**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.
|
||||
|
||||
**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.
|
||||
|
||||
### OD-2: Which bundle policy should the maintained example demonstrate?
|
||||
|
||||
**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.
|
||||
|
||||
**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.
|
||||
Reference in New Issue
Block a user