Plan configuration outcome implementation
This commit is contained in:
@@ -1,10 +1,9 @@
|
||||
# Invalid configuration outcomes
|
||||
|
||||
Status — accepted roadmap, pending implementation planning. The user has
|
||||
accepted the targeted integration behavior, the built-in diagnostic mapping
|
||||
with operational fallback, and a shared exported classification function in
|
||||
ckconfig. The implementation plan will enumerate the mapped codes and select
|
||||
the function's exact name and signature.
|
||||
Status — accepted feature roadmap, pending implementation. The user has
|
||||
accepted the targeted behavior and both design decisions below. The
|
||||
[implementation plan](implementation.md) owns the ordered work, exact code
|
||||
mapping, shared API signature, and verification.
|
||||
|
||||
## Purpose
|
||||
|
||||
@@ -89,110 +88,15 @@ execution, and application-specific error semantics retain their owning
|
||||
contracts. The work concerns interpreting returned failure evidence at the CLI
|
||||
boundary.
|
||||
|
||||
## Work needed
|
||||
## Release targets
|
||||
|
||||
### 1. Define the configuration-failure classification
|
||||
|
||||
- Inventory ConfigKit v1.2.0's public diagnostic codes and their documented
|
||||
meaning. Record the selected input-error cases explicitly using upstream
|
||||
constants. Review all code families, including composition, imports,
|
||||
inheritance, versions, overrides, secrets, and configured limits.
|
||||
- Use error-severity diagnostics as failure evidence. Warning records can
|
||||
accompany a failure or a successful result.
|
||||
- Handle wrapped `LoadError` values and standard joined error branches. A failure
|
||||
selects usage only when its failing evidence is classified as invalid input.
|
||||
An operational or unclassified failing branch makes the combined result
|
||||
operational. Preserve the original cause tree.
|
||||
- Account for cancellation and deadlines before choosing usage. When an existing
|
||||
checkpoint observes cancellation alongside an acquisition failure, preserve
|
||||
both causes using the established error-joining approach.
|
||||
- Implement the built-in mapping and error-chain classification in one exported
|
||||
ckconfig function, shared by both integrations. Existing core outcome
|
||||
constructors and reporting provide the required mechanics. Invocation-specific
|
||||
cancellation checks belong in the handlers.
|
||||
|
||||
### 2. Apply it throughout ckconfig
|
||||
|
||||
Wire the classification into acquisition failure handling for `config show`,
|
||||
`config sources`, `config validate`, `config explain`, and `config diff`.
|
||||
|
||||
Follow each operation's current preparation, aggregation, and reporting flow.
|
||||
In particular, source and validation reports can accompany a failed load.
|
||||
Detailed validation filters control displayed findings, while the complete
|
||||
underlying failure supplies classification evidence. Comparison must classify a
|
||||
failure on either loading side and retain the side-specific diagnostic context.
|
||||
|
||||
Include native ConfigKit scopes, PromptKit configuration scopes, and custom
|
||||
scope callbacks returning the supported evidence. Scope selection and input
|
||||
preflight continue through their existing contracts.
|
||||
|
||||
### 3. Apply it throughout ckprompt
|
||||
|
||||
Cover engine-acquisition failures in catalogs, named prompt/profile/backend
|
||||
inspection, requirements discovery, concrete request validation, prepared-request
|
||||
preview, individual smoke operations, and aggregate smoke testing.
|
||||
|
||||
Acquisition evidence may arrive through loaders or application request builders.
|
||||
Use the same classification policy wherever it reaches the standard command's
|
||||
failure boundary. For joined aggregate smoke errors, an operational or
|
||||
unclassified failure takes precedence over input failures. Follow the existing
|
||||
aggregate execution and report lifecycle when selecting the final outcome.
|
||||
|
||||
### 4. Verify observable integration behavior
|
||||
|
||||
Extend focused public-command tests where they provide regression protection.
|
||||
Use upstream errors as fixtures to establish CommandKit's classification and
|
||||
preservation behavior, following the
|
||||
[integration testing policy](../policy/testing.md#upstream-integration-testing-ownership).
|
||||
|
||||
Cover these distinct risks with a proportionate set of cases.
|
||||
|
||||
- Malformed main and companion configuration produce status `2` with
|
||||
`yaml.invalid` and the typed ConfigKit cause available through wrapping.
|
||||
- Representative decoding and selected semantic-validation errors receive the
|
||||
intended classification. Operational and unrecognized loading diagnostics
|
||||
receive status `1`, including mixed failing evidence and warnings alongside
|
||||
errors.
|
||||
- The five configuration operations and affected PromptKit command families use
|
||||
the policy, including comparison-side failures and aggregate smoke outcomes.
|
||||
- Cancellation and deadlines receive status `1` and preserve their supported
|
||||
identity. Already-canceled invocations retain the reviewed empty-output
|
||||
behavior. A failed acquisition combined with cancellation preserves both causes.
|
||||
- Source and validation reports retain their operation-specific failure evidence.
|
||||
Detailed display filters do not determine failure classification.
|
||||
- Output failures continue to follow the shared reporting contract when the
|
||||
command has selected usage status `2`.
|
||||
|
||||
Run the complete deterministic suites independently for each changed integration
|
||||
and with the aligned local workspace as described in the
|
||||
[developer guide](../development.md#documentation-validation). Exercise the
|
||||
maintained examples where their existing assertions cover affected outcomes.
|
||||
The Audita reproduction supplies supporting consumer evidence. CommandKit-owned
|
||||
tests provide the maintained regression coverage.
|
||||
|
||||
### 5. Document and prepare the integration releases
|
||||
|
||||
Update the CLI status table and affected operation sections with the implemented
|
||||
classification. Update any affected exported GoDoc and consumer guidance under
|
||||
their canonical owners. Explain the classification boundary and fallback through
|
||||
the chosen API's documentation.
|
||||
|
||||
Prepare ckconfig v0.8.0 followed by ckprompt v0.8.0, with ckprompt selecting the
|
||||
published ckconfig version. The status-contract change warrants minor releases
|
||||
under the [compatibility policy](../policy/release.md#versioning-and-compatibility).
|
||||
The release notes should explain that identifiable invalid configuration now
|
||||
selects status `2`, alongside the operational classification and preserved error
|
||||
evidence. Follow the [release procedure](../release.md) when publication is
|
||||
authorized. Implementation completion and publication are tracked separately.
|
||||
|
||||
## Completion evidence
|
||||
|
||||
Implementation is complete when the accepted classification is exercised through
|
||||
the public integration commands, the focused regression cases and selected
|
||||
integration suites pass, and the canonical documentation describes the
|
||||
implemented behavior. Review the final diff for the agreed scope and retire this
|
||||
roadmap under the normal documentation lifecycle after recording any unfinished
|
||||
release work.
|
||||
Target ckconfig v0.8.0 followed by ckprompt v0.8.0, with released ckprompt
|
||||
selecting the published ckconfig version containing the shared API. This is a
|
||||
published status-contract change under the
|
||||
[compatibility policy](../policy/release.md#versioning-and-compatibility).
|
||||
Implementation and source publication have their own completion evidence under
|
||||
the [release procedure](../release.md). Pending downstream dependency alignment
|
||||
belongs in the release handoff.
|
||||
|
||||
## Accepted decisions
|
||||
|
||||
@@ -204,9 +108,10 @@ code semantics. Include YAML-content and decoding errors, explicit
|
||||
whose documented meaning clearly identifies invalid configuration content.
|
||||
Classify schema/options defects, acquisition failures, hook execution failures,
|
||||
invalid callback paths or records, and validation mutation as operational.
|
||||
Keep ambiguous limit, secret, and source-selection cases operational until their
|
||||
individual meaning supports input classification. Review and record those cases
|
||||
when preparing the implementation plan.
|
||||
Use operational classification for ambiguous limit, secret, and source-selection
|
||||
evidence. The implementation plan records the individual codes selected under
|
||||
this rule, including limits that explicitly identify excessive input and secret
|
||||
reference errors that explicitly identify invalid configuration.
|
||||
|
||||
This uses the evidence upstream already supplies and distinguishes reported
|
||||
configuration rejection from callback machinery failing. Source evidence
|
||||
@@ -220,12 +125,14 @@ Place one narrowly documented, exported classification function in ckconfig.
|
||||
Both integrations use it, with ckprompt accessing it through its existing
|
||||
dependency. The function inspects the returned error and its ConfigKit
|
||||
diagnostics and returns the appropriate outcome classification. Its
|
||||
responsibilities include the
|
||||
diagnostic mapping, operational fallback, and joined-error precedence.
|
||||
responsibilities include the diagnostic mapping, operational fallback, and
|
||||
joined-error precedence.
|
||||
|
||||
Keep command explanation construction, cause attachment, reporting, and
|
||||
invocation-specific cancellation checks in their owning handlers. Select the
|
||||
function's exact name and signature during implementation planning.
|
||||
invocation-specific cancellation checks in their owning handlers. The
|
||||
implementation plan specifies the shared function as
|
||||
`ClassifyConfigurationError(error) commandkit.OutcomeKind`. It classifies nil as
|
||||
success, identifiable input failures as usage, and other failures as operational.
|
||||
|
||||
A shared implementation reduces drift across the two standard families and
|
||||
fits ckconfig's ownership of ConfigKit adaptation. The narrowly scoped public
|
||||
|
||||
Reference in New Issue
Block a user