Record diagnostics and invocation lifecycle decisions

This commit is contained in:
2026-11-19 18:09:17 +00:00
parent d83c5f0062
commit 3868822277

View File

@@ -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