From d83c5f0062337488fc6d7604e167886749125e4b Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 19 Nov 2026 17:50:25 +0000 Subject: [PATCH] Record agreed CommandKit reporting decisions --- docs/roadmap/commandkit-notepad.md | 70 ++++++++++++++++++++++++------ 1 file changed, 57 insertions(+), 13 deletions(-) diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md index 5ed23d0..4781e68 100644 --- a/docs/roadmap/commandkit-notepad.md +++ b/docs/roadmap/commandkit-notepad.md @@ -268,6 +268,52 @@ typed-secret handling and normal configuration validation. Safe inspection, diagnostics, and persistence remain separate output responsibilities; they do not justify additional restrictions on which fields may be overridden. +### Reports and machine-readable output + +Use CommandKit's native reporting system throughout. Produce one structured +result per invocation where the command has a meaningful result, keeping +progress and diagnostics separate. Standard ckconfig commands retain their +native report shapes; Narratio defines report values for its domain operations. + +| Command family | Report content | +| --- | --- | +| `run`, `regenerate-artifacts` | Campaign/session identity, selected stages, execution or reuse outcomes, generated artifacts, and completion status | +| `session plan` | Selected stages, planned execution/reuse decisions and reasons, artifact targets, and prerequisites | +| `session status` | Local stage state and available remote publication information | +| Artifact catalogs | Source identities, producers, dependencies, and session-specific availability/publication where applicable | +| `session validate` | Overall outcome and individual findings | +| `session restore`, `session clean` | Planned or completed actions, conflicts, and dry-run status | +| Session initialization and lock mutations | Concise confirmation identifying the affected session, destination, or lock | + +Support native `--format text|yaml|json` conventions. Start with native automatic +presentation, including YAML for structured values. Add a custom text template +only when representative output demonstrates a substantial readability benefit. +The template presents the same report value rather than a separate information +model; recreating the existing handwritten text output is not a goal. + +Long-running operations emit progress through the diagnostic channel and their +final report through the result channel, allowing JSON results to be captured +without progress mixed into the document. A streaming JSON event protocol is +deferred as a separate interface. + +When execution stops after meaningful domain work, report what completed and +where work stopped alongside the failed command outcome. Preserve the success +of earlier durable work. Failures before meaningful domain work, such as invalid +arguments, need only the native error; do not manufacture an empty run report. +Report-delivery failure follows CommandKit's native handling and does not undo +completed pipeline work. + +Define public report values separately from internal structs and durable +manifests. Expose information useful to operators and callers without making +the entire internal state or manifest schema the CLI contract. Document +application-owned report fields as a public interface. An additional schema +version mechanism is not part of the initial design; review native report +changes during dependency upgrades. + +`--format` controls the command report, not the format of generated artifacts. +For example, session initialization still writes its YAML configuration when +the confirmation report uses JSON. + ## Reviewed upstream baseline The initial review covered these released modules: @@ -295,19 +341,6 @@ baseline. They remain current-behavior documents until the migration lands. ## Open decisions -### Reports and machine-readable output - -Design useful report values for planning, status, artifact inventories, -validation, restore, cleanup, and execution summaries. Apply native text, YAML, -and JSON presentation consistently. Decide where a text template improves -operator readability and where native structured presentation is sufficient. - -CommandKit does not transform raw application output into structured reports. -Identify any output that genuinely needs raw bytes and distinguish final -results from diagnostic/progress messages. Decide what stability Narratio will -promise for application-owned report fields; do not accidentally make durable -manifest schemas the CLI response contract. - ### Diagnostics and invocation lifecycle Classify existing messages into CommandKit's result, failure, warning, @@ -398,6 +431,17 @@ native overrides and resolution; they do not make identity fields immutable. Credential overrides use native typed-secret handling. Safe output and persistence do not impose additional override restrictions. +### 2026-11-19 — Reporting agreed + +Accepted native structured reporting with one meaningful result document per +invocation, separate diagnostics/progress, and native ckconfig report shapes. +Custom text templates require a demonstrated readability benefit. Domain +reports describe partial execution on failure without undoing durable work; +early failures need no empty report. Report models remain separate from +manifests and generated artifact formats, with documented public fields and no +additional schema version mechanism initially. Streaming JSON events remain +deferred. Diagnostics and invocation lifecycle are the next discussion topic. + ### Continuing the discussion For each topic, record the question, the agreed outcome, its rationale, and any