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

Record proposed CLI decisions and clarify CommandKit boundaries

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-06 23:36:06 +00:00
parent 6a0467148e
commit 84234275eb
15 changed files with 1243 additions and 331 deletions
Download Patch File Download Diff File Expand all files Collapse all files

185
docs/roadmap/01-cli-plan.md
View File

@@ -16,6 +16,12 @@ future work.
- Use namespace/resource first: `app config show` and `app promptkit show`.
Whether the first noun describes a resource or a library namespace does not
change the command grammar or its ownership boundary.
- Assemble families from declared capabilities. Each family defines its own
supported verbs; configuration scopes expose their available operations.
- Keep ordinary version output focused on the application. Explicit
`version --scope commandkit` reports embedded CommandKit identity.
- Govern CommandKit's own behavior and provider contracts. Shared loading and
callback organization are consumer guidance.
- Put PromptKit definition inspection under the single `promptkit` family.
CommandKit does not reserve the root `prompt` and `profile` names.
- Support `config show --scope all`, with the application configuration followed
@@ -39,11 +45,12 @@ provide configuration schemas, source acquisition, domain resolution, validation
build metadata, and PromptKit engine construction. These collaborators supply data
and perform domain work; they do not replace CommandKit's handlers or renderers.
An application's registration of a standard family adopts its complete contract.
It cannot redefine `config show`, add a private `config artifacts` operation, or
choose a different meaning for `config sources`. Domain reports belong outside
the reserved family. New shared operations become part of CommandKit through an
explicit standard change.
CommandKit assembles standard families from registered capabilities and preserves
its contracts for enabled operations. It rejects replacement standard handlers
and private operations under its reserved families. Each family defines its own
operation set; providers can supply supported subsets. Help and discovery expose
that availability. New shared operations enter through versioned library changes.
[ADR 0001](../adr/0001-command-dispatch-and-inputs.md) owns this decision.
Applications may register context selectors and typed configuration overrides
through the extension mechanism described in section 5. This is a defined input
@@ -100,7 +107,7 @@ CommandKit rather than relying on sibling checkout links.
## 3. Recommended command inventory
### Required core suite
### Standard configuration operation inventory
| Command | Operator question or task |
| --- | --- |
@@ -132,8 +139,9 @@ to applications.
**Recommendation:** use explicit resource operands after `list` and `show`.
Plural collection names select catalogs; singular names select one definition.
This keeps prompt IDs and execution profile IDs unambiguous even when they overlap.
Registering the suite reserves the complete `promptkit` family, supplies all four
operations, and registers the `promptkit` configuration scope.
Registration reserves the `promptkit` family and supplies handlers for its
declared definition capabilities. Its configuration scope is a separate capability;
definition operations and configuration inspection can be integrated independently.
Configuration inspection remains `config show --scope promptkit`; the definition
commands report metadata and resolved execution targets, not a second configuration
display path.
@@ -159,8 +167,8 @@ implementation dependency, not evidence against a useful command standard.
configuration with backend-completed execution settings and gives `config` an
unrelated resource vocabulary.
- **Include only the core suite initially.** A reasonable delivery phase. Keep
the PromptKit suite explicitly pending until its public APIs are available;
avoid independent replacement inspection commands in the applications.
individual PromptKit capabilities pending until their public APIs are available;
their absence leaves existing inspection capabilities available.
`run`, `execute`, `render`, `serve`, `session`, and artifact catalogs are not
CommandKit-owned commands in this proposal. Recommend `run` for a new application's
@@ -193,7 +201,8 @@ configuration check. An operator can request the combined inspection explicitly.
Help must state these defaults prominently.
`config scopes` lists scope ID, description, and whether it is the default for
inspection. It uses registration metadata, so it works when files are missing or
inspection, together with supported operations. It uses registration metadata,
so it works when files are missing or
configuration is invalid. List `app` first, `promptkit` second when registered,
then additional scopes sorted by ID; use this same order for `show --scope all`.
It accepts `--format text|yaml` and no loading selectors. Unsupported scope names
@@ -201,11 +210,17 @@ are usage errors, with the
available names in the diagnostic; there is no fallback to `app`.
Scopes use stable semantic names rather than executable names such as `notarius`.
Applications may register additional independently meaningful configuration scopes
through the same complete contract. A scope must supply an effective snapshot,
sources, explanations, and comparison support; a custom formatted report does not
qualify as a scope. Scope dependencies must be explicit, and one invocation must
reuse already loaded dependencies rather than reread them unnecessarily.
Additional independently meaningful configuration scopes declare their supported
inspection operations and applicable providers. CommandKit validates declared
wiring and coordinates explicit dependencies, reusing compatible provider results
within an invocation. Scope inventory and help report the supported operations.
An unsupported scope-operation selection receives a usage diagnostic before
acquisition. `all` retains its all-scope meaning and checks coverage for the
requested operation. [ADR 0009](../adr/0009-configuration-scopes.md) owns the model.
A configuration scope targets configuration, while a command family targets its
own resources. A future FeedKit family could supply `list` and `show`; FeedKit
configuration inspection could separately register a configuration scope.
**Alternatives:**
@@ -219,17 +234,19 @@ reuse already loaded dependencies rather than reread them unnecessarily.
in one document, but requires additional presentation work and indentation of
the native reports. The accepted initial approach keeps separate native YAML
documents; its output and ordering contract are defined below.
- **Permit partial scopes with different operations.** Accommodates legacy
implementations, but makes `config` behave differently across applications.
Adapt or improve the inspection provider instead.
- **Require every inspection operation per scope.** Gives a uniform inventory.
A missing upstream operation then blocks useful existing capabilities. The
selected approach exposes operation availability explicitly.
## 5. Shared inputs and command syntax
### Configuration selection and overrides
**Recommendation:** every loading configuration operation accepts `--config PATH`,
`--overlay NAME`, and `--scope NAME`. These have the same meanings for validation,
display, source inventory, explanation, and comparison.
**Recommendation:** register selection inputs according to provider applicability.
`--scope NAME` selects the configuration. Providers using an application root
accept `--config PATH`; ConfigKit overlay integrations accept `--overlay NAME`.
These names retain the same meanings wherever applicable. Additional source models
can declare their own selectors through the standard input extension mechanism.
`--config` selects the application root configuration even for `promptkit` scope;
the application constructs the selected framework inputs from that root and its
@@ -238,12 +255,12 @@ missing or invalid file is a load failure and never triggers discovery fallback.
Relative CLI paths use the invocation working directory. File-relative resources
retain the owning library's source-context semantics.
When `--config` is omitted, use the application's registered discovery policy
identically across these commands and ordinary execution. CommandKit must not
hard-code a second search policy. Discovery order, environment-variable support,
default-only operation, and packaging paths must be visible in help. This proposes
a uniform selection interface; a universal filesystem discovery convention is a
separate decision because the applications have different deployment layouts.
When `--config` is omitted, CommandKit invokes the registered acquisition callback
with that absence preserved. It exposes supplied discovery, environment, and
default-only metadata in help. Sharing acquisition code with ordinary execution is
recommended consumer practice; execution loading and filesystem discovery remain
application choices. [ADR 0010](../adr/0010-configuration-selection.md) owns the
parsing and propagation contract.
`--overlay` always selects a configuration overlay, never a PromptKit execution
profile. Follow ConfigKit's naming and resolution semantics: omission, an empty
@@ -251,17 +268,18 @@ name, and the exact name `default` select the base; other names select one overl
An overlay name is not a file path. Replace `--config-overlay` with this standard
spelling rather than silently maintaining two conventions.
Applications register domain context selectors, such as Narratio's `--campaign`
and `--campaign-file`, and typed configuration overrides. CommandKit owns their
registration, parsing, help exposure, and propagation; applications own their
field mappings and domain checks. A selector must be offered on each operation
where it is meaningful, with the same meaning. Invalid combinations fail before
loading. Selectors that do not affect a chosen scope must be rejected rather than
silently ignored. Registration cannot shadow a standard flag.
The registration API accepts domain context selectors, such as Narratio's
`--campaign` and `--campaign-file`, and typed configuration overrides. CommandKit
parses them, exposes their declared applicability in help, and passes values to
the selected callback. Field mapping and domain checks remain callback behavior.
CommandKit validates declared combinations and applicability before loading and
reports collisions with standard flags. Shared selector names keep their defined
meaning on the operations where they are registered.
Preserve explicit flag presence. Omission, an empty string, false, zero, and null
are not interchangeable. Send configuration changes through ConfigKit's override
records and resolution mechanisms so effective output and provenance agree.
CommandKit preserves explicit flag presence. Omission, an empty string, false,
zero, and null retain their registered meanings. Using ConfigKit's recorded
overrides and domain resolution is recommended for coherent values and provenance;
CommandKit passes typed inputs to the registered integration callback.
Execution-only controls such as resume, output directories for generated artifacts,
or lane execution do not belong on generic configuration commands.
@@ -334,18 +352,19 @@ registered flag metadata, honor `--`, and correctly handle values beginning with
### `config validate`
**Recommendation:** validate all selected scopes completely through their owning
loaders. Include acquisition, composition, defaults, typed decoding, recorded
resolution, and domain configuration checks. PromptKit scope constructs the engine
and validates all effective definitions, including unused ones. Application scope
includes configured references and catalog relationships that can be checked
without executing a request.
**Recommendation:** invoke each selected scope's declared validation capability.
CommandKit checks support and coordinates required provider calls. The provider
implements acquisition, composition, defaults, decoding, and domain resolution
according to its public result contract. The PromptKit adapter requests upstream
configuration validation with all-definition coverage. Missing upstream support
is a dependency of that capability, rather than the entire integration.
[ADR 0008](../adr/0008-inspection-lifecycle.md) owns this boundary.
Validation does not execute a pipeline, prepare request-specific prompts, read
request inputs, contact a provider, or create runtime state. Do not add generic
pipeline or lane selectors to this operation. An application's operational
preflight, such as `session validate`, can perform additional context-dependent
checks outside the standard suite.
CommandKit's validation handler requests the declared configuration-validation
operation and writes its result. Request preparation, execution, and operational
preflight belong to custom domain handlers, such as `session validate`. Source
acquisition and effects inside callbacks remain provider behavior. Registered
input applicability determines the selectors used by standard validation.
Default text output is one concise success line identifying the validated scopes.
`--format yaml` returns a structured success report containing the scope IDs.
@@ -360,7 +379,8 @@ environment values, whereas PromptKit inspection does not itself resolve provide
credentials. Describe these requirements in scope help. Offline means no provider
or remote execution; it does not promise credential-independent loading. Existing
explicit credential-file bootstrap may run as part of acquisition, with its safe
report on stderr; it must not create durable application runtime state.
report through the supplied diagnostic channel. Callback effects and bootstrap
policy remain application-owned; focused acquisition is recommended practice.
**Alternatives:**
@@ -416,7 +436,8 @@ multiple documents. Comments are human labels, not parsed metadata; scope identi
for automated consumers follows the documented order. This is suitable YAML for
automation, but it is not one configuration document or a reloadable combined file.
Load and validate all selected scopes before starting output. A scope load failure
Check operation availability, acquire all selected views, and complete validation
required by their provider contracts before starting output. A scope load failure
returns `1` without a partial successful report. Writer failures can still leave
partial output. A broken PromptKit configuration can therefore prevent `--scope all`
from displaying otherwise usable application settings; `--scope app` remains
@@ -522,7 +543,8 @@ app config diff --config ./config.yml --overlay staging --against-overlay produc
app config diff --config ./old.yml --against-config ./new.yml --against-overlay default
```
Both sides must load and validate. Compare semantic effective values, including
For a scope declaring safe comparison support, acquire both views through the
registered provider's loading/validation contract. Compare effective values, including
defaults and recorded domain resolution, rather than YAML formatting, source IDs,
file order, or overlay names. Recursively compare mappings; keep sequences atomic,
preserving their order. Distinguish absence, null, empty mappings, and empty
@@ -615,8 +637,11 @@ raw `InspectProfile` results have native configuration redaction.
### Help
**Recommendation:** `app`, `app help`, `app --help`, and `app -h` print root help
and succeed. A family invoked without an operation, such as `app config`, prints
family help and succeeds. `app help config explain` and
and succeed. A command group with no execution handler, such as `app config`,
prints group help on bare invocation and succeeds. Runnable commands follow their
registered handler and operand requirements, including when they also have
subcommands. [ADR 0006](../adr/0006-command-grammar.md) records this distinction.
`app help config explain` and
`app config explain --help` print the same leaf help with status `0`.
Help never acquires configuration, constructs PromptKit, resolves credentials,
@@ -638,17 +663,21 @@ command or unknown flag valid.
### Version
**Recommendation:** `app version` prints `app VERSION` and a newline. Standardize
`app --version` as a root-only shortcut, rather than retaining it merely as a
Notarius compatibility alias. Neither form loads configuration. Recommend
`version --format yaml` with application name/version, optional revision and build
time, and the CommandKit standard revision implemented by the binary.
**Accepted:** `app version` prints `app VERSION` and a newline; root
`app --version` reports the same application identity. The version command defaults
to `--scope app`. `app version --scope commandkit` explicitly reports the embedded
CommandKit release version. `--format yaml` changes presentation of the selected
identity. Version subjects are separate from configuration scopes. CommandKit
uses build metadata with acquisition callbacks left uninvoked.
Future component identities can use registered version metadata.
[ADR 0004](../adr/0004-standard-inspection-surface.md) records version selection.
Applications supply build identity, with tagged Go build information usable when
available. An unversioned development build reports `dev`; unknown revision or
build time stays absent rather than being invented. The CLI standard revision is
distinct from application version and from the CommandKit module version. It
identifies observable command/report contracts, not application artifact formats.
build time stays absent rather than being invented. The CommandKit release version
identifies the library and its standard CLI contracts. Compatibility changes
follow the [release policy](../policy/release.md#versioning-and-compatibility).
**Alternatives:**
@@ -657,8 +686,13 @@ identifies observable command/report contracts, not application artifact formats
- **Emit all build and dependency information by default.** Helpful for debugging,
but unnecessarily verbose and unstable for a simple identity check. Structured
output should expose the selected fields.
- **Use the application version as the sole compatibility signal.** Insufficient
to distinguish independent CLI-standard and application-artifact changes.
- **List dependency versions alongside application version by default.** Adds
diagnostic detail to an identity check. Explicit subject selection keeps each
report focused.
- **Use a combined dependency-version option.** Useful for a broad inventory.
Scoped selection also supports querying one embedded component.
- **Add a separate integer CLI standard revision.** Rejected during ADR review.
The tagged CommandKit release version provides the shared compatibility identity.
## 9. Output, diagnostics, and failures
@@ -698,7 +732,7 @@ semantics rather than promising that every report is safe for public disclosure.
Default to stdout and shell redirection; do not initially add `--out` or `--output`
to standard reports. Ordinary writer failures may leave partial output and return
`1`; consumers must check status before decoding. This avoids adding filesystem
`1`; checking status before decoding is recommended caller practice. This avoids adding filesystem
creation, replacement, and retention behavior to inspection.
| Status | CommandKit-owned command meaning |
@@ -742,14 +776,14 @@ Existing public APIs already support native YAML, native explanation text,
structured explanation records, source records, and named definition inspection.
They do not yet provide everything recommended here:
| Needed capability | Implementation work before the complete standard can ship |
| Needed capability | Implementation work for that capability |
| --- | --- |
| Semantic diff | A safe structured effective snapshot from ConfigKit, preserving value semantics and per-path sensitivity; expose it through PromptKit inspection. This serves comparison rather than JSON output. |
| Combined configuration display | Compose native writers as labeled separate YAML documents after all selected scopes load; no new snapshot API is needed just to concatenate these reports. |
| Prompt/profile catalogs | Public PromptKit methods enumerating captured IDs and prompt versions without reparsing source YAML. |
| Safe rich profile reports | PromptKit-owned redacted inspection data for provider parameters. |
| Narratio's final application snapshot | Adapt its configuration boundary so campaign-derived effective values and provenance are recorded in the inspected result; avoid an unrelated typed-struct dump. |
| Full cross-scope validation | Application integration registering dependencies and offline configuration checks, with clear credential requirements. |
| Cross-scope validation | Registered validation capabilities and dependencies, with their actual acquisition and credential requirements exposed in help. |
Suggested sequence:
@@ -762,18 +796,19 @@ Suggested sequence:
display (including `show --scope all`), source inventory, and explanation using
existing APIs.
4. Integrate Scriptorium and Notarius to exercise both scopes and remove duplicated
handlers. Partial adoption remains development work, not conformance to the
complete proposed standard.
5. Add safe semantic comparison and the optional complete PromptKit definition
suite once the upstream APIs are released.
handlers. Register and report the supported capabilities; additional upstream
features can be integrated independently.
5. Add safe semantic comparison and additional PromptKit definition capabilities
as their upstream APIs are released.
6. Integrate Audita and Narratio, moving domain reports outside reserved families
and aligning their standard operations. Update consumer adapters and docs for
the intentional breaking releases.
A complete core adopter exposes every required core command for every registered
scope. A complete PromptKit-suite adopter additionally exposes all four definition
commands. Do not ship placeholder commands, claim unsupported formats, or silently
omit required operations.
CommandKit installs supported operations with their standard meanings and exposes
actual capabilities in help and scope metadata. Missing comparison or catalog
support leaves other operations available. Each family's resources determine its
supported verb set. Initial ConfigKit/PromptKit reports retain their chosen formats;
future families define suitable report contracts for their own resources.
Later implementation validation should exercise genuine contract risks: help with
invalid configuration, leaf flag placement and `--`, explicit empty/false/zero

10
docs/roadmap/02-dispatch.md
View File

@@ -27,9 +27,9 @@ The [backend roadmap](03-backend.md) tracks Cobra/pflag integration, and the
composable groups, and invocation using application context and streams.
2. Express nested paths, descriptions, typed flags and defaults, repeatable
inputs, presence, operands, and typed handlers in one definition.
3. Define capability-provider registration that installs complete standard
families without executing providers. Design wiring diagnostics separately
from invocation-time loading failures.
3. Define capability-provider registration that assembles supported standard
operations and help from declared capabilities, leaving acquisition callbacks
uninvoked. Design wiring diagnostics separately from loading failures.
4. Specify the outcome/error interface so common usage errors, standard-command
failures, and application-specific domain outcomes remain distinguishable.
5. Demonstrate bindings against the proposed `config show`, `promptkit show
@@ -82,8 +82,8 @@ argv to handlers.
APIs, following the upstream dependencies and delivery sequence in the CLI plan.
6. Replace application routers and parser plumbing with registration and handlers.
Coordinate the intentional breaking changes with application docs and
subprocess consumers. Partial integrations remain development work rather
than conformance to an unsupported complete suite.
subprocess consumers. Supported capability subsets can be integrated and
released independently, with their actual availability exposed in metadata.
## 4. Implementation evidence

362
docs/roadmap/adr.md
View File

@@ -1,6 +1,6 @@
# CommandKit ADR candidates
Status: proposed ADR inventory; no new decisions are approved by this document.
Status: eight draft ADRs are Proposed and await review and approval.
Date: 2026-10-06.
@@ -8,7 +8,9 @@ This review covers the four numbered roadmaps:
[CLI standard](01-cli-plan.md), [dispatcher](02-dispatch.md),
[backend](03-backend.md), and [public facade](04-facade.md). It compares their
choices with the existing ADRs and adopted policies. Candidate identifiers below
are review references, not reserved ADR numbers or filenames.
retain their original review meaning. The draft filenames now provide sequential
record numbers after the existing three ADRs. All eight drafts remain Proposed
pending review and approval; committing them preserves that status.
An ADR is useful for a significant choice with durable consequences for ownership,
consumer behavior, compatibility, or implementation boundaries. Exact API spelling,
@@ -24,30 +26,97 @@ owns ADR format and lifecycle.
| [ADR 0002](../adr/0002-cobra-backend.md) | 03 | Cobra/pflag as the sole initial internal backend, fresh backend state, framework reuse with CommandKit-owned semantics, and no initial selectable backend facility. |
| [ADR 0003](../adr/0003-public-facade.md) | 04 | Root-owned public contracts, explicit conversions, internal dependency direction, Cobra adapter isolation, error/type boundaries, and proportionate boundary protection. |
Recommend retaining those records without splitting them or creating overlapping
ADRs for their constituent choices. They were created during policy adoption;
roadmaps 02–04 now chiefly track their implementation and unresolved API design.
New records should address distinct decisions left open, and link to existing
records for established constraints.
These records were created during policy adoption. ADR 0001 was revised directly
in this review under the user's explicit override of the documentation policy's
supersession rule. It retains dispatcher and typed-input decisions while correcting
capability installation and consumer-policy scope. No superseding record was
retained. Roadmaps 02–04 track implementation and unresolved API design.
## 2. Recommended candidates
| ID | Proposed ADR title | Current decision status | Recommendation |
| Candidate | Draft ADR | Status | Policy reach |
| --- | --- | --- | --- |
| C1 | Use native YAML inspection and separate documents for combined scopes | YAML/JSON and combined-display principles accepted; some operational details remain proposed | Record the accepted principles first. |
| C2 | Define the standard inspection surface and complete-family conformance | Ownership/completeness principles established; exact inventory proposed | Resolve the standard's operator responsibilities and required capabilities. |
| C3 | Model inspection through complete named configuration scopes | Scope model and most defaults proposed; combined display accepted | Resolve with provider API design. |
| C4 | Apply one CLI grammar through registered metadata | Shared parsing/presence established; particular grammar rules proposed | Resolve before fixing adapter behavior. |
| C5 | Use one configuration selection path with controlled domain input extensions | Extension/ownership boundary established; detailed selection policy proposed | Resolve before provider and binding APIs are fixed. |
| C6 | Inspect captured effective state without executing application work | Library/runtime ownership established; detailed inspection lifecycle proposed | Resolve with scope and provider design. |
| C7 | Compare semantic configuration snapshots with explicit sensitivity gaps | Semantic diff and its comparison policy proposed | Resolve with the upstream inspection capability design. |
| C8 | Return explicit invocation outcomes and separate reports from diagnostics | Outcome/process ownership established; public outcome model and status policy open | Resolve alongside invocation API design. |
| C9 | Identify the CLI standard separately from application build identity | Separate CLI standard revision proposed; Go/CLI compatibility already policy | Resolve before version reporting and first publication. |
| C2 | [0004: Standard inspection surface](../adr/0004-standard-inspection-surface.md) | Proposed | Standard operation purposes and capability-based availability. |
| C8 | [0005: Invocation outcomes](../adr/0005-invocation-outcomes.md) | Proposed | Shared Go/CLI classification, streams, and process integration. |
| C4 | [0006: Command grammar and vocabulary guidance](../adr/0006-command-grammar.md) | Proposed | Common parsing, discovery, and vocabulary guidance across command families. |
| C1 | [0007: Native YAML reports](../adr/0007-native-yaml-reports.md) | Proposed | Initial report formats and combined inspection presentation. |
| C6 | [0008: Captured inspection lifecycle](../adr/0008-inspection-lifecycle.md) | Proposed | Data ownership, acquisition effects, and inspection lifetimes. |
| C3 | [0009: Configuration scopes](../adr/0009-configuration-scopes.md) | Proposed | Declared provider capabilities and configuration view selection. |
| C5 | [0010: Configuration selection](../adr/0010-configuration-selection.md) | Proposed | Root, overlay, context, and override input semantics. |
| C7 | [0011: Semantic configuration diff](../adr/0011-semantic-configuration-diff.md) | Proposed | One operation's comparison and sensitivity policy. |
The review sequence proceeds from the broad standard surface through common
invocation, grammar, and reporting policy. It then covers
inspection lifecycle and provider boundaries, specific configuration inputs, and
finally semantic comparison. This ordering reflects policy reach; implementation
sequencing remains with the numbered roadmaps.
Candidate C9, a separate integer CLI standard revision, was rejected during
review. The tagged CommandKit release version identifies the library and its
standard CLI contracts under the adopted release compatibility policy.
The accepted YAML principles carried by draft 0007 retain their existing
planning authority, while the consolidated record and its additional details have
Proposed status. The existing accepted ADRs 0001–0003 remain authoritative.
The following scopes distinguish existing commitments from recommendations.
An accepted principle does not automatically approve every adjacent paragraph
of the CLI proposal.
### C2. Define standard operations by family and declared capability
**Recorded direction:** each family defines its resources and supported operations;
CommandKit assembles handlers from declared capabilities and exposes availability.
Shared verbs retain consistent meanings. Version reporting defaults to the
application, with explicit `--scope commandkit` selecting the embedded library.
**Review status:** capability-based installation, scoped version reporting, and
consumer-policy boundaries were agreed during review. The initial operation
inventory and remaining detailed contracts retain their prior Proposed status in
[ADR 0004](../adr/0004-standard-inspection-surface.md).
Implementation: [CLI inventory](01-cli-plan.md#3-recommended-command-inventory) and
[delivery work](01-cli-plan.md#10-implementation-dependencies-and-delivery).
### C8. Return explicit invocation outcomes and separate reports from diagnostics
**Decision to resolve:** a public outcome/error model that distinguishes usage
errors, failed valid operations, and application domain results; selected standard
status mappings; report/diagnostic channels; warning and writer-failure behavior.
**Why an ADR:** the model crosses handlers, adapter translation, output, and the
application entry point. It affects Go error identity and subprocess compatibility.
Concrete status values in the CLI plan are still proposals.
**Recommendation:** preserve existing application process/outcome ownership and
backend-error isolation. Favor explicit classification over message matching and
single diagnostic emission. Select stdout/stderr policy, standard mappings, and
partial-output behavior with the invocation API. C1 owns format selection; this
record owns result classification and delivery semantics.
Sources: [reports and statuses](01-cli-plan.md#9-output-diagnostics-and-failures),
[dispatcher outcome work](02-dispatch.md#2-public-api-design),
[adapter diagnostics](03-backend.md#diagnostics-and-outcomes), and
[facade error conversion](04-facade.md#2-api-and-internal-representation-design).
### C4. Apply one CLI grammar through registered metadata
**Decision to resolve:** options after the complete command path, interspersed
leaf operands/options, `--`, singleton repetition, ordered repeatable values, and
how the selected mechanics apply to custom commands.
**Why an ADR:** grammar is a suite-wide compatibility contract that must survive
backend updates or replacement. Cobra/pflag selection alone does not select it.
**Recommendation:** evaluate the proposed grammar as one coherent policy and
implement selected differences from backend defaults centrally. Preserve the
already selected presence and typed-input model; do not repeat its rationale in
a new record. Detailed spelling and operand counts belong in command references.
Sources: [grammar proposal](01-cli-plan.md#flag-placement-and-repeated-flags),
[backend presence/repetition work](03-backend.md#presence-and-repetition), and
[existing typed-input decision](../adr/0001-command-dispatch-and-inputs.md#typed-inputs-with-explicit-bindings).
### C1. Use native YAML inspection and separate documents for combined scopes
**Decision to record:** the initial implementation defers JSON without promising
@@ -71,109 +140,50 @@ Sources: [accepted planning decisions](01-cli-plan.md#accepted-planning-decision
[output formats](01-cli-plan.md#9-output-diagnostics-and-failures), and
[backend report integration](03-backend.md#provider-integration-and-native-reports).
### C2. Define the standard inspection surface and complete-family conformance
### C6. Coordinate captured inspection through the provider boundary
**Decision to resolve:** which operator responsibilities constitute the core
inspection standard, which belong to the optional PromptKit family, and what
complete adoption requires once those capabilities are available. The proposed
surface distinguishes source inventory from path explanation, effective
configuration from definition metadata, and inspection from mutation/execution.
**Recorded direction:** CommandKit lazily requests provider results, coordinates
declared dependencies, reuses compatible captures within its own invocation, and
queries supported public inspection views. Its standard handlers perform
inspection; callback effects and application execution remain consumer choices.
**Why an ADR:** the chosen responsibilities determine bundled handlers, provider
requirements, and the infrastructure applications can delete. This is a policy
choice beyond a list of command spellings.
**Review status:** the ownership clarification was agreed. Shared execution and
inspection loading is recommended guidance. Detailed capture and validation
contracts retain Proposed status in
[ADR 0008](../adr/0008-inspection-lifecycle.md).
**Recommendation:** use the proposed core/optional division as the starting point.
Select the inventory deliberately, including whether semantic diff is required
for core conformance despite its upstream dependency. Preserve the existing
complete-family/no-placeholder boundary. Delivery phases and deferred product
ideas remain roadmap material; exact commands belong in the future CLI reference.
Implementation: [validation](01-cli-plan.md#config-validate),
[display](01-cli-plan.md#config-show), and
[upstream work](01-cli-plan.md#10-implementation-dependencies-and-delivery).
Sources: [inventory](01-cli-plan.md#3-recommended-command-inventory),
[delivery and conformance](01-cli-plan.md#10-implementation-dependencies-and-delivery),
[deferred commands](01-cli-plan.md#11-explicitly-deferred-commands), and
[existing capability decision](../adr/0001-command-dispatch-and-inputs.md#explicit-registry-and-capability-installation).
### C3. Select named scopes with declared inspection capabilities
### C3. Model inspection through complete named configuration scopes
**Recorded direction:** scope metadata identifies configuration targets and their
available operations. Configuration scopes and library command families are
independent integration points. A missing comparison or provenance capability
leaves other supported operations available.
**Decision to resolve:** stable scope identities, a complete inspection capability
per scope, scope dependencies and reuse, and the meaning/applicability of `all`.
Select the proposed application inspection default versus all-scope validation
default deliberately.
**Review status:** capability-based scope support was agreed. Scope defaults,
aggregate coverage behavior, ordering, and exact provider declarations remain
proposals in [ADR 0009](../adr/0009-configuration-scopes.md).
**Why an ADR:** one scope abstraction can remove duplicated operation trees and
support future integrations. Requiring complete scopes versus partial capability
sets changes public provider design and consumer obligations.
Implementation: [scope work](01-cli-plan.md#4-configuration-scopes) and
[provider API work](02-dispatch.md#2-public-api-design).
**Recommendation:** prefer complete semantic scopes over separate operation trees.
Resolve the required provider capabilities, loading dependencies, and treatment
of unavailable operations with C2 and C6. Decide whether public providers use
CommandKit-owned contracts or deliberately selected ConfigKit/PromptKit types;
ADR 0003 establishes the boundary but leaves that API choice open.
### C5. Parse and propagate inspection selection inputs
Sources: [configuration scopes](01-cli-plan.md#4-configuration-scopes),
[dispatcher API work](02-dispatch.md#2-public-api-design), and
[facade representation work](04-facade.md#2-api-and-internal-representation-design).
**Recorded direction:** CommandKit preserves presence, validates declared selector
applicability, and passes typed inputs to the registered provider. Application-root
and ConfigKit overlay selectors apply to compatible providers; additional source
models use the input extension mechanism.
### C4. Apply one CLI grammar through registered metadata
**Review status:** shared loading is consumer guidance. Source discovery and
application execution remain application-owned. Exact selector semantics and
provider declarations retain Proposed status in
[ADR 0010](../adr/0010-configuration-selection.md).
**Decision to resolve:** options after the complete command path, interspersed
leaf operands/options, `--`, singleton repetition, ordered repeatable values, and
how the selected mechanics apply to custom commands.
**Why an ADR:** grammar is a suite-wide compatibility contract that must survive
backend updates or replacement. Cobra/pflag selection alone does not select it.
**Recommendation:** evaluate the proposed grammar as one coherent policy and
implement selected differences from backend defaults centrally. Preserve the
already selected presence and typed-input model; do not repeat its rationale in
a new record. Detailed spelling and operand counts belong in command references.
Sources: [grammar proposal](01-cli-plan.md#flag-placement-and-repeated-flags),
[backend presence/repetition work](03-backend.md#presence-and-repetition), and
[existing typed-input decision](../adr/0001-command-dispatch-and-inputs.md#typed-inputs-with-explicit-bindings).
### C5. Use one configuration selection path with controlled domain input extensions
**Decision to resolve:** reuse application discovery and selection across execution
and inspection, common root/overlay selectors, typed configuration overrides, and
registered domain selectors with explicit applicability to operations/scopes.
**Why an ADR:** a second discovery/resolution path can inspect different state
from actual execution. Extension choices also determine how applications express
real domain context while CommandKit retains its standard-family ownership.
**Recommendation:** favor one application-owned acquisition path and ConfigKit's
recorded override/resolution mechanisms. Resolve selector applicability, invalid
combinations, path interpretation, and no-fallback behavior for explicit inputs.
Do not infer a universal filesystem discovery convention from shared CLI syntax.
Sources: [selection and overrides](01-cli-plan.md#configuration-selection-and-overrides),
[dispatcher binding work](02-dispatch.md#2-public-api-design), and
[existing input-extension boundary](../adr/0001-command-dispatch-and-inputs.md#ownership-and-namespace-structure).
### C6. Inspect captured effective state without executing application work
**Decision to resolve:** expose the owning libraries' final captured views,
coordinate dependency loading once per invocation, and distinguish configuration
validation and definition inspection from runtime preflight, request preparation,
provider calls, and application execution.
**Why an ADR:** this establishes which effects inspection may cause and which
state reports describe. It prevents reconstruction from mutable runtime structs
or reparsing YAML, and supports clear provider lifetimes.
**Recommendation:** prefer captured owning-library inspection APIs and preserve
their resolution, provenance, and redaction semantics. Specify configuration
validation scope, credential requirements, and acquisition effects explicitly;
offline inspection must not silently become a credential-independent guarantee.
Keep request-specific rendering and operational checks application-owned.
Sources: [validation](01-cli-plan.md#config-validate),
[effective display](01-cli-plan.md#config-show),
[PromptKit definitions](01-cli-plan.md#7-promptkit-definition-inspection), and
[upstream capability work](01-cli-plan.md#10-implementation-dependencies-and-delivery).
The basic library/runtime ownership boundary already exists in ADR 0001.
Implementation: [selection inputs](01-cli-plan.md#configuration-selection-and-overrides)
and [binding work](02-dispatch.md#2-public-api-design).
### C7. Compare semantic configuration snapshots with explicit sensitivity gaps
@@ -194,69 +204,19 @@ Coordinate the comparison outcome with C8 rather than defining it twice.
Sources: [semantic diff](01-cli-plan.md#config-diff) and
[structured inspection dependencies](01-cli-plan.md#10-implementation-dependencies-and-delivery).
### C8. Return explicit invocation outcomes and separate reports from diagnostics
## 3. Review sequence and decision status
**Decision to resolve:** a public outcome/error model that distinguishes usage
errors, failed valid operations, and application domain results; selected standard
status mappings; report/diagnostic channels; warning and writer-failure behavior.
1. Review 0004 for standard responsibilities and capability-based availability.
2. Review 0005–0007 for outcomes, grammar, and report formats shared across the
standard suite and common invocation mechanics.
3. Review 0008–0010 for captured inspection, provider scopes, and configuration
selection. Their contracts need to fit together during API design.
4. Review 0011 for semantic comparison and its upstream sensitivity requirements.
**Why an ADR:** the model crosses handlers, adapter translation, output, and the
application entry point. It affects Go error identity and subprocess compatibility.
Concrete status values in the CLI plan are still proposals.
**Recommendation:** preserve existing application process/outcome ownership and
backend-error isolation. Favor explicit classification over message matching and
single diagnostic emission. Select stdout/stderr policy, standard mappings, and
partial-output behavior with the invocation API. C1 owns format selection; this
record owns result classification and delivery semantics.
Sources: [reports and statuses](01-cli-plan.md#9-output-diagnostics-and-failures),
[dispatcher outcome work](02-dispatch.md#2-public-api-design),
[adapter diagnostics](03-backend.md#diagnostics-and-outcomes), and
[facade error conversion](04-facade.md#2-api-and-internal-representation-design).
### C9. Identify the CLI standard separately from application build identity
**Decision to resolve:** whether applications report an explicit CLI standard
revision distinct from application and module versions; its meaning, ownership,
change rules, and relationship to module releases and consumer adoption.
**Why an ADR:** a new compatibility identifier creates a durable versioning axis.
The adopted release policy already covers Go and CLI compatibility, but does not
define a separate standard-revision scheme.
**Recommendation:** consider the proposed explicit revision if it gives operators
and subprocess consumers actionable information. Compare it with deriving the
signal from the CommandKit module version before introducing another maintained
identifier. Record that tradeoff; routine build-info fields and output spelling
belong in the CLI reference.
Sources: [version proposal](01-cli-plan.md#version),
[consumer migration](01-cli-plan.md#10-implementation-dependencies-and-delivery),
[backend compatibility work](04-facade.md#4-completion-and-later-replacement), and
[release compatibility policy](../policy/release.md#versioning-and-compatibility).
## 3. Suggested order
1. Record C1's already accepted principles; keep unresolved adjacent details
proposed. Existing ADRs 0001–0003 already cover the other accepted architectural
foundations from the numbered roadmaps.
2. Resolve C2, C3, C5, and C6 together to establish the inspection surface and
provider responsibilities before fixing public API declarations. Combine
records if the eventual choices are inseparable and one coherent rationale
is clearer.
3. Resolve C4 and C8 alongside binding/invocation API design, before adapter
defaults become observable commitments.
4. Resolve C7 with the upstream snapshot/sensitivity contract; it may precede
implementation of the diff command without blocking native YAML display.
5. Resolve C9 before exposing a new standard-revision field or publishing its
compatibility meaning.
This is a drafting sequence, not a requirement to produce nine ADRs before any
implementation. Select records according to the significance of actual decisions.
When a decision changes an accepted ADR, create a superseding record rather than
rewriting its decision content. None of these candidates currently requires
superseding the three existing records.
Each candidate has its own draft as requested. Related records can be reviewed
together while retaining their distinct policy responsibilities. The current
records are proposals for review; accepted decisions and existing implementation
plans retain their prior authority.
## 4. Items to keep outside separate ADRs for now
@@ -282,13 +242,67 @@ superseding the three existing records.
## 5. Handoff to durable records
For each selected candidate, capture context, decision, viable alternatives, and
consequences using the adopted ADR format. Assign the next sequential filename
when drafting the actual record. Keep candidate approval status accurate; listing
a recommendation here does not approve it.
The eight drafts use the adopted ADR format: title, status, date, context, decision,
alternatives considered, and consequences. Review and approval determine each
record's transition from Proposed to Accepted. Source commits preserve draft
status until that approval occurs.
Once a record owns architectural rationale, replace that rationale in non-owning
roadmaps with a link and retain implementation status and unresolved work. Update
the architecture or release policy only where the accepted choice establishes a
new normative rule. GoDoc and the implemented CLI reference remain the eventual
owners of exact public contracts.
## 6. Review of library authority and future expansion
Reviewed all eleven ADRs on 2026-10-06. The three agreed revisions were applied,
followed by a review of consumer mandates and unnecessary integration prerequisites.
ADRs 0001–0003 retain Accepted status; ADRs 0004–0011 remain Proposed. Approval of
individual review principles leaves other proposed choices at their prior status.
The drafts are committed for continued review with their Proposed status retained.
| ADR | Review finding and action |
| --- | --- |
| [0001](../adr/0001-command-dispatch-and-inputs.md) | Revised directly under the user override. Installation follows declared capabilities. Fresh input, lazy calls, domain-result preservation, and namespace checks now explicitly describe CommandKit behavior. Consumer structure and migration coordination are guidance. |
| [0002](../adr/0002-cobra-backend.md) | Clarified the existing backend boundary: CommandKit keeps Cobra internal; consumers can independently use other frameworks. Metadata-only tree construction describes CommandKit's work, with caller lifecycle retained. |
| [0003](../adr/0003-public-facade.md) | Retained root-owned contracts, adapter isolation, and deliberate future public-package decisions. Clarified that permitted public integration dependencies can include libraries beyond ConfigKit and PromptKit. |
| [0004](../adr/0004-standard-inspection-surface.md) | Removed universal core and PromptKit completeness prerequisites. Defined capability-based availability, consistent verb purposes, independent definition/configuration integration, and explicit version subjects. |
| [0005](../adr/0005-invocation-outcomes.md) | Scoped report and diagnostic rules to CommandKit's output through supplied streams. Caller output, final exits, and domain mappings remain caller-owned; outcome checking is guidance. |
| [0006](../adr/0006-command-grammar.md) | Limited grammar authority to commands dispatched by CommandKit. Preserved common parser behavior and added explicit version-subject selection. |
| [0007](../adr/0007-native-yaml-reports.md) | Limited format choices to the initial reports. Future families choose suitable report contracts. Loading and validation are expressed as provider-result requirements; custom formats remain caller-owned. |
| [0008](../adr/0008-inspection-lifecycle.md) | Separated implemented coordination, provider result contracts, and application guidance. Loading parity, callback internals, credential policy, and bootstrap effects remain consumer choices. |
| [0009](../adr/0009-configuration-scopes.md) | Removed the all-operations scope prerequisite. Added declared capabilities, discoverable support, independent command families, and explicit unsupported-selection diagnostics. |
| [0010](../adr/0010-configuration-selection.md) | Replaced the required shared consumer loader with reusable bindings and recommended practice. Selectors depend on provider applicability, allowing additional source models. |
| [0011](../adr/0011-semantic-configuration-diff.md) | Required safe comparison data only for enabled diff support. Left other operations independently available and scoped initial root/overlay bindings to compatible integrations. |
### Boundaries retained deliberately
- Reserved standard namespaces and registration conflict checks protect the agreed
ownership model. They constrain what CommandKit accepts through its API.
- Typed inputs, explicit presence, parser grammar, outcomes, and report semantics
define CommandKit behavior. Custom domain effects and report formats remain
application-owned.
- Root facade and internal Cobra isolation preserve the chosen public API boundary.
The initial backend and public-package choices permit later deliberate changes;
they are separate from a universal consumer framework policy.
- Safe data is required for the operation consuming it. A missing capability
affects that operation, rather than registration of unrelated capabilities.
### Remaining proposals and implementation questions
The scope defaults, aggregate coverage diagnostics, parser details, numeric status
mappings, and detailed comparison/report choices remain proposals until separately
approved. The revised scope proposal preserves `all` as all registered scopes and
reports unsupported coverage before loading; it leaves explicit supported
selections available. This is an operator-selection rule, not a completeness
requirement for registering an integration.
Public API work still needs proportionate capability declarations, dependency
identity, capture ownership, and diagnostics delivery. The design should make new
inspection capabilities additive where practical rather than extending one
mandatory provider interface with every future operation. Future family verbs,
resource models, source selectors, and formats belong to their respective contracts.
Architecture policy and CLI/dispatcher planning were aligned in this pass so old
completeness requirements and application-loading mandates do not reappear during
implementation. Durable ADRs retain links to other ADRs and policies only.