Plan invocation reporting implementation

docs/roadmap/reporting.md

@@ -13,6 +13,8 @@ below are also selected. Architectural preparation is complete:
 [ADR 0014](../adr/0014-invocation-reporting.md) is accepted, and the
 [architecture policy](../policy/architecture.md) is aligned. Implementation has
 not started; implementation, validation, and maintained consumer examples remain.
+The [implementation plan](implementation.md) owns stage order and execution
+instructions.
 
 ## Purpose
 
@@ -850,85 +852,30 @@ 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
+## Delivery scope
 
-1. Specify the selected behavior in examples covering ordinary application output,
-   immediate and deferred diagnostics, failure after partial output, help and
-   version, and integration diagnostics in every mode. Include applications that
-   emit no Progress messages and the distinction between Info and Progress.
-   Cover silent recovery, an explicit Warning with or without a Go error, and a
-   terminal failure with an explicit explanation and no Go error cause.
-   Include simple and structured failure construction without early emission,
-   optional cause transport independent of operator text, and an integration
-   returning both a substantive report and a failure. Include provider-returned
-   independent warnings and terminal context, unexplained failures receiving the
-   fallback, and rendering helpers using only the supplied callback writer.
-2. Review current diagnostic batching, parsing, help, outcome presentation, and
-   writer ownership to identify the smallest shared changes. Include invocation
-   failures that occur before a handler receives its `Invocation`.
-3. Implement the selected unified reporting API and flag contracts, including
-   interactions with command and flag aliases, following OD-1 through OD-4 above.
-   Replace split handler submission paths and adapt core and integration callers.
-   Account for 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.
-   Adapt provider-returned `Acquired[T]`, `Diagnostic`, and `Severity` contracts
-   to independent nonterminal messages and separate terminal explanations.
-   Replace whole-batch severity promotion with deliberate separation of failure
-   context and unrelated messages. Providers remain independent of the reporter.
-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. Cover explicit explanatory
-   context in quiet mode, independent warnings in mixed batches, already-labelled
-   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. Cover immediate and deferred
-   ordering on success and failure, handler cleanup, automatic finalization,
-   flushing ordinary buffers before terminal delivery, handler-completion debug
-   placement, and ownership of caller-supplied writers. Verify concurrent reporter
-   calls protect shared state and keep individual messages together, without
-   requiring a predetermined order among concurrent submissions. Verify ignored
-   immediate write errors and deferred delivery failures follow the outcome table
-   above, original explanations and causes are retained, and failed destinations
-   receive no further writes. Cover diagnostic-destination failure without
-   fallback into substantive output, quiet-mode rendering failures, and
-   suppression without destination writes or incomplete-delivery status.
-   Distinguish renderer failures from destination failures, including callbacks
-   that fail without writing and continued terminal delivery through a healthy
-   diagnostic destination. Cover usage failure becoming operational failure when
-   presentation fails, domain classification and non-zero status preservation,
-   and zero domain status becoming `1`. Verify all category destinations and
-   usage guidance under quiet mode.
-   Verify the selected API's empty-heading native rendering, ordered details,
-   deferred submission errors, replacement by `WithExplanation`, and delivery
-   states for each destination. Check bounded first-error observations, rendering
-   through `RenderOutput`, and `ErrReporterClosed` for retained handles in quiet mode.
-   Verify `WithCause` preserves classification, status, and explanation, and
-   `WithExplanation` preserves the cause. Check cause identity through outcome
-   processing and subsequent presentation failures, including wrapped errors
-   inspected with `errors.Is` and `errors.As`. Verify causes alone do not produce
-   messages or change statuses or visibility.
-   Verify provider-returned data remains unpresented until submitted by the
-   integration, including data returned alongside an error. Cover mixed batches
-   where terminal context remains visible in quiet mode and unrelated warnings
-   remain suppressed. Verify generic fallback presentation and retention for
-   failed outcomes with no message or non-nil detail renderer, with and without
-   a cause. Check unchanged classifications, statuses, and causes when fallback
-   delivery succeeds, and existing presentation-failure rules when it fails.
-   Cover native details with an empty heading, including a renderer that writes
-   no bytes, without adding a fallback or replaying callbacks to inspect content.
-   Exercise callback helpers using the supplied writer, messages submitted before
-   and after rendering, and ordinary concurrent submissions serialized around a
-   complete rendering operation. Document the callback boundary without requiring
-   runtime detection of recursive reporter use.
-6. Update GoDoc, the CLI reference, consumer guidance, and release documentation
-   when implemented. Exact reporting APIs and flag syntax remain API/CLI
-   contracts.
+The completed feature includes the selected reporter and outcome API, ordered
+mode/progress selection through normal parsing, shared core presentation, and
+both optional integration migrations. Passive provider diagnostics distinguish
+independent messages from terminal explanations while preserving native evidence
+and rendering. Existing command behavior remains unchanged outside the selected
+reporting policy.
+
+Maintained consumers demonstrate ordinary output, immediate/deferred messages,
+silent recovery, explicit warnings, failure after partial output, optional cause
+transport, and structured terminal explanations. Integration consumers include
+native diagnostic context and useful reports returned alongside failures.
+
+Behavioral coverage establishes CommandKit-owned parsing, visibility, ordering,
+concurrent reporter coordination, closure, presentation observations, and failure
+handling. It preserves existing alias, input/state, discovery, native-report,
+and upstream-adapter protections without testing upstream domain correctness.
+GoDoc, CLI documentation, consumer guidance, internal documentation, and release
+notes describe the implemented boundary under their canonical ownership.
+
+The [implementation plan](implementation.md) defines the concrete migration
+steps, focused validation, and completion criteria. This roadmap defines the
+target behavior and selected policy choices.
 
 ## Architectural preparation completed
 
@@ -939,5 +886,6 @@ rules.
   ownership model, including application ownership of domain-specific error
   decisions and scope for useful shared error helpers.
 
-OD-1 through OD-4 and the consumer API signatures are selected. Turn the target-API
-examples into maintained, executable consumers as implementation proceeds.
+OD-1 through OD-4 and the consumer API signatures are selected. The target end
+state includes maintained, executable consumers using those APIs; the
+[implementation plan](implementation.md) owns their delivery sequence.