From f31dec61ef69a0dc3714ac0582ef219ca239842e Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 19 Nov 2026 17:54:57 +0000 Subject: [PATCH] Settle output destination and native verbosity conventions --- docs/roadmap/commandkit-notepad.md | 44 +++++++++++++++++++++++------- 1 file changed, 34 insertions(+), 10 deletions(-) diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md index 47e9ea7..cdb7990 100644 --- a/docs/roadmap/commandkit-notepad.md +++ b/docs/roadmap/commandkit-notepad.md @@ -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