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
|
||||
|
||||
Reference in New Issue
Block a user