Consolidate and renumber architectural decision records

docs/adr/0006-invocation-reporting.md

@@ -0,0 +1,78 @@
+# ADR 0006: Share invocation reporting while preserving application outcomes
+
+## Status
+
+Accepted. Consolidated during the [alpha ADR cleanup](README.md#alpha-consolidation).
+The structured-report formatting extension is accepted but not yet implemented;
+the [adoption roadmap](../roadmap/promptkit-v0.19.0.md#shared-core-report-output-prerequisite)
+tracks that work.
+
+## Date
+
+2026-11-07; consolidates decisions made on 2026-10-06 and 2026-10-25
+and the accepted shared-format ownership extension.
+
+## Context
+
+An invocation crosses routing, parsing, acquisition, command execution, and output
+delivery. Applications need consistent presentation and useful returned outcomes
+without giving a CLI library control of domain recovery or process termination.
+Separate reporting facilities would repeat visibility and failure-handling rules.
+
+## Decision
+
+Core provides one reporting facility per invocation for command results,
+immediate messages, deferred messages, and final presentation. Callers choose
+result and diagnostic destinations. Applications and integrations choose content,
+messages, and domain outcomes; core coordinates visibility, delivery, and its
+own parsing and presentation failures.
+
+Applications decide whether a domain error warrants recovery, a warning, or a
+failed invocation. They supply explicit outcomes and explanations, optionally
+with an error cause. A cause alone does not select an outcome or create an
+operator-facing message. Preserve supplied causes and their supported public
+identity. Integrations adapt upstream evidence without taking ownership of its
+domain meaning or disclosure rules.
+
+Return explicit outcome classifications that distinguish shared usage and
+operational failures from application-defined domain outcomes. Preserve domain
+classification and keep presentation failures separately observable from the
+operation's explanation and cause. Delivery failure must be visible without
+silently discarding the application's result. The application entry point owns
+final process status mapping and termination.
+
+Present terminal failure explanations after ordinary reporting finishes. Core
+coordinates its own diagnostic paths to avoid duplicate presentation. Reporting
+state serves delivery and the returned outcome; logging and message history
+remain application responsibilities.
+
+The accepted structured-report extension centralizes format selection,
+serialization, and rendering in core. Applications and integrations hand off
+selected content, including their chosen detail level and optional text template;
+core determines how to output it. New core formats should work through that
+shared handoff without each command maintaining encoders. This extends the same
+invocation lifecycle, with a writer API sharing rendering outside invocations.
+Implementation status and initial format choices remain in the roadmap above.
+
+## Alternatives considered
+
+- Handler-owned presentation would maximize local control but repeat output,
+  visibility, and delivery-error infrastructure.
+- Letting core interpret domain errors would give it recovery decisions that
+  depend on application behavior.
+- One failure category or numeric status alone would lose meaningful distinctions
+  between usage, operational, and domain results.
+- Separate facilities for results and messages, or encoders in each integration,
+  would spread shared behavior across independent implementations.
+
+## Consequences
+
+Commands share presentation while retaining ownership of their content and
+outcomes. Core must keep operation and presentation evidence distinguishable,
+including when output is partial. Caller writers retain their own lifecycle.
+
+GoDoc and the [CLI reference](../cli.md#reporting) own implemented APIs, numeric
+statuses, visibility controls, and exact delivery behavior. Report layouts,
+format defaults, YAML framing, and scope ordering are presentation contracts,
+not separate architectural decisions. The shared-format extension remains
+planned until its implementation and canonical contracts land.