Record optional detailed configuration diff report

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)

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
+For optional detailed comparison, project the native `Difference` records
-and their presence/redaction fields together, including `HiddenChanged` when
+already returned by `Scope.Compare`; retain the existing concise report by
-the safe values look equal. Native sequence comparisons remain atomic; this
+default. Keep snapshots and their presence/redaction fields together, including
-work does not add element-level resource matching or a reloadable patch format.
+`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
+- [ ] Default `config diff` retains its concise additions/changes/deletions
-  evidence, including empty comparisons and sequence-level changes.
+  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
+**Agreed:** retain the existing concise additions/changes/deletions report as
-default. Emit a YAML record sequence carrying native paths, snapshots, and
+the default for `config diff`, and add optional `--details` for investigating
-hidden-change fields, preferably within a scope-labeled envelope. This supplies
+changes. The default serves human operators who need a quick overview; retaining
-the missing evidence without changing existing reduced-report consumers.
+it is a presentation choice, not a compatibility constraint.
 
-**Alternative:** replace the reduced form with the detailed report in a new
+The detailed mode should help an operator compare old and new values,
-minor module release. One canonical report is simpler to maintain and avoids
+distinguish absence from explicit null, and understand concealed changes even
-selection flags, but requires migration of published CLI consumers. The release
+when the displayed safe snapshots look equal. Present native paths, left/right
-policy permits a deliberate pre-v1 minor compatibility change; the benefit must
+snapshots, presence, redaction, and hidden-change evidence in readable YAML.
-justify that disruption.
+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