From 6a0467148e4f71350922df939706b80290c2108c Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 6 Oct 2026 16:39:20 +0000 Subject: [PATCH] List remaining architecture and policy ADR candidates --- docs/roadmap/adr.md | 294 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 294 insertions(+) create mode 100644 docs/roadmap/adr.md diff --git a/docs/roadmap/adr.md b/docs/roadmap/adr.md new file mode 100644 index 0000000..e476c2a --- /dev/null +++ b/docs/roadmap/adr.md @@ -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.