Adopt shared policies and record CommandKit architecture

docs/roadmap/03-backend.md

@@ -0,0 +1,88 @@
+# CommandKit CLI backend implementation
+
+Status: accepted backend; implementation pending.
+
+Date: 2026-10-06.
+
+[ADR 0002](../adr/0002-cobra-backend.md) owns the Cobra/pflag selection, alternatives,
+and rationale. [ADR 0003](../adr/0003-public-facade.md) owns the root facade and
+internal adapter boundary. This roadmap tracks dependency selection, adaptation,
+and implementation evidence. The [CLI plan](01-cli-plan.md) retains command and
+grammar proposals; [dispatcher work](02-dispatch.md) tracks the public input and
+invocation API.
+
+## 1. Current status
+
+Cobra with pflag is selected as the sole initial backend. No module dependency,
+adapter, or executable behavior is implemented. Select versions and attribution
+when dependencies are incorporated. There is no initial public backend selection
+or plugin facility.
+
+## 2. Adapter work
+
+### Typed inputs and fresh state
+
+Translate CommandKit's explicit bindings into backend flag bindings and operand
+assignments. Create a fresh backend command tree and fresh input storage for each
+invocation from registered definitions. Construction must not load configuration,
+resolve credentials, or create execution dependencies.
+
+### Presence and repetition
+
+Record CLI presence independently of parsed defaults, preserving explicit empty,
+false, and zero values. Transfer presence into the typed fields selected by each
+command; handlers must not need backend flag lookups.
+
+Resolve repetition and grammar choices before enforcing them. The CLI plan's
+singleton-repetition rejection is still a proposal. If selected, enforce it
+explicitly using registered metadata while preserving ordered accumulation for
+repeatable inputs. Exercise interspersed flags, values beginning with `-`, and
+`--` against the selected contract; avoid application-maintained flag-name lists.
+
+### Help and command discovery
+
+Generate help from one registry's metadata for standard and application commands,
+using backend machinery with the selected CommandKit presentation. Keep help and
+version usable without configuration or runtime construction.
+
+Configure automatic backend behavior to match the chosen inventory. Backend
+completion support does not itself add a standard completion command. Parent and
+family help, unknown-command handling, operands, and leaf help need explicit
+contract choices rather than incidental defaults.
+
+### Diagnostics and outcomes
+
+Use backend context and stream support. Translate backend-owned syntax failures
+into CommandKit diagnostics/outcomes and avoid duplicate emission. Preserve the
+selected distinctions among usage errors, valid-invocation failures, and custom
+application outcomes. Do not match domain error strings or print usage for every
+runtime failure. Return control to the application for process termination.
+
+### Provider integration and native reports
+
+Install selected standard families from supplied providers and acquire their data
+lazily. Scope dependencies and native YAML rendering remain CommandKit integration
+work through ConfigKit/PromptKit public inspection APIs.
+
+Implement accepted `config show --scope all` using native writers and the YAML
+stream contract in the CLI plan. Preserve the initial JSON deferral. A parser
+backend creates no need for another configuration loader or public backend-specific
+provider types.
+
+## 3. Delivery sequence and evidence
+
+1. Select and pin Cobra/pflag versions and record their actual licensing/notices.
+2. Design the neutral internal definitions required by the public registry and
+   typed-binding API, then implement translation within the adapter boundary.
+3. Exercise representative standard and application command definitions, including
+   the examples in the dispatcher roadmap, against selected semantics.
+4. Introduce meaningful integration evidence for conflicts, nested routing, help
+   with invalid configuration, repetition, presence, `--`, fresh state, context
+   and streams, failed writers, and application outcomes. Adapt defaults as needed
+   without treating that work as grounds to reopen the accepted selection.
+5. Integrate standard handlers and coordinate breaking application adoption under
+   the CLI delivery plan. Update consumer docs and subprocess adapters.
+
+The testing policy owns check selection; the architecture policy owns boundaries.
+The ADR owns the backend-selection rationale and reviewed primary references.
+No second backend or generalized backend framework is a prerequisite.