commandkit/docs/roadmap/promptkit-v0.18.0.md

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