Complete module release documentation

docs/roadmap/implementation.md

@@ -1,6 +1,6 @@
 # Implementation plan: individual Go module releases
 
-Status: ready for implementation.
+Status: complete; all 15 stages implemented and locally verified.
 
 ## Objective and authority
 
@@ -756,6 +756,17 @@ evidence describe the complete implemented feature.
 record the full-suite and compiled API check results, and confirm that the
 implemented examples and canonical documentation agree with the current API.
 
+**Completed:** Updated facade GoDoc, consumer and CLI/configuration guidance,
+Gitea and internal ownership documents, recovery guidance, and maintained
+examples for module selection, full tags, path bases, shared files, preparation,
+and receipt ownership. Added pending next-release notes with migration guidance
+and corrected the current Go minimum facts. Audited acceptance coverage against
+the stage-owned tests and reviewed ReleaseKit's root release procedure against
+the adopted release policy; no new release gates were added. Verified
+`go test ./...`, `go run ./internal/apicheck`, local links and heading fragments
+in 13 changed Markdown documents, multi-module shell/config/module syntax, and
+`git diff --check`.
+
 ### Acceptance coverage audit
 
 | Requirement | Primary stage/evidence owner |

docs/roadmap/next-release-notes.md

@@ -0,0 +1,100 @@
+# Pending notes for the next release
+
+Status: pending release preparation. This feature does not select a release
+version or move this draft to `docs/releases/<version>.md`.
+
+## Release individual Go modules
+
+ReleaseKit operations can now select one Go module within a Git repository.
+Omitted module selection retains the repository-root default. A selected module
+is identified by both its repository-relative physical directory and its own
+declared module path. ReleaseKit derives a semantic version's complete Git tag
+from that identity, including Go's `/v2` major-version convention. For example,
+`v2.1.0` for a module declared as `example.com/project/integrations/core/v2`
+uses `integrations/core/v2.1.0`, whether the module is physically stored at
+`integrations/core` or `integrations/core/v2`. Its release note stays at the
+physical module's `docs/releases/v2.1.0.md` path.
+
+The public `Check`, `Publish`, `Build`, and `Deliver` requests add `ModuleDir`;
+results expose the resolved module directory, declared module path, and complete
+tag alongside existing commit and outcome evidence. `Version` remains the
+stable semantic version used in note titles, binary version output, and asset
+names. Git publication and hosted delivery use the complete tag. Product
+commands receive both repository and module paths, and candidate callbacks
+receive the module identity.
+
+`ValidationSpec.SharedFiles` and profile `validation.shared_files` allow a
+repository-relative list of committed shared files to join optional file
+checks. Omission or `null` selects the available root `COPYRIGHT`, `LICENSE`,
+and `docs/oss/attribution.md` defaults; an explicit list replaces those
+defaults, and `[]` selects none. Explicit files must exist even when file
+checks are disabled. This selection does not enable a check.
+
+Profiles add `module_dir` for physical module selection. The CLI's `ci-deliver`
+now takes a full Git `TAG`; its final path component supplies the semantic
+version. The optional `--prepared` mode verifies an already prepared checkout
+without fetching or checking it out again. `--expected-module` binds a mapped
+launcher selection to the selected profile. The public tagged-checkout request
+renames `Version` to `Tag` and adds `VerifyOnly`; dependency preparation now
+takes a `DependencyPreparationRequest` with repository and module directories.
+`DeliveryRequest.ExpectedTag` binds delivery to the exact CI event tag before
+building artifacts or contacting Gitea.
+
+The private `.releasekit-build.json` receipt now requires schema version 1 and
+binds artifacts to the module directory, declared module path, semantic
+version, complete tag, source commit, normalized build settings, and artifact
+declarations. Older and unversioned receipts are rejected; rebuild with the
+updated `build` command before using `deliver --assets DIR`.
+
+The maintained [multi-module example](../../examples/multi-module/) shares a
+four-column `release-modules.tsv` and POSIX selector between its local launcher
+and mapped Woodpecker workflow. The workflow verifies and detaches the triggering
+tag before reading the mapping, profile, module files, or ReleaseKit version.
+Retries therefore use the original tagged source after the default branch
+changes. Root-only consumers can keep the ordinary profile and the simpler
+[root tag workflow](../../examples/woodpecker/tag-delivery.yml) without a map.
+
+## Consumer migration
+
+Update callers, profiles, receipts, and CI declarations together for this
+clean interface cutover; compatibility shims and legacy receipt readers are
+not provided.
+
+- Set `ModuleDir` in Go requests or `module_dir` in profiles for a nested
+  module. The selected directory must contain its own `go.mod`; module paths
+  and release tags are read from that declaration, not inferred from a folder
+  name. Keep `Version` as a semantic version in ordinary commands and API calls.
+- Update reads of result identity to use `ModuleDir`, `ModulePath`, and `Tag`
+  where needed. Product commands can use `RELEASEKIT_REPOSITORY_DIR` and
+  `RELEASEKIT_MODULE_DIR` to distinguish repository-level work from
+  module-local checks.
+- Replace `TaggedCheckoutRequest.Version` with the complete `Tag`. Set
+  `VerifyOnly` when a bootstrap step already verified and detached the event
+  checkout. Change `PrepareBuildDependencies` calls to pass a
+  `DependencyPreparationRequest`.
+- Add `module_dir` and, when needed, `validation.shared_files` to profiles.
+  Recheck profile-relative and repository-relative paths. Prepare and commit
+  each binary module's `go.sum` before tagging so dependency preparation leaves
+  the tagged source clean for delivery verification.
+- Change `ci-deliver VERSION` invocations to pass the full event `TAG` and
+  required `--commit OID`. Maintained bootstraps should use `--prepared` after
+  verifying the tag and commit. A mapped launcher should pass
+  `--expected-module DIR`; the profile remains the source of selection.
+- Regenerate existing build receipts with the new `build` command before
+  prebuilt delivery. Do not edit old receipts into the new format.
+- Root-module validation now excludes independently released nested modules
+  from module-scoped file checks. Run a nested module's checks from that module
+  when it is the release unit. Nested module fixtures remain available to the
+  parent module's product tests.
+
+ReleaseKit's current consumer minimum remains Go 1.26.0. Root-module releases
+retain their existing note path, unprefixed tags, profile defaults, and small
+root-only workflow. A successful push of the intended source tag remains the
+source-release completion point; hosted page and asset delivery remains
+asynchronous and may be retried from the same immutable tag. No live-service,
+deployment, or consumer-rollout gate is introduced.
+
+For current behavior, see the [API and consumer guides](../consumers/),
+[CLI contract](../cli.md), [configuration reference](../config.md),
+[Gitea integration](../integrations/gitea.md), and
+[ReleaseKit release procedure](../release.md).