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

Consolidate and renumber architectural decision records

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-07 02:42:54 +00:00
parent 76c00e32d0
commit 5d90d59996
25 changed files with 525 additions and 1432 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
docs/policy/architecture.md
View File

@@ -2,7 +2,7 @@
**Base Policy Version:** 1.3
**Last Updated**: 2026-10-26
**Last Updated**: 2026-11-07
**Upstream Source:** [architecture.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md)
@@ -45,9 +45,8 @@ flexibility to express genuine application requirements within one command model
## Command And Application Ownership
[ADR 0001](../adr/0001-command-dispatch-and-inputs.md) records the selected
CommandKit-owned dispatcher, per-instance registry, and typed-input model.
[ADR 0011](../adr/0011-captured-declarations-and-installation.md) refines declaration
capture, installation, optional-family ownership, and invocation input lifetimes.
dispatcher, captured declarations, installation boundary, and typed-input model.
The [ADR index](../adr/README.md) records the alpha consolidation and renumbering.
CommandKit owns dispatch, common parsing, presence tracking, help, shared syntax
diagnostics, and the handlers and CLI contracts of its standard families.
@@ -72,8 +71,8 @@ semantics or success-report formats.
CommandKit's grammar applies to commands using its dispatcher and binding APIs.
Its documentation recommends the same grammar and vocabulary for application-owned
commands, including those outside its dispatcher, under
[ADR 0006](../adr/0006-command-grammar.md).
commands, including those outside its dispatcher. The
[CLI reference](../cli.md#registered-command-syntax) owns implemented grammar.
Use explicit instance construction and composable command registration, not
package-global or import-time registries. Applications and integrations supply
@@ -126,8 +125,10 @@ application-owned.
Use one reporting facility per invocation for command results, immediate messages,
and deferred messages. Core owns shared visibility, formatting, delivery, and
finalization. Applications and integrations choose their report content and
messages; callers choose the destinations. [ADR 0014](../adr/0014-invocation-reporting.md)
extends the outcome and delivery model in [ADR 0005](../adr/0005-invocation-outcomes.md).
messages; callers choose the destinations.
[ADR 0006](../adr/0006-invocation-reporting.md) records this reporting and outcome
ownership model. Its accepted structured-report extension remains planned in the
[adoption roadmap](../roadmap/promptkit-v0.19.0.md#shared-core-report-output-prerequisite).
Applications decide how to respond to domain-specific errors. CommandKit may
provide shared helpers for carrying, inspecting, and presenting errors while
@@ -137,8 +138,8 @@ handles its own errors, including routing, parsing, and presentation failures.
Preserve application-defined domain classifications and supplied error identity.
Report rendering and delivery failures separately from the command's explanation
and cause, applying the outcome rules in ADR 0005 and ADR 0014. Intentionally
suppressed output is not a delivery failure. Present terminal failure explanations
and cause, applying the [CLI reporting contract](../cli.md#presentation-failures).
Intentionally suppressed output is not a delivery failure. Present terminal failure explanations
after normal reporting finishes, avoid duplicate presentation through core's own
paths, and retain the explanation and any supplied cause in the returned outcome.
@@ -164,10 +165,12 @@ installation, help, version, and scope discovery.
For two-selection configuration comparison, prepare and check each side's input
separately with its scope identity and selection, applying the same applicable
converted selector values to both. Finish both checks before initializing shared
state once and invoking the integration-owned pair provider under
[ADR 0012](../adr/0012-typed-configuration-comparison-pairs.md). Required provider
wiring follows declared capabilities; a comparison-only scope does not require
an unrelated ordinary acquisition callback.
state once and invoking the integration-owned pair provider. The
[consumer guide](../consumers/guide.md#configkit-scopes) and linked GoDoc own the
provider lifecycle; the [CLI reference](../cli.md#compare-configuration-selections)
owns current selector behavior. Required provider wiring follows declared
capabilities; a comparison-only scope does not require an unrelated ordinary
acquisition callback.
Omitted input and state factories supply the respective type's zero value,
including nil for pointers. Caller factories and callbacks retain responsibility
@@ -187,8 +190,8 @@ composition does not create a second parser or a raw-argument handler model.
CommandKit keeps parsed values, collections, and presence from one invocation out
of subsequent runs. Storage allocation and safe reuse are implementation choices;
rebuilding backend state is the initial strategy under
[ADR 0002](../adr/0002-cobra-backend.md). Caller-owned closures and runtime state
the [internal overview](../internal/overview.md#internalcobra) describes the
current backend lifecycle. Caller-owned closures and runtime state
retain their own lifecycle. Concurrent dispatch is a separate contract.
Applications may interpret parsed domain values and provide domain value parsers
@@ -197,11 +200,11 @@ Keep input declarations available without application initialization.
## Public Facade And Dependency Direction
[ADR 0010](../adr/0010-optional-integration-modules.md) scopes the root
`commandkit` facade to the core module and selects separate optional integration
modules with their own public package contracts. It partially supersedes
[ADR 0003](../adr/0003-public-facade.md), whose remaining facade and internal
adapter principles apply to the core and integrations alike.
[ADR 0004](../adr/0004-optional-integration-modules.md) selects separate optional
integration modules with their own public package contracts. The facade and
backend isolation principles in
[ADR 0002](../adr/0002-public-facade-and-cli-backend.md) apply within those module
boundaries.
The core owns command declarations, registration, bindings, dispatch, help/version,
shared syntax, diagnostics, and outcomes. Each integration owns its standard
@@ -241,8 +244,8 @@ without exporting private assembly or backend structures.
## Backend And Library Integration
[ADR 0002](../adr/0002-cobra-backend.md) selects Cobra with pflag as the sole
initial backend. Their types and operations stay inside an internal adapter that
[ADR 0002](../adr/0002-public-facade-and-cli-backend.md) selects Cobra with pflag
as the sole initial backend. Their types and operations stay inside an internal adapter that
translates CommandKit-owned definitions into backend machinery. Registry logic,
standard handlers, and shared internal representations remain independent of
backend-specific structures.
@@ -275,15 +278,14 @@ 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.
Concrete integration needs guide provider representations under
[ADR 0009](../adr/0009-configuration-scopes.md).
[ADR 0003](../adr/0003-configuration-scopes.md).
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 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).
Use upstream safe inspection data to preserve owning-library meaning and
disclosure rules under [ADR 0004](../adr/0004-optional-integration-modules.md).
The [CLI reference](../cli.md#show-effective-configuration) owns current native
report formats and operation-specific preparation and delivery timing. Semantic
comparison exposes the adopted upstream comparison API and carries its evidence
through the provider boundary; it does not introduce a CommandKit equality engine.
## Scope And Non-goals