From 92727ecf2b44d1e398738b09a16f8be543c63642 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 11 Oct 2026 19:14:23 +0000 Subject: [PATCH] Clarify CommandKit ownership of upstream integration and presentation --- docs/policy/architecture.md | 36 ++++++++++++++++++++++++++---------- 1 file changed, 26 insertions(+), 10 deletions(-) diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 0088633..d058bfb 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -9,9 +9,11 @@ ## Purpose And Ownership CommandKit is an opinionated Go library for standard inspection commands, -consistent CLI syntax, and reduced application command infrastructure. This -policy owns normative responsibility boundaries, dependency direction, and -architectural constraints. ADRs own decision rationale; the +consistent CLI syntax, and reduced application command infrastructure. It provides +useful operator access to capabilities owned by its integrated libraries through +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 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. 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 meaning, effects, domain validation, artifacts, and operational outcomes. 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 semantics, secret classification, and native rendering. Applications provide schemas, acquisition, domain resolution and validation, and construction of -inspection providers. CommandKit exposes those capabilities without implementing -a parallel configuration or prompt engine. Use independently released public -contracts; do not import sibling internal packages or depend on adjacent checkouts. +inspection providers. CommandKit exposes those capabilities through supported +upstream APIs. The public contract of the adopted library version governs their +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 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. 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 -their own output timing. Semantic comparison delegates to supported owning-library -comparison APIs and retains paired safe disclosure and hidden-change metadata at -the provider boundary. Reports may present the reduced view selected by +their own output timing. Semantic comparison exposes the adopted upstream +comparison API, carrying its results and relevant metadata through the provider +boundary. CommandKit owns report presentation under [ADR 0008](../adr/0008-semantic-configuration-diff.md). ## Scope And Non-goals