commandkit/docs/roadmap/adr.md

# CommandKit ADR candidates

Status: proposed ADR inventory; no new decisions are approved by this document.

Date: 2026-10-06.

This review covers the four numbered roadmaps:
[CLI standard](01-cli-plan.md), [dispatcher](02-dispatch.md),
[backend](03-backend.md), and [public facade](04-facade.md). It compares their
choices with the existing ADRs and adopted policies. Candidate identifiers below
are review references, not reserved ADR numbers or filenames.

An ADR is useful for a significant choice with durable consequences for ownership,
consumer behavior, compatibility, or implementation boundaries. Exact API spelling,
report fields, and implementation tasks generally belong in their canonical
references or roadmaps. The [documentation policy](../policy/documentation.md#architecture-decision-records)
owns ADR format and lifecycle.

## 1. Decisions already recorded

| Existing record | Roadmap coverage | Decisions already captured |
| --- | --- | --- |
| [ADR 0001](../adr/0001-command-dispatch-and-inputs.md) | 01 and 02 | CommandKit-owned dispatch; reserved standard families and namespace/resource-first syntax; the single `promptkit` namespace; explicit per-instance registries and command groups; capability installation and lazy providers; typed inputs, presence, fresh state, and application lifecycle/outcome ownership. |
| [ADR 0002](../adr/0002-cobra-backend.md) | 03 | Cobra/pflag as the sole initial internal backend, fresh backend state, framework reuse with CommandKit-owned semantics, and no initial selectable backend facility. |
| [ADR 0003](../adr/0003-public-facade.md) | 04 | Root-owned public contracts, explicit conversions, internal dependency direction, Cobra adapter isolation, error/type boundaries, and proportionate boundary protection. |

Recommend retaining those records without splitting them or creating overlapping
ADRs for their constituent choices. They were created during policy adoption;
roadmaps 02–04 now chiefly track their implementation and unresolved API design.
New records should address distinct decisions left open, and link to existing
records for established constraints.

## 2. Recommended candidates

| ID | Proposed ADR title | Current decision status | Recommendation |
| --- | --- | --- | --- |
| C1 | Use native YAML inspection and separate documents for combined scopes | YAML/JSON and combined-display principles accepted; some operational details remain proposed | Record the accepted principles first. |
| C2 | Define the standard inspection surface and complete-family conformance | Ownership/completeness principles established; exact inventory proposed | Resolve the standard's operator responsibilities and required capabilities. |
| C3 | Model inspection through complete named configuration scopes | Scope model and most defaults proposed; combined display accepted | Resolve with provider API design. |
| C4 | Apply one CLI grammar through registered metadata | Shared parsing/presence established; particular grammar rules proposed | Resolve before fixing adapter behavior. |
| C5 | Use one configuration selection path with controlled domain input extensions | Extension/ownership boundary established; detailed selection policy proposed | Resolve before provider and binding APIs are fixed. |
| C6 | Inspect captured effective state without executing application work | Library/runtime ownership established; detailed inspection lifecycle proposed | Resolve with scope and provider design. |
| C7 | Compare semantic configuration snapshots with explicit sensitivity gaps | Semantic diff and its comparison policy proposed | Resolve with the upstream inspection capability design. |
| C8 | Return explicit invocation outcomes and separate reports from diagnostics | Outcome/process ownership established; public outcome model and status policy open | Resolve alongside invocation API design. |
| C9 | Identify the CLI standard separately from application build identity | Separate CLI standard revision proposed; Go/CLI compatibility already policy | Resolve before version reporting and first publication. |

The following scopes distinguish existing commitments from recommendations.
An accepted principle does not automatically approve every adjacent paragraph
of the CLI proposal.

### C1. Use native YAML inspection and separate documents for combined scopes

**Decision to record:** the initial implementation defers JSON without promising
future delivery; combined `config show --scope all` uses separate native YAML
documents, with application configuration followed by registered PromptKit
configuration. The CLI plan also marks document separators and scope comments
as accepted combined-display behavior.

**Why an ADR:** this preserves owning-library rendering and avoids a second
serialization model or merged configuration schema. It determines automated
consumption and makes the multi-document versus single-wrapper tradeoff durable.

**Recommendation:** record those accepted choices now. Keep operation-specific
text/YAML defaults, exact structured report schemas, and the proposed policy for
loading all scopes before output and handling failures distinct until selected.
Detailed output contracts remain in the roadmap until implemented, then move to
the CLI reference.

Sources: [accepted planning decisions](01-cli-plan.md#accepted-planning-decisions),
[`config show`](01-cli-plan.md#config-show),
[output formats](01-cli-plan.md#9-output-diagnostics-and-failures), and
[backend report integration](03-backend.md#provider-integration-and-native-reports).

### C2. Define the standard inspection surface and complete-family conformance

**Decision to resolve:** which operator responsibilities constitute the core
inspection standard, which belong to the optional PromptKit family, and what
complete adoption requires once those capabilities are available. The proposed
surface distinguishes source inventory from path explanation, effective
configuration from definition metadata, and inspection from mutation/execution.

**Why an ADR:** the chosen responsibilities determine bundled handlers, provider
requirements, and the infrastructure applications can delete. This is a policy
choice beyond a list of command spellings.

**Recommendation:** use the proposed core/optional division as the starting point.
Select the inventory deliberately, including whether semantic diff is required
for core conformance despite its upstream dependency. Preserve the existing
complete-family/no-placeholder boundary. Delivery phases and deferred product
ideas remain roadmap material; exact commands belong in the future CLI reference.

Sources: [inventory](01-cli-plan.md#3-recommended-command-inventory),
[delivery and conformance](01-cli-plan.md#10-implementation-dependencies-and-delivery),
[deferred commands](01-cli-plan.md#11-explicitly-deferred-commands), and
[existing capability decision](../adr/0001-command-dispatch-and-inputs.md#explicit-registry-and-capability-installation).

### C3. Model inspection through complete named configuration scopes

**Decision to resolve:** stable scope identities, a complete inspection capability
per scope, scope dependencies and reuse, and the meaning/applicability of `all`.
Select the proposed application inspection default versus all-scope validation
default deliberately.

**Why an ADR:** one scope abstraction can remove duplicated operation trees and
support future integrations. Requiring complete scopes versus partial capability
sets changes public provider design and consumer obligations.

**Recommendation:** prefer complete semantic scopes over separate operation trees.
Resolve the required provider capabilities, loading dependencies, and treatment
of unavailable operations with C2 and C6. Decide whether public providers use
CommandKit-owned contracts or deliberately selected ConfigKit/PromptKit types;
ADR 0003 establishes the boundary but leaves that API choice open.

Sources: [configuration scopes](01-cli-plan.md#4-configuration-scopes),
[dispatcher API work](02-dispatch.md#2-public-api-design), and
[facade representation work](04-facade.md#2-api-and-internal-representation-design).

### C4. Apply one CLI grammar through registered metadata

**Decision to resolve:** options after the complete command path, interspersed
leaf operands/options, `--`, singleton repetition, ordered repeatable values, and
how the selected mechanics apply to custom commands.

**Why an ADR:** grammar is a suite-wide compatibility contract that must survive
backend updates or replacement. Cobra/pflag selection alone does not select it.

**Recommendation:** evaluate the proposed grammar as one coherent policy and
implement selected differences from backend defaults centrally. Preserve the
already selected presence and typed-input model; do not repeat its rationale in
a new record. Detailed spelling and operand counts belong in command references.

Sources: [grammar proposal](01-cli-plan.md#flag-placement-and-repeated-flags),
[backend presence/repetition work](03-backend.md#presence-and-repetition), and
[existing typed-input decision](../adr/0001-command-dispatch-and-inputs.md#typed-inputs-with-explicit-bindings).

### C5. Use one configuration selection path with controlled domain input extensions

**Decision to resolve:** reuse application discovery and selection across execution
and inspection, common root/overlay selectors, typed configuration overrides, and
registered domain selectors with explicit applicability to operations/scopes.

**Why an ADR:** a second discovery/resolution path can inspect different state
from actual execution. Extension choices also determine how applications express
real domain context while CommandKit retains its standard-family ownership.

**Recommendation:** favor one application-owned acquisition path and ConfigKit's
recorded override/resolution mechanisms. Resolve selector applicability, invalid
combinations, path interpretation, and no-fallback behavior for explicit inputs.
Do not infer a universal filesystem discovery convention from shared CLI syntax.

Sources: [selection and overrides](01-cli-plan.md#configuration-selection-and-overrides),
[dispatcher binding work](02-dispatch.md#2-public-api-design), and
[existing input-extension boundary](../adr/0001-command-dispatch-and-inputs.md#ownership-and-namespace-structure).

### C6. Inspect captured effective state without executing application work

**Decision to resolve:** expose the owning libraries' final captured views,
coordinate dependency loading once per invocation, and distinguish configuration
validation and definition inspection from runtime preflight, request preparation,
provider calls, and application execution.

**Why an ADR:** this establishes which effects inspection may cause and which
state reports describe. It prevents reconstruction from mutable runtime structs
or reparsing YAML, and supports clear provider lifetimes.

**Recommendation:** prefer captured owning-library inspection APIs and preserve
their resolution, provenance, and redaction semantics. Specify configuration
validation scope, credential requirements, and acquisition effects explicitly;
offline inspection must not silently become a credential-independent guarantee.
Keep request-specific rendering and operational checks application-owned.

Sources: [validation](01-cli-plan.md#config-validate),
[effective display](01-cli-plan.md#config-show),
[PromptKit definitions](01-cli-plan.md#7-promptkit-definition-inspection), and
[upstream capability work](01-cli-plan.md#10-implementation-dependencies-and-delivery).
The basic library/runtime ownership boundary already exists in ADR 0001.

### C7. Compare semantic configuration snapshots with explicit sensitivity gaps

**Decision to resolve:** effective-value comparison rather than rendered line
diffs, absence/null/container distinctions, sequence treatment, independently
resolved selections, and incomplete comparison when sensitivity hides values.

**Why an ADR:** identical redaction masks do not establish equality. Comparing
two snapshots requires a deliberate sensitivity policy and an upstream data
contract; this cannot be settled by a formatter or string-matching heuristic.

**Recommendation:** favor semantic snapshots supplied by the owning libraries,
the proposed union of both sides' sensitivity classifications, and explicit
not-comparable paths. Resolve sequence granularity, comparison/report outcomes,
and available safe snapshot data before treating these choices as accepted.
Coordinate the comparison outcome with C8 rather than defining it twice.

Sources: [semantic diff](01-cli-plan.md#config-diff) and
[structured inspection dependencies](01-cli-plan.md#10-implementation-dependencies-and-delivery).

### C8. Return explicit invocation outcomes and separate reports from diagnostics

**Decision to resolve:** a public outcome/error model that distinguishes usage
errors, failed valid operations, and application domain results; selected standard
status mappings; report/diagnostic channels; warning and writer-failure behavior.

**Why an ADR:** the model crosses handlers, adapter translation, output, and the
application entry point. It affects Go error identity and subprocess compatibility.
Concrete status values in the CLI plan are still proposals.

**Recommendation:** preserve existing application process/outcome ownership and
backend-error isolation. Favor explicit classification over message matching and
single diagnostic emission. Select stdout/stderr policy, standard mappings, and
partial-output behavior with the invocation API. C1 owns format selection; this
record owns result classification and delivery semantics.

Sources: [reports and statuses](01-cli-plan.md#9-output-diagnostics-and-failures),
[dispatcher outcome work](02-dispatch.md#2-public-api-design),
[adapter diagnostics](03-backend.md#diagnostics-and-outcomes), and
[facade error conversion](04-facade.md#2-api-and-internal-representation-design).

### C9. Identify the CLI standard separately from application build identity

**Decision to resolve:** whether applications report an explicit CLI standard
revision distinct from application and module versions; its meaning, ownership,
change rules, and relationship to module releases and consumer adoption.

**Why an ADR:** a new compatibility identifier creates a durable versioning axis.
The adopted release policy already covers Go and CLI compatibility, but does not
define a separate standard-revision scheme.

**Recommendation:** consider the proposed explicit revision if it gives operators
and subprocess consumers actionable information. Compare it with deriving the
signal from the CommandKit module version before introducing another maintained
identifier. Record that tradeoff; routine build-info fields and output spelling
belong in the CLI reference.

Sources: [version proposal](01-cli-plan.md#version),
[consumer migration](01-cli-plan.md#10-implementation-dependencies-and-delivery),
[backend compatibility work](04-facade.md#4-completion-and-later-replacement), and
[release compatibility policy](../policy/release.md#versioning-and-compatibility).

## 3. Suggested order

1. Record C1's already accepted principles; keep unresolved adjacent details
   proposed. Existing ADRs 0001–0003 already cover the other accepted architectural
   foundations from the numbered roadmaps.
2. Resolve C2, C3, C5, and C6 together to establish the inspection surface and
   provider responsibilities before fixing public API declarations. Combine
   records if the eventual choices are inseparable and one coherent rationale
   is clearer.
3. Resolve C4 and C8 alongside binding/invocation API design, before adapter
   defaults become observable commitments.
4. Resolve C7 with the upstream snapshot/sensitivity contract; it may precede
   implementation of the diff command without blocking native YAML display.
5. Resolve C9 before exposing a new standard-revision field or publishing its
   compatibility meaning.

This is a drafting sequence, not a requirement to produce nine ADRs before any
implementation. Select records according to the significance of actual decisions.
When a decision changes an accepted ADR, create a superseding record rather than
rewriting its decision content. None of these candidates currently requires
superseding the three existing records.

## 4. Items to keep outside separate ADRs for now

- Exact command spellings, flags, report fields, and defaults should be defined
  by their owning CLI contracts after the significant policy choices above are
  settled. Do not make an ADR per subcommand or YAML field.
- Exact constructor/binding signatures, presence type names, and option
  conveniences remain API design work. Create another ADR only if their choice
  introduces a significant architectural tradeoff beyond existing typed bindings.
- Illustrative internal package names, forwarding helpers, and concrete checker
  mechanics are implementation choices. Facade ownership and boundary protection
  are already recorded in ADR 0003.
- Library version pins and ordinary attribution maintenance follow adopted OSS
  policy. They are not new ADRs merely because dependencies are introduced.
- Delivery phases, application adoption order, and deferred product ideas remain
  roadmap material. Initial breaking adoption and application ownership already
  have established rationale.
- Public backend selection, concurrent dispatch, and extra extension frameworks
  have no new demonstrated requirement in these roadmaps. Do not invent decisions
  or guarantees for them to fill the ADR inventory.
- Adopted repository policy rules need no duplicate ADR catalog here. A deliberate
  exception or substantive new policy tradeoff may warrant a record when it arises.

## 5. Handoff to durable records

For each selected candidate, capture context, decision, viable alternatives, and
consequences using the adopted ADR format. Assign the next sequential filename
when drafting the actual record. Keep candidate approval status accurate; listing
a recommendation here does not approve it.

Once a record owns architectural rationale, replace that rationale in non-owning
roadmaps with a link and retain implementation status and unresolved work. Update
the architecture or release policy only where the accepted choice establishes a
new normative rule. GoDoc and the implemented CLI reference remain the eventual
owners of exact public contracts.