Plan a clean module release API and receipt cutover

docs/roadmap/module-releases.md

@@ -53,8 +53,7 @@ scope. Independently released nested modules are excluded from their parent's
 automatic validation inputs. Shared file selections follow the
 [resolved shared-file rules](#shared-file-validation-inputs). Checks may read
 referenced material elsewhere in the captured repository without adding that
-material's surrounding files to the
-input set. The checkout remains the boundary for outside-checkout link checks.
+material's surrounding files to the input set. The checkout remains the boundary for outside-checkout link checks.
 
 Repository cleanliness, branch, candidate commit, remote endpoint, and publication
 guards remain repository-wide. The complete selected tag governs uniqueness,
@@ -85,6 +84,9 @@ request and profile, with root defaults. Resolve it against the captured
 repository and committed module declaration. Derive tags using Go's standard
 module conventions, including major-version directories: a `/v2` module stored
 at `integrations/ckconfig/v2` uses `integrations/ckconfig/v2.0.0` for `v2.0.0`.
+The same module stored at `integrations/ckconfig` uses that complete tag too.
+Support both physical layouts and distinguish the module directory from its
+tag prefix.
 Carry the resolved identity through facade conversions, internal requests,
 callbacks, results, and CLI diagnostics. Keep semantic-version validation
 separate from full-tag handling. Exact field names belong in API design.
@@ -154,7 +156,9 @@ and module release titles. Select the module-local note and retain existing
 page/asset conflict, retry, and partial-delivery behavior. Test source URLs with
 slash-containing tags. Distinct module tags can have separate Gitea pages at the
 same commit. A page-only profile continues to require no application binary.
-Review receipt compatibility deliberately and document any required migration.
+Use the new module-bound receipt format for prebuilt delivery. Consumers
+regenerate receipts through the updated build operation as part of the clean
+cutover described below.
 
 ### 5. Support module-aware CI delivery
 
@@ -169,9 +173,11 @@ Tool selection follows the tagged module configuration under
 **Work:** Extend tagged-checkout preparation and `ci-deliver` to distinguish the
 full event tag from the semantic version. Adapt tag filters, profile selection,
 tool bootstrap, and application dependency preparation. Use an explicit
-module/profile mapping or equivalent small consumer declaration; keep the
-selection consistent with the derived tag. Verify the event commit before tool
-bootstrap and use the tagged source's selected module files on retries.
+module/profile mapping or equivalent small consumer declaration from the
+verified tagged checkout. Resolve the physical module directory and profile
+before tool bootstrap, and keep the selection consistent with the derived tag.
+Verify the event commit before resolving that mapping and use the tagged
+source's selected module files on retries.
 Preserve temporary bootstrap metadata and existing credential handling. Cover
 major-version directory layouts without assuming that trimming the tag always
 identifies the physical module directory. Include page-only and binary examples.
@@ -204,8 +210,9 @@ selected module is validated and only its intended tag is published.
 
 **Work:** Extend existing behavioral tests using local repositories and remotes.
 Cover root defaults; nested-module failure while the root suite passes; equal
-versions across modules; major-version directories; full-tag reuse; and failed
-or unknown publication with the correct recovery identity. Exercise optional
+versions across modules; major versions with and without physical major-version
+directories; full-tag reuse; and failed or unknown publication with the correct
+recovery identity. Exercise optional
 checks with violations inside and outside the selected scope, parent selection
 excluding independent nested modules, and cross-module Markdown references.
 Cover omitted, replacement, and empty shared-file lists; optional default files;
@@ -215,16 +222,19 @@ disabled, and that shared-file selection preserves enabled checks and Go scope.
 Verify that repository guards still observe changes outside the selected module
 and that module selection does not repeat the standard suite. Reuse existing
 failure tests where they already protect unchanged behavior. Add representative
-nested-module build/version-injection, receipt ownership, Gitea page/asset, and
-CI tag/profile/tool-selection coverage. Use local HTTP servers for delivery and
+nested-module build/version-injection, new-format receipt ownership and cutover,
+Gitea page/asset, and CI tag/profile/tool-selection coverage. Use local HTTP servers for delivery and
 isolated synthetic module proxies for bootstrap tests. Verify that retries use
 the original module selection and full tag after the default branch changes.
 
 Update GoDoc, CLI/configuration references, check/publication/build/delivery guides,
-adoption examples, CI templates, and recovery guidance together. Explain root-module
-scope changes in the release note and migration guidance. Document semantic version versus full
-tag in note titles and source/licensing links. ReleaseKit's own maintainer policy
-continues to describe its root-module release; consumer guidance explains how
+adoption examples, CI templates, and recovery guidance together. Supply migration
+guidance in the next release's documentation, covering API and profile updates,
+receipt regeneration, CI mapping, and root-module scope changes, including
+exclusion of nested fixture modules from automatic file checks. Document
+semantic version versus full tag in note titles and source/licensing links.
+ReleaseKit's own maintainer policy continues to describe its root-module release;
+consumer guidance explains how
 multi-module consumers adapt their policies. Run the normal offline suite and
 public API checks for implementation changes; validate documentation links and
 examples. Synthetic dependency fixtures use isolated module caches.
@@ -283,8 +293,8 @@ configured product-command execution at the selected module. Keep diagnostic
 file paths repository-relative and expose both directories to product commands.
 Markdown destinations remain relative to their source documents.
 
-Existing root profiles retain their meaning. Nested-module launchers use the
-provided repository context for shared scripts. These conventions keep
+Root profiles use the repository-root module by default. Nested-module launchers
+use the provided repository context for shared scripts. These conventions keep
 per-module profiles self-contained without adding per-check path-base switches.
 
 ### Complete operation support
@@ -295,5 +305,17 @@ for root and nested modules. CommandKit's current source-only use supplies an
 adoption case while the feature supports the full existing release workflow.
 
 Implementation may proceed in stages; feature completion includes all of these
-operations. Existing single-module defaults and the separation between source
-publication and asynchronous delivery remain in place.
+operations. Omitted module selection uses the root module, and source publication
+and asynchronous delivery retain their separate outcomes.
+
+### Clean API and receipt cutover
+
+Implement one current API and module-bound receipt format as the complete
+supported interface after cutover. Consumers update their calls, profiles, and
+CI declarations to that interface and regenerate prior receipts through the
+updated build operation. Compatibility shims and legacy receipt readers are
+outside the implementation scope.
+
+Migration means guidance supplied in the next release's documentation. That
+guidance explains the required consumer changes and the root-module validation
+scope change; implementation completion covers the new interface directly.