commandkit/docs/roadmap/01-cli-plan.md

# CommandKit CLI planning record

Status: initial CLI planning complete; remaining proposals deferred.

Original review: 2026-10-06. Reconciled: 2026-10-07.

## Purpose and current owners

This document preserves the initial command-suite review and identifies remaining
future work. Its completed implementation tasks and obsolete contract drafts
have been retired. The [initial feature target](initial.md) and
[completed implementation plan](implementation.md) record delivery scope and
execution history.

The [CLI reference](../cli.md) owns implemented commands, syntax, formats, and
outcomes. Go declarations and GoDoc own exact exported APIs; the
[consumer guide](../consumers/guide.md) explains integration. Accepted ADRs own
architectural rationale, and the [architecture policy](../policy/architecture.md)
owns responsibility boundaries. This planning record does not define a second
current command contract.

## Completed initial scope

| Planning area | Delivered boundary and current reference |
| --- | --- |
| Discovery and identity | Generated [help](../cli.md#help) and [version reporting](../cli.md#version). |
| Configuration inspection | [Scope discovery](../cli.md#configuration-scopes), validation, native display including aggregate display, sources, and path explanation. |
| PromptKit integration | Engine configuration scope and optional [named prompt/profile inspection](../cli.md#promptkit-definition-inspection), registered independently. |
| Common command infrastructure | Instance registry, typed inputs, presence, routing, and outcomes; see the [consumer guide](../consumers/guide.md) and [internal overview](../internal/overview.md). |

CommandKit owns its standard families. Applications retain custom commands,
source selection, schema/domain work, acquisition callbacks, and executable
lifecycle. Migration of existing applications remains separate work; the
maintained [simple](../../examples/simple/README.md) and
[composed](../../examples/composed/README.md) consumers demonstrate library usage.

## Superseded proposal choices

The following entries are historical reconciliation notes. They summarize why
older drafts no longer describe the selected implementation; use the linked
owner for the complete current contract.

| Earlier proposal, now superseded | Selected result and owner |
| --- | --- |
| Bare validation defaults to every scope | Configuration operations default to `app`; aggregate validation/display is explicit. See [configuration scopes](../cli.md#configuration-scopes). |
| Reject repeated singleton flags | Last occurrence supplies the value; every supplied occurrence is converted. See [registered syntax](../cli.md#registered-command-syntax). |
| Prompt inspection uses `--prompt-version` | It uses `--version`. See [definition inspection](../cli.md#promptkit-definition-inspection). |
| Rich profile reports await an upstream provider-parameter redaction API | Current public inspection supplies effective `ExtraParams`, included without additional redaction requirements. See [profile reports](../cli.md#promptkit-definition-inspection). |
| Fix application root/overlay interpretation in CommandKit, reject empty config values, and derive PromptKit selection from one prescribed root | Values and presence are passed to application callbacks, which interpret them. See [scope integration](../consumers/guide.md#a-configuration-scope) and [selection declarations](../../config.go). |
| Validation failure always emits no success report | Completed scope records can precede a later failure. See [validation](../cli.md#validate-configuration). |
| Native display has no format flag | `config show --format yaml` is accepted. See [effective display](../cli.md#show-effective-configuration) for syntax and framing. |
| Scope inventory includes description/default fields; sources use a prescribed table | The selected report shapes are defined in [scope discovery](../cli.md#configuration-scopes) and [source inventory](../cli.md#list-configuration-sources). |
| Root `app --version` is a standard entry point | The delivered entry point is `app version`; text can include revision and YAML has explicit identity fields. See [version reporting](../cli.md#version). |
| Blank definition IDs are usage failures | Missing operands are usage failures; explicitly blank values reach owning inspection and produce operational results. See [definition inspection](../cli.md#promptkit-definition-inspection). |
| CommandKit automatically coordinates shared loads and dependencies | Applications compose acquisition and may use invocation-local caches. See [consumer integration](../consumers/guide.md) and the composed example. |

The selected namespace/resource-first grammar, capability-based family assembly,
application-focused default version, native aggregate YAML, and initial JSON
deferral remain reflected in the accepted ADRs and delivered target. The earlier
alternatives are review history, not unresolved implementation choices.

## Deferred work and remaining proposals

### `config diff`

Semantic comparison is deferred pending supported upstream safe snapshot APIs.
[ADR 0008](../adr/0008-semantic-configuration-diff.md) owns its accepted comparison
and sensitivity-gap decisions. The [deferred capability target](initial.md#deferred-capability-targets)
records dependencies.

Exact comparison selection syntax and report layout remain future design work.
The original proposal considered separate right-side root/overlay selection,
shared versus independent domain context, and an optional assertion mode. None
of those flags or modes is installed or promised by the initial implementation.
CommandKit should use owning public APIs rather than compare rendered YAML or
implement another configuration engine.

### PromptKit catalogs

Prompt/profile listing is deferred pending public catalog APIs. Catalog resource
names and enumeration/report details can be specified when supported APIs exist;
CommandKit does not enumerate by reparsing PromptKit configuration YAML. See the
[deferred capability target](initial.md#deferred-capability-targets).

### Other proposals outside the initial delivery

Configuration mutation, reloadable export, credential diagnostics, live provider
probes, shell completion, exhaustive field-origin inventories, generic value
assignment, additional component identity registration, and domain artifact
catalogs remain outside the initial scope. Their inclusion requires a concrete
operator purpose and an appropriate ownership/behavior decision. JSON remains
deferred without a commitment to add it.

Execution, rendering, serving, and session operations remain application-owned.
Shared vocabulary is guidance under [ADR 0006](../adr/0006-command-grammar.md),
not a reserved implementation contract for every consumer.

Application migrations should replace divergent standard paths and update
subprocess consumers and documentation for intentional breaking changes. The
original review considered Scriptorium/Notarius followed by Audita/Narratio;
that ordering is historical evidence, not a completed migration or mandatory
adoption sequence. Future capabilities can be adopted independently.

## Historical review evidence

The initial review on 2026-10-06 compared Audita's `print-effective`, Notarius's
`effective`, and Narratio/Scriptorium's `show`; inconsistent scope/source reports;
repeated dispatch/loading/report plumbing; and differing help, syntax, and status
conventions. Those differences informed the shared standard, rather than imposing
compatibility requirements. Narratio's subprocess interpretation of application
statuses also demonstrated the need to coordinate consumer adoption.

Evidence sources, relative to this roadmap in the sibling workspace checkouts:

- [Audita CLI contract](../../../audita/docs/cli.md) and
  [configuration parsing](../../../audita/internal/cli/config_input.go).
- [Narratio CLI contract](../../../narratio/docs/cli.md),
  [configuration inspection](../../../narratio/internal/app/config_commands.go),
  and [comparison](../../../narratio/internal/app/config_diff.go).
- [Notarius CLI contract](../../../notarius/docs/cli.md) and
  [configuration commands](../../../notarius/internal/cli/configkit_commands.go).
- [Scriptorium CLI contract](../../../scriptorium/docs/cli.md),
  [application inspection](../../../scriptorium/internal/adapter/cli/config.go),
  and [framework inspection](../../../scriptorium/internal/adapter/cli/framework_config.go).
- [ConfigKit inspection API](../../../ConfigKit/inspection.go),
  [source records](../../../ConfigKit/records.go), and
  [configuration contract](../../../ConfigKit/docs/config.md).
- [PromptKit configuration inspection](../../../promptkit/configuration_inspection.go)
  and [consumer guide](../../../promptkit/docs/consumers/pkg-promptkit.md).

These links identify sibling-checkout evidence from that review. They are not
build dependencies, permanent implementation references, or claims about the
applications' present adoption status. Current contracts are owned in CommandKit.