Add reusable CI preparation operations

docs/consumers/delivery.md

@@ -7,6 +7,37 @@ The operation accepts historical lightweight and annotated tags, including a
 detached checkout, when the checked-out `HEAD` identifies the selected tag
 commit. It does not require the old remote `main` to match.
 
+## CI preparation
+
+Use `PrepareTaggedCheckout` when a disposable CI checkout must be verified
+against the commit that triggered the job. It fetches only the selected tag
+from the chosen remote (default `origin`), compares the peeled tag commit with
+the expected commit, and checks out that commit detached. Fetch or checkout
+conflicts are returned so the caller can replace or repair the workspace.
+Cancellation is returned to the caller; the operation does not publish a tag
+or hosted content.
+
+```go
+err := releasekit.PrepareTaggedCheckout(ctx, releasekit.TaggedCheckoutRequest{
+    RepositoryDir:  repositoryDir,
+    Version:        version,
+    ExpectedCommit: ciCommit,
+})
+if err != nil {
+    return err
+}
+```
+
+For binary profiles, call `PrepareBuildDependencies(ctx, repositoryDir)` after
+checkout preparation and before delivery. It runs `go mod download` with
+workspace discovery disabled and the available compatible local Go toolchain.
+The operation may use the network and updates the Go module cache while
+preserving the caller's proxy, private-module, credential, and cache settings.
+If checksums are missing, Go may update `go.sum`; see the
+[Go Modules Reference](https://go.dev/ref/mod#go-mod-download). Cancellation
+and command errors are returned. Page-only profiles do not need dependency
+preparation.
+
 ## Command line
 
 Add a Gitea destination to the profile:

docs/internal/overview.md

@@ -6,7 +6,8 @@ two Go facades and a command-line interface:
 - The root `releasekit` package is the orchestration facade. `Check` validates
   one local candidate, `Publish` validates and publishes its exact annotated
   source tag, `Build` compiles selected application targets, and `Deliver`
-  delivers a tagged note page and any declared assets.
+  delivers a tagged note page and any declared assets. `PrepareTaggedCheckout`
+  and `PrepareBuildDependencies` provide explicit local CI preparation.
 - `buildinfo` is the small runtime facade. `Version` reports the injected
   application version, the main-module version when available, or `dev`.
 - `cmd/releasekit` is the executable interface. Its `version`, `check`,
@@ -39,11 +40,12 @@ these implemented packages:
 | `internal/build` | Candidate-build coordination, selected Go target compilation, version injection, native smoke check, and artifact digests. |
 | `internal/candidate` | Stable-version, note, repository-state, candidate capture, and post-validation checks. |
 | `internal/delivery` | Tagged-source and release-note checks, managed builds in disposable storage outside the checkout, prebuilt artifact validation, manifest assembly, and hosted delivery coordination. |
-| `internal/git` | Git command boundary, push-destination resolution, exact ref inspection, and tag operations, including captured-endpoint verification during recovery. |
+| `internal/git` | Git command boundary, push-destination resolution, exact ref inspection, tagged checkout preparation, and tag operations, including captured-endpoint verification during recovery. |
 | `internal/gitea` | Gitea API transport, hosted release pages, asset inspection, manifests, and uploads. |
-| `internal/gotool` | Effective Go configuration discovery and shared native-validation and static-build environments; see [Go command environments](gotool.md). |
+| `internal/gotool` | Effective Go configuration discovery, shared native-validation and static-build environments, and network-capable dependency preparation; see [Go command environments](gotool.md). |
 | `internal/tempdir` | Disposable system temporary storage outside source worktrees. |
 | `internal/process` | Cancellable child-process execution with per-command environment overlays and removals. |
+| `internal/preparation` | Coordination for expected-commit tag checkout and Go module dependency preparation. |
 | `internal/publish` | Publication guards, one validation run, annotated tag creation, push, and recovery state. |
 | `internal/runtimeinfo` | Private version lookup used by the runtime facade. |
 | `internal/versioncontract` | Shared stable-version rules and linker-symbol identity. |
@@ -70,6 +72,7 @@ not a separate release matrix:
 | Publication partial and uncertain recovery | `internal/publish`, `internal/git` | `TestPublishRejectedPushKeepsLocalTagAndReportsNotPublished`, `TestPublishLostAcknowledgmentConfirmsExactRemoteObject`, `TestPublishLostAcknowledgmentWithChangedEndpointRemainsUnknown`, `TestPublishUnavailableReconciliationRemainsUnknownAndPreservesPushError` |
 | Cross-builds, version smoke checks, empty target sets, and partial outputs | `releasekit.Build`, `internal/build`, `buildinfo` | `TestBuildCreatesSelectedTargetsAndInjectsVersion`, `TestBuildWithNoTargetsDoesNotInvokeCompiler`, `TestBuildReturnsPartialArtifactsAfterTargetFailure` |
 | Page-only and managed or prebuilt binary delivery | `releasekit.Deliver`, `internal/delivery`, `internal/gitea`, CLI | `TestDeliverPageOnlySkipsBuildAndHostedAssets`, `TestDeliverManagedBuildUploadsArtifactsAndCleansTemporaryOutput`, `TestDeliverPrebuiltArtifactsRemainCallerOwned`, `TestDeliverManagedBuildFailureCleansTemporaryOutputBeforeHostedWrites`, `TestDeliverManagedBuildCancellationCleansTemporaryOutput`, `TestDeliverBuildsTaggedArtifactsAndReusesAssets`, `TestDeliverRejectsTamperedAssetsAndStaleReceiptBeforeRemoteWrites` |
+| Tagged checkout and build dependency preparation | `releasekit.PrepareTaggedCheckout`, `releasekit.PrepareBuildDependencies`, `internal/preparation`, `internal/git`, `internal/gotool` | `TestPrepareTaggedCheckoutFetchesExpectedCommitAndDetaches`, `TestPrepareTaggedCheckoutRejectsWrongCommitBeforeCheckout`, `TestPrepareTaggedCheckoutReportsLocalCheckoutConflict`, `TestPrepareTaggedCheckoutReportsConflictingLocalTag`, `TestPrepareBuildDependenciesPreservesPreparationEnvironment`, `TestPrepareBuildDependenciesPropagatesCommandFailure`, `TestPrepareBuildDependenciesPropagatesCancellation` |
 | Page, manifest, asset comparison, and additive retry outcomes | `internal/gitea` | `TestEnsureReleaseCreatesMissingPageFromCommittedNote`, `TestInspectAssetsDetectsSameNameAndSizeWithDifferentBytes`, `TestUploadMissingPartialFailureThenRerunOnlyMissingAssets` |
 | CLI profiles and prepared Woodpecker sequences | `cmd/releasekit`, `cmd/releasekit/internal/cli`, `examples/woodpecker/` | `TestLoadSettingsRejectsInvalidProfiles`, `TestWoodpeckerDeliveryCommandSequences`, `TestReleaseKitSourceDeliveryWorkflowFromTaggedCheckout` |
 

docs/roadmap/implementation.md

@@ -1,6 +1,6 @@
 # ReleaseKit audit implementation plan
 
-Status: Stages 1–7 complete; Stage 8 next.
+Status: Stages 1–8 complete; Stage 9 next.
 Baseline: `e4be7fa` (2026-10-06). The [audit](audit.md) records the evidence,
 product goals, and selected direction. This document owns implementation order
 and completion criteria for that work.
@@ -412,6 +412,18 @@ uses the repository and preparation environment and propagates failure and
 cancellation. Keep default tests offline with a local module cache or a small
 Go-command fixture; no live module server is needed.
 
+**Completed:** The root facade now exposes `PrepareTaggedCheckout` and
+`PrepareBuildDependencies`. Checkout preparation fetches an explicit tag
+refspec, compares the peeled commit with the expected full object ID, and
+detaches only after a match; tests cover default and selected remotes, wrong
+commits, conflicting local edits and tags, and input rejection before fetch.
+Dependency preparation runs `go mod download` with workspace discovery off and
+the local Go toolchain, preserving caller proxy, private-module, and cache
+settings; subprocess fixtures verify repository selection, failure details,
+and cancellation without network access. GoDoc, the delivery consumer guide,
+and the internal inventory describe effects and ownership. The full offline
+suite, API boundary check, and documentation whitespace checks pass.
+
 ## Stage 9 — Add the shared CI delivery command
 
 **Covers:** the shared command portion of F6.