From 3868822277cd087ca3b78c4d959b34d5c40a8357 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 19 Nov 2026 18:09:17 +0000 Subject: [PATCH] Record diagnostics and invocation lifecycle decisions --- docs/roadmap/commandkit-notepad.md | 96 ++++++++++++++++++++++++------ 1 file changed, 78 insertions(+), 18 deletions(-) diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md index 4781e68..3263364 100644 --- a/docs/roadmap/commandkit-notepad.md +++ b/docs/roadmap/commandkit-notepad.md @@ -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