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

Simplify ADRs and relax premature constraints

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-07 02:45:09 +00:00
parent 984d159676
commit 7e453a2df2
9 changed files with 165 additions and 310 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
docs/adr/0004-standard-inspection-surface.md
View File

@@ -15,13 +15,9 @@ needs. A defined operator surface establishes the infrastructure CommandKit
provides. Different integrations expose different resources and inspection
capabilities, while shared verbs benefit from consistent meanings.
[ADR 0001](0001-command-dispatch-and-inputs.md) establishes dispatch, registration,
capability-based installation, and the boundary of CommandKit policy. The remaining
decisions are the operator questions the initial standard answers.
## Decision
CommandKit supplies help and version reporting and defines ConfitKit and
CommandKit supplies help and version reporting and defines ConfigKit and
PromptKit inspection operations. Each family defines its own supported set of
operations. Registration installs handlers for the capabilities supplied by the
integration and exposes their availability through help and discovery metadata.
@@ -44,31 +40,23 @@ backend-completed named execution targets. PromptKit definition capabilities and
its configuration scope are registered according to their available provider
operations. Either can be integrated independently.
CommandKit assembles each installed family from its declared capabilities, keeping
standard handlers and metadata together. The inventory describes available
standard operations; adoption can use the supported subset. Semantic diff depends
on safe comparison snapshots for its selected scope. Its availability is
independent of display, validation, and other inspection capabilities.
Adoption can use the supported subset under
[ADR 0001](0001-command-dispatch-and-inputs.md). Missing comparison or catalog
capabilities leave other inspection operations available.
Shared verbs keep consistent purposes: `list` enumerates resources, `show`
displays a selected resource, and `diff` compares supported representations. Each
family specializes those purposes for its own resources. For example, a future
FeedKit family could supply `list` and `show` as its intended operation set.
family specializes those purposes for its own resources.
`app version` and root `app --version` report application version. The version
command defaults to `--scope app`; `app version --scope commandkit` reports the
embedded CommandKit release version. `--format` selects presentation of the same
subject. Future component identities can use registered version metadata. Version
subjects are independent of configuration scopes and loading providers.
Version subjects are independent of configuration scopes and loading providers.
CommandKit owns vocabulary and observable contracts within its standard families.
Custom execution, rendering, serving, sessions, and artifact workflows retain
their application-owned meanings. Additional shared operations enter through
versioned CommandKit releases under the
[release policy](../policy/release.md#versioning-and-compatibility).
their application-owned meanings.
The CLI reference owns exact flags, operands, defaults, and report schemas when
implemented. This record owns operation purposes and capability-based availability.
The [CLI roadmap](../roadmap/01-cli-plan.md) tracks command details and delivery.
The CLI reference will own exact flags, operands, defaults, and report schemas
when implemented.
## Alternatives considered
@@ -79,7 +67,6 @@ implemented. This record owns operation purposes and capability-based availabili
| Definition inspection through configuration operations alone | Source values and provenance share one path. Captured catalogs and completed execution targets require additional interpretation. |
| Standardize execution and mutation alongside inspection | Expands shared vocabulary to more workflows. Additional domain and state-management contracts require their own evidence and design. |
| Display dependency identities in ordinary application version output | Makes dependency information immediately visible. Application identity becomes coupled to dependency reporting. |
| A combined dependency-version option | Gives a useful diagnostic inventory. Scoped version reporting also supports selecting one identity. |
## Consequences
@@ -88,12 +75,6 @@ availability from registration. Each enabled operation needs its own data
contract: comparison needs safe snapshots, catalogs need enumeration, and profile
display needs safe execution-target inspection.
Shared operations retain clear purposes. CommandKit release notes describe changes
to its published operations. Coordinated application documentation and caller
updates are recommended migration practices.
Help and discovery describe actual supported capabilities. The
[scope model](0009-configuration-scopes.md),
[inspection lifecycle](0008-inspection-lifecycle.md), and
[comparison policy](0011-semantic-configuration-diff.md) describe the proposed
provider and behavioral contracts supporting this surface.
The [scope model](0009-configuration-scopes.md) and
[comparison policy](0008-semantic-configuration-diff.md) describe related
capability and behavioral decisions.