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
|
Without `--check`, successful comparisons return status `0`, including empty
|
||||||
results. Unsupported scopes and formats are usage errors. Application input
|
results. Unsupported scopes and formats are usage errors. Application input
|
||||||
checks can report usage or operational failures. Load and comparison failures
|
checks can report usage or operational failures. Configuration load failures
|
||||||
use status `1`.
|
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 bundled adapters load the left side before the right. Diagnostics identify
|
||||||
the side and its sources; left-side diagnostics are retained if right loading
|
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
|
value or a claim that one is available. Neither report resolves references or
|
||||||
performs a network probe. See the [PromptKit resource inspection
|
performs a network probe. See the [PromptKit resource inspection
|
||||||
contracts](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/resource_inspection.go).
|
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
|
Omitting the ID is a usage error. Configuration loading follows the
|
||||||
shared operational failure rules.
|
[configuration failure classification](#configuration-failure-classification);
|
||||||
|
lookup failures and cancellation are operational.
|
||||||
|
|
||||||
### Resource namespace selection
|
### 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
|
call will succeed. Application loaders and callbacks may have their own
|
||||||
effects. The [PromptKit Prepare
|
effects. The [PromptKit Prepare
|
||||||
API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/engine.go)
|
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
|
## PromptKit requirements
|
||||||
|
|
||||||
@@ -806,9 +810,10 @@ issues:
|
|||||||
PromptKit determines these findings and explanations. A partial report can
|
PromptKit determines these findings and explanations. A partial report can
|
||||||
still be a successful command result (status `0`); read `complete` and
|
still be a successful command result (status `0`); read `complete` and
|
||||||
`issues` to understand what remains unknown. A reported issue alone does not
|
`issues` to understand what remains unknown. A reported issue alone does not
|
||||||
fail this command. Load or selection failures, cancellation, and report
|
fail this command. Configuration loading follows the [configuration failure
|
||||||
delivery failures use status `1`. Invalid syntax, arguments, variable
|
classification](#configuration-failure-classification). Selection failures and
|
||||||
assignments, or formats use status `2`.
|
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
|
### Concrete request validation
|
||||||
|
|
||||||
@@ -867,7 +872,9 @@ not certify provider acceptance or guarantee later execution. See PromptKit's
|
|||||||
[`Engine.ValidateRequest`
|
[`Engine.ValidateRequest`
|
||||||
API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/engine.go).
|
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
|
retaining available diagnostics. Malformed syntax, missing arguments, and
|
||||||
unsupported formats use status `2`. Messages follow the common reporting
|
unsupported formats use status `2`. Messages follow the common reporting
|
||||||
policy; report delivery failures follow the shared [output failure
|
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
|
passed to PromptKit without local membership interpretation. See the
|
||||||
[PromptKit v0.21.0 consumer
|
[PromptKit v0.21.0 consumer
|
||||||
guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09/docs/consumers/pkg-promptkit.md)
|
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
|
## 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,
|
error. It does not mean every check passed: inspect the reported facts,
|
||||||
`reason`, and whether the test was supported, applicable, and completed. For
|
`reason`, and whether the test was supported, applicable, and completed. For
|
||||||
`all`, all four operations must return without error for status `0`.
|
`all`, all four operations must return without error for status `0`.
|
||||||
Individual errors use status `1`; the sequence continues after them but stops
|
Configuration errors use the [configuration failure classification](#configuration-failure-classification);
|
||||||
on cancellation, preserving results already obtained. A report returned with
|
other individual errors use status `1`. For `all`, every failing operation must
|
||||||
an error is still shown. Invalid syntax, arguments, formats, or conflicting
|
identify invalid configuration input to select status `2`; an operational
|
||||||
namespace flags use status `2`.
|
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
|
### Smoke-test flags
|
||||||
|
|
||||||
@@ -1106,10 +1117,23 @@ and [engine API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit
|
|||||||
| Status | Standard meaning |
|
| Status | Standard meaning |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
| `0` | The operation succeeded. |
|
| `0` | The operation succeeded. |
|
||||||
| `1` | Loading, execution, cancellation, or output failed. |
|
| `1` | An operational loading or execution failure, cancellation, or output failure occurred. |
|
||||||
| `2` | The command syntax or supplied inputs were invalid. |
|
| `2` | The command syntax, supplied inputs, or identifiable configuration input were invalid. |
|
||||||
| `3` | `config diff --check` found differences. |
|
| `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
|
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
|
maps to the process exit code. A command's successful status does not replace
|
||||||
reading its report: partial requirements discovery and unsupported smoke
|
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
|
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
|
select core v0.6.0. ckprompt v0.7.0 selects ckconfig v0.7.0, which includes
|
||||||
`AdaptDiagnostics`.
|
`AdaptDiagnostics`.
|
||||||
They build independently against these released dependencies; a local workspace
|
Those published versions build independently against their released dependencies.
|
||||||
is optional for development. Published ckconfig v0.3.0 also uses ConfigKit v1.1.0
|
The current checkout of ckprompt uses an API added to local ckconfig after
|
||||||
and does not compose with ckprompt v0.2.0's earlier ConfigKit dependency.
|
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
|
ConfigKit v1.2.0 adds fields to `Input` and `LayeredOptions`, so application
|
||||||
loaders should use keyed struct literals when constructing them. ConfigKit's
|
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 GoDoc](../../integrations/ckconfig/contracts.go) for the provider boundary.
|
||||||
`ckconfig.AdaptDiagnostics` captures native diagnostic presentation evidence
|
`ckconfig.AdaptDiagnostics` captures native diagnostic presentation evidence
|
||||||
for applications providing their own ConfigKit-backed CLI integration.
|
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
|
Set `Scope.Features.Overrides` only when the loader passes
|
||||||
`Selection.Overrides` to ConfigKit as part of its normal load. The integration
|
`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
|
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
|
the ignored `go.work` and `go.work.sum`; do not commit them. Use
|
||||||
`GOWORK=off GOTOOLCHAIN=local` for dependency preparation
|
`GOWORK=off GOTOOLCHAIN=local` for dependency preparation
|
||||||
and independent module suites. Both integrations select released core v0.6.0;
|
and independent module suites. Both integrations select released core v0.6.0;
|
||||||
ckprompt also selects released ckconfig v0.7.0. Their declared dependencies
|
ckprompt also selects released ckconfig v0.7.0. The current ckprompt source uses
|
||||||
support independent builds. The aligned workspace exercises the local sources
|
the new classifier in local ckconfig, so its independent build is pending
|
||||||
together.
|
publication of ckconfig v0.8.0 and a ckprompt dependency update. The aligned
|
||||||
Run `GOWORK=off GOTOOLCHAIN=local go test ./...` separately from each module
|
workspace exercises the local sources together; ckconfig remains independently
|
||||||
directory. From the repository root, a workspace containing all three modules can
|
buildable against its published dependencies. See the
|
||||||
also run:
|
[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
|
```sh
|
||||||
GOTOOLCHAIN=local go test ./...
|
GOTOOLCHAIN=local go test ./...
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
# Future work
|
# 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.
|
No delivery dates are selected here.
|
||||||
|
|
||||||
## Purpose and authority
|
## 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
|
and [consumer guide](../consumers/guide.md) own implemented behavior. Retaining
|
||||||
an idea here does not select its syntax, API, priority, or delivery date.
|
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 verification
|
||||||
|
|
||||||
### Optional shell completion validation
|
### Optional shell completion validation
|
||||||
|
|||||||
@@ -1,6 +1,7 @@
|
|||||||
# Invalid configuration outcome implementation
|
# 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
|
## Sprint scope and baseline
|
||||||
|
|
||||||
@@ -290,7 +291,15 @@ classification broadening.
|
|||||||
|
|
||||||
## Stage 5 — Update documentation, validate, and record release coordination
|
## 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
|
Update the implemented CLI contract in `docs/cli.md`, including the outcome
|
||||||
table and affected load-failure wording in configuration comparison, inspection,
|
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