diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 00c97b8..238d4fe 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -70,7 +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 formats and filter spellings are selected in the roadmap; +Initial report content, default preferences, and filter spellings are selected +in the roadmap; core owns universal 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 @@ -161,12 +162,14 @@ steps. No delivery date or final API is selected here. ### Reporting extensions 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 the agreed command -output declarations, format-independent reporting operation, and centralized -representation rules, initially targeting YAML. Human-oriented/native rendering -and format availability remain open discussions there. Additional renderers such -as JSON, XML, and Markdown remain future work; planning for them does not select -their mappings, command coverage, or delivery dates. +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 +existing commands without per-command adoption. Error-conversion helpers such as `WarnError` remain deferred pending demonstrated value; applications can already use `report.Warn(err.Error())`. Terminal redraw diff --git a/docs/roadmap/promptkit-v0.19.0.md b/docs/roadmap/promptkit-v0.19.0.md index dd0f9df..ecd9b9c 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 format-independent report output API, initially targeting YAML, 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 selection, optional command defaults, and text/YAML/JSON targets, 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,11 +162,12 @@ cause identity. Native errors and their categories remain upstream-owned. ### Preview and request flags -Expose preview as `promptkit show prepared PROMPT_ID`, with YAML-only output -initially, 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 diagnostics, and invocation reporting patterns. +Expose preview as `promptkit show prepared PROMPT_ID`, defaulting to YAML and +accepting core's 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 +diagnostics, and invocation reporting patterns. Exact callback names and signatures follow the selected CLI design. Preview performs applicable resource I/O and rendering but no model call. @@ -315,34 +316,52 @@ 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. -YAML is the initial structured output target. Design the public entry points -for additional formats, such as JSON, XML, and Markdown, without requiring -handlers to change their reporting call. This selects extensibility now, not -implementation of those additional renderers in this adoption. It supersedes -the earlier suggestion to assess only an optional YAML writer during -implementation. Keep the implementation proportionate; exact public names, -signatures, and internal representation remain design work. +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 +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 -Declare output behavior once per command, including its default format and -supported alternatives. Core uses that declaration for a standard `--format` -flag, help, input validation, and renderer selection. Omission selects the -declared default; an explicit supported value selects the requested format. -Use one format flag rather than separate `--yaml`, `--json`, or `--xml` flags. -An unsupported selection is a usage error before acquisition or other command -work. Handlers do not repeat this plumbing. +Core owns the universal `--format` flag, its available options, help, input +validation, and renderer selection. Commands do not maintain format allowlists; +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. -This establishes the declaration and selection mechanism. How available -renderers become supported alternatives for a particular report remains a -separate open discussion below. +Commands may optionally declare a default output format. 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. + +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. ### Agreed format-independent reporting operation -Provide one public operation through the invocation Reporter that accepts report -data without requiring a handler to switch on the selected format or configure -an encoder. `invocation.Reporter().Report(report)` illustrates the intended -shape only; it is not a selected signature or an existing API. +The application or integration decides what content to report, including which +information appears normally and what is added by `--details`. Core does not +select domain facts, add detail when a format changes, or infer a summary. +Retain the agreed `--details` spelling for the standard commands. + +Provide one public operation through the invocation Reporter that accepts the +selected report data and an optional plain-text template, without requiring a +handler to switch on the selected format or configure an encoder. Core renders +both concise and detailed report values. `invocation.Reporter().Report(report)` +illustrates the intended operation only; it is not a selected signature or an +existing API. Provide a corresponding writer-based API for rendering outside an invocation. Both entry points share the rendering implementation. Invocation reporting uses @@ -371,34 +390,57 @@ Exact conventions, serialization-contract selection, and adapter APIs need to be specified during design. A large public document model or custom reflection framework is not selected by this decision. -### Remaining core reporting discussions +### Agreed plain-text rendering -The following topics remain open and must be settled before their corresponding -API contracts are finalized: +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 +template. Applications do not supply separate YAML/JSON writers. -- **Human-oriented presentation (discussion point 4).** Determine how concise - text and richer formats such as Markdown relate to automatic structured - rendering, what shared layout helpers are useful, and where custom or native - renderers fit. Generic tables, field lists, custom-renderer hooks, and a - native-document path are candidates, not accepted API requirements. Preserve - the previously agreed operator reports while deciding their implementation. -- **Format availability (discussion point 5).** Determine how core renderer - availability relates to the formats offered by each command or report, - including whether adding a renderer automatically enables it for suitable - reports or requires explicit adoption. Do not infer that every command must - support every format, or select mandatory per-report opt-in, from the agreed - declaration mechanism alone. XML mapping conventions and cross-format - limitations will need deliberate treatment when those formats are added. +Recommend a readable hierarchical fallback with named fields, nested values, +and list items. A template can arrange the supplied content as a sentence, +table, or another useful presentation. Core owns template execution, shared +formatting helpers, and delivery errors. Go's `text/template` and reusable +templates declared once are implementation candidates; the template API, +helper set, and exact fallback layout still need design. -These discussions do not reopen the agreed declaration mechanism, shared -reporting operation, or centralized representation rules. They also do not -silently expand the YAML-only reports already selected in this roadmap. +This resolves the earlier human-oriented presentation discussion (point 4). +Universal core formats resolve point 5; per-command supported-format lists and +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 + numeric loss. This concerns report data, not arbitrary runtime objects. +- **Text handoff.** Settle the template API and helper functions, whether + templates receive the original Go value or shared representation, fallback + conventions, and template preparation and failure behavior. Prefer a small + reusable mechanism; applications select content and layout, core renders it. +- **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. + +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. ## 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. Resolve the core discussions +feedback on actual reports should guide changes. Resolve the core design details above, then implement the agreed extension points without delaying delivery for exhaustive layout design or speculative additional renderers. @@ -421,10 +463,10 @@ 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 existing native-document semantics and concise diff and validation -presentations. Their connection to the shared API is part of the open -human-oriented/native-rendering discussion, not a decision to rewrite them as -generic structured dumps. +Preserve native-document semantics 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. Separate content projection from format rendering and from invocation delivery. Use the existing Reporter and outcome lifecycle for delivery and failures. @@ -436,15 +478,17 @@ incidental formatting detail in tests. ## Work sequence 1. **Confirm remaining implementation choices.** Use the accepted flags and - report formats as the MVP target. Resolve the two remaining core reporting - discussions and specify the public API and shared representation conventions. + 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. 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 - declarations, `--format` selection, format-independent Reporter operation, - writer-based API, and shared representation/encoding machinery, with YAML as - the initial structured target. Exercise the public API with core reporting + defaults, 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 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 @@ -493,12 +537,19 @@ CommandKit to retest PromptKit rendering, schema, namespace, or ConfigKit resolution algorithms. Default tests remain offline and independent of real credentials. -- [ ] Human-oriented/native rendering and format-availability decisions are - recorded before finalizing their core API contracts. Exact public signatures - and shared representation conventions are documented with implementation. -- [ ] Command output declarations drive defaults, `--format`, help, validation, - and renderer selection. Unsupported selections produce usage failures before - acquisition, and selected formats do not leak between invocations. +- [ ] Remaining representation, text-template, native-document, and initial + default/staging 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. +- [ ] 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. - [ ] The invocation and writer-based public APIs share rendering behavior; handlers submit report data without their own format switches or encoder setup. Existing quiet-mode, presentation-failure, and domain-outcome behavior @@ -519,7 +570,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 in YAML, the only initial output format. + faithfully reports native fields, defaulting to YAML 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. @@ -557,9 +609,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 +- [ ] 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. - [ ] Metadata discovery through `config explain` distinguishes effective and historical paths, retains available history on absent lookup, and projects @@ -573,9 +626,10 @@ 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 its current contract. Focused display uses one scope and native YAML - without a snapshot wrapper; absent effective paths and unknown source IDs - produce clear operational failures. + 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. - [ ] 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. @@ -591,10 +645,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, 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. + diagnostic report, with an initial text default preference and universal + format choices. 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 available evidence with an acquisition error; the original failure, unavailable-versus-empty evidence, cancellation, and @@ -640,10 +694,11 @@ from configuration to deliver it in this roadmap. General execution, prepared handle lifecycle, sessions, and observer convenience APIs remain application responsibilities. Persistent configuration editing, new live probes, dynamic completion, and unrelated deferred proposals are not added by this roadmap. -JSON, XML, and Markdown renderers remain future additions; the -[shared core API](#shared-core-report-output-prerequisite) now explicitly plans -for format extensibility. Renderer availability policy remains open, and this -roadmap does not promise those formats for every report. +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. Transient acquisition overrides are included under OD-11. Output-contract override and appended-message flags are deferred under OD-2 and retained in @@ -658,10 +713,19 @@ 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). +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 +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-only output -initially and the complete relevant `PreparedRun` projection. The argument names +**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 the prompt to prepare, not a saved prepared object. A single native preparation supplies both validation and preview evidence. @@ -672,8 +736,9 @@ 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. A separate -text presentation may be considered later; it is outside the initial scope. +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. ### OD-2: Request controls and provider-parameter grammar @@ -847,8 +912,8 @@ 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 YAML available through `--format yaml`, and one scope at a time. List -current effective paths by default; `--historical` adds historical-only paths +with alternatives through core's universal `--format`, and 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 application defaults or historical-only metadata with explicitness false. @@ -888,7 +953,9 @@ 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. YAML is the only initial detailed format. +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. Keep the projection close to native report values, using the [shared reporting approach](#initial-report-implementation-approach) rather than @@ -915,8 +982,8 @@ mode on `config diff`. Retain concise validation by default, including its ordinary warning and error reporting. Detailed mode reports available native diagnostic records and source references alongside the validation result. The purpose is to help a human operator locate and investigate configuration -problems; it does not introduce new validation rules. Selecting YAML alone does -not implicitly enable the additional detail. +problems; it does not introduce new validation rules. Changing the output format +does not implicitly enable the additional detail. Preserve available evidence when loading fails: `config validate --details` reports diagnostic findings and relevant source references, and `config sources` @@ -931,9 +998,10 @@ 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 -YAML available through `--format yaml`. Begin text output with scope and outcome, -then show readable findings with their available messages, severities, codes, -configuration paths, and source locations. Place useful locations near messages; +alternatives through core's universal `--format`. Supply a text template that +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. Use repeatable `--severity` and `--code` filters in detailed mode. Multiple values @@ -984,10 +1052,12 @@ 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. -Focused show emits the selected native effective YAML directly, without a -snapshot wrapper containing presence/redaction/YAML fields. 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 +`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. +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.