Plan complete module support across release operations

docs/roadmap/module-releases.md

@@ -1,18 +1,18 @@
 # Roadmap: release individual Go modules
 
-Status: planned feature; open recommendations await resolution.
+Status: planned feature; scope decisions resolved.
 
 ## Purpose
 
-Implement [ADR 0005](../adr/0005-module-release-scope.md) so a consumer can check
+Implement [ADR 0005](../adr/0005-module-release-scope.md) so a consumer can check,
-and publish one selected Go module in a shared repository through ReleaseKit's
+publish, build, and deliver one selected Go module in a shared repository through
-API and CLI. CommandKit's core and optional integrations provide the initial
+ReleaseKit's API and CLI. CommandKit's core and optional integrations provide the initial
 consumer case. Each invocation should require only module selection, product
 settings, and a semantic version, with ReleaseKit owning the common mechanics.
 
 This roadmap describes the target and the work from the current baseline. It
 does not select a ReleaseKit release version or prescribe a staged implementation
-plan. Recommendations under Open Decisions are proposals, not accepted contracts.
+plan. The decisions recorded below govern the planned scope.
 
 ## Current baseline
 
@@ -57,13 +57,16 @@ 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,
 publication, and recovery. A successful source-tag push remains completion.
-Dependency preparation and sibling release ordering remain consumer activities.
+Consumers prepare dependencies before offline candidate validation and choose
+sibling release ordering. Dependency preparation for delivery targets the
+selected module through the existing preparation operation when needed.
 
 The feature covers individual releases. Batch publication, automatic release
 selection, dependency-driven versioning, and arbitrary tag templates remain
-outside this roadmap. Artifact and hosted-delivery integration is an open scope
+outside this roadmap. Artifact builds, hosted delivery, and CI use the same
-decision below. This work adds no consumer-installation, proxy-availability, CI,
+selected module and release identity. Delivery remains asynchronous and supports
-or hosted-delivery completion gate.
+both page-only and binary profiles. This work adds no consumer-installation,
+proxy-availability, CI, or hosted-delivery publication completion gate.
 
 ## Work needed
 
@@ -107,8 +110,7 @@ selected module's check. Determine relevant shared release materials through
 existing conventions; shared files should not pull in an entire parent tree.
 Keep the optional checks optional and retain their existing individual rules,
 error identities, cancellation, and cause propagation apart from the intended
-scope change. Resolve boundary identification and path conventions below before
+scope change. Apply the boundary and path conventions recorded below.
-finalizing these contracts.
 
 ### 3. Bind notes and publication to the resolved identity
 
@@ -126,7 +128,52 @@ as available, alongside commit, endpoint, phase, state, and tag object. Preserve
 the existing publication outcomes and repository checks. Root notes and tags
 retain their ordinary forms.
 
-### 4. Make API and CLI adoption small and coherent
+### 4. Carry module identity through builds and delivery
+
+**Rationale:** A selected module should mean the same release unit throughout
+ReleaseKit's supported operations.
+
+**Target:** Standalone builds, candidate build checks, direct delivery, and
+prebuilt-asset delivery all operate on the selected module. Hosted pages use
+its complete tag and module-local note; binaries report its semantic version.
+
+**Work:** Extend build and delivery requests and profile mapping with the shared
+module identity. Resolve main packages and module-owned build paths from the
+module directory. Prepare build dependencies there, and preserve existing offline
+artifact compilation and version smoke checks. Carry module identity through
+build results and receipts so prebuilt delivery verifies the selected module,
+version, tag where applicable, candidate commit, settings, and artifact hashes.
+Keep ordinary local builds usable without requiring a published tag.
+
+Use the full tag for tagged-checkout verification, Gitea release lookup and
+creation, and source links. Use the semantic version for binary version injection
+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.
+
+### 5. Support module-aware CI delivery
+
+**Rationale:** Local operations and tagged-source delivery need the same module,
+profile, and version selection.
+
+**Target:** The maintained consumer workflow accepts root and nested-module tags,
+selects the corresponding profile, and delivers only that module's release.
+Tool selection follows the tagged module configuration under
+[ADR 0004](../adr/0004-module-selected-tooling.md).
+
+**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.
+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.
+
+### 6. Make API and CLI adoption small and coherent
 
 **Rationale:** The shared release operation should replace consumer publication
 logic with small per-module declarations.
@@ -144,7 +191,7 @@ preparation before offline validation and sequential sibling releases when a
 dependency version must be published first. Keep product checks focused on
 consumer assertions instead of repeating the standard suite.
 
-### 5. Verify and document the complete behavior
+### 7. Verify and document the complete behavior
 
 **Rationale:** This changes release identity and validation boundaries, including
 the behavior of root modules with nested modules.
@@ -160,82 +207,56 @@ checks with violations inside and outside the selected scope, parent selection
 excluding independent nested modules, and cross-module Markdown references.
 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.
+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
+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 guides, adoption
+Update GoDoc, CLI/configuration references, check/publication/build/delivery guides,
-examples, and recovery guidance together. Explain root-module scope changes in
+adoption examples, CI templates, and recovery guidance together. Explain root-module
-the release note and migration guidance. Document semantic version versus full
+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
 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.
 
-## Open Decisions
+## Resolved decisions
 
-### 1. How should nested module boundaries be recognized?
+### Module boundaries
 
-**Recommendation:** Use committed nested `go.mod` locations as module boundaries
+Use committed nested `go.mod` locations as module boundaries for ordinary source
-for ordinary source directories. This follows Go's module structure and avoids
+directories. This follows Go's module structure and avoids a second registry of
-a second registry of independently versioned products. Specify treatment of
+independently versioned products. Vendored material remains part of the selected
-vendored content and fixture modules before implementation: vendored material
+module's file-check inputs. Nested fixture modules are excluded from generic
-remains part of the selected module's file-check inputs, while nested fixture
+parent file checks and can be exercised through the parent's tests or product
-modules can be exercised through the parent's tests or product checks. A
+checks. Document this distinction and verify representative cases.
-repository-level workspace file outside a selected nested module's scope would
-not fail that module's workspace-file check merely because it exists.
 
-The tradeoff is that a nested fixture module can be excluded from generic file
+A repository-level workspace file outside the selected nested module's scope
-checks even when it has no independent release. That distinction needs clear
+does not fail that module's workspace-file check merely because it exists.
-documentation and representative tests.
+Shared release materials and referenced destinations receive the targeted
+inspection described above.
 
-**Alternative:** Declare independently released module directories explicitly
+### Relative paths and product commands
-and exclude only those boundaries. This distinguishes products from fixtures
-precisely and keeps fixture files in their parent's generic validation. It adds
-a declaration consumers must maintain and coordinate with their module layout.
-It is viable if real consumers need that distinction enough to justify the
-configuration.
 
-### 2. Which directory anchors relative paths and product commands?
+Anchor module selection and profile lookup at the repository. Anchor
-
+module-owned validation and build paths, including file-size exclusions, and
-**Recommendation:** Anchor module selection and profile lookup at the repository;
-anchor module-owned validation settings, such as file-size exclusions, and
 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. This makes a
+Markdown destinations remain relative to their source documents.
-per-module profile self-contained while retaining unambiguous findings.
 
-Existing root profiles retain their meaning. Nested-module launchers would use
+Existing root profiles retain their meaning. Nested-module launchers use the
-the provided repository context when invoking shared scripts. Document these
+provided repository context for shared scripts. These conventions keep
-rules together rather than adding a path-base switch to each check.
+per-module profiles self-contained without adding per-check path-base switches.
 
-**Alternative:** Keep configuration paths and product-command execution
+### Complete operation support
-repository-relative, while shared check inputs remain module-scoped. This
-preserves the current conventions and makes shared script invocation direct.
-It requires module prefixes in otherwise module-specific settings and makes
-moving or copying profiles more cumbersome. Both choices can implement the
-accepted validation scope.
 
-### 3. Should nested-module builds and hosted delivery ship with publication?
+Implement module selection across checking, publication, artifact builds,
+hosted delivery, and CI in this feature. The target is a coherent release API
+for root and nested modules. CommandKit's current source-only use supplies an
+adoption case while the feature supports the full existing release workflow.
 
-**Recommendation:** Deliver the requested source-only `Check` and `Publish`
+Implementation may proceed in stages; feature completion includes all of these
-capability first. Keep existing root build/delivery workflows working and document
+operations. Existing single-module defaults and the separation between source
-the supported boundary. For that initial increment, report an unsupported
+publication and asynchronous delivery remain in place.
-nested-module artifact-build request before validation or publication rather
-than building the root product under the nested module's release identity.
-This proposed limitation requires an explicit scope decision; it is not imposed
-by ADR 0005. Package compilation remains part of module validation and is covered
-by this roadmap.
-
-This meets CommandKit's immediate need with a focused change, at the cost of
-requiring follow-up work for consumers needing nested-module artifacts or hosted
-pages. Review shared profile handling so unsupported delivery paths do not
-silently interpret a nested module as the root product.
-
-**Alternative:** Extend artifact builds and hosted delivery in the same release.
-This gives every release operation the same module model immediately. It adds
-work on build paths, semantic-version injection, receipts, tag verification,
-note/source URLs, dependency preparation, and CI profile/tool selection. The
-maintained tag filter and root-only bootstrap also need adaptation. This is a
-viable cohesive release if those consumers are ready; it expands the sprint
-beyond the source-only publication request. Delivery remains asynchronous under
-either choice.