Retire completed PromptKit planning documents
This commit is contained in:
@@ -8,6 +8,9 @@ No delivery dates are selected here.
|
||||
Completed roadmaps, implementation plans, and review findings have been retired.
|
||||
This document preserves unfinished work and unselected ideas under the
|
||||
[release policy](../policy/release.md#release-documentation-and-preparation).
|
||||
The completed PromptKit v0.18.0 adoption roadmap and implementation plan remain
|
||||
available in the
|
||||
[PromptKit retirement snapshot](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/540e2359d66d604a563df0be1c9fc961588f5b9c/docs/roadmap).
|
||||
The completed ConfigKit adoption, reporting, dependency alignment, release-tooling,
|
||||
and remediation records remain available at the
|
||||
[retirement snapshot](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/260256d722f52bc947103d078cb67a129f4cc9f1/docs/roadmap).
|
||||
@@ -23,19 +26,20 @@ an idea here does not select its syntax, API, priority, or delivery date.
|
||||
|
||||
### ckprompt release
|
||||
|
||||
The [PromptKit v0.18.0 adoption roadmap](promptkit-v0.18.0.md) records the
|
||||
completed migration and its unpublished ckprompt v0.3.0 candidate. Publication
|
||||
and hosted delivery remain separate operations under the [release procedure](../release.md).
|
||||
The PromptKit v0.18.0 migration is complete. The
|
||||
[ckprompt v0.3.0 candidate](../../integrations/ckprompt/docs/releases/v0.3.0.md)
|
||||
remains unpublished. Publication and hosted delivery remain separate operations
|
||||
under the [release procedure](../release.md).
|
||||
The published ckprompt v0.2.0 retains its earlier dependencies; see the
|
||||
[consumer guide](../consumers/guide.md#module-selection) for module selection.
|
||||
|
||||
### Later PromptKit release review
|
||||
|
||||
The current adoption develops only against PromptKit v0.18.0 as released.
|
||||
The completed adoption used 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.
|
||||
and does not reopen the completed v0.18.0 adoption.
|
||||
|
||||
## Future capability targets
|
||||
|
||||
@@ -96,7 +100,7 @@ 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
|
||||
The [completed PromptKit adoption scope](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/540e2359d66d604a563df0be1c9fc961588f5b9c/docs/roadmap/promptkit-v0.18.0.md#scope-decisions) deferred 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).
|
||||
@@ -118,8 +122,9 @@ from the ConfigKit review identifiers above.
|
||||
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`.
|
||||
- **Namespace helpers or standard selectors (PromptKit OD-5).** The
|
||||
[consumer guidance](../consumers/guide.md#namespace-views) covers 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.
|
||||
|
||||
@@ -1,343 +0,0 @@
|
||||
# PromptKit v0.18.0 implementation plan
|
||||
|
||||
Status: all stages complete; publication and hosted delivery are not performed.
|
||||
|
||||
## Authority and execution
|
||||
|
||||
Implement the target and OD-1 through OD-5 in the
|
||||
[feature roadmap](promptkit-v0.18.0.md#scope-decisions). This plan owns the steps
|
||||
and completion evidence. Read `docs/development.md` and its applicable policies
|
||||
before editing. Use codebase-memory MCP for code discovery as instructed by
|
||||
`AGENTS.md`; fall back to text searches for literals and configuration fixtures.
|
||||
|
||||
The intended implementer is a Luna coding agent. Execute Stage 1 through Stage 7
|
||||
in order as one end-to-end sprint. Intermediate stages may fail to compile or
|
||||
test. Do not introduce compatibility bridges, temporary public APIs, or extra
|
||||
commits merely to make intermediate stages green. Follow the repository's local
|
||||
commit policy for completed, reviewable units; final validation covers the whole
|
||||
sprint. Record stage progress and final evidence here as work proceeds.
|
||||
|
||||
Develop only against released PromptKit v0.18.0. Its reviewed source commit is
|
||||
`d9f6aad30509e538fc73ea16710df3a3ec084502`; use its downloaded module, GoDoc, and
|
||||
the pinned migration/release references in the feature roadmap. Do not inspect
|
||||
unreleased upstream or sibling-checkout development. Upstream owns domain
|
||||
semantics and their tests; CommandKit owns forwarding, coordination, reporting,
|
||||
and outcomes. Expose the adopted public contract neutrally.
|
||||
|
||||
The sprint adds no core API or command, metadata/history facet, prepared-request
|
||||
inspection, namespace helper, or standard namespace selector. Those capabilities
|
||||
remain in [future work](future.md#promptkit-inspection-and-selection-extensions).
|
||||
Namespace-loader consumer guidance is included. Publication, tagging, pushing,
|
||||
and hosted delivery are separate from implementation completion and are not
|
||||
authorized by this plan.
|
||||
|
||||
## Baseline and working locations
|
||||
|
||||
Planning baseline: CommandKit `ee0debe` (scope decisions recorded), with a clean
|
||||
worktree. Recheck the actual worktree before implementing and preserve unrelated
|
||||
work. The three modules are repository root, `integrations/ckconfig`, and
|
||||
`integrations/ckprompt`. The composed example is a package inside ckprompt,
|
||||
not a fourth module.
|
||||
|
||||
| Area | Starting points |
|
||||
| --- | --- |
|
||||
| Dependencies | `integrations/ckprompt/go.mod`, `go.sum`; root and ckconfig manifests for comparison |
|
||||
| Native adapters | `integrations/ckprompt/adapters.go`, `smoke.go` (acquisition diagnostics live in `adapters.go`) |
|
||||
| Reports | `integrations/ckprompt/command.go`, `smoke_report.go` |
|
||||
| Adapter and CLI tests | ckprompt `adapters_test.go`, `command_test.go`, `requirements_*test.go`, `validation_*test.go`, `smoke_*test.go`, composition, cancellation, and native-explanation tests |
|
||||
| Maintained consumer | `integrations/ckprompt/examples/composed/main.go`, `main_test.go`, `fixtures/before.yml`, `fixtures/after.yml`, `README.md` |
|
||||
| Current contract owners | `docs/cli.md`, `docs/consumers/guide.md`, ckprompt GoDoc and README, `docs/development.md`, `docs/release.md` |
|
||||
| Notices and candidate | `integrations/ckprompt/docs/oss/attribution.md`, local license texts, `integrations/ckprompt/docs/releases/v0.3.0.md` |
|
||||
|
||||
ckprompt currently selects old-path PromptKit v0.16.0, old-path ConfigKit v0.8.0,
|
||||
and vanity ckconfig v0.2.0. Local ckconfig v0.3.0 already selects vanity ConfigKit
|
||||
v1.1.0. The ignored `go.work` currently declares Go 1.26.10 and includes all
|
||||
three modules. Preserve it and `go.work.sum`; align the workspace only after the
|
||||
module changes. Never read or stage `.releasekit/gitea-token` contents.
|
||||
|
||||
## Stage 1: Align module identities and imports
|
||||
|
||||
**Complete.** Go 1.27.0, dependency preparation, and the declared module graph were verified.
|
||||
|
||||
1. Select Go 1.27.0 on `PATH` using the existing
|
||||
[toolchain instructions](../release.md#release-toolchain). Confirm with
|
||||
`GOWORK=off GOTOOLCHAIN=local go version`. Do not change the root consumer
|
||||
minimum, ckconfig's dependency selection, or the ReleaseKit version.
|
||||
2. In every ckprompt production, test, and example Go import, replace
|
||||
`gitea.maximumdirect.net/eric/promptkit` with
|
||||
`go.maximumdirect.net/promptkit`, and
|
||||
`gitea.maximumdirect.net/eric/ConfigKit` with
|
||||
`go.maximumdirect.net/configkit`. Retain package names and the current core
|
||||
and ckconfig vanity identities. Historical release documents are not import
|
||||
migration targets.
|
||||
3. Edit ckprompt's manifest to declare `go 1.27.0`, remove the two old-path
|
||||
requirements, require vanity PromptKit v0.18.0 and ConfigKit v1.1.0, raise
|
||||
ckconfig to v0.3.0, and retain core v0.3.0. Use `go mod edit` or equivalent
|
||||
explicit edits; do not select `latest` or add a local `replace`.
|
||||
4. From `integrations/ckprompt`, run dependency preparation with
|
||||
`GOWORK=off GOTOOLCHAIN=local go mod tidy` and
|
||||
`GOWORK=off GOTOOLCHAIN=local go mod download`. Keep the
|
||||
actual generated sums and indirect selections, including tool dependencies.
|
||||
If source migration prevents tidying, finish it after Stage 5. Review
|
||||
`GOWORK=off GOTOOLCHAIN=local go list -m all` against the target dependency
|
||||
table; remove stale direct requirements rather than hand-editing sums.
|
||||
|
||||
Stage result: imports and declarations use the intended public type identities.
|
||||
Compilation failures caused by removed version fields and old fixtures are
|
||||
expected until subsequent stages. No dependency replacement is needed.
|
||||
|
||||
## Stage 2: Adapt production reports and their projection tests
|
||||
|
||||
**Complete.** Focused catalog, prompt, requirements, and smoke projection tests pass on Go 1.27.0; native fixtures remain for migration.
|
||||
|
||||
1. In `command.go`, remove the `PromptVersion` members from
|
||||
`promptInspectionReport` and `requirementsInspectionReport`, their projection
|
||||
assignments, and the prompt text formatter's version line. Remove `Version`
|
||||
from `promptCatalogEntry`; `encodePromptCatalog` projects prompt ID only.
|
||||
2. In `smoke_report.go`, remove `PromptVersion` from `smokeTargetDTO` and its
|
||||
native target conversion. These are the four production reads of removed
|
||||
upstream metadata identified in the review. Search for remaining uses of
|
||||
`PromptVersion` and `PromptIdentity.Version`, including composite literals.
|
||||
3. Update synthetic DTO/command tests in `command_test.go`,
|
||||
`requirements_command_test.go`, `smoke_report_test.go`, and other affected
|
||||
report tests. Remove obsolete optional-version-only cases such as
|
||||
`TestOptionalPromptVersionsPreserveAbsenceAndEmptyValues`. Preserve their
|
||||
independent coverage of string encoding, ordering, empty inventories,
|
||||
presence, diagnostics, and delivery where that coverage remains useful.
|
||||
4. Assert the intended report migration at the consumer boundary: prompt
|
||||
catalogs, prompt/requirements YAML, and smoke target YAML omit the removed
|
||||
member, and prompt text omits its version line. Preserve native IDs, hashes,
|
||||
output contracts, profile parameters, smoke facts/timing/attempts/usage, and
|
||||
optional-value semantics. Preserve collection `release_version`, source
|
||||
specification headers, and application identity/version behavior.
|
||||
5. Keep `Suite`, `FromEngine`, `ConfigScope`, request-validation and smoke
|
||||
callbacks, operation availability, selectors, and invocation lifetimes intact
|
||||
except for the necessary upstream import/type migration. Do not add an
|
||||
alternate template engine, local domain validation, bundle filtering, or error
|
||||
taxonomy.
|
||||
|
||||
Stage result: production report projection matches the adopted API. Existing
|
||||
commands and their non-version report data remain available. Old real-engine
|
||||
fixtures may still prevent the full test suite from running.
|
||||
|
||||
## Stage 3: Convert native engine fixtures
|
||||
|
||||
**Complete.** Native fixtures use identified resource lists and explicit minimal bundle choices; focused engine-backed tests pass. Report path expectations remain for Stage 4.
|
||||
|
||||
1. Inspect ckprompt test configurations outside the composed example (Stage 5),
|
||||
including embedded YAML, MapFS files, and programmatic mappings. Start with `adapterEngine` and
|
||||
`adapterEngineFrom` in `adapters_test.go`, then the requirements, validation,
|
||||
smoke, composition/comparison, and native-explanation fixtures that load
|
||||
real engines. Convert PromptKit-owned root and collection resource maps to
|
||||
ordered `prompts`, `profiles`, and `backends` lists with explicit `id` fields.
|
||||
Preserve unrelated application maps and collection namespace mappings.
|
||||
2. Remove descriptive versions from prompt records. Translate resource
|
||||
inheritance, imports, and source-root controls according to the released
|
||||
migration guide: sibling identity references, `config` controls where old
|
||||
`configkit` controls occur, and explicit import requiredness where the test
|
||||
requires a missing import to fail. Retain meaningful source headers. Convert
|
||||
any `ProfileSource`/`BackendSource` map arguments to ordered native record
|
||||
slices with IDs. Do not broaden this into adopting unrelated upstream options.
|
||||
3. For focused tests needing a minimal inventory, explicitly opt out with
|
||||
`WithBundledOpenRouter(false)` in the owning fixture loader. Keep a separate
|
||||
default-constructed fixture for the bundle projection coverage below; do not
|
||||
disable the bundle in production adapters or every fixture indiscriminately.
|
||||
|
||||
Stage result: module test engine inputs use the released shapes and deliberate
|
||||
fixture bundle choices. Existing assertions can still fail until Stage 4.
|
||||
|
||||
## Stage 4: Refresh adapter expectations and bundle coverage
|
||||
|
||||
**Complete.** The ckprompt package suite passes with native normalized reports, and bundled profile and source evidence reach command output.
|
||||
|
||||
1. Adjust configuration path expectations to the new list indexes and returned
|
||||
native normalized values/history. With the bundle enabled, derive relevant
|
||||
records/paths from the returned view rather than assuming application records
|
||||
occupy index zero. Preserve native effective-value diffs, including atomic
|
||||
lists; do not reconstruct authored-only values or merge lists locally.
|
||||
2. Update adapter assertions that read removed version fields. Retain tests
|
||||
proving request, selection, filters, typed input, and context forwarding;
|
||||
load and operation diagnostics; supported native error identity; cancellation;
|
||||
help/preflight without acquisition; independent optional operations; and
|
||||
writer failure handling. Replace obsolete assertions with boundary coverage,
|
||||
not new tests of upstream inheritance, rendering, or validation correctness.
|
||||
3. Add or adapt focused end-to-end coverage comparing returned native bundled
|
||||
records and source evidence with CommandKit catalog/config-source output.
|
||||
Prove a bundled item actually reaches output so accidental filtering would
|
||||
fail the test. Do not copy the full bundled catalog or assert its total count.
|
||||
4. Keep smoke fixtures deterministic and offline. Use explicit application or
|
||||
local-fixture prompt/profile/backend selections and existing injected
|
||||
clients/transports. An injected LLM client covers inference, not arbitrary
|
||||
HTTP probes; retain local transport/server seams for HTTP diagnostics where
|
||||
used. Account for native bundled fallback selection in default smoke requests.
|
||||
|
||||
Stage result: module test fixtures load under v0.18.0, meaningful adapter
|
||||
coverage survives, and bundle forwarding is covered. Run focused affected
|
||||
package tests to guide corrections; full final validation is Stage 7.
|
||||
|
||||
## Stage 5: Migrate the composed consumer and its tests
|
||||
|
||||
**Complete.** The composed suite passes with identified lists, the native bundle, and explicit local smoke targets; the aggregate report was inspected.
|
||||
|
||||
1. In `examples/composed/main.go`, convert the root resources and `field-notes`
|
||||
collection resources assembled by `loadPromptEngine` to identified lists.
|
||||
Preserve qualified stored references such as `field-notes/demo` and
|
||||
`field-notes/assistant`, and preserve the collection's release label.
|
||||
2. Remove campaign `PromptVersion` and the generated prompt `version` members.
|
||||
Remove the now-unused `prompt_version` values from both application YAML
|
||||
fixtures and the default mapping in `loadApplicationConfig`. Retain campaign
|
||||
selection, defaults, models, IDs, application identity, session behavior,
|
||||
request-builder presence handling, and per-run loading/cache behavior. Do not redesign the consumer loader/cache.
|
||||
3. Retain the default native bundle in this example. Update `main_test.go`
|
||||
catalog, config show/explain/diff, requirements, smoke, aliases, and completion
|
||||
expectations for lists, normalized evidence, and version removal. Assert
|
||||
relevant application records without treating the whole native inventory as
|
||||
a fixed snapshot. Keep bundle projection evidence from Stage 4 or add it here
|
||||
if this is the simpler public boundary; avoid duplicate coverage.
|
||||
4. Preserve the existing injected example client and explicit local smoke
|
||||
selections, including aggregate tests. Inspect any default-target calls for
|
||||
native fallback to bundled providers. Keep tests independent of credentials
|
||||
and live services without restricting the operator-facing capabilities.
|
||||
5. Keep namespace-view support as consumer guidance in Stage 6. Do not add new
|
||||
flags, change existing `--namespace` catalog filtering, or silently scope this
|
||||
example's engine as part of migration.
|
||||
|
||||
Stage result: the composed application still demonstrates config and PromptKit
|
||||
families, application commands, aliases, and shared reporting with the aligned
|
||||
public types and native bundle. Its tests remain part of ckprompt's suite.
|
||||
|
||||
## Stage 6: Update current guidance, notices, and the candidate note
|
||||
|
||||
**Complete.** Current guidance, namespace loader wiring, dependency attribution, and the unpublished v0.3.0 candidate note are updated. Local Markdown destinations and fragments were checked.
|
||||
|
||||
1. Update ckprompt GoDoc/README, root README where affected, `docs/cli.md`,
|
||||
`docs/consumers/guide.md`, and the composed example README to match Stage 2's
|
||||
reports and the selected dependency/configuration migration. Replace stale
|
||||
current v0.16 guidance with pinned v0.18 owning references. Preserve old
|
||||
release notes and historical source links as history. Do not globally replace
|
||||
all occurrences of `version` or old URLs.
|
||||
2. Document namespace views in the consumer guide with a small application-owned
|
||||
loader example calling `engine.WithNamespaces(promptkit.Namespaces{...})` and
|
||||
returning its result/error. Show independent prompt/profile/backend defaults.
|
||||
Explain unqualified caller-name resolution, qualified IDs passing through,
|
||||
unchanged stored references/config inspection, and global namespace/collection
|
||||
inventories. Keep catalog filtering distinct. Use released GoDoc for meaning;
|
||||
add no helper, new binding, or standard selector. Check example identifiers
|
||||
and signatures against the adopted module.
|
||||
3. Restore aligned workspace instructions in `docs/development.md` and the
|
||||
consumer guide; remove the temporary warning that local ckprompt cannot
|
||||
compose with local ckconfig. Update minimum-Go descriptions, including
|
||||
`docs/release.md`: core retains Go 1.26.0, both integrations use Go 1.27.0,
|
||||
and the existing maintainer toolchain remains Go 1.27.0.
|
||||
4. Review the actual tidied ckprompt module graph and the selected upstream
|
||||
license/notice files under the OSS policy. Update module-local attribution,
|
||||
exact source/notice commit links, and necessary standard license texts.
|
||||
Remove entries only when their material/dependency is no longer distributed;
|
||||
account for transitive tool requirements as well as runtime packages. Inspect
|
||||
shared root notices for affected facts without changing independent module
|
||||
selections or copying whole notice lists from a sibling checkout.
|
||||
5. Prepare `integrations/ckprompt/docs/releases/v0.3.0.md` with the correct product
|
||||
title, dependency identities, Go minimum, list-configuration migration,
|
||||
removed report fields, native default bundle, and consumer actions. Use the
|
||||
full tag `integrations/ckprompt/v0.3.0` for the immutable footer links to this
|
||||
module's COPYRIGHT, LICENSE, and ATTRIBUTION, following `docs/release.md`.
|
||||
Prepare the candidate only; do not create a tag or hosted page.
|
||||
|
||||
Stage result: current documentation describes implemented behavior, notices
|
||||
reflect the selected graph, and the candidate note explains the pre-v1 changes.
|
||||
Deferred proposals remain future work and are not presented as implemented.
|
||||
|
||||
## Stage 7: Validate the final modules and workspace, then close the sprint
|
||||
|
||||
**Complete.** Validation used Go 1.27.0 against source revision `e28ba63`
|
||||
with the final import-formatting and roadmap-closure changes in the completion
|
||||
commit. Dependency preparation (`go mod tidy`, `go mod download`, and
|
||||
`go list -m all`) used `GOWORK=off GOTOOLCHAIN=local`; the selected graph has
|
||||
the intended vanity modules and no local replacements or old-path PromptKit or
|
||||
ConfigKit imports. The root, ckconfig, and ckprompt modules each passed
|
||||
`GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...` independently.
|
||||
|
||||
The preserved ignored workspace was set to Go 1.27.0, keeping its three existing
|
||||
`use` entries. From the root, `GOTOOLCHAIN=local go test ./...`,
|
||||
`go test ./integrations/ckconfig/...`, and `go test ./integrations/ckprompt/...`
|
||||
all passed with workspace discovery. Changed Go files were formatted. Local
|
||||
Markdown destinations and fragments, source/notice pins, the complete sprint
|
||||
diff, and whitespace checks were reviewed. Deferred capabilities remain in
|
||||
[future work](future.md#promptkit-inspection-and-selection-extensions).
|
||||
|
||||
All six standalone composed-consumer commands listed below returned status 0.
|
||||
The inspected source report included the application and bundled evidence;
|
||||
the selected spring profile and prompt, hash, and request validation appeared
|
||||
in their reports. Aggregate smoke selected the local backend, reported unavailable
|
||||
HTTP diagnostics, used the injected inference client, and recorded
|
||||
`valid_json: false` for structured output; its native facts did not alter the
|
||||
successful aggregate outcome. No publication or hosted delivery was performed.
|
||||
|
||||
1. Finish tidying/downloading ckprompt dependencies with workspace discovery
|
||||
off if deferred from Stage 1. Format changed Go files with `gofmt`. Inspect
|
||||
final imports, manifests, and graph for old-path PromptKit/ConfigKit packages,
|
||||
unintended upgrades, and local replacements. Do not change authentic sums to
|
||||
force a preferred graph. Investigate any remaining old identity by its actual
|
||||
dependency rather than deleting graph entries blindly.
|
||||
2. On Go 1.27.0, run each command from the named directory. These independent
|
||||
suites exercise actual declared releases, not local workspace substitutions:
|
||||
|
||||
| Directory | Command |
|
||||
| --- | --- |
|
||||
| `integrations/ckprompt` | `GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...` |
|
||||
| `integrations/ckconfig` | `GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...` |
|
||||
| Repository root | `GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...` |
|
||||
|
||||
The ckprompt command includes `examples/composed`; the root command does not
|
||||
traverse the integrations. Fix failures at their owning boundary and rerun
|
||||
affected checks. Do not add race/matrix/live-service gates for this migration.
|
||||
3. Preserve the ignored workspace files and existing `use` entries. Set its Go
|
||||
directive to 1.27.0 with `GOTOOLCHAIN=local go work edit -go=1.27.0`. From
|
||||
the repository root, run with normal workspace discovery:
|
||||
|
||||
```sh
|
||||
GOTOOLCHAIN=local go test ./...
|
||||
GOTOOLCHAIN=local go test ./integrations/ckconfig/...
|
||||
GOTOOLCHAIN=local go test ./integrations/ckprompt/...
|
||||
```
|
||||
|
||||
This tests local core/ckconfig composition as well as the maintained consumer.
|
||||
Allow normal ignored workspace sum maintenance; do not stage workspace files.
|
||||
4. From `integrations/ckprompt`, exercise representative standalone consumer
|
||||
commands with `GOWORK=off GOTOOLCHAIN=local go run ./examples/composed` followed
|
||||
by each argument set below. Inspect reports against the selected contracts:
|
||||
|
||||
```text
|
||||
config validate --scope all --campaign spring --limit=0
|
||||
config sources --scope promptkit --campaign spring
|
||||
promptkit list profiles --campaign spring
|
||||
promptkit show prompt briefing --campaign spring --format yaml
|
||||
promptkit requirements validate briefing --campaign spring --input topic=examples/composed/fixtures/topic.txt
|
||||
promptkit test all --campaign spring --prompt briefing --profile spring
|
||||
```
|
||||
|
||||
Use the maintained example's local client and intended offline diagnostic
|
||||
wiring. Inspect the aggregate smoke report and outcome according to its
|
||||
existing contract; concluded native diagnostic facts are not a new universal
|
||||
success assertion. The composed tests also cover aliases, completion, domain
|
||||
commands, comparison, and failure/report delivery.
|
||||
5. Review Markdown links/fragments, current examples, pinned provenance, and
|
||||
`git diff --check -- '*.md' COPYRIGHT`. Review the full diff for scope and
|
||||
accidental changes to histories, secrets, or independent modules. No code
|
||||
generation, new test framework, or publication check is needed for prose.
|
||||
6. Record the actual commands/results and final source revision in this plan.
|
||||
Mark completion only after all selected scope is implemented and required
|
||||
validation succeeds; the earlier disposable migration is not final evidence.
|
||||
Confirm the feature roadmap's target is met and the deferred capabilities
|
||||
remain tracked. Keep source-publication and hosted-delivery status separate.
|
||||
7. Follow the local commit policy: inspect status and staged changes, stage only
|
||||
intended sprint files, run the staged whitespace check, and commit completed
|
||||
work with a short plain-English message. Report commits and any remaining
|
||||
changes. No push or release action follows automatically.
|
||||
|
||||
## Open Questions
|
||||
|
||||
None required for this adoption. OD-1 through OD-5 fix the dependency, bundle,
|
||||
and capability scope. Deferred metadata, preparation reports, and namespace
|
||||
helpers retain their future design questions; they are not decisions Luna needs
|
||||
to resolve to complete this sprint.
|
||||
@@ -1,274 +0,0 @@
|
||||
# PromptKit v0.18.0 adoption
|
||||
|
||||
Status: implementation and validation complete; the ckprompt v0.3.0 candidate
|
||||
remains unpublished. Released PromptKit v0.18.0 was the sole development target.
|
||||
[Scope decisions](#scope-decisions) record that dependency choice and the
|
||||
selected example policy and capability scope. The
|
||||
[implementation plan](implementation.md) owns staged work, validation commands,
|
||||
and completion evidence; this document owns the desired state and scope.
|
||||
|
||||
## 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 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
|
||||
|
||||
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.
|
||||
|
||||
## 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
|
||||
|
||||
Prepare ckprompt v0.3.0 against this released dependency set under OD-1:
|
||||
|
||||
| Requirement | Target |
|
||||
| --- | --- |
|
||||
| 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` |
|
||||
| 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
|
||||
|
||||
PromptKit-owned root and collection `prompts`, `profiles`, and `backends` use
|
||||
lists with explicit `id` values. Calls to `ProfileSource` and `BackendSource`
|
||||
use ordered record slices. Inheritance and configuration-inspection paths
|
||||
match the adopted shapes. Consumer guidance links 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.
|
||||
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
|
||||
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. The ignored workspace composes root, ckconfig, and
|
||||
ckprompt with a Go version supporting its Go 1.27.0 members. Development guidance
|
||||
describes the aligned workspace, and the maintained composed consumer works
|
||||
with both the declared releases and the local module set.
|
||||
|
||||
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.
|
||||
|
||||
## Scope boundaries
|
||||
|
||||
The adoption covers dependency, API/report, fixture, and workspace alignment
|
||||
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. Ordered work belongs in the
|
||||
[implementation plan](implementation.md).
|
||||
|
||||
## Released upstream baseline
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Scope decisions
|
||||
|
||||
OD-1 records the user's explicit dependency direction. OD-2 through OD-5 record
|
||||
the selected scope for this sprint; deferred capabilities still require
|
||||
focused API and CLI design. These decisions do not describe implemented features
|
||||
or authorize publication.
|
||||
|
||||
| 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. |
|
||||
|
||||
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.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
The final integration uses the selected released vanity dependencies and Go
|
||||
minimum throughout production, tests, and the composed example. Its existing
|
||||
operations faithfully expose the adopted upstream results, with descriptive
|
||||
prompt-version fields removed and unrelated version meanings retained.
|
||||
|
||||
Maintained configuration uses the adopted resource shapes. The composed example
|
||||
retains the native bundle; CommandKit output carries its records and source
|
||||
evidence, and the default test suite and maintained smoke examples stay offline. The three modules compose in
|
||||
the local workspace while independently validating against declared releases.
|
||||
|
||||
Current contracts, consumer and namespace-loader guidance, notices, and the
|
||||
ckprompt v0.3.0 candidate note describe that implemented state. Workspace files
|
||||
and local dependency replacements are absent from release inputs. Source
|
||||
publication and hosted delivery remain separate under the existing release
|
||||
procedure. The [implementation plan](implementation.md#stage-7-validate-the-final-modules-and-workspace-then-close-the-sprint)
|
||||
owns concrete checks and their final evidence; the earlier disposable review
|
||||
is preliminary evidence only.
|
||||
Reference in New Issue
Block a user