Settle output destination and native verbosity conventions

This commit is contained in:
2026-11-19 17:54:57 +00:00
parent 293374d7a7
commit f31dec61ef

View File

@@ -109,8 +109,9 @@ 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.
inline JSON reporting. The report file's format is JSON independently of the
main result's `--format`; requesting a report does not change the main result's
representation or destination.
Failure to write a requested report is a delivery failure and must produce a
nonzero outcome and diagnostic.
@@ -125,6 +126,33 @@ 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.
### Output destinations and verbosity
Decision recorded 2026-11-19: use `--output PATH` for the main result's file
destination. Without it, the main result goes to stdout. With it, the selected
representation goes to the file without duplicate stdout output. Use the
spelling `--output`, with no legacy `--out` compatibility alias.
`--format` selects the representation independently of the destination:
default/text emits the raw artifact, while JSON/YAML emits the native result
with metadata. The filename does not select the format. `--report PATH` remains
an additional native JSON report, so callers can save the raw artifact and its
report to separate files.
Adopt CommandKit's upstream verbosity and `--quiet` semantics fully, including
mode selection, message visibility, rendering, and presentation failures. Do
not add Scriptorium-specific exceptions to normal command-output suppression.
Quiet mode does not cancel generation, and failure explanations remain visible
through the native diagnostic channel.
Explicitly requested `--output` and `--report` writes are application-owned file
operations and still occur in quiet mode. Render those files through CommandKit's
writer API; the invocation reporter governs console output. This follows the
upstream distinction between reporting visibility and application effects.
With quiet mode and no requested files, generation still runs while ordinary
result output is suppressed. The [upstream reporting contract][upstream-cli]
owns the shared verbosity rules.
## Upstream baseline
The initial review covered CommandKit **v0.7.0**, ckconfig **v0.9.0**, and
@@ -150,15 +178,11 @@ not requirements to reproduce during migration.
## Open decisions
### 1 Generation output and process outcomes
### 1 Generation integration details
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
does not cancel execution; application-owned file effects need an explicit
design.
The consumer requirements, native result reporting, output destinations, and
verbosity decisions above are settled. The remaining work is to specify their
integration in the feature roadmap.
Map PromptKit's typed errors and reported outcomes into CommandKit conventions,
preserving its distinction between a completed content check reporting