commandkit/docs/roadmap/initial.md

# Initial CommandKit feature roadmap

Status: proposed implementation target; open decisions require review before the
staged implementation plan is prepared.

Date: 2026-10-07.

## Purpose and authority

This document defines the proposed end state of the initial library: packages,
features, integration contracts, dependencies, and completion evidence. It is
prepared using [the agreed checklist](initial-plan.md). It does not sequence
implementation tasks or describe existing Go code. CommandKit currently has no Go
module or dispatcher implementation.

The [architecture policy](../policy/architecture.md) and nine accepted ADRs control
this proposal. Recommendations below fill in implementation choices; they do not
become accepted architecture merely by appearing here. Exact exported contracts
will belong in Go declarations and GoDoc; implemented operator contracts will
belong in `docs/cli.md`.

### 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 [four earlier roadmaps](01-cli-plan.md), [dispatcher proposal](02-dispatch.md),
[backend proposal](03-backend.md), and [facade proposal](04-facade.md) supply design
evidence. Carry these controlling corrections into implementation:

- 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, shared-load mandates, selector inheritance rules,
  illustrative Go declarations, and exact report layouts remain proposals.

## Recommended 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 a documented projection for `promptkit show profile` subject to OD-3 |
| Application commands | Typed custom leaf commands, nested groups, and groups with their own runnable handler |

Recommend deferring catalog listing and semantic comparison until the owning
libraries expose the required public contracts. These are accepted standard
operations with deferred implementation, not rejected features. Their absence
must appear accurately in help and capabilities. **OD-1** considers including
upstream enhancements in the initial delivery instead.

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

Recommend the following reproducible starting baseline, rather than floating
dependencies or sibling `replace` directives:

| Item | Proposed 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 are a proposal, not a claim that they are the newest releases. Resolve
and review the actual module graph and license notices when adding dependencies.
OD-1's expanded delivery alternative would require released upstream versions
containing its new capabilities 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. Recommend construction from application identity and registry options,
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.
Exact names/signatures are settled through **OD-2** before the Luna plan.

**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.

Recommend 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.

Recommend making 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 a delivery indication so callers can distinguish 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.
Warnings alone allow success. Report or diagnostic writer errors are operational
failures and can leave partial output. **OD-2** includes this public result shape.

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.

Recommend 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. Exact assembly is part of OD-2; do not require 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 recommended implementation
targets, subject to the open decisions below.

### 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.
- Recommend `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. Recommend 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. Recommend 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.

Recommend 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 timing is an initial proposal,
distinct from show's accepted preparation rule; **OD-4** considers alternatives.

**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. Recommend 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. Recommend `---` 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. Recommend 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

Recommend `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. Recommend
`--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

Recommend 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 static target fields,
credential environment-variable name, and direct-credential requirement. Recommend
an initial documented projection excluding arbitrary `ExtraParams`, with an
explicit report indication that those parameters are omitted. Do not present an
omitted map as empty or claim this projection is a complete effective target.
**OD-3** weighs this useful current-release subset against waiting for an
owner-redacted complete result.

**Provider requirements:** public `InspectPrompt`/`InspectProfile` respectively;
each capability can be registered independently. **Depends on:** INT-01 and the
chosen report projection. **Completion evidence:** text and YAML preserve selected
public metadata; 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

Recommend 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. **OD-4** reviews this proposed
selection contract. Do not infer application-specific campaign or session policy.

Recommend 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`; credential-reference fields are documented, but `ExtraParams` is arbitrary copied data | Include the OD-3 projection only after its contract is selected. |
| 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.
- **Complete PK-03:** obtain a safe owner-defined profile projection, including
  provider parameters and their disclosure treatment, before expanding the initial
  report beyond its selected coverage.

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 DTO fields are a useful starting inventory. Replace JSON output with YAML and select OD-3's profile coverage; its raw `ExtraParams` serialization must not become an assumed redacted report. |
| [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.

Review the declaration and callback burden against the existing handlers. If
these examples require the consumer to recreate dispatch, standard input parsing,
or standard report projection, revisit the API before making the Luna plan.

## Explicit deferrals

In addition to DIFF-01, CAT-01, and complete profile projection, 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, release publication, and ReleaseKit integration are separate
work. Initial implementation should be a usable module with maintained examples;
source-release tooling is planned under the release policy when preparing a
releasable candidate. Do not create placeholder publisher commands or a binary
build matrix.

## Completion and implementation-plan handoff

The initial target is complete when the included feature IDs have their stated
observable behavior and evidence, and the selected open-decision outcomes 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.

Before writing the staged Luna plan, review the proposed delivery scope and
resolve OD-1–4. Translate included IDs into ordered tasks with prerequisites,
precise API/CLI deliverables, and completion checks. Carry deferred IDs forward
without scaffolding them. That subsequent plan should make the selected public
contracts concrete enough that the implementation agent need not invent them.

## Open Decisions

### OD-1: current-release delivery or upstream expansion first?

**Recommendation:** adopt the initial scope above against released ConfigKit
v0.5.0/PromptKit v0.12.0; defer DIFF-01 and CAT-01. Most duplicated inspection
infrastructure can be removed now. Capability-based assembly already accommodates
later additions without requiring every family/scope to acquire those verbs.

**Alternative:** include public safe snapshots and catalog inspection in upstream
work before completing the initial CommandKit implementation. This delivers the
broader standard suite together and avoids an interim subset. It expands the
initial effort into multiple independently released libraries and requires their
data contracts, versions, and comparison selection rules to be selected first.
Choose it if comparison/catalog inspection are required for initial adoption.

### OD-2: exact typed registration and outcome API shape

**Recommendation:** use an application handle, composable groups, generic command
factories with explicit typed binding setters, and generic standard-suite helpers.
Handlers receive typed inputs plus a separate invocation environment; return a
root-owned outcome carrying classification, suggested status, cause, and delivery
information. Reuse public upstream inspection records through small capabilities.
This supports an ordinary input struct and avoids parallel consumer parsing.
Go generic methods are unavailable, so generic entry points should be package
functions/factories rather than methods with their own type parameters.

**Alternative:** use typed descriptor/builders that collect bindings before a
non-generic registration call. This can offer readable fluent assembly and stronger
construction guidance, but adds builder surface and potentially more conversion
machinery. Evaluate it against both consumer examples before choosing signatures.

For failure delivery, recommend one outcome carrying both the operation cause and
delivery failure, with a clear diagnostic-delivery indication. A viable alternative
is `(Outcome, error)`, with the error reserved for invocation/delivery failures.
That follows familiar Go conventions but needs a precise rule preventing the same
failure from being ambiguously represented in both results. Resolve this alongside
the constructor, binding helpers, captured-view assembly, and stream placement;
neither signature is approved by this roadmap.

### OD-3: initial profile-report coverage

**Recommendation:** ship a documented current-API projection of named profile
identity, static effective target fields, and credential requirements/reference
names. Explicitly report that arbitrary provider parameters are omitted. This
exposes useful backend-completed inspection now while keeping the coverage honest.
It does not impose a new upstream confidentiality guarantee or promise complete
effective-profile output.

**Alternative:** defer PK-03 until PromptKit provides an owner-redacted complete
profile inspection representation with provider-parameter treatment. This yields
one fuller report contract and keeps sensitivity decisions entirely upstream,
but delays useful named-profile inspection and expands upstream prerequisites.
Directly serializing all current `ExtraParams` does not establish safe inspection
semantics and is not a substitute for choosing a disclosure contract.

### OD-4: standard selector and validation-report behavior

**Recommendation:** use presence-aware `--config` and singleton `--overlay`, plus
explicit typed context bindings with scope applicability. Use `--path` for
configuration explanation and operands for named definitions. Validate coverage
and declared input combinations before acquisition. For aggregate validation,
report completed scopes in order and stop at the first operational failure.
Use the proposed text/YAML schemas above. This is a small consistent initial
operator surface; native show retains its separate preparation requirement.

**Alternative:** expose distinct application/engine source flags and acquire all
validation results before emitting one aggregate report. Separate selectors make
independent source selection explicit and complete validation results are useful
for tooling. They increase input vocabulary and need a defined aggregation/error
model. Adopt these where actual consumers need independent roots or comprehensive
validation in one invocation, rather than assuming every engine follows the app
selection. A narrower variant retains shared selectors and only changes validation
aggregation. Decide these report/selection details before publishing contracts.