From 111f963c6721dd60f6d7a658a210a54bd507a180 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 6 Nov 2026 13:56:45 +0000 Subject: [PATCH] Record explicit prompt input flags and text aliases --- docs/roadmap/future.md | 23 ++++++--- docs/roadmap/promptkit-v0.19.0.md | 82 ++++++++++++++++++++++--------- 2 files changed, 76 insertions(+), 29 deletions(-) diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 6db01f5..4fc6c3b 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -86,9 +86,10 @@ and the shared configuration inspection extensions. Its execution flags will be public reusable `ckprompt` collections for standard and application-owned CLI commands, composed through existing core bindings. [Roadmap OD-2](promptkit-v0.19.0.md#od-2-request-controls-and-provider-parameter-grammar) -records the agreed canonical naming, scoped convenience aliases, and integration -installation collection; no core extension is required. Additional request-input -features remain open for individual review. These are CLI features; +records the agreed canonical naming, scoped convenience aliases, integration +installation collection, and selected text/file input forms; no core extension +is required. Appended-message flags remain open for individual review. These +are CLI features; general-purpose helpers for application-internal PromptKit use are outside CommandKit's ownership boundary. @@ -103,11 +104,19 @@ CommandKit's ownership boundary. command syntax and report fields; this feature is outside the v0.19.0 adoption scope. -Additional request controls, including output-contract, inline-input, and -appended-message flags, remain scope choices under +- **Output-contract override flags.** Deferred from the current adoption. A + possible future operator task is validating or previewing one prompt with a + replacement output contract without editing its definition. PromptKit uses + whole-contract replacement; a complete-contract file option was discussed, + but no flag spelling or file format is selected. Existing configuration and + application builders remain available. Revisit when the standard `promptkit` + commands have a demonstrated need for this workflow. + +Appended-message flags remain a scope choice under [roadmap OD-2](promptkit-v0.19.0.md#od-2-request-controls-and-provider-parameter-grammar). -Their native API availability alone does not select CLI syntax or require a -convenience API for application execution. +Inline text and explicit file input are now selected there for single-prompt +validation and preview. Native API availability alone does not select further +CLI syntax or require a convenience API for application execution. ### Alias completion and discovery diff --git a/docs/roadmap/promptkit-v0.19.0.md b/docs/roadmap/promptkit-v0.19.0.md index 673cfba..ce59dca 100644 --- a/docs/roadmap/promptkit-v0.19.0.md +++ b/docs/roadmap/promptkit-v0.19.0.md @@ -94,7 +94,8 @@ 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 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`. | +| Inspect what a concrete prompt request prepares | `promptkit show prepared PROMPT_ID --profile … --input-file … --var …` | `ckprompt`: YAML report of selected IDs, effective settings, rendered/appended messages, output contract and schema, session, hashes, and timing from `PreparedRun`. | +| Supply a short sample to one prompt without creating a file | `promptkit show prepared PROMPT_ID --input NAME=TEXT`; also request validation | `ckprompt`: native inline input for single-prompt preparation; file input remains available through `--input-file NAME=PATH`. | | Reproduce target/provider settings without editing configuration | Applicable existing smoke override flags on validation and preview; `--llm-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. | @@ -186,7 +187,8 @@ values and whole-map replacement semantics. Support deliberate subsets for actual command needs while retaining common flag names and meanings, using a proportionate composition API. Keep parsing in CommandKit and domain validity in PromptKit. Existing application builders remain authoritative as agreed in -OD-2; additional request-input controls remain open for individual review. +OD-2. That decision also selects literal-text and file input bindings, defers +output-contract overrides, and leaves appended-message controls open. ### Namespace selection @@ -295,8 +297,9 @@ errors remain errors even if an override would replace the affected value. against the released notices and source commit. Update the unpublished candidate note and affected canonical dependency/compatibility guidance. No core Go-minimum increase follows from this adoption. -3. **Implement request inspection and selection.** Add preview, applicable - override flags, provider-parameter input, and namespace selectors. Implement +3. **Implement request inspection and selection.** Add preview, literal-text + input and renamed file-input flags, applicable override flags, + provider-parameter input, and namespace selectors. Implement public `ckprompt` execution-flag collections on existing core bindings and reuse them in the standard commands. Generate scoped convenience aliases and provide a collection for installing the commands and routing declarations. @@ -357,8 +360,12 @@ Default tests remain offline and independent of real credentials. - [ ] The convenient installation collection includes commands and their scoped aliases; canonical-only installation remains available. Help and migration guidance explain both forms without requiring consumer-maintained alias lists. -- [ ] Output-contract, inline-input, and appended-message options each receive - an explicit scope decision before implementation. +- [ ] Text and file input names and aliases follow OD-2. Literal content, + including empty text, reaches native inline inputs; file bindings remain file + references. Examples, help, and documentation use the selected meanings. + Resolve and cover duplicate-name precedence across the two input forms. +- [ ] Appended-message options receive an explicit scope decision before + implementation; output-contract override flags remain deferred. - [ ] Namespace defaults, explicit clearing, qualified selections, and catalog filters are forwarded according to the selected design. - [ ] The full configuration suite retains six subcommands. Explanation @@ -427,6 +434,8 @@ handle lifecycle, sessions, and observer convenience APIs remain application responsibilities. Persistent configuration editing, new live probes, dynamic completion, JSON report formats, and unrelated deferred proposals are not added by this roadmap. Transient acquisition overrides remain an explicit choice in OD-11. +Output-contract override flags are also deferred under OD-2 and retained in +[future work](future.md#promptkit-inspection-and-selection-extensions). Discovery tracing and secrets-directory bootstrap commands remain deferred: the source inventory is not a trace of rejected search candidates, and bootstrap performs application startup effects. @@ -493,11 +502,12 @@ applications may deliberately install convenience aliases on their own commands. | `--llm-prompt` | `--prompt` | | `--llm-session-id` | `--session-id` | | `--llm-var` | `--var` | -| `--llm-input` | `--input` | +| `--llm-input-text NAME=TEXT` | `--input-text`, `--llm-input`, `--input` | +| `--llm-input-file NAME=PATH` | `--input-file` | -Retain existing value syntax and units, including integer timeout seconds and -file-backed input bindings. Commands taking a positional prompt ID retain that -argument; this naming decision does not add a redundant prompt flag. Execution, +Retain existing value syntax and units, including integer timeout seconds. +The input naming and content changes are specified below. Commands taking a +positional prompt ID retain that argument; this naming decision does not add a redundant prompt flag. Execution, resource-selection, and request-input collections may remain separately composable. Namespace controls remain subject to OD-3. @@ -520,19 +530,47 @@ existing core API. Subtree alias scopes and a new core declaration-bundle type are not part of this adoption. Help should identify canonical names and their applicable aliases using current -core presentation. Review published flag contracts during implementation and -document migration, including retention of existing unprefixed spellings through -the convenience collection. Do not assume canonical-only installation preserves -those spellings. +core presentation. CommandKit is alpha with no consumers; redesign without +compatibility constraints is explicitly accepted for these flags. Update implementation, examples, help, and documentation together; do not +retain old meanings merely for compatibility. Canonical-only installation does +not supply convenience aliases. -**Remaining request surface:** discuss output-contract overrides, inline-input -flags, and appended-message flags individually before selecting scope and syntax. -Agreement to discuss these separately does not yet include or defer them. -Existing file inputs and application builders continue to support preview. A -whole-output-contract file option and additional message/input options could -support more reproduction workflows, with corresponding syntax, precedence, -and reporting decisions. No general-purpose request-building API follows from -these CLI choices. +**Agreed input forms:** include literal text alongside file input for +`promptkit requirements validate` and `promptkit show prepared`. The concrete +operator task is preparing one selected prompt with a short, disposable sample +without creating a fixture file. File inputs remain useful for substantial +content and repeatable artifacts. These operations make no model call and do +not establish model-output quality or application-workflow success. Assess +usefulness within these standard commands; speculative applicability to +multi-prompt application workflows is not a reason to add flags. + +Use the explicit canonical pair `--llm-input-text NAME=TEXT` and +`--llm-input-file NAME=PATH`. The scoped aliases in the table include both +`--input` and `--llm-input` for literal text. They route to the original text +binding with the same parsing, presence, and occurrence-order behavior. +`--input` no longer means a file path; file bindings use the explicit file form. +Do not infer file access from literal content that resembles a path. + +Provide repeatable named bindings, splitting at the first `=` and preserving +literal content, including explicit empty text, through native `Inline` inputs. +File bindings continue to use native `File` references. Keep the canonical +forms available through reusable request-input collections; application commands +choose whether these bindings fit their workflow and may opt into aliases. +None of these aliases is application-wide by default. Do not add prompt-input +flags to smoke tests, which use their own diagnostic content. + +Duplicate-name precedence across text and file bindings remains a design point +for review. The current recommendation is last command-line occurrence wins +across both forms; this is not yet an agreed cross-binding ordering contract. + +**Deferred output-contract overrides:** no CLI override is included in this +adoption. Retain the candidate in +[future work](future.md#promptkit-inspection-and-selection-extensions); +existing configuration and application builders remain available. + +**Remaining request surface:** discuss appended-message flags individually +before selecting scope and syntax. No general-purpose request-building API +follows from these CLI choices. ### OD-3: Namespace flags and loader defaults