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

Cleaned up documentation language

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-06 19:36:02 -05:00
parent 84234275eb
commit a722bc1505
11 changed files with 40 additions and 696 deletions
Download Patch File Download Diff File Expand all files Collapse all files

308
docs/roadmap/adr.md
View File

@@ -1,308 +0,0 @@
# CommandKit ADR candidates
Status: eight draft ADRs are Proposed and await review and approval.
Date: 2026-10-06.
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
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,
report fields, and implementation tasks generally belong in their canonical
references or roadmaps. The [documentation policy](../policy/documentation.md#architecture-decision-records)
owns ADR format and lifecycle.
## 1. Decisions already recorded
| Existing record | Roadmap coverage | Decisions already captured |
| --- | --- | --- |
| [ADR 0001](../adr/0001-command-dispatch-and-inputs.md) | 01 and 02 | CommandKit-owned dispatch; reserved standard families and namespace/resource-first syntax; the single `promptkit` namespace; explicit per-instance registries and command groups; capability installation and lazy providers; typed inputs, presence, fresh state, and application lifecycle/outcome ownership. |
| [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. |
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
| Candidate | Draft ADR | Status | Policy reach |
| --- | --- | --- | --- |
| 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
future delivery; combined `config show --scope all` uses separate native YAML
documents, with application configuration followed by registered PromptKit
configuration. The CLI plan also marks document separators and scope comments
as accepted combined-display behavior.
**Why an ADR:** this preserves owning-library rendering and avoids a second
serialization model or merged configuration schema. It determines automated
consumption and makes the multi-document versus single-wrapper tradeoff durable.
**Recommendation:** record those accepted choices now. Keep operation-specific
text/YAML defaults, exact structured report schemas, and the proposed policy for
loading all scopes before output and handling failures distinct until selected.
Detailed output contracts remain in the roadmap until implemented, then move to
the CLI reference.
Sources: [accepted planning decisions](01-cli-plan.md#accepted-planning-decisions),
[`config show`](01-cli-plan.md#config-show),
[output formats](01-cli-plan.md#9-output-diagnostics-and-failures), and
[backend report integration](03-backend.md#provider-integration-and-native-reports).
### C6. Coordinate captured inspection through the provider boundary
**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.
**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).
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).
### C3. Select named scopes with declared inspection capabilities
**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.
**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).
Implementation: [scope work](01-cli-plan.md#4-configuration-scopes) and
[provider API work](02-dispatch.md#2-public-api-design).
### C5. Parse and propagate inspection selection inputs
**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.
**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).
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
**Decision to resolve:** effective-value comparison rather than rendered line
diffs, absence/null/container distinctions, sequence treatment, independently
resolved selections, and incomplete comparison when sensitivity hides values.
**Why an ADR:** identical redaction masks do not establish equality. Comparing
two snapshots requires a deliberate sensitivity policy and an upstream data
contract; this cannot be settled by a formatter or string-matching heuristic.
**Recommendation:** favor semantic snapshots supplied by the owning libraries,
the proposed union of both sides' sensitivity classifications, and explicit
not-comparable paths. Resolve sequence granularity, comparison/report outcomes,
and available safe snapshot data before treating these choices as accepted.
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).
## 3. Review sequence and decision status
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.
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
- Exact command spellings, flags, report fields, and defaults should be defined
by their owning CLI contracts after the significant policy choices above are
settled. Do not make an ADR per subcommand or YAML field.
- Exact constructor/binding signatures, presence type names, and option
conveniences remain API design work. Create another ADR only if their choice
introduces a significant architectural tradeoff beyond existing typed bindings.
- Illustrative internal package names, forwarding helpers, and concrete checker
mechanics are implementation choices. Facade ownership and boundary protection
are already recorded in ADR 0003.
- Library version pins and ordinary attribution maintenance follow adopted OSS
policy. They are not new ADRs merely because dependencies are introduced.
- Delivery phases, application adoption order, and deferred product ideas remain
roadmap material. Initial breaking adoption and application ownership already
have established rationale.
- Public backend selection, concurrent dispatch, and extra extension frameworks
have no new demonstrated requirement in these roadmaps. Do not invent decisions
or guarantees for them to fill the ADR inventory.
- Adopted repository policy rules need no duplicate ADR catalog here. A deliberate
exception or substantive new policy tradeoff may warrant a record when it arises.
## 5. Handoff to durable records
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.

106
docs/roadmap/policy.md
View File

@@ -1,106 +0,0 @@
# CommandKit policy adoption and follow-up
Status: initial adoption and decision alignment complete; implementation-specific
follow-up pending.
Date: 2026-10-06.
This document records completion of the initial adoption and retains work tied to
future library implementation. Local policies are authoritative. Architectural
rationale now belongs in ADRs, and the implementation roadmaps retain pending
work. The CLI proposal keeps its accepted choices and remaining recommendations.
## 1. Adopted baseline
The seven policies were adapted from Standard Repository Policies at:
`d84a38ebab26f048cafbe59a2246700c35d29843`
The selected commit is available in the local upstream checkout and is the
baseline used by PromptKit, ConfigKit, and ReleaseKit. Adoption used that fixed
revision rather than relying on remote freshness. Each local policy preserves its
base version, records the actual adoption date, and links to its source file at
that commit. Updates require deliberate review under
[policy provenance](../policy/meta.md) and the upstream adoption guide.
| Adopted policy | Base version | Adaptation |
| --- | --- | --- |
| [Meta](../policy/meta.md) | 1.0 | Local authority, provenance, and upstream navigation. |
| [Agents](../policy/agents.md) | 1.3 | Proportionate implementation, explicit contract authority, and local commits. |
| [Architecture](../policy/architecture.md) | 1.3 | Dispatcher, registry, typed inputs, root facade, adapter, and ownership constraints. |
| [Testing](../policy/testing.md) | 1.3 | Offline behavioral evidence and CommandKit-specific risk priorities. |
| [Documentation](../policy/documentation.md) | 1.11 | Go API and CLI owners, ADR rationale, and roadmap implementation status. |
| [Release](../policy/release.md) | 1.4 | Source-only module publication and Go/CLI compatibility. |
| [OSS](../policy/oss.md) | 1.8 | Library grant, policy-document license scope, and factual attribution. |
Template adoption sections were removed. Reference examples remain upstream;
source and example links are pinned, while discovery links may track upstream
main. No automatic synchronization, recurring synchronization gate, or separate
license approval flow was added.
## 2. Initial adoption outcomes
- Root [AGENTS.md](../../AGENTS.md) preserves the supplied knowledge-graph
instructions and adds adopted contributor orientation.
- The [developer guide](../development.md) routes tasks to relevant policies and
gives proportionate current documentation validation guidance.
- [COPYRIGHT](../../COPYRIGHT) records the `LGPL-3.0-or-later` library grant and
separate CC-BY-SA-4.0 scope for adopted policies and copied orientation/reading
guidance. Existing independently supplied instructions remain outside that
copied-material scope.
- Root [LICENSE](../../LICENSE) retains the existing complete LGPL/GPL texts.
- [Attribution](../oss/attribution.md) identifies the exact adapted material and
commit-specific source/notices, with the standard CC-BY-SA text copied locally.
- The [README](../../README.md) gives truthful current status, navigation, and
grant/attribution links. No public API, executable, or release tooling is claimed.
The adopted agents policy authorizes local commits for completed units by default,
subject to explicit user instructions. It does not authorize pushing, publishing,
or history rewriting. Review and preserve unrelated work before committing.
## 3. Decision alignment
| Accepted decision | Durable owner | Pending implementation |
| --- | --- | --- |
| Dispatcher ownership, explicit per-instance registry, namespace boundary, and typed inputs | [ADR 0001](../adr/0001-command-dispatch-and-inputs.md) | [Dispatcher roadmap](02-dispatch.md) |
| Cobra/pflag as the sole initial backend | [ADR 0002](../adr/0002-cobra-backend.md) | [Backend roadmap](03-backend.md) |
| Root-owned public contracts and an internal Cobra adapter | [ADR 0003](../adr/0003-public-facade.md) | [Facade roadmap](04-facade.md) |
The architecture policy owns normative boundaries. Accepted ADRs preserve context,
choices, alternatives, and consequences without asserting that implementation
exists. The three implementation roadmaps now link to those records instead of
maintaining duplicate architectural rationale.
The [CLI proposal](01-cli-plan.md) remains the owner of future operator-contract
proposals and their individual approval status. Adoption did not approve the
remaining command inventory, grammar, exit statuses, or illustrative APIs.
## 4. Follow-up with implementation
| Work | Introduce when |
| --- | --- |
| Exact API declarations and GoDoc | Public registration, binding, provider, and invocation operations are implemented. |
| Task-oriented consumer guides and maintained examples | There are substantive supported consumer workflows. |
| `docs/cli.md` | Standard commands and operator contracts are implemented. |
| Internal inventory and subsystem documentation | Actual packages and mechanisms exist. |
| Cobra/pflag versions, notices, and license texts | Dependencies are incorporated; selection alone is not incorporation. |
| Proportionate boundary and consumer checks | Code introduces the public facade and backend adapter. |
| `docs/release.md`, publication tooling, and release notes | A releasable source module and working publication workflow exist. |
ConfigKit and PromptKit keep ownership of configuration and prompt semantics.
CommandKit documents their CLI exposure and links to their canonical contracts.
Select meaningful checks for actual CommandKit risks; do not inherit another
library's platform matrix, scanners, or validation gates automatically.
ReleaseKit remains a candidate for publication mechanics, not a selected
integration. Source-only releases are sufficient. Compatibility covers published
Go and CLI contracts, including parser behavior and YAML reports, even when Go
signatures are unchanged.
## 5. Completion boundary
Initial adoption comprises the customized policy set, supporting notices,
contributor navigation, and alignment of already accepted decisions. That work is
complete. The follow-up above remains future implementation scope; empty CLI/API
references, checker code, release scripts, and speculative dependency entries are
not prerequisites to policy adoption.