commandkit/docs/adr/0006-invocation-reporting.md

# ADR 0006: Share invocation reporting while preserving application outcomes

## Status

Accepted.
The structured-report formatting extension is accepted but not yet implemented;
the [adoption roadmap](../roadmap/promptkit-v0.20.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.