diff --git a/docs/roadmap/promptkit-v0.19.0.md b/docs/roadmap/promptkit-v0.19.0.md index 73f742a..1aa63c0 100644 --- a/docs/roadmap/promptkit-v0.19.0.md +++ b/docs/roadmap/promptkit-v0.19.0.md @@ -2,7 +2,7 @@ Status: proposed roadmap for review. Scope is agreed in principle; implementation has not started. Command spellings, report designs, and API changes below are -recommendations until the open decisions are resolved. +recommendations except where explicitly recorded as agreed below. ## Purpose and ownership @@ -89,12 +89,12 @@ The original adoption tasks remain included: propagation at CommandKit's boundary. 4. Validate the final independent modules and aligned workspace. -Add the following operator capabilities. Syntax is illustrative and subject to -the decisions at the end of this document. +Add the following operator capabilities. Syntax is illustrative unless selected +in the decisions at the end of this document. | Operator task | Proposed CLI | Owning module and report | | --- | --- | --- | -| Inspect what a concrete prompt request prepares | `promptkit show request ID --profile … --input … --var …` | `ckprompt`: selected IDs, effective settings, rendered/appended messages, output contract and schema, session, hashes, and timing from `PreparedRun`. | +| Inspect what a concrete prompt request prepares | `promptkit show prepared PROMPT_ID --profile … --input … --var …` | `ckprompt`: YAML report of selected IDs, effective settings, rendered/appended messages, output contract and schema, session, hashes, and timing from `PreparedRun`. | | Reproduce target/provider settings without editing configuration | Applicable existing smoke override flags on validation and preview; `--extra-params JSON` on these and smoke operations | `ckprompt`: native request forwarding; preview and smoke reports show returned effective settings. | | Resolve unqualified resource selections in chosen namespaces | Independent prompt/profile/backend namespace flags | `ckprompt`: delegate to native namespace views, retaining the distinction from catalog filters. | | Find configuration paths and inspect their explicitness | `config explain --list --scope promptkit`, with historical selection; metadata alongside path explanation | `ckconfig`, wired through `ckprompt.ConfigScope`: observed paths, effective presence, explicitness/null/origin evidence, and available history. | @@ -148,8 +148,9 @@ cause identity. Native errors and their categories remain upstream-owned. ### Preview and request flags -Add an independently available preview capability alongside existing suite -callbacks. The native adapter calls `Engine.Prepare` and projects its returned +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. Exact callback names and signatures follow the selected CLI design. @@ -335,9 +336,11 @@ Default tests remain offline and independent of real credentials. native unknown facts. Smoke preparation errors retain supported causes and operational outcomes, including the no-report case; no model dispatch is introduced by CommandKit to handle them. -- [ ] Preview forwards the intended request and faithfully reports native - fields. Its CLI path makes no model call and does not create/execute retained - prepared handles. +- [ ] `promptkit show prepared PROMPT_ID` forwards the intended request and + faithfully reports native fields in YAML, the only initial output format. + 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. - [ ] New flags preserve selected omission/empty/zero semantics, parse malformed inputs through the existing usage path, and do not leak state between runs. Numeric decoding of provider JSON matches the selected strategy in OD-2. @@ -420,21 +423,26 @@ performs application startup effects. ## Open Decisions -These decisions concern significant choices within the proposed scope. OD -numbers are local to this roadmap, not the retired adoption documents. +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. ### OD-1: Preview command and report presentation -**Recommendation:** use `promptkit show request ID`, with YAML as the initial -report format and the complete relevant `PreparedRun` projection. It sits beside -definition inspection while clearly requiring concrete inputs. A single native -preparation supplies both validation and preview evidence. Document rendered -content disclosure directly in help and CLI guidance. +**Agreed:** use `promptkit show prepared PROMPT_ID`, with YAML-only output +initially and the complete relevant `PreparedRun` projection. The argument names +the prompt to prepare, not a saved prepared object. A single native preparation +supplies both validation and preview evidence. -**Alternative:** `promptkit prepare ID`, with text and YAML reports. This names -the native action and makes interactive inspection easier, but can suggest an -executable prepared handle and adds a second rendering contract. Both forms can -stay entirely within CLI ownership; select vocabulary and formats before coding. +The command sits beside definition inspection and emphasizes that the report +contains resolved settings and rendered content. Use help wording such as: +"Prepare a prompt request and show the resulting messages and settings without +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. ### OD-2: Request controls and provider-parameter grammar