243 lines
13 KiB
Markdown
243 lines
13 KiB
Markdown
|
|
# 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 — pending.
|
||
|
|
|
||
|
|
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 — pending.
|
||
|
|
|
||
|
|
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 — pending.
|
||
|
|
|
||
|
|
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 — pending.
|
||
|
|
|
||
|
|
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 — pending.
|
||
|
|
|
||
|
|
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.
|