Plan the multi-module implementation sprint

docs/roadmap/modules.md

@@ -1,11 +1,10 @@
 # Optional integration modules
 
-Status: module boundary accepted in ADR 0010; implementation planning remains
-in progress and no module extraction has begun. The consumer API is finalized
-and its ADR/architecture-policy alignment is complete. The internal registration
-and execution design is finalized, including both composition-question resolutions.
-The next minor ReleaseKit release will support individual module releases;
-CommandKit adoption is pending.
+Status: module boundary accepted in ADR 0010; consumer API and internal backend
+design finalized, with both composition questions resolved. The
+[staged implementation plan](implementation.md) is complete; no module extraction
+has begun. ReleaseKit v0.4.0 provides module-release support; CommandKit adoption
+is pending.
 
 ## Purpose and authority
 
@@ -15,7 +14,9 @@ should acquire neither ConfigKit nor PromptKit through CommandKit's package or
 module dependencies. ConfigKit-only consumers should not acquire PromptKit.
 
 This roadmap records the targeted end state, selected module layout, and
-migration work. The finalized [registration API](registration-api.md) owns the
+delivery boundaries. The [implementation plan](implementation.md) owns the ordered
+steps and validation needed to reach this target. The finalized
+[registration API](registration-api.md) owns the
 selected declarations, installation semantics, and representative consumer
 examples. The finalized [registration backend design](registration-backend.md)
 owns internal structure, shared installation/execution mechanics, and the resolved
@@ -31,8 +32,11 @@ 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
+Give the existing prototype implementation zero deference when selecting the
+final API, as directed for this transition. Core `v0.1.0` has since been published;
+preserve that release and prepare the incompatible replacement as a fresh minor
+release under the release policy. Publication does not change the selected API
+or require compatibility wrappers for this sprint. 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
@@ -171,9 +175,9 @@ shapes merely because they already exist.
 
 ### Selected multi-module release approach
 
-Adopt the next minor ReleaseKit version with module-release support. This is a
-planned tooling upgrade from the current v0.3.0 baseline, not an implemented
-CommandKit capability. Use ReleaseKit's public contracts for checking and
+Adopt ReleaseKit v0.4.0 with module-release support. This is a planned tooling
+upgrade from the current v0.3.0 baseline, not an implemented CommandKit capability.
+Use ReleaseKit's public contracts for checking and
 publishing one explicitly selected module per invocation; do not build a separate
 CommandKit publication engine or temporary compatibility path.
 
@@ -195,144 +199,92 @@ without CI, hosted delivery, proxy-availability, or installation gates.
 
 CommandKit's preferred shared file inputs are repository-root `COPYRIGHT`,
 `LICENSE`, and `docs/oss/attribution.md`, when present, rather than the entire
-root `docs/` tree. Use the forthcoming configurable list or its defaults as
-documented by ReleaseKit. Shared inputs affect enabled file checks, not Go suite
-scope; resolving references does not add surrounding directories to the inputs.
+root `docs/` tree. Use v0.4.0's `validation.shared_files` field to select those
+three files explicitly, as documented by ReleaseKit. Shared inputs affect enabled
+file checks, not Go suite scope; resolving references does not add surrounding
+directories to the inputs.
 
 Keep module selection and profile lookup repository-relative, module-owned
 validation settings and product-command execution module-relative, and diagnostic
 paths repository-relative. Use the provided repository context for shared scripts.
-Confirm exact profile fields, command syntax, context exposure, and shared-file
-selection semantics against the released public documentation during adoption.
-These are integration tasks, not remaining choices between publication engines.
+The released [profile](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/b96262eb0ce9c8f2eb3e948a5841db2b799bc91b/docs/config.md)
+and [CLI](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/b96262eb0ce9c8f2eb3e948a5841db2b799bc91b/docs/cli.md)
+contracts govern profile fields, command syntax, module context, and shared-file
+selection. The implementation plan specifies their adoption; no separate
+publication engine is needed.
 Nested-module artifact builds, hosted delivery, and batch publication are not
 needed for CommandKit's source-only releases.
 
-## Work sequence
+## Consumer examples and validation target
 
-### 1. Prepare the selected API for implementation
+Three maintained public consumers demonstrate the final API:
 
-Completed: ADR 0010 is accepted and ADR 0003 is marked partially superseded,
-with its decision text preserved. The consumer API is finalized, ADR 0011
-records its registration and input-lifetime choices, ADR 0001 remains accepted
-with refinements recorded in ADR 0011. ADR 0010's consumer-migration consequence
-is superseded for the unreleased prototype transition. The architecture policy
-reflects the selected core/integration facades, installed-family ownership, and
-scope-aware configuration input validation. Earlier accepted decision text remains
-intact. The internal backend design is also finalized; its runnable-child,
-scope-error attachment, and unused-binding decisions are incorporated into the
-API target. Both composition questions are resolved.
+| Adoption path | Example home | Required evidence |
+| --- | --- | --- |
+| Core only | `examples/core` | Typed commands/groups, presence, help/version; no optional-library imports or module requirements |
+| ConfigKit only | `integrations/ckconfig/examples/simple` | Focused `AppCommand` convenience and standard config reports; no PromptKit imports or module requirements |
+| ConfigKit and PromptKit | `integrations/ckprompt/examples/composed` | Combined configuration scopes, typed applicable selectors, independent scope inputs, shared state, named definition inspection, and an application-owned command |
 
-- Use the finalized [registration API](registration-api.md) and selected module
-  layout together with the [backend design](registration-backend.md) as the
-  implementation target before moving public symbols.
-- Inventory root exports, imports, private helper use, and family registration
-  behavior. Use the inventory as evidence of responsibilities and coupling, not
-  as a list of APIs to preserve. Implement final exports and ownership from the
-  selected API and consumer needs; no compatibility mapping for the unpublished
-  prototype is required.
-- Use the API document's [three representative consumers](registration-api.md#complete-consumer-registration-examples):
-  core only, ConfigKit only, and both libraries. They define the target wiring,
-  including combined configuration scopes and independent definition inspection;
-  port them into maintained examples as implementation lands.
-- Prepare a staged implementation plan from this roadmap, the finalized API,
-  and the finalized [backend design](registration-backend.md),
-  preserving the unreleased-prototype organizing principle above.
+Tests, fixtures, and benchmarks belong to the module owning their contracts.
+Mixed suites are split by responsibility; root tests and examples cannot
+reintroduce optional integration dependencies. Public composition checks belong
+in the PromptKit integration. Relevant existing coverage is retained or rewritten
+for selected behavior rather than incidental prototype API shapes.
 
-Completion: the dependency direction, final API, and registration approach
-are concrete enough to implement without inventing a general plugin framework.
+Validation addresses package imports and each independently selected module
+graph, including transitive and tool requirements. Core-only consumers exclude
+both owning libraries and integrations; ConfigKit-only consumers exclude
+PromptKit and its integration. Root `go test ./...` alone cannot validate nested
+modules. The three modules' suites and representative public consumers provide
+composition evidence without an exhaustive historical compatibility matrix.
 
-### 2. Extract the integrations and isolate the core
+Local workspace composition supports development; distributed manifests contain
+versioned inter-module requirements, without filesystem replacements or committed
+workspace files. Workspace-off prepublication checks against local intended
+source establish wiring and isolation, not published-version availability.
+Released consumers resolve actual independently released versions without
+adjacent checkouts or consumer replacements. The implementation plan defines the
+prepublication checks and ordered release handoff.
 
-- Establish the selected module layout, preserving the existing root import
-  path for the core. Use the backend document's [internal ownership boundaries](registration-backend.md#selected-internal-ownership)
-  when organizing private declarations, bindings, registry, execution, neutral
-  metadata, and the Cobra adapter.
-- Move configuration declarations, registration, handlers, reports, and
-  ConfigKit adapters together. Move PromptKit declarations, handlers, reports,
-  and its configuration-scope adapter into the PromptKit integration.
-- Use the shared installer and typed compiler for every command source, including
-  built-in help/version. Replace direct registry writes, duplicated family
-  collision checks, and integration-specific core state with the selected
-  captured-declaration path. Integration factories use public core contracts,
-  and `ckprompt` uses the selected scope-error attachment contract in `ckconfig`.
-- Follow the backend document's [integration preparation design](registration-backend.md#integration-preparation-without-parallel-execution-frameworks)
-  for selected inputs and shared state. Preserve each operation's acquisition
-  and report timing while removing repeated scope selection and mixed-context
-  projection.
-- Implement core outcomes, diagnostics, bindings, and command declarations using
-  the finalized 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
-  maintainer dependencies is not a prerequisite.
-- Use released inter-module requirements for consumer builds. Local workspace
-  composition may support development, but published modules must not depend
-  on sibling checkouts or consumer-applied `replace` directives.
+## Documentation and distribution target
 
-Completion: core-only and ConfigKit-only consumers have the intended dependency
-boundaries, while the composed consumer retains the existing standard commands.
+Implemented GoDoc owns exact exports and error/lifetime semantics. The consumer
+guide and READMEs present the final imports and optional-module selection directly;
+maintained examples demonstrate it. The CLI reference retains selected operator
+behavior, with registration/ownership prose matching the implemented API. Internal
+inventory and contributor navigation describe implemented owners and validation.
+No separate downstream prototype migration guide is required.
 
-### 3. Move examples and validate the consumer boundaries
+Each integration distributes a module-local README, project grant, complete
+license texts, applicable attribution and required notices, and module-local
+release notes. Required licensing material remains available in that module's Go
+source distribution rather than only through an outside-module local link. The
+existing grant and separately licensed material retain their terms. Repository
+attribution can retain factual entries for integration material while module-local
+notices identify applicable components.
 
-- Keep a genuine core-only example with no configuration-library imports. Place
-  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 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
-  PromptKit. Merely observing a smaller executable is insufficient.
-- Exercise combined `app` and `promptkit` configuration scopes and independent
-  installation of named PromptKit inspection through public APIs.
-- Run each module's relevant suite. Verify ordinary module consumption with
-  workspace mode disabled so local workspace resolution cannot hide missing
-  requirements. Root `go test ./...` alone will not cover nested modules.
+Modules use independent versions. The planned core replacement is `v0.2.0`;
+ckconfig and ckprompt initially use `v0.1.0`. Their dependency requirements express
+that relationship explicitly. The already published root `v0.1.0` and its note
+remain intact. If a planned version is occupied before preparation, select a
+fresh appropriate version under the release policy. Core publication precedes
+ckconfig, which precedes ckprompt; actual released dependencies and corresponding
+sums are prepared for each candidate. Source-only publication still completes at
+successful tag publication, without proxy-availability or installation gates.
 
-Completion: representative public consumers demonstrate isolation and retained
-composition. These checks protect the selected boundary without requiring an
-exhaustive matrix of historical dependency versions.
+The release procedure and CommandKit-specific release-policy adaptations describe
+selected-module publication, independent versions, semantic-version note paths,
+full-tag links and recovery identity, and the root shared-file selection. Release
+profiles and launcher use released ReleaseKit contracts; additional delivery
+services and permanent migration gates are outside the target.
 
-### 4. Prepare final API documentation and initial module releases
+## Implementation status
 
-- 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.
-- 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.
-- Upgrade the module-selected ReleaseKit tool to the next minor release providing
-  module-release support. Adopt its released public API and CLI/profile contracts
-  through the shared launcher and per-module profiles described above. Update
-  launcher checks, validation context, version/tag reporting, and recovery guidance
-  for selected-module publication; do not duplicate ReleaseKit-owned guards.
-- Align the release policy and procedure with module-local notes, independent
-  versions, full-tag identity, and selected-module validation. Confirm the
-  documented shared-file defaults or configure the selected files explicitly.
-- For nested modules, use Go's module-subdirectory tag prefixes and make
-  release-note paths and immutable links unambiguous. Review licensing and
-  attribution visibility in each distributed module under the
-  [OSS policy](../policy/oss.md).
-- Establish publication order from module dependencies and record compatible
-  requirements explicitly. Published consumers must resolve actual released
-  versions. A local workspace is not a substitute for that release sequence.
-  Preserve the existing successful-source-publication completion model.
-
-Completion: every consumer module can be released and consumed independently of
-local workspace state, with documentation of the final public API and optional
-integration choices.
+ADR/architecture alignment, public API design, and internal backend design are
+complete. Module extraction, code refactoring, maintained consumers, validation,
+current documentation, and multi-module tooling adoption are not implemented.
+The [16-stage implementation plan](implementation.md) owns the sequence and
+completion evidence. Earlier accepted ADR decision text remains intact.
 
 ## Scope and follow-up