diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 238d4fe..876f9a6 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -70,8 +70,8 @@ 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. -Initial report content, default preferences, and filter spellings are selected -in the roadmap; core owns universal format selection. The +Initial report content, text templates, and filter spellings are selected +in the roadmap; core owns universal and automatic format selection. The 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 @@ -164,11 +164,13 @@ steps. No delivery date or final API is selected here. The [shared core report output prerequisite](promptkit-v0.19.0.md#shared-core-report-output-prerequisite) is now part of the working adoption roadmap. It records application-owned content selection, core-owned rendering, a text fallback with optional templates, -universal format availability, and optional command defaults that otherwise -defer to core policy. Plain text, YAML, and JSON are the target formats; -representation, template, native-document, and delivery-staging details remain -there. XML is removed from current consideration. Markdown and other potential -formats are not selected for this adoption; new core formats will work with +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; representation, template, and +native-document details remain 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. Error-conversion helpers such as `WarnError` remain deferred pending demonstrated diff --git a/docs/roadmap/promptkit-v0.19.0.md b/docs/roadmap/promptkit-v0.19.0.md index ecd9b9c..7fdb6a5 100644 --- a/docs/roadmap/promptkit-v0.19.0.md +++ b/docs/roadmap/promptkit-v0.19.0.md @@ -33,7 +33,7 @@ The completed v0.18.0 adoption is not reopened. | Component | Current baseline | Target | | --- | --- | --- | -| Core | `go.maximumdirect.net/commandkit`; Go 1.26.0 minimum | Public report output API with universal format selection, optional command defaults, and text/YAML/JSON targets, as a prerequisite. Flag collections and scoped aliases still use existing core APIs. | +| Core | `go.maximumdirect.net/commandkit`; Go 1.26.0 minimum | Public report output API with universal format choices and automatic selection; text/YAML/JSON land together as a prerequisite. Flag collections and scoped aliases still use existing core APIs. | | `ckconfig` | ConfigKit v1.1.0; Go 1.27.0; core v0.3.0 | Adopt the new core reporting API, shared CLI inspection extensions, and an appropriate module release. | | `ckprompt` | PromptKit v0.18.0; ConfigKit v1.1.0; ckconfig/core v0.3.0; Go 1.27.0 | Adopt the new core reporting API, 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. | @@ -162,8 +162,8 @@ cause identity. Native errors and their categories remain upstream-owned. ### Preview and request flags -Expose preview as `promptkit show prepared PROMPT_ID`, defaulting to YAML and -accepting core's universal format choices, through an independently available +Expose preview as `promptkit show prepared PROMPT_ID`, using core's automatic +selection and universal format choices, through an independently available capability alongside existing suite callbacks. The native adapter calls `Engine.Prepare` and projects its returned snapshot; a preliminary `ValidateRequest` call is unnecessary. Use existing typed selection, acquisition @@ -316,17 +316,18 @@ Centralize formatting and translation machinery to the greatest practical extent so commands share output conventions and avoid repeated infrastructure. Core remains independent of ConfigKit and PromptKit types and domain semantics. -Focus the capability on plain text, YAML, and JSON. YAML remains the first -structured encoding target; text and JSON are near-term targets, with delivery -staging to be settled during implementation planning. XML is removed from -current consideration. Markdown is not selected for this adoption. New core -formats must work with existing commands without handler refactoring or +Deliver plain text, YAML, and JSON together in the same core feature release, +implemented in separate reviewable units as useful. Exercise all three before +downstream integration additions depend on the API, so representation decisions +are validated across formats. XML is removed from current consideration. +Markdown is not selected for this adoption. New core formats must work with +existing commands without handler refactoring or per-command encoder registration. This supersedes both the optional YAML-helper proposal and earlier YAML-only report restrictions. Keep implementation proportionate; exact public names, signatures, and internal representation remain design work. -### Agreed command declarations and format selection +### Agreed universal and automatic format selection Core owns the universal `--format` flag, its available options, help, input validation, and renderer selection. Commands do not maintain format allowlists; @@ -334,20 +335,46 @@ adding a renderer and format option in core makes it available to existing commands automatically. An unknown format is a usage error before acquisition or other command work. Use one format flag rather than separate format flags. -Commands may optionally declare a default output format. Resolve the effective -format in this order: +The initial public API does not offer command-specific format defaults. Resolve +the effective format in this order: 1. The operator's explicit `--format` choice. -2. The command's declared default, if supplied. -3. CommandKit's centrally chosen default. +2. Text when the report handoff includes a text template. +3. Core's automatic selection from the shared report representation below. -An unset command default means "CommandKit chooses," not "plain text." Preserve -that distinction in the public API rather than making the unspecified value an -alias for text. Core can deliberately change its default in a future release; -commands with explicit defaults retain their preference. A command default does -not restrict operator choices or prevent automatic adoption of new formats. -`config show` declares YAML as its default. Plain text is recommended as the -initial core default, but that policy is not yet selected. +| Report content, without a text template | Automatic format | +| --- | --- | +| String | Text | +| Nonempty sequence containing only strings | Text, one item per line | +| Number or boolean | Text | +| Mapping, including an empty mapping | YAML | +| Sequence of mappings, nested sequences, or mixed values | YAML | +| Empty sequence or null | YAML, keeping the empty result visible | + +Inspect the logical report representation after the selected serialization and +adaptation rules, not just the original Go type. A struct normally represents a +mapping, while a custom serializer may represent that value as a string. Use the +outer shape; do not search inside mappings for a presumed primary field. Select +once for the complete logical report, not independently for each item in a +result collection. + +Omitting `--format` means "CommandKit chooses," not a fixed text default. The +choice can vary with the result: a populated string list yields text, while an +empty list yields YAML `[]`. Explicit selection provides a predictable format +when needed, including `config show --format yaml` for a configuration document +even when the selected value is a string. Core can deliberately evolve its +automatic policy in a future release. + +This supersedes optional command defaults and the proposed per-command default +inventory, including explicit YAML defaults for `config show`, `config diff`, +and prepared-request preview. Applications choose report content and optional +text templates; core selects the format. Reconsider command overrides only for +a concrete demonstrated requirement. + +For `config show`, hand off the selected logical configuration value, not a +string containing serialized YAML or a snapshot metadata wrapper. With no text +template, a configuration mapping naturally selects YAML and a selected string +value selects text. Native snapshot adaptation must preserve that distinction. ### Agreed format-independent reporting operation @@ -393,10 +420,12 @@ framework is not selected by this decision. ### Agreed plain-text rendering Core provides a default plain-text fallback and accepts an optional template -from the application or integration as part of the report handoff. With a -template, core renders the chosen text arrangement; without one, it renders the -selected report data using its standard fallback. YAML and JSON use the same -selected content and shared representation rules, independently of the text +from the application or integration as part of the report handoff. When text is +selected, core uses the template if supplied and otherwise renders the selected +report data using its standard fallback. A template selects text automatically +only when the operator omits `--format`; explicit YAML or JSON takes precedence. +YAML and JSON use the same selected content and shared representation rules, +independently of the text template. Applications do not supply separate YAML/JSON writers. Recommend a readable hierarchical fallback with named fields, nested values, @@ -412,11 +441,6 @@ per-format application renderers are not the selected mechanism. ### Remaining core reporting decisions -- **Initial defaults and staging.** Confirm the initial central default - (recommend text), which standard commands pin a default versus inherit core - policy, and whether text/YAML/JSON land together or in successive core units. - `config show` explicitly defaults to YAML; the existing selected text/YAML - presentations are starting targets, not format restrictions. - **Shared representation contract.** Specify field/tag and custom-marshaling precedence, omission and scalar rules, supported Go report values, and how unsupported values are reported. Keep adapters explicit and avoid silent @@ -434,7 +458,8 @@ per-format application renderers are not the selected mechanism. Exact public signatures, flag integration/collision handling, and replacement of existing format plumbing are implementation design tasks. The decisions -above do not reopen content selection, universal formats, or default precedence. +above do not reopen content selection, universal formats, automatic selection, +or delivery of all three initial formats together. ## Initial report implementation approach @@ -477,18 +502,18 @@ incidental formatting detail in tests. ## Work sequence -1. **Confirm remaining implementation choices.** Use the accepted flags and - report content and default preferences as the MVP target. Resolve the - remaining core representation, text-template, native-document, and initial - default/staging decisions; specify the public API. +1. **Confirm remaining implementation choices.** Use the accepted flags, report + content, and automatic format policy as the MVP target. Resolve the remaining + core representation, text-template, and native-document decisions; specify + the public API. Resolve outstanding acquisition/binding grammar and flag collisions; use concrete examples to review report details during implementation rather than reopening accepted scope. -2. **Implement shared core report output.** Deliver the agreed command output - defaults, universal `--format` selection, format-independent Reporter +2. **Implement shared core report output.** Deliver the agreed automatic format + policy, universal `--format` selection, format-independent Reporter operation, writer-based API, and shared representation/encoding machinery. - Deliver YAML encoding, text fallback/templates, and JSON encoding according - to the selected staging. Exercise the public API with core reporting + Deliver YAML encoding, text fallback/templates, and JSON encoding together + in the core feature release. Exercise the public API with core reporting and an application-owned command example, and consolidate suitable existing integration reports onto it. Cover the selected contracts and update their canonical documentation with the implementation. Complete this prerequisite @@ -537,16 +562,22 @@ CommandKit to retest PromptKit rendering, schema, namespace, or ConfigKit resolution algorithms. Default tests remain offline and independent of real credentials. -- [ ] Remaining representation, text-template, native-document, and initial - default/staging decisions are recorded. Public signatures and shared - representation conventions are documented with implementation. +- [ ] Remaining representation, text-template, and native-document decisions + are recorded. 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 allowlists. Unknown selections fail before acquisition, and selected formats do not leak between invocations. -- [ ] Explicit operator selection overrides a declared command default, which - overrides core policy. An unspecified default remains distinct from text. - `config show` defaults to YAML without restricting other format choices. +- [ ] Explicit operator selection overrides automatic selection. Without it, + a text template selects text; otherwise core selects from the shared report + shape. Cover scalars, nonempty string lists, mappings, mixed/nested lists, + empty collections, and null. The initial API has no command format defaults. +- [ ] Automatic selection uses the logical report after adaptation, once per + complete report. Native YAML source strings are not mistaken for string + configuration values. Focused configuration values follow the same rules. +- [ ] Plain text, YAML, and JSON ship together; representative reports exercise + shared representation and explicit selection across all three. - [ ] Plain text uses the supplied template or core's fallback. Core owns rendering and errors in both cases. The integration chooses concise/detailed content; changing format does not implicitly change the selected detail level. @@ -570,8 +601,8 @@ Default tests remain offline and independent of real credentials. operational outcomes, including the no-report case; no model dispatch is introduced by CommandKit to handle them. - [ ] `promptkit show prepared PROMPT_ID` forwards the intended request and - faithfully reports native fields, defaulting to YAML and accepting universal - format choices. + faithfully reports native fields, using automatic selection and accepting + universal format choices. Help identifies the argument as a prompt ID and explains resource I/O and rendered content disclosure. Its CLI path makes no model call and does not create/execute retained prepared handles. @@ -609,11 +640,11 @@ 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 retains its initial text default preference, with universal - format choices, 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. +- [ ] Discovery supplies a compact text template, which core selects when no + format is requested, with 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. @@ -627,9 +658,9 @@ Default tests remain offline and independent of real credentials. - [ ] 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 - uses one scope and defaults to the native YAML value without a snapshot - wrapper; other formats use the shared representation. Absent effective paths - and unknown source IDs produce clear operational failures. + 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. - [ ] Source-ID selection works on successful and failed acquisitions. Path, explicitness, severity, and code filters preserve the selected evidence and source references without masking the acquisition outcome. @@ -645,8 +676,9 @@ 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, with an initial text default preference and universal - format choices. Changing format alone does not enable detailed mode. + diagnostic report with a text template. Core automatically selects text when + that template is supplied, while explicit formats still win. Changing format + 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 @@ -697,8 +729,7 @@ completion, and unrelated deferred proposals are not added by this roadmap. The [shared core API](#shared-core-report-output-prerequisite) targets text, YAML, and JSON, with automatic availability of newly added core formats. XML is removed from current consideration; Markdown is not selected for this -adoption. Exact delivery staging for the three target formats remains to be -settled, rather than retaining JSON as an unrelated deferred proposal. +adoption. The three initial formats land together in the core feature release. Transient acquisition overrides are included under OD-11. Output-contract override and appended-message flags are deferred under OD-2 and retained in @@ -713,9 +744,9 @@ These decisions concern significant choices within the proposed scope. Resolved items retain their numbers and record the agreed decision. OD numbers are local to this roadmap, not the retired adoption documents. -The core ownership, text fallback/template, universal-format, and default -precedence decisions are now agreed above. Their remaining design details are -listed under [remaining core reporting decisions](#remaining-core-reporting-decisions). +The core ownership, text fallback/template, universal-format, automatic-selection, +and joint format-delivery decisions are now agreed above. Their remaining design +details are listed under [remaining core reporting decisions](#remaining-core-reporting-decisions). 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 @@ -723,9 +754,11 @@ layouts otherwise remain ordinary implementation choices, not unresolved scope. ### OD-1: Preview command and report presentation -**Agreed:** use `promptkit show prepared PROMPT_ID`, with YAML as its default -and the complete relevant `PreparedRun` projection. Universal core format -selection supersedes the earlier YAML-only restriction. The argument names +**Agreed:** use `promptkit show prepared PROMPT_ID` with the complete relevant +`PreparedRun` projection. The structured mapping, without a dedicated text +template, selects YAML through core's automatic policy. Universal format choices +and automatic selection supersede both the earlier YAML-only restriction and +the command-specific default proposal. The argument names the prompt to prepare, not a saved prepared object. A single native preparation supplies both validation and preview evidence. @@ -737,8 +770,8 @@ calling the model." Document resource I/O and rendered content disclosure directly in help and CLI guidance. The report is an inspection snapshot, not a saved execution handle or a guarantee that later execution uses the same snapshot or succeeds. Core's -text fallback supplies text output without requiring a dedicated preview -template; a specialized template is not required for initial delivery. +text fallback supplies explicit `--format text` output without requiring a +dedicated preview template; a specialized template is not required for initial delivery. ### OD-2: Request controls and provider-parameter grammar @@ -911,8 +944,9 @@ the root explanation, not help. This deliberately replaces the current missing-path usage error; automatic discovery on a bare invocation is not selected. -**Agreed initial presentation:** use a compact text discovery report by default, -with alternatives through core's universal `--format`, and one scope at a time. +**Agreed initial presentation:** supply a compact text discovery template, which +core selects automatically when no format is requested. Explicit alternatives +use core's universal `--format`. Operate on one scope at a time. List current effective paths by default; `--historical` adds historical-only paths rather than selecting only removed paths. Show path, current/historical-only presence, and available explicitness. Do not equate non-explicit values with @@ -953,9 +987,11 @@ presence so missing and null remain distinct. Show redaction and concealed-chang 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. Retain YAML as the default preference; -universal core formats supersede the earlier YAML-only detailed restriction. -The same selected comparison evidence is handed to core in every format. +has an explicit empty difference list. Both concise and detailed comparison +hand off structured mappings without a text template; core's automatic policy +selects YAML. Universal format choices supersede the earlier YAML-only detailed +restriction. The same selected comparison evidence is handed to core in every +format; explicit text uses core's fallback. Keep the projection close to native report values, using the [shared reporting approach](#initial-report-implementation-approach) rather than @@ -997,9 +1033,9 @@ 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. -**Agreed initial presentation:** detailed validation uses text by default, with -alternatives through core's universal `--format`. Supply a text template that -begins with scope and outcome, then shows readable findings with their available +**Agreed initial presentation:** supply a detailed validation text template, +which core selects automatically unless the operator requests another format. +The template begins with scope and outcome, then shows readable findings with their available messages, severities, codes, configuration paths, and source locations. Place useful locations near messages; YAML may use a source legend shared by multiple findings. @@ -1052,10 +1088,11 @@ does not authorize publication. Keep reports unfiltered by default. The purpose is to reduce noise for a human operator investigating a known part of the configuration. -`config show` explicitly defaults to YAML. In that format, focused show emits -the selected native effective YAML directly, without a snapshot wrapper -containing presence/redaction/YAML fields. Other core formats render the selected -value through the shared representation; YAML is a default, not a restriction. +`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. +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 null remains a valid value; historical-only paths are not effective values.