Document configuration outcomes and release handoff
This commit is contained in:
56
docs/cli.md
56
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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 ./...
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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,
|
||||
|
||||
19
integrations/ckconfig/docs/releases/v0.8.0.md
Normal file
19
integrations/ckconfig/docs/releases/v0.8.0.md
Normal 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)
|
||||
Reference in New Issue
Block a user