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. It does not sequence implementation tasks or describe existing Go code. CommandKit currently has no Go module or dispatcher implementation.

The architecture policy 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	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 four earlier roadmaps, dispatcher proposal, backend proposal, and facade proposal 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 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 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:

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, 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.
• 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: 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 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: 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.

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