commandkit/docs/roadmap/future.md

# Future work

Status: pending release and integration work, plus future capability proposals.
No delivery dates are selected here.

## Purpose and authority

Completed roadmaps, implementation plans, and review findings have been retired.
This document preserves unfinished work and unselected ideas under the
[release policy](../policy/release.md#release-documentation-and-preparation).
The completed PromptKit v0.18.0 adoption roadmap and implementation plan remain
available in the
[PromptKit retirement snapshot](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/540e2359d66d604a563df0be1c9fc961588f5b9c/docs/roadmap).
The completed ConfigKit adoption, reporting, dependency alignment, release-tooling,
and remediation records remain available at the
[retirement snapshot](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/260256d722f52bc947103d078cb67a129f4cc9f1/docs/roadmap).
[Earlier retired records](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/6bc37e7ba64ca0920b4d0cc77039a18d4006b24e/docs/roadmap)
also remain in Git history. Completed records are not assignments to restart work.

Accepted [ADRs](../adr/) and the [architecture policy](../policy/architecture.md)
govern any future implementation. The [CLI reference](../cli.md), public GoDoc,
and [consumer guide](../consumers/guide.md) own implemented behavior. Retaining
an idea here does not select its syntax, API, priority, or delivery date.

## Pending release and integration work

### ckprompt release

The PromptKit v0.18.0 migration is complete. The
[ckprompt v0.3.0 candidate](../../integrations/ckprompt/docs/releases/v0.3.0.md)
remains unpublished. Publication and hosted delivery remain separate operations
under the [release procedure](../release.md).
The published ckprompt v0.2.0 retains its earlier dependencies; see the
[consumer guide](../consumers/guide.md#module-selection) for module selection.

### PromptKit v0.19.0 roadmap preparation

The completed adoption used PromptKit v0.18.0 as released. PromptKit v0.19.0
has now been released and reviewed. The working adoption scope includes the
dependency, checksum, attribution, and unpublished candidate-note updates;
consumer compatibility guidance and corrected credential-report wording;
focused authentication-reason and smoke preparation-error coverage; and final
independent-module and aligned-workspace validation.

The proposed additional CLI scope is agreed in principle, subject to review of
the adoption roadmap: concrete request preview, applicable request-override
flags, namespace selection, configuration path discovery and explicitness,
and detailed configuration comparison. Configuration failure investigation is
also proposed for this roadmap, combining failed-load source inventory and
structured diagnostics under
[configuration inspection extensions](#configuration-inspection-extensions).
Successful evidence reporting must retain the failed configuration outcome;
report-delivery failures remain separately observable.

These proposals concern standard operator commands, flags, and reports, not
general-purpose helpers for application-internal PromptKit use. Exact CLI/API
contracts and implementation sequencing remain for roadmap review. Focused
backend inspection remains deferred pending released upstream support, as
recorded under
[PromptKit inspection and selection extensions](#promptkit-inspection-and-selection-extensions).
Use released upstream contracts only; do not inspect or monitor unreleased
upstream work in anticipation of future adoption.

## Future capability targets

### Comparison extensions

Independent per-side domain selectors and an optional assertion mode remain
unselected extensions to the delivered ConfigKit comparison. Consider them only
for a concrete consumer need and a deliberate API/behavior decision under the
relevant ADRs.

### Configuration inspection extensions

The [completed ConfigKit v1.1.0 adoption review](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/260256d722f52bc947103d078cb67a129f4cc9f1/docs/roadmap/configkit-v1.1.0.md#selected-scope-decisions)
retained the following work after dependency and source-report adoption.
Metadata inspection is the recommended next functional sprint; the other
features have no selected sequence or delivery date. These proposals do not
establish command grammar, report schemas, or new provider requirements.
ConfigKit's public APIs own the evidence and its semantics.

- **Optional field metadata, path discovery, and history (OD-3).** Expose native
  `Metadata.Lookup`, `IsExplicit`, `HistoricalPaths`, and `History` through an
  optional provider capability. Design field and history reports together,
  keeping existing providers usable. Distinguish effective paths from removed
  historical paths: a failed `Lookup` must not suppress available `History`.
  Validate that distinction and faithful projection of returned field/change
  records without recreating upstream provenance logic. Historical enumeration
  is not an exhaustive inventory of possible schema fields. This gives the
  earlier field-origin inventory proposal a concrete, upstream-backed scope;
  command names, selectors, and report shapes remain to be designed. For
  PromptKit, design this shared optional ckconfig capability first, then wire
  `ConfigurationInspection.Metadata()` through `ckprompt.ConfigScope`. This is
  PromptKit adoption OD-3; it does not require a separate provenance model or a
  new core API.
- **Failed-load source inventory (OD-4).** Present acquired source evidence from
  `LoadError.Sources()` while retaining the failed outcome and diagnostics.
  Design how an adapter returns its source facet on error and how result output
  precedes terminal failure presentation. Cover acquisition and report-delivery
  failures together; current diagnostic context remains available meanwhile.
- **Detailed comparison (OD-5).** Consider an additional form projecting native
  `Difference` paths, both snapshots, presence/redaction fields, and
  `HiddenChanged`. The current comparison retains the reduced
  additions/changes/deletions report. Decide later whether a detailed form
  complements it or replaces it through a deliberate compatibility change.
- **Structured diagnostics (OD-6).** Consider machine-readable native codes,
  paths, severities, and locations alongside CommandKit's shared reporting
  design. Define result/diagnostic channels, warning and terminal-failure
  interaction, and delivery outcomes. A ckconfig-specific report remains an
  alternative, with its cross-family alignment considered explicitly.
- **Source-ID filtering.** Consider selecting a record already available in the
  source inventory. Native `Source(id)` lookup is a convenience; this proposal
  need not introduce another command or require a lookup method from every
  custom source provider.

Discovery, import defaults, collection identities, and field-level resolution
recording remain available through application loaders. Standard inspection of
resource contexts or secrets-directory bootstrap has no immediate proposal;
those capabilities primarily serve application loading and startup.

### PromptKit inspection and selection extensions

The [completed PromptKit adoption scope](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/540e2359d66d604a563df0be1c9fc961588f5b9c/docs/roadmap/promptkit-v0.18.0.md#scope-decisions) deferred these
capabilities beyond the v0.18.0 compatibility migration. Shared configuration
metadata remains the recommended next functional sprint, under
[configuration inspection extensions](#configuration-inspection-extensions).
The OD identifiers below belong to the PromptKit adoption roadmap, separately
from the ConfigKit review identifiers above.

- **Focused backend inspection.** Defer a standard backend detail command
  until a released PromptKit version provides a suitable public backend
  inspection capability. The operator task is to inspect one backend's
  endpoint, credential environment reference, concurrency and queue settings,
  provider defaults, and smoke-probe configuration without running a probe.
  PromptKit v0.19.0 has no dedicated backend inspection API. Do not implement
  this proposal by reconstructing backend selection from captured
  configuration. Review the released upstream capability before selecting
  command syntax and report fields; this feature is outside the v0.19.0
  adoption scope.
- **Prepared-request inspection (PromptKit OD-4).** Consider an optional provider
  and report based on the released native `Engine.Prepare` and `PreparedRun`,
  reusing the concrete request-builder pattern. This would extend standard
  inspection into rendering and needs an explicit scope decision. The snapshot
  offers selected resource IDs, effective settings, output/schema metadata,
  messages, session ID, hashes, and timing without a model call. Its `Messages`
  contain complete rendered and appended messages; its effective execution
  settings exclude resolved API-key values. Select report content and document
  those upstream semantics rather than treating the complete snapshot as an
  existing inspection report. Command grammar, callback shape, formats, and the
  relationship to request validation remain open. Validate capability
  availability, forwarding, projection, and report delivery at CommandKit's
  boundary. PromptKit retains preparation and rendering semantics. Keeping this
  operation application-owned remains an alternative; model execution and
  prepared-handle lifecycle are outside this proposal.
- **Namespace helpers or standard selectors (PromptKit OD-5).** The
  [consumer guidance](../consumers/guide.md#namespace-views) covers loaders
  returning `Engine.WithNamespaces`.
  Consider reusable bindings or helpers when consumers demonstrate repeated
  wiring. Design independent prompt/profile/backend defaults, applicable
  operations, and their interaction with existing catalog filters together.
  Namespace views resolve unqualified caller selections; they do not rewrite
  captured configuration references or global configuration inspection, and
  namespace/collection inventories remain global. Preserve the distinction
  between name resolution and catalog filtering. No flag names or changed
  filtering meanings are selected.
- **Other reusable request bindings.** Consider helpers for native request
  options only where consumers repeat wiring. Execution/output-validation
  overrides, session IDs, appended messages, and retry settings are already
  reachable through application request builders; engine options remain
  available through loaders. API availability alone does not select a standard
  flag or a new core abstraction.

The released [prepared snapshot](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/types.go)
and [namespace API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/namespaces.go)
provide the reviewed upstream contracts. These proposals establish no new
provider requirement, delivery date, or adoption completion condition.

### Alias completion and discovery

The delivered [shell completion feature](../cli.md#shell-completion) provides
canonical suggestions and alias-aware interpretation. Potential future work
includes suggesting command and flag alias spellings and valid continuations of
alias-only prefixes. For example, completion could suggest `inspect` after
`app legacy ` when `legacy inspect` is an installed alias.

Alias discovery is outside the initial scope. This deferral does not establish a
permanent canonical-only completion contract or prohibit future alias discovery.
A later design should determine how alias suggestions are presented alongside
canonical suggestions while ensuring inserted continuations form valid next
steps. No delivery date or final API is selected here.

### Reporting extensions

Error-conversion helpers such as `WarnError` remain deferred pending demonstrated
value; applications can already use `report.Warn(err.Error())`. Terminal redraw
and progress-bar presentation were outside the completed reporting scope and
remain unselected. Whole-run buffering to make failed runs show only errors
was also outside that scope. Any later extension needs a deliberate API and
presentation decision rather than assuming those behaviors are already provided.

### Release workflow extensions

Historical hosted-page backfilling and automated CI delivery remain separate
future choices. The current local page-only delivery workflow is implemented;
these extensions are not prerequisites for using it. The release procedure owns
delivery, immutable content, and recovery behavior.

Additional validation options, including race testing, full vet, compilation
matrices, size limits, and more forbidden-file paths, can be considered for
demonstrated needs. None is selected by retaining it here, and the existing
candidate checks do not become general prohibitions on development workspaces.

## Other future proposals

These capabilities remain outside the delivered scope and require a concrete
operator or consumer need and an appropriate ownership/behavior decision:

- JSON reports and output-file management or reloadable export.
- Shell completion extensions, including alias discovery described above and
  dynamic discovery of configured or remote values.
- Configuration mutation and generic value assignment. Field metadata and
  provenance inspection are scoped under
  [configuration inspection extensions](#configuration-inspection-extensions).
- Credential diagnostics beyond PromptKit's native smoke checks and additional
  live provider probes.
- Additional component identity registration and domain artifact catalogs.
- Additional library families, including possible FeedKit integration; families
  can define suitable verbs without requiring comparison or configuration scopes.
- Backend selection or replacement, a plugin framework, general dependency
  injection, and concurrent-dispatch guarantees.

Execution, rendering, serving, and session operations remain application-owned.
The [prepared-request inspection proposal](#promptkit-inspection-and-selection-extensions)
would extend standard inspection into rendering and remains an open scope choice.
Shared vocabulary is guidance under [ADR 0006](../adr/0006-command-grammar.md).
Backend replacement remains possible behind the accepted facade, subject to the
published API/CLI contracts and deliberate compatibility decisions.

## Possible further efficiency work

Selected-scope memoization and selector-membership indexes were deferred pending
measurements that justify their bookkeeping. Mutable backend reuse across
invocations, segmented aggregate YAML delivery, provider caching, consumer-loader
redesign, and a replacement backend were outside the completed performance
target. Reconsider them only with concrete motivation and review of ownership,
invocation state, native reports, and the affected contracts. Retained measurement
records are historical evidence, not performance guarantees or release gates.

## Consumer adoption

Consumer migrations remain separate from library delivery. Applications can
replace duplicated standard handlers and routing, then update their CLI docs
and subprocess consumers for intentional changes while retaining domain commands.
No migration order or claim about individual applications' adoption is recorded
here; the [consumer guide](../consumers/guide.md) and maintained examples provide
integration guidance.