Expand reporting categories and define failure-bound errors

docs/roadmap/reporting.md

@@ -1,15 +1,16 @@
 # Output policy and invocation reporting
 
-Status: initial planning. The three output modes and uniform treatment of help
-and version are selected. Consumer API, flag details, and delivery mechanics
-remain open. Implementation has not started.
+Status: initial planning. Message categories, the quiet/default/verbose output
+policy, and uniform treatment of help and version are selected. A debug mode
+extends the proposed hierarchy. Consumer API, flag details, and delivery
+mechanics remain open. Implementation has not started.
 
 ## Purpose
 
-Provide consistent handling of `--quiet` and `--verbose` across application
-commands and optional integrations. Reduce repeated output classification,
-diagnostic presentation, and delivery bookkeeping where CommandKit can provide
-a meaningful benefit.
+Provide consistent handling of `--quiet`, `--verbose`, and the proposed
+`--debug` mode across application commands and optional integrations. Reduce
+repeated output classification, diagnostic presentation, and delivery bookkeeping
+where CommandKit can provide a meaningful benefit.
 
 Ordinary Go writers and formatting functions already make application output
 straightforward. Design reporting conveniences around the shared output policy
@@ -36,22 +37,42 @@ CommandKit diagnostics while preserving native rendering and source context.
 Some adapters wrap multiple records in one diagnostic writer and classify the
 batch by its highest severity. This matters when designing selective visibility.
 
-There is currently no shared quiet/verbose policy or invocation reporter API.
+There is currently no shared verbosity policy or invocation reporter API.
 
 ## Selected output policy
 
-The operator chooses among quiet, ordinary, and verbose presentation:
+Distinguish substantive application output from diagnostic message categories:
 
-| Output category | `--quiet` | No flag | `--verbose` |
-| --- | --- | --- | --- |
-| Substantive application output | Suppressed | Shown | Shown |
-| Warnings and informational messages | Suppressed | Suppressed | Shown |
-| Error diagnostics for a failed run | Shown | Shown | Shown |
+- **Substantive output (Normal):** The requested report or command result.
+- **Error:** The invocation failed and will return a non-zero status code.
+- **Warning:** Something went wrong or deserves attention, but the invocation
+  can still succeed. A recovered problem is a warning.
+- **Info:** Progress or useful explanation, including completion messages.
+- **Debug:** Troubleshooting detail, including intermediate decisions and
+  execution-path information.
 
-Substantive output includes requested reports and command results. Progress and
-completion chatter are informational messages. The category of a message
-determines its visibility; stream destination alone cannot distinguish a
-warning from an error.
+Quiet, ordinary, and verbose presentation follow the selected policy. The
+proposed debug mode adds troubleshooting detail to verbose output:
+
+| Output category | `--quiet` | No flag | `--verbose` | `--debug` (proposed) |
+| --- | --- | --- | --- | --- |
+| Substantive application output | Suppressed | Shown | Shown | Shown |
+| Error | Shown | Shown | Shown | Shown |
+| Warning | Suppressed | Suppressed | Shown | Shown |
+| Info | Suppressed | Suppressed | Shown | Shown |
+| Debug | Suppressed | Suppressed | Suppressed | Shown |
+
+Info belongs in verbose mode; debug includes verbose messages. Normal output
+remains a substantive result category, separate from diagnostic severity.
+The category of a message determines its visibility; stream destination alone
+cannot distinguish a warning from an error.
+
+Error presentation is tied to invocation failure. Prefer deriving error
+diagnostics from a failed outcome, which may carry detailed explanations. Avoid
+an unrestricted `Error(...)` reporting method that permits an error message
+followed by a successful outcome. The application still controls process exit
+under the existing outcome contract; the returned outcome must consistently
+represent the failure and its non-zero status.
 
 Apply the same policy to help and version. There are no command-specific
 exceptions for successful output:
@@ -69,10 +90,10 @@ diagnostic delivery.
 
 ### Flag and invocation behavior
 
-Model quiet, ordinary, and verbose as mutually exclusive presentation modes.
-The proposed rule when both flags occur is last occurrence wins, consistent
-with existing repetition conventions. Exact boolean forms, resets, short
-spellings, placement, and collision handling remain to be specified.
+Model quiet, ordinary, verbose, and debug as mutually exclusive presentation
+modes. The proposed rule when multiple mode flags occur is last occurrence wins,
+consistent with existing repetition conventions. Exact boolean forms, resets,
+short spellings, placement, and collision handling remain to be specified.
 
 Keep verbosity a presentation choice: a quiet invocation still performs its
 requested operation and returns the ordinary outcome. Apply the policy through
@@ -81,9 +102,9 @@ streams or external destinations remains application-owned.
 
 ### Streaming and failure diagnostics
 
-The proposed approach applies visibility when output is emitted. A verbose run
-may show progress before subsequently failing, and an ordinary run may write
-part of its substantive output before failing. Previously written bytes cannot
+The proposed approach applies visibility when output is emitted. A verbose or
+debug run may show progress before subsequently failing, and an ordinary run may
+write part of its substantive output before failing. Previously written bytes cannot
 be withdrawn. Whole-run buffering solely to make failed runs contain only error
 output is not part of the proposed direction.
 
@@ -99,7 +120,9 @@ An invocation-scoped facility could classify messages, coordinate immediate and
 end-of-handler presentation, and retain delivery failures. Earlier illustrative
 API shapes included `inv.Reporter()`, `Info`, `Warn`, `Diagnostic`, and an
 `AtEnd()` view. These names and shapes are exploratory, not selected contracts.
-Reassess the necessary API around the output modes before adopting them.
+Reassess the necessary API around the output modes and expanded message
+categories before adopting them. Debug messages need a corresponding
+classification; its exact API remains open.
 
 Continue to support standard `io.Writer` usage for report bodies and native
 report writers. Reuse existing diagnostic and outcome concepts where practical.
@@ -107,9 +130,9 @@ Any reporting facility should coordinate with returned `Outcome.Diagnostics`
 and operation causes so already-presented messages are not repeated.
 
 Whether reporting methods return write errors, retain them for finalization,
-or expose an explicit delivery-error accessor remains open. Emitting an
-error-severity message and deciding the operation's outcome need clearly
-defined responsibilities.
+or expose an explicit delivery-error accessor remains open. The API must enforce
+the selected relationship between Error diagnostics and failed outcomes,
+including diagnostics supplied through generic or existing entry points.
 
 ### Upstream diagnostic ownership
 
@@ -123,6 +146,10 @@ already exists or prescribe its upstream shape. Preserve useful native
 diagnostic detail and supported error identity, and coordinate returned errors
 with diagnostics that already explain them.
 
+Debug output follows the same upstream disclosure and safe-rendering contracts.
+Enabling debug does not authorize secret disclosure or bypass owning-library
+rules.
+
 ## Work needed
 
 1. Settle the open decisions with examples covering ordinary application output,
@@ -136,8 +163,9 @@ with diagnostics that already explain them.
 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,
-   ordering, duplicate prevention, and write-failure handling with focused
-   behavioral tests and maintained consumer examples.
+   ordering, duplicate prevention, Error/non-zero-outcome consistency, debug
+   visibility, and write-failure handling with focused behavioral tests and
+   maintained consumer examples.
 6. Update GoDoc, the CLI reference, consumer guidance, and release documentation
    when implemented. Review whether any resulting architectural change needs an
    ADR; exact reporting APIs and flag syntax remain API/CLI contracts.
@@ -146,23 +174,26 @@ with diagnostics that already explain them.
 
 ### OD-1: Flag grammar and scope
 
-How are quiet and verbose selected, repeated, combined, or explicitly reset?
-Are short spellings built in? Where may the flags appear, including on help
+How are quiet, verbose, and debug selected, repeated, combined, or explicitly
+reset? Are short spellings built in? Where may the flags appear, including on help
 requests? How are canonical and alias spelling collisions handled, and how is
 the mode determined for invocations that fail during routing or parsing?
 
 ### OD-2: Consumer API and output classification
 
-What is the smallest API for substantive output, informational messages,
-warnings, and errors? How do direct writes through `Invocation.Streams` interact
-with it? How can helpers report through the same invocation? Is a dedicated
-immediate/deferred reporter needed, and how does it compose with existing
+What is the smallest API for substantive output, debug and informational
+messages, warnings, and failure diagnostics? How do direct writes through
+`Invocation.Streams` interact with it? How can helpers report through the same
+invocation? Is a dedicated immediate/deferred reporter needed, and how does it compose with existing
 outcome diagnostics?
 
 ### OD-3: Failure presentation and diagnostic retention
 
-What identifies an error that must be shown, particularly for application domain
-outcomes and error-severity diagnostics accompanying a successful outcome?
+How does the API enforce that Error diagnostics accompany a failed invocation
+with a non-zero status, including application domain outcomes? How should
+inconsistent caller-supplied combinations be handled through existing diagnostic
+and outcome APIs? How are recovered upstream problems represented as warnings
+while preserving their native context?
 Which contextual records belong to an error explanation? How are mixed upstream
 diagnostic batches filtered while preserving useful native rendering? What is
 retained when presentation is suppressed, and how is duplicate presentation