Clarify the final API design and module decisions

docs/roadmap/modules.md

@@ -17,9 +17,25 @@ proposals. It does not describe these changes as implemented.
 boundary and convenient registration principles; it partially supersedes
 [ADR 0003](../adr/0003-public-facade.md), whose remaining principles still apply.
 Alignment of the [architecture policy](../policy/architecture.md) remains part of
-the work below. Current implemented contracts remain in GoDoc, the
-[CLI reference](../cli.md), and the
-[consumer guide](../consumers/guide.md).
+the work below. GoDoc, the [CLI reference](../cli.md), and the
+[consumer guide](../consumers/guide.md) describe the prototype baseline; they do
+not make its incidental API shapes compatibility requirements for this sprint.
+
+## Organizing principle: design the final API
+
+CommandKit is an unreleased prototype with no downstream consumers. Give the
+existing implementation zero deference when selecting the final API. The goal is
+the best, simplest, most coherent API for the accepted responsibilities and
+representative consumers, not the smallest diff or a mechanically relocated
+prototype. Accepted architectural decisions and explicitly selected behavior
+remain requirements; prototype declarations, helpers, bookkeeping, and tests do
+not independently establish contracts.
+
+Complete the transition in one sprint. No backward-compatibility wrappers,
+deprecation period, or migration bridge is needed. Intermediate commits need not
+build or pass tests; do not add temporary machinery merely to make them do so.
+Validate the complete target state before release. Reuse existing code where it
+serves that design, and refactor, replace, or remove it where it does not.
 
 ## Current baseline
 
@@ -31,6 +47,8 @@ The root combines core command infrastructure with configuration and PromptKit
 inspection. Coupling extends beyond constructors:
 
 - `NewConfigKitScope` accepts ConfigKit results and maps their diagnostics.
+- Core `Diagnostic.Severity` currently uses ConfigKit's public severity type;
+  moving inspection handlers alone will not remove that dependency.
 - `SourceReader` returns ConfigKit source records; `ExplanationReader` accepts
   ConfigKit paths and returns ConfigKit explanations.
 - `PromptKitSuite` callbacks return PromptKit inspection types.
@@ -103,11 +121,30 @@ modules. Do not retain root forwarding wrappers that restore those imports.
 Shared helpers stay private unless a concrete cross-module interaction needs a
 supported contract; extraction is not a reason to expose every existing helper.
 
-Preserve current operator behavior during extraction: command vocabulary,
-selection and scope semantics, native reports, diagnostics, error identity,
-outcomes, and help without provider acquisition. Any necessary CLI change must
-be identified and decided separately. Public Go import and symbol relocation
-is an intentional consumer migration.
+Preserve explicitly selected operator behavior: command vocabulary, selection
+and scope semantics, native reports, diagnostics, error identity, outcomes, and
+help without provider acquisition. Identify and decide any changes to selected
+CLI behavior separately. Do not preserve accidental prototype behavior or Go API
+shapes merely because they already exist.
+
+### Selected API and release principles
+
+- Design convenient integration registration around representative consumers.
+  Reuse public command/group registration when it fits the final design. Add a
+  narrow core capability only where a concrete responsibility requires it; do
+  not introduce a general family framework or preserve private bookkeeping for
+  its own sake. Exact signatures remain implementation-planning work.
+- Core diagnostics use a small CommandKit-owned severity type. Upstream
+  diagnostic conversion belongs in the integrations, preserving selected
+  classification, delivery, and error semantics without copying ConfigKit's
+  wider data model into the core.
+- Version the modules independently according to their own changes and the
+  [release policy](../policy/release.md#versioning-and-compatibility). Do not
+  require integration version numbers to match either the core or upstream
+  dependency versions. Record selected dependencies in `go.mod` and explain
+  relevant upstream adoption in module release notes. Coordinate publication
+  when changes span modules; independent versions do not imply an exhaustive
+  compatibility matrix.
 
 ## Work sequence
 
@@ -122,15 +159,16 @@ authorized exception to the documentation policy for this decision.
 - Align the architecture policy with ADR 0010 and review other
   ADRs for affected ownership statements without reopening unrelated decisions.
 - Inventory root exports, imports, private helper use, and family registration
-  behavior. Assign each to core or an integration; document the consumer-facing
-  old-to-new API mapping rather than freezing a full inventory in this roadmap.
+  behavior. Use the inventory as evidence of responsibilities and coupling, not
+  as a list of APIs to preserve. Select final exports and ownership from consumer
+  needs; no compatibility mapping for the unpublished prototype is required.
 - Sketch three representative consumers: core only, ConfigKit only, and both
   libraries. Confirm that combined configuration scopes remain straightforward
   and that registration meets ADR 0010's convenience principle without replacing
   removed boilerplate with new plumbing. Use these examples to evaluate the
   registration API; no fixed call count or particular options pattern is selected.
 
-Completion: the dependency direction, public migration, and registration approach
+Completion: the dependency direction, final API, and registration approach
 are concrete enough to implement without inventing a general plugin framework.
 
 ### 2. Extract the integrations and isolate the core
@@ -144,10 +182,11 @@ are concrete enough to implement without inventing a general plugin framework.
   supported interactions needed by those integrations. Preserve duplicate
   registration handling and standard-family ownership; audit these boundaries
   rather than assuming package relocation preserves them automatically.
-- Keep core outcomes, diagnostics, bindings, and command declarations as shared
-  contracts. Place report encoding and upstream diagnostic conversion with their
-  owners. Avoid copying ConfigKit's data model into the core merely to remove
-  imports.
+- Design core outcomes, diagnostics, bindings, and command declarations as shared
+  contracts for the final API. Replace ConfigKit severity in core diagnostics
+  with the selected CommandKit-owned type. Place report encoding and upstream
+  diagnostic conversion with their owners. Remove redundant prototype state and
+  helpers; avoid copying ConfigKit's data model merely to remove imports.
 - Remove integration dependencies from the core module, including dependencies
   reintroduced by its tests, examples, tools, or remaining public declarations.
   Review tool dependencies for that specific objective; broad removal of all
@@ -165,9 +204,11 @@ boundaries, while the composed consumer retains the existing standard commands.
   ConfigKit and composed examples, fixtures, and integration tests in modules
   that can legitimately depend on those integrations. Choose their exact home
   with the module layout; examples in the root module must not defeat isolation.
-- Move existing behavioral tests with their owners. Retain coverage for typed
-  presence, repeated invocations, registration collisions, provider errors,
-  report delivery, and preserved CLI behavior without duplicating every suite.
+- Move or rewrite existing tests for their final owners and selected contracts.
+  Remove assertions that merely freeze incidental prototype design. Retain
+  coverage for typed presence, repeated invocations, registration collisions,
+  provider errors, report delivery, and selected CLI behavior without duplicating
+  every suite.
 - Add focused consumer checks for the three adoption paths. Verify both package
   dependencies and the selected module graph, including transitive requirements.
   Core-only checks exclude both libraries; ConfigKit-only checks exclude
@@ -182,18 +223,18 @@ Completion: representative public consumers demonstrate isolation and retained
 composition. These checks protect the selected boundary without requiring an
 exhaustive matrix of historical dependency versions.
 
-### 4. Prepare migration documentation and module releases
+### 4. Prepare final API documentation and initial module releases
 
 - Update GoDoc, the consumer guide, maintained examples, README, internal
   inventory, and contributor reading guide as the implementation lands. Keep
   the CLI reference unchanged except where actual behavior or relevant ownership
   changes require an update. Link this roadmap from contributor navigation when
   integrating it into the implementation workflow.
-- Explain moved imports and constructors and the selection of optional modules.
-  Release the incompatible root API change according to the
-  [release policy](../policy/release.md#versioning-and-compatibility); do not
-  publish it as a compatible patch. Inspect actual publication state when
-  selecting versions and preserve existing published tags and notes.
+- Document final imports, constructors, and optional module selection directly.
+  Rewrite prototype guidance where necessary rather than publishing a downstream
+  migration guide. Prepare initial module versions and notes under the
+  [release policy](../policy/release.md); unpublished prototype API changes do
+  not require a compatibility release or a version bump solely for relocation.
 - Adapt release profiles, module discovery, validation, note locations, version
   reporting, and publication commands to the selected release model. Verify
   ReleaseKit's supported capabilities before choosing the mechanics; the current
@@ -208,7 +249,8 @@ exhaustive matrix of historical dependency versions.
   Preserve the existing successful-source-publication completion model.
 
 Completion: every consumer module can be released and consumed independently of
-local workspace state, with a documented migration from the combined API.
+local workspace state, with documentation of the final public API and optional
+integration choices.
 
 ## Scope and follow-up
 
@@ -224,37 +266,37 @@ Semantic comparison retains the upstream-contract dependency recorded in
 
 ## Open Decisions
 
-### Registration across the new public boundary
+### Exact registration API
 
-ADR 0010 selects convenient family registration with specialized composition
-where needed. The remaining decision is how to support it across module
-boundaries.
+The design principle is selected: convenient registration through the simplest
+coherent public core contracts, without preserving the prototype. Exact
+signatures and any additional core capability remain to be settled through the
+three representative consumer sketches and an ownership/collision review.
 
-**Recommendation:** first reuse public command/group registration and duplicate
-path checks. Add only a narrow core registration capability if preserving the
-existing standard-family ownership contract requires it. This keeps integrations
-ordinary Go libraries and avoids exporting root-private state. Its suitability
-must be checked against reserved paths and registration atomicity during the API
-inventory.
+**Recommendation:** integrations construct their standard groups and install them
+through ordinary public registration, adding a narrow capability only if the
+selected ownership or atomicity behavior cannot be expressed coherently. Remove
+redundant private flags and checks rather than reproducing them publicly.
 
-**Alternative:** introduce an explicit public family declaration and installation
-API for all standard suites. This can give ownership and collision handling a
-clear shared representation if ordinary registration proves insufficient. It
-also creates a new long-lived abstraction that may duplicate command groups;
-prefer it only when the concrete extraction shows a distinct responsibility.
+**Alternative:** an explicit public family declaration and installation API can
+represent ownership and collision handling if command groups cannot adequately
+express those responsibilities. It adds a lasting abstraction, so select it only
+for a demonstrated consumer or core responsibility, not to imitate current state.
 
-### Versioning and publication cadence
+### Multi-module release mechanics
 
-**Recommendation:** version modules independently, declare their supported
-minimum dependency versions through ordinary module requirements, and coordinate
-releases when changes span modules. Core-only consumers then avoid unrelated
-integration releases. This requires clear per-module notes and publication
-ordering; exact tooling and note placement need verification before adoption.
+Independent versioning is selected. Exact release tooling and per-module note
+locations still require investigation of ReleaseKit's supported capabilities.
+This is release-workflow design work, not a reason to retain the combined module.
 
-**Alternative:** release all three modules with matching version numbers on a
-coordinated cadence. A single documented release set simplifies communication
-and initial testing, while still retaining separate dependency graphs. It causes
-unchanged modules to receive releases and still needs distinct Go tags and
-inter-module dependency ordering; matching numbers alone do not enforce
-compatibility. Neither choice implies support for every possible version
-combination.
+**Recommendation:** reuse shared publication machinery with explicit module
+selection, module-specific versions and notes, and the appropriate tag prefixes.
+Validate the selected candidate and publish in dependency order as required by
+actual module requirements. Keep the successful source-publication completion
+model and avoid duplicate validation of an unchanged final candidate.
+
+**Alternative:** maintain separate per-module release entry points or profiles
+using ReleaseKit's supported mechanisms. This may be simpler if ReleaseKit is
+intrinsically single-module, but risks duplicated guards and inconsistent
+procedures. Verify its capabilities before selecting exact commands; neither
+approach requires matching module versions or a new general release framework.