base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Clarify CommandKit ownership of upstream integration and presentation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-11 19:14:23 +00:00
parent 21c2fde8d5
commit 92727ecf2b
1 changed files with 26 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
docs/policy/architecture.md
View File

@@ -9,9 +9,11 @@
## Purpose And Ownership ## Purpose And Ownership
CommandKit is an opinionated Go library for standard inspection commands, CommandKit is an opinionated Go library for standard inspection commands,
consistent CLI syntax, and reduced application command infrastructure. This consistent CLI syntax, and reduced application command infrastructure. It provides
policy owns normative responsibility boundaries, dependency direction, and useful operator access to capabilities owned by its integrated libraries through
architectural constraints. ADRs own decision rationale; the shared command vocabulary, registration, selection, coordination, presentation,
and invocation outcomes. This policy owns normative responsibility boundaries,
dependency direction, and architectural constraints. ADRs own decision rationale; the
[implementation roadmaps](../development.md#task-specific-reading-guide) own [implementation roadmaps](../development.md#task-specific-reading-guide) own
proposals, sequencing, and implementation status. proposals, sequencing, and implementation status.
@@ -48,7 +50,8 @@ CommandKit-owned dispatcher, per-instance registry, and typed-input model.
capture, installation, optional-family ownership, and invocation input lifetimes. capture, installation, optional-family ownership, and invocation input lifetimes.
CommandKit owns dispatch, common parsing, presence tracking, help, shared syntax CommandKit owns dispatch, common parsing, presence tracking, help, shared syntax
diagnostics, and the handlers and observable contracts of its standard families. diagnostics, and the handlers and CLI contracts of its standard families.
The integrated libraries own the domain semantics exposed through those handlers.
Applications register domain commands outside those families and own their Applications register domain commands outside those families and own their
meaning, effects, domain validation, artifacts, and operational outcomes. meaning, effects, domain validation, artifacts, and operational outcomes.
Namespaces provide the ownership boundary. Core construction reserves help and Namespaces provide the ownership boundary. Core construction reserves help and
@@ -228,9 +231,22 @@ them; a public backend selection or plugin framework is not part of the design.
ConfigKit and PromptKit own configuration composition, provenance, inspection ConfigKit and PromptKit own configuration composition, provenance, inspection
semantics, secret classification, and native rendering. Applications provide semantics, secret classification, and native rendering. Applications provide
schemas, acquisition, domain resolution and validation, and construction of schemas, acquisition, domain resolution and validation, and construction of
inspection providers. CommandKit exposes those capabilities without implementing inspection providers. CommandKit exposes those capabilities through supported
a parallel configuration or prompt engine. Use independently released public upstream APIs. The public contract of the adopted library version governs their
contracts; do not import sibling internal packages or depend on adjacent checkouts. meaning and disclosure rules. When CommandKit adopts an upstream revision,
changes to those semantics flow through its integration. Adaptation and
documentation follow the adopted contract; descriptions of upstream behavior
do not establish a separate, fixed CommandKit specification of that behavior.
CommandKit owns presentation and may summarize or transform returned safe data
for different operator needs. Reports can evolve in format, organization, and
detail while respecting upstream disclosure rules and the evidence supplied by
the capability. Exact report contracts belong in the CLI reference when
implemented; changes to CommandKit's published contracts follow the release
policy.
Use independently released public contracts; do not import sibling internal
packages or depend on adjacent checkouts.
Use narrow integration contracts, reusing upstream public types where useful and Use narrow integration contracts, reusing upstream public types where useful and
introducing CommandKit-owned abstractions where they simplify integration. introducing CommandKit-owned abstractions where they simplify integration.
@@ -240,9 +256,9 @@ Concrete integration needs guide provider representations under
Native report writers and safe inspection data preserve owning-library semantics. Native report writers and safe inspection data preserve owning-library semantics.
Loading all selected views before report output is a `config show` decision under Loading all selected views before report output is a `config show` decision under
[ADR 0007](../adr/0007-native-yaml-reports.md); other inspection operations define [ADR 0007](../adr/0007-native-yaml-reports.md); other inspection operations define
their own output timing. Semantic comparison delegates to supported owning-library their own output timing. Semantic comparison exposes the adopted upstream
comparison APIs and retains paired safe disclosure and hidden-change metadata at comparison API, carrying its results and relevant metadata through the provider
the provider boundary. Reports may present the reduced view selected by boundary. CommandKit owns report presentation under
[ADR 0008](../adr/0008-semantic-configuration-diff.md). [ADR 0008](../adr/0008-semantic-configuration-diff.md).
## Scope And Non-goals ## Scope And Non-goals