Files
commandkit/docs/roadmap/remediation.md

125 lines
6.5 KiB
Markdown
Raw Normal View History

# Configuration outcome review remediation
Status — R1 complete, R2 open. Findings from the stage-by-stage review of
[the implementation plan](implementation.md) at commit
`8a22dd6`. Review findings concern the accepted
[feature target](invalid-configuration-outcomes.md).
## R1 — Present ConfigKit diagnostics returned by request builders
Priority — P2. Status — complete. Affects Stages 3 and 4.
Completed by sharing ConfigKit loading-error diagnostic adaptation between engine
loaders and all three request builders. Public-command regression coverage now
checks malformed configuration, warnings and semantic rejection, ordinary builder
failures, cancellation, preserved causes, and skipped engine loading across
validation, preparation, individual smoke, and aggregate smoke. The regression
fails against the original adapters using a temporary Go overlay and passes with
the fix. All three aligned-workspace module suites and maintained examples passed
with Go 1.27.0, offline dependencies, and read-only module metadata.
### Relevant implementation
- `WithRequestValidation` returns an empty acquisition when its builder fails in
[adapters.go](../../integrations/ckprompt/adapters.go) at line 196.
- `WithRequestPreparation` does the same in
[preparation.go](../../integrations/ckprompt/preparation.go) at line 43.
- `WithSmokeTesting` does the same in
[smoke.go](../../integrations/ckprompt/smoke.go) at line 51.
- The builder cases in
[configuration_outcomes_test.go](../../integrations/ckprompt/configuration_outcomes_test.go)
discard stderr and assert status and cause identity. The native engine-loader
cases also assert diagnostic presentation.
### Circumstances and observed behavior
An application request builder can load configuration while deriving a concrete
validation, preparation, or smoke request. If that load returns a wrapped
`*configkit.LoadError`, the native adapter returns the original cause with an
empty `Acquired` value. The handler correctly classifies the error, but receives
an empty diagnostic/explanation acquisition. Core renders the handler's generic
failure explanation and usage guidance.
A temporary public-API reproduction used a ConfigKit loading error for malformed
`profiles: [` YAML with source label `operator-prompts.yml`. The following
commands returned status `2` and retained the typed loading cause, while stderr
omitted both `yaml.invalid` and the source label.
- `promptkit requirements validate example`
- `promptkit show prepared example`
- `promptkit test reachability`
- `promptkit test all`
Returning the same error from the engine loader presented the diagnostic and
source context in each command. Builder-failure cases invoked the engine loader
zero times. The early builder returns predate this sprint, but they leave a gap
in its accepted target of preserving actionable configuration diagnostics across
the affected paths. Stage 3 explicitly includes diagnostics in the native
loader/builder verification.
### Expected behavior and remediation
Adapt available ConfigKit source evidence, warnings, and terminal diagnostics
from builder-returned loading errors through the same presentation logic used
for engine-loader failures. Keep the original returned error as the cause and
apply the shared classifier and handler cancellation precedence. A failing
builder completes through its existing failure path.
Reuse `promptKitDiagnostics` and the error adaptation already performed by
`loadPromptKitEngine`. A small private error-to-acquisition helper can make that
adaptation available to all three builder-failure branches. Ordinary application
errors follow their existing explanation and operational fallback behavior.
Extend the public-command builder cases to capture stderr and assert the
diagnostic code, source context, usage status, and typed/wrapped cause. Cover
validation, preparation, individual smoke, and aggregate smoke through their
native adapters. Retain cancellation coverage and verify that the engine loader
is skipped following a builder error. These assertions concern CommandKit's
adaptation of supplied error evidence.
## R2 — Reconcile feature-roadmap status and baseline wording
Priority — P3. Status — open. Affects Stage 5 documentation consistency.
The [feature roadmap](invalid-configuration-outcomes.md) still says
"pending implementation" at its opening. Its baseline section also describes
the current CLI contract as assigning loading failures status `1` and presents
the status change as proposed. Meanwhile, the implementation plan records all
stages complete, and the current
[CLI reference](../cli.md#configuration-failure-classification) documents the
implemented status `2` classification and operational fallback.
Update the feature status to reflect implemented work, outstanding remediation,
and the separately tracked release coordination. Describe the old status `1`
contract explicitly as behavior at the reviewed baseline. Keep the historical
baseline evidence and accepted decisions, with links to the current CLI contract
and [release handoff](future.md#configuration-outcome-release-handoff).
## Review verification
Reviewed the code mapping and error-tree traversal in Stage 1, configuration
failure handling in Stage 2, inspection and request paths in Stage 3, smoke
aggregation and composed scopes in Stage 4, and documentation and release
coordination in Stage 5. The classifier's usage switch matches all 48 constants
in the plan. The implementation maintains the accepted ownership boundaries and
operational fallback.
Using Go 1.27.0, offline dependencies, read-only module metadata, and a temporary
writable build cache, the following suites passed.
- Root module in the aligned workspace, including the core example and scripts.
- ckconfig independently against its declared published dependencies, including
the simple example.
- ckconfig in the aligned workspace, including the simple example.
- ckprompt in the aligned workspace, including the composed example.
Checked 133 local Markdown links/fragments across the six Markdown files changed
by the sprint and checked the sprint diff for whitespace errors. The temporary
builder reproduction described in R1 exercised the public command boundary
with deterministic, local failure fixtures.
ckprompt's independent published-dependency validation follows the recorded
release handoff because its manifest still selects ckconfig v0.7.0. This is the
planned release coordination state. The review identified no additional
strengthened contracts or restrictions requiring remediation.