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
|
||||
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
|
||||
|
||||
The initial review covered these released modules:
|
||||
@@ -341,24 +408,6 @@ baseline. They remain current-behavior documents until the migration lands.
|
||||
|
||||
## 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
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
For each topic, record the question, the agreed outcome, its rationale, and any
|
||||
|
||||
Reference in New Issue
Block a user