Record generation output and subprocess requirements

This commit is contained in:
2026-11-19 16:11:00 +00:00
parent 3f5e441756
commit b3a0a73416

View File

@@ -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 three capabilities is settled. Prepared-request preview and the future of
`render` remain a separate discussion below. `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 ## Upstream baseline
The initial review covered CommandKit **v0.7.0**, ckconfig **v0.9.0**, and 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 ### 1 Generation output and process outcomes
The starting proposal is to keep generated artifact bytes easy to consume, The consumer requirements above are settled. The proposed native composition is
with execution metadata separately available. CommandKit supports both raw a CommandKit `Report` whose value is PromptKit's `RunResult`, with a text
output and structured reports; using it does not require wrapping generated template that emits only generated content. Default/text output would serve
artifacts in a report envelope. 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, PromptKit's `RunResult` includes content, validation, selected resources, usage,
execution-report delivery, and how those choices interact with standard format and timing. Operational failures return no partial `RunResult`; observer events
and verbosity controls. In particular, quiet mode suppresses CommandKit output separately expose terminal metadata, retry counts, and presence-aware usage.
but does not cancel execution; application-owned file effects need an explicit Do not invent an empty or synthetic success result to represent a failure.
design. Ordinary diagnostics should follow upstream reporting conventions. 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 Settle explicit artifact-file output and its interaction with report selection
generated-output validation failure as an application domain outcome. The and standard verbosity controls. Quiet mode suppresses CommandKit output but
current use of exit 2 for that failure conflicts with CommandKit's usage and does not cancel execution; application-owned file effects need an explicit
invalid-configuration convention. Also settle output/report write failures and design.
how callers distinguish them from generation or validation failures.
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 Signal cancellation and the whole-operation deadline remain application
responsibilities. Decide their mapping to the CommandKit invocation context responsibilities. Decide their mapping to the CommandKit invocation context