From 3b6614605aaeae9cda665e966bc445f8e021c5f4 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 7 Nov 2026 00:41:56 +0000 Subject: [PATCH] Use a scope-keyed mapping for aggregate configuration reports --- docs/roadmap/future.md | 6 ++- docs/roadmap/promptkit-v0.19.0.md | 70 ++++++++++++++++++++++++------- 2 files changed, 58 insertions(+), 18 deletions(-) diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 90857ca..84df2ea 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -173,8 +173,10 @@ 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. Multiple-result -framing remains open there. XML is removed from current consideration. +reuses the YAML renderer; template errors never trigger fallback. Aggregate +configuration display uses an ordinary scope-keyed mapping through the same +renderers, with no scope-order guarantee or separate-document machinery. +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 1ac4c72..079b93a 100644 --- a/docs/roadmap/promptkit-v0.19.0.md +++ b/docs/roadmap/promptkit-v0.19.0.md @@ -474,7 +474,8 @@ 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. +accepted ADR's decision text as history. The aggregate presentation decision below +also replaces its separate-document framing. This approach reduces new machinery by reusing standard serialization and centralizing the remaining conversion and rendering work. Exact internal @@ -523,20 +524,52 @@ renderer or pretty-printer. It supersedes the proposed generic text outline. Applications do not supply separate YAML/JSON writers, and a failing template never enters this no-template path. -### Remaining core reporting decisions +### Agreed aggregate configuration presentation -- **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. +**Agreed:** `config show --scope all` produces one mapping keyed by the unique +scope identifiers. Each value is that scope's safe effective configuration: + +```yaml +app: + server: + port: 8080 +promptkit: + default_profile: standard +``` + +The example illustrates the report shape. Scope names sit outside each +configuration's namespace; no `scope` or `config` metadata field is inserted +into the configuration. Keep the scope-keyed mapping even when only one scope +is registered. Single-scope display continues to return the configuration value +directly, without a scope wrapper. + +`ckconfig` collects the safe values and hands the complete ordinary Go mapping +to core once. Core renders it using the shared machinery: automatic selection +chooses YAML, explicit JSON renders the same mapping, and explicit text without +a template uses the YAML fallback. No separate-document output or special core +multi-result rendering API is needed. Applications and integrations choose how +to group other reports using ordinary report values. + +Scope order has no semantic significance or output-order guarantee in this +aggregate mapping. Retain the existing availability checks and acquisition +behavior: acquire all selected views and complete provider-required validation +before report output begins; a failure prevents the combined display. The new +shape does not introduce partial-success output. + +When implementation lands, supersede ADR 0007's ordered native-document framing +and refine [ADR 0009](../adr/0009-configuration-scopes.md)'s combined-display +ordering contract through a new ADR. This decision concerns aggregate display; +it does not change scope discovery or acquisition ordering. + +### Remaining core reporting implementation details 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, -safe YAML input conversion, or joint format delivery. +safe YAML input conversion, aggregate configuration presentation, or joint +format delivery. Report serialization does not settle the separate JSON input-number conversion choices in OD-2 and OD-11. @@ -585,8 +618,8 @@ incidental formatting detail in tests. ## Work sequence 1. **Confirm remaining implementation choices.** Use the accepted flags, report - content, and automatic format policy as the MVP target. Resolve the remaining - multiple-result framing decision; specify the public API, reusable template helpers, + content, aggregate presentation, and automatic format policy as the MVP target. + 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 @@ -644,8 +677,7 @@ CommandKit to retest PromptKit rendering, schema, namespace, or ConfigKit resolution algorithms. Default tests remain offline and independent of real credentials. -- [ ] Multiple-result framing is decided and recorded. - Public signatures and shared representation conventions are +- [ ] Public signatures and shared representation conventions are documented with implementation. - [ ] Core owns universal `--format` options, help, validation, and selection. Added core formats work with existing commands without refactoring or local @@ -689,8 +721,14 @@ Default tests remain offline and independent of real credentials. 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. +- [ ] A superseding ADR records the replacement of native-writer, mapping-order, + and separate-document requirements in ADR 0007 and the combined-display ordering + requirement in ADR 0009; canonical contracts are updated with implementation. +- [ ] `config show --scope all` hands off one mapping keyed by scope identifier, + including when only one scope is registered. All formats retain scope identity + and safe values without injecting metadata into configuration fields. Cover + configurations with fields named `scope` or `config`, single-scope unwrapped + output, and failure before combined display. Do not assert aggregate scope order. - [ ] 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. @@ -849,7 +887,7 @@ to this roadmap, not the retired adoption documents. The core ownership, JSON representation conventions, text printing/templates, universal-format, automatic-selection, and joint format-delivery decisions are now agreed above. Remaining details are listed under -[remaining core reporting decisions](#remaining-core-reporting-decisions). +[remaining core reporting implementation details](#remaining-core-reporting-implementation-details). Outstanding integration choices are provider JSON decoding in OD-2, namespace applicability in OD-3, empty comparison collections and binding design in OD-9, and override grammar/acquisition details in OD-11. Exact helper names and report @@ -1201,7 +1239,7 @@ 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 null remains a valid value; historical-only paths are not effective values. Path-selected display initially uses one scope, while whole-document -`--scope all` remains available. +`--scope all` uses the agreed [scope-keyed mapping](#agreed-aggregate-configuration-presentation). Filters change presentation, not validation outcomes. Keep source references needed to interpret the selected findings. Apply subtree filtering to parsed