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
`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