Document PromptKit request validation

README.md

@@ -16,7 +16,7 @@ constructing them, and returns outcomes without exiting the process. Its
 | --- | --- | --- |
 | `gitea.maximumdirect.net/eric/CommandKit` | `commandkit` | Typed commands, bindings, execution, outcomes, help, and version. |
 | `gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig` | `ckconfig` | ConfigKit-backed `config` scopes and inspection commands. |
-| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | `ckprompt` | PromptKit engine configuration/comparison, prompt/profile catalogs, named inspection, and requirements discovery. |
+| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | `ckprompt` | PromptKit engine configuration/comparison, prompt/profile catalogs, named inspection, requirements discovery, and concrete request validation. |
 
 Importing an integration does not install commands. Pass its declaration to
 `commandkit.New` or `App.Register` to install it. The integrations depend on the

docs/cli.md

@@ -385,9 +385,8 @@ from its own inspection methods. Supported cancellation identity is preserved.
 ## PromptKit requirements
 
 When `Suite.InspectRequirements` is present,
-`ckprompt.Command(suite)` installs the following optional operation. It accepts
+`ckprompt.Command(suite)` installs `promptkit requirements show`. It accepts one
-one required prompt ID and uses PromptKit's native selection and discovery
+required prompt ID and uses PromptKit's native selection and discovery rules:
-rules:
 
 ```text
 example promptkit requirements show briefing --campaign spring
@@ -471,6 +470,78 @@ Provider errors, native selection errors, cancellation, and report delivery
 failures use the operational path (status `1`) with supported cause identity.
 Syntax, operand, variable-assignment, and format errors use usage status `2`.
 
+### Concrete request validation
+
+When `Suite.ValidateRequest` is present, `ckprompt.Command(suite)` also installs
+`promptkit requirements validate`. It can be installed without discovery, and
+discovery can remain installed without validation. The command accepts one
+required prompt ID and passes a concrete request to PromptKit's native
+`Engine.ValidateRequest` preparation path:
+
+```text
+example promptkit requirements validate briefing --campaign spring --input topic=topic.txt
+example promptkit requirements validate briefing --version 2 --profile editorial --session-id session-42 --var mode=full --input notes=notes.txt
+```
+
+The command accepts:
+
+| Flag | Values | Default | Meaning |
+| --- | --- | --- | --- |
+| `--config` | path string | omitted | Select the configuration input; explicit presence is retained. |
+| `--overlay` | path string | omitted | Select one overlay; explicit presence is retained. Repeated occurrences use the last value. |
+| Suite selectors | application-defined | per selector | The flags captured from `Suite.Selectors`. |
+| `--version` | string | empty | Pass the prompt version to PromptKit. |
+| `--profile` | string | empty | Pass the profile ID to PromptKit. |
+| `--session-id` | string | empty | Pass session context to PromptKit. |
+| `--var` | repeatable `KEY=VALUE` | none | Supply caller variables for the concrete request. |
+| `--input` | repeatable `NAME=PATH` | none | Bind a file-backed PromptKit artifact. |
+| `--format` | `yaml` | `yaml` | Select the success confirmation format. Other formats are usage errors. |
+
+The built-in flags other than repeatable `--var` and `--input` are singleton
+bindings; when repeated, the last value is used. Suite selectors retain their
+declared binding behavior. Explicit empty `--config` or `--overlay` values keep
+their supplied-presence information.
+
+The version, profile, and session fields use native empty-string semantics:
+an explicit empty string has the same meaning as omission. PromptKit owns their
+interpretation and selection errors. The `promptkit` namespace identifies the
+operation, so there is no built-in `--scope` flag.
+
+Each `--var` and `--input` occurrence must contain `=`. CommandKit splits at
+the first separator and preserves the exact key/name and remaining value/path.
+Empty variable keys and values are passed to PromptKit. Empty input names and
+paths are also passed to native validation. File paths are translated to
+`promptkit.File(PATH)` references without reading, normalizing, expanding, or
+rebasing them during argument binding. Duplicate keys or names use the last
+value, but all occurrences are parsed, so any malformed occurrence is a usage
+error even if a later assignment is valid. Syntax and path values after shell
+processing are otherwise preserved.
+
+On success, the YAML confirmation contains only the requested prompt ID and
+`valid: true`:
+
+```yaml
+prompt_id: briefing
+valid: true
+```
+
+Validation delegates concrete request preparation to PromptKit. Depending on
+the request and configuration, native preparation may resolve prompt/profile
+resources, load artifact and schema resources, render messages and session
+context, and perform applicable configuration and credential checks. Native
+errors are returned as encountered rather than as an exhaustive inventory.
+Validation does not make a model call or retain a prepared execution snapshot.
+A successful report means preparation passed for this invocation; it does not
+certify provider acceptance or guarantee that later execution will succeed.
+See PromptKit's [v0.15.0 `Engine.ValidateRequest` API](https://gitea.maximumdirect.net/eric/promptkit/src/commit/635674c066d0b432187f96e72b9c03d085443ac5/engine.go)
+for the native contract.
+
+Builder, engine-loading, and native validation errors use the operational path
+(status `1`) with supported error identity and acquired diagnostics retained.
+Malformed syntax, missing operands, and unsupported formats use usage status
+`2`. Input-check failures keep their existing shared handling. Successful
+diagnostics and report-delivery failures follow the common delivery contract.
+
 ### PromptKit catalogs
 
 An installed `ckprompt.Command(suite)` exposes the catalog commands supplied by

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/comparison, prompt/profile catalogs, named inspection, or requirements discovery. |
+| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | The application wants PromptKit engine configuration/comparison, prompt/profile catalogs, named inspection, requirements discovery, or concrete request validation. |
 
 The two integrations are independent optional imports. `ckprompt` uses the
 public scope and error contracts from `ckconfig`; importing it does not add the
@@ -119,22 +119,54 @@ source inventory, path explanation, and ConfigKit-backed comparison for the
 capabilities declared by its scopes. The [CLI reference](../cli.md#configuration-scopes)
 owns operator syntax and report details.
 
-## PromptKit configuration and definitions
+## PromptKit configuration, definitions, and requirements
 
 `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` with validate/show/sources/explain and native diff operations;
 it does not install PromptKit catalog, definition, or requirements commands.
 
-`ckprompt.FromEngine(loadEngine)` supplies the prompt/profile catalog callbacks,
+`ckprompt.FromEngine(loadEngine)` supplies five callbacks: prompt and profile
-named inspection callbacks, and native requirements callback. Set its
+catalogs, named prompt and profile inspection, and native requirements
-`NewInput`, `NewState`, selectors, or validation when the application needs
+discovery. Concrete request validation is a sixth, independently optional
-them, then pass `ckprompt.Command(suite)` to core. All five callbacks are
+capability and is added explicitly with `ckprompt.WithRequestValidation`.
-independently optional; `Command` creates each operation group only when its
+`ckprompt.Command(suite)` creates only operations whose callbacks are present;
-callbacks are present. Applications can use the requirements callback alone,
+discovery and validation share `promptkit requirements` but can be installed
-clear it while retaining other operations, wrap it, or replace it with their
+independently. A composed suite can keep the standard five and add validation:
-own provider. For catalogs without named or requirements inspection, narrow the
+
-suite before command capture:
+```go
+suite := ckprompt.FromEngine(loadEngine)
+suite = ckprompt.WithRequestValidation(suite, loadEngine, buildRequest)
+suite.NewInput = newInput
+suite.NewState = newState
+suite.Selectors = selectors
+definitionCommand := ckprompt.Command(suite)
+```
+
+A validation-only suite can start empty. With application types named `Input`
+and `State`, a nil builder forwards the request fields populated by standard
+flags directly to PromptKit:
+
+```go
+suite := ckprompt.WithRequestValidation(
+	ckprompt.Suite[Input, State]{}, loadEngine, nil,
+)
+validationCommand := ckprompt.Command(suite)
+```
+
+If the loader is nil, the returned suite retains a wiring issue for installation
+to report, even if capabilities are narrowed later. A builder runs before the
+engine loader and receives the seed request, selection, typed input, shared
+state, and invocation context. It returns the
+concrete request; the adapter does not merge seed fields back afterward. The
+loader receives the original selection. Builders should start from the seed,
+preserve operator values and bindings, and apply defaults only when a map key is
+absent, so explicitly supplied empty values stay meaningful. Applications that
+validate and then execute a request are encouraged to share their request
+construction logic between those paths.
+
+All six suite capabilities are independently optional. For catalogs without
+named or requirements inspection, narrow the suite before command capture:
 
 ```go
 definitions := ckprompt.FromEngine(loadEngine)
@@ -144,20 +176,28 @@ definitions.InspectRequirements = nil
 definitionCommand := ckprompt.Command(definitions)
 ```
 
-Each selected inspection, requirements, or catalog operation prepares one input,
+Each selected inspection, requirements, validation, or catalog operation
-applies its captured selectors, checks that input, and initializes one state
+prepares one input, applies its captured selectors, checks that input, and
-value when those steps are reached. See
+initializes one state value when those steps are reached. The bundled validation
+adapter delegates concrete request preparation to PromptKit and carries its
+native errors plus engine-loading diagnostics through the acquisition. It does
+not call the model or retain a prepared execution snapshot. 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 listing and inspection methods,
+and state. `FromEngine` uses PromptKit's public listing and inspection methods,
-including `Engine.InspectRequirements`, and preserves acquisition diagnostics
+including `Engine.InspectRequirements`; validation must be opted into separately
-and supported error identity.
+and uses `Engine.ValidateRequest`.
 
-CommandKit-owned listing and inspection code does not execute prompts, contact model
+Catalog, named definition inspection, and requirements discovery do not render
-providers, or resolve credential values; application loaders and direct callbacks
+messages or load request artifacts. Concrete request validation follows native
-retain their own effects. The [CLI reference](../cli.md#promptkit-definition-inspection)
+PromptKit preparation, which can resolve prompt/profile resources, load
-owns the command and report contracts.
+artifacts and schemas, render messages, and perform applicable configuration
+and credential checks. It does not make a model call or certify that a later
+execution will succeed. Application loaders and direct callbacks retain their
+own effects. The [CLI reference](../cli.md#promptkit-definition-inspection)
+and [requirements contract](../cli.md#promptkit-requirements) own operator
+syntax and reports.
 
 The [composed example](../../integrations/ckprompt/examples/composed/README.md)
 combines app and PromptKit config scopes, comparison and catalogs, named and

docs/development.md

@@ -4,8 +4,9 @@ CommandKit is distributed as a core Go module and two optional integration
 modules. Core owns captured declarations, typed input preparation, installation,
 dispatch, outcomes, help, and version. `integrations/ckconfig` owns ConfigKit
 scope adaptation and reports; `integrations/ckprompt` owns PromptKit engine,
-definition inspection, and requirements discovery adapters. The maintained
+definition inspection, requirements discovery, and concrete request validation.
-[consumer guide](consumers/guide.md) links to the three maintained consumers.
+The maintained [consumer guide](consumers/guide.md) links to the three maintained
+consumers.
 The [README](../README.md) provides project orientation; the
 [documentation policy](policy/documentation.md#canonical-ownership) assigns
 canonical documentation owners.
@@ -144,6 +145,8 @@ go run ./examples/core workspace greet --count=0 --tag=first --tag second
 (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 . session restore session-42 --campaign spring)
 ```
 

docs/internal/overview.md

@@ -48,11 +48,13 @@ acquisitions or comparison callback.
 
 `integrations/ckprompt` owns PromptKit engine loading, configuration-scope
 adaptation and native comparison, plus optional prompt/profile catalogs, named
-inspection, and native requirements discovery. It uses public core and ckconfig
+inspection, native requirements discovery, and concrete request validation.
-contracts plus PromptKit's public APIs. It does not add a configuration family
+Validation delegates request preparation to PromptKit and is independently
-when its declaration is installed; callers compose `ckprompt.ConfigScope` with
+opted into a suite. It uses public core and ckconfig contracts plus PromptKit's
-`ckconfig.Command` separately when they want configuration operations alongside
+public APIs. It does not add a configuration family when its declaration is
-PromptKit commands.
+installed; callers compose `ckprompt.ConfigScope` with `ckconfig.Command`
+separately when they want configuration operations alongside PromptKit
+commands.
 
 The three maintained consumers live at `examples/core`,
 `integrations/ckconfig/examples/simple`, and
@@ -67,7 +69,9 @@ graph isolation.
 
 ConfigKit owns configuration decoding, validation, source history, and path
 explanations. PromptKit owns its captured engine configuration, prompt
-definitions, profile inheritance, and named inspection semantics. CommandKit
+definitions, profile inheritance, named inspection, requirements discovery,
-adapts those public contracts without maintaining parallel schemas or invoking
+and concrete request validation semantics. CommandKit adapts those public
-prompt execution. Application loaders and domain behavior remain application
+contracts without maintaining parallel schemas or invoking model generation.
-owned.
+Native request validation may load resources and artifacts, render messages,
+and perform applicable configuration or credential checks through PromptKit.
+Application loaders and domain behavior remain application owned.

docs/roadmap/implementation.md

@@ -1,6 +1,6 @@
 # PromptKit request validation implementation plan
 
-Status: Stages 1–7 complete; implementation is ongoing.
+Status: Stages 1–8 complete; implementation is ongoing.
 
 ## Authority, scope, and baseline
 
@@ -462,6 +462,15 @@ mandates.
 capability under its assigned owners, with no stale five-callback or
 metadata-only claims covering request validation.
 
+**Completed:** 2026-10-12. Updated ckprompt GoDoc, the CLI reference, consumer
+guidance, README module summary, development orientation and examples, and the
+internal component inventory. The docs distinguish `FromEngine`'s five
+callbacks from explicit validation composition, describe native preparation and
+the minimal success YAML, and scope discovery-only statements to discovery.
+`GOTOOLCHAIN=local go test -count=1 ./...` passed from `integrations/ckprompt`;
+the Stage 7 consumer tests and commands remain unchanged and passed. Changed
+Markdown links and anchors and Markdown whitespace checks passed.
+
 ## Stage 9: Validate the complete end state and finish
 
 1. Format changed Go files and inspect the final diff for scope, generated junk,

integrations/ckprompt/adapters.go

@@ -43,7 +43,7 @@ type RequirementsRequest struct {
 }
 
 // Suite describes application-owned input, shared state, and optional catalog,
-// named inspection, requirements inspection, and concrete request validation
+// named inspection, requirements discovery, and concrete request validation
 // capabilities. Its private issues retain adapter construction failures.
 // Factory results and callback effects remain caller-owned: Command does not
 // deep-copy arbitrary objects or repair aliases returned by factories.
@@ -52,13 +52,14 @@ type RequirementsRequest struct {
 // Factories are not invoked during construction, installation, help, or version,
 // and need not run after failure.
 type Suite[I, S any] struct {
-	// NewInput is called once when definition, requirements, validation, or catalog input
+	// NewInput is called once when definition, requirements, validation, or
-	// preparation is reached, before applying selectors and calling CheckInput.
+	// catalog input preparation is reached, before applying selectors and
+	// calling CheckInput.
 	// If nil, input is the zero value of I, including nil for pointer types.
 	NewInput func() I
-	// NewState is called once when an inspection, validation, or catalog callback is reached,
+	// NewState is called once when an inspection, validation, or catalog
-	// after input checks pass. If nil, state is the zero value of S, including
+	// callback is reached, after input checks pass. If nil, state is the zero
-	// nil for pointer types.
+	// value of S, including nil for pointer types.
 	NewState func() S
 	// Selectors declares the original typed flags accepted by definition,
 	// requirements, validation, and catalog commands.
@@ -71,12 +72,15 @@ type Suite[I, S any] struct {
 	// InspectProfile inspects the selected profile after input and state preparation.
 	InspectProfile func(context.Context, ProfileRequest, I, S) (commandkit.Acquired[*promptkit.ProfileInspection], error)
 	// InspectRequirements inspects native PromptKit requirements after input and
-	// state preparation. It is optional; a nil callback omits the requirements
+	// state preparation. It is optional; a nil callback omits
-	// command without disabling other capabilities.
+	// `promptkit requirements show` without disabling validation or other
+	// capabilities.
 	InspectRequirements func(context.Context, RequirementsRequest, I, S) (commandkit.Acquired[*promptkit.RequirementInspection], error)
-	// ValidateRequest validates a concrete PromptKit request after input and state
+	// ValidateRequest validates a concrete PromptKit request after input and
-	// preparation. It is optional; a nil callback omits request validation without
+	// state preparation. It is optional; a nil callback omits
-	// disabling other capabilities.
+	// `promptkit requirements validate` without disabling discovery or other
+	// capabilities. The acquisition carries diagnostics and an empty value on
+	// success; PromptKit errors are returned unchanged where supported.
 	ValidateRequest func(context.Context, ValidationRequest, I, S) (commandkit.Acquired[struct{}], error)
 	// ListPrompts lists prompt identities after input and state preparation.
 	// It is optional; a nil callback does not install a prompt catalog command.
@@ -89,13 +93,18 @@ type Suite[I, S any] struct {
 }
 
 // WithRequestValidation attaches PromptKit-backed concrete request validation
-// to suite. The loader receives the request's original selection; the builder,
+// to suite while preserving its other capabilities and retained issues. Those
-// when present, runs first and its returned request is passed to PromptKit
+// issues remain attached if capabilities are narrowed before Command captures
-// unchanged. A nil builder forwards the seed request. PromptKit's native
+// the suite. The
-// validation errors and the engine loader's configuration diagnostics are
+// builder, when present, runs before the engine loader and receives the seed,
-// returned through the acquisition. A nil loader is retained as a suite wiring
+// input, state, and invocation context. Its returned request is passed to
-// issue and does not install a validation callback. Caller-owned callback
+// PromptKit unchanged; the loader receives the seed's original configuration
-// references and objects remain caller-owned.
+// selection. A nil builder forwards the seed request unchanged. A builder
+// failure prevents engine loading and preserves its supported error identity.
+// Native validation errors are returned with supported identity, and
+// configuration diagnostics from engine loading remain in the acquisition. A
+// nil loader is retained as a suite wiring issue and does not install a
+// validation callback. Callback references and objects remain caller-owned.
 func WithRequestValidation[I, S any](
 	suite Suite[I, S],
 	load func(context.Context, ckconfig.Selection, I, S) (*promptkit.Engine, error),
@@ -218,15 +227,17 @@ func promptKitContextError(ctx context.Context) error {
 	return ctx.Err()
 }
 
-// FromEngine supplies prompt and profile catalog callbacks, named inspection
+// FromEngine supplies five PromptKit-backed callbacks: prompt and profile
-// callbacks, and a requirements inspection callback backed by a PromptKit engine
+// catalogs, named prompt and profile inspection, and requirements discovery.
-// loader. The requirements callback forwards RequirementsRequest.Inspection to
+// The requirements callback forwards RequirementsRequest.Inspection to
-// Engine.InspectRequirements. FromEngine does not call the loader during
+// Engine.InspectRequirements. Concrete request validation is an independent
-// construction. Each selected operation passes its context, supplied
+// capability and can be composed explicitly with WithRequestValidation.
-// selection, initialized input, and shared invocation state to the loader before
+// FromEngine does not call the loader during construction. Each selected
-// calling PromptKit's public listing or inspection method. Applications can
+// operation passes its context, supplied selection, initialized input, and
-// narrow, wrap, or replace these callbacks before Command captures them. A nil
+// shared invocation state to the loader before calling PromptKit's public
-// loader is retained as an adapter issue.
+// listing or inspection method. Applications can narrow, wrap, or replace these
+// callbacks before Command captures them. A nil loader is retained as an
+// adapter issue.
 func FromEngine[I, S any](load func(context.Context, ckconfig.Selection, I, S) (*promptkit.Engine, error)) Suite[I, S] {
 	if load == nil {
 		return Suite[I, S]{issues: []error{errors.New("PromptKit engine loader is nil")}}

integrations/ckprompt/command.go

@@ -50,14 +50,16 @@ type inputAssignment struct {
 }
 
 // Command captures the optional PromptKit catalog, named inspection,
-// requirements inspection, and concrete request validation callbacks and adds
+// requirements discovery, and concrete request validation callbacks and adds
-// only supplied operations. An absent suite claims no namespace; attached
+// only supplied operations. Discovery and validation share the
-// construction issues remain reportable. It adds no configuration family;
+// `requirements` group and remain independently optional. An absent suite
-// callers compose ConfigScope independently. Construction, installation, help,
+// claims no namespace; attached construction issues remain reportable. It adds
-// and version do not run suite factories or providers. Command captures suite
+// no configuration family; callers compose ConfigScope independently.
-// callbacks and selector metadata; callback-referenced objects and effects
+// Construction, installation, help, and version do not run suite factories or
-// remain caller-owned. Suite documents invocation input and state initialization,
+// providers. Command captures suite callbacks and selector metadata;
-// zero values, and caller ownership of returned objects.
+// callback-referenced objects and effects remain caller-owned. Suite documents
+// invocation input and state initialization, zero values, and caller ownership
+// of returned objects.
 // Catalog commands accept config/overlay selection and suite selectors, and
 // render YAML with `yaml` as the only format and default. Named-show formats are
 // unchanged.

integrations/ckprompt/doc.go

@@ -1,5 +1,5 @@
 // Package ckprompt provides optional PromptKit configuration comparison,
-// definition catalogs, named inspections, and prompt requirements inspection
+// definition catalogs, named inspections, requirements discovery, and concrete
-// for CommandKit. Importing ckprompt installs neither family; callers compose
+// request validation for CommandKit. Importing ckprompt installs neither
-// its declarations with core and ckconfig explicitly.
+// family; callers compose its declarations with core and ckconfig explicitly.
 package ckprompt

integrations/ckprompt/validation.go

@@ -5,12 +5,12 @@ import (
 	promptkit "gitea.maximumdirect.net/eric/promptkit"
 )
 
-// ValidationRequest carries the configuration selection and concrete
+// ValidationRequest carries the configuration selection and seed PromptKit
-// PromptKit request to validate.
+// request populated by the standard validation command inputs.
 type ValidationRequest struct {
 	// Selection identifies the configuration sources used to load the engine.
 	Selection ckconfig.Selection
-	// Request is the seed request, or the request returned by a validation
+	// Request contains the prompt identity, scalar context, variables, and
-	// builder when one is configured.
+	// artifact references supplied to the command.
 	Request promptkit.RunRequest
 }