Record agreed CommandKit reporting decisions
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user