Plan configuration outcome implementation

This commit is contained in:
2026-11-16 17:56:34 +00:00
parent a53bf9f916
commit 9d3ffff69f
2 changed files with 361 additions and 115 deletions

View File

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