Record agreed CommandKit reporting decisions

This commit is contained in:
2026-11-19 17:50:25 +00:00
parent 981eb6be8f
commit d83c5f0062

View File

@@ -268,6 +268,52 @@ typed-secret handling and normal configuration validation. Safe inspection,
diagnostics, and persistence remain separate output responsibilities; they do diagnostics, and persistence remain separate output responsibilities; they do
not justify additional restrictions on which fields may be overridden. 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 ## Reviewed upstream baseline
The initial review covered these released modules: The initial review covered these released modules:
@@ -295,19 +341,6 @@ baseline. They remain current-behavior documents until the migration lands.
## Open decisions ## 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 ### Diagnostics and invocation lifecycle
Classify existing messages into CommandKit's result, failure, warning, 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 Credential overrides use native typed-secret handling. Safe output and
persistence do not impose additional override restrictions. 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 ### Continuing the discussion
For each topic, record the question, the agreed outcome, its rationale, and any For each topic, record the question, the agreed outcome, its rationale, and any