Document ConfigKit adoption

2026-11-04 15:05:42 +00:00
parent 42176a7ac4
commit 5ccdcb91c9
10 changed files with 118 additions and 70 deletions
--- a/README.md
+++ b/README.md
@@ -22,8 +22,10 @@ defines the shared visibility policy.
 | `go.maximumdirect.net/ckconfig` | `ckconfig` | ConfigKit-backed `config` scopes, including configuration source evidence. |
 | `go.maximumdirect.net/ckprompt` | `ckprompt` | PromptKit engine configuration/comparison, five catalogs, named inspection, requirements discovery, concrete request validation, and native smoke tests. |

-Importing an integration does not install commands. The matched ckconfig and
-ckprompt v0.2.0 modules use core v0.3.0. See the
+Importing an integration does not install commands. The published ckconfig and
+ckprompt v0.2.0 modules use core v0.3.0. The local
+ckconfig v0.3.0 candidate uses ConfigKit v1.1.0 and does not compose with
+ckprompt v0.2.0; the published v0.2.0 pair remains matched. See the
 [consumer guide](docs/consumers/guide.md#module-selection) for migration details.

 ## Examples
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -363,14 +363,14 @@ sources:
  - id: source-1
    label: "application config"
    path: /etc/example/config.yml
-    layer: base
+    layer: main
    kind: file
    underlay_index: 0
    imported_from: null
    destination: /server
    placement: mapping
-    destination_unresolved: false
-    version_check:
+    destination_is_fallback: false
+    version_evidence:
      path: /version
      version:
        present: true
@@ -381,22 +381,28 @@ sources:
        line: 2
        column: 1
      redacted: false
+    empty_import_selections: []
 ```

 Each source includes `id`, `label`, `path`, `layer`, `kind`, `underlay_index`,
-and `imported_from`, plus the native destination pointer, placement, unresolved
-destination flag, and nullable `version_check`. Placement is `mapping` or
-`sequence_item`. The import location is null when absent; otherwise it has
+and `imported_from`, plus the native destination pointer, placement,
+`destination_is_fallback`, nullable `version_evidence`, and
+`empty_import_selections`. Placement is `mapping` or `sequence_item`. The
+import location is null when absent; otherwise it has
 `source_id`, `line`, and `column`. Version evidence preserves `path`, `present`,
 `null`, `text`, optional source `location`, and `redacted` as returned by
 ConfigKit. Owning values and source order are preserved, including empty fields,
 zero coordinates, false and null observations, and synthetic sources without
-paths. An absent version check is null. An empty inventory is `sources: []`.
+paths. Absent version evidence is null. Each empty-import record has a source-local
+`path`, a `location` mapping (`source_id`, `line`, `column`), and a `selector`;
+records preserve their returned order. No records are `empty_import_selections: []`.
+An empty inventory is `sources: []`.
 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 v0.8.0 inspection API](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/137769f3f18a370c68444242fb5d88e620e307e5/inspection.go)
-for native evidence definitions.
+[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).

 ### Explain a configuration path

@@ -427,7 +433,7 @@ effective:
  redacted: false
  yaml: "localhost:8080\n"
 origin:
-  layer: base
+  layer: main
  locations:
    - source_id: source-1
      line: 4
--- a/docs/consumers/guide.md
+++ b/docs/consumers/guide.md
@@ -15,7 +15,9 @@ installed at the application root, not as group children.
 | `go.maximumdirect.net/ckconfig` | The application wants ConfigKit-backed configuration scopes and reports. |
 | `go.maximumdirect.net/ckprompt` | The application wants PromptKit engine configuration/comparison, five catalogs, named inspection, requirements discovery, request validation, or native smoke testing. |

-The matched releases are core v0.3.0, ckconfig v0.2.0, and ckprompt v0.2.0.
+The published matched releases are core v0.3.0, ckconfig v0.2.0, and ckprompt v0.2.0.
+The local ckconfig v0.3.0 candidate uses ConfigKit v1.1.0 and does not compose
+with ckprompt v0.2.0, which retains ckconfig v0.2.0 and ConfigKit v0.8.0.
 Update application imports and dependency versions together; old and new core
 paths have distinct Go type identities. Install core with
 `go get go.maximumdirect.net/commandkit@v0.3.0` and either integration with
@@ -30,12 +32,13 @@ core-only, ConfigKit-only, and composed applications.

 ## Go compatibility

-All three modules declare a consumer minimum of Go 1.26.0. The root module also
+Core and ckprompt declare a consumer minimum of Go 1.26.0; the ckconfig
+v0.3.0 candidate requires 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
 [release policy](../policy/release.md#consumer-minimum-and-release-toolchain)
-defines the support assumption. Maintainers use Go 1.26.8 for validation and
+defines the support assumption. Maintainers use Go 1.27.0 for validation and
 publication; see the [release procedure](../release.md#release-toolchain).

 ## Core commands
@@ -347,8 +350,24 @@ 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](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/137769f3f18a370c68444242fb5d88e620e307e5/inspection.go),
+[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 migration
+
+The ckconfig v0.3.0 candidate uses `go.maximumdirect.net/configkit v1.1.0`
+and Go 1.27.0. Consumers must migrate ConfigKit imports and values passed to
+ckconfig: the old and new package paths have distinct type identities. Source
+reports rename `destination_unresolved` to `destination_is_fallback` and
+`version_check` to `version_evidence`, and add `empty_import_selections`.
+
+The upstream [v0.9 migration notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v0.9.0.md),
+[v0.10 notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v0.10.0.md),
+[v1.0 migration notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v1.0.0.md),
+and [v1.1 notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v1.1.0.md)
+cover source-root `configkit` controls becoming `config`, import requiredness
+and defaults, collection registration and operations, removed APIs, and CLI
+assignment order.
--- a/docs/development.md
+++ b/docs/development.md
@@ -99,25 +99,14 @@ Sibling-checkout references in retired planning records are historical review
 evidence, not build dependencies. Implemented contracts belong in CommandKit
 under their canonical owners.

-The root module does not traverse nested modules. During development, use a
-local workspace for all three modules; it is ignored and must not be committed.
-If a local `go.work` already exists, preserve it and add these module directories:
+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.

-```sh
-if [ -f go.work ]; then
-    go work use . ./integrations/ckconfig ./integrations/ckprompt
-else
-    go work init . ./integrations/ckconfig ./integrations/ckprompt
-fi
-go test ./...
-(cd integrations/ckconfig && go test ./...)
-(cd integrations/ckprompt && go test ./...)
-```
-
-The workspace checks package behavior. Workspace-off checks with each module's
-own dependency graph are separate evidence. For unpublished CommandKit dependency
-versions, the [completed integration validation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/8a82620dfcd34c0ae56bbecb0d014eb49786bc92/docs/roadmap/implementation.md#stage-12-validate-the-complete-end-state-and-finish)
-describes the disposable module-file procedure used during implementation.
 Format changed Go files with `gofmt`. The
 [maintainer release procedure](release.md) owns candidate preparation and
 publication commands.
@@ -141,25 +130,25 @@ external services. The PromptKit smoke examples use local fixtures and the
 example's configured client:

 ```sh
-go run ./examples/core workspace greet --count=0 --tag=first --tag second
-(cd integrations/ckconfig/examples/simple && go run . config show)
-(cd integrations/ckconfig/examples/simple && go run . config diff --config fixtures/before.yml --against-config fixtures/after.yml)
-(cd integrations/ckprompt/examples/composed && go run . config validate --scope all --campaign spring --limit=0)
-(cd integrations/ckprompt/examples/composed && go run . config diff --scope app --config fixtures/before.yml --against-config fixtures/after.yml)
-(cd integrations/ckprompt/examples/composed && go run . config diff --scope promptkit --config fixtures/before.yml --against-config fixtures/after.yml --campaign spring)
-(cd integrations/ckprompt/examples/composed && go run . promptkit list prompts --config fixtures/before.yml --campaign spring)
-(cd integrations/ckprompt/examples/composed && go run . promptkit list profiles --config fixtures/after.yml --campaign autumn --format yaml)
-(cd integrations/ckprompt/examples/composed && go run . promptkit list backends --namespace team)
-(cd integrations/ckprompt/examples/composed && go run . promptkit list namespaces --kind prompt --kind profile)
-(cd integrations/ckprompt/examples/composed && go run . promptkit list collections)
-(cd integrations/ckprompt/examples/composed && go run . promptkit show prompt briefing --campaign spring --format yaml)
-(cd integrations/ckprompt/examples/composed && go run . promptkit requirements show briefing --campaign spring)
-(cd integrations/ckprompt/examples/composed && go run . promptkit requirements show briefing --campaign spring --var mode=full --format yaml)
-(cd integrations/ckprompt/examples/composed && go run . promptkit requirements validate briefing --campaign spring --input topic=fixtures/topic.txt)
-(cd integrations/ckprompt/examples/composed && go run . promptkit requirements validate briefing --campaign spring --input topic=fixtures/topic.txt --var mode=full --input notes=fixtures/notes.txt --format yaml)
-(cd integrations/ckprompt/examples/composed && go run . promptkit test reachability --campaign spring --prompt briefing --profile spring)
-(cd integrations/ckprompt/examples/composed && go run . promptkit test all --campaign spring --prompt briefing --profile spring)
-(cd integrations/ckprompt/examples/composed && go run . session restore session-42 --campaign spring)
+GOWORK=off GOTOOLCHAIN=local go run ./examples/core workspace greet --count=0 --tag=first --tag second
+(cd integrations/ckconfig/examples/simple && GOWORK=off GOTOOLCHAIN=local go run . config show)
+(cd integrations/ckconfig/examples/simple && GOWORK=off GOTOOLCHAIN=local go run . config diff --config fixtures/before.yml --against-config fixtures/after.yml)
+(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . config validate --scope all --campaign spring --limit=0)
+(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . config diff --scope app --config fixtures/before.yml --against-config fixtures/after.yml)
+(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . config diff --scope promptkit --config fixtures/before.yml --against-config fixtures/after.yml --campaign spring)
+(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit list prompts --config fixtures/before.yml --campaign spring)
+(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit list profiles --config fixtures/after.yml --campaign autumn --format yaml)
+(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit list backends --namespace team)
+(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit list namespaces --kind prompt --kind profile)
+(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit list collections)
+(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit show prompt briefing --campaign spring --format yaml)
+(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit requirements show briefing --campaign spring)
+(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit requirements show briefing --campaign spring --var mode=full --format yaml)
+(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit requirements validate briefing --campaign spring --input topic=fixtures/topic.txt)
+(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit requirements validate briefing --campaign spring --input topic=fixtures/topic.txt --var mode=full --input notes=fixtures/notes.txt --format yaml)
+(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit test reachability --campaign spring --prompt briefing --profile spring)
+(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit test all --campaign spring --prompt briefing --profile spring)
+(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . session restore session-42 --campaign spring)
 ```

 The [consumer guide](consumers/guide.md) explains how their public API usage
--- a/docs/release.md
+++ b/docs/release.md
@@ -35,20 +35,21 @@ module metadata.

 ## Release toolchain

-The selected release toolchain is **Go 1.26.8**. Each module declares a consumer
-minimum of **Go 1.26.0**. Maintainers use Go 1.26.8 for dependency preparation,
-candidate validation, and ReleaseKit execution. The
+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
+use Go 1.27.0 for dependency preparation, candidate validation, and ReleaseKit
+execution. The
 [consumer guide](consumers/guide.md#go-compatibility) and
 [release policy](policy/release.md#consumer-minimum-and-release-toolchain)
 describe these selections.

-Select Go 1.26.8 on `PATH`; the launcher uses `GOTOOLCHAIN=local`. If needed,
+Select Go 1.27.0 on `PATH`; the launcher uses `GOTOOLCHAIN=local`. If needed,
 install it with the standard Go tools:

 ```sh
-GOWORK=off GOTOOLCHAIN=local go install golang.org/dl/go1.26.8@latest
-go1.26.8 download
-export PATH="$(go1.26.8 env GOROOT)/bin:$PATH"
+GOWORK=off GOTOOLCHAIN=local go install golang.org/dl/go1.27.0@latest
+go1.27.0 download
+export PATH="$(go1.27.0 env GOROOT)/bin:$PATH"
 hash -r
 GOWORK=off GOTOOLCHAIN=local go version
 ```
--- a/docs/roadmap/implementation.md
+++ b/docs/roadmap/implementation.md
@@ -1,6 +1,6 @@
 # ConfigKit v1.1.0 adoption implementation plan

-Status: Stages 1–3 complete; Stages 4–6 are not started.
+Status: Stages 1–4 complete; Stages 5–6 are not started.

 This plan is for a Luna coding agent implementing the selected
 [ConfigKit adoption target](configkit-v1.1.0.md). Follow Stage 1 through Stage 6
@@ -187,6 +187,10 @@ classifies sensitive data correctly.

 ## Stage 4: Update current guidance and prepare the release note

+**Completed.** Current guidance describes the new source report, consumer and
+toolchain migration, and temporary ckprompt mismatch. The v0.3.0 candidate
+note is prepared; published notes remain unchanged.
+
 1. Update ckconfig README, GoDoc, and `examples/simple/README.md` for the new
   dependency identity and Go minimum, and the planned ckconfig v0.3.0 with
   core v0.3.0. Keep package/provider usage consistent with actual code.
--- a/integrations/ckconfig/README.md
+++ b/integrations/ckconfig/README.md
@@ -7,9 +7,9 @@ itself.

 ## Module

-The module path is `go.maximumdirect.net/ckconfig`. Version v0.2.0 uses
-`go.maximumdirect.net/commandkit v0.3.0` and
-ConfigKit; it does not import PromptKit. See the
+The module path is `go.maximumdirect.net/ckconfig`. The prepared v0.3.0
+candidate requires Go 1.27.0 and uses `go.maximumdirect.net/commandkit v0.3.0` and
+`go.maximumdirect.net/configkit v1.1.0`; it does not import PromptKit. See the
 [consumer guide](https://gitea.maximumdirect.net/eric/CommandKit/src/branch/main/docs/consumers/guide.md#configkit-scopes)
 for exact callback and lifetime contracts.

@@ -26,9 +26,9 @@ scopes, selectors, input checks, and state shared by the selected acquisitions
 or comparison in a config invocation. `ckconfig.FromConfigKit` adapts a typed
 ConfigKit loader. The `config` command family exposes scope discovery and the
 validate, show, sources, explain, and diff operations supported by the declared
-scopes. Source reports include native destination, placement, unresolved
-destination, and source version-check evidence. Comparison returns ConfigKit's
-native records to the YAML report path; the
+scopes. Source reports include native destination, placement, destination
+fallback, version evidence, and empty-import selections. Comparison returns
+ConfigKit's native records to the YAML report path; the
 [CLI reference](https://gitea.maximumdirect.net/eric/CommandKit/src/branch/main/docs/cli.md#compare-configuration-selections)
 owns its operator details.

--- a/integrations/ckconfig/doc.go
+++ b/integrations/ckconfig/doc.go
@@ -1,10 +1,10 @@
 // Package ckconfig, provided by go.maximumdirect.net/ckconfig, provides
-// CommandKit's optional ConfigKit integration. Its
+// CommandKit's optional ConfigKit v1.1.0 integration, requiring Go 1.27.0. Its
 // canonical Command declaration installs the standard config command family
 // through the core commandkit package. Applications can install CommandKit
 // RoutingRule declarations alongside it through commandkit.New or
 // App.Register. Source reports preserve ConfigKit's destination, placement,
-// and version-check evidence. Invocation reporting applies CommandKit's shared
+// version, and empty-import evidence. Invocation reporting applies CommandKit's shared
 // visibility and delivery policy; provider warnings remain independent of
 // failure explanations. Importing ckconfig alone installs no commands.
 package ckconfig
--- a/integrations/ckconfig/docs/releases/v0.3.0.md
+++ b/integrations/ckconfig/docs/releases/v0.3.0.md
@@ -0,0 +1,25 @@
+# CommandKit ckconfig v0.3.0
+
+## Summary
+
+This candidate adopts `go.maximumdirect.net/configkit v1.1.0` and requires Go
+1.27.0, while retaining `go.maximumdirect.net/commandkit v0.3.0`. It updates
+configuration source reports to expose ConfigKit's current evidence.
+
+## Migration
+
+Change ConfigKit imports from `gitea.maximumdirect.net/eric/ConfigKit` to
+`go.maximumdirect.net/configkit`. Values from the two paths have distinct Go
+type identities. Update application loaders and provider values together with
+ckconfig. Published ckprompt v0.2.0 continues to use ckconfig v0.2.0 and the old
+ConfigKit identity; it does not compose with this candidate.
+
+Source reports rename `destination_unresolved` to `destination_is_fallback` and
+`version_check` to `version_evidence`, use the native `main` layer name, and add
+`empty_import_selections` records (or `[]` when empty). Update report consumers.
+See the [consumer migration guide](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.3.0/docs/consumers/guide.md#configkit-v11-migration)
+for links to upstream configuration and API changes.
+
+[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.3.0/integrations/ckconfig/COPYRIGHT) |
+[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.3.0/integrations/ckconfig/LICENSE) |
+[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.3.0/integrations/ckconfig/docs/oss/attribution.md)
--- a/integrations/ckconfig/examples/simple/README.md
+++ b/integrations/ckconfig/examples/simple/README.md
@@ -1,7 +1,9 @@
 # Simple consumer

 This example imports `go.maximumdirect.net/ckconfig` and
-`go.maximumdirect.net/commandkit`; use ckconfig v0.2.0 with core v0.3.0.
+`go.maximumdirect.net/commandkit`; use the ckconfig v0.3.0 candidate with core
+v0.3.0, ConfigKit v1.1.0, and Go 1.27.0. Set `GOWORK=off GOTOOLCHAIN=local`
+for the commands below.

 Run the maintained example with: