From 263dc420b45ee851aa65665e8f82910a5f5b9ec5 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 16 Nov 2026 19:07:57 +0000 Subject: [PATCH] Record integration v0.8.0 releases and retire completed plans --- docs/consumers/guide.md | 21 +- docs/development.md | 13 +- docs/roadmap/future.md | 23 +- docs/roadmap/implementation.md | 373 ------------------ .../roadmap/invalid-configuration-outcomes.md | 142 ------- docs/roadmap/remediation.md | 130 ------ 6 files changed, 18 insertions(+), 684 deletions(-) delete mode 100644 docs/roadmap/implementation.md delete mode 100644 docs/roadmap/invalid-configuration-outcomes.md delete mode 100644 docs/roadmap/remediation.md diff --git a/docs/consumers/guide.md b/docs/consumers/guide.md index 37f0488..951cbed 100644 --- a/docs/consumers/guide.md +++ b/docs/consumers/guide.md @@ -14,14 +14,14 @@ applications. | `go.maximumdirect.net/ckconfig` | You want operators to view, validate, explain, and compare ConfigKit configuration. | | `go.maximumdirect.net/ckprompt` | You want operators to inspect PromptKit resources, check and preview requests, or run smoke tests. | -The v0.7.0 integrations select ConfigKit v1.2.0, and ckprompt selects PromptKit +The v0.8.0 integrations select ConfigKit v1.2.0, and ckprompt selects PromptKit v0.21.0. | Selection | Core | ckconfig | ckprompt | Upstream libraries and status | | --- | --- | --- | --- | --- | | Published core | v0.6.0 | — | — | Usable independently. | -| ConfigKit integration | v0.6.0 | v0.7.0 | — | ConfigKit v1.2.0. | -| PromptKit integration | v0.6.0 | v0.7.0 | v0.7.0 | ConfigKit v1.2.0 and PromptKit v0.21.0. | +| ConfigKit integration | v0.6.0 | v0.8.0 | — | ConfigKit v1.2.0. | +| PromptKit integration | v0.6.0 | v0.8.0 | v0.7.0 | ConfigKit v1.2.0 and PromptKit v0.21.0. | | Earlier matched integration set | v0.3.0 | v0.2.0 | v0.2.0 | ConfigKit v0.8.0 and PromptKit v0.16.0, using their earlier import paths. | Install the published core with: @@ -30,15 +30,12 @@ Install the published core with: go get go.maximumdirect.net/commandkit@v0.6.0 ``` -Select either integration with `go get go.maximumdirect.net/ckconfig@v0.7.0` -or `go get go.maximumdirect.net/ckprompt@v0.7.0`. The published integrations -select core v0.6.0. ckprompt v0.7.0 selects ckconfig v0.7.0, which includes -`AdaptDiagnostics`. -Those published versions build independently against their released dependencies. -The current checkout of ckprompt uses an API added to local ckconfig after -v0.7.0, so it requires the aligned workspace until ckconfig v0.8.0 is published -and ckprompt updates its dependency. See the -[release handoff](../roadmap/future.md#configuration-outcome-release-handoff). +Select either integration with `go get go.maximumdirect.net/ckconfig@v0.8.0` +or `go get go.maximumdirect.net/ckprompt@v0.8.0`. The published integrations +select core v0.6.0. ckprompt v0.8.0 selects ckconfig v0.8.0, which includes +`AdaptDiagnostics` and `ClassifyConfigurationError`. Both integrations build +independently against their released dependencies. An aligned workspace can +exercise the local sources together during development. Published ckconfig v0.3.0 also uses ConfigKit v1.1.0 and does not compose with ckprompt v0.2.0's earlier ConfigKit dependency. diff --git a/docs/development.md b/docs/development.md index 92e6ca7..4cd6f73 100644 --- a/docs/development.md +++ b/docs/development.md @@ -119,14 +119,11 @@ If a workspace already exists, ensure it includes these three modules. Preserve the ignored `go.work` and `go.work.sum`; do not commit them. Use `GOWORK=off GOTOOLCHAIN=local` for dependency preparation and independent module suites. Both integrations select released core v0.6.0; -ckprompt also selects released ckconfig v0.7.0. The current ckprompt source uses -the new classifier in local ckconfig, so its independent build is pending -publication of ckconfig v0.8.0 and a ckprompt dependency update. The aligned -workspace exercises the local sources together; ckconfig remains independently -buildable against its published dependencies. See the -[release handoff](roadmap/future.md#configuration-outcome-release-handoff). -Run `GOWORK=off GOTOOLCHAIN=local go test ./...` separately for core and -ckconfig, and for ckprompt after its published dependency is updated. From the +ckprompt also selects released ckconfig v0.8.0. Both integrations support +independent builds against their published dependencies. The aligned workspace +exercises the local sources together. +Run `GOWORK=off GOTOOLCHAIN=local go test ./...` separately from each module +directory. From the repository root, a workspace containing all three modules can also run: ```sh diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index feac7ba..e1cc653 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -1,6 +1,6 @@ # Future work -Status: release coordination, optional shell validation, and future capability proposals. +Status — optional shell validation and future capability proposals. No delivery dates are selected here. ## Purpose and authority @@ -25,29 +25,14 @@ and remediation records remain available at the [Earlier retired records](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/6bc37e7ba64ca0920b4d0cc77039a18d4006b24e/docs/roadmap) also remain in Git history. Completed records are not assignments to restart work. +The completed configuration-outcome implementation and remediation are preserved +in the [v0.8.0 retirement snapshot](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/6c7d7c90de4deea8be38b2a447b5c957d748d1b0/docs/roadmap). + Accepted [ADRs](../adr/) and the [architecture policy](../policy/architecture.md) govern any future implementation. The [CLI reference](../cli.md), public GoDoc, and [consumer guide](../consumers/guide.md) own implemented behavior. Retaining an idea here does not select its syntax, API, priority, or delivery date. -## Configuration outcome release handoff - -The current ckprompt source requires the classifier in local ckconfig, while -its published dependency remains ckconfig v0.7.0. The aligned workspace -validates the source combination; ckprompt independent validation remains -pending until the dependency is published and updated. Follow the -[dependency-first release procedure](../release.md#scope-and-release-order): - -1. When publication is authorized, publish ckconfig v0.8.0 from its independently - validated candidate. -2. Prepare ckprompt against the actual published ckconfig v0.8.0 using `go get` - and `go mod download` with `GOWORK=off GOTOOLCHAIN=local`, retaining the real - checksums. Complete its v0.8.0 release note, compatibility guidance, and - candidate preparation under the existing rules for its other dependencies. -3. Independently validate and publish ckprompt v0.8.0 under the same - authorization and procedure. Track hosted release delivery separately under - the runbook. - ## Optional verification ### Optional shell completion validation diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md deleted file mode 100644 index f4344cf..0000000 --- a/docs/roadmap/implementation.md +++ /dev/null @@ -1,373 +0,0 @@ -# Invalid configuration outcome implementation - -Status — complete. Release coordination remains in the -[future work handoff](future.md#configuration-outcome-release-handoff). - -## Sprint scope and baseline - -Implement the accepted [feature roadmap](invalid-configuration-outcomes.md). -Its target and accepted decisions govern the work. This plan supplies the -specific API, diagnostic mapping, integration edits, and validation. - -The planning baseline is commit `a53bf9f916ffb44d816f3929fb5297a68ad118c0`. -Production sources still match the reviewed v0.7.0 integration baseline. Read -[development guidance](../development.md), the [agent policy](../policy/agents.md), -and the applicable architecture, testing, documentation, and release policies. - -Execute Stage 1 through Stage 5 in order as one sprint. Intermediate stages may -leave dependent work or test expectation updates for a later stage. Mark each -stage complete with its actual verification evidence and commit completed units -under the repository's local commit policy. Continue through the remaining -stages using the decisions in this plan. - -Use Go 1.27.0 and the ignored workspace containing core, ckconfig, and ckprompt. -The new shared API will first exist in local ckconfig. ckprompt currently selects -published ckconfig v0.7.0, which lacks it. The aligned workspace supplies local -ckconfig throughout this sprint. Published dependency alignment is release -coordination work described in Stage 5. Record that pending state explicitly -when reporting validation. - -## Stage 1 — Implement the shared classifier - -Status — complete. Added the shared classifier and focused tests for the -selected diagnostic codes, fallback evidence, wrappers, joins, cancellation, -and real ConfigKit loading errors. Verified with Go 1.27.0 using -`GOTOOLCHAIN=local GOPROXY=off go test ./integrations/ckconfig -run 'TestConfigurationDiagnosticClassification|TestClassifyConfigurationError' -count=1` -in the aligned workspace (with a temporary writable Go build cache). - -Add `integrations/ckconfig/errors.go` with the following exported function and -GoDoc describing its CLI classification purpose, accepted evidence, fallback, -nil behavior, and precedence. - -```go -func ClassifyConfigurationError(err error) commandkit.OutcomeKind -``` - -The function returns an outcome kind and reads error evidence. Handlers own -outcome construction, explanations, causes, and invocation context. - -### Exact behavior - -1. A nil error returns `commandkit.OutcomeSuccess`. -2. A nonnil error matching `context.Canceled` or `context.DeadlineExceeded` - through `errors.Is` returns `commandkit.OutcomeOperational`. -3. Recognize a nonnil `*configkit.LoadError`, including ordinary wrapping, and - inspect its complete `Diagnostics()` result. Ignore warning diagnostics. - Require at least one error-severity diagnostic and classify as usage only - when every error diagnostic has a usage code in the table below. An unknown - severity, an operational or unknown error code, or insufficient error - evidence selects operational. -4. Traverse ordinary `Unwrap() error` wrappers and `Unwrap() []error` branches. - A join selects usage only when every nonnil failing branch selects usage. - An operational branch wins in either ordering. A nonnil error exposing an - empty child list is an unclassified failure and selects operational. -5. Other nonnil errors select `commandkit.OutcomeOperational`. This includes an - empty or typed-nil `*configkit.LoadError`, opaque application errors, and - native PromptKit errors carrying their existing domain classifications. - -Use the public ConfigKit constants in an explicit switch. The following table is -the complete usage-code list for the selected ConfigKit v1.2.0 baseline. All -error codes outside it select operational. - -| Evidence | ConfigKit constants selecting usage | -| --- | --- | -| YAML content and fixed parser input bounds | `CodeYAMLInvalid`, `CodeYAMLEmpty`, `CodeYAMLMultipleDocuments`, `CodeYAMLRootType`, `CodeYAMLDuplicateKey`, `CodeYAMLTag`, `CodeYAMLAnchor`, `CodeYAMLAlias`, `CodeYAMLMergeKey`, `CodeYAMLScalar`, `CodeYAMLDepthLimit`, `CodeYAMLNodeLimit` | -| Typed decoding | `CodeDecodeType`, `CodeDecodeNull`, `CodeDecodeRange`, `CodeDecodeDuration`, `CodeDecodeText`, `CodeDecodeUnknownField`, `CodeDecodeArrayLength` | -| Excessive individual source input | `CodeSourceLimitExceeded` | -| Unsupported import directives and invalid graph relationships | `CodeImportDisabled`, `CodeImportCycle`, `CodeImportRepeated`, `CodeImportVersion` | -| Sequence declarations and peer composition | `CodeSequenceInvalid`, `CodeSequenceConflict`, `CodeComposeInvalid`, `CodeComposeConflict` | -| Protected version contributions | `CodeUnderlayVersion`, `CodeOverlayVersion` | -| Invalid overlay relationships and directives | `CodeOverlayRepeated`, `CodeOverlayDirective` | -| Version and explicit semantic rejection | `CodeVersionType`, `CodeVersionError`, `CodeResolveError`, `CodeValidateError` | -| Inheritance declarations and references | `CodeInheritanceInvalid`, `CodeInheritanceMissing`, `CodeInheritanceCycle`, `CodeInheritanceVersion` | -| Invalid override paths and conflicting assignments | `CodeOverrideInvalidPath`, `CodeOverrideDuplicate`, `CodeOverrideOverlap`, `CodeOverrideDirective`, `CodeOverrideVersion` | -| Excessive override input | `CodeOverrideLimitExceeded` | -| Invalid or absent typed secret references | `CodeSecretRequired`, `CodeSecretInvalidName` | - -The mapping follows the public code meanings and ConfigKit v1.2.0's -`docs/config.md` sections on input limits, YAML documents, composition, -inheritance, overrides, secret references, and safe failures. Review the pinned -module source and documentation in the Go module cache when implementing it. - -The fallback intentionally includes these reviewed cases. - -- Acquisition failures, including missing or unreadable sources and imports, - permission failures, non-regular sources, and unavailable overlays. -- `CodeImportInvalid` and `CodeOverlayInvalid`, which cover both invalid content - and acquisition/context failures. Their codes alone provide ambiguous evidence. -- `CodeImportOutsideRoot` and `CodeOverlayOutsideRoot`, where containment can - reflect source resolution and filesystem conditions. -- `CodeImportLimitExceeded` and `CodeOverlayLimitExceeded`, whose acquisition - budgets can encompass source graph and filesystem traversal work. -- Schema and options errors, source-description and reused-reader errors, - `CodeHistoryLimitExceeded`, and callback failures or invalid callback actions. -- `CodeOverrideInvalidLabel` and `CodeOverrideInvalidValue`, whose meanings also - cover malformed application-created records and unsupported Go values. -- `CodeSecretUnset` and `CodeSecretEmpty`, which describe credential acquisition - from the runtime environment. Secrets-directory bootstrap failures also follow - the operational fallback. - -The fixed source/parser bounds and override input budgets in the usage list -identify excessive supplied input. The acquisition and retained-evidence budgets -listed above retain operational classification under the accepted fallback. -These choices classify returned evidence and leave upstream limits and -validation rules with ConfigKit. - -Implement straightforward error-tree traversal. Recognize the current typed -loading error before following its children. Inspect join branches separately -so an `errors.As` search over a whole join cannot hide later failures. Perform -the cancellation `errors.Is` checks once at the public entry point, then walk -the tree and inspect each encountered loading error's diagnostics once. A small -private diagnostics classifier and recursive walker are appropriate here. - -Add focused tests in `integrations/ckconfig/errors_test.go`. - -- Exercise the mapping through the private diagnostics classifier using ordinary - diagnostic values, including warnings, mixed evidence, unknown codes, and - missing error evidence. Include each selected usage constant and representative - operational families. -- Exercise the exported function with real public loading-error fixtures, - wrappers, all-input joins, mixed joins in both orders, nested joins, - cancellation, deadlines, nil, and empty loading errors. Assert classification - and preservation of the original error's supported identity. - -Generate representative fixtures through public ConfigKit loading APIs. Assertions -own CommandKit's mapping and traversal. Upstream domain validation remains owned -by ConfigKit under the [testing policy](../policy/testing.md#upstream-integration-testing-ownership). - -Run the focused classifier tests. Stage 5 owns the final independent module suite. - -## Stage 2 — Apply classification and cancellation precedence in ckconfig - -Status — complete. The configuration failure boundary now incorporates -invocation cancellation and selects the shared classification. Tests cover all -five operations, both comparison sides, filtered validation, report delivery, -operational failures, and cancellation with retained causes. Updated the native -override and simple-example expectations for their input diagnostic codes. -Verified with Go 1.27.0: `GOTOOLCHAIN=local GOPROXY=off go test -./integrations/ckconfig/...` in the aligned workspace, using a temporary Go -build cache; both the integration and simple example passed. - -Update `configFailure` in `integrations/ckconfig/operations.go` to receive -`context.Context` as its first argument. Update its callers in `operations.go`, -`show.go`, `sources.go`, `explain.go`, `validate.go`, and `diff.go` to pass the -invocation context. Add context to `configAcquisitionFailure` and pass it through -from `runConfigShow`. - -At this failure boundary, sample `ctx.Err()` when context is available. If it is -nonnull, use it as the cause when the operation cause is nil, or join it with the -operation cause when `errors.Is` does not already identify it. Preserve the -original cause directly when additional cancellation evidence is absent. - -Call `ClassifyConfigurationError` with that combined cause. Construct -`commandkit.Usage` for usage classification and `commandkit.Failure` otherwise. -Keep the latter default for intentionally reported failures with a nil cause. -Retain the existing explanation selection, details, and cause attachment. - -Apply the result to all acquisition errors reaching the five configuration -operations. Classification uses the returned error's complete evidence. Detailed -validation filters and projected `View.Findings` are report inputs. Successful -callbacks continue through their existing result flow. - -Follow the existing operation-specific reporting lifecycle. Sources can emit -their inventory after failed loading, validation can emit its reached-scope -report, and comparisons retain side-specific diagnostics. The existing -`config diff --check` domain outcome and core presentation rules apply. - -Extend the existing command and native-adapter tests to cover these outcomes. - -1. A wrapped malformed-YAML loading error returned through `FromConfigKit` - produces usage status `2` for show, sources, validate, explain discovery, and - diff. Assert the actionable diagnostic, typed cause, and appropriate report - evidence for each operation. -2. Diff handles a failure on either loading side and preserves the acquired - diagnostic context. A detailed-validation filter hiding an error has the same - classification as the unfiltered failure. -3. Ordinary acquisition failures and a representative operational loading error - produce status `1`. -4. Already-canceled invocations produce status `1`, retain cancellation identity, - and leave stdout empty before acquisition. A callback that cancels context - and returns a loading error retains both causes and selects status `1`. -5. An output failure while delivering a source or validation report after an - input failure follows core's operational presentation-failure rule while - retaining the configuration cause. - -Use existing coverage in `detailed_validation_test.go`, `diff_execution_test.go`, -the source/report tests, and `contracts_adapter_test.go` where suitable. Update -the invalid-fixture expectations in `examples/simple/main_test.go`, which -currently assert operational outcomes for native loading errors. Check related -expectations against their actual fixture codes before changing them. - -Run the changed command tests and the affected simple-example tests. Stage 5 -owns the final independent ckconfig suite. - -## Stage 3 — Apply the shared function to PromptKit inspection and requests - -Status — complete. PromptKit failure handling now samples invocation -cancellation and applies the shared classifier, including the smoke handler -call sites needed for compilation. Tests cover every catalog, named inspection, -requirements, validation, preparation, native loader and builder failures, -and cancellation with preserved causes. With Go 1.27.0, the aligned workspace -passed `GOTOOLCHAIN=local GOPROXY=off go test ./integrations/ckprompt -skip -'^TestPublicConfigDiffUsesPromptKitPairAndPreparedInputs$'`; that composition -test and the composed example retain expectations for Stage 4. A temporary Go -build cache was used. - -Update `definitionFailure` in `integrations/ckprompt/command.go` to receive the -invocation context and combine observed cancellation with the operation cause -using the same handler-level approach as Stage 2. Call -`ckconfig.ClassifyConfigurationError` and choose Usage or Failure while retaining -the existing explanation and cause. A nil cause for a missing provider result -still yields an operational failure. - -Update all callers, including the catalog fallback in `newCatalogListCommand`, -the handlers in `command.go`, `validation_command.go`, `preparation.go`, and the -smoke handlers that Stage 4 will verify. - -Cover every installed catalog and named prompt/profile/backend inspection, -requirements discovery, concrete validation, and prepared-request preview. -Configuration loading errors may come from engine loaders or request builders. -The returned ConfigKit evidence selects the classification in each path. -Native lookup, preparation, validation, and provider errors with insufficient -configuration evidence take the operational fallback. Existing preflight and -application input-check contracts continue to govern their own failures. - -Retain the original upstream error and diagnostic adaptation in `adapters.go`. -Use the newly context-aware failure boundary to observe cancellation when a -callback returns an error before the handler's later success checkpoint. - -Extend tests around `command_test.go`, `requirements_command_test.go`, -`validation_command_test.go`, and `preparation_test.go`. - -- Supply a shared real ConfigKit loading-error fixture through each relevant - suite callback and representative native loader/builder paths. Assert usage - status `2`, diagnostics, and `errors.As`/`errors.Is` preservation. -- Cover an ordinary PromptKit lookup error, an ordinary loader or builder - failure, and missing-result handling as operational outcomes. -- Cover pre-canceled input and cancellation occurring with a returned loading - error, checking status `1` and retained cancellation/loading identity. - -Use table-driven cases for handlers with equivalent failure behavior. Reuse -existing tests for forwarding and lifecycle semantics. Verify the affected -packages using the aligned workspace. - -## Stage 4 — Verify smoke aggregation and configuration composition - -Status — complete. Verified individual and aggregate smoke outcomes, mixed -failures and cancellation with retained reports and causes, and all five -operations through the composed PromptKit configuration scope, including the -right comparison side and pre-canceled invocations. Updated the existing -comparison and composed-example expectations for input diagnostics. With Go -1.27.0, `GOTOOLCHAIN=local GOPROXY=off go test ./integrations/ckprompt/...` -passed in the aligned workspace using a temporary Go build cache. - -In `integrations/ckprompt/smoke_command.go`, complete the context argument updates -and apply the shared classification to individual failures and the final joined -aggregate cause. Follow the existing sequential four-kind execution, cancellation -stop behavior, report delivery, explanation combination, and acquired diagnostic -flow. The classifier supplies the new aggregate outcome. - -Extend `smoke_outcome_test.go`, `smoke_aggregate_test.go`, and related command -tests to verify a single input failure, an all-input aggregate, a mixed -input/operational aggregate, and cancellation joined with an input failure. -Assert the available reports and all supplied error identities. Existing -report-with-error behavior remains part of those assertions. - -Exercise `ConfigScope` through the public ckconfig family in ckprompt tests. -Use a loader returning a wrapped malformed-YAML loading error and cover show, -sources, validate, explain discovery, and diff, including the right comparison -side. This establishes that composed PromptKit configuration commands use the -shared ckconfig policy. Check the accompanying source and validation report -evidence and the already-canceled behavior. - -Update affected assertions in `examples/composed/main_test.go` against the -fixture's actual evidence. Add a focused fixture only where it establishes a -CommandKit-specific composition or outcome boundary. Reuse the existing example -and adapter tests for ordinary upstream capability forwarding. - -Run the focused smoke/composition tests. Stage 5 owns the final aligned-workspace -ckprompt suite. Review native lookup and operational error tests for accidental -classification broadening. - -## Stage 5 — Update documentation, validate, and record release coordination - -Status — complete. Updated the CLI and consumer contracts, development -guidance, ckconfig v0.8.0 release note, and dependency-first release handoff. -With Go 1.27.0 and a temporary writable Go build cache, the independent ckconfig -suite passed with `GOWORK=off GOTOOLCHAIN=local GOPROXY=off go test --mod=readonly ./...`. In the aligned workspace, the three prescribed -`GOTOOLCHAIN=local GOPROXY=off go test -mod=readonly` commands passed for -`./...`, `./integrations/ckconfig/...`, and `./integrations/ckprompt/...`. -Reviewed the diff, local Markdown links and fragments, and whitespace. The -independent ckprompt build remains pending publication and dependency alignment. - -Update the implemented CLI contract in `docs/cli.md`, including the outcome -table and affected load-failure wording in configuration comparison, inspection, -requirements discovery, concrete validation, catalogs, preparation, and smoke -testing. Document input classification, operational fallback, mixed-error -precedence, and the existing output-failure rules. Add the new exported API's -GoDoc and concise consumer guidance linked to it. - -Prepare `integrations/ckconfig/docs/releases/v0.8.0.md` explaining the status -contract change and shared classification API, using the module's existing -release-note conventions and immutable licensing footer. Record the planned -ckprompt v0.8.0 note and published-dependency update as release follow-up under -`docs/roadmap/future.md`. The ckprompt candidate is prepared after ckconfig -publication under the [release procedure](../release.md#scope-and-release-order). - -### Final sprint verification - -Format changed Go files. Run the commands below from the indicated module -directories, with Go 1.27.0 on PATH. The default suites are deterministic and -offline once selected dependencies are present in the module cache. - -From `integrations/ckconfig`, verify its published dependencies independently. - -```sh -GOWORK=off GOTOOLCHAIN=local GOPROXY=off go test -mod=readonly ./... -``` - -From the repository root, verify all three local modules together. - -```sh -GOTOOLCHAIN=local GOPROXY=off go test -mod=readonly ./... -GOTOOLCHAIN=local GOPROXY=off go test -mod=readonly ./integrations/ckconfig/... -GOTOOLCHAIN=local GOPROXY=off go test -mod=readonly ./integrations/ckprompt/... -``` - -The integration commands include their maintained example packages. Review -the final diff, Markdown links/fragments, and `git diff --check`. Confirm that -the shared code mapping, error trees, cancellation, reporting, both scope -adapters, and command families have the planned regression evidence. Report -actual checks and any remaining failures. - -ckprompt's independent published-dependency build is pending the ckconfig release -because its current v0.7.0 selection lacks the new function. Keep that limitation -visible in the development/consumer guidance and release handoff. Retain the -existing published requirements through the implementation sprint. The ignored -aligned workspace is the local build setup for the new source combination. - -### Release handoff - -Record these follow-up actions together in `future.md` so they survive later -retirement of the implementation documents. - -1. Publish ckconfig v0.8.0 from its independently validated candidate using the - documented release process when publication is authorized. -2. Prepare ckprompt with actual published ckconfig v0.8.0 using `go get` and - `go mod download` with `GOWORK=off GOTOOLCHAIN=local`. Retain real checksums, - then finish its v0.8.0 release note, consumer compatibility guidance, and - release preparation. The other dependency selections follow their existing - release preparation rules. -3. Validate ckprompt independently against its updated published dependencies - through its release candidate suite and publish ckprompt v0.8.0 under the - same authorization and procedure. Track hosted release delivery under the - runbook's separate delivery process. - -These actions follow the existing dependency-first release procedure. The sprint -can complete with verified local behavior and explicit pending release alignment. -The release handoff identifies the remaining independent-build evidence. - -Mark each completed stage with its implementation and verification evidence. -Commit the completed sprint work under the repository policy and report its -commits, checks, and pending release coordination. diff --git a/docs/roadmap/invalid-configuration-outcomes.md b/docs/roadmap/invalid-configuration-outcomes.md deleted file mode 100644 index 5ecd4fc..0000000 --- a/docs/roadmap/invalid-configuration-outcomes.md +++ /dev/null @@ -1,142 +0,0 @@ -# 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. diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md deleted file mode 100644 index 5ed4807..0000000 --- a/docs/roadmap/remediation.md +++ /dev/null @@ -1,130 +0,0 @@ -# Configuration outcome review remediation - -Status — R1 and R2 complete. 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 — complete. Affects Stage 5 documentation consistency. - -Completed by marking the feature as implemented with review remediation complete, -linking the release handoff, and labeling the old status behavior and failure -helpers as historical baseline evidence. Verified the document against the -implemented classifier, current CLI contract, and pending release coordination. -Local Markdown links/fragments and whitespace checks passed. - -At review time, the [feature roadmap](invalid-configuration-outcomes.md) said -"pending implementation" at its opening. Its baseline section also described -the current CLI contract as assigning loading failures status `1` and presented -the status change as proposed. Meanwhile, the implementation plan recorded all -stages complete, and the -[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.