Consolidate and renumber architectural decision records
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
**Base Policy Version:** 1.3
|
||||
|
||||
**Last Updated**: 2026-10-17
|
||||
**Last Updated**: 2026-11-07
|
||||
|
||||
**Upstream Source:** [testing.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/testing.md)
|
||||
|
||||
@@ -66,7 +66,7 @@ implemented:
|
||||
- Selected inspection/report contracts, including native YAML and document order
|
||||
for `config show --scope all`.
|
||||
- Public type ownership and the internal Cobra/pflag import boundary selected by
|
||||
[ADR 0003](../adr/0003-public-facade.md).
|
||||
[ADR 0002](../adr/0002-public-facade-and-cli-backend.md).
|
||||
|
||||
Use external-package consumer tests for facade semantics and real backend
|
||||
integration where correctness depends on that interaction. Internal package
|
||||
|
||||
Reference in New Issue
Block a user