Simplify ADRs and relax premature constraints

docs/adr/0001-command-dispatch-and-inputs.md

@@ -15,7 +15,7 @@ duplicated or near-duplicated code relating to configuration inspection,
 routing, parsing, help, and error handling. However, their command vocabulary
 and syntax have diverged. CommandKit aims to provide a single, unified CLI
 implementation that will reduce duplication, provide consistent vocabulary and
-grammar, and reduce the amount of code each individual applicaiton must own. 
+grammar, and reduce the amount of code each individual application must own.
 
 Applications have genuine domain commands, such as Narratio's `session restore`,
 that remain outside the standard suite. Merely forwarding standard families from
@@ -37,11 +37,9 @@ custom command names, domain meaning, validation, effects, artifacts, and
 operational outcomes.
 
 Use namespace-first syntax for the standard suite, which provides a clear
-family ownership boundary. The initial release of CommandKit will ship with two
+family ownership boundary. The initial standard command families are `config`
-bundled standard command families:
+for ConfigKit inspection and validation, and `promptkit` for PromptKit inspection
-    (1) The `config` family provides ConfigKit inspection and validation; and
+and utilities. CommandKit integrates these libraries through their supported public
-    (2) the `promptkit` family provides PromptKit inspection and utilities.
-CommandKit integrates ConfigKit and PromptKit through their supported public 
 semantics.
 
 CommandKit accepts custom commands outside its reserved standard families and
@@ -100,10 +98,10 @@ 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.
 
-CommandKit creates fresh input storage per invocation and keeps its previous
+CommandKit keeps parsed values, collections, and presence from one invocation out
-parsed values, collections, and presence out of subsequent invocations. Handler
+of subsequent invocations. Storage allocation and reuse are implementation
-closures and application state retain their own lifecycle. Fresh CommandKit state
+choices. Handler closures and application state retain their own lifecycle;
-addresses invocation lifetime; concurrent dispatch is a separate contract.
+concurrent dispatch is a separate contract.
 
 The invocation API supplies context and streams separately from CLI inputs.
 CommandKit creates its declarations and bindings from metadata and defers its
@@ -117,8 +115,9 @@ an exact public API.
 ### Outcomes and domain behavior
 
 Resolve the command and handle help/version before loading application state.
-For execution, allocate fresh inputs, apply shared parsing and operand checks,
+For execution, prepare independent invocation inputs, apply shared parsing and
-then invoke the typed handler. Return its invocation outcome to the application.
+operand checks, then invoke the typed handler. Return its invocation outcome to
+the application.
 
 CommandKit classifies shared usage errors and standard-family outcomes. Its
 handler result contract accepts application-specific outcomes and preserves their
@@ -179,7 +178,7 @@ resources, with standard meanings preserved for operations that are installed.
 | 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. CommandKit's fresh input contract remains separate from caller-owned object lifetimes; objects are an application option. |
+| Typed command objects | Can organize complex handlers. CommandKit's invocation-state 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. |
 
@@ -195,7 +194,8 @@ 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.
+without configuration, presence, independent invocation inputs, cancellation,
+and domain outcomes.
 CommandKit releases document intentional compatibility changes. Coordinated
 application documentation and subprocess-caller updates are recommended migration
 practices.

docs/adr/0002-cobra-backend.md

@@ -29,11 +29,12 @@ getters stay within CommandKit's internal adapter. Independent consumer framewor
 use remains application-owned. [ADR 0003](0003-public-facade.md) records the
 adapter and root-owned public contracts.
 
-Build fresh backend command/flag state and input storage per invocation. A fresh
+Invocations do not inherit parsed values or presence from previous invocations.
-command tree constructed from registered definitions is the initial approach.
+Rebuilding the backend command tree and input storage from registered definitions
-CommandKit's tree construction uses registered metadata and leaves acquisition
+is the initial implementation strategy; safe reuse remains an implementation
-callbacks uninvoked. Application startup and callback effects retain their own
+choice. CommandKit's tree construction uses registered metadata and leaves
-lifecycle.
+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
@@ -56,10 +57,10 @@ The framework supplies established generic CLI machinery. CommandKit still owns
 registration conflicts, reserved families, typed bindings and presence, standard
 help and diagnostics, provider integration, and selected reports and outcomes.
 
-The adapter must accommodate explicit empty/false/zero values, fresh state,
+The adapter must accommodate explicit empty/false/zero values, independent parsed
-selected repetition and operand rules, and help without configuration. Backend
+state, selected repetition and operand rules, and help without configuration.
-features do not expand the standard automatically: for example, completion
+Backend features do not expand the standard automatically: for example,
-commands remain deferred unless deliberately selected.
+completion commands remain deferred unless deliberately selected.
 
 Backend error handling must preserve application outcomes, avoid duplicate
 diagnostics, and return control to the application's entry point.

docs/adr/0003-public-facade.md

@@ -32,38 +32,39 @@ Define CommandKit's public named types there and expose only selected operations
 extension contracts, and documented methods. Handles keep implementation state in
 private fields.
 
-Implementation packages belong under Go's `internal/` boundary. Public code
+Straightforward implementation may live in the root package without expanding
-forwards inward with explicit wrappers and conversions; internal production
+its exports. Introduce internal packages, interfaces, and conversions where they
-packages do not import the root. Shared internal contracts live inside that
+simplify implementation or protect the backend boundary. Package organization and
-boundary. Additional public packages require a deliberate decision based on a
+the amount of internal layering follow implementation needs. Additional public
-durable consumer responsibility.
+packages require a deliberate decision based on a durable consumer responsibility.
 
 Do not alias public types to internal or backend types, anonymously embed those
 types to promote methods, or expose implementation bridge methods. Exported
 fields, signatures, variables, callbacks, interface methods, constraints, and
-method sets must not reveal internal or Cobra/pflag structures. Loosely typed
+method sets must not reveal internal or Cobra/pflag structures. CommandKit does
-values and returned errors must not provide indirect backend-object access.
+not expose its internal backend objects or backend-specific syntax errors through
+its public API, including through loosely typed values or returned errors.
+Caller-supplied values and errors retain their documented handling; this boundary
+does not require inspecting or transforming arbitrary application objects.
 
 Standard contracts such as `context.Context` and `io.Writer` remain appropriate.
 Public types from integration libraries, such as ConfigKit and PromptKit, may
-be selected as deliberate dependencies. Application input types remain application-owned. 
+be selected as deliberate dependencies. Application input types remain
-Go declarations and GoDoc own exact exported contracts.
+application-owned. Go declarations and GoDoc own exact exported contracts.
 
 Confine Cobra/pflag types and operations to an internal adapter. Registry logic,
-standard handlers, and shared definitions use CommandKit-owned representations.
+standard handlers, and shared definitions remain independent of backend structures.
 The adapter translates paths, descriptions, bindings, presence, callbacks, and
 selected help/outcome semantics into backend machinery. Do not reproduce Cobra's
 complete API through renamed wrappers.
 
-Typed input factories and handlers can cross the facade through private callbacks
+Preserve independent parsed state per invocation under
-without internal packages importing public declarations. Preserve fresh input and
+[ADR 0001](0001-command-dispatch-and-inputs.md). Factories, callbacks, and shared
-backend state per invocation. Introduce narrow internal interfaces where actual
+representations remain API and implementation design choices.
-engine/adapter interaction justifies them; exact package names and splits remain
-implementation choices.
 
 Translate backend-owned syntax failures into CommandKit diagnostics and outcomes.
 Preserve useful public identity for application handler errors and cancellation
-according to the invocation contract. Explicit conversions must preserve value
+according to the invocation contract. Any conversions must preserve value
 ownership, callback lifetime, presence, and supported error semantics.
 
 ## Alternatives considered
@@ -71,6 +72,7 @@ ownership, callback lifetime, presence, and supported error semantics.
 | Alternative | Analysis |
 | --- | --- |
 | Keep all machinery in the public root | Less forwarding, but harder consumer navigation and easier accidental public expansion. |
+| Require a forwarding-only root and separate internal representations | Enforces a uniform layering scheme. It can add duplicate types and callback plumbing before those mechanisms simplify implementation. |
 | Alias or embed implementation types | Less conversion code, but couples public type identity, fields, or method sets to internal choices. |
 | Hide Cobra only behind the public facade | Hides types from applications but allows backend structures to spread through internal logic, complicating replacement. |
 | Mirror Cobra's API with wrappers | Removes dependency names while preserving its conceptual coupling and compatibility surface. |
@@ -84,15 +86,10 @@ collaborators, and package boundaries can evolve. Useful application registratio
 capabilities still need a proportionate API; minimizing accidental exports must
 not recreate repetitive consumer infrastructure.
 
-Explicit forwarding and conversion require maintenance. Type identity, ownership,
+Forwarding and conversion add maintenance where used. Proportionate checks should
-method sets, callback lifetime, and error semantics must be protected by evidence,
+protect the public surface, backend isolation, and consumer behavior through the
-not inferred from package relocation.
+real adapter. The implementation determines which checks provide useful evidence;
-
+package relocation alone does not establish those properties.
-Compiled public API checks protect aliases, fields, signatures, constraints, and
-promoted methods. Import checks keep the backend in its adapter and internal
-production code independent of root. External-package tests protect consumer
-semantics through the real adapter. ConfigKit and ReleaseKit provide precedents
-for these checks without requiring their full validation workflows.
 
 Backend replacement can preserve the public Go API but must also preserve selected
 CLI behavior or follow the release policy for intentional incompatibilities.

docs/adr/0004-standard-inspection-surface.md

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

docs/adr/0005-invocation-outcomes.md

@@ -15,58 +15,47 @@ 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.
+Exact Go declarations remain part of facade API design under
+[ADR 0003](0003-public-facade.md).
 
 Use these mappings for CommandKit-owned commands:
 
 | Status | Meaning |
 | --- | --- |
-| `0` | The requested operation completed successfully, including help and completed comparison. |
+| `0` | The requested operation completed successfully. |
 | `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. |
+| `2` | The invocation failed command, flag, scope, format, operand, 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.
+when returning the handler's result. A custom domain status and a shared usage
-A custom domain status and a shared usage status may have the same numeric value;
+status may have the same numeric value; their explicit classifications retain
-their explicit classifications retain their distinct meanings. The application
+their distinct meanings. The application entry point controls final process
-entry point controls final process termination and status mapping.
+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
+conventionally stderr. Callers choose the streams. CommandKit assigns responsibility
-one delivery owner and one emission through the selected channel. The provider
+for presenting its diagnostics, avoids duplicate presentation through its own
-contract carries acquisition diagnostics and their delivery state so CommandKit
+paths, and reports write failures. Caller callbacks retain control of their own
-can present pending diagnostics once. CommandKit adapts backend
+output. CommandKit adapts backend syntax failures into its public classification
-syntax failures into its public classification and safe diagnostic presentation.
+and diagnostic presentation. Usage guidance accompanies usage errors; operational
-Usage guidance accompanies usage errors; operational failures receive diagnostics
+failures receive diagnostics appropriate to the failed operation.
-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
+failure is an operational failure.
-preserved where supplied by the owning library.
 
-Report writers use the application's supplied streams. Shell redirection provides
+A writer failure can leave a partial report and returns operational failure. The
-file output for the initial standard. A writer failure can leave a partial report
+outcome identifies incomplete delivery. Custom handler output remains
-and returns operational failure. The outcome identifies incomplete delivery;
+application-owned. [ADR 0007](0007-native-yaml-reports.md) covers `config show` report
-checking it before interpreting reports is recommended caller practice. Custom
+preparation; [ADR 0008](0008-semantic-configuration-diff.md) defines successful
-handler output remains application-owned. Multi-scope loading and ordering follow
+comparison, including differences and coverage gaps.
-[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
 
@@ -76,7 +65,6 @@ application or consuming script can interpret differences according to its task.
 | 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
 
@@ -84,11 +72,7 @@ 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
+The public result/error design must preserve cause and delivery failures across
-responsibility. Output failures may produce partial bytes; callers receive an
+handlers, writers, and the backend adapter. Diagnostic delivery bookkeeping
-outcome describing delivery failure. The public result/error design preserves
+remains API design work. Acceptance establishes the compatibility meaning of the
-these semantics
+status values and delivery rules across standard commands.
-through fresh invocation state and private adapter callbacks.
-
-Acceptance establishes the compatibility meaning of these status values and
-delivery rules across standard commands.

docs/adr/0006-command-grammar.md

@@ -11,16 +11,10 @@ Proposed
 ## 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
+commands. A concrete grammar makes option placement, operands, repetition, and
-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
@@ -36,25 +30,23 @@ Applications are encouraged to use standard verbs such as `help`, `list`, and
 [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
+selected command, options and declared operands may be interspersed. Operand
-and types come from registration; custom operand domain meaning belongs to the
+counts and types come from registration.
-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
+Registered metadata identifies each flag as singleton or repeatable. For a
-accepts one occurrence per invocation. Repetition across either supported spelling
+singleton, the last occurrence supplies its value, including when the invocation
-is a usage error. A repeatable flag accumulates values in invocation order.
+mixes supported spellings. A repeatable flag accumulates values in invocation order.
-Presence is recorded independently of defaults and values, preserving supplied
+Presence follows the typed-input contract in
-empty strings, false, and zero under the existing typed-input decision.
+[ADR 0001](0001-command-dispatch-and-inputs.md).
 
 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
+classification in [ADR 0005](0005-invocation-outcomes.md).
-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.
@@ -62,21 +54,8 @@ 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
+for execution requests; help uses registered metadata. Invalid paths and flag
-metadata. Invalid paths and flag names receive usage diagnostics.
+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
 
@@ -84,21 +63,16 @@ at that boundary, following [ADR 0002](0002-cobra-backend.md).
 | --- | --- |
 | 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. |
+| Reject repeated singleton flags | Detects repeated assignments, but prevents callers from assembling defaults followed by explicit overrides. |
 | 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.
+commands using CommandKit. Shared vocabulary guidance encourages consistent
-Typed bindings and metadata support consistent parsing and generated help.
+names for equivalent application-owned operations.
-Shared vocabulary guidance encourages consistent names for equivalent
-application-owned operations.
 
-The adapter carries the work needed to preserve the grammar across dependency
+The internal adapter must preserve the selected grammar across backend changes.
-updates. Contract evidence must cover repetition, mixed spellings, explicit
+The [CLI roadmap](../roadmap/01-cli-plan.md) tracks operation-specific syntax;
-presence, interspersed operands, `--`, help, and fresh state. Backend replacement
+the CLI reference will own detailed command signatures and examples when
-preserves the selected grammar under the release compatibility policy.
+implemented.
-
-The CLI reference owns detailed command signatures and examples when implemented.
-This record owns the common rules that apply across those signatures.

docs/adr/0007-native-yaml-reports.md

@@ -14,73 +14,39 @@ 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 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.
 
-| 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,
+order defined by [ADR 0009](0009-configuration-scopes.md). CommandKit supplies
-PromptKit next when registered, followed by additional scopes in identifier order.
+document separators and scope-label comments around native writer output. Each
-Each document begins with `---` and a `# scope: NAME` comment. A one-scope `all`
+scope retains its own value namespace and native rendering; the documents can
-selection uses the same labeled document form.
+be decoded individually.
 
-CommandKit writes the separators and comments around the native writer output.
+For `config show`, CommandKit checks operation availability for selected scopes
-Comments label scopes for operators; document order follows the registered scope
+before acquisition. It acquires all selected views and completes validation
-inventory. That framing offers callers an association between documents and
+required by those provider contracts before report output begins. A failure
-scopes. Each scope retains its own value namespace and native rendering.
+returns its diagnostic outcome before report writing. Other inspection operations
-The combined stream is an inspection report whose documents can be decoded
+define their own output timing. After writing begins, a writer failure may leave
-individually.
+partial bytes and returns operational failure under
-
+[ADR 0005](0005-invocation-outcomes.md).
-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.
+Additional families select formats appropriate to their resources. Custom handler
-Configuration path syntax follows ConfigKit's JSON Pointer contract independently
+formats remain application-owned. The [CLI roadmap](../roadmap/01-cli-plan.md)
-of serialization format.
+tracks per-operation formats, framing syntax, and report shapes; the implemented
+CLI reference will own their exact contracts.
 
 ## Alternatives considered
 
@@ -89,20 +55,18 @@ of serialization format.
 | 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. |
+| Write `config show` documents as each scope is acquired | 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
+contract.
-identification.
 
-Loading all scopes before output adds preparation time and allows a failure in
+Loading all selected scopes before `config show` output adds preparation time and
-one selected scope to prevent combined output. Explicit single-scope inspection
+allows a failure in one scope to prevent combined display. Explicit single-scope
-remains available for a narrower view. Writer failures remain visible through
+display remains available for a narrower view.
-outcomes and may leave partial output.
 
 Additional structured schemas are compatibility contracts owned by CommandKit.
 Native concatenation can use existing writers; semantic comparison separately

docs/adr/0008-semantic-configuration-diff.md

@@ -23,37 +23,13 @@ value semantics while making limited coverage visible to operators.
 
 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
+before acquisition. Providers supply captured results through the owning
-define the left side where applicable. The initial application-root/ConfigKit
+libraries' supported public inspection APIs.
-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
+compared recursively; ordered sequences are compared as whole values.
-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
@@ -67,9 +43,12 @@ 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
+schema belongs in the CLI reference when implemented. Selection syntax,
-returns success whether it finds differences or gaps; load, comparison, and
+inheritance rules, and detailed change records remain proposals in the
-writer failures use the operational failure classification in
+[CLI roadmap](../roadmap/01-cli-plan.md#config-diff).
+
+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
@@ -81,14 +60,13 @@ writer failures use the operational failure classification in
 | 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
+where sensitivity limits comparison. Whole-sequence comparison keeps
-comparison keep reports understandable and implementation scope focused.
+implementation scope focused at the cost of less detailed collection changes.
 
 Diff support depends on safe snapshots preserving value semantics and sensitivity.
 CommandKit applies this comparison policy to scopes declaring that capability.
@@ -96,6 +74,4 @@ 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
+assertion workflows.
-need evidence for presence, container replacement, sensitivity changes, and
-coverage gaps.

docs/adr/0009-configuration-scopes.md

@@ -15,13 +15,9 @@ 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`
+Configuration scopes and command families are distinct. A scope targets
-family can inspect feeds through its own verbs, independently of whether FeedKit
+configuration; a family defines operations on its own resources. A library
-configuration is also exposed as a configuration scope.
+integration can expose either or both.
-
-[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
 
@@ -32,16 +28,17 @@ 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
+path explanation, and safe semantic comparison data. CommandKit validates declared
-identity, supported operations, applicable selectors, and dependencies.
+wiring and registers operations supplied by at least one scope under
-CommandKit checks the wiring needed by each declared capability. Additional
+[ADR 0004](0004-standard-inspection-surface.md). Help and scope discovery report
-operations can be supported as their upstream data becomes available.
+actual capabilities from metadata, independently of file loading.
 
-Expose scope operations through CommandKit-owned public provider contracts.
+Define narrow integration contracts, reusing upstream public types where useful
-Adapters preserve supported upstream values, provenance, and confidentiality.
+and introducing CommandKit-owned abstractions where they simplify integration.
-Exact Go declarations remain API design work under
+Preserve supported upstream values, provenance, and confidentiality. Select
-[ADR 0003](0003-public-facade.md). Separate capability contracts allow new
+provider representations against concrete integration needs; exact Go declarations
-operations to evolve independently of existing provider implementations.
+remain API design work under
+[ADR 0003](0003-public-facade.md).
 
 `--scope NAME` selects one configuration. `all` denotes all registered scopes for
 `config validate` and `config show`; `sources`, `explain`, and `diff` select one.
@@ -50,30 +47,14 @@ availability across the requested selection before acquiring views. An unavailab
 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
+`show`, `sources`, `explain`, `diff`, and `validate` default to `app`. Explicit
-`all`. Explicit selection remains available for narrower validation. These
+`--scope all` requests aggregate validation or display.
-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
+show use that order. [ADR 0007](0007-native-yaml-reports.md) defines combined
-operations, and selection defaults entirely from metadata. Discovery is available
+presentation. Acquisition coordination and selector details remain design work
-independently of file loading.
+tracked in the [CLI roadmap](../roadmap/01-cli-plan.md).
-
-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
 
@@ -83,9 +64,9 @@ family, configuration scope, or both, according to the provided capabilities.
 | 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. |
+| Validation defaults to `all` | Checks every scope implicitly, but adding a scope without validation support can make bare validation unavailable. |
 | 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. |
+| Require CommandKit-owned provider types throughout | Gives a uniform abstraction boundary, but can duplicate upstream APIs and require unnecessary adapters. |
 
 ## Consequences
 
@@ -94,9 +75,6 @@ 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
+An `all` request can report unsupported coverage; default application inspection
-report unsupported coverage; an explicit supported scope remains available.
+remains independent of other scopes' capabilities. Provider design must balance
-The same verb purpose can serve different families with different operation sets.
+simple wiring against dependency coupling as concrete integrations are developed.
-
-[Selection inputs](0010-configuration-selection.md) define parsing and propagation;
-[native YAML reporting](0007-native-yaml-reports.md) defines combined presentation.