From a722bc1505da3309b6999b9fad0c8621491de34c Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 6 Oct 2026 19:36:02 -0500 Subject: [PATCH] Cleaned up documentation language --- COPYRIGHT | 5 - docs/adr/0001-command-dispatch-and-inputs.md | 30 +- docs/adr/0002-cobra-backend.md | 23 +- docs/adr/0003-public-facade.md | 32 +- docs/adr/0004-standard-inspection-surface.md | 4 +- docs/adr/0007-native-yaml-reports.md | 12 +- docs/adr/0008-inspection-lifecycle.md | 114 ------- ...md => 0008-semantic-configuration-diff.md} | 2 +- docs/adr/0010-configuration-selection.md | 100 ------ docs/roadmap/adr.md | 308 ------------------ docs/roadmap/policy.md | 106 ------ 11 files changed, 40 insertions(+), 696 deletions(-) delete mode 100644 docs/adr/0008-inspection-lifecycle.md rename docs/adr/{0011-semantic-configuration-diff.md => 0008-semantic-configuration-diff.md} (98%) delete mode 100644 docs/adr/0010-configuration-selection.md delete mode 100644 docs/roadmap/adr.md delete mode 100644 docs/roadmap/policy.md diff --git a/COPYRIGHT b/COPYRIGHT index 8b9b010..d213ba4 100644 --- a/COPYRIGHT +++ b/COPYRIGHT @@ -18,8 +18,3 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. Third-party code and assets are subject to their respective license terms. - -Policy documents adapted from Standard Repository Policies, the root AGENTS.md -orientation, and the Policy Reading Guide in docs/development.md remain licensed -under CC-BY-SA-4.0. See docs/oss/attribution.md for the affected material, -upstream credit, and license links. diff --git a/docs/adr/0001-command-dispatch-and-inputs.md b/docs/adr/0001-command-dispatch-and-inputs.md index f566ac6..e3b5f53 100644 --- a/docs/adr/0001-command-dispatch-and-inputs.md +++ b/docs/adr/0001-command-dispatch-and-inputs.md @@ -10,11 +10,12 @@ Accepted. ## Context -Audita, Narratio, Notarius, and Scriptorium repeat configuration inspection, -routing, parsing, help, and error handling. Their command vocabulary and syntax -have diverged. CommandKit aims to provide one implementation of standard -inspection, consistent vocabulary and mechanics, and less application -infrastructure. Application migrations are expected to make breaking changes. +Several downstream consumers of the ConfigKit and PromptKit libraries include +duplicated or near-duplicated code relating to configuration inspection, +routing, parsing, help, and error handling. However, their command vocabulary +and syntax have diverged. CommandKit aims to provide a single, unified CLI +implementation that will reduce duplication, provide consistent vocabulary and +grammar, and reduce the amount of code each individual applicaiton must own. Applications have genuine domain commands, such as Narratio's `session restore`, that remain outside the standard suite. Merely forwarding standard families from @@ -35,11 +36,13 @@ syntax diagnostics, and standard-family handlers and outcomes. Applications own custom command names, domain meaning, validation, effects, artifacts, and operational outcomes. -Use namespace/resource-first syntax for the standard suite. The `config` family -and an installed `promptkit` family belong to CommandKit. PromptKit definition -inspection uses the single `promptkit` namespace; root `prompt` and `profile` -names remain available to applications. This provides a clear family ownership -boundary without spreading a namespace across root verbs. +Use namespace-first syntax for the standard suite, which provides a clear +family ownership boundary. The initial release of CommandKit will ship with two +bundled standard command families: + (1) The `config` family provides ConfigKit inspection and validation; and + (2) the `promptkit` family provides PromptKit inspection and utilities. +CommandKit integrates ConfigKit and PromptKit through their supported public +semantics. CommandKit accepts custom commands outside its reserved standard families and reports registration errors for attempts to replace standard handlers or add @@ -49,8 +52,7 @@ selectors and typed overrides for standard operations. CommandKit accepts caller-supplied context, streams, handlers, and inspection providers and returns invocation outcomes. It leaves process termination to the caller. Executable startup, signals, runtime construction, schemas, acquisition, -and domain resolution remain application choices. CommandKit integrates ConfigKit -and PromptKit through their supported public semantics. +and domain resolution remain application choices. ### Explicit registry and capability installation @@ -159,8 +161,8 @@ resources, with standard meanings preserved for operations that are installed. | Both full dispatch and embeddable family handlers | Serves established external CLI architectures but adds integration surfaces and maintenance. Add embedding only for a concrete need. | | Raw-argument handlers for custom commands | Eases migration but leaves parsing and help responsibilities with applications. A future transition adapter would need to describe its separate parsing and help contract. | | Universal application runtime framework | Could absorb startup and operational services, but expands beyond the demonstrated CLI boundary and domain ownership. | -| Verb-first standard paths | Groups actions but distributes namespace ownership among individual routes. Namespace/resource-first paths keep family ownership clear. | -| Reserve root `prompt` and `profile` | Provides short resource paths but consumes application namespaces. A single `promptkit` family gives the library one ownership boundary. | +| Verb-first standard paths | Groups actions, but distributes namespace ownership among individual routes. Namespace/resource-first paths keep family ownership clear. | +| Reserve root `prompt` and `profile` for PromptKit | Provides short resource paths but consumes application namespaces. A single `promptkit` family gives the library one ownership boundary. | ### Registration diff --git a/docs/adr/0002-cobra-backend.md b/docs/adr/0002-cobra-backend.md index e43f289..77b35fc 100644 --- a/docs/adr/0002-cobra-backend.md +++ b/docs/adr/0002-cobra-backend.md @@ -15,16 +15,6 @@ generated help, usage diagnostics, and invocation execution. Reimplementing this generic infrastructure would add work beyond the suite-specific inspection and consistency behavior that motivates the library. -Cobra and urfave/cli v3 were the finalists. The latter's destination bindings and -duplicate controls offered a close fit for the explicit-input model. The author -strongly preferred Cobra because of its broader adoption. Familiarity and the -availability of contributors who know the framework are useful maintenance -considerations across several related applications. - -The selection was based on documentation and API review. Ecosystem adoption is -the selection rationale, not evidence that every backend default is an appropriate -CommandKit contract. - ## Decision Use Cobra with pflag as the sole initial CLI backend. CommandKit translates its @@ -39,10 +29,6 @@ getters stay within CommandKit's internal adapter. Independent consumer framewor use remains application-owned. [ADR 0003](0003-public-facade.md) records the adapter and root-owned public contracts. -Applications retain process lifecycle and domain execution. ConfigKit and -PromptKit retain configuration and inspection semantics. Framework selection -does not transfer those responsibilities to Cobra or CommandKit. - Build fresh backend command/flag state and input storage per invocation. A fresh command tree constructed from registered definitions is the initial approach. CommandKit's tree construction uses registered metadata and leaves acquisition @@ -76,14 +62,7 @@ features do not expand the standard automatically: for example, completion commands remain deferred unless deliberately selected. Backend error handling must preserve application outcomes, avoid duplicate -diagnostics, and return control to the application's entry point. Native YAML -inspection and multi-document scope display remain integration work using the -owning libraries. Choosing a framework introduces no JSON report requirement. - -Exact dependency versions and attribution are selected when dependencies are -incorporated. Meaningful integration evidence must exercise the real adapter -against selected contracts. A dependency update or replacement can change CLI -behavior even with unchanged Go signatures and is subject to compatibility policy. +diagnostics, and return control to the application's entry point. The [architecture policy](../policy/architecture.md) owns normative boundaries. [ADR 0001](0001-command-dispatch-and-inputs.md) records the dispatcher and input diff --git a/docs/adr/0003-public-facade.md b/docs/adr/0003-public-facade.md index 593ad59..eab95d6 100644 --- a/docs/adr/0003-public-facade.md +++ b/docs/adr/0003-public-facade.md @@ -10,20 +10,20 @@ Accepted. ## Context -CommandKit needs room to change implementation while consumers retain stable -registration, input, and invocation contracts. Exposing backend assembly or -extension structures would let applications depend on details that maintainers -may later replace. +CommandKit needs room to change its internal implementation details while +consumers retain access to a stable external API. Exposing backend assembly or +extension structures would let applications ossify around implementation +details that maintainers may later decide to replace. -ConfigKit, PromptKit, and ReleaseKit demonstrate facades that own public types and -delegate through private state and explicit conversion. ConfigKit also translates -upstream YAML parser structures into an independent internal document model. -ReleaseKit has a second facade for a distinct lightweight runtime responsibility; -CommandKit has no corresponding requirement for another public package initially. +ConfigKit, PromptKit, and ReleaseKit demonstrate facades that own public types +and delegate through private state and explicit conversion. ConfigKit also +translates upstream YAML parser structures into an independent internal document +model. -The Cobra selection is compatible with dependency isolation. Public API -independence needs a genuine contract boundary, and keeping backend structures -out of shared internal representations also makes future replacement easier. +The selection of Cobra as an internal dependency is compatible with this +decision. Public API independence needs a genuine contract boundary, and +keeping backend structures out of shared internal representations also makes +future replacement easier. ## Decision @@ -46,8 +46,8 @@ values and returned errors must not provide indirect backend-object access. Standard contracts such as `context.Context` and `io.Writer` remain appropriate. Public types from integration libraries, such as ConfigKit and PromptKit, may -be selected as deliberate dependencies. Application input types remain application-owned. Go declarations -and GoDoc own exact exported contracts. +be selected as deliberate dependencies. Application input types remain application-owned. +Go declarations and GoDoc own exact exported contracts. Confine Cobra/pflag types and operations to an internal adapter. Registry logic, standard handlers, and shared definitions use CommandKit-owned representations. @@ -61,10 +61,6 @@ backend state per invocation. Introduce narrow internal interfaces where actual engine/adapter interaction justifies them; exact package names and splits remain implementation choices. -Use one concrete backend initially. There is no public backend interface, plugin -registry, or requirement for a second implementation. Replacement is a future -maintainer change. - Translate backend-owned syntax failures into CommandKit diagnostics and outcomes. Preserve useful public identity for application handler errors and cancellation according to the invocation contract. Explicit conversions must preserve value diff --git a/docs/adr/0004-standard-inspection-surface.md b/docs/adr/0004-standard-inspection-surface.md index f82439f..77c61f1 100644 --- a/docs/adr/0004-standard-inspection-surface.md +++ b/docs/adr/0004-standard-inspection-surface.md @@ -10,7 +10,7 @@ Proposed ## Context -CommandKit serves applications with shared configuration and PromptKit inspection +CommandKit serves applications with shared ConfigKit and PromptKit inspection 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. @@ -21,7 +21,7 @@ decisions are the operator questions the initial standard answers. ## Decision -CommandKit supplies help and version reporting and defines configuration and +CommandKit supplies help and version reporting and defines ConfitKit 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. diff --git a/docs/adr/0007-native-yaml-reports.md b/docs/adr/0007-native-yaml-reports.md index 61c6523..2ba9594 100644 --- a/docs/adr/0007-native-yaml-reports.md +++ b/docs/adr/0007-native-yaml-reports.md @@ -14,16 +14,15 @@ ConfigKit and PromptKit provide native YAML configuration inspection. Reusing their writers preserves captured value semantics, ordering, and redaction. YAML also supports automated consumption of structured reports. -The agreed initial direction is YAML-based structured inspection with JSON -deferred, and separate native documents for `config show --scope all`. The -remaining choices concern report defaults, document framing, and when output -begins relative to configuration loading. +The agreed initial direction is YAML-based structured inspection and separate +native documents for `config show --scope all`. The remaining choices concern +report defaults, document framing, and when output begins relative to +configuration loading. ## Decision The initial standard uses text for concise operator reports and YAML for -structured consumption. JSON retains deferred status; a future format extension -is evaluated against a concrete consumer need. +structured consumption. | Operation | Default report | Available initial formats | | --- | --- | --- | @@ -78,6 +77,7 @@ Report confidentiality follows the owning libraries' sensitivity classifications Their safe writers and records supply redacted content. CommandKit preserves those confidentiality semantics; arbitrary caller content retains the caller's disclosure policy. + Report delivery uses the supplied streams and the channel policy in ADR 0005. Configuration path syntax follows ConfigKit's JSON Pointer contract independently of serialization format. diff --git a/docs/adr/0008-inspection-lifecycle.md b/docs/adr/0008-inspection-lifecycle.md deleted file mode 100644 index 5a83301..0000000 --- a/docs/adr/0008-inspection-lifecycle.md +++ /dev/null @@ -1,114 +0,0 @@ -# ADR 0008: Coordinate inspection through provider-supplied captured views - -## Status - -Proposed - -## Date - -2026-10-06 - -## Context - -Operators use inspection to understand effective configuration and definitions. -An owning library's captured view gives values, provenance, and definition -metadata a coherent source. Application callbacks provide acquisition and domain -resolution that CommandKit cannot independently implement or audit. - -[ADR 0001](0001-command-dispatch-and-inputs.md) establishes lazy registration and -the boundary between library contracts and application guidance. This decision -covers CommandKit's use of loaded views and its invocation-local coordination. - -## Decision - -### CommandKit behavior - -CommandKit invokes the registered provider when an inspection operation needs -its data. Standard handlers consume the provider's captured inspection views -through supported public contracts. Effective display uses final values supplied -by that view; source inventory and explanation use its provenance; definition -operations use its catalogs and resolved targets. - -CommandKit coordinates declared dependencies and reuses compatible provider -results within an invocation. It requests each distinct resolved selection once -through that coordination path. Semantic diff requests independently resolved -left and right captures under [ADR 0011](0011-semantic-configuration-diff.md). -Provider-internal loading remains outside this coordination boundary. - -`config validate` invokes the registered validation capability for each selected -scope and propagates its result. The PromptKit integration requests its public -configuration-validation operation, whose intended coverage is all configured -definitions. CommandKit uses the upstream operation's documented semantics; -additional upstream capabilities are needed where the public API lacks that -coverage. - -CommandKit's inspection handlers acquire views, query them, validate through the -registered capability, and write reports. Model execution, request preparation, -capacity admission, artifact production, and operational preflight are domain -handler responsibilities outside the standard inspection family. - -Help, version, and scope discovery use registration metadata independently of -inspection capture. Construction and those metadata operations leave acquisition -callbacks uninvoked. - -### Provider contract - -An inspection provider supplies views with the semantics required by its declared -operation. For the ConfigKit and PromptKit integrations, CommandKit consumes their -supported public inspection results and native writers. It preserves supplied -presence, resolution, provenance, and confidentiality semantics. - -The provider boundary communicates selection identity, declared dependencies, -applicable operations, loading failures, and acquisition diagnostics. Loading and -validation steps are those required to produce the owning API's inspection result. -CommandKit requires the corresponding result contract, while the callback's -internal organization remains application-owned. - -Acquisition can read files, environment values, or credentials and can perform -application-selected bootstrap work. CommandKit propagates supplied diagnostics -under [ADR 0005](0005-invocation-outcomes.md) and exposes supplied requirements in -help. Its coordination contract governs its own calls; callbacks retain their own -effects. CommandKit's API offers acquisition and inspection hooks independently -of application runtime construction. - -CommandKit integrations adopt upstream capabilities through supported public -APIs. Secret classification and native rendering follow those APIs. New catalog, -comparison, or profile inspection support is an integration dependency for its -respective operation. - -### Recommended application practice - -Sharing loading and domain-resolution code between inspection and execution is -recommended: equivalent inputs can then produce equivalent effective values and -provenance. Acquisition callbacks are best kept focused on producing those views, -with application work performed by execution handlers. - -These recommendations describe useful consumer structure. Applications control -their execution pipeline, callback implementation, credential lifecycle, and -bootstrap policy. CommandKit's decisions govern the hooks it offers and how its -handlers use the results. - -## Alternatives considered - -| Alternative | Analysis | -| --- | --- | -| Render mutable runtime configuration structs | Gives direct access to application values. Captured provenance, presence, and resolution need additional synchronization. | -| Reparse effective YAML for catalogs and queries | Uses available serialized data. CommandKit assumes upstream schemas and reconstructs definition semantics. | -| Include operational preflight in standard inspection | Adds readiness information. Inspection acquires provider-execution and state-management responsibilities. | -| Prescribe one consumer loading implementation | Encourages equivalent reports and execution. CommandKit has no authority over arbitrary callback or application internals. | -| Promise credential-independent acquisition | Simplifies an operator expectation. Actual upstream and callback loading requirements may require credentials. | - -## Consequences - -CommandKit reports describe provider-supplied captured state and preserve its -supported semantics. Dependency coordination reduces repeated provider calls -within an invocation. Shared loading is available as integration guidance. - -The API needs clear result ownership, callback lifetime, dependency identity, -and diagnostic delivery. Report accuracy depends on the registered provider's -contract. Acquisition requirements and effects remain visible as supplied -integration metadata. - -The [scope model](0009-configuration-scopes.md) and -[selection contract](0010-configuration-selection.md) define related target and -input behavior. Application execution remains outside these library decisions. diff --git a/docs/adr/0011-semantic-configuration-diff.md b/docs/adr/0008-semantic-configuration-diff.md similarity index 98% rename from docs/adr/0011-semantic-configuration-diff.md rename to docs/adr/0008-semantic-configuration-diff.md index cb77dfe..a4cb094 100644 --- a/docs/adr/0011-semantic-configuration-diff.md +++ b/docs/adr/0008-semantic-configuration-diff.md @@ -1,4 +1,4 @@ -# ADR 0011: Compare semantic snapshots with explicit sensitivity gaps +# ADR 0008: Compare semantic snapshots with explicit sensitivity gaps ## Status diff --git a/docs/adr/0010-configuration-selection.md b/docs/adr/0010-configuration-selection.md deleted file mode 100644 index f4eb3c5..0000000 --- a/docs/adr/0010-configuration-selection.md +++ /dev/null @@ -1,100 +0,0 @@ -# ADR 0010: Parse and propagate standardized inspection selection inputs - -## Status - -Proposed - -## Date - -2026-10-06 - -## Context - -Configuration inspection needs explicit selection inputs and domain context, such -as Narratio's campaign selectors. Shared flag meanings and presence tracking make -those inputs understandable. Source discovery, acquisition, and resolution are -implemented by application integration callbacks. - -[ADR 0001](0001-command-dispatch-and-inputs.md) establishes typed bindings and the -standard-family extension boundary and limits policy to CommandKit's contracts -and behavior. - -## Decision - -CommandKit parses registered selection inputs, preserves explicit values and -presence, and passes them to the selected inspection provider. It offers reusable -bindings so custom execution handlers can receive equivalent selection inputs. -Provider capture follows [ADR 0008](0008-inspection-lifecycle.md). - -For integrations based on application configuration, `--config PATH` selects the -application root, including when targeting its PromptKit engine. CommandKit passes -that selection and applicable context to the registered provider. `--scope NAME` -selects the inspected configuration under [ADR 0009](0009-configuration-scopes.md). - -An explicit empty root path receives a usage error. An explicit relative CLI path -is interpreted against the invocation working directory. When the selector is -omitted, CommandKit delegates discovery to the registered acquisition callback. -It preserves explicit selection and returns source-loading failures from that -callback as operational failures. CommandKit adds no discovery retry after a -failed explicit selection. File-relative resource resolution belongs to the -owning upstream API or provider. - -The ConfigKit overlay integration uses `--overlay NAME`. Omission, an empty name, -and the exact name `default` select the base according to ConfigKit semantics; -other values select a named overlay. This selector describes configuration -composition. PromptKit execution-profile selection has its own resource identity. - -Selector registration describes applicable operations and scopes. CommandKit -exposes supported selectors and validates their applicability before loading. -Root selection applies to providers using the application root; ConfigKit -overlay selection applies to providers supporting that composition model. -Other integrations can declare their own source selectors through the same -extension mechanism, keeping shared names consistent where applicable. - -The binding API accepts typed configuration overrides and domain context selectors -with help, conversion, applicability, and domain-mapping metadata. Parsing -preserves explicitly supplied empty, false, and zero values, as well as the -registered type semantics of nullable inputs. Registration detects collisions -with standard flags. Parsing validates declared combinations and reports usage -errors under [ADR 0005](0005-invocation-outcomes.md). - -CommandKit propagates supplied discovery descriptions, environment requirements, -and defaults-only behavior into help. The provider implements those conventions. -The API passes typed override and context values to integration callbacks; field -mapping and recorded domain resolution are outside CommandKit's implementation. -PromptKit definition operations use the applicable selectors registered for their -provider and target the engine's definition-inspection capabilities. - -### Recommended application practice - -Sharing discovery, acquisition, and domain-resolution code between inspection and -execution helps equivalent inputs produce equivalent effective values. Reusing -these bindings and using ConfigKit's recorded override and resolution mechanisms -helps preserve provenance. Describing discovery and callback effects in help -helps operators understand acquisition requirements. - -These are consumer recommendations. Execution loading, source policies, and -internal application structure remain application choices. CommandKit's decision -covers parsing, validation of declared inputs, metadata, and callback propagation. - -## Alternatives considered - -| Alternative | Analysis | -| --- | --- | -| Require an explicit root for every operation | Gives visible selection. Limits discovered, defaults-only, and independently sourced configurations. | -| Define a universal filesystem discovery policy | Gives identical locations. Deployment and packaging become library policy. | -| Require one loading function for every consumer | Encourages inspection/execution parity. Prescribes application internals outside CommandKit's authority. | -| Offer only root, overlay, and scope selectors | Keeps declarations small. Domain context and additional source models need another entry path. | -| Generic `--set path=value` overrides | Supports arbitrary edits. Requires another value language, conversion contract, and discovery model. | - -## Consequences - -CommandKit supplies consistent input mechanics and extension points. Provider -metadata determines selector relevance, allowing future source models to fit -without implementing ConfigKit-specific composition. Callbacks receive enough -selection information to produce useful captured inspection results. - -Shared loading is recommended integration guidance. CommandKit can preserve and -propagate inputs; parity with actual application execution depends on consumer -implementation. Exact selectors and field mappings belong to their implemented -command contracts. diff --git a/docs/roadmap/adr.md b/docs/roadmap/adr.md deleted file mode 100644 index 3bfa167..0000000 --- a/docs/roadmap/adr.md +++ /dev/null @@ -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. diff --git a/docs/roadmap/policy.md b/docs/roadmap/policy.md deleted file mode 100644 index 79565f0..0000000 --- a/docs/roadmap/policy.md +++ /dev/null @@ -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.