From b3a0a73416c5e5db2f580884986538df6a62604a Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 19 Nov 2026 16:11:00 +0000 Subject: [PATCH] Record generation output and subprocess requirements --- docs/roadmap/commandkit-notepad.md | 60 +++++++++++++++++++++++------- 1 file changed, 46 insertions(+), 14 deletions(-) diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md index 80cec83..f2d1efd 100644 --- a/docs/roadmap/commandkit-notepad.md +++ b/docs/roadmap/commandkit-notepad.md @@ -80,6 +80,26 @@ Application-specific wiring remains to be designed, but inclusion of these three capabilities is settled. Prepared-request preview and the future of `render` remain a separate discussion below. +### Generation and subprocess requirements + +Decision recorded 2026-11-19: optimize the default generation response for the +majority of consumers, who want only the raw resulting artifact. Metadata is +optional. Consumers requesting it may receive it inline with the content or in +a separately saved report; either is acceptable, and both may be supported if +convenient. Supporting both delivery modes is not a requirement. + +Prefer native CommandKit reporting and PromptKit result types before introducing +a Scriptorium-specific response format. A failure must produce a nonzero process +status and information explaining the failure. This does not require a new +structured error envelope: native diagnostics are an acceptable way to deliver +that information. + +Scriptorium remains a neutral interface to PromptKit. Pass through the errors, +validation outcomes, and result information that PromptKit supplies rather than +adding independent judgments about generated content or redefining upstream +failure semantics. Adapting those outcomes to CommandKit and process exit codes +is application work; deciding what constitutes a PromptKit failure is not. + ## Upstream baseline The initial review covered CommandKit **v0.7.0**, ckconfig **v0.9.0**, and @@ -107,22 +127,34 @@ not requirements to reproduce during migration. ### 1 Generation output and process outcomes -The starting proposal is to keep generated artifact bytes easy to consume, -with execution metadata separately available. CommandKit supports both raw -output and structured reports; using it does not require wrapping generated -artifacts in a report envelope. +The consumer requirements above are settled. The proposed native composition is +a CommandKit `Report` whose value is PromptKit's `RunResult`, with a text +template that emits only generated content. Default/text output would serve +artifact consumers; standard JSON/YAML formats would expose the native result +and its metadata. This uses CommandKit's existing reporting mechanism and +PromptKit's existing result shape; ckprompt does not supply a general generation +command or prescribe this composition. Confirm this choice and decide whether +separate report-file delivery adds enough value to include it as well. -Decide the new generation interface: stdout versus explicit file output, -execution-report delivery, and how those choices interact with standard format -and verbosity controls. In particular, quiet mode suppresses CommandKit output -but does not cancel execution; application-owned file effects need an explicit -design. Ordinary diagnostics should follow upstream reporting conventions. +PromptKit's `RunResult` includes content, validation, selected resources, usage, +and timing. Operational failures return no partial `RunResult`; observer events +separately expose terminal metadata, retry counts, and presence-aware usage. +Do not invent an empty or synthetic success result to represent a failure. +Use native failure diagnostics, and consider additional observation reporting +only if a concrete consumer need warrants it. -Adopt upstream usage and operational outcomes, then decide how to represent -generated-output validation failure as an application domain outcome. The -current use of exit 2 for that failure conflicts with CommandKit's usage and -invalid-configuration convention. Also settle output/report write failures and -how callers distinguish them from generation or validation failures. +Settle explicit artifact-file output and its interaction with report selection +and standard verbosity controls. Quiet mode suppresses CommandKit output but +does not cancel execution; application-owned file effects need an explicit +design. + +Map PromptKit's typed errors and reported outcomes into CommandKit conventions, +preserving its distinction between a completed content check reporting +`ValidationFailed` and an operational error. Select any necessary domain exit +code without reusing the current validation-failure exit 2, which conflicts with +CommandKit's usage convention. Also specify artifact/report delivery failures +using CommandKit's presentation-failure behavior where applicable. These are +adapter mappings, not a new application validation policy. Signal cancellation and the whole-operation deadline remain application responsibilities. Decide their mapping to the CommandKit invocation context