diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index c5640bd..90857ca 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -168,11 +168,13 @@ and universal format availability. Explicit operator selection wins; otherwise core selects text for a supplied template or chooses from the logical report shape. Command-specific format defaults are omitted from the initial API. Plain text, YAML, and JSON land together. The roadmap selects standard Go JSON -serialization conventions for core-serialized report values, with separate core -adaptation for native configuration YAML. Text templates use Go's `text/template` +serialization conventions for core-serialized report values. Core explicitly +converts safe inspection YAML into ordinary report values, preserving data +meaning and redaction without a separate native-YAML preservation path. +Text templates use Go's `text/template` with the original Go report value. Without a template, structured text output -reuses the YAML renderer; template errors never trigger fallback. Native-document -decisions remain there. XML is removed from current consideration. +reuses the YAML renderer; template errors never trigger fallback. Multiple-result +framing remains open there. XML is removed from current consideration. Markdown and other potential formats are not selected for this adoption; new core formats will work with existing commands without per-command adoption. diff --git a/docs/roadmap/promptkit-v0.19.0.md b/docs/roadmap/promptkit-v0.19.0.md index b741aca..1ac4c72 100644 --- a/docs/roadmap/promptkit-v0.19.0.md +++ b/docs/roadmap/promptkit-v0.19.0.md @@ -450,13 +450,31 @@ when the desired operator content differs from that representation. representations. Templated text executes against the original value without requiring a JSON round trip. -**Agreed separate treatment:** native configuration YAML uses explicit core -adaptation with defined cross-format mappings, not blind conversion through the -ordinary JSON path. Preserve native YAML semantics and disclosure rules when -YAML is requested, and avoid silent loss of richer YAML information. The adapter -API, supported mappings, and multiple-document behavior remain part of the -native-document decision below. This is not an exemption from universal formats -or permission for integration-owned formatting pipelines. +**Agreed configuration input conversion:** decode upstream safe inspection YAML +into ordinary Go report values, then use the same shared representation and +renderers as other reports. Core owns the explicit YAML-input conversion helper; +ordinary report strings are never heuristically parsed as YAML. This supersedes +the proposed separate native-YAML preservation path. + +Preserve meaningful data: strings versus numbers and booleans, null versus empty +collections, absent versus present false/zero/null, numeric precision, sequence +order, and upstream redaction. Retain presence and other inspection metadata +where the selected report calls for it. Mapping order, comments, whitespace, +quoting, block/flow style, and exact numeric spelling are not preservation +requirements. Unsupported conversion must remain observable rather than silently +changing meaning. ConfigKit v1.1.0's safe inspection YAML already represents a +restricted, JSON-like value model, making this conversion proportionate. + +Obtain those values from upstream safe inspection output, not application runtime +configuration structs: the latter may lose the captured snapshot, field inclusion, +disclosure rules, or inspection evidence. This is an output conversion, not a +replacement for upstream configuration loading or validation. No lossless YAML +document model or second rendering pipeline is needed. + +When implementation lands, record the deliberate replacement of +[ADR 0007](../adr/0007-native-yaml-reports.md)'s native-writer and mapping-order +requirements in a superseding ADR and update current contracts. Retain the +accepted ADR's decision text as history. Multi-scope framing remains open below. This approach reduces new machinery by reusing standard serialization and centralizing the remaining conversion and rendering work. Exact internal @@ -507,19 +525,18 @@ never enters this no-template path. ### Remaining core reporting decisions -- **Native documents and multiple results.** Define how native safe YAML - snapshots and ordered multi-scope documents enter the shared representation, - and how multiple documents/results appear in JSON and text. Preserve native - YAML meanings and disclosure rules without silently losing data or exempting - commands from universal format support. Keep format translation in core and - domain evidence selection in the integrations. +- **Multiple results and framing.** Decide how multiple scope values/results, + particularly `config show --scope all`, are grouped and identified across + YAML, JSON, and text: separate documents versus an aggregate list or wrapper. + Safe YAML input conversion is settled above; it does not settle aggregation. + Keep format translation in core and domain evidence selection in integrations. Exact public signatures, reusable template preparation and helper functions, flag integration/collision handling, and replacement of existing format plumbing are implementation design tasks. The decisions above do not reopen content selection, JSON conventions for core serialization, original Go values for text templates, no-template text rendering, universal formats, automatic selection, -or joint format delivery. +safe YAML input conversion, or joint format delivery. Report serialization does not settle the separate JSON input-number conversion choices in OD-2 and OD-11. @@ -544,17 +561,17 @@ 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. Core reuses the JSON contract across its serialization paths; migrate YAML-only report tags -or provide a thin projection where necessary. Native configuration documents follow their -explicit adaptation path rather than the ordinary Go-value path. +or provide a thin projection where necessary. Safe configuration YAML enters the +ordinary Go-value path through core's explicit input conversion helper. 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. -Preserve native-document semantics and the concise diff and validation content +Preserve inspection data meaning and the concise diff and validation content selections. Integrations prepare those values and any text templates; core owns -rendering. Native-document adaptation is part of the shared representation -design, not an integration-owned alternative formatting pipeline. +rendering. YAML input conversion feeds that same machinery without preserving +source formatting or adding an integration-owned formatting pipeline. Separate content projection from format rendering and from invocation delivery. Use the existing Reporter and outcome lifecycle for delivery and failures. @@ -569,7 +586,7 @@ incidental formatting detail in tests. 1. **Confirm remaining implementation choices.** Use the accepted flags, report content, and automatic format policy as the MVP target. Resolve the remaining - native-document decisions; specify the public API, reusable template helpers, + multiple-result framing decision; specify the public API, reusable template helpers, and internal conversion design under the agreed JSON representation contract. Resolve outstanding acquisition/binding grammar and flag collisions; use concrete examples to review report details during implementation rather than @@ -627,7 +644,7 @@ CommandKit to retest PromptKit rendering, schema, namespace, or ConfigKit resolution algorithms. Default tests remain offline and independent of real credentials. -- [ ] Remaining native-document decisions are recorded. +- [ ] Multiple-result framing is decided and recorded. Public signatures and shared representation conventions are documented with implementation. - [ ] Core owns universal `--format` options, help, validation, and selection. @@ -667,8 +684,13 @@ Default tests remain offline and independent of real credentials. - [ ] Representative reports retain null/false/zero/empty distinctions and numeric values through conversion, including large integers. Unsupported values and serialization failures remain observable presentation failures. -- [ ] Native YAML follows explicit core adaptation with the selected mappings, - retaining native meaning without silent loss through JSON conversion. +- [ ] Safe inspection YAML is explicitly converted to ordinary Go report values + in core and uses the shared renderers. Preserve types, presence/null/empty + distinctions, numeric precision, sequence order, and redaction. Do not require + mapping order or source formatting, or substitute runtime configuration structs. + Conversion failures are observable; ordinary strings are not parsed as YAML. +- [ ] A superseding ADR records the replacement of native-writer and mapping-order + requirements in ADR 0007; canonical contracts are updated with implementation. - [ ] Core, both integrations, and a maintained application-owned command exercise the public reporting capability. Suitable duplicate selection and encoding code is removed; core has no optional integration dependencies. @@ -737,7 +759,7 @@ Default tests remain offline and independent of real credentials. when there are no differences. - [ ] Focused display preserves native snapshot content and distinguishes missing/historical-only paths from explicit null. Whole-document display - retains native YAML semantics when that format is selected. Focused display + preserves safe inspection values through the shared renderers. Focused display uses one scope and hands off the logical value without a snapshot wrapper or text template; core applies automatic or explicit selection. Absent effective paths and unknown source IDs produce clear operational failures. @@ -1171,8 +1193,9 @@ operator investigating a known part of the configuration. `config show` hands off the selected logical configuration value without a text template. Core selects from its shape: a mapping yields YAML, while a selected -string yields text. Explicit `--format yaml` always requests native effective -YAML, without a snapshot wrapper containing presence/redaction/YAML fields. +string yields text. Explicit `--format yaml` renders the safe effective value as +YAML, without a snapshot wrapper containing presence/redaction/YAML fields or a +promise to preserve upstream formatting or mapping order. All formats render the selected value through the shared representation. Use the existing explanation capability to obtain the native snapshot. An absent effective path or unknown source ID produces a clear operational failure. Explicitly present