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
|
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
|
||||||
|
|||||||
Reference in New Issue
Block a user