# Invalid configuration outcomes Status — implemented, with review remediation complete. The [implementation plan](implementation.md) and [remediation record](remediation.md) record the completed work and verification. Publication and downstream dependency alignment remain in the [release handoff](future.md#configuration-outcome-release-handoff). The accepted behavior and design decisions are recorded below. ## Purpose Make standard ckconfig and ckprompt commands return usage status `2` for identifiable invalid configuration input, while returning operational status `1` for cancellation and other operational failures. Preserve actionable upstream diagnostics and supported typed error identity through the integration boundary. CommandKit owns this CLI classification. ConfigKit and PromptKit own loading, validation, diagnostic meaning, and their public error contracts. Application commands own their domain outcomes. These responsibilities follow the [architecture policy](../policy/architecture.md#ownership-boundaries). ## Historical baseline The reviewed baseline is CommandKit commit `1e92a87706e44684ee34395245e5b633474677e0`, following the publication of ckconfig v0.7.0 and ckprompt v0.7.0. Both integration modules select core v0.6.0 and ConfigKit v1.2.0. ckprompt selects ckconfig v0.7.0 and PromptKit v0.21.0. Their manifests own the dependency selections. The consumer report reproduced malformed operator YAML in Audita, including its automatic `prompts.yml` companion and an explicitly selected application configuration. Delegated inspection returned `yaml.invalid` with status `1`, while Audita's processing command returned the same diagnostic with status `2`. The report's reproduction is retained in Audita's [upstream handoff](https://forge.maximumdirect.net/eric/audita/src/commit/a355f05a273d6ac9d577eab8d30caa60cb74eee8/docs/roadmap/implementation.md). The initial review confirmed the baseline behavior through Audita's existing regression tests and a temporary public-API reproduction against the aligned CommandKit workspace. The latter covered catalog listing and all five configuration operations in both the application and PromptKit scopes, including wrapped ConfigKit loading errors and already-canceled contexts. - [FromConfigKit](../../integrations/ckconfig/configkit_adapter.go) and [the PromptKit adapters](../../integrations/ckprompt/adapters.go) preserved the ConfigKit loading error and adapted its diagnostic evidence. - [configFailure](../../integrations/ckconfig/operations.go) and [definitionFailure](../../integrations/ckprompt/command.go) constructed operational outcomes for the affected failures. Configuration comparison and validation also reached the former helper. - ConfigKit's public `LoadError` represents several kinds of loading failure, including malformed YAML, acquisition errors, and schema or callback problems. Its public diagnostic codes provide the classification evidence. Its error contract intentionally exposes safe diagnostics and preserves its own typed identity across CommandKit adaptation. - `config sources` can report discovered source evidence after failed loading, and `config validate` can report failed validation. Cancellation observed before acquisition leaves stdout empty in the reviewed command paths. At that baseline, the published CLI contract assigned loading failures status `1`. The implemented change classifies identifiable invalid configuration as usage status `2`, with operational fallback, as described in the [current CLI contract](../cli.md#configuration-failure-classification). ## Targeted end state | Evidence available to the integration | Selected outcome | | --- | --- | | ConfigKit error diagnostics that identify invalid configuration input under the selected mapping | Usage, status `2` | | Caller cancellation or deadline observed at an existing operation checkpoint, or present in the returned error chain | Operational, status `1` | | I/O, schema or wiring defects, callback execution failures, and other recognized operational failures | Operational, status `1` | | An unrecognized failure, including a loading error with insufficient classification evidence | Operational, status `1` | | Successful acquisition with warnings | Follow the command's successful-result behavior | Classification uses upstream structured evidence. Diagnostic text, filenames, and source labels serve presentation and provenance. The input-error code mapping follows the accepted decisions below. The selected outcome retains the original returned cause, including ordinary wrapping and joined errors, so supported `errors.Is` and `errors.As` queries continue to work. Existing explanations, source context, diagnostic visibility, and operation-specific reporting lifecycles apply to the newly classified failures. Shared rendering and delivery failures follow the [core output-failure rules](../cli.md#output-failures), including their effect on usage outcomes. Apply the classification to configuration acquisition failures throughout the standard suites, including failures returned by application callbacks when they carry the supported ConfigKit evidence. CLI syntax, resource lookup, request execution, and application-specific error semantics retain their owning contracts. The work concerns interpreting returned failure evidence at the CLI boundary. ## Release targets 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 ### Exact diagnostic-code mapping Use a built-in, explicit mapping based on ConfigKit v1.2.0's public code semantics. Include YAML-content and decoding errors, explicit `version.error`, `resolve.error`, and `validate.error` findings, and other codes 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. 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 alone may be insufficient to establish whether application-supplied data came from an operator, so the rule follows the meaning recorded in upstream diagnostics. ### Shared classification interface 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. Keep command explanation construction, cause attachment, reporting, and 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 function adds an API maintenance obligation while allowing the mapping and error-chain rules to be maintained in one place.