From 491f0b49f4519bb2367ded6275918803a57df3df Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 6 Nov 2026 18:37:32 +0000 Subject: [PATCH] Record optional detailed configuration diff report --- docs/roadmap/future.md | 5 ++++ docs/roadmap/promptkit-v0.19.0.md | 46 +++++++++++++++++++++---------- 2 files changed, 36 insertions(+), 15 deletions(-) diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 3a4d3b8..ec66d25 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -50,6 +50,11 @@ included in the [working roadmap](promptkit-v0.19.0.md#additional-configkit-oper Their binding and outcome contracts remain open under roadmap OD-9 and OD-10; retaining those proposals does not change current comparison behavior. +[Roadmap OD-5](promptkit-v0.19.0.md#od-5-detailed-comparison-selection-and-shape) +selects an optional detailed report while retaining the concise default for +human operators. Both presentations reuse the existing native comparison data; +the detailed layout remains to be designed. + ### Configuration inspection extensions The [PromptKit v0.19.0 roadmap](promptkit-v0.19.0.md#shared-configuration-capabilities) diff --git a/docs/roadmap/promptkit-v0.19.0.md b/docs/roadmap/promptkit-v0.19.0.md index 9cbbabf..632f5a7 100644 --- a/docs/roadmap/promptkit-v0.19.0.md +++ b/docs/roadmap/promptkit-v0.19.0.md @@ -222,10 +222,13 @@ explicitness within explanation discovery instead of reproducing upstream provenance logic. Preserve native list-index paths; do not silently reinterpret them as resource IDs. -For detailed comparison, project native `Difference` records. Keep snapshots -and their presence/redaction fields together, including `HiddenChanged` when -the safe values look equal. Native sequence comparisons remain atomic; this -work does not add element-level resource matching or a reloadable patch format. +For optional detailed comparison, project the native `Difference` records +already returned by `Scope.Compare`; retain the existing concise report by +default. Keep snapshots and their presence/redaction fields together, including +`HiddenChanged` when the safe values look equal. Reuse the same loading and +comparison path for both presentations. Native sequence comparisons remain +atomic; this work does not add element-level resource matching or a reloadable +patch format. For failure investigation, retain `LoadError.Sources()` and `Diagnostics()` as evidence alongside the error. The current adapters and `config sources` failure @@ -382,8 +385,11 @@ Default tests remain offline and independent of real credentials. - [ ] Metadata discovery through `config explain` distinguishes effective and historical paths, retains available history on absent lookup, and projects native field/change records. -- [ ] Detailed diff retains both snapshots and presence/redaction/hidden-change - evidence, including empty comparisons and sequence-level changes. +- [ ] Default `config diff` retains its concise additions/changes/deletions + report. Optional `--details` uses the same comparison records to present both + snapshots and presence/redaction/hidden-change evidence. Cover additions, + deletions, explicit null, empty comparisons, sequence-level changes, and + report-delivery failures without extra configuration loads or comparisons. - [ ] Focused display preserves native snapshot content and distinguishes missing/historical-only paths from explicit null. Whole-document display retains its current contract. @@ -642,16 +648,26 @@ implementation; these details remain open. ### OD-5: Detailed comparison selection and shape -**Recommendation:** add `--details` to `config diff`, retaining the existing -default. Emit a YAML record sequence carrying native paths, snapshots, and -hidden-change fields, preferably within a scope-labeled envelope. This supplies -the missing evidence without changing existing reduced-report consumers. +**Agreed:** retain the existing concise additions/changes/deletions report as +the default for `config diff`, and add optional `--details` for investigating +changes. The default serves human operators who need a quick overview; retaining +it is a presentation choice, not a compatibility constraint. -**Alternative:** replace the reduced form with the detailed report in a new -minor module release. One canonical report is simpler to maintain and avoids -selection flags, but requires migration of published CLI consumers. The release -policy permits a deliberate pre-v1 minor compatibility change; the benefit must -justify that disruption. +The detailed mode should help an operator compare old and new values, +distinguish absence from explicit null, and understand concealed changes even +when the displayed safe snapshots look equal. Present native paths, left/right +snapshots, presence, redaction, and hidden-change evidence in readable YAML. +Select and organize the information for those tasks rather than dumping every +upstream field. A record sequence within a scope-labeled envelope remains a +presentation recommendation; exact field names and layout remain open. + +Keep implementation localized to flag selection and a second report writer, +with focused boundary tests, help, and examples. The existing `Scope.Compare` +contract and both native adapters already return the required difference +records. Reuse that data and existing safe-snapshot decoding; no new comparison +callback, core API, additional load, or comparison algorithm is required. +A side-by-side terminal display is not part of this adoption. Comparison exit +status remains a separate choice under OD-10. ### OD-6: Failure evidence and structured diagnostic delivery