Document PromptKit comparison and catalogs

2026-10-12 02:38:27 +00:00
parent 4bc0689c44
commit ee038df530
13 changed files with 203 additions and 103 deletions
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -106,8 +106,9 @@ declared scope capabilities and installed handlers, so an operation is listed
 only when the corresponding command is available.

 Applications can add `ckprompt.ConfigScope(loadEngine)` to the ConfigKit suite
-to expose PromptKit engine configuration through these handlers. This scope
-does not install PromptKit prompt or profile definition commands.
+to expose PromptKit engine configuration through these handlers. The scope
+declares validate, show, sources, explain, and native diff. It does not install
+PromptKit prompt or profile definition commands.

 ### Validate configuration

@@ -235,8 +236,11 @@ serialized as `[]`.
 `config diff` prepares two selections for one scope that declares comparison
 and invokes its comparison provider after input checks pass. The default scope
 is `app`; `--scope all` is unsupported.
-The PromptKit engine scope does not currently declare comparison, so selecting
-`--scope promptkit` is a usage error.
+When an application installs `ckprompt.ConfigScope(loadEngine)`, the PromptKit
+scope declares comparison and delegates it to PromptKit's captured
+configuration inspection API. PromptKit owns the meaning of that native
+comparison; CommandKit uses the existing `config diff` preparation and report
+path.
 `--config` and `--overlay` select the left side. `--against-config` and
 `--against-overlay` independently override the right side. When a right-side
 field is omitted, it inherits the corresponding left value and supplied state;
@@ -250,21 +254,24 @@ YAML is the only format and the default. Explicit `--format yaml` is accepted;
 example config diff --config before.yml --against-config after.yml
 example config diff --config base.yml --against-overlay candidate
 example config diff --config base.yml --overlay current --against-overlay ""
+example config diff --scope promptkit --config before.yml --against-config after.yml
 ```

-ConfigKit compares frozen effective typed values after defaults and resolution;
-source or provenance differences alone do not create a change. The report is one
-YAML document with `additions`, `changes`, and `deletions` in that order.
-Additions and changes preserve semantic paths and contain safe right-side values.
-Deletions contain canonical JSON Pointer paths. Explicit null is a value; it is
-not a deletion. Changed sequences and native structural replacement regions stay
-atomic.
+For ConfigKit-backed scopes, ConfigKit compares frozen effective typed values
+after defaults and resolution; source or provenance differences alone do not
+create a change. PromptKit delegates its native comparison to ConfigKit. The
+report is one YAML document with `additions`, `changes`, and `deletions` in that
+order. Additions and changes preserve semantic paths and contain right-side
+values provided by the native comparison. Deletions contain canonical JSON
+Pointer paths. Explicit null is a value; it is not a deletion. Changed sequences
+and native structural replacement regions stay atomic.

 ConfigKit pairs sensitivity across both loads. A concealed change can therefore
-appear even when its two safe snapshots are equal. The report omits separate
-redaction and hidden-change metadata: a reported masked region changed, but that
-does not mean every member inside it changed. Marker-looking public strings stay
-ordinary YAML values. An empty comparison succeeds with this shape:
+appear even when its two safe snapshots are equal. For those ConfigKit-backed
+comparisons, the report omits separate redaction and hidden-change metadata: a
+reported masked region changed, but that does not mean every member inside it
+changed. Marker-looking public strings stay ordinary YAML values. An empty
+comparison succeeds with this shape:

 ```yaml
 additions: {}
@@ -277,7 +284,7 @@ automatically applicable patch. Exceptional whole-root empty/null transitions
 can be ambiguous because the report has no root envelope; ordinary field-level
 null values and deletions retain their distinction.

-Successful comparisons return status `0`, including concealed or empty results.
+Successful comparisons return status `0`, including empty results.
 Unsupported scopes and format errors are usage errors; input checks retain the
 existing usage/operational classification. Load and native comparison failures
 are operational and preserve supported error identity.
@@ -375,6 +382,43 @@ error identity. Cancellation is also operational: standard handlers check the
 caller's context at inspection boundaries, and PromptKit can return cancellation
 from its own inspection methods. Supported cancellation identity is preserved.

+### PromptKit catalogs
+
+An installed `ckprompt.Command(suite)` exposes the catalog commands supplied by
+the suite:
+
+```text
+example promptkit list prompts
+example promptkit list profiles --config settings.yml --campaign spring
+```
+
+Each command accepts `--config`, `--overlay`, and applicable selectors from
+`Suite.Selectors`. It takes no ID or version operand and has no `--version` or
+`--scope` selector. `--format` defaults to `yaml`; `--format yaml` is accepted,
+and other formats are usage errors.
+
+Each invocation writes one bare YAML sequence. Prompt entries have explicit
+string `id` and `version` fields; profile entries are strings. Provider order and
+exact identity values are preserved. For example:
+
+```yaml
+- id: briefing
+  version: "1"
+- id: briefing
+  version: "2"
+```
+
+```yaml
+- autumn
+- spring
+```
+
+Successful nil and allocated-empty inventories both render as `[]`. Catalog
+membership and ordering follow the selected provider, and a listed definition
+is not a readiness check or execution result. PromptKit owns the meaning of its
+native listing APIs; custom providers own their results. Applications retain
+their own disclosure choices for catalog data.
+
 ## Outcome status

 CommandKit usage failures use status `2`; operational failures use status `1`.
--- a/docs/consumers/guide.md
+++ b/docs/consumers/guide.md
@@ -11,7 +11,7 @@ through `commandkit.New` or `App.Register`.
 | --- | --- |
 | `gitea.maximumdirect.net/eric/CommandKit` | The application needs typed command declarations and common CLI behavior. |
 | `gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig` | The application wants ConfigKit-backed configuration scopes and reports. |
-| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | The application wants PromptKit engine configuration or named prompt/profile inspection. |
+| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | The application wants PromptKit engine configuration/comparison, prompt/profile catalogs, or named inspection. |

 The two integrations are independent optional imports. `ckprompt` uses the
 public scope and error contracts from `ckconfig`; importing it does not add the
@@ -123,29 +123,41 @@ owns operator syntax and report details.

 `ckprompt.ConfigScope(loadEngine)` returns a `ckconfig.Scope` for the PromptKit
 engine's captured configuration. Add that scope to a `ckconfig.Suite` to expose
-it under `config`; it does not install named definition commands.
+it under `config` with validate/show/sources/explain and native diff operations;
+it does not install named definition commands.

-`ckprompt.FromEngine(loadEngine)` supplies PromptKit named prompt and profile
-inspection callbacks. Set its `NewInput`, `NewState`, selectors, or validation
-when the application needs them, then pass `ckprompt.Command(suite)` to core.
-Prompt and profile capabilities can be installed independently by providing
-only the corresponding callback. Each selected inspection prepares one input
-and one state value when those steps are reached. See
+`ckprompt.FromEngine(loadEngine)` supplies the prompt/profile catalog callbacks
+and named inspection callbacks. Set its `NewInput`, `NewState`, selectors, or
+validation when the application needs them, then pass `ckprompt.Command(suite)`
+to core. The four callbacks are independently optional; `Command` creates `list`
+and `show` groups only when their corresponding callbacks are present. Narrow a
+bundled suite before command capture when the application wants catalogs without
+named inspections:
+
+```go
+definitions := ckprompt.FromEngine(loadEngine)
+definitions.InspectPrompt = nil
+definitions.InspectProfile = nil
+definitionCommand := ckprompt.Command(definitions)
+```
+
+Each selected inspection or catalog operation prepares one input, applies its
+captured selectors, checks that input, and initializes one state value when
+those steps are reached. See
 [ckprompt.Suite's GoDoc](../../integrations/ckprompt/adapters.go) for factory
 timing, omitted-factory zero values, and caller-owned objects and effects.
 The loader receives invocation context, explicitly supplied selection, input,
-and state. The adapter
-uses PromptKit's public inspection methods and preserves acquisition diagnostics
-and error identity.
+and state. The adapter uses PromptKit's public listing and inspection methods
+and preserves acquisition diagnostics and supported error identity.

-CommandKit-owned inspection code does not execute prompts, contact model
+CommandKit-owned listing and inspection code does not execute prompts, contact model
 providers, or resolve credential values; application loaders and direct callbacks
 retain their own effects. The [CLI reference](../cli.md#promptkit-definition-inspection)
-owns the inspection boundary and credential-report semantics.
+owns the command and report contracts.

 The [composed example](../../integrations/ckprompt/examples/composed/README.md)
-combines app and PromptKit config scopes, independently registers profile
-inspection, and adds an application-owned `session restore` command.
+combines app and PromptKit config scopes, comparison and catalogs, named
+inspection, and an application-owned `session restore` command.

 ## Outcomes and ownership

--- a/docs/development.md
+++ b/docs/development.md
@@ -137,6 +137,9 @@ go run ./examples/core workspace greet --count=0 --tag=first --tag second
 (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 show prompt briefing --campaign spring --format yaml)
 (cd integrations/ckprompt/examples/composed && go run . session restore session-42 --campaign spring)
 ```
--- a/docs/internal/overview.md
+++ b/docs/internal/overview.md
@@ -47,10 +47,11 @@ initialized input, while one suite-owned state value is shared by an invocation'
 acquisitions or comparison callback.

 `integrations/ckprompt` owns PromptKit engine loading, configuration-scope
-adaptation, and optional named prompt/profile inspection. It uses public core
-and ckconfig contracts plus PromptKit's public APIs. It does not add a
-configuration family when its declaration is installed; callers compose
-`ckprompt.ConfigScope` with `ckconfig.Command` separately when they want both.
+adaptation and native comparison, plus optional prompt/profile catalogs and
+named inspection. It uses public core and ckconfig contracts plus PromptKit's
+public APIs. It does not add a configuration family when its declaration is
+installed; callers compose `ckprompt.ConfigScope` with `ckconfig.Command`
+separately when they want configuration operations alongside definition commands.

 The three maintained consumers live at `examples/core`,
 `integrations/ckconfig/examples/simple`, and
--- a/docs/roadmap/configkit.md
+++ b/docs/roadmap/configkit.md
@@ -36,8 +36,8 @@ disclosure; CommandKit owns selection, coordination, adaptation, and presentatio
 | --- | --- |
 | Core module | Go 1.26.0; captured commands, typed bindings, dispatch, outcomes, help, and version. No ConfigKit dependency. ReleaseKit v0.4.0 is the declared maintainer tool. |
 | `integrations/ckconfig` | Requires ConfigKit v0.7.1. `Scope`, `Suite`, `FromConfigKit`, and `AppCommand` expose independently declared validate/show/sources/explain/diff capabilities. |
-| `integrations/ckprompt` | Requires ConfigKit v0.7.1 and PromptKit v0.12.0. It depends on ckconfig's public scope contracts and adapts engine configuration plus named definitions; its ConfigKit scope does not declare comparison. |
-| Comparison status | ConfigKit-backed `config diff` is implemented. The [CLI reference](../cli.md#compare-configuration-selections), integration GoDoc, and [implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/20e19b95694f7fdfd5c342ec4d543152986623dc/docs/roadmap/implementation.md) own current contracts and evidence. PromptKit comparison remains deferred. |
+| `integrations/ckprompt` | The later PromptKit adoption selects PromptKit v0.14.0 and ConfigKit v0.7.1. It adapts engine configuration and exposes native comparison, prompt/profile catalogs, and named definitions through ckconfig and core contracts. |
+| Comparison status | ConfigKit-backed `config diff` and PromptKit engine-scope comparison are implemented. The [CLI reference](../cli.md#compare-configuration-selections) and [PromptKit adoption record](promptkit.md) describe current behavior; the [implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/20e19b95694f7fdfd5c342ec4d543152986623dc/docs/roadmap/implementation.md) records ConfigKit completion. |

 The ConfigKit adapter acquires typed `*configkit.Result[T]` values and exposes
 effective, source, and explanation facets through `View` for ordinary operations.
@@ -62,9 +62,11 @@ and [comparison contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/com

 ## Dependency adoption and ownership

-Both integration modules now select ConfigKit v0.7.1 and carry normal dependency
-metadata for their actual graphs. Consumer Go minimums remain 1.26.0, the selected
-release toolchain remains 1.26.8, and PromptKit remains v0.12.0 for this work.
+Both integration modules select ConfigKit v0.7.1 and carry normal dependency
+metadata for their actual graphs. Consumer Go minimums remain 1.26.0, and the
+selected release toolchain remains 1.26.8. At completion of this ConfigKit work,
+ckprompt still selected PromptKit v0.12.0; the later PromptKit adoption is tracked
+in [promptkit.md](promptkit.md).
 Core continues to have no ConfigKit or optional-integration dependency.

 ConfigKit's declared tool requirement brings ReleaseKit v0.4.1 into the integration
--- a/docs/roadmap/deferred.md
+++ b/docs/roadmap/deferred.md
@@ -5,8 +5,8 @@ Status: retained future work and unselected proposals; no implementation schedul
 ## Purpose and authority

 Completed initial delivery, performance, ReleaseKit upgrade, and remediation
-records have been retired. This document preserves their unfinished capability
-targets and deferred ideas under the
+records have been retired. This document preserves remaining deferred
+capabilities and unselected ideas under the
 [release policy](../policy/release.md#release-documentation-and-preparation).
 The original records remain available in
 [Git history](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/6bc37e7ba64ca0920b4d0cc77039a18d4006b24e/docs/roadmap).
@@ -18,13 +18,13 @@ an idea here does not select its syntax, API, priority, or delivery date.

 ## Deferred capability targets

-### PromptKit configuration comparison
+### PromptKit requirement inspection

-ConfigKit-backed `config diff` is implemented by `ckconfig` for scopes that
-declare that capability. `ckprompt.ConfigScope` does not declare comparison.
-Reassess PromptKit's supported public comparison capabilities before planning a
-PromptKit comparison. Do not reach into ConfigKit internals or infer comparison
-semantics from rendered YAML.
+PromptKit exposes `Engine.InspectRequirements`, but a standard CommandKit
+operation for requirement inspection remains deferred. Its command syntax,
+selection behavior, presentation, and readiness semantics have not been
+selected. Reassess the owning library's public contract and make those product
+choices before planning delivery.

 ### Comparison extensions

@@ -33,16 +33,6 @@ unselected extensions to the delivered ConfigKit comparison. Consider them only
 for a concrete consumer need and a deliberate API/behavior decision under the
 relevant ADRs.

-### CAT-01: PromptKit catalogs
-
-List captured prompt/version entries and named profiles through owning public
-catalog APIs, with deterministic reports of loaded definitions. Resource names,
-enumeration details, and report shapes remain future design work.
-
-The initial PromptKit v0.12.0 review did not find public enumeration APIs.
-Reassess current released capabilities before planning delivery. Do not infer
-catalogs by reparsing configuration YAML or inspecting sibling internals.
-
 ## Other deferred proposals

 These capabilities remain outside the delivered scope and require a concrete
--- a/docs/roadmap/implementation.md
+++ b/docs/roadmap/implementation.md
@@ -1,6 +1,6 @@
 # Implement PromptKit comparison and catalogs

-Status: Stages 1–9 complete; remaining stages are planned.
+Status: Stages 1–10 complete; remaining stages are planned.

 ## Scope and authority

@@ -583,6 +583,29 @@ Review diffs, links/fragments, examples, and stale statements; run documented
 Markdown whitespace checks. Describe native semantics as upstream-owned. Do not
 promise arbitrary catalog/provider data is safe for public disclosure.

+**Completion evidence (2026-10-12)**
+
+- Updated ckprompt GoDoc for native configuration comparison, all four optional
+  callbacks, callback narrowing, selector/input preparation, nil-factory zero
+  values, and catalog YAML defaults. Root and module READMEs now describe the
+  shipped integration.
+- Updated the CLI reference for PromptKit `config diff` and independent prompt
+  and profile catalogs, including selectors, YAML schema/default, empty results,
+  and the owning-library boundary for comparison and catalog membership. It
+  leaves catalog data disclosure with the application/provider.
+- Updated consumer guidance with a narrowing-before-capture example, the
+  internal package overview, and development commands. The PromptKit roadmap now
+  records delivered behavior; the ConfigKit roadmap summary reflects the later
+  PromptKit adoption; and `deferred.md` retains only requirement inspection as a
+  PromptKit capability deferred from this feature.
+- Reviewed the architecture policy and ADRs 0004 and 0008–0012. They remain
+  consistent with the delivered ownership and invocation model; no decision
+  record changes were needed. Historical baseline and ConfigKit completion
+  records remain clearly scoped to their original work.
+- Markdown whitespace checks passed. A local-link and fragment check passed for
+  all ten changed Markdown files. Composed example behavior was exercised and
+  passed with Stage 9's example and complete ckprompt suite checks.
+
 ## Stage 11: Reconcile notices and prepared release notes

 **Outcome:** distributed metadata/notices match actual graphs, and unpublished
--- a/docs/roadmap/promptkit.md
+++ b/docs/roadmap/promptkit.md
@@ -1,7 +1,8 @@
 # Adopt PromptKit v0.14.0 and expose comparison and catalogs

-Status: accepted feature end state; implementation has not started. Scope,
-ownership, catalog API, and initial presentation choices are settled.
+Status: comparison, catalogs, and current behavior documentation are implemented.
+Dependency notice/release-note reconciliation and complete validation remain in
+the [implementation record](implementation.md), Stages 11–12.

 ## Purpose and authority

@@ -34,9 +35,7 @@ This roadmap defines the selected end state. The
 [implementation plan](implementation.md) assigns the ordered work and records
 stage completion evidence.

-## Current baseline
-
-Baseline: CommandKit commit `ab270e2`.
+## Baseline at commit ab270e2

 CommandKit is a prerelease alpha codebase with no existing consumers. The
 maintained consumer examples demonstrate intended usage; this adoption needs no
@@ -48,7 +47,19 @@ consumer migration plan.
 | `integrations/ckconfig` | ConfigKit v0.7.1; independent validate/show/sources/explain/diff capabilities, paired selection/input preparation, and the shared YAML comparison report and delivery path. Report placement uses a report-local mapping index. |
 | `integrations/ckprompt` | PromptKit v0.12.0 and ConfigKit v0.7.1. `ConfigScope` exposes validate/show/sources/explain, without comparison. `Suite` and `FromEngine` expose named prompt/profile inspection; `Command` generates only `promptkit show` children. |
 | Maintained composed consumer | Demonstrates both configuration scopes, app configuration comparison, named prompt/profile inspection, and an application-owned session command. Application configuration caching distinguishes selections and supplied campaign inputs. |
-| Deferred work | PromptKit comparison and catalogs are recorded as future capabilities in [deferred.md](deferred.md). They are targets of this adoption; requirement inspection is deferred separately. |
+| Deferred work | PromptKit comparison and catalogs were future capabilities at this baseline. The later adoption delivers them; requirement inspection remains deferred in [deferred.md](deferred.md). |
+
+## Delivered status
+
+The current repository uses PromptKit v0.14.0. `ConfigScope` declares native
+comparison through `config diff`; `FromEngine` supplies prompt/profile catalog
+and named-inspection callbacks; and `Command` installs only the supplied `list`
+and `show` operations. The maintained composed consumer exercises comparison,
+both catalogs, named inspection, and its application-owned session command.
+Stages 1–10 and their completion evidence are recorded in the
+[implementation plan](implementation.md). Requirement inspection remains
+deferred; distribution reconciliation and complete validation are still pending
+there.

 The existing [ckprompt contracts and adapters](../../integrations/ckprompt/adapters.go)
 and [command assembly](../../integrations/ckprompt/command.go) are the starting
@@ -113,8 +124,8 @@ app config diff --scope promptkit --config before.yml --against-config after.yml
 app config diff --scope promptkit --config base.yml --against-overlay candidate
 ```

-These are target invocations, not currently implemented PromptKit comparisons.
-They use the existing [comparison CLI contract](../cli.md#compare-configuration-selections):
+These invocations use the existing
+[comparison CLI contract](../cli.md#compare-configuration-selections):
 one scope, left selectors and inherited right overrides, shared applicable domain
 selector values, YAML-only additions/changes/deletions presentation, and success
 for completed comparisons regardless of whether differences exist. There is no
@@ -290,7 +301,10 @@ exact strings; quote through the YAML encoder rather than interpreting
 numeric-looking versions. CommandKit defines these report fields explicitly;
 serialization of an upstream Go struct does not define the CLI schema.

-## Work needed from the baseline
+## Selected implementation scope
+
+The sections below record the scope selected for adoption. Implementation status
+and evidence are tracked in the [implementation plan](implementation.md).

 ### Dependencies and distribution