Settle failure presentation and reporting retention boundaries

docs/roadmap/reporting.md

@@ -5,8 +5,9 @@ treatment of help and version, message prefixes, and OD-1's flag grammar and
 scope (including independent Progress control) are selected.
 OD-2's unified reporting direction, the terminal failure model, and application
 ownership of error handling are selected.
-Exact API signatures, failure explanation details, retention, and delivery
+OD-3's failure presentation and retention boundaries are selected.
-mechanics remain open. Implementation has not started.
+Exact API signatures and OD-4's delivery mechanics remain open.
+Implementation has not started.
 
 ## Purpose
 
@@ -34,9 +35,9 @@ the application supplies a non-zero outcome and an operator-facing explanation.
 Reporting does not require the underlying Go error or undertake its tracking,
 recovery, or identity preservation.
 
-A convenience helper that explicitly presents `err.Error()` as a Warning could
+Applications can explicitly present `err.Error()` as a Warning through the
-fit this boundary. Such a helper would only convert the supplied error to a
+ordinary message API, illustrated by `report.Warn(err.Error())`. Defer a separate
-message at the application's request; its inclusion and signature remain open.
+`WarnError` convenience helper; this conversion already requires little code.
 
 CommandKit retains responsibility for handling its own errors, including
 routing, parsing, and reporting failures. Integration-owned commands similarly
@@ -125,9 +126,9 @@ For multiline diagnostics, prefix the opening line and preserve the structured
 detail. Integration adapters coordinate native diagnostic rendering to avoid
 duplicate severity labels or loss of upstream formatting.
 
-Streaming Progress messages use the diagnostic channel so they do not corrupt
+Initially, Progress messages are unprefixed streamed lines. They use the
-substantive output such as JSON or YAML. Progress presentation details remain
+diagnostic channel so they do not corrupt substantive output such as JSON or
-part of the consumer API and delivery design below.
+YAML. Terminal redraw and progress-bar behavior are outside this implementation.
 
 ### Terminal failure model
 
@@ -149,7 +150,7 @@ continue, the handler returns a non-zero outcome with an explicit explanation
 such as "Unable to export the requested report." The application can choose to
 include detail from a Go error in that explanation. CommandKit presents the
 supplied explanation without automatically deriving text from an application
-error. The exact failure-construction API remains open under OD-3.
+error. Exact API names and signatures remain to be finalized.
 
 Output streamed before the failure remains visible according to its selected
 mode; terminal failure does not withdraw earlier bytes. Deferred messages,
@@ -157,6 +158,36 @@ cleanup writes, and delivery failures must respect the end of normal reporting.
 Their finalization and late-write behavior remain OD-4 details. A terminal
 failure may have multiple explanatory records, all belonging to that failure.
 
+### Failure explanations and presentation ownership (OD-3)
+
+Make a non-zero outcome with an explicit message the convenient failure path.
+Support structured explanations, including multiple records, through the same
+presentation facility for richer application and integration reports. Neither
+form requires an underlying Go error.
+
+The application or integration explicitly identifies the context belonging to
+a terminal explanation. Present that context with the failure in every mode,
+including quiet. Independent warnings and other messages retain their own
+visibility rules. For mixed upstream batches, adapters preserve useful native
+rendering while distinguishing terminal explanatory context from independent
+messages. Core does not infer those relationships from error chains or text.
+
+Assign each submitted message one presentation path. Returning a terminal
+explanation schedules its presentation once; core does not append another
+message derived from an application error cause. Native renderers can supply
+already-labelled content without receiving duplicate prefixes. Avoid text-based
+deduplication: separate events may legitimately produce identical messages.
+
+### Retention boundary (OD-3)
+
+CommandKit provides invocation-scoped CLI presentation. Logging and message
+history collection remain application concerns. Keep terminal explanations with
+the returned outcome, and keep the temporary state needed for deferred delivery,
+parser events awaiting mode selection, and delivery bookkeeping. The reporting
+facility does not collect a transcript or retain other emitted or suppressed
+messages for later inspection. No optional message-history facility is planned
+for this implementation.
+
 ## Selected flag grammar and scope
 
 ### Mode selection and resets
@@ -316,9 +347,8 @@ output is not part of the proposed direction.
 
 Keep errors understandable in every mode, including source locations and
 related explanatory context. Unrelated warnings and informational messages
-remain subject to the selected mode. Whether to retain submitted messages for
+remain subject to the selected mode. Apply the selected retention boundary
-programmatic inspection, including suppressed messages, remains open under
+without accumulating a message history.
-OD-3. This concerns presentation records, not application error tracking.
 
 ## Selected consumer reporting API direction
 
@@ -358,10 +388,10 @@ explicit status and presentation content; they do not require a Go error cause.
 
 Use the reporter as the common diagnostic submission path, replacing the earlier
 proposal to split submission between a reporter and `Outcome.Diagnostics`.
-Whether the execution result exposes retained diagnostic observations is an
+The returned outcome carries terminal explanations, with other retention limited
-OD-3 decision, separate from how handlers submit messages. Caller-selected
+to the presentation needs described above. Caller-selected destinations belong
-destinations belong at the execution boundary; the handler-facing API routes
+at the execution boundary; the handler-facing API routes output through the
-output through the reporter instead of requiring a parallel raw-stream API.
+reporter instead of requiring a parallel raw-stream API.
 
 Whether reporting methods return write errors, retain them for finalization,
 or expose an explicit delivery-error accessor remains open under OD-4. Standard
@@ -404,16 +434,18 @@ rules.
    flag collisions and document changed public contracts.
 4. Implement the selected behavior across core and the integrations. Preserve
    upstream rendering and semantics while applying the chosen visibility policy.
-5. Verify classification, flag selection, suppression, retained diagnostics,
+5. Verify classification, flag selection, suppression, terminal explanations,
    ordering, duplicate prevention, terminal Error/non-zero-outcome consistency, debug
    visibility, and write-failure handling with focused behavioral tests and
    maintained consumer examples. Cover mode resets, mixed canonical/alias
    ordering, help and discovery contexts, and core parser events presented
    according to the final mode. Cover explicit progress overrides, debug's
    progress default, quiet suppression, progress aliases, message prefixes,
-   and preservation of native multiline diagnostics. Verify the end of normal
+   and preservation of native multiline diagnostics. Cover explicit explanatory
-   reporting after terminal error presentation, including deferred and late
+   context in quiet mode, independent warnings in mixed batches, already-labelled
-   writes under the selected OD-4 behavior.
+   native content, and distinct submissions with identical text. Verify the end
+   of normal reporting after terminal error presentation, including deferred
+   and late writes under the selected OD-4 behavior.
 6. Update GoDoc, the CLI reference, consumer guidance, and release documentation
    when implemented. Reconcile the selected error-handling boundary with
    ADR 0005's existing outcome and error-identity commitments before changing
@@ -422,27 +454,6 @@ rules.
 
 ## Open Decisions
 
-### OD-3: Failure presentation and diagnostic retention
-
-The terminal failure model and application error-handling boundary are selected
-above. The remaining questions concern explicit presentation content:
-
-- How does a handler supply a non-zero outcome with a simple explanation or
-  multiple structured explanatory records, including application domain failures?
-- How do callers and integration adapters identify the context belonging to a
-  terminal explanation, and present mixed diagnostic batches while preserving
-  useful native rendering and applying visibility to independent messages?
-- Which submitted messages, if any, are retained for programmatic inspection,
-  including when suppressed? How is that observation exposed separately from
-  message submission?
-- How is duplicate presentation avoided, and how do adapters apply prefixes to
-  mixed or already-labelled native diagnostics?
-- What presentation should streaming Progress use? Is a convenience helper for
-  explicitly presenting `err.Error()` as a Warning useful enough to include?
-
-Application error classification, recovery, and cause tracking are outside
-these questions. Delivery failures produced by reporting remain under OD-4.
-
 ### OD-4: Delivery lifecycle and quiet execution
 
 How are immediate and deferred messages ordered and finalized, including when
@@ -453,6 +464,5 @@ delivery state represents intentional suppression? Does quiet mode discard
 rendered bytes or skip report rendering, and how does that choice preserve
 operation semantics and failure detection? Which streaming behavior becomes
 part of the public contract?
-Are initial Progress messages ordinary streamed lines, or is terminal redraw
+How do Progress delivery failures interact with other messages? Progress uses
-behavior needed? How do progress delivery failures and retention interact with
+the selected streamed-line presentation and shared retention boundary.
-other messages? No progress-bar, redraw, or terminal-specific API is selected yet.