# PromptKit v0.23.1 implementation plan ## Purpose and execution Implement the target state in the [adoption roadmap](promptkit-v0.23.1.md). The [companion-YAML report](promptkit-companion-yaml-exit-status.md) provides the original reproduction and expected outcomes. This plan is written for a Luna coding agent working through one end-to-end sprint. Follow Stage 1 through Stage 5 in order. Continue between stages using the decisions below. Intermediate stages may be incomplete while the sprint moves toward the final target. Record each completed stage and its verification here, then commit each completed nonempty unit using a short plain English message, following the [agent policy](../policy/agents.md#git-commit-policy). Read the [developer guide](../development.md) and its applicable policy links. Use the installed codebase knowledge graph for code discovery. Use Go 1.27.0 on `PATH` with `GOTOOLCHAIN=local`. The final deliverable is a locally committed, release-ready ckprompt v0.9.0 candidate. Publication and hosted-page delivery follow the existing [release procedure](../release.md) when authorized. ## Baseline and selected approach The planning baseline is `8513949`. ckprompt v0.8.0 selects PromptKit v0.21.0, ckconfig v0.8.0, core v0.6.0, and ConfigKit v1.2.0, with Go 1.27.0 as its consumer minimum. PromptKit v0.23.1 corresponds to upstream source commit `74066167942fcf6f70c112359995739ec9789fa6`. Select PromptKit v0.23.1 and retain the other baseline dependency selections. Use the existing `ckconfig.ClassifyConfigurationError`, ckprompt diagnostic adaptation, and core outcome presentation. The upstream constructor fix enables those mechanisms to classify malformed YAML correctly. Any production-code adjustment should address a failure demonstrated by the integration checks. Existing application callbacks continue to own engine construction and native request construction. Upstream owns conversation execution, operation timeouts, and prepared-run notifications. Additional CLI proposals retain their status in [future work](future.md). The [testing policy](../policy/testing.md#upstream-integration-testing-ownership) governs assertions about these integrations. ## Stage 1 — Select PromptKit v0.23.1 and update attribution Status — completed. `GOWORK=off GOTOOLCHAIN=local go get` selected PromptKit v0.23.1; `go list -m all` confirmed the baseline dependency versions, and `go list -m go.maximumdirect.net/promptkit` confirmed the selected version. The module diff adds only the PromptKit version and checksums. The selected upstream LICENSE and COPYRIGHT match v0.21.0, and attribution now points to commit `74066167942fcf6f70c112359995739ec9789fa6`. 1. Inspect `integrations/ckprompt/go.mod`, `go.sum`, and the module-local `docs/oss/attribution.md`. Prepare the published dependency from the ckprompt directory with the following command. ```sh GOWORK=off GOTOOLCHAIN=local go get go.maximumdirect.net/promptkit@v0.23.1 ``` 2. Review the resulting module diff and resolved versions with `GOWORK=off GOTOOLCHAIN=local go list -m all`. Keep the selected ckconfig, core, ConfigKit, and Go minimum from the baseline. Resolve incidental module changes using ordinary Go module tooling and the actual dependency graph. 3. Compare PromptKit's license and copyright notices at the selected source. Update only the affected attribution entry and its source/license links to v0.23.1 and commit `74066167942fcf6f70c112359995739ec9789fa6`, applying the [OSS policy](../policy/oss.md). Existing reviewed license texts match. 4. Verify the published module selection with `GOWORK=off GOTOOLCHAIN=local go list -m go.maximumdirect.net/promptkit`. Keep any local `go.work` and `go.work.sum` as ignored development files. Completion evidence consists of the selected published version, reviewed module/checksum diff, and updated attribution. Focused behavioral tests follow in Stage 2. ## Stage 2 — Cover real constructor failures through both integrations Status — completed. The focused independent-module test `GOWORK=off GOTOOLCHAIN=local go test -count=1 -run '^TestPromptConstructorConfigurationOutcomes$' .` passes with PromptKit v0.23.1. It exercises a real malformed companion through catalog and configuration commands, preserving constructor and typed error identity, diagnostic/source evidence, reports, and diff-side context. 1. Read the existing test wiring in ckprompt's `command_test.go`, `configuration_outcomes_test.go`, and `configuration_composition_outcomes_test.go`. In particular, `TestPromptNativeConfigurationFailures` and `TestComposedConfigurationInputOutcomes` currently inject ConfigKit errors directly. Reuse `newPromptTestApp` and the existing suite composition. 2. Add focused regression tests in `integrations/ckprompt/constructor_outcomes_test.go`, using package `ckprompt`. Build a small test-owned loader with `t.TempDir()` files, including malformed `prompts.yml` containing `profiles: [`. Resolve the companion from a valid application-config fixture, then construct the engine using `promptkit.NewEngine` with a `configkit.File` input for that companion. Use the existing fixture's `WithBundledOpenRouter(false)` option to keep construction self-contained. Capture the actual constructor error for identity assertions. 3. Let the test loader's `ckconfig.Selection` distinguish valid and malformed configurations so it can serve both comparison sides. Use the existing `adapterEngine` fixture for a successful side. Register a `FromEngine` suite and a `ckconfig.Command` containing `ConfigScope(load)` through the usual public command declarations. 4. Add `TestPromptConstructorConfigurationOutcomes` with the following invocation cases. Pass the fixture's selected main path through `--config` and use `--scope=promptkit` on configuration commands. | Invocation | Additional assertion | | --- | --- | | `promptkit list prompts` | Catalog acquisition preserves the constructor error. | | `config show` | Configuration acquisition classifies the same error. | | `config sources --format=json` | Available source evidence is still reported. | | `config validate --details --format=json` | Available findings include the returned YAML diagnostic. | | `config explain --list` | Discovery follows the configuration acquisition outcome. | | `config diff` with malformed left input | Explanation identifies the left side. | | `config diff` with valid left and malformed right inputs | Explanation identifies the right side. | 5. For each case, assert usage classification and status 2, propagation of the captured error through `errors.Is`, access to the same typed `*configkit.LoadError` through `errors.As`, and recognition of `promptkit.ErrInvalidConfig`. Check the returned `yaml.invalid` diagnostic and companion source context through stable structured fields or small semantic output fragments. Assert the available source/validation report for the two reporting cases. Keep comparisons about adaptation and outcome selection at the CommandKit boundary. 6. Run the focused test from the ckprompt module directory. ```sh GOWORK=off GOTOOLCHAIN=local go test -count=1 -run '^TestPromptConstructorConfigurationOutcomes$' . ``` Completion evidence consists of real constructor errors producing the expected CommandKit outcomes, identity, diagnostics, reports, and comparison-side context. ## Stage 3 — Preserve failure precedence and native report compatibility Status — completed. The focused constructor and preparation tests and `GOWORK=off GOTOOLCHAIN=local go test ./...` passed against published dependencies. Real missing-schema and malformed-YAML constructor failures retain their causes; mixed operational and cancellation causes and pre-canceled invocations select status 1. The prepared report retains `ParentRunID`. Both native request adapters forward whole builder results; upstream preparation and validation use the supplied context, while execution owns notifications and operation timeouts. 1. Add `TestPromptConstructorFailurePrecedence` alongside Stage 2's tests. Exercise a representative catalog command and `config show --scope=promptkit` for each distinct failure category below. - Use `NewEngine` with `WithSchemaFile` pointing to an absent file to obtain an actual operational constructor error. Assert operational classification, status 1, and preservation of both `ErrInvalidConfig` and `os.ErrNotExist`. - Join the real malformed-YAML constructor error with a test-owned operational sentinel using `errors.Join` in the loader. Assert status 1 and preservation of both causes. - Join the real malformed-YAML constructor error with `context.Canceled`. Assert status 1 and preservation of the cancellation and constructor causes. - Execute with an already-canceled context and a loader that could otherwise construct an engine. Assert status 1, `context.Canceled`, empty stdout, and acquisition skipped, reusing the existing cancellation test pattern. 2. Review `WithRequestPreparation` in `preparation.go` and `WithRequestValidation` in `adapters.go` against the selected upstream `RunRequest` type. Their existing whole-request assignment forwards native builder results. Account for the new fields using that path. 3. Extend `TestPreparationCommandForwardsOrderedInputsAndNativeReport` in `preparation_test.go` with a nonempty `ParentRunID` on its supplied native `PreparedRun`. Keep its existing logical comparison with upstream JSON serialization to cover additive report data through CommandKit's renderer. 4. Use the upstream public contracts when interpreting new options. `Prepare` and `ValidateRequest` use the supplied context and leave `OnPrepared` invocation to execution operations. Operation-timeout behavior belongs to the upstream operations that apply it. Review keyed struct literals and native-type use for compatibility during compilation. 5. Run the constructor tests and the affected preparation test, then ckprompt's full default suite with published dependency selections. ```sh GOWORK=off GOTOOLCHAIN=local go test -count=1 -run '^(TestPromptConstructor.*|TestPreparationCommandForwardsOrderedInputsAndNativeReport)$' . GOWORK=off GOTOOLCHAIN=local go test ./... ``` Completion evidence consists of operational/cancellation precedence, retained causes, native prepared-report forwarding, and the passing independent suite. ## Stage 4 — Update current guidance and prepare ckprompt v0.9.0 Status — completed. Consumer and CLI guidance identifies the prepared v0.9.0 candidate separately from published v0.8.0, links to PromptKit v0.23.1, and describes construction, request ownership, and the corrected outcome. The version-matched release note records compatibility and includes full-tag notice links. Upstream source paths and relevant fragments were checked against the selected module; ckprompt GoDoc required no version-specific correction. 1. Update PromptKit references in `docs/consumers/guide.md` and `docs/cli.md` to the selected source revision. Verify destinations and fragments against v0.23.1. Review affected ckprompt GoDoc and correct version-specific claims where needed. 2. Keep the currently published v0.8.0 installation instructions and historical release facts accurate. Add a clearly identified prepared ckprompt v0.9.0 candidate paragraph beside the consumer guide's version table, selecting core v0.6.0, ckconfig v0.8.0, ConfigKit v1.2.0, and PromptKit v0.23.1. Current checkout guidance can describe its selected v0.23.1 capabilities. Published installation guidance can advance when publication occurs. 3. Document the corrected constructor-error behavior by referencing the existing configuration-failure contract. Explain the application-owned engine/request callbacks briefly and link upstream for conversation and execution features. The existing maintained consumer supplies the composition example for this adoption. Keep examples focused on CommandKit-specific integration behavior. 4. Create `integrations/ckprompt/docs/releases/v0.9.0.md` with title `CommandKit ckprompt v0.9.0`. Describe the PromptKit upgrade, malformed companion YAML changing from status 1 to status 2, preserved diagnostics and typed causes, operational/cancellation status 1, dependency pairing, and Go 1.27.0 minimum. Explain relevant additive native-type/report compatibility and link to upstream upgrade guidance. Link current contracts for details. 5. End the release note with `COPYRIGHT | LICENSE | ATTRIBUTION` links using full tag `integrations/ckprompt/v0.9.0` and module-prefixed paths, following the [release-note procedure](../release.md#modules-versions-notes-and-shared-files). Treat this as preparation for subsequent publication. Completion evidence consists of accurate current-versus-published guidance, updated pinned references, and a version-matched release note. ## Stage 5 — Verify the assembled candidate and complete the records Status — completed. With Go 1.27.0 and the aligned three-module workspace, `GOTOOLCHAIN=local go test ./...`, `go test ./integrations/ckconfig/...`, and `go test ./integrations/ckprompt/...` all passed, including the composed consumer. The independent ckprompt suite passed in Stage 3 with unchanged Go and module inputs. Aggregate whitespace and Go formatting checks passed; local documentation links and the selected upstream paths and fragments were reviewed. The companion-YAML report records resolution. The subsequent cleanup commit retires these completed records and links this evidence from future work. 1. Ensure the ignored local workspace includes root, ckconfig, and ckprompt, following the developer guide. Run the following from the repository root to validate aligned local sources and the maintained composed consumer. ```sh GOTOOLCHAIN=local go test ./... GOTOOLCHAIN=local go test ./integrations/ckconfig/... GOTOOLCHAIN=local go test ./integrations/ckprompt/... ``` The ckprompt workspace suite includes `examples/composed`; use that package's result as the maintained-consumer evidence. Reuse Stage 3's independent-suite result for the same Go inputs, or rerun that suite if later Go/module changes affect it. 2. Review the aggregate diff against the roadmap's target state. Check Go formatting for changed Go files, Markdown links and fragments, release-note paths, attribution revision, and whitespace. Validate intended new files along with tracked files. Resolve failures within their owning integration paths and rerun affected checks. 3. Record stage completion and concrete verification commands/results. Mark the companion-YAML report resolved with the selected upstream version and integration regression evidence. Commit the verified implementation and completed records under the local commit policy. 4. Complete roadmap retirement as release preparation. Preserve any unfinished items in `future.md`. Record an immutable Git-history link in `future.md` to the commit containing the completed records, then remove the completed adoption roadmap, companion-YAML report, and this implementation plan. Repair affected references and commit the cleanup. This sequence preserves their resolution evidence in history while keeping active roadmaps current. 5. Confirm a clean worktree and summarize the dependency selection, tests, documentation, commits, and prepared ckprompt version. Identify publication as the subsequent separately authorized release action using the existing procedure. The sprint is complete when the locally committed candidate meets the target state, the scoped verification passes, and completed planning records have been retired with their evidence retained in Git history.