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. Implementation steps and stage evidence belong in the completed initial implementation record. 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.

The architecture policy 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; implemented operator contracts belong in the CLI reference. The internal overview 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	REG-01, INPUT-01, INV-01, INT-01
Use Cobra/pflag internally; initially rebuild backend state for each invocation.	ADR 0002	BACK-01, INPUT-01
Expose one root facade with root-owned public named types and no backend leakage.	ADR 0003	API-01, BACK-01
Supply standard help/version and available configuration/PromptKit inspection operations; families may support different subsets.	ADR 0004	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	OUT-01
Apply namespace/resource-first grammar, options after the complete command path, interspersed operands, presence, and selected repetition rules.	ADR 0006	INPUT-01, HELP-01
Preserve native effective YAML; prepare all selected show views before writing; frame aggregate display as separate documents.	ADR 0007	CFG-03
Compare safe semantic snapshots with sensitivity union and explicit coverage gaps when comparison is enabled.	ADR 0008	deferred DIFF-01
Declare scope capabilities; default to app; preserve the meaning and coverage of all; order scopes consistently.	ADR 0009	CFG-01–05, INT-01

The CLI planning record, dispatcher record, backend record, and facade record 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 requires pflag v1.0.9.
pflag	v1.0.9	Match that Cobra baseline; its module declaration 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:

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, metadata, PromptKit configuration inspection, engine methods, and inspection types. 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: 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: 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: 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: 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. 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 status is tracked in the adoption roadmap; current release operations are in the maintainer procedure. Its completed implementation record is available at the historical adoption revision. 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: 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.