commandkit/docs/adr/0007-native-yaml-reports.md

# ADR 0007: Use native YAML and ordered documents for inspection reports

## Status

Proposed

## Date

2026-10-06

## Context

ConfigKit and PromptKit provide native YAML configuration inspection. Reusing
their writers preserves captured value semantics, ordering, and redaction. YAML
also supports automated consumption of structured reports.

The agreed initial direction is YAML-based structured inspection and separate 
native documents for `config show --scope all`. The remaining choices concern 
report defaults, document framing, and when output begins relative to 
configuration loading.

## Decision

The initial standard uses text for concise operator reports and YAML for
structured consumption.

| Operation | Default report | Available initial formats |
| --- | --- | --- |
| `help` | Text | Text |
| `version` | Text | Text, YAML |
| `config scopes`, `validate`, `sources`, `explain`, `diff` | Text | Text, YAML |
| `config show` | Native YAML | YAML |
| `promptkit list/show` | Text | Text, YAML |

These format choices govern initial configuration and PromptKit reports and
version reporting. Additional families select formats appropriate to their own
resources through their command contracts. Custom handler formats remain
application-owned. Version format selection preserves the selected subject under
[ADR 0004](0004-standard-inspection-surface.md).

Operations with a format choice use `--format text|yaml`. Format names are
lowercase. YAML-only display uses its native writer directly. Help presents its
registered text form. Format validation follows the usage outcome policy in
[ADR 0005](0005-invocation-outcomes.md).

A single-scope `config show` writes the owning library's complete native redacted
YAML. Its output consists of the inspection document itself. The native writer
preserves effective presence, null and container distinctions, stable mapping
order, and sequence order according to its public contract.

`config show --scope all` emits one native document per registered scope in the
order defined by [ADR 0009](0009-configuration-scopes.md): application first,
PromptKit next when registered, followed by additional scopes in identifier order.
Each document begins with `---` and a `# scope: NAME` comment. A one-scope `all`
selection uses the same labeled document form.

CommandKit writes the separators and comments around the native writer output.
Comments label scopes for operators; document order follows the registered scope
inventory. That framing offers callers an association between documents and
scopes. Each scope retains its own value namespace and native rendering.
The combined stream is an inspection report whose documents can be decoded
individually.

CommandKit checks operation availability for selected scopes before acquisition.
It acquires their views and completes validation required by those provider
contracts before report output begins. A failure returns its diagnostic outcome
before report writing. After writing begins, a writer failure may leave partial
bytes and returns operational failure under ADR 0005.

Other structured reports use operation-specific YAML schemas and selection
metadata. They contain one document and a trailing newline. Native explanation
snapshots retain their safe YAML text and presence/redaction metadata when
projected into structured reports. The CLI reference owns exact schemas and
field names after implementation.

Report confidentiality follows the owning libraries' sensitivity classifications.
Their safe writers and records supply redacted content. CommandKit preserves
those confidentiality semantics; arbitrary caller content retains the caller's
disclosure policy.

Report delivery uses the supplied streams and the channel policy in ADR 0005.
Configuration path syntax follows ConfigKit's JSON Pointer contract independently
of serialization format.

## Alternatives considered

| Alternative | Analysis |
| --- | --- |
| A scope-keyed YAML wrapper | Carries scope identity as parsed mapping keys. Rendering needs an additional wrapper representation and indentation of native documents. |
| JSON alongside YAML initially | Serves JSON-specific tools. The library maintains another serializer and representation contract. |
| YAML as every report's default | Provides uniform structured output. Interactive help, tables, and explanation workflows use structured documents for routine discovery. |
| Output each scope as acquisition finishes | Starts reporting earlier. A later acquisition failure can leave a successful prefix representing only part of the selection. |
| Marshal application runtime structs | Reuses application data types. Presence, captured resolution, ordering, and safe historical inspection need a separate rendering lifecycle. |

## Consequences

Native display preserves owning-library behavior and keeps rendering focused.
Combined inspection requires multi-document YAML consumption and an ordered scope
contract. The comments label documents, and the ordered inventory supports
identification.

Loading all scopes before output adds preparation time and allows a failure in
one selected scope to prevent combined output. Explicit single-scope inspection
remains available for a narrower view. Writer failures remain visible through
outcomes and may leave partial output.

Additional structured schemas are compatibility contracts owned by CommandKit.
Native concatenation can use existing writers; semantic comparison separately
requires the safe structured data described in
[ADR 0008](0008-semantic-configuration-diff.md).