Document PromptKit adoption and release candidate
This commit is contained in:
41
docs/cli.md
41
docs/cli.md
@@ -401,8 +401,7 @@ Text output begins with the scope heading and prints the same source fields,
|
||||
quoting labels and paths. These fields project the selected ConfigKit source
|
||||
records; CommandKit does not reload files or rerun version checks. See the
|
||||
[ConfigKit v1.1.0 source records](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/records.go)
|
||||
for native evidence definitions. Ckprompt v0.2.0 uses
|
||||
[ConfigKit v0.8.0](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/137769f3f18a370c68444242fb5d88e620e307e5/inspection.go).
|
||||
for native evidence definitions.
|
||||
|
||||
### Explain a configuration path
|
||||
|
||||
@@ -533,10 +532,9 @@ catalogs. Its loader receives invocation context, configuration selection,
|
||||
typed input, and shared state. Direct suite callbacks retain their own
|
||||
implementation and lifecycle.
|
||||
|
||||
Prompt inspection uses an ID only. PromptKit returns any descriptive version
|
||||
metadata as an optional report field; there is no `--version` flag for selecting
|
||||
a prompt version. The prompt format and native selection behavior remain owned by
|
||||
[PromptKit v0.16.0](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/docs/consumers/pkg-promptkit.md).
|
||||
Prompt inspection uses an ID only. The prompt format and native selection
|
||||
behavior remain owned by
|
||||
[PromptKit v0.18.0](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/docs/consumers/pkg-promptkit.md).
|
||||
|
||||
```text
|
||||
example promptkit show prompt customer/summary --format yaml
|
||||
@@ -548,14 +546,11 @@ Both commands require one ID operand and accept `--config`, `--overlay`, and
|
||||
`--format text|yaml` (default `text`). These commands have no built-in
|
||||
`--scope` selection; their namespace is `promptkit`.
|
||||
|
||||
Prompt YAML preserves native input order and uses an optional `version` field.
|
||||
The key is omitted when PromptKit returns no version and is retained when the
|
||||
version is present, including an empty string. The prompt hash is an opaque
|
||||
Prompt YAML preserves native input order. The prompt hash is an opaque
|
||||
owning-library equality value.
|
||||
|
||||
```yaml
|
||||
prompt_id: customer/summary
|
||||
version: "2"
|
||||
prompt_hash: opaque-value
|
||||
default_profile_id: customer-support
|
||||
inputs:
|
||||
@@ -625,7 +620,7 @@ The `promptkit` namespace identifies the operation, so there is no built-in
|
||||
`--scope` flag. An explicitly empty profile or session value retains PromptKit's
|
||||
native empty-string meaning. Requirements inspection does not require a profile
|
||||
to be execution-ready. See the
|
||||
[PromptKit v0.16.0 consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/docs/consumers/pkg-promptkit.md)
|
||||
[PromptKit v0.18.0 consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/docs/consumers/pkg-promptkit.md)
|
||||
for native configuration, selection, and requirements behavior. The built-in
|
||||
flags other than `--var` are singleton bindings; when repeated, the last value
|
||||
is used. Suite selectors retain their declared binding behavior.
|
||||
@@ -642,15 +637,13 @@ retained. Input metadata preserves null versus an empty string. Variable entries
|
||||
contain `name`, `kind`, `supplied`, and `explanation`. `supplied` reports native
|
||||
exact-key presence, including an explicitly empty value, independently of
|
||||
`kind` and `complete`. Explanations and issue descriptions are upstream-owned
|
||||
human-readable summaries, not machine-readable details. The optional `version`
|
||||
key is omitted when absent and retained when supplied by PromptKit.
|
||||
human-readable summaries, not machine-readable details.
|
||||
|
||||
For a prompt with the template `{{if .mode}}{{input "notes"}}{{end}}` and no
|
||||
input declarations, omitting `mode` can produce a partial report:
|
||||
|
||||
```yaml
|
||||
prompt_id: briefing
|
||||
version: "2"
|
||||
profile_id: editorial
|
||||
complete: false
|
||||
inputs:
|
||||
@@ -733,7 +726,7 @@ configuration and credential checks. It does not make a model call or retain a
|
||||
prepared execution snapshot. A successful report describes this preparation
|
||||
invocation; it does not certify provider acceptance or guarantee later
|
||||
execution. See PromptKit's
|
||||
[`Engine.ValidateRequest` API](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/engine.go).
|
||||
[`Engine.ValidateRequest` API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/engine.go).
|
||||
|
||||
Builder, engine-loading, and native validation errors use the operational path
|
||||
(status `1`) with supported error identity and acquired diagnostics retained.
|
||||
@@ -776,8 +769,7 @@ values are forwarded in order. Collections have no namespace or kind filter.
|
||||
Each operation writes one bare YAML sequence, retaining provider order and
|
||||
native identities:
|
||||
|
||||
- Prompt entries are `{id, version?}`. The optional `version` key is omitted
|
||||
when absent and retained for a present empty or nonempty value.
|
||||
- Prompt entries are `{id}`.
|
||||
- Profiles, backends, and namespaces are strings.
|
||||
- Collection entries are `{namespace, version?}`, where `version` projects
|
||||
PromptKit's optional release version.
|
||||
@@ -785,7 +777,6 @@ native identities:
|
||||
|
||||
```yaml
|
||||
- id: team/briefing
|
||||
version: "2"
|
||||
```
|
||||
|
||||
```yaml
|
||||
@@ -796,7 +787,7 @@ native identities:
|
||||
A catalog result is an inventory, not a readiness check or execution result.
|
||||
The owning provider controls membership and order. Namespace filters are passed
|
||||
to PromptKit without local membership interpretation. See the
|
||||
[PromptKit v0.16.0 consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/docs/consumers/pkg-promptkit.md)
|
||||
[PromptKit v0.18.0 consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/docs/consumers/pkg-promptkit.md)
|
||||
for native resource and selection definitions.
|
||||
|
||||
### PromptKit smoke testing
|
||||
@@ -845,7 +836,7 @@ A single report projects the native smoke report into YAML. It preserves native
|
||||
false, unknown/null, and incomplete values and does not add a readiness score.
|
||||
The report includes `kind`, `supported`, `applicable`, `completed`, `reason`,
|
||||
`target`, `facts`, `timing`, `attempts`, `usage`, and `failure`. Its target
|
||||
contains selected IDs, optional `version`, selection source, endpoint, effective
|
||||
contains selected IDs, selection source, endpoint, effective
|
||||
settings, and settings-presence flags. Attempt entries retain their own facts,
|
||||
timing, failure, and token-usage evidence. Durations use Go duration strings;
|
||||
token counts preserve `value`, `known`, and `complete`.
|
||||
@@ -859,14 +850,14 @@ applicable: null
|
||||
completed: true
|
||||
reason: http_diagnostics_unavailable
|
||||
target:
|
||||
backend_id: ""
|
||||
backend_id: local
|
||||
profile_id: spring
|
||||
prompt_id: briefing
|
||||
version: "1"
|
||||
default_source_backend_id: ""
|
||||
selection_source: profile
|
||||
endpoint: https://example.invalid/v1
|
||||
effective_settings:
|
||||
backend_id: local
|
||||
endpoint: https://example.invalid/v1
|
||||
model: spring-model
|
||||
temperature: 0
|
||||
@@ -939,9 +930,9 @@ operation causes. Syntax, operand, unsupported format, and conflicting
|
||||
namespace selection are usage status `2`.
|
||||
|
||||
Native configuration, selection, and diagnostic meanings remain owned by
|
||||
PromptKit. See the [v0.16.0 consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/docs/consumers/pkg-promptkit.md),
|
||||
[smoke API](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/smoke_diagnostics.go),
|
||||
and [engine API](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/engine.go).
|
||||
PromptKit. See the [v0.18.0 consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/docs/consumers/pkg-promptkit.md),
|
||||
[smoke API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/smoke_diagnostics.go),
|
||||
and [engine API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/engine.go).
|
||||
|
||||
## Outcome status
|
||||
|
||||
|
||||
@@ -24,6 +24,12 @@ paths have distinct Go type identities. Install core with
|
||||
`go get go.maximumdirect.net/ckconfig@v0.2.0` or
|
||||
`go get go.maximumdirect.net/ckprompt@v0.2.0`.
|
||||
|
||||
The current ckprompt source targets ckconfig v0.3.0, ConfigKit v1.1.0, and
|
||||
PromptKit v0.18.0 using their `go.maximumdirect.net` identities. Its v0.3.0
|
||||
release is a candidate, not a published release. A Go 1.27.0 workspace may
|
||||
compose all three local modules; independent tests with `GOWORK=off` exercise
|
||||
the declared releases.
|
||||
|
||||
The two integrations are independent optional imports. `ckprompt` uses the
|
||||
public scope and error contracts from `ckconfig`; importing it does not add the
|
||||
`config` family. An application that wants both families passes both returned
|
||||
@@ -32,8 +38,8 @@ core-only, ConfigKit-only, and composed applications.
|
||||
|
||||
## Go compatibility
|
||||
|
||||
Core and ckprompt declare a consumer minimum of Go 1.26.0; ckconfig
|
||||
v0.3.0 requires Go 1.27.0. The root module also
|
||||
Core declares a consumer minimum of Go 1.26.0; both current integration
|
||||
modules require Go 1.27.0. The root module also
|
||||
selects ReleaseKit v0.9.0 (`go.maximumdirect.net/releasekit`) as a Go tool, which
|
||||
makes that tool's module graph part of the root consumer module requirements
|
||||
even though production packages do not import ReleaseKit. The
|
||||
@@ -338,6 +344,40 @@ combines app and PromptKit config scopes, comparison and catalogs, named and
|
||||
requirements inspection, request validation, smoke testing, and an
|
||||
application-owned `session restore` command.
|
||||
|
||||
### Namespace views
|
||||
|
||||
An application can return a scoped PromptKit view from its own engine loader:
|
||||
|
||||
```go
|
||||
func loadScopedEngine(ctx context.Context, selection ckconfig.Selection, input Input, state State) (*promptkit.Engine, error) {
|
||||
engine, err := loadEngine(ctx, selection, input, state)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return engine.WithNamespaces(promptkit.Namespaces{
|
||||
Prompt: "editorial", Profile: "team", Backend: "providers",
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
These are independent defaults for unqualified caller-supplied prompt, profile,
|
||||
and backend names; qualified IDs pass through. Stored references and configuration
|
||||
inspection are unchanged, while namespace and collection inventories remain global.
|
||||
Catalog `--namespace` filters are separate from these defaults. See the released
|
||||
[namespace API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/namespaces.go).
|
||||
|
||||
### PromptKit configuration migration
|
||||
|
||||
The current integration uses identified resource lists and keeps PromptKit's
|
||||
native default OpenRouter bundle. Loaders can opt out with
|
||||
`promptkit.WithBundledOpenRouter(false)`. Catalogs and configuration reports
|
||||
expose the supplied engine's inventory and native source evidence. The
|
||||
[upstream migration guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/docs/consumers/configuration-migration.md)
|
||||
covers list records, inheritance, source-root controls, and import requiredness.
|
||||
Prompt catalog, prompt and requirements inspection, and smoke target reports no
|
||||
longer carry descriptive prompt versions; collection release labels and source
|
||||
version evidence retain their own meanings.
|
||||
|
||||
## Outcomes and ownership
|
||||
|
||||
Core classifies usage and operational failures while preserving application
|
||||
@@ -350,11 +390,11 @@ signal handling, and exit mapping; `Execute` never exits the process.
|
||||
Go declarations and GoDoc own exact exported contracts. ConfigKit owns
|
||||
configuration decoding, validation, and provenance. PromptKit owns prompt
|
||||
formats, profile resolution, and inspection details. See the
|
||||
[ConfigKit v0.8.0 inspection API for ckprompt v0.2.0](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/137769f3f18a370c68444242fb5d88e620e307e5/inspection.go),
|
||||
[PromptKit engine methods](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/engine.go),
|
||||
[configuration inspection](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/configuration_inspection.go),
|
||||
[smoke diagnostics](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/smoke_diagnostics.go),
|
||||
and [PromptKit v0.16.0 consumer guidance](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/docs/consumers/pkg-promptkit.md).
|
||||
[ConfigKit v1.1.0 source records](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/records.go),
|
||||
[PromptKit engine methods](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/engine.go),
|
||||
[configuration inspection](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/configuration_inspection.go),
|
||||
[smoke diagnostics](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/smoke_diagnostics.go),
|
||||
and [PromptKit v0.18.0 consumer guidance](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/docs/consumers/pkg-promptkit.md).
|
||||
|
||||
## ConfigKit v1.1 migration
|
||||
|
||||
|
||||
@@ -101,12 +101,18 @@ evidence, not build dependencies. Implemented contracts belong in CommandKit
|
||||
under their canonical owners.
|
||||
|
||||
The root module does not traverse nested modules. Preserve the ignored `go.work`
|
||||
and `go.work.sum`; use `GOWORK=off GOTOOLCHAIN=local` for dependency preparation,
|
||||
module suites, and examples during the ckconfig migration. Local ckprompt uses
|
||||
the old ConfigKit identity and cannot compose with migrated local ckconfig. Its
|
||||
independent suite and composed example use published ckconfig v0.2.0; restore
|
||||
full local workspace guidance after the coordinated ckprompt migration.
|
||||
Run `go test ./...` separately from each module directory.
|
||||
and `go.work.sum`; use `GOWORK=off GOTOOLCHAIN=local` for dependency preparation
|
||||
and independent module suites. With a Go 1.27.0 workspace containing all three modules, normal
|
||||
workspace discovery also validates local composition.
|
||||
Run `GOWORK=off GOTOOLCHAIN=local go test ./...` separately from each module
|
||||
directory. From the repository root, a workspace containing all three modules can
|
||||
also run:
|
||||
|
||||
```sh
|
||||
GOTOOLCHAIN=local go test ./...
|
||||
GOTOOLCHAIN=local go test ./integrations/ckconfig/...
|
||||
GOTOOLCHAIN=local go test ./integrations/ckprompt/...
|
||||
```
|
||||
|
||||
Format changed Go files with `gofmt`. The
|
||||
[maintainer release procedure](release.md) owns candidate preparation and
|
||||
|
||||
@@ -35,8 +35,8 @@ module metadata.
|
||||
|
||||
## Release toolchain
|
||||
|
||||
The selected release toolchain is **Go 1.27.0**. Core and ckprompt declare a
|
||||
consumer minimum of **Go 1.26.0**; ckconfig requires **Go 1.27.0**. Maintainers
|
||||
The selected release toolchain is **Go 1.27.0**. Core declares a
|
||||
consumer minimum of **Go 1.26.0**; both integrations require **Go 1.27.0**. Maintainers
|
||||
use Go 1.27.0 for dependency preparation, candidate validation, and ReleaseKit
|
||||
execution. The
|
||||
[consumer guide](consumers/guide.md#go-compatibility) and
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# PromptKit v0.18.0 implementation plan
|
||||
|
||||
Status: Stages 1–5 complete; Stages 6–7 remain.
|
||||
Status: Stages 1–6 complete; Stage 7 remains.
|
||||
|
||||
## Authority and execution
|
||||
|
||||
@@ -208,6 +208,8 @@ 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
|
||||
|
||||
Reference in New Issue
Block a user