Record generation output and subprocess requirements
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user