Set initial report designs and lightweight YAML implementation guidance

docs/roadmap/future.md

@@ -55,7 +55,8 @@ These accepted plans do not change the currently implemented 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.
+the accepted initial layout is recorded there for implementation and later beta
+feedback.
 
 ### Configuration inspection extensions
 
@@ -67,14 +68,18 @@ structured diagnostics belong to `config validate`; the suite retains six
 subcommands. The roadmap records the agreed explanation modes and help behavior;
 [OD-6](promptkit-v0.19.0.md#od-6-failure-evidence-and-structured-diagnostic-delivery)
 selects optional validation details, a concise default, and available evidence
-on failure. OD-8 selects focused display, source selection, and report filters;
+on failure. OD-8 selects focused display, source selection, and report filters.
-report shapes and exact filter grammar remain open.
+Initial report formats and filter spellings are selected in the roadmap;
+remaining layout details will be evaluated through implementation and beta use.
 It also includes focused effective display,
 source-ID selection, metadata/diagnostic filters, independent comparison
 selectors, and assertion mode. The original four shared proposals had ConfigKit
 adoption identifiers OD-3 through OD-6; the new roadmap has its own decision numbering. Implementation
 belongs in `ckconfig`, with PromptKit exposing native evidence through its
-configuration scope. CLI syntax and report contracts remain subject to review.
+configuration scope. The
+[initial report implementation approach](promptkit-v0.19.0.md#initial-report-implementation-approach)
+favors direct Go-to-YAML serialization, thin projections, and shared output
+helpers. Further presentation refinements should follow practical feedback.
 
 Transient acquisition overrides are included as an opt-in loader capability in
 [roadmap OD-11](promptkit-v0.19.0.md#od-11-transient-configuration-overrides).

docs/roadmap/promptkit-v0.19.0.md

@@ -2,7 +2,9 @@
 
 Status: proposed roadmap for review. Scope is agreed in principle; implementation
 has not started. Command spellings, report designs, and API changes below are
-recommendations except where explicitly recorded as agreed below.
+recommendations except where explicitly recorded as agreed below. Accepted
+report formats are an initial implementation target; practical beta feedback
+will guide later refinements rather than requiring exhaustive layout design now.
 
 ## Purpose and ownership
 
@@ -27,7 +29,7 @@ The completed v0.18.0 adoption is not reopened.
 
 | Component | Current baseline | Target |
 | --- | --- | --- |
-| Core | `go.maximumdirect.net/commandkit`; Go 1.26.0 minimum | No core change currently identified. |
+| Core | `go.maximumdirect.net/commandkit`; Go 1.26.0 minimum | No core change needed for flag collections or scoped aliases; assess a small shared YAML output helper during implementation. |
 | `ckconfig` | ConfigKit v1.1.0; Go 1.27.0; core v0.3.0 | Shared CLI inspection extensions and a new appropriate module release. |
 | `ckprompt` | PromptKit v0.18.0; ConfigKit v1.1.0; ckconfig/core v0.3.0; Go 1.27.0 | PromptKit v0.19.0 and the ckconfig version delivering the shared work. |
 | Candidate | [ckprompt v0.3.0](../../integrations/ckprompt/docs/releases/v0.3.0.md), recorded as unpublished | Update the unpublished candidate after checking its status during implementation. |
@@ -112,8 +114,9 @@ The configuration suite retains six subcommands: `scopes`, `validate`, `show`,
 structured diagnostics belong within `config validate`. This command placement
 is agreed. OD-4 selects `--list` and `--path` as the explanation modes, with
 help on a bare invocation. OD-6 selects `config validate --details` for detailed
-diagnostics while retaining concise validation by default. Report shapes and
+diagnostics while retaining concise validation by default. Initial report
-filter spellings remain proposals under OD-4, OD-6, and OD-8. No separate path inventory
+presentation and filter spellings are selected under OD-4, OD-6, and OD-8; exact
+Go projections can be refined during implementation. No separate path inventory
 or diagnostics subcommand is planned.
 
 Transient configuration overrides are included under OD-11 as an opt-in loader
@@ -294,11 +297,52 @@ PromptKit execution override's complete provider-map replacement. Do not reuse
 one grammar implementation in a way that erases that distinction. Source-load
 errors remain errors even if an override would replace the affected value.
 
+## Initial report implementation approach
+
+Use the accepted OD-4 through OD-6 flags and formats as a practical starting
+point. Keep added code, report types, and translations proportionate. Beta
+feedback on actual reports should guide changes; do not delay implementation
+for speculative layout options or build a report framework in anticipation of
+future formats.
+
+The repository already uses `go.yaml.in/yaml/v4` and small Go-value-to-YAML
+writers in core and both integrations. Centralize common encoder configuration
+and reusable output helpers where practical. A small shared writer accepting an
+`io.Writer` and a Go report value is sufficient; exact placement and exported
+API, if needed across module boundaries, are implementation choices. Keep any
+core helper independent of ConfigKit and PromptKit types. A separately versioned
+output module or custom serialization engine is not needed. Account for module
+release/dependency ordering under OD-7 if a shared public core helper is added.
+
+Prefer directly encoding suitable native inspection/report values or a thin Go
+projection with serialization tags. Do not mirror a whole upstream object graph
+just to rename fields or rearrange equivalent data. Reuse small path, snapshot,
+location, and duration projections where they are genuinely needed. Types whose
+intended representation depends on JSON tags or custom JSON serialization cannot
+be assumed to encode identically under YAML; reuse their supported serialization
+or provide a small explicit adapter rather than inventing a reflection framework.
+
+Exceptions serve concrete report semantics: preserving absent/null/false/zero
+and empty collections, expressing paths and durations readably, projecting safe
+snapshot values, and retaining native redaction. Encode report/inspection values,
+not engines, mutable runtime configuration, or request credential storage. Reuse
+native writers where their output already serves the selected report. Keep the
+existing concise diff and validation presentations; the simpler YAML approach
+applies to detailed reports and other suitable projections.
+
+Separate content projection from YAML encoding and from invocation delivery.
+Use the existing Reporter and outcome lifecycle for delivery and failures.
+Share common helpers without forcing text output through a YAML round trip or
+forcing semantically different reports into one schema. Validate representative
+reports and meaningful adaptation boundaries, rather than freezing every
+incidental formatting detail in tests.
+
 ## Work sequence
 
-1. **Resolve the significant CLI choices.** Review the open decisions, record
+1. **Confirm remaining implementation choices.** Use the accepted flags and
-   selections here, and identify affected published reports and flag collisions.
+   report formats as the MVP target. Resolve outstanding acquisition/binding
-   Prepare concrete command/flag/report examples for implementation review.
+   grammar and flag collisions; use concrete examples to review report details
+   during implementation rather than reopening accepted scope.
 2. **Adopt v0.19.0.** Update `integrations/ckprompt/go.mod` and `go.sum`, then
    [module attribution](../../integrations/ckprompt/docs/oss/attribution.md)
    against the released notices and source commit. Update the unpublished
@@ -320,7 +364,8 @@ errors remain errors even if an override would replace the affected value.
    metadata/diagnostic filters using those evidence capabilities. Extend typed
    comparison selection and add the agreed assertion outcome. Implement explicit
    override acquisition and comparison-side wiring under OD-11 as a separate
-   reviewable unit. Keep boundary coverage with each change.
+   reviewable unit. Reuse and centralize output helpers under the initial report
+   implementation approach. Keep boundary coverage with each change.
 5. **Update operator and consumer documentation.** The CLI reference owns
    syntax, report schemas, availability, and outcomes; GoDoc owns callback and
    value contracts. Extend maintained simple/composed examples to demonstrate
@@ -386,6 +431,10 @@ Default tests remain offline and independent of real credentials.
 - [ ] Bare `config explain` displays help successfully, presenting `--list` and
   `--path` as the two alternatives. Selecting both modes is a usage error;
   explicitly supplied `--path ""` selects root explanation rather than help.
+- [ ] Discovery uses text by default with YAML available, compact path/presence/
+  explicitness fields, and the selected `--historical`, `--under`, and
+  `--explicit` behavior. Historical-only paths and unavailable discovery are not
+  misreported as current implicit values or an empty configuration.
 - [ ] Metadata discovery through `config explain` distinguishes effective and
   historical paths, retains available history on absent lookup, and projects
   native field/change records.
@@ -394,6 +443,8 @@ Default tests remain offline and independent of real credentials.
   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.
+  Detailed YAML uses one before/after entry per path and an explicit empty list
+  when there are no differences.
 - [ ] Focused display preserves native snapshot content and distinguishes
   missing/historical-only paths from explicit null. Whole-document display
   retains its current contract. Focused display uses one scope and native YAML
@@ -414,7 +465,10 @@ Default tests remain offline and independent of real credentials.
   selected comparison-side behavior, native errors, and returned provenance
   preserved. No tests independently re-establish ConfigKit override semantics.
 - [ ] Default validation remains concise; `--details` selects the additional
-  diagnostic report. Selecting YAML alone does not enable detailed mode.
+  diagnostic report, with text by default and optional YAML. Selecting YAML
+  alone does not enable detailed mode. Severity/code filters, evidence
+  availability, no-match presentation, and known duplicate-warning handling
+  preserve the underlying validation outcome.
 - [ ] `config sources` and `config validate --details` report
   available evidence with an acquisition error;
   the original failure, unavailable-versus-empty evidence, cancellation, and
@@ -425,6 +479,9 @@ Default tests remain offline and independent of real credentials.
 - [ ] Maintained consumer examples demonstrate the selected CLI tasks and the
   configuration failure workflow with deterministic local evidence, including
   collection reuse by an application-owned command.
+- [ ] Suitable reports use direct Go-value serialization or thin projections,
+  sharing YAML and common output helpers where practical. Necessary adapters
+  preserve native meaning without a generic report translation framework.
 - [ ] Canonical documentation, module release notes, and roadmap links agree
   with the implemented boundary. Open decisions are resolved or deliberately
   superseded before the corresponding behavior is claimed complete.
@@ -659,13 +716,28 @@ the root explanation, not help. This deliberately replaces the current
 missing-path usage error; automatic discovery on a bare invocation is not
 selected.
 
-**Remaining presentation recommendations:** list effective paths by default,
+**Agreed initial presentation:** use a compact text discovery report by default,
-offer optional historical selection and subtree/explicitness filters, and
+with YAML available through `--format yaml`, and one scope at a time. List
-include available field metadata in detailed explanation. Use the current
+current effective paths by default; `--historical` adds historical-only paths
-single-scope model. A compact text discovery report with YAML available for
+rather than selecting only removed paths. Show path, current/historical-only
-scripts is recommended. Define report fields, historical/filter spellings,
+presence, and available explicitness. Do not equate non-explicit values with
-mode-specific option combinations, and unavailable metadata handling before
+application defaults or historical-only metadata with explicitness false.
-implementation; these details remain open.
+
+Use `--under POINTER` to narrow listing to a subtree and
+`--explicit=true|false` to select current explicitness. Omitting explicitness
+filtering includes both states and, when requested, historical-only entries;
+historical-only entries do not match either current explicitness value. Apply
+subtree filtering to parsed paths, not textual prefixes. These filters and
+`--historical` belong to listing mode; `--path` continues to select detailed
+explanation, including its available metadata and history.
+
+Keep values and change history out of the compact listing. Include useful field
+metadata in detailed explanation without repeating existing evidence. If a
+provider cannot supply discovery metadata, report that capability as unavailable
+rather than presenting an empty configuration; its existing path-specific
+explanation remains usable. These are sufficient starting choices for the MVP;
+exact field layout and mode-specific error wording can be decided in code and
+reviewed with concrete examples.
 
 ### OD-5: Detailed comparison selection and shape
 
@@ -678,17 +750,29 @@ 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
+**Agreed initial layout:** one entry per changed path in a scope-labeled YAML
-presentation recommendation; exact field names and layout remain open.
+report, with before/after snapshots rather than expanded versions of the three
+summary categories. Display snapshot values as YAML values, preserving explicit
+presence so missing and null remain distinct. Show redaction and concealed-change
+annotations where relevant; omission of an optional annotation has a defined
+meaning and never relies on recognizing a marker-looking string. Prefer ordinary
+Go fields and serialization tags to custom omission logic. An empty comparison
+has an explicit empty difference list. YAML is the only initial detailed format.
+
+Keep the projection close to native report values, using the
+[shared reporting approach](#initial-report-implementation-approach) rather than
+extensive translation for cosmetic layout. Exact field names are implementation
+choices for the initial release and can evolve with beta feedback.
 
 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.
+callback, additional load, or comparison algorithm is required. A shared YAML
-A side-by-side terminal display is not part of this adoption. Comparison exit
+output helper may be used, but detailed comparison needs no domain-specific core
-status remains a separate choice under OD-10.
+API. A side-by-side terminal display is not part of this adoption. Comparison
+exit status follows OD-10.
 
 ### OD-6: Failure evidence and structured diagnostic delivery
 
@@ -716,19 +800,31 @@ error. Unlike detailed comparison, the existing adapters need to carry additiona
 structured evidence through to reporting. Use current core reporting and outcome
 handling; no generic cross-family diagnostics framework is required.
 
-**Remaining presentation recommendations:** provide readable structured YAML,
+**Agreed initial presentation:** detailed validation uses text by default, with
-for example `config validate --details --format yaml`, with native codes,
+YAML available through `--format yaml`. Begin text output with scope and outcome,
-severities, paths, locations, and a source legend where available. Exact report
+then show readable findings with their available messages, severities, codes,
-layout and format support remain to be designed. Support severity/code filters
+configuration paths, and source locations. Place useful locations near messages;
-under OD-8 without changing the underlying validation outcome. Distinguish
+YAML may use a source legend shared by multiple findings.
-unavailable evidence from an available empty set of findings.
+
+Use repeatable `--severity` and `--code` filters in detailed mode. Multiple values
+within a filter match any selected value; different filters narrow results
+together. Filtering never changes the validation outcome. Distinguish no native
+findings, no findings matching the filters, and unavailable structured evidence.
+Keep referenced sources needed to interpret selected findings.
+
+Avoid presenting a finding both in the detailed report and as a duplicate
+ordinary warning when the records have a known relationship. Do not deduplicate
+by guessing from message text. Preserve unrelated messages and the terminal
+failure explanation. Keep this coordination within the integration rather than
+introducing a general diagnostics framework.
 
 Structured results use the result stream and ordinary messages use the
-diagnostic stream. Resolve warning duplication and partial-result cancellation
+diagnostic stream. Preserve report-delivery failures separately from the original
-presentation before implementation. Preserve report-delivery failures separately
+operation failure through existing outcome handling. Retain current aggregate
-from the original operation failure through existing outcome handling. Retain
+stopping behavior; detailed output does not promise exhaustive validation across
-current aggregate stopping behavior; detailed output does not promise exhaustive
+all scopes. Partial-evidence and cancellation presentation should use the same
-validation across all scopes.
+simple report values and existing reporting lifecycle, with exact layout refined
+during implementation and practical testing.
 
 ### OD-7: Module release and interim workspace coordination
 
@@ -767,9 +863,10 @@ needed to interpret the selected findings. Apply subtree filtering to parsed
 paths; distinguish unavailable current metadata on historical-only paths from
 an effective value that was not explicitly supplied.
 
-**Remaining design:** exact filter names, values, combination rules, and empty
+**Selected filter grammar:** OD-4 records discovery filters and OD-6 records
-filtered-result presentation. No additional snapshot-wrapper report or aggregate
+diagnostic filters. Exact report field layout and remaining edge-case messages
-path-selected display is selected for this adoption.
+are implementation choices for the MVP. No additional snapshot-wrapper report
+or aggregate path-selected display is selected for this adoption.
 
 ### OD-9: Independent comparison selector bindings