From 293374d7a771ae05e70f3760bfa8d3b9367185bb Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 19 Nov 2026 16:20:45 +0000 Subject: [PATCH] Record native result and report file decisions --- docs/roadmap/commandkit-notepad.md | 48 +++++++++++++++++++----------- 1 file changed, 30 insertions(+), 18 deletions(-) diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md index f2d1efd..47e9ea7 100644 --- a/docs/roadmap/commandkit-notepad.md +++ b/docs/roadmap/commandkit-notepad.md @@ -84,9 +84,7 @@ three capabilities is settled. Prepared-request preview and the future of 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. +optional and available through the native result reporting choices below. Prefer native CommandKit reporting and PromptKit result types before introducing a Scriptorium-specific response format. A failure must produce a nonzero process @@ -100,6 +98,33 @@ 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. +### Native result reporting and separate report files + +Decision recorded 2026-11-19: use a CommandKit `Report` containing PromptKit's +native `RunResult`, with a text template that emits only generated content. +Default/text output serves artifact consumers; standard JSON/YAML formats expose +the native result and its metadata. This composes existing upstream APIs; +ckprompt does not supply a general generation command or prescribe this template. + +Include an optional `--report PATH` flag requiring an explicit file destination. +Omitting it creates no separate report file. When requested, save the native +result as JSON through CommandKit's renderer, using the same representation as +inline JSON reporting. The report file's format is JSON independently of stdout's +`--format`; requesting a file does not change the normal stdout selection. +Failure to write a requested report is a delivery failure and must produce a +nonzero outcome and diagnostic. + +Do not include a configured reporting directory or automatic report collection +in the initial migration. The caller selects the report path and manages its +lifecycle. A configured directory may be considered later if automatic +collection becomes useful; an explicit report path would take precedence. + +Native result reports are available when PromptKit returns a result. Operational +failures produce a nonzero exit and native diagnostics. This follows PromptKit's +capabilities and is the intended boundary, not a gap for Scriptorium to address. +Do not synthesize replacement results or add an alternative failure-report +format to compensate for the absence of a native result. + ## Upstream baseline The initial review covered CommandKit **v0.7.0**, ckconfig **v0.9.0**, and @@ -127,21 +152,8 @@ not requirements to reproduce during migration. ### 1 Generation output and process outcomes -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. - -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. +The consumer requirements, native result reporting, and separate report-file +design above are settled. Settle explicit artifact-file output and its interaction with report selection and standard verbosity controls. Quiet mode suppresses CommandKit output but