From ad16bfc521bad43e5e14bb702ef75102c91fa484 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 6 Nov 2026 01:18:55 +0000 Subject: [PATCH] Retire completed PromptKit planning documents --- docs/development.md | 3 +- docs/roadmap/future.md | 21 +- docs/roadmap/implementation.md | 343 ------------------------------ docs/roadmap/promptkit-v0.18.0.md | 274 ------------------------ 4 files changed, 15 insertions(+), 626 deletions(-) delete mode 100644 docs/roadmap/implementation.md delete mode 100644 docs/roadmap/promptkit-v0.18.0.md diff --git a/docs/development.md b/docs/development.md index 534b46f..6719e9e 100644 --- a/docs/development.md +++ b/docs/development.md @@ -72,7 +72,8 @@ Read all applicable rows for cross-cutting work. Go declarations and GoDoc own current exported contracts; the CLI reference owns operator behavior. The [maintainer release procedure](release.md) owns current release operations. Completed roadmaps and implementation evidence remain available in Git history, -including [ConfigKit adoption, reporting, release-tooling, and remediation records](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/260256d722f52bc947103d078cb67a129f4cc9f1/docs/roadmap), +including [PromptKit v0.18.0 adoption and implementation](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/540e2359d66d604a563df0be1c9fc961588f5b9c/docs/roadmap), +[ConfigKit adoption, reporting, release-tooling, and remediation records](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/260256d722f52bc947103d078cb67a129f4cc9f1/docs/roadmap), [application-owned alias planning, implementation, and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/f42aefe02d84e154855ac922173e6f367180929f/docs/roadmap) and [PromptKit requirements implementation and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/40499a43608bf60d1104cd8ee24caf18ac0e9e66/docs/roadmap). These records are not assignments to restart completed work. The diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 380d968..f53e906 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -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. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md deleted file mode 100644 index 30f5f75..0000000 --- a/docs/roadmap/implementation.md +++ /dev/null @@ -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. diff --git a/docs/roadmap/promptkit-v0.18.0.md b/docs/roadmap/promptkit-v0.18.0.md deleted file mode 100644 index 54b5da1..0000000 --- a/docs/roadmap/promptkit-v0.18.0.md +++ /dev/null @@ -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.