diff --git a/docs/cli.md b/docs/cli.md index ecc4cb1..fae8a42 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -622,8 +622,9 @@ fields remain distinct. Without `--check`, successful comparisons return status `0`, including empty results. Unsupported scopes and formats are usage errors. Application input -checks can report usage or operational failures. Load and comparison failures -use status `1`. +checks can report usage or operational failures. Configuration load failures +follow the [configuration failure classification](#configuration-failure-classification); +other comparison failures use status `1`. The bundled adapters load the left side before the right. Diagnostics identify the side and its sources; left-side diagnostics are retained if right loading @@ -666,8 +667,9 @@ request overrides. Backend reports describe configured backend fields. An value or a claim that one is available. Neither report resolves references or performs a network probe. See the [PromptKit resource inspection contracts](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/resource_inspection.go). -Omitting the ID is a usage error. Lookup failures and cancellation follow the -shared operational failure rules. +Omitting the ID is a usage error. Configuration loading follows the +[configuration failure classification](#configuration-failure-classification); +lookup failures and cancellation are operational. ### Resource namespace selection @@ -721,7 +723,9 @@ application content in the report. It does not guarantee that a later model call will succeed. Application loaders and callbacks may have their own effects. The [PromptKit Prepare API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/engine.go) -owns the prepared value and upstream preparation behavior. +owns the prepared value and upstream preparation behavior. Configuration failures +follow the [configuration failure classification](#configuration-failure-classification); +other preparation failures are operational. ## PromptKit requirements @@ -806,9 +810,10 @@ issues: PromptKit determines these findings and explanations. A partial report can still be a successful command result (status `0`); read `complete` and `issues` to understand what remains unknown. A reported issue alone does not -fail this command. Load or selection failures, cancellation, and report -delivery failures use status `1`. Invalid syntax, arguments, variable -assignments, or formats use status `2`. +fail this command. Configuration loading follows the [configuration failure +classification](#configuration-failure-classification). Selection failures and +cancellation use status `1`; invalid syntax, arguments, variable assignments, +or formats use status `2`. Report delivery follows the [output failure rules](#output-failures). ### Concrete request validation @@ -867,7 +872,9 @@ not certify provider acceptance or guarantee later execution. See PromptKit's [`Engine.ValidateRequest` API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/engine.go). -Request construction, engine loading, and validation failures use status `1`, +Configuration errors returned by request construction or engine loading follow +the [configuration failure classification](#configuration-failure-classification). +Other request construction, loading, and validation failures use status `1`, retaining available diagnostics. Malformed syntax, missing arguments, and unsupported formats use status `2`. Messages follow the common reporting policy; report delivery failures follow the shared [output failure @@ -931,7 +938,8 @@ The owning provider controls membership and order. Namespace filters are passed to PromptKit without local membership interpretation. See the [PromptKit v0.21.0 consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/docs/consumers/pkg-promptkit.md) -for resource and selection definitions. +for resource and selection definitions. Catalog loading failures follow the +[configuration failure classification](#configuration-failure-classification). ## PromptKit smoke testing @@ -965,10 +973,13 @@ Status `0` means the requested operation and reporting completed without error. It does not mean every check passed: inspect the reported facts, `reason`, and whether the test was supported, applicable, and completed. For `all`, all four operations must return without error for status `0`. -Individual errors use status `1`; the sequence continues after them but stops -on cancellation, preserving results already obtained. A report returned with -an error is still shown. Invalid syntax, arguments, formats, or conflicting -namespace flags use status `2`. +Configuration errors use the [configuration failure classification](#configuration-failure-classification); +other individual errors use status `1`. For `all`, every failing operation must +identify invalid configuration input to select status `2`; an operational +failure or cancellation takes precedence. The sequence continues after errors +but stops on cancellation, preserving results already obtained. A report +returned with an error is still shown. Invalid syntax, arguments, formats, or +conflicting namespace flags use status `2`. ### Smoke-test flags @@ -1106,10 +1117,23 @@ and [engine API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit | Status | Standard meaning | | --- | --- | | `0` | The operation succeeded. | -| `1` | Loading, execution, cancellation, or output failed. | -| `2` | The command syntax or supplied inputs were invalid. | +| `1` | An operational loading or execution failure, cancellation, or output failure occurred. | +| `2` | The command syntax, supplied inputs, or identifiable configuration input were invalid. | | `3` | `config diff --check` found differences. | +### Configuration failure classification + +Standard configuration and PromptKit commands classify ConfigKit loading errors +using their structured diagnostics. Identifiable invalid configuration input, +including malformed YAML, decoding errors, and explicit semantic rejection, +selects status `2`. Warnings do not fail a load. Missing or unreadable sources, +schema and application wiring errors, callback failures, unknown or ambiguous +diagnostics, and other failures select status `1`. An error with multiple +failing branches selects status `2` only when every branch identifies invalid +input; cancellation or a deadline always selects status `1`. Existing source +and validation reports can still be delivered after a failed load. Filters on +validation details do not change classification. + Applications may define additional results and decide how CommandKit's status maps to the process exit code. A command's successful status does not replace reading its report: partial requirements discovery and unsupported smoke diff --git a/docs/consumers/guide.md b/docs/consumers/guide.md index 9d5fc76..37f0488 100644 --- a/docs/consumers/guide.md +++ b/docs/consumers/guide.md @@ -34,9 +34,13 @@ Select either integration with `go get go.maximumdirect.net/ckconfig@v0.7.0` or `go get go.maximumdirect.net/ckprompt@v0.7.0`. The published integrations select core v0.6.0. ckprompt v0.7.0 selects ckconfig v0.7.0, which includes `AdaptDiagnostics`. -They build independently against these released dependencies; a local workspace -is optional for development. Published ckconfig v0.3.0 also uses ConfigKit v1.1.0 -and does not compose with ckprompt v0.2.0's earlier ConfigKit dependency. +Those published versions build independently against their released dependencies. +The current checkout of ckprompt uses an API added to local ckconfig after +v0.7.0, so it requires the aligned workspace until ckconfig v0.8.0 is published +and ckprompt updates its dependency. See the +[release handoff](../roadmap/future.md#configuration-outcome-release-handoff). +Published ckconfig v0.3.0 also uses ConfigKit v1.1.0 and does not compose with +ckprompt v0.2.0's earlier ConfigKit dependency. ConfigKit v1.2.0 adds fields to `Input` and `LayeredOptions`, so application loaders should use keyed struct literals when constructing them. ConfigKit's @@ -321,6 +325,10 @@ acquired evidence. See `EffectiveWriter` and `ExplanationReader` in the [ckconfig GoDoc](../../integrations/ckconfig/contracts.go) for the provider boundary. `ckconfig.AdaptDiagnostics` captures native diagnostic presentation evidence for applications providing their own ConfigKit-backed CLI integration. +[`ckconfig.ClassifyConfigurationError`](../../integrations/ckconfig/errors.go) +provides the standard CLI outcome classification for ConfigKit errors; callers +construct their own outcomes, explanations, and causes. The [CLI reference](../cli.md#configuration-failure-classification) +describes the standard commands' status behavior. Set `Scope.Features.Overrides` only when the loader passes `Selection.Overrides` to ConfigKit as part of its normal load. The integration parses CLI records but cannot add them to an already-loaded result. The diff --git a/docs/development.md b/docs/development.md index cd04bc9..92e6ca7 100644 --- a/docs/development.md +++ b/docs/development.md @@ -119,12 +119,15 @@ If a workspace already exists, ensure it includes these three modules. Preserve the ignored `go.work` and `go.work.sum`; do not commit them. Use `GOWORK=off GOTOOLCHAIN=local` for dependency preparation and independent module suites. Both integrations select released core v0.6.0; -ckprompt also selects released ckconfig v0.7.0. Their declared dependencies -support independent builds. The aligned workspace exercises the local sources -together. -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: +ckprompt also selects released ckconfig v0.7.0. The current ckprompt source uses +the new classifier in local ckconfig, so its independent build is pending +publication of ckconfig v0.8.0 and a ckprompt dependency update. The aligned +workspace exercises the local sources together; ckconfig remains independently +buildable against its published dependencies. See the +[release handoff](roadmap/future.md#configuration-outcome-release-handoff). +Run `GOWORK=off GOTOOLCHAIN=local go test ./...` separately for core and +ckconfig, and for ckprompt after its published dependency is updated. From the +repository root, a workspace containing all three modules can also run: ```sh GOTOOLCHAIN=local go test ./... diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 548a604..feac7ba 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -1,6 +1,6 @@ # Future work -Status: optional shell validation and future capability proposals. +Status: release coordination, optional shell validation, and future capability proposals. No delivery dates are selected here. ## Purpose and authority @@ -30,6 +30,24 @@ govern any future implementation. The [CLI reference](../cli.md), public GoDoc, and [consumer guide](../consumers/guide.md) own implemented behavior. Retaining an idea here does not select its syntax, API, priority, or delivery date. +## Configuration outcome release handoff + +The current ckprompt source requires the classifier in local ckconfig, while +its published dependency remains ckconfig v0.7.0. The aligned workspace +validates the source combination; ckprompt independent validation remains +pending until the dependency is published and updated. Follow the +[dependency-first release procedure](../release.md#scope-and-release-order): + +1. When publication is authorized, publish ckconfig v0.8.0 from its independently + validated candidate. +2. Prepare ckprompt against the actual published ckconfig v0.8.0 using `go get` + and `go mod download` with `GOWORK=off GOTOOLCHAIN=local`, retaining the real + checksums. Complete its v0.8.0 release note, compatibility guidance, and + candidate preparation under the existing rules for its other dependencies. +3. Independently validate and publish ckprompt v0.8.0 under the same + authorization and procedure. Track hosted release delivery separately under + the runbook. + ## Optional verification ### Optional shell completion validation diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 7d83d0a..f4344cf 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,6 +1,7 @@ # Invalid configuration outcome implementation -Status — ready for implementation. Stages are pending. +Status — complete. Release coordination remains in the +[future work handoff](future.md#configuration-outcome-release-handoff). ## Sprint scope and baseline @@ -290,7 +291,15 @@ classification broadening. ## Stage 5 — Update documentation, validate, and record release coordination -Status — pending. +Status — complete. Updated the CLI and consumer contracts, development +guidance, ckconfig v0.8.0 release note, and dependency-first release handoff. +With Go 1.27.0 and a temporary writable Go build cache, the independent ckconfig +suite passed with `GOWORK=off GOTOOLCHAIN=local GOPROXY=off go test +-mod=readonly ./...`. In the aligned workspace, the three prescribed +`GOTOOLCHAIN=local GOPROXY=off go test -mod=readonly` commands passed for +`./...`, `./integrations/ckconfig/...`, and `./integrations/ckprompt/...`. +Reviewed the diff, local Markdown links and fragments, and whitespace. The +independent ckprompt build remains pending publication and dependency alignment. Update the implemented CLI contract in `docs/cli.md`, including the outcome table and affected load-failure wording in configuration comparison, inspection, diff --git a/integrations/ckconfig/docs/releases/v0.8.0.md b/integrations/ckconfig/docs/releases/v0.8.0.md new file mode 100644 index 0000000..576406e --- /dev/null +++ b/integrations/ckconfig/docs/releases/v0.8.0.md @@ -0,0 +1,19 @@ +# CommandKit ckconfig v0.8.0 + +CommandKit ckconfig v0.8.0 classifies identifiable invalid ConfigKit input as a +usage failure. The new `ClassifyConfigurationError` function exposes the same +CLI classification for callers building their own outcomes. + +## Compatibility and upgrade + +Select `go.maximumdirect.net/ckconfig v0.8.0` with CommandKit core v0.6.0. The +consumer minimum remains Go 1.27.0. Standard configuration commands now return +status `2` for diagnostic evidence identifying invalid configuration input; +previously these loading failures returned status `1`. Update scripts that +interpret those statuses. Cancellation, operational failures, and ambiguous or +unknown evidence remain status `1`. See the [CLI contract](../../../../docs/cli.md#configuration-failure-classification) +and the [classifier GoDoc](../../errors.go) for details. + +[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.8.0/integrations/ckconfig/COPYRIGHT) | +[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.8.0/integrations/ckconfig/LICENSE) | +[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.8.0/integrations/ckconfig/docs/oss/attribution.md)