Write release notes for CommandKit v0.5.0

docs/releases/v0.5.0.md

@@ -0,0 +1,47 @@
+# CommandKit v0.5.0
+
+CommandKit v0.5.0 fixes defects in deferred reporting and YAML value preservation,
+reduces repeated work in command installation and alias help, and simplifies
+typed input preparation and replay of captured flags.
+
+## Changes
+
+- Acceptance of deferred messages now closes atomically when invocation finalization
+  begins. Concurrent submissions are included in the final batch or rejected
+  with `ErrReporterClosed`; accepted messages can no longer be silently lost
+  between batch detachment and closure.
+- Finalized reporting state releases its direct references to borrowed output
+  and diagnostic writers while retaining presentation results. Writers remain
+  caller-owned.
+- `DecodeYAMLReport` follows resolved YAML scalar tags, preserving numeric-looking
+  strings as strings. YAML report rendering preserves explicit numeric meaning
+  for values beyond the resolver's ordinary numeric range.
+- Compilation of flag aliases reuses resolved chain suffixes. Alias discovery and
+  help reuse the existing source tree, and declaration validation reuses one
+  scratch path across siblings, formatting paths only for diagnostics.
+- Typed input preparation reconstructs occurrence order without general sorting;
+  replay of captured flags merges already ordered streams. Parsing and completion
+  share flag-consumption mechanics while retaining their distinct handling of
+  errors and incomplete input.
+- The core reporting example preserves its default scenario when the optional
+  operand is omitted. The interactive completion fixture no longer collides with
+  the reserved `--format` flag. `FlagMeta` documentation now states the existing
+  naming and reserved-spelling rules.
+
+## Compatibility and upgrade
+
+The public core Go API, CLI grammar, and Go 1.26.0 consumer minimum are unchanged.
+The maintainer release toolchain remains Go 1.27.0.
+
+Applications using background producers should coordinate deferred submissions
+before the handler returns and handle `ErrReporterClosed` once finalization
+begins. See the [invocation reporting guide](../consumers/guide.md#invocation-reporting).
+
+Callers supplying YAML with numbers beyond the resolver's ordinary range should
+use explicit `!!int` or `!!float` tags when numeric meaning is intended. Untagged
+values resolved as strings now retain that type. See
+[`DecodeYAMLReport`](../../report_value.go) for the conversion contract.
+
+[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.5.0/COPYRIGHT) |
+[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.5.0/LICENSE) |
+[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.5.0/docs/oss/attribution.md)