commandkit/docs/roadmap/initial.md

# Initial CommandKit feature roadmap

Status: selected initial target implemented; completed design baseline.

Date: 2026-10-07.

## Purpose and authority

This document defines the selected initial target for the library: packages,
features, integration contracts, dependencies, and completion evidence. It was
prepared using [the agreed checklist](initial-plan.md). Implementation steps and
stage evidence belong in the [completed initial implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/3871d837489b9955998b362587a52b47282dc021/docs/roadmap/implementation.md).
Detailed specifications below preserve the selected design baseline; they are
planning history, not a parallel current API or operator reference. The included
target is implemented; the table below records feature status.

| Included feature IDs | Status | Evidence |
| --- | --- | --- |
| API-01, REG-01, INPUT-01, BACK-01, INV-01, OUT-01 | complete | Root API and dispatcher tests; `go test ./...`. |
| HELP-01, VER-01 | complete | Help/version behavior tests; `go test ./...`. |
| INT-01, CFG-01–05 | complete | Configuration scope, validation, show, sources, and explain tests; `go test ./...`. |
| PK-01 | complete | PromptKit scope adapter tests; `go test ./...`. |
| PK-02, PK-03 | complete | Prompt/profile inspection tests; `go test ./...`. |
| DIFF-01, CAT-01 | deferred | Require upstream safe snapshot and catalog APIs; see [deferred capability targets](#deferred-capability-targets). |

The [architecture policy](../policy/architecture.md) and nine accepted ADRs control
this roadmap. The delivery scope, typed API model, selector/report behavior, and
full profile inspection described here were selected during roadmap review.
These implementation choices operate within the accepted architecture. Exact
exported contracts belong in Go declarations and GoDoc, navigated through the
[consumer guide](../consumers/guide.md); implemented operator contracts belong in
the [CLI reference](../cli.md). The [internal overview](../internal/overview.md)
owns current package inventory and mechanics.

### Requirements and traceability

| Requirement | Authority | Feature targets |
| --- | --- | --- |
| Own dispatch; use explicit instance registries, composable groups, typed inputs, and capability-based standard families. Keep application domain behavior with applications. | [ADR 0001](../adr/0001-command-dispatch-and-inputs.md) | REG-01, INPUT-01, INV-01, INT-01 |
| Use Cobra/pflag internally; initially rebuild backend state for each invocation. | [ADR 0002](../adr/0002-cobra-backend.md) | BACK-01, INPUT-01 |
| Expose one root facade with root-owned public named types and no backend leakage. | [ADR 0003](../adr/0003-public-facade.md) | API-01, BACK-01 |
| Supply standard help/version and available configuration/PromptKit inspection operations; families may support different subsets. | [ADR 0004](../adr/0004-standard-inspection-surface.md) | HELP-01, VER-01, CFG-01–05, PK-01–03; deferred DIFF-01, CAT-01 |
| Return explicit classifications and recommended statuses; preserve supported cause identity and report delivery failures. | [ADR 0005](../adr/0005-invocation-outcomes.md) | OUT-01 |
| Apply namespace/resource-first grammar, options after the complete command path, interspersed operands, presence, and selected repetition rules. | [ADR 0006](../adr/0006-command-grammar.md) | INPUT-01, HELP-01 |
| Preserve native effective YAML; prepare all selected show views before writing; frame aggregate display as separate documents. | [ADR 0007](../adr/0007-native-yaml-reports.md) | CFG-03 |
| Compare safe semantic snapshots with sensitivity union and explicit coverage gaps when comparison is enabled. | [ADR 0008](../adr/0008-semantic-configuration-diff.md) | deferred DIFF-01 |
| Declare scope capabilities; default to `app`; preserve the meaning and coverage of `all`; order scopes consistently. | [ADR 0009](../adr/0009-configuration-scopes.md) | CFG-01–05, INT-01 |

The [CLI planning record](01-cli-plan.md), [dispatcher record](02-dispatch.md),
[backend record](03-backend.md), and [facade record](04-facade.md) preserve the
review history. These corrections were selected for the initial target:

- Singleton flags use the last supplied occurrence, including mixed `--name value`
  and `--name=value` spellings. Repeatable flags accumulate in order.
- Every configuration operation, including `validate`, defaults to `app`.
- Straightforward private implementation may live in the root package. A
  forwarding-only facade and a separate internal engine are unnecessary targets.
- Partial capabilities remain useful; neither scopes nor families need every verb.
- Preparing every selected view before report output is a `config show`
  requirement. Other operations have their own output timing.
- The older acquisition graph and shared-load mandates were superseded by
  application-composed callbacks. Exact declarations, selector behavior, and
  report layouts are owned by GoDoc and the CLI reference. Old illustrations
  remain historical evidence.

## Initial delivery scope

Deliver the dispatcher, public registration/binding API, identity/outcomes, and
inspection operations supported by ConfigKit v0.5.0 and PromptKit v0.12.0.
Applications can use CommandKit without registering either integration; the Go
module still declares the dependencies used by its bundled helpers.

| Family | Initial target |
| --- | --- |
| Identity and discovery | `help`, command/group help, `version`, explicit CommandKit version selection |
| Configuration | `config scopes`, `validate`, `show`, `sources`, `explain`, including explicit aggregate validation/display |
| PromptKit configuration | The `promptkit` configuration scope, independently of definition inspection |
| PromptKit definitions | `promptkit show prompt` and `promptkit show profile`, including effective `ExtraParams` |
| Application commands | Typed custom leaf commands, nested groups, and groups with their own runnable handler |

Catalog listing and semantic comparison remain deferred until the owning
libraries expose the required public contracts. Their absence appears accurately
in help and capabilities. The implemented target uses the released inspection
APIs; upstream snapshot/catalog enhancements are separate follow-up work.

This scope provides meaningful configuration inspection immediately and avoids
requiring an initial consumer migration to wait for every future capability.

## Target packages and dependencies

Create two production packages. Keep comparison and inspection helpers as private
root implementation when needed; the current target does not justify another
production package or a public integration subpackage.

| Package | Purpose and owned features | Inputs and outputs | Dependencies and extension points |
| --- | --- | --- | --- |
| Root `commandkit` | Sole public facade; registry, typed bindings, standard handlers, provider integration, reports, identity, and outcomes | Accepts metadata, typed command declarations, acquisition callbacks, context, arguments, and caller streams; returns registration errors and invocation outcomes | Standard library, public ConfigKit/PromptKit APIs, YAML encoder, and the internal adapter. Consumers extend through commands, groups, parsers, scopes, and supported provider callbacks. |
| `internal/cobra` | Routing/parsing/help adapter; fresh backend state; conversion of backend-owned failures | Accepts neutral command/flag/operand metadata, binding callbacks, and invocation callbacks; returns neutral parse/help results and classified syntax failures | Cobra/pflag and standard library. Its bridge is internal and carries no Cobra/pflag objects back to the root. |

Dependency direction is root → adapter → Cobra/pflag. The adapter does not import
the root. Root command declarations are lowered into the adapter's small neutral
bridge; closures bind freshly allocated typed inputs and invoke root/application
handlers. The root translates bridge failures into its public outcomes. Reuse
standard `context.Context`, `io.Writer`, and ordinary Go values at this boundary.

Keep registry policy, capability checks, standard handlers, and reports in the
root. Cobra supplies routing and parsing machinery; its defaults must be adapted
where they differ from the accepted grammar. Do not copy its entire API into
CommandKit or introduce a selectable backend abstraction.

### Module baseline

Use the following reproducible starting baseline:

| Item | Initial baseline | Reason |
| --- | --- | --- |
| Module | `gitea.maximumdirect.net/eric/CommandKit` | Matches project identity and the existing library suite's module convention. |
| Go | `1.25.5` | Matches PromptKit v0.12.0's declared minimum; ConfigKit v0.5.0 declares 1.25.0. |
| ConfigKit | `v0.5.0` | Reviewed released inspection API. |
| PromptKit | `v0.12.0` | Reviewed released configuration and named-definition inspection API. |
| Cobra | `v1.10.1` | Concrete initial pin implementing the accepted backend decision. Its [module declaration](https://github.com/spf13/cobra/blob/v1.10.1/go.mod) requires pflag v1.0.9. |
| pflag | `v1.0.9` | Match that Cobra baseline; its [module declaration](https://github.com/spf13/pflag/blob/v1.0.9/go.mod) fits the selected Go baseline. |
| YAML encoder | `go.yaml.in/yaml/v4 v4.0.0-rc.6` | Match ConfigKit's existing dependency for CommandKit-owned YAML reports. Native configuration writers remain authoritative. |

These pins identify the initial baseline without claiming they are the newest
releases. Resolve and review the actual module graph and license notices when
adding dependencies.
Deferred snapshot/catalog capabilities will require released upstream versions
containing the new public APIs and a revised capability assessment.

## Public API and integration model

### API-01: public facade

**Owner:** root. **Prerequisites:** registry and invocation contracts below.

Expose an application handle with private state and a small deliberate method
set. Use construction from application identity and explicit initial command
registrations, registration methods for groups/standard suites, and invocation
with context, arguments, and caller streams. Keep runtime dependencies in handler
closures or a separate typed execution dependency parameter; they are not parsed
CLI fields.
Construction automatically installs help and version from identity/build metadata.
Provider registration assembles the other standard families' supported operations.

The target concepts are identity, application/registry handle, command/group
declarations, typed bindings, presence, invocation environment, outcome, and scope
registration. Public named CommandKit types live in the root. Public ConfigKit
and PromptKit types are deliberate integration dependencies where useful.
Use generic package functions/factories with explicit typed binding setters and
composable groups. Go methods cannot declare their own type parameters, so generic
entry points belong in package functions/factories. Typed declarations and captured
views retain their selected ownership and supported public value/error semantics.

**Completion evidence:** an external consumer uses only the root facade to
register and execute commands; public signatures, callbacks, fields, constraints,
and method sets contain no backend/internal types. No public aliases, anonymous
embedding, loosely typed bridge values, or returned backend errors defeat this
boundary. Caller-supplied values/errors retain their documented treatment.

### REG-01: instance registry and command groups

**Owner:** root. **Provider requirements:** none. **Depends on:** API-01.

Use one metadata declaration for each command's path, description, operands,
flags, bindings, and handler. Compose groups explicitly per application instance.
Support nested custom commands and a group that has both children and a runnable
handler. Groups without handlers show help when invoked bare.

Reject duplicate command paths and replacement of standard handlers. Own the
`config` namespace when installed and `promptkit` when installed: applications
cannot insert private children underneath them. Additional application families
remain registerable without needing the standard families' verb subsets.

Build standard command availability from declared capabilities. Validate missing
wiring at registration; never load files to discover operations. Return errors
from registration rather than allowing registration order to choose a winner.

**Completion evidence:** two separate instances have independent registries;
collisions and reserved-family violations return clear errors; nested custom
groups work; partial standard suites expose only their available operations.

### INPUT-01 and BACK-01: typed inputs and adapter behavior

**Owners:** root for bindings/presence; adapter for backend mechanics.
**Provider requirements:** none. **Depends on:** REG-01.

Use generic command factories with explicit typed flag/operand setters and
a typed handler. Allocate the input struct for each invocation. A presence wrapper
such as `Supplied[T]` carries a value and whether it was supplied; omission differs
from an explicitly supplied empty string, false, or zero. A repeatable binding
collects ordered values. Support ordinary scalar conversions and caller-provided
typed domain parsers without handler lookups by flag name.

Metadata expresses required operands/flags, counts, and declared incompatible
combinations. Parsing and declared input-shape failures are usage outcomes;
application domain validation stays with the application handler. Do not infer
additional incompatibilities from parser convenience.

Apply ADR 0006's grammar through the adapter: standard long lowercase hyphenated
flags, separated/equal string values, boolean presence or explicit boolean value,
`--` termination, options after the full command path, and interspersed options
and operands within that command. Help bypasses missing execution requirements;
unknown help paths/flags still fail as usage errors.

Initially rebuild the Cobra tree and binding state for each invocation. Repeated
calls retain no prior values, slices, or presence bits. Caller closures keep their
own lifecycle; this design does not establish concurrent dispatch support.

**Completion evidence:** public invocations exercise the real adapter, explicit
zero/false/empty values, omission, singleton last-wins, ordered repetition,
interspersed operands, termination, and repeated executions with fresh inputs.
Help routing must follow CommandKit's grammar even where Cobra differs.

### INV-01 and OUT-01: invocation, outcomes, and diagnostics

**Owner:** root, with syntax adaptation in the adapter.
**Provider requirements:** handlers/acquisition callbacks. **Depends on:** INPUT-01.

Pass caller context to handlers and acquisition callbacks. CommandKit does not
create the executable entry point, install signal handlers, or call `os.Exit`.
Return explicit success, usage, operational, or application-domain classification,
recommended status, and supported cause identity. Standard statuses are 0, 2, and
1 respectively for success, usage, and operational failure. Preserve an
application handler's explicit domain classification and suggested status.

Make root invocation the single presenter of CommandKit diagnostics.
Standard handlers return report/delivery information and safe diagnostic data;
the adapter suppresses its own automatic error printing. Use public
`configkit.WriteDiagnostics` for ConfigKit diagnostics and neutral presentation
for syntax errors. Pair diagnostics with supplied source records where useful.
Do not print an owning-library diagnostic twice through nested CommandKit paths.

Return one root-owned outcome containing classification, suggested status,
operation cause, delivery failure, and a clear diagnostic-delivery indication.
This indication distinguishes a diagnostic already presented from one whose write
failed. Preserve both the operation cause and a delivery error when both occur;
do not replace either with a backend error. Invocation returns this outcome
without a separate error result. Warnings alone allow success. Report or diagnostic
writer errors are operational failures and can leave partial output.

Callbacks control their own output. Consumer guidance should recommend returning
diagnostics to the standard path and avoiding repeated presentation, without
prescribing all downstream error handling. Upstream APIs determine how much
underlying error identity survives; CommandKit cannot recover causes an upstream
library deliberately withholds.

**Completion evidence:** usage guidance appears on the diagnostic stream;
reports appear on the report stream; warnings permit success; callback,
cancellation, report-write, and diagnostic-write failures are classified correctly;
public causes remain usable with `errors.Is`/`errors.As` where supported.

### INT-01: acquisition and provider contracts

**Owner:** root. **Depends on:** registry, typed inputs, outcomes.

Use a typed configuration-suite factory parameterized by an
application-owned inspection-context input. It installs the standard input
bindings once, plus explicit typed application selector bindings, and scope
registrations with acquisition callbacks. A simple consumer uses an empty context
type. A complex consumer supplies campaign or other domain selection as typed
fields. Generic suite helpers and small capabilities provide this assembly without
a universal untyped service container or handler access to parser objects.

Each scope declares supported operations and obtains a captured view only on an
invocation that needs it. Use small operation-specific interfaces/callbacks:
native effective writer; source reader; safe explanation reader/writer; and
validation callback. Reuse `configkit.SourceInfo`, `Diagnostic`, `Path`, and
`Explanation` rather than creating parallel provenance types. A bundled generic
ConfigKit helper connects a loader returning `*configkit.Result[T]`; a PromptKit
helper connects engine acquisition and `ConfigurationInspection`. Missing an
operation must not require dummy implementations of other interfaces.

For a selected operation, acquire its scope once and retain that view through
reporting. A bundled helper can reuse the same loaded result for diagnostics and
the report. Aggregate show retains all selected views before writing. Other
operations need no application-wide cache or dependency graph.

When an engine depends on application configuration, the application acquisition
callback composes that dependency. It may share results in an invocation-local
closure. Document that pattern, without requiring one universal loading method,
forbidding consumer effects, or promising that arbitrary callbacks never reload.
Recommend sharing inspection and execution loading/resolution where practical.

**Completion evidence:** metadata-only commands do not invoke acquisition;
single-scope operations acquire only their target; aggregate show observes its
preparation rule; simple and complex consumer examples require no parallel
dispatcher, manual standard-command parser, or duplicated standard report logic.

## Standard command features

All features below belong to the root; routing, flag conversion, and help
mechanics use the adapter. Their common prerequisites are REG-01, INPUT-01,
INV-01, and OUT-01. Provider requirements and additional dependencies are stated
per feature. The following flags/report shapes are selected implementation
targets for the initial standard suite.

### HELP-01 and VER-01: help and identity

- Help describes installed standard and custom commands using registry metadata.
  Root bare invocation, `help [COMMAND…]`, `--help`, and `-h` follow ADR 0006.
- Use `version` and `version --scope commandkit`; default output is only
  application identity. Version subjects are separate from configuration scopes.
- Application identity is supplied at construction. Recommend obtaining embedded
  CommandKit identity from Go build information, respecting module replacement
  metadata; use an explicit development/unknown label when a tag is unavailable.
  Do not invent a separate integer CLI version. Use a text default and
  optional `--format yaml` for version records.

**Provider requirements:** identity metadata only. **Completion evidence:** help,
version, and discovery work with missing/invalid configuration and never invoke
acquisition callbacks. Default version excludes dependency inventory; explicit
CommandKit selection identifies the embedded component accurately.

### CFG-01: scope metadata and selection

`config scopes` lists identifiers and supported operations in order: `app`,
`promptkit`, then additional identifiers alphabetically. Use text by default
and `--format yaml` producing `scopes: [{name, operations}]`.

All installed configuration operations use `--scope NAME`, defaulting to `app`.
`validate` and `show` additionally accept `all`. Check requested coverage before
acquisition. An unsupported scope/operation is usage failure with available
choices; `all` never silently skips a scope. If `app` is absent, its default
selection fails with useful choices rather than silently selecting another scope.

**Provider requirements:** registration metadata only. **Completion evidence:**
discovery matches installed handlers and partial capabilities; aggregate coverage
errors occur before any acquisition; ordering and defaults match ADR 0009.

### CFG-02: validation

`config validate` invokes the selected provider's configuration load/validation
boundary. ConfigKit's bundled helper regards successful load and required owning
validation as success. PromptKit's helper constructs/obtains a valid engine;
it does not run a prompt or probe model availability. Application domain context
validation, when needed for its inspection view, belongs in its callback.

Use text by default and `--format yaml` with a `scopes` sequence of completed
validation records (`name`, `valid`). For `all`, preflight capability coverage,
then validate in scope order and report successful scopes as they complete;
stop on the first operational failure. Diagnostics explain the failure and the
outcome indicates incomplete completion. This selected validation timing preserves
show's separate preparation rule.

**Provider requirements:** validation/acquisition callback and safe diagnostics.
**Depends on:** INT-01, CFG-01. **Completion evidence:** default validates `app`;
explicit `all` validates requested coverage; invalid configuration yields status 1;
warnings alone do not fail; no model execution is triggered by bundled handlers.

### CFG-03: native effective display

`config show` writes the selected scope's owning-library effective YAML. It must
not marshal `Result.Config`, reinterpret defaults, remove nulls, or rebuild the
native document from runtime structs. Use YAML as its sole initial format;
accept `--format yaml` for explicitness.

For `--scope all`, acquire and complete required owning validation of every view
before writing any report bytes. Compose separate native documents in scope order,
with YAML separators and scope-label comments. Use `---` followed by
`# scope: NAME` before each document. Single-scope show writes native output
without an added scope envelope. Preserve native content; framing must account
for any native document marker without creating accidental empty documents.

**Provider requirements:** native writer plus successful acquisition/validation.
**Depends on:** INT-01, CFG-01. **Completion evidence:** single native output is
preserved; aggregate YAML has one labeled document per selected scope in order;
a later acquisition failure leaves no successful prefix; writer failure returns
operational failure and may leave partial output.

### CFG-04: source inventory

`config sources` exposes the selected captured view's public source records.
Retain the owning source IDs, labels, paths, kinds, layers, underlay indices, and
import locations where available; missing fields do not acquire invented values.
Keep owning-library record order. Use readable text by default and
`--format yaml` with `{scope, sources}` and explicit snake-case source fields.

**Provider requirements:** public source reader and acquisition.
**Depends on:** INT-01, CFG-01. **Completion evidence:** acquired and synthetic
records remain identifiable; import references correlate with owning IDs;
reporting does not reload files or confuse provenance with effective values.

### CFG-05: path explanation

Use `config explain --path POINTER`, including an explicitly supplied empty
pointer for the root. Use public `configkit.ParsePath`; malformed pointers are
usage errors and unknown effective/historical paths are operational lookup
failures. Do not treat a native writer's empty output as successful lookup.

Text defaults to the owning `WriteExplanation` rendering. Use
`--format yaml` with `{scope, path, effective, origin, history, secret_reference}`.
Preserve `present`, `redacted`, and the owner's YAML fragment in each value
snapshot; represent fragments as strings so absence/null/masked values remain
unambiguous. Canonicalize paths through public `Path.String()`. Preserve owning
provenance, reasons, dependencies, and reference names, not credential values.

**Provider requirements:** safe public explanation and native text writer.
**Depends on:** INT-01, CFG-01. **Completion evidence:** known current and removed
historical paths work, root-pointer presence works, invalid/missing paths have
distinct outcomes, and safe snapshots survive YAML report conversion.

### PK-01: PromptKit configuration integration

The bundled helper acquires an engine through the application callback, then
uses `Engine.InspectConfiguration()` and its public native writers, sources,
diagnostics, and explanation methods. Register these capabilities under the
`promptkit` scope. Registration of this scope neither requires nor implicitly
installs definition inspection.

**Provider requirements:** engine/configuration-inspection acquisition.
**Depends on:** INT-01, CFG-01–05. **Completion evidence:** native PromptKit YAML
and ConfigKit-compatible provenance are exposed through the standard family;
aggregate show can combine it with `app` without translating either document.

### PK-02 and PK-03: named definition inspection

Use these command inputs:

```text
app promptkit show prompt ID [--version VERSION] [--format text|yaml]
app promptkit show profile ID [--format text|yaml]
```

Both acquire the engine lazily and pass the invocation context to the public
inspection method. Prompt-version omission follows PromptKit's own selection
semantics. Missing named definitions are operational lookup failures. These
operations do not render/execute prompts, resolve credential values, or generate
model output through CommandKit's handlers; application acquisition retains its
own behavior.

Prompt reports include ID, selected version, opaque hash, declared default profile,
input definitions in declaration order, and declared output contract. Use explicit
YAML fields rather than depending on incidental Go struct serialization. An
output-contract value of `json` is domain metadata, not a JSON report format.

Profile reports include the named ID, backend-completed effective target fields,
`ExtraParams`, credential environment-variable name, and direct-credential
requirement from the existing public `ProfileInspection` result. `ExtraParams`
contains provider settings and is included in both text and YAML reports. It
requires no additional redaction or upstream inspection API for this feature.
Preserve nested parameter values when projecting the public result into the
CommandKit report schema. Credential values remain separate from these settings.

**Provider requirements:** public `InspectPrompt`/`InspectProfile` respectively;
each capability can be registered independently. **Depends on:** INT-01 and the
public report projection. **Completion evidence:** text and YAML preserve public
metadata and effective provider parameters; profile credentials are reported as
requirements/references; unknown IDs and cancellation retain supported public
error identity; help never constructs an engine.

## Selectors, reports, and ownership

Use a shared standard selection input for acquisition-bearing inspection
commands, carrying presence-aware `--config` and singleton `--overlay`.
Application callbacks interpret their values using the owning loader. Omission
delegates discovery/default selection; an explicitly empty overlay can represent
the loader's no-overlay selection. The application
supplies schema, filesystem/source construction, imports, and domain resolution.
PromptKit integration does not assume its configuration is at the application
root path; its callback maps selectors to its acquisition path.

Register application context flags through typed bindings with declared scope
applicability. For example, a Narratio campaign selection can matter to `app`
inspection and to engine acquisition derived from that application view. Reject
explicit selectors that do not apply to any selected scope with a usage diagnostic;
for `all`, route each selector to the scopes that declare it. Metadata/help should
state applicability. Validate declared selector combinations before acquisition;
domain lookup/validation remains operational. Do not infer application-specific
campaign or session policy.

Use text defaults for CommandKit-owned summaries and YAML alternatives;
`config show` is native YAML. CommandKit owns report schemas for summaries,
source/explanation projections, and definition reports. Owning libraries own the
native documents and safe values. Select schema fields deliberately and document
them with implementation; no separate schema-version integer is proposed.

| Responsibility | Owner |
| --- | --- |
| Command paths, shared grammar, standard handlers, metadata/help, selection preflight, report framing, outcomes | CommandKit |
| Typed custom input mechanics and routing | CommandKit; custom domain meaning remains with the application |
| Configuration composition, recorded resolution, provenance, sensitivity, native effective/explanation rendering | ConfigKit/PromptKit through supported public APIs |
| Source discovery, application schema and domain validation/resolution, engine construction, runtime dependencies | Application callbacks |
| Custom session/execution commands, effects, outputs, and domain results | Application |
| Process context/signals, streams, final status mapping, process exit | Application entry point |

Safe owning-library inspection is required for enabled standard operations. This
does not promise that arbitrary configuration or prompt content is suitable for
public disclosure, and CommandKit does not inspect arbitrary consumer error
objects to enforce a broader confidentiality policy.

## Upstream capability evidence

The following clean sibling revisions were reviewed on 2026-10-07. They are
evidence snapshots, not build dependencies.

| Repository | Reviewed revision | Released API baseline |
| --- | --- | --- |
| ConfigKit | `dc09959cca4e105f49ec316c6d4ba585bd2340bd` | v0.5.0 |
| PromptKit | `4b8169da286917fde7875425bb32b799b12c6af3` | v0.12.0 |
| Scriptorium | `723fee9c466789fd3b6cca5492bf2edf99f4136c` | Consumer evidence |
| Notarius | `66fa5585c1190581e96ec42102ce745c3869ba6d` | Consumer evidence |
| Narratio | `8afb49c01808c04bc73f782d1619e87c8c2cd312` | Consumer evidence |
| Audita | `3b4933256eff84327b812e7ae12babf743bc04a6` | Consumer evidence |

| Capability | ConfigKit v0.5.0 | PromptKit v0.12.0 | Delivery consequence |
| --- | --- | --- | --- |
| Validated acquisition | `Load`/recorded resolution with application definition | `NewEngine` and application acquisition | Include CFG-02; do not add a parallel validator. |
| Native effective YAML | `Result[T].WriteEffective` | `ConfigurationInspection.WriteEffective` | Include CFG-03 and PK-01. |
| Sources/diagnostics | Public result/load-error source and diagnostic records | Configuration-inspection sources/diagnostics | Include CFG-04 and OUT-01. |
| Safe path explanation | `Explain`, `WriteExplanation`, public `Path` | Equivalent configuration-inspection methods | Include CFG-05. |
| Named prompt metadata | Outside its resource domain | `Engine.InspectPrompt` and `PromptInspection` | Include PK-02. |
| Named effective profile target | Outside its resource domain | `Engine.InspectProfile` exposes the effective target including copied `ExtraParams`, plus credential requirements/reference names | Include PK-03 using the existing public result, including provider parameters. |
| Catalog enumeration | Outside its resource domain | No public prompt/profile enumeration API found | Defer CAT-01; recommend upstream captured catalog inspection. |
| Safe full semantic comparison snapshot | No dedicated public structured tree plus full sensitivity/coverage contract found | No corresponding configuration snapshot API found | Defer DIFF-01; recommend upstream safe snapshot support. |

Relevant public declarations are [ConfigKit inspection](../../../ConfigKit/inspection.go),
[metadata](../../../ConfigKit/metadata.go), [PromptKit configuration inspection](../../../promptkit/configuration_inspection.go),
[engine methods](../../../promptkit/engine.go), and [inspection types](../../../promptkit/types.go).
ConfigKit's `HistoricalPaths`, `Explain`, and redacted YAML provide useful pieces;
they do not expressly define the full comparison representation required by ADR
0008. Deriving a comparison contract from these pieces would require an explicit
owning-library agreement and design, rather than assuming masks imply equality.

### Deferred capability targets

- **DIFF-01:** acquire two independently resolved selections of one scope through
  public safe snapshots. Preserve absent/null/empty distinctions and scalar
  semantics, recursively compare mappings, compare ordered sequences atomically,
  apply sensitivity union, and report differences plus gaps in text/YAML. Completed
  comparisons succeed even with differences/gaps. Snapshot data must describe
  hidden paths and supported reasons without fetching secrets. Comparison selector
  syntax/inheritance must be decided when bringing this feature into delivery.
- **CAT-01:** list captured prompt/version entries and named profiles through public
  owning catalog APIs; deterministic reports describe actual loaded definitions.
  Do not infer catalogs from configuration YAML or inspect sibling internals.

Do not create empty handlers, pretend capabilities, or unused public snapshot
types for these deferred targets. Future upstream contracts should inform their
representations. Future FeedKit-like families can supply appropriate operations
without supporting comparison or configuration scopes.

## Reuse assessment and consumer fit

Use the reviewed revisions above to evaluate extraction; no source is copied by
this roadmap. Prefer existing public owning writers over porting their renderers.

| Candidate | Useful behavior | Adaptation and boundary |
| --- | --- | --- |
| [Notarius configuration handlers](../../../notarius/internal/cli/configkit_commands.go): `runConfigEffective`, `runConfigExplain` | Load an application result and call native ConfigKit writers; canonical path parsing and lookup handling | Retain the acquisition-to-writer pattern. Replace application scopes, manual flag sets, output/status handling, and loader coupling with INT-01/CFG-03/05. The application keeps its loader and domain selection. |
| Same file: `runConfigProfile`, `runConfigValidate` | Named profile inspection and application-specific validation examples | Evaluate inputs and callback needs. Their JSON report, private wrappers, and runtime/domain validation are not standard contracts. |
| [Scriptorium inspection dispatch](../../../scriptorium/internal/adapter/cli/inspect.go): `inspectCommand` | Lazy engine acquisition and named inspection followed by formatting | Keep upstream method use. Replace private dispatch, `context.Background`, output-file behavior, old command paths, and integer-status plumbing with caller context, streams, and outcomes. |
| [Scriptorium report projections](../../../scriptorium/internal/format/inspection.go): `FormatPromptInspection`, `FormatProfileInspection` | Explicit prompt/profile field projection and readable presentation | Prompt/profile DTO fields are useful starting inventories. Replace JSON output with YAML and include the public effective `ExtraParams` values in profile reports. |
| [Narratio comparison](../../../narratio/internal/app/config_diff.go): `ConfigDiff`, `configDiffWithDependencies` and comparison helpers | Independent resolved selections, deterministic path records, and add/remove/change presentation | Evidence for future DIFF-01. Its application projection/digests, overlay-only operands, shared campaign policy, and absence of ADR 0008 sensitivity-gap semantics require redesign; no initial direct port is proposed. |

Recommend implementing the small integration glue from these public contracts,
using consumer code as behavioral evidence. If a substantive helper or fixture is
actually copied/adapted, record its source commit, affected symbols/files,
modifications, and required notices when it lands. Scriptorium and Notarius grants
are GPL-3.0-or-later; CommandKit is LGPL-3.0-or-later. Common ownership does not by
itself change those grants. Resolve applicable reuse rights or an author's
deliberate licensing choice before any such copy under the
[OSS policy](../policy/oss.md). No blanket source-port permission is inferred.

Use secret-free synthetic fixtures reflecting existing consumer scenarios:
defaults plus overlays and historical deletion, inherited profiles, explicit
zero/false selectors, missing definitions, and a second scope that fails during
aggregate show. Existing consumer cases can inform these fixtures; entire
application schemas/workspaces need not be imported.

Two maintained public examples should substantiate infrastructure reduction:

1. **Simple ConfigKit consumer:** register one application loader and its schema,
   use bundled scope wiring, then register a typed custom command. Standard help,
   parsing, validation, native show, sources, and explanation need no private CLI
   handlers or formatters.
2. **Complex consumer modeled on Narratio/Scriptorium:** register app and PromptKit
   scopes plus named definition inspection, with typed campaign/context selection;
   compose app → engine acquisition in consumer code; retain a custom
   `session restore` group/handler. Standard paths and report composition remain
   CommandKit-owned while campaign/session meaning stays with the application.

The declaration and callback burden should demonstrate infrastructure reduction
against the existing handlers. Consumers should be able to use these examples
without recreating dispatch, standard input parsing, or standard report projection.

## Explicit deferrals

In addition to DIFF-01 and CAT-01, defer JSON report
output, shell completion, output-file management, backend selection, a plugin
framework, general dependency injection, concurrent-dispatch guarantees, and
implementation of additional library families. None is needed to prove the
initial selected feature target. Application-owned commands remain extensible.

Consumer migrations and source publication were kept outside the initial
library target. ReleaseKit adoption is complete; current release operations
are in the [maintainer procedure](../release.md). The completed adoption record is
available at the [historical adoption revision](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/c0c03285f7beac3e96f1708b655c1eb2add35e79/docs/roadmap/implementation.md).
The initial implementation targeted a usable module with maintained examples;
it did not create placeholder publisher commands or a binary build matrix.

## Completion criteria

The initial target is complete when the included feature IDs have their stated
observable behavior and evidence, and the selected roadmap choices are reflected
consistently in the API and CLI contracts.

Use proportionate deterministic, offline behavioral evidence under the
[testing policy](../policy/testing.md): public consumer tests with the real adapter
for grammar/presence/state, real local ConfigKit/PromptKit fixtures for inspection,
and controlled acquisition/writer failures at those boundaries. Review the public
type/dependency boundary directly; choose automation only where its distinct
protection justifies maintenance. Do not retest complete upstream libraries or
add blanket coverage, race, scanner, or platform gates.

Maintain these substantive documents/artifacts as implementation lands:

- GoDoc for exact exported contracts, ownership, errors, and lifecycle.
- `docs/cli.md` for installed standard syntax, formats, scope coverage, and outcomes.
- Consumer guidance and complete simple/complex examples; link to owning upstream
  configuration contracts instead of duplicating schemas.
- `docs/internal/overview.md` describing the two implemented packages and their
  actual boundary. Add focused internal/integration documents only where useful.
- Dependency/source attribution and applicable license/notice material in the
  change that incorporates it, under the OSS policy.
- Contributor commands and orientation updates once the Go module and validation
  commands actually exist; preserve existing policy ownership.