From 84234275eb3099567802636d9b9603432aa50622 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 6 Oct 2026 23:36:06 +0000 Subject: [PATCH] Record proposed CLI decisions and clarify CommandKit boundaries --- docs/adr/0001-command-dispatch-and-inputs.md | 130 ++++--- docs/adr/0002-cobra-backend.md | 17 +- docs/adr/0003-public-facade.md | 10 +- docs/adr/0004-standard-inspection-surface.md | 99 +++++ docs/adr/0005-invocation-outcomes.md | 94 +++++ docs/adr/0006-command-grammar.md | 104 ++++++ docs/adr/0007-native-yaml-reports.md | 110 ++++++ docs/adr/0008-inspection-lifecycle.md | 114 ++++++ docs/adr/0009-configuration-scopes.md | 102 ++++++ docs/adr/0010-configuration-selection.md | 100 +++++ docs/adr/0011-semantic-configuration-diff.md | 101 ++++++ docs/policy/architecture.md | 36 +- docs/roadmap/01-cli-plan.md | 185 ++++++---- docs/roadmap/02-dispatch.md | 10 +- docs/roadmap/adr.md | 362 ++++++++++--------- 15 files changed, 1243 insertions(+), 331 deletions(-) create mode 100644 docs/adr/0004-standard-inspection-surface.md create mode 100644 docs/adr/0005-invocation-outcomes.md create mode 100644 docs/adr/0006-command-grammar.md create mode 100644 docs/adr/0007-native-yaml-reports.md create mode 100644 docs/adr/0008-inspection-lifecycle.md create mode 100644 docs/adr/0009-configuration-scopes.md create mode 100644 docs/adr/0010-configuration-selection.md create mode 100644 docs/adr/0011-semantic-configuration-diff.md diff --git a/docs/adr/0001-command-dispatch-and-inputs.md b/docs/adr/0001-command-dispatch-and-inputs.md index 2012de0..f566ac6 100644 --- a/docs/adr/0001-command-dispatch-and-inputs.md +++ b/docs/adr/0001-command-dispatch-and-inputs.md @@ -41,23 +41,22 @@ 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. -Applications register commands outside reserved families. They cannot replace -standard handlers or add private operations underneath a reserved family. -Standard-family context selectors and typed overrides use the defined input -extension mechanism rather than introducing application-owned operations there. +CommandKit accepts custom commands outside its reserved standard families and +reports registration errors for attempts to replace standard handlers or add +private operations beneath them. Its input extension mechanism accepts context +selectors and typed overrides for standard operations. -Applications retain `main`, signal handling, context creation, stream selection, -runtime construction, and final process exit. CommandKit returns invocation -outcomes and does not terminate the process. Configuration schemas, acquisition, -domain resolution and validation, and provider construction remain application -integration responsibilities. ConfigKit and PromptKit retain their own -configuration, provenance, safe inspection, and native rendering semantics. +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. ### Explicit registry and capability installation -Each explicitly constructed application instance owns a registry. Applications -register individual commands and composable groups. There is no package-global -registry or import-time `init` registration. +Each explicitly constructed CommandKit instance owns a registry. Its API accepts +individual commands and composable groups. Registration uses explicit instance +state with caller-controlled construction and composition. Definitions provide paths, descriptions, flags and defaults, repetition and presence metadata, operand requirements, and execution handlers. One definition @@ -65,41 +64,49 @@ supplies routing, parsing, and help. Duplicate paths and attempts to replace reserved commands return registration errors; order does not select a winner. Help and version are installed automatically using supplied application identity -and build metadata. Configuration and PromptKit families are installed when the -application supplies their providers. Supplying a capability installs its complete -standard family, not a collection requiring manual operation-by-operation wiring. +and build metadata. CommandKit assembles standard families from declared provider +capabilities, installing their supported handlers and metadata together. Each +family defines its own resource model, supported verbs, and per-operation data +contracts. Configuration scopes declare their available inspection operations. -Registering providers does not execute them. Construction may diagnose missing -or invalid wiring without reading configuration, resolving credentials, or -building engines. Invalid configuration is an invocation-time failure. Command -declarations, help, and version remain available independently of application -initialization. The selected handler acquires dependencies when it needs them. +The API allows supported capabilities to be integrated independently. Adding +comparison, catalogs, or other inspection features extends the installed surface +according to the supplied providers. Shared verbs have consistent purposes across +families, while the available subsets reflect their resources and capabilities. +Help and discovery expose those subsets. Registration validates the wiring of +declared capabilities and reports unsupported selections before acquisition. -Do not install placeholder commands. Omitting the configuration provider does -not make a partial integration a complete core adopter. PromptKit is optional; -its selected family is installed as a complete capability. The CLI roadmap owns -the proposed command inventory and the remaining choices for that standard. +CommandKit registration validates declarations with acquisition callbacks left +uninvoked. Its construction, help, and version paths use metadata. The selected +handler requests dependencies when its operation needs them. Invalid configuration +returned by an acquisition callback is an invocation-time failure. Caller code +executed before registration and effects inside callbacks remain caller-owned. + +CommandKit installs handlers for supplied capabilities and describes actual +availability. Each enabled operation retains its standard meaning and output +contract. The exact operation inventory and remaining command contracts are +separate design decisions. ### Typed inputs with explicit bindings -Use application-defined input structs for custom commands and CommandKit-defined -inputs for standard handlers. Explicit registration binds flags and operands to -their input fields. The declarations also supply parsing and help metadata. -Handlers do not retrieve primitive values by flag name or parse the complete argv. +The public binding contract accepts application-defined input structs for custom +commands and uses CommandKit-defined inputs for standard handlers. Explicit +registration binds flags and operands to fields and supplies parsing and help +metadata. CommandKit delivers parsed typed inputs to registered handlers. -Use ordinary typed fields where omission has no separate meaning. Where it does, -keep supplied/not-supplied state beside the value in a presence-aware field. -Defaults do not mark input as explicitly supplied. Preserve explicit empty, -false, and zero values. +Bindings support ordinary typed fields and presence-aware fields where omission +has a separate meaning. CommandKit records supplied state independently of values +and defaults, preserving explicitly supplied empty, false, and zero values. -Create fresh input storage per invocation. Registered commands must not capture -one mutable input permanently or retain prior values, collections, or presence. -This decision addresses lifetime without establishing concurrent dispatch. +CommandKit creates fresh input storage per invocation and keeps its previous +parsed values, collections, and presence out of subsequent invocations. Handler +closures and application state retain their own lifecycle. Fresh CommandKit state +addresses invocation lifetime; concurrent dispatch is a separate contract. -Supply context and stream access separately from CLI inputs. Input declarations -and binding setup must not construct execution dependencies. Applications perform -domain validation and may interpret parsed domain values or supply a custom value -parser through the binding system. +The invocation API supplies context and streams separately from CLI inputs. +CommandKit creates its declarations and bindings from metadata and defers its +acquisition calls to the selected handler. The binding system accepts domain value +parsers; domain interpretation and validation belong to registered callbacks. The public factory, binding, registration, and handler signatures and presence type names remain API design choices. No illustrative declaration establishes @@ -111,17 +118,35 @@ Resolve the command and handle help/version before loading application state. For execution, allocate fresh inputs, apply shared parsing and operand checks, then invoke the typed handler. Return its invocation outcome to the application. -Shared usage errors and standard-family outcomes belong to CommandKit. Custom -handlers must communicate application-specific outcomes without silent generic -reclassification. For example, Scriptorium output validation and Notarius artifact -outcomes remain application concerns. Do not classify domain errors by matching -message strings or print usage unconditionally for runtime failures. +CommandKit classifies shared usage errors and standard-family outcomes. Its +handler result contract accepts application-specific outcomes and preserves their +supplied classification. Scriptorium output validation and Notarius artifact +outcomes, for example, remain domain results. CommandKit translates results from +explicit classification and emits usage guidance for usage failures. Common mechanics do not require a common success-report format for custom commands. The application owns its artifact and operational output contracts. Exact result/error interfaces and unresolved grammar choices are separate design work, not approvals implied by this decision. +### Contract scope and consumer guidance + +This decision governs CommandKit's public contracts and implemented behavior. +Each operation specifies the inputs, result semantics, callback lifetimes, and +metadata its provider supplies. Consumers choose how to implement those callbacks +and how to structure loading, execution, startup, and process status mapping. + +Sharing acquisition and resolution between inspection and execution, and keeping +acquisition focused on producing inspection views, are recommended practices. +CommandKit supports those patterns through reusable inputs and lazy provider +hooks. Its API preserves declared results and coordinates its own calls; arbitrary +application internals remain application-owned. + +Cobra isolation applies to CommandKit's exports and internal adapter. Independent +consumer use of another CLI library remains an application choice. Additional +families and source models can use capability contracts appropriate to their +resources, with standard meanings preserved for operations that are installed. + ## Alternatives considered ### Dispatcher and ownership @@ -132,7 +157,7 @@ work, not approvals implied by this decision. | Standard definitions mounted into an application's framework | Reuses routing infrastructure, but application configuration can preserve inconsistent behavior outside mounted families. Internal framework reuse remains compatible with this decision. | | Shared metadata/help with separate routing | Unifies discovery but adds synchronization among metadata, routing, and parsing. One dispatcher avoids it. | | 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 needs explicit limitations and is not full adoption. | +| 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. | @@ -152,7 +177,7 @@ work, not approvals implied by this decision. | Parsed-value accessor object | Uniform handlers, but string-based lookup, runtime type errors, and repeated assembly remain. | | Individual typed parameters | Clear for small commands; grows into long signatures and adapter machinery. Typed structs scale more naturally. | | Reflection and struct tags | Compact declarations, but adds a tag language, field-discovery rules, and runtime declaration validation. Explicit bindings keep declarations visible. | -| Typed command objects | Can organize complex handlers; must separate fresh input from dependency and execution lifetimes. Applications may use objects without making them mandatory. | +| Typed command objects | Can organize complex handlers. CommandKit's fresh input contract remains separate from caller-owned object lifetimes; objects are an application option. | | Generated bindings/adapters | Can combine compact authoring and typing, but adds tooling and generated-file maintenance without demonstrated need. | | Raw arguments | Simple routing integration, but returns common parsing and help to applications. | @@ -169,11 +194,10 @@ support consistent mechanics without requiring reflection or generated code. Shared parsing defects can affect every adopter. Consumer and backend integration evidence must protect selected semantics, including ownership conflicts, help without configuration, presence, fresh input, cancellation, and domain outcomes. -Intentional migration changes require coordinated application documentation and -subprocess-consumer updates. +CommandKit releases document intentional compatibility changes. Coordinated +application documentation and subprocess-caller updates are recommended migration +practices. The [architecture policy](../policy/architecture.md) owns normative boundaries. -The [dispatcher roadmap](../roadmap/02-dispatch.md) owns implementation status and -pending API design. The [CLI roadmap](../roadmap/01-cli-plan.md) retains command -proposals and their approval status. [ADR 0002](0002-cobra-backend.md) selects the -backend, and [ADR 0003](0003-public-facade.md) defines its public/internal boundary. +[ADR 0002](0002-cobra-backend.md) selects the backend, and +[ADR 0003](0003-public-facade.md) defines its public/internal boundary. diff --git a/docs/adr/0002-cobra-backend.md b/docs/adr/0002-cobra-backend.md index 9920742..e43f289 100644 --- a/docs/adr/0002-cobra-backend.md +++ b/docs/adr/0002-cobra-backend.md @@ -33,9 +33,11 @@ Reuse their routing, option parsing, help, context, and stream mechanisms and ad adaptation where selected CommandKit semantics require it. CommandKit retains its own public registration API, typed inputs, standard -families, and observable contracts. Applications do not construct Cobra commands -or use pflag getters in handlers. [ADR 0003](0003-public-facade.md) isolates the -backend behind an internal adapter and root-owned public contracts. +families, and observable contracts. Its public registration and handler APIs +use CommandKit-owned definitions and typed inputs. Cobra commands and pflag +getters stay within CommandKit's internal adapter. Independent consumer framework +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 @@ -43,7 +45,9 @@ 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. -Tree construction must not load configuration or create application runtime. +CommandKit's tree construction uses registered metadata and leaves acquisition +callbacks uninvoked. Application startup and callback effects retain their own +lifecycle. Implement one concrete backend. There is no initial public backend selector or pluggable framework. A future replacement can change internal implementation @@ -81,10 +85,9 @@ 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. -The [architecture policy](../policy/architecture.md) owns normative boundaries; -the [backend roadmap](../roadmap/03-backend.md) owns implementation tasks and status. +The [architecture policy](../policy/architecture.md) owns normative boundaries. [ADR 0001](0001-command-dispatch-and-inputs.md) records the dispatcher and input -model. Remaining command and grammar proposals belong to the CLI roadmap. +model. Reviewed primary references from the selection: diff --git a/docs/adr/0003-public-facade.md b/docs/adr/0003-public-facade.md index 4a053b4..593ad59 100644 --- a/docs/adr/0003-public-facade.md +++ b/docs/adr/0003-public-facade.md @@ -45,8 +45,8 @@ method sets must not reveal internal or Cobra/pflag structures. Loosely typed values and returned errors must not provide indirect backend-object access. Standard contracts such as `context.Context` and `io.Writer` remain appropriate. -ConfigKit or PromptKit public types may be selected as deliberate integration -dependencies. Application input types remain application-owned. Go declarations +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. Confine Cobra/pflag types and operations to an internal adapter. Registry logic, @@ -103,7 +103,5 @@ CLI behavior or follow the release policy for intentional incompatibilities. Backend defaults do not independently establish new CommandKit contracts. The [architecture policy](../policy/architecture.md) owns normative boundaries. -The [facade roadmap](../roadmap/04-facade.md) owns implementation status, package -layout illustrations, and pending work. [ADR 0001](0001-command-dispatch-and-inputs.md) -records the dispatcher/input model, and [ADR 0002](0002-cobra-backend.md) selects -the initial backend. The CLI roadmap retains individual command approval status. +[ADR 0001](0001-command-dispatch-and-inputs.md) records the dispatcher/input model, +and [ADR 0002](0002-cobra-backend.md) selects the initial backend. diff --git a/docs/adr/0004-standard-inspection-surface.md b/docs/adr/0004-standard-inspection-surface.md new file mode 100644 index 0000000..f82439f --- /dev/null +++ b/docs/adr/0004-standard-inspection-surface.md @@ -0,0 +1,99 @@ +# ADR 0004: Define standard inspection operations by family and capability + +## Status + +Proposed + +## Date + +2026-10-06 + +## Context + +CommandKit serves applications with shared configuration 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. + +[ADR 0001](0001-command-dispatch-and-inputs.md) establishes dispatch, registration, +capability-based installation, and the boundary of CommandKit policy. The remaining +decisions are the operator questions the initial standard answers. + +## Decision + +CommandKit supplies help and version reporting and defines configuration 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. + +| Standard operation | Responsibility | +| --- | --- | +| `help` | Describe registered standard and application commands. | +| `version` | Report application version by default; report embedded CommandKit version when explicitly selected. | +| `config scopes` | List registered configuration scopes and supported operations. | +| `config validate` | Validate the selected configuration and its configured definitions. | +| `config show` | Display final effective configuration. | +| `config sources` | Describe the acquired and synthetic input source inventory. | +| `config explain` | Explain effective or historical values and provenance at a selected path. | +| `config diff` | Compare effective configuration selections semantically. | + +The optional PromptKit suite supplies `promptkit list prompts`, +`promptkit list profiles`, `promptkit show prompt`, and `promptkit show profile`. +These operations expose captured definition catalogs, prompt metadata, and +backend-completed named execution targets. PromptKit definition capabilities and +its configuration scope are registered according to their available provider +operations. Either can be integrated independently. + +CommandKit assembles each installed family from its declared capabilities, keeping +standard handlers and metadata together. The inventory describes available +standard operations; adoption can use the supported subset. Semantic diff depends +on safe comparison snapshots for its selected scope. Its availability is +independent of display, validation, and other inspection capabilities. + +Shared verbs keep consistent purposes: `list` enumerates resources, `show` +displays a selected resource, and `diff` compares supported representations. Each +family specializes those purposes for its own resources. For example, a future +FeedKit family could supply `list` and `show` as its intended operation set. + +`app version` and root `app --version` report application version. The version +command defaults to `--scope app`; `app version --scope commandkit` reports the +embedded CommandKit release version. `--format` selects presentation of the same +subject. Future component identities can use registered version metadata. Version +subjects are independent of configuration scopes and loading providers. + +CommandKit owns vocabulary and observable contracts within its standard families. +Custom execution, rendering, serving, sessions, and artifact workflows retain +their application-owned meanings. Additional shared operations enter through +versioned CommandKit releases under the +[release policy](../policy/release.md#versioning-and-compatibility). + +The CLI reference owns exact flags, operands, defaults, and report schemas when +implemented. This record owns operation purposes and capability-based availability. + +## Alternatives considered + +| Alternative | Analysis | +| --- | --- | +| Initial operations limited to validation and display | Accelerates first integrations. Source explanation, comparison, and discovery remain repeated application infrastructure. | +| Require every operation for every integration | Gives a uniform inventory. One unavailable capability blocks other useful operations and future resource families. | +| Definition inspection through configuration operations alone | Source values and provenance share one path. Captured catalogs and completed execution targets require additional interpretation. | +| Standardize execution and mutation alongside inspection | Expands shared vocabulary to more workflows. Additional domain and state-management contracts require their own evidence and design. | +| Display dependency identities in ordinary application version output | Makes dependency information immediately visible. Application identity becomes coupled to dependency reporting. | +| A combined dependency-version option | Gives a useful diagnostic inventory. Scoped version reporting also supports selecting one identity. | + +## Consequences + +CommandKit supplies shared handlers with predictable meanings and discovers their +availability from registration. Each enabled operation needs its own data +contract: comparison needs safe snapshots, catalogs need enumeration, and profile +display needs safe execution-target inspection. + +Shared operations retain clear purposes. CommandKit release notes describe changes +to its published operations. Coordinated application documentation and caller +updates are recommended migration practices. + +Help and discovery describe actual supported capabilities. The +[scope model](0009-configuration-scopes.md), +[inspection lifecycle](0008-inspection-lifecycle.md), and +[comparison policy](0011-semantic-configuration-diff.md) describe the proposed +provider and behavioral contracts supporting this surface. diff --git a/docs/adr/0005-invocation-outcomes.md b/docs/adr/0005-invocation-outcomes.md new file mode 100644 index 0000000..36e38c0 --- /dev/null +++ b/docs/adr/0005-invocation-outcomes.md @@ -0,0 +1,94 @@ +# ADR 0005: Return explicit outcomes and deliver reports through defined channels + +## Status + +Proposed + +## Date + +2026-10-06 + +## Context + +An invocation crosses routing, parsing, provider acquisition, a standard or +application handler, report writing, and the application entry point. Operators +and subprocess consumers need consistent classifications for those stages. +Applications also have meaningful domain outcomes of their own. + +[ADR 0001](0001-command-dispatch-and-inputs.md) establishes process and domain +ownership. [ADR 0003](0003-public-facade.md) establishes public error and backend +boundaries. The remaining decisions concern the public outcome model, report +and diagnostic channels, and standard process-status mappings. + +## Decision + +CommandKit returns an invocation outcome with an explicit classification and +recommended process status. The public model distinguishes successful operation, +usage error, operational failure, and application domain outcome. Failures retain +their consumer-facing cause and supported `errors.Is`/`errors.As` identity. +Exact Go declarations remain part of facade API design. + +Use these mappings for CommandKit-owned commands: + +| Status | Meaning | +| --- | --- | +| `0` | The requested operation completed successfully, including help and completed comparison. | +| `1` | A syntactically valid operation failed during loading, validation, lookup, inspection, cancellation, diagnostics delivery, or report writing. | +| `2` | The invocation failed command, flag, scope, format, operand, repetition, or input-combination validation. | + +CommandKit's handler result contract accepts domain classifications and suggested +process statuses supplied by the caller. CommandKit preserves that classification +when returning the handler's result. +A custom domain status and a shared usage status may have the same numeric value; +their explicit classifications retain their distinct meanings. The application +entry point controls final process termination and status mapping. + +CommandKit writes standard reports to the supplied report stream, conventionally +stdout, and its warnings and errors to the supplied diagnostic stream, +conventionally stderr. Callers choose the streams. Each CommandKit diagnostic has +one delivery owner and one emission through the selected channel. The provider +contract carries acquisition diagnostics and their delivery state so CommandKit +can present pending diagnostics once. CommandKit adapts backend +syntax failures into its public classification and safe diagnostic presentation. +Usage guidance accompanies usage errors; operational failures receive diagnostics +appropriate to the failed operation. + +Warning severity alone permits a successful operation. A diagnostic writer +failure is an operational failure. Source coordinates and source-ID legends are +preserved where supplied by the owning library. + +Report writers use the application's supplied streams. Shell redirection provides +file output for the initial standard. A writer failure can leave a partial report +and returns operational failure. The outcome identifies incomplete delivery; +checking it before interpreting reports is recommended caller practice. Custom +handler output remains application-owned. Multi-scope loading and ordering follow +[the YAML report policy](0007-native-yaml-reports.md). + +A completed semantic comparison returns success with its differences and coverage +gaps recorded in the report. Its outcome describes successful inspection; the +application or consuming script can interpret differences according to its task. + +## Alternatives considered + +| Alternative | Analysis | +| --- | --- | +| A single failure classification | Simplifies outcome handling. Callers derive syntax, operational, and domain distinctions through additional interpretation. | +| Backend errors and output as the public outcome model | Reuses framework machinery directly. Backend conventions become dependencies for applications and subprocess consumers. | +| One common mapping for application domain failures | Produces uniform numeric statuses. Applications adapt existing artifact and execution outcomes to shared categories. | +| Handler-owned diagnostics for every failure | Gives each handler full presentation control. Shared diagnostic consistency requires repeated ownership and formatting coordination. | +| Dedicated file-output options | Adds direct file targeting. The standard acquires creation, replacement, and retention responsibilities alongside report writing. | + +## Consequences + +The outcome model supports both Go callers and executable entry points. Explicit +classification keeps domain identity intact through adapter and facade conversion. +Single diagnostic ownership supports predictable presentation. + +CommandKit handlers and writers coordinate cause propagation and delivery +responsibility. Output failures may produce partial bytes; callers receive an +outcome describing delivery failure. The public result/error design preserves +these semantics +through fresh invocation state and private adapter callbacks. + +Acceptance establishes the compatibility meaning of these status values and +delivery rules across standard commands. diff --git a/docs/adr/0006-command-grammar.md b/docs/adr/0006-command-grammar.md new file mode 100644 index 0000000..af71b4c --- /dev/null +++ b/docs/adr/0006-command-grammar.md @@ -0,0 +1,104 @@ +# ADR 0006: Apply common command grammar and recommend shared vocabulary + +## Status + +Proposed + +## Date + +2026-10-06 + +## Context + +CommandKit owns routing, parsing, and help for standard and registered application +commands. The selected registry and typed-input model supply a shared source for +syntax metadata. A concrete grammar makes option placement, operands, repetition, and +help predictable across the application suite. Shared vocabulary also reduces +the need to remember different verbs for equivalent operations. + +[ADR 0001](0001-command-dispatch-and-inputs.md) establishes namespace-first +ownership, typed bindings, explicit presence, and fresh invocation inputs. +The remaining choices concern option placement, operand handling, repetition, +and discovery behavior across registered commands. + +## Decision + +CommandKit's standard grammar and vocabulary are part of the contract for +CommandKit-owned commands. Its shared dispatcher and binding APIs implement that +grammar, so application-owned commands registered through those APIs receive the +same parsing mechanics. Applications retain ownership of their command names, +operand meanings, and domain behavior. + +CommandKit's documentation recommends the same grammar and vocabulary for +application-owned commands, including commands implemented outside its dispatcher. +Applications are encouraged to use standard verbs such as `help`, `list`, and +`show` where their operations have the corresponding purposes described in +[ADR 0004](0004-standard-inspection-surface.md). + +CommandKit parses options after the complete registered command path. Within the +selected command, options and declared operands may be interspersed. Operand counts +and types come from registration; custom operand domain meaning belongs to the +handler. + +Standard options use lowercase names with hyphen-separated words and the `--` +prefix. Value options accept `--name value` and `--name=value`. Boolean options +accept their documented presence form and explicit values such as `--name=false`. +The `--` token ends option parsing; subsequent tokens are operands. + +Registered metadata identifies each flag as singleton or repeatable. A singleton +accepts one occurrence per invocation. Repetition across either supported spelling +is a usage error. A repeatable flag accumulates values in invocation order. +Presence is recorded independently of defaults and values, preserving supplied +empty strings, false, and zero under the existing typed-input decision. + +CommandKit validates paths, flag names, conversions, operand counts, and declared +input combinations through the shared parser. Those failures use the usage +classification in [ADR 0005](0005-invocation-outcomes.md). Registered domain value +parsers and handlers receive values through the typed binding contract. + +Root help is available through `app`, `app help`, `app --help`, and `app -h`. +Invoking a command group with no registered execution handler displays group help. +A runnable command follows its registered handler and operand requirements, +including when it also has subcommands. CommandKit-owned groups such as `config` +display help on bare invocation. `app help COMMAND ...` and a resolved command's +`--help` display the same registered help. Required execution operands are checked +for execution requests; help uses resolved command and flag +metadata. Invalid paths and flag names receive usage diagnostics. + +`app version` and the root-only `app --version` shortcut report application version. +The version command also accepts explicit component selection under +[ADR 0004](0004-standard-inspection-surface.md). +Standard configuration operations have declared flag inputs. PromptKit collection +and definition commands declare their resource and ID operands. The registry +generates help, including supported formats and selector applicability, from +those declarations. + +The internal Cobra/pflag adapter implements this grammar using registered +metadata and backend parsing mechanisms. Flag values beginning with `-` follow +their registered type and supported value syntax. Parser adaptation is centralized +at that boundary, following [ADR 0002](0002-cobra-backend.md). + +## Alternatives considered + +| Alternative | Analysis | +| --- | --- | +| Flags before all operands | Gives argument order a simple positional rule. Operators organize values around that rule when assembling commands. | +| Common flags before or between command-path components | Supports familiar global-option styles. Routing and help need rules for options across several command levels. | +| Last singleton occurrence wins | Supports layered argv construction. Repeated assignments become an override mechanism requiring separate presence and precedence interpretation. | +| Application-selected parser conventions | Supports existing CLI implementations. Operators and shared help need per-application syntax knowledge. | + +## Consequences + +Operators learn one option placement and repetition policy for adopting +commands using CommandKit. Custom handlers retain their operand domain contracts. +Typed bindings and metadata support consistent parsing and generated help. +Shared vocabulary guidance encourages consistent names for equivalent +application-owned operations. + +The adapter carries the work needed to preserve the grammar across dependency +updates. Contract evidence must cover repetition, mixed spellings, explicit +presence, interspersed operands, `--`, help, and fresh state. Backend replacement +preserves the selected grammar under the release compatibility policy. + +The CLI reference owns detailed command signatures and examples when implemented. +This record owns the common rules that apply across those signatures. diff --git a/docs/adr/0007-native-yaml-reports.md b/docs/adr/0007-native-yaml-reports.md new file mode 100644 index 0000000..61c6523 --- /dev/null +++ b/docs/adr/0007-native-yaml-reports.md @@ -0,0 +1,110 @@ +# ADR 0007: Use native YAML and ordered documents for inspection reports + +## Status + +Proposed + +## Date + +2026-10-06 + +## Context + +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. + +## 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. + +| Operation | Default report | Available initial formats | +| --- | --- | --- | +| `help` | Text | Text | +| `version` | Text | Text, YAML | +| `config scopes`, `validate`, `sources`, `explain`, `diff` | Text | Text, YAML | +| `config show` | Native YAML | YAML | +| `promptkit list/show` | Text | Text, YAML | + +These format choices govern initial configuration and PromptKit reports and +version reporting. Additional families select formats appropriate to their own +resources through their command contracts. Custom handler formats remain +application-owned. Version format selection preserves the selected subject under +[ADR 0004](0004-standard-inspection-surface.md). + +Operations with a format choice use `--format text|yaml`. Format names are +lowercase. YAML-only display uses its native writer directly. Help presents its +registered text form. Format validation follows the usage outcome policy in +[ADR 0005](0005-invocation-outcomes.md). + +A single-scope `config show` writes the owning library's complete native redacted +YAML. Its output consists of the inspection document itself. The native writer +preserves effective presence, null and container distinctions, stable mapping +order, and sequence order according to its public contract. + +`config show --scope all` emits one native document per registered scope in the +order defined by [ADR 0009](0009-configuration-scopes.md): application first, +PromptKit next when registered, followed by additional scopes in identifier order. +Each document begins with `---` and a `# scope: NAME` comment. A one-scope `all` +selection uses the same labeled document form. + +CommandKit writes the separators and comments around the native writer output. +Comments label scopes for operators; document order follows the registered scope +inventory. That framing offers callers an association between documents and +scopes. Each scope retains its own value namespace and native rendering. +The combined stream is an inspection report whose documents can be decoded +individually. + +CommandKit checks operation availability for selected scopes before acquisition. +It acquires their views and completes validation required by those provider +contracts before report output begins. A failure returns its diagnostic outcome +before report writing. After writing begins, a writer failure may leave partial +bytes and returns operational failure under ADR 0005. + +Other structured reports use operation-specific YAML schemas and selection +metadata. They contain one document and a trailing newline. Native explanation +snapshots retain their safe YAML text and presence/redaction metadata when +projected into structured reports. The CLI reference owns exact schemas and +field names after implementation. + +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. + +## Alternatives considered + +| Alternative | Analysis | +| --- | --- | +| A scope-keyed YAML wrapper | Carries scope identity as parsed mapping keys. Rendering needs an additional wrapper representation and indentation of native documents. | +| JSON alongside YAML initially | Serves JSON-specific tools. The library maintains another serializer and representation contract. | +| YAML as every report's default | Provides uniform structured output. Interactive help, tables, and explanation workflows use structured documents for routine discovery. | +| Output each scope as acquisition finishes | Starts reporting earlier. A later acquisition failure can leave a successful prefix representing only part of the selection. | +| Marshal application runtime structs | Reuses application data types. Presence, captured resolution, ordering, and safe historical inspection need a separate rendering lifecycle. | + +## Consequences + +Native display preserves owning-library behavior and keeps rendering focused. +Combined inspection requires multi-document YAML consumption and an ordered scope +contract. The comments label documents, and the ordered inventory supports +identification. + +Loading all scopes before output adds preparation time and allows a failure in +one selected scope to prevent combined output. Explicit single-scope inspection +remains available for a narrower view. Writer failures remain visible through +outcomes and may leave partial output. + +Additional structured schemas are compatibility contracts owned by CommandKit. +Native concatenation can use existing writers; semantic comparison separately +requires the safe structured data described in +[ADR 0011](0011-semantic-configuration-diff.md). diff --git a/docs/adr/0008-inspection-lifecycle.md b/docs/adr/0008-inspection-lifecycle.md new file mode 100644 index 0000000..5a83301 --- /dev/null +++ b/docs/adr/0008-inspection-lifecycle.md @@ -0,0 +1,114 @@ +# 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/0009-configuration-scopes.md b/docs/adr/0009-configuration-scopes.md new file mode 100644 index 0000000..db45725 --- /dev/null +++ b/docs/adr/0009-configuration-scopes.md @@ -0,0 +1,102 @@ +# ADR 0009: Select named configuration scopes with declared inspection capabilities + +## Status + +Proposed + +## Date + +2026-10-06 + +## Context + +An application can expose its own configuration, PromptKit engine configuration, +and other independently meaningful configurations through the `config` family. +A scope identifies the configuration targeted by an operation. Different +providers may support different inspection operations. + +Configuration scopes and command families are distinct: a future `feedkit` +family can inspect feeds through its own verbs, independently of whether FeedKit +configuration is also exposed as a configuration scope. + +[ADR 0004](0004-standard-inspection-surface.md) defines initial operation purposes. +[ADR 0001](0001-command-dispatch-and-inputs.md) records +installation from declared capabilities. + +## Decision + +Use stable semantic scope identifiers. The `app` scope describes application +configuration; an optional `promptkit` scope describes captured engine +configuration. Registration also accepts additional independently meaningful +configuration scopes with unique identifiers. + +Each scope declares its available inspection operations and their providers. +Capabilities can include validation, native effective YAML, source inventory, +path explanation, and safe semantic comparison data. Scope metadata describes +identity, supported operations, applicable selectors, and dependencies. +CommandKit checks the wiring needed by each declared capability. Additional +operations can be supported as their upstream data becomes available. + +Expose scope operations through CommandKit-owned public provider contracts. +Adapters preserve supported upstream values, provenance, and confidentiality. +Exact Go declarations remain API design work under +[ADR 0003](0003-public-facade.md). Separate capability contracts allow new +operations to evolve independently of existing provider implementations. + +`--scope NAME` selects one configuration. `all` denotes all registered scopes for +`config validate` and `config show`; `sources`, `explain`, and `diff` select one. +An aggregate selection retains its all-scope meaning. CommandKit checks operation +availability across the requested selection before acquiring views. An unavailable +operation yields a usage diagnostic identifying the scope and available choices, +so an aggregate result accurately describes the requested coverage. + +`show`, `sources`, `explain`, and `diff` default to `app`; `validate` defaults to +`all`. Explicit selection remains available for narrower validation. These +selection defaults operate against the registered inventory and capabilities. + +Scope order is `app` first when registered, `promptkit` next when registered, +then additional scopes sorted by identifier. `config scopes` and combined YAML +show use that order. The inventory reports identity, description, supported +operations, and selection defaults entirely from metadata. Discovery is available +independently of file loading. + +CommandKit validates scope collisions, operation wiring, selector applicability, +and supported selections. It registers the standard operations supplied by at +least one scope, alongside metadata discovery. Help identifies their applicable +scopes; selection of an unsupported scope-operation pair yields a usage diagnostic. + +Declared dependencies are coordinated under +[ADR 0008](0008-inspection-lifecycle.md). An inspection operation acquires its +selected scope and required prerequisites through that provider boundary. + +A command family defines its own resources, supported verbs, and data contracts. +The configuration provider contract applies to configuration inspection. FeedKit +resource listing or display, for example, can use separate capabilities with +meanings consistent with shared verbs. A library integration can expose a command +family, configuration scope, or both, according to the provided capabilities. + +## Alternatives considered + +| Alternative | Analysis | +| --- | --- | +| Require every configuration inspection operation per scope | Gives one capability set. Missing comparison or provenance blocks other useful inspection operations. | +| A separate command tree for each configuration | Makes the target part of the path. Repeats common operations and help. | +| One verb set for every library family | Gives a uniform inventory. Resource domains acquire operations with little useful meaning. | +| Executable names as scope identifiers | Relates scopes to application branding. Shared scripts need application-specific identifiers. | +| Every operation defaults to `app` | Gives one selection default. Integrated validation becomes an explicit aggregate request. | +| Skip unsupported scopes during aggregate inspection | Produces available reports. The meaning and coverage of `all` become less apparent. | +| Public upstream result types as the provider API | Simplifies direct wiring. CommandKit acquires those type identities and release dependencies. | + +## Consequences + +A shared configuration family serves multiple configurations while help and +inventory make operation availability explicit. Individual capabilities can be +integrated before other upstream inspection APIs exist. Default and ordering +rules remain observable CommandKit behavior. + +Scoped operations validate availability before loading. An `all` request can +report unsupported coverage; an explicit supported scope remains available. +The same verb purpose can serve different families with different operation sets. + +[Selection inputs](0010-configuration-selection.md) define parsing and propagation; +[native YAML reporting](0007-native-yaml-reports.md) defines combined presentation. diff --git a/docs/adr/0010-configuration-selection.md b/docs/adr/0010-configuration-selection.md new file mode 100644 index 0000000..f4eb3c5 --- /dev/null +++ b/docs/adr/0010-configuration-selection.md @@ -0,0 +1,100 @@ +# 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/adr/0011-semantic-configuration-diff.md b/docs/adr/0011-semantic-configuration-diff.md new file mode 100644 index 0000000..cb77dfe --- /dev/null +++ b/docs/adr/0011-semantic-configuration-diff.md @@ -0,0 +1,101 @@ +# ADR 0011: Compare semantic snapshots with explicit sensitivity gaps + +## Status + +Proposed + +## Date + +2026-10-06 + +## Context + +Configuration comparison helps operators understand changes in final effective +values across roots and overlays. Formatting, authored file layout, and provenance +identifiers are different properties from effective-value equality. Sensitivity +classification also limits the values available for inspection. + +Meaningful comparison requires structured effective snapshots with per-path +sensitivity data from the owning libraries. The comparison policy must preserve +value semantics while making limited coverage visible to operators. + +## Decision + +For a scope declaring safe comparison support, `config diff` compares two +independently resolved effective configurations. CommandKit checks that capability +before acquisition. Registered root, overlay, context, and override selectors +define the left side where applicable. The initial application-root/ConfigKit +integration uses `--against-config PATH`, `--against-overlay NAME`, or both to +select the right side. Other comparison +source models can declare applicable paired selectors through the input extension +contract under [ADR 0010](0010-configuration-selection.md). + +Unspecified right selectors inherit the resolved left selection. Discovery is +resolved for the left selection once. An omitted right overlay inherits the left +overlay; the explicit overlay name `default` selects the base. Domain selectors +and typed overrides apply identically to both sides for the initial operation. +CommandKit requests each resolved side through the inspection provider under +[ADR 0008](0008-inspection-lifecycle.md). The provider supplies the captured result +according to its public loading and validation contract. + +Compare values using the owning library's safe structured inspection semantics, +including defaults and recorded domain resolution. Preserve the distinctions +among absent values, null, empty mappings, and empty sequences. Mappings are +compared recursively; ordered sequences are compared as whole values. A container +replacement produces one change at the replaced path. + +Changes are classified as `added`, `removed`, or `changed` and sorted by JSON +Pointer configuration paths, consistent with the ConfigKit integration. Reports +contain safe before/after snapshots and resolved selection metadata. Presentation +and source identity retain their own metadata roles, while value comparison +operates on the effective semantic representation. + +CommandKit's comparison provider contract accepts effective values and +sensitivity metadata through supported public inspection APIs. The comparison +handler consumes inspection-safe data and uses supplied redaction classifications. +Secret resolution remains part of the upstream or callback loading lifecycle. + +For each path, use the union of the two sides' sensitivity classifications to +protect both before and after presentation. A value classified on either side +receives the corresponding safe treatment in both snapshots. Hidden values +produce explicit comparison gaps with their paths and supported reasons. + +Equality conclusions cover the comparable data. A comparison with gaps reports +its limited coverage alongside observed differences. A complete comparison with +an empty difference set supports an equality conclusion for the inspected +selection. Redaction masks are presentation data; classification metadata +determines comparison coverage. + +Text and YAML reports include differences and coverage gaps. The exact report +schema belongs in the CLI reference when implemented. A completed comparison +returns success whether it finds differences or gaps; load, comparison, and +writer failures use the operational failure classification in +[ADR 0005](0005-invocation-outcomes.md). + +## Alternatives considered + +| Alternative | Analysis | +| --- | --- | +| Rendered YAML line comparison | Reuses native display output. Formatting and masking become part of change interpretation. | +| Compare masks as literal strings | Uses visible snapshot bytes directly. Equal masks express equal presentation while hidden values remain uncertain. | +| Use one side's sensitivity policy | Simplifies classification selection. A value's disclosure treatment depends on which snapshot supplies that policy. | +| Fetch secret values for comparison | Gives access to additional equality evidence. Comparison acquires sensitive material and additional confidentiality responsibilities. | +| Element-by-element sequence diff | Gives detailed collection changes. Stable element identity and alignment need another comparison contract. | +| Independent domain selectors for each side | Supports broader context comparison. The operation acquires duplicated selector sets and pairing rules. | +| A distinct status for observed differences | Supports assertion-oriented scripts. Inspection completion and change detection share an outcome signal. | + +## Consequences + +Operators receive meaningful effective-value changes with explicit uncertainty +where sensitivity limits comparison. Stable path ordering and whole-sequence +comparison keep reports understandable and implementation scope focused. + +Diff support depends on safe snapshots preserving value semantics and sensitivity. +CommandKit applies this comparison policy to scopes declaring that capability. +Other operations and families can be integrated independently under +[ADR 0004](0004-standard-inspection-surface.md). + +Applications can use the successful report as input to domain decisions or future +assertion workflows. Separate left/right loading and safe union classification +need evidence for presence, container replacement, sensitivity changes, and +coverage gaps. diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 31e96d3..1baf9cf 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -50,8 +50,8 @@ diagnostics, and the handlers and observable contracts of its standard families. Applications register domain commands outside those families and own their meaning, effects, domain validation, artifacts, and operational outcomes. Namespaces provide the ownership boundary: standard `config` and an installed -`promptkit` family remain CommandKit-owned. Applications do not replace their -handlers or add private operations beneath them. +`promptkit` family remain CommandKit-owned. CommandKit reports registration errors +for attempts to replace their handlers or add private operations beneath them. Applications own their executable entry points, context creation, signals, stream selection, runtime construction, and final process exit. CommandKit @@ -64,12 +64,25 @@ package-global or import-time registries. One definition supplies routing, parsing, and help metadata. Duplicate paths and attempts to replace reserved commands report errors rather than letting registration order select a winner. -Standard families are installed from supplied capabilities. Help and version use -application identity/build metadata; configuration and PromptKit providers install -their complete corresponding families. Provider registration is lazy and does -not acquire configuration or construct engines. Help and version remain available -with missing or invalid configuration. Do not install placeholder commands or -claim complete adoption for unsupported operations. +Standard families are assembled from declared provider capabilities. Each family +specifies its own resources and supported operations; shared verbs retain +consistent meanings across families. Configuration scopes describe their supported +inspection operations. CommandKit installs the supplied handlers and metadata and +reports actual availability through help and discovery. Missing upstream +capabilities leave other supported operations available. + +Help and version use identity/build metadata. CommandKit's registration and +metadata paths leave acquisition callbacks uninvoked. Help and version remain +available with missing or invalid configuration. Callers retain their startup and +callback effects. Version reporting defaults to application identity; explicit +component selection reports embedded library identity. + +These rules govern CommandKit's own API, dispatcher, and standard handlers. +Provider contracts define required inputs and results for enabled operations; +callback internals and application execution remain consumer choices. Shared +inspection/execution loading and focused acquisition callbacks are recommended +integration practices. Independent consumer use of other CLI frameworks remains +application-owned. ## Handler Inputs And Invocation State @@ -78,9 +91,10 @@ Use presence-aware fields where omission matters; preserve explicitly supplied empty, false, and zero values independently of parser defaults. Context, streams, and execution dependencies are separate from CLI inputs. -Create fresh input and backend command/flag state per invocation. Registered -commands must not retain input values, collections, or presence state across -runs. This does not establish a concurrent-dispatch guarantee. +CommandKit creates fresh input and backend command/flag state per invocation, +keeping its parsed values, collections, and presence out of subsequent runs. +Caller-owned closures and runtime state retain their own lifecycle. Concurrent +dispatch is a separate contract. Applications may interpret parsed domain values and provide domain value parsers through the binding system. Raw-argument parsing is not the primary handler model. diff --git a/docs/roadmap/01-cli-plan.md b/docs/roadmap/01-cli-plan.md index 0ffdf26..0c10a67 100644 --- a/docs/roadmap/01-cli-plan.md +++ b/docs/roadmap/01-cli-plan.md @@ -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 diff --git a/docs/roadmap/02-dispatch.md b/docs/roadmap/02-dispatch.md index c3e8e2c..56ae0ca 100644 --- a/docs/roadmap/02-dispatch.md +++ b/docs/roadmap/02-dispatch.md @@ -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 diff --git a/docs/roadmap/adr.md b/docs/roadmap/adr.md index e476c2a..3bfa167 100644 --- a/docs/roadmap/adr.md +++ b/docs/roadmap/adr.md @@ -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.