Document configuration outcomes and release handoff

This commit is contained in:
2026-11-16 18:08:33 +00:00
parent 20d2924338
commit 8a22dd6a4f
6 changed files with 109 additions and 28 deletions

View File

@@ -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

View File

@@ -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

View File

@@ -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 ./...

View File

@@ -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

View File

@@ -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,

View File

@@ -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)