Record native result and report file decisions

This commit is contained in:
2026-11-19 16:20:45 +00:00
parent b3a0a73416
commit 293374d7a7

View File

@@ -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 Decision recorded 2026-11-19: optimize the default generation response for the
majority of consumers, who want only the raw resulting artifact. Metadata is 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 optional and available through the native result reporting choices below.
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 Prefer native CommandKit reporting and PromptKit result types before introducing
a Scriptorium-specific response format. A failure must produce a nonzero process 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 failure semantics. Adapting those outcomes to CommandKit and process exit codes
is application work; deciding what constitutes a PromptKit failure is not. 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 ## 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
@@ -127,21 +152,8 @@ not requirements to reproduce during migration.
### 1 Generation output and process outcomes ### 1 Generation output and process outcomes
The consumer requirements above are settled. The proposed native composition is The consumer requirements, native result reporting, and separate report-file
a CommandKit `Report` whose value is PromptKit's `RunResult`, with a text design above are settled.
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.
Settle explicit artifact-file output and its interaction with report selection Settle explicit artifact-file output and its interaction with report selection
and standard verbosity controls. Quiet mode suppresses CommandKit output but and standard verbosity controls. Quiet mode suppresses CommandKit output but