Record diagnostics and invocation lifecycle decisions
This commit is contained in:
@@ -314,6 +314,73 @@ changes during dependency upgrades.
|
|||||||
For example, session initialization still writes its YAML configuration when
|
For example, session initialization still writes its YAML configuration when
|
||||||
the confirmation report uses JSON.
|
the confirmation report uses JSON.
|
||||||
|
|
||||||
|
### Diagnostics and invocation lifecycle
|
||||||
|
|
||||||
|
Adopt CommandKit's native visibility rules. Ordinary mode shows results and
|
||||||
|
failures; warnings and information require verbose/debug mode. Progress requires
|
||||||
|
`--progress` or debug mode. Quiet suppresses successful results and progress
|
||||||
|
while retaining failures. Conditions that materially affect the result also
|
||||||
|
belong in its structured report rather than depending solely on warning
|
||||||
|
visibility.
|
||||||
|
|
||||||
|
Classify Narratio's messages by their purpose:
|
||||||
|
|
||||||
|
| Category | Examples |
|
||||||
|
| --- | --- |
|
||||||
|
| Result | Final execution summary, plan, status, or configuration report |
|
||||||
|
| Failure | Failed stage, invalid configuration, or unavailable required input |
|
||||||
|
| Warning | Recoverable problem worth investigating |
|
||||||
|
| Information | Configuration selection or successful credential-bootstrap summary |
|
||||||
|
| Progress | Stage started/completed, artifact completed, or prior work reused |
|
||||||
|
| Debug | Additional safe acquisition or execution detail |
|
||||||
|
|
||||||
|
CommandKit owns console presentation: results go to stdout and diagnostics and
|
||||||
|
progress go to stderr. Domain operations return results and errors without
|
||||||
|
independently printing duplicate terminal failures at several layers. Preserve
|
||||||
|
downstream stdout/stderr in existing captured diagnostic logs; console output
|
||||||
|
provides concise context and useful log locations instead of automatically
|
||||||
|
replaying downstream output.
|
||||||
|
|
||||||
|
Durable logs and checkpoints retain their own policies. Quiet does not disable
|
||||||
|
logging or persistence. Debug increases diagnostic visibility without
|
||||||
|
automatically enabling downstream prompt-rendering/debug artifacts. Reporting
|
||||||
|
modes do not change pipeline selection, execution, or retention.
|
||||||
|
|
||||||
|
Keep startup lightweight and acquire dependencies only when needed:
|
||||||
|
|
||||||
|
1. Parse the command and validate syntax and input combinations.
|
||||||
|
2. Bootstrap credentials when the operation needs configuration.
|
||||||
|
3. Resolve the required configuration and domain context.
|
||||||
|
4. Acquire execution resources and perform the operation.
|
||||||
|
5. Finalize domain state, release resources, present the result, and return the
|
||||||
|
outcome.
|
||||||
|
|
||||||
|
Help, version, completion, and scope discovery do not bootstrap secrets, load
|
||||||
|
configuration, contact storage, or initialize stage adapters. Configuration-
|
||||||
|
dependent validation happens after loading; syntactic errors fail before it.
|
||||||
|
Session inspection may perform the already-agreed remote reads when needed.
|
||||||
|
|
||||||
|
The process boundary supplies an invocation context canceled by Ctrl-C or
|
||||||
|
termination. Propagate that context through CommandKit and Narratio operations.
|
||||||
|
On cancellation, stop scheduling further work, cancel active operations, and
|
||||||
|
let existing adapters perform their resource/subprocess shutdown. Attempt the
|
||||||
|
appropriate terminal manifest update and release held locks, preserve completed
|
||||||
|
checkpoints, and report meaningful partial results. Report persistence or
|
||||||
|
shutdown errors alongside the originating cancellation. Cancellation does not
|
||||||
|
invoke the pipeline cleanup stage or delete resumable work. Abrupt process
|
||||||
|
death is not guaranteed to permit finalization.
|
||||||
|
|
||||||
|
Use native outcome classification: success is `0`; operational failure,
|
||||||
|
cancellation, and output failure use `1`; invalid invocation or identifiable
|
||||||
|
configuration input uses `2`; `diff --check` uses `3` when differences exist.
|
||||||
|
Use public configuration-error classification support rather than matching
|
||||||
|
error strings. Failure explanations identify the affected operation and useful
|
||||||
|
next steps while retaining underlying error identity for programmatic access.
|
||||||
|
|
||||||
|
Include native completion for command paths, flags, static stage/scope values,
|
||||||
|
and appropriate file/directory selectors. Dynamic campaign and artifact
|
||||||
|
suggestions requiring configuration loading or storage access remain deferred.
|
||||||
|
|
||||||
## Reviewed upstream baseline
|
## Reviewed upstream baseline
|
||||||
|
|
||||||
The initial review covered these released modules:
|
The initial review covered these released modules:
|
||||||
@@ -341,24 +408,6 @@ baseline. They remain current-behavior documents until the migration lands.
|
|||||||
|
|
||||||
## Open decisions
|
## Open decisions
|
||||||
|
|
||||||
### Diagnostics and invocation lifecycle
|
|
||||||
|
|
||||||
Classify existing messages into CommandKit's result, failure, warning,
|
|
||||||
information, progress, and debug categories. Use native visibility rules,
|
|
||||||
including their suppression behavior, and ensure failures communicate the
|
|
||||||
actionable context. Coordinate this with existing durable logs and stage
|
|
||||||
diagnostics so the CLI does not emit duplicate messages.
|
|
||||||
|
|
||||||
Define where configuration acquisition and secrets bootstrap occur so help,
|
|
||||||
version, completion, and invalid syntax do not unnecessarily initialize runtime
|
|
||||||
services. Narratio owns process startup, signal handling, cancellation, and
|
|
||||||
exit; decide how that lifecycle supplies CommandKit invocations while retaining
|
|
||||||
session locking and failure persistence.
|
|
||||||
|
|
||||||
Completion can suggest commands, static values such as stage names, and
|
|
||||||
filesystem paths. Decide which declarations receive those hints; dynamic
|
|
||||||
campaign/artifact discovery would need a separately supported capability.
|
|
||||||
|
|
||||||
### Delivery and migration guidance
|
### Delivery and migration guidance
|
||||||
|
|
||||||
Choose implementation work units that lead to one complete native cutover.
|
Choose implementation work units that lead to one complete native cutover.
|
||||||
@@ -442,6 +491,17 @@ manifests and generated artifact formats, with documented public fields and no
|
|||||||
additional schema version mechanism initially. Streaming JSON events remain
|
additional schema version mechanism initially. Streaming JSON events remain
|
||||||
deferred. Diagnostics and invocation lifecycle are the next discussion topic.
|
deferred. Diagnostics and invocation lifecycle are the next discussion topic.
|
||||||
|
|
||||||
|
### 2026-11-19 — Diagnostics and invocation lifecycle agreed
|
||||||
|
|
||||||
|
Accepted native diagnostic categories, visibility, and outcome classification,
|
||||||
|
with CommandKit owning console presentation separately from durable logs.
|
||||||
|
Startup acquires only the resources needed by the selected operation. Process
|
||||||
|
signals cancel the invocation context, preserving completed checkpoints and
|
||||||
|
allowing ordinary terminal persistence and lock release without triggering
|
||||||
|
pipeline cleanup. Accepted static and filesystem completion, with dynamic
|
||||||
|
campaign/artifact suggestions deferred. Delivery and migration guidance remain
|
||||||
|
open.
|
||||||
|
|
||||||
### 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