List remaining architecture and policy ADR candidates
This commit is contained in:
294
docs/roadmap/adr.md
Normal file
294
docs/roadmap/adr.md
Normal file
@@ -0,0 +1,294 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user