From a0cb466395b3c91a6c25f7b5cc419969c5a93b44 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 6 Oct 2026 15:37:33 +0000 Subject: [PATCH] Plan the release audit implementation --- docs/roadmap/audit.md | 78 +++--- docs/roadmap/implementation.md | 481 +++++++++++++++++++++++++++++++++ 2 files changed, 518 insertions(+), 41 deletions(-) create mode 100644 docs/roadmap/implementation.md diff --git a/docs/roadmap/audit.md b/docs/roadmap/audit.md index b7fcb29..a42bdc3 100644 --- a/docs/roadmap/audit.md +++ b/docs/roadmap/audit.md @@ -1,7 +1,8 @@ # ReleaseKit pre-release audit Date: 2026-10-06. Reviewed source: `536a57916f6565ae8194c4563577dfcebd6cfb69`. -Status: review findings and proposed changes, revised for the clarified product goals. +Status: historical review evidence and selected target direction for the +[implementation plan](implementation.md). Audience: maintainers deciding the shared release standard before `v0.1.0`. ## Assessment @@ -115,8 +116,8 @@ configuration. Preserve caches and legitimate dependency preparation settings. Share internal Go-environment handling where the semantics match. Preserve the settings appropriate to native tests and static release builds separately. Apply the same baseline to ReleaseKit's own profile. Retain a regression showing -that a failing test remains effective under an ambient filter. F4 and Open Question 1 address how -intentional product-specific checks should compose with this baseline. +that a failing test remains effective under an ambient filter. F4 and Design +Choice 1 describe how product-specific checks compose with this baseline. ### F2 — High: automatic push recovery can query a different endpoint and report false absence @@ -174,7 +175,7 @@ settings that affect expected compatibility or validation. Keep the application profile focused on its package, binary name, and targets. Exact toolchain pinning and detailed build metadata remain optional operational choices. When a retry requires the original bytes, preserve and reuse those artifacts. -Open Question 2 compares local toolchain use with a centrally maintained build +Design Choice 2 compares local toolchain use with a centrally maintained build environment for consumers that benefit from shared setup. ### F4 — Design priority: adding a custom check replaces the entire standard suite @@ -195,8 +196,8 @@ to preserve one suite run. product-specific checks. Move redundant suite invocations out of consumer scripts. Retain checks for actual product behavior, such as PromptKit's examples. Add alternative test-invocation settings when a concrete consumer requirement -justifies them. This proposal changes the current customization contract; Open -Question 1 records the replacement-callback alternative. +justifies them. This choice changes the current customization contract; Design +Choice 1 records the replacement-callback alternative. ### F5 — Design priority: the CLI owns reusable tagged-build delivery orchestration @@ -219,7 +220,7 @@ source before expensive compilation, then retain the necessary checks before remote effects. Let the CLI adapt JSON, credentials, and output to that operation. Use the same build declaration for candidate validation and delivery. Support caller-provided builds for concrete needs such as retrying with retained -artifacts, as discussed in Open Question 3. Keep separate building useful for +artifacts, as discussed in Design Choice 3. Keep separate building useful for local development. The ordinary consumer workflow should complete delivery in one invocation; advanced artifact handoffs can use private coordination data when needed. @@ -241,11 +242,12 @@ publication and CI delivery. **Recommendation.** Provide one maintained integration entry point and one default delivery sequence for source-only and binary profiles. Consumers select the ReleaseKit version, supply product settings, and provision credentials. -Centralize installation and update instructions. Choose source installation or a -maintained image according to the setup and maintenance effort each saves. +Centralize installation and update instructions. Use versioned source +installation for the shared CI command. Evaluate a maintained image by the +additional setup and maintenance effort it saves. Keep dependency preparation separate from offline validation/builds. A split build/delivery flow remains useful for an actual credential boundary or artifact -handoff. See Open Question 4 for packaging alternatives. +handoff. See Design Choice 4 for packaging alternatives. `TestWoodpeckerDeliveryCommandSequences` in [the CLI workflow tests](../../cmd/releasekit/woodpecker_test.go) executes @@ -276,9 +278,8 @@ reporting and automation. **Recommendation.** Prefer mutually exclusive current-outcome categories: confirmed matching, uploaded, known pending, conflicting, and uncertain. Move an asset out of pending when its outcome becomes uncertain or conflicting, and -clarify the facade GoDoc. Alternatively, explicitly define pending as a superset -of all unfinished assets and implement that rule consistently; see Open -Question 5. Update behavioral tests to protect the selected meaning. +clarify the facade GoDoc. Design Choice 5 records the alternative superset +interpretation. ### F8 — Maintainability: artifact rules have several implementation owners @@ -301,7 +302,7 @@ from receipt and delivery adapters. Share Go invocation/environment construction where the semantics match. Keep the explicit facade conversions required by the ADR. Focus refactoring on the small internal helpers that own these rules. -## Recommended standard and release sequencing +## Target state Retain the existing source transaction: committed stable-version note, clean `main`, candidate already on authoritative `main`, one validation, selected-target @@ -316,31 +317,24 @@ ReleaseKit owns the standard suite, routine build settings, delivery sequence, and recovery reporting. Product developers choose versions and write compatibility notes. Evaluate each proposed setting by the work it saves them. -Recommended order: - -1. Fix F1–F2 and retain focused behavioral regressions before tagging `v0.1.0`. -2. Settle the validation and delivery API choices in Open Questions 1 and 3. - Adopt clear result categories under Question 5. Implement the selected - changes with their canonical documentation and consolidate F8 in those owners. -3. Address F3 through internal compatibility defaults, using Open Question 2 to - keep build configuration proportionate to actual consumer needs. -4. Exercise one source-only consumer with an extra product check and one binary - consumer through the common integration. Measure removed scripts, duplicated - tests, setup steps, and recurring release decisions. Keep ReleaseKit's default - suite independent of sibling checkouts. -5. Choose the simplest shared installation and update path under Open Question 4. - Verify the maintained integration during deployment preparation. Follow the - existing maintainer procedure for the release note and source publication; - report hosted delivery separately. +The [implementation plan](implementation.md) owns the stages, API changes, +regression coverage, and completion criteria needed to reach this target. +Representative adoption should demonstrate fewer scripts, duplicated tests, +setup steps, and recurring release decisions. Feature expansion should follow demonstrated consumer needs and measurable reductions in application maintenance or developer effort. -## Open Questions +## Design Choices + +The implementation plan selects the recommended directions below for the +upcoming sprint. Alternatives record the tradeoffs for future consumer needs. +These choices describe the target behavior; current contracts change as their +implementation lands. ### 1. Should product checks supplement or replace standard validation? -**Recommended:** Run the shared offline Go suite once, followed by optional +**Selected direction:** Run the shared offline Go suite once, followed by optional product-specific checks. ReleaseKit owns the command and its routine environment settings. Migrate repeated suite invocations out of application scripts. Add alternative invocation settings when an actual consumer requirement establishes @@ -356,8 +350,8 @@ specific consumer need. ### 2. How should ReleaseKit choose build settings? -**Recommended:** Use the available compatible Go toolchain, ordinary baseline CPU -settings, and shared build flags. Handle incidental environment settings internally +**Selected direction:** Use the available compatible Go toolchain, ordinary +baseline CPU settings, and shared build flags. Handle incidental settings internally so developers can rely on the selected target's expected compatibility. Keep application configuration small. Toolchain-dependent byte differences are acceptable; digest checks preserve existing published content, and retained @@ -373,7 +367,7 @@ Explicit hardware variants can be added for a demonstrated product need. ### 3. Should the library own build-and-deliver, or accept only completed builds? -**Recommended:** Provide one facade operation for tagged-source verification, +**Selected direction:** Provide one facade operation for tagged-source verification, selected-target builds, temporary storage, checksums, uploads, and cleanup. Use it from the CLI so both interfaces share the procedure. Retain separate building for local development and support prebuilt delivery where a concrete @@ -389,11 +383,13 @@ operational separation they need. ### 4. How should the shared executable and CI integration be distributed? -**Recommended:** Choose the simplest maintained entry point for installation, -updates, and delivery. Begin with versioned source installation if it keeps -consumer integration small. Centralize reusable setup and provide one clear -upgrade procedure. Applications should select a ReleaseKit version and supply -product settings and credentials; shared integration should own routine setup. +**Selected direction:** Choose the simplest maintained entry point for installation, +updates, and delivery. Use versioned source installation and a shared CI delivery +command. The command prepares the tagged checkout, reads its product profile, +prepares dependencies for selected binaries, and invokes ordinary facade delivery. +Centralize reusable setup and provide one clear upgrade procedure. Applications +select a ReleaseKit version and supply product settings and credentials; shared +integration owns routine setup. Assess packaging by the consumer code and recurring developer work it removes. **Viable alternative:** Publish a maintained CI image containing ReleaseKit and @@ -405,7 +401,7 @@ applications a small configuration and a routine invocation. ### 5. How should delivery results support simple recovery? -**Recommended:** Use exclusive outcome categories: matching, uploaded, known +**Selected direction:** Use exclusive outcome categories: matching, uploaded, known pending, conflicting, and uncertain. Present ordinary callers with completion or a clear failure and recovery instruction. Keep asset details available for diagnostics. Derive recovery guidance centrally so each application can present diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md new file mode 100644 index 0000000..16cd980 --- /dev/null +++ b/docs/roadmap/implementation.md @@ -0,0 +1,481 @@ +# ReleaseKit audit implementation plan + +Status: planned; implementation has not started. +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. + +## How to execute this plan + +Implement one numbered stage per prompt, in order. Each stage includes its +production change, relevant tests, and current-contract documentation. Leave the +repository compiling and its checks passing at each stage boundary. Record +completed stages here with a concise validation result; report the commit +identifier in the stage completion response. Read +[development guidance](../development.md) and its applicable policies at the +start of each stage. + +Use the [agent policy](../policy/agents.md), [architecture +policy](../policy/architecture.md), [testing policy](../policy/testing.md), and +[documentation policy](../policy/documentation.md). Discover current symbols +through the codebase graph, then inspect their callers and tests before editing. +The paths below locate the baseline; internal names may evolve during the work. +Use ordinary functions and existing internal packages where their ownership +fits. Public named types remain facade-owned with explicit internal conversions. + +For each stage, run focused behavioral tests for its changed responsibilities. +Then run the existing repository checks from the root: + +```sh +GOTOOLCHAIN=local GOPROXY=off GOSUMDB=off go test -mod=readonly -count=1 ./... +GOTOOLCHAIN=local GOPROXY=off GOSUMDB=off go run ./internal/apicheck +``` + +Prepare dependencies before these offline checks when needed. Review changed +GoDoc, examples, local documentation links and fragments, and `git diff --check`. +Reuse successful checks for unchanged content. Commit each completed stage +under the agent policy. These implementation checks serve the development +workflow. + +## Decisions for this sprint + +These choices resolve the audit's design alternatives for implementation: + +- Candidate validation runs the standard offline Go suite once, then optional + product checks, then selected-target build verification. Rename the Go + callback to `AdditionalChecks`; JSON retains `checks` with additive semantics. +- ReleaseKit uses the available compatible Go toolchain, internal baseline CPU + settings, and shared build flags. It controls incidental flags and persistent + Go settings while preserving operational configuration such as caches. +- `Deliver` accepts a build declaration and owns temporary build output, + checksums, uploads, and cleanup. An explicit prebuilt path retains original + artifacts for retries and supports separated build/delivery environments. +- Delivery asset categories are disjoint observations: matching, uploaded, + known pending, conflicting, and uncertain. Existing overall delivery states + and content-preservation rules remain authoritative. +- A versioned source-installed command is the initial shared CI entry point. + Add `ci-deliver` for explicit CI checkout and dependency preparation followed + by the same facade delivery operation. Ordinary `deliver` remains suitable + for an already prepared checkout. CI images remain an operational option. +- Shared artifact rules and Go execution settings have small internal owners. + Application profiles continue to declare product facts and additional checks. + +The callback and delivery request changes are deliberate pre-release API +changes. Update all in-repository callers and their canonical documentation in +the corresponding stage. The initial release note should describe the final +interfaces and migration impact when that release is prepared. + +The sprint preserves the existing source transaction, successful-tag-push +completion point, bounded recovery, content-aware retries, standalone `Build`, +and lightweight `buildinfo`. Build observations and private receipts retain +their existing source-eligibility meaning. Toolchain-dependent byte differences +remain acceptable. Build identity remains an observation of the checked source +and produced files under the existing contracts. Live deployment and sibling +repository migrations remain separate adoption work in the +[product roadmap](releasekit.md). + +## Stage 1 — Keep ambiguous-push recovery on the captured endpoint + +**Covers:** F2. **Primary owners:** `internal/git/tag.go`, +`internal/git/remote.go`, `internal/publish/publish.go` and their tests. + +1. Before `Endpoint.QueryTag` performs its remote read, reuse + `verifyScopedURLs` with the captured endpoint and command-scoped configuration. + Verify that the captured URL still resolves to itself. Use the existing + reconciliation context and timeout for both verification and the remote read. +2. Treat verification failure as unreadable authoritative state. Preserve error + identity through wrapping so `reconcilePush` reports `unknown`, retains the + local tag, and preserves the original push failure for diagnosis. +3. Keep the captured endpoint as recovery's authority. The local resolution + check precedes the existing single remote tag query. Preserve exact tag-object + and peeled-commit comparison and successful push as the completion point. +4. Update relevant recovery GoDoc and internal guidance to explain the + automatic URL-resolution check. Keep the manual recovery runbook consistent. + +**Completion evidence:** Extend the existing local Git publication fixtures with +F2's lost-acknowledgment reproduction: actually publish the tag, install a URL +rewrite to an empty bare repository, then report a push error. Recovery must +return unknown and preserve the tag/error; direct inspection of the original +remote must find the intended object. Existing unchanged-endpoint success, +absence, conflict, and unreadable-recovery tests continue to pass. Test the +behavior through publication; avoid a second copy of the full recovery matrix. + +## Stage 2 — Own effective Go settings for validation and builds + +**Covers:** F1, F3, Go-environment portion of F8. **Primary owners:** +`internal/candidate/check.go`, `internal/build/build.go`, `internal/process/`, +and a small new `internal/gotool` package. + +1. Put effective Go-environment construction and common invocation behavior in + `internal/gotool`. Reuse the existing subprocess boundary for context, + working directory, output, and error handling. Support native validation and + static target builds as distinct modes of the same implementation. +2. Account for both the process environment and values from Go's persistent + environment file. Resolve effective Go configuration with the installed Go + command under local toolchain selection and a controlled `GOFLAGS`. Ensure + configuration discovery itself tolerates the ambient settings being replaced; + an experiment override used only for discovery must not become the build + default. Carry effective operational settings into child environments, then + use `GOENV=off` + there so removed settings cannot reappear from the persistent file. Retain + ordinary process variables and effective cache, module-cache, temporary, + tool-location, and native C-tool settings. Keep informational `go env` output + separate from configuration when constructing child environments. +3. Own `GOFLAGS`, `GOWORK`, `GOTOOLCHAIN`, module-network settings, target + selection, experiment selection, and architecture-feature settings. Standard + validation uses `go test -mod=readonly -count=1 ./...`, host OS/architecture, + `GOWORK=off`, `GOTOOLCHAIN=local`, `GOPROXY=off`, `GONOPROXY=none`, and + `GOSUMDB=off`. Resolve the Go host target independently of ambient cross-build + settings. Native tests retain native Go cgo behavior and explicit native + C-tool configuration; release builds retain `CGO_ENABLED=0`. +4. Clear ambient experiments and architecture tuning for the child so the + selected Go toolchain supplies ordinary baseline defaults. Handle the Go + feature variables for supported toolchains, including `GOAMD64`, `GOARM`, + `GOARM64`, `GO386`, `GOMIPS`, `GOMIPS64`, `GOPPC64`, `GORISCV64`, and `GOWASM`. + Clearing must take effect for persisted values as well. Retain the existing + release flags, linker injection, target selection, and native version smoke + check. Keep these settings internal; the profile needs no new tuning fields. +5. Route default validation, build toolchain/host queries, target compilation, + and native smoke-build compilation through the shared owner. Preserve useful + compiler diagnostics and cancellation. Custom product commands retain their + explicitly selected arguments and environment overlays. +6. Update the build and check consumer guides and relevant GoDoc with the + supported behavior: shared baseline settings and the available compatible + toolchain. Exact internal environment construction belongs in internal docs. + +**Completion evidence:** A genuinely failing fixture test still fails with +`GOFLAGS=-run=^$` supplied through either the process or a temporary Go env file. +An ambient cross-target setting still results in host-native validation. Extend +existing build fixtures to demonstrate that ambient/persisted `GOAMD64=v2` and +experiment settings do not alter the selected baseline build settings. Inspect +build metadata where useful; identical binary bytes are unnecessary evidence. +Use a temporary configured cache to demonstrate that persistent cache choices +survive. Preserve existing version injection, empty-target, cancellation, and +partial-build behavior. Fixtures use temporary Go configuration and never edit +the developer's persistent settings. + +## Stage 3 — Make product checks additive + +**Covers:** F4 and ReleaseKit's own F1 exposure. **Primary owners:** `check.go`, +`publish.go`, `internal/candidate/`, CLI profile mapping and fixtures. + +1. Rename `ReleaseRequest.Validate` to + `AdditionalChecks func(context.Context, Candidate) error` and update the + corresponding internal request and facade conversions. The callback keeps + the existing candidate-value ownership and error-wrapping behavior. +2. Make `candidate.Validate` always run the shared offline suite first. On + success, invoke `AdditionalChecks` once when supplied. Run selected-target + build verification after these checks through the existing orchestration. + A failure or cancellation ends the sequence and preserves its cause. +3. Retain `checks` in JSON as ordered additional commands. Map the CLI's + `RunChecks` callback to `AdditionalChecks`. Keep the existing argument-vector + and per-command environment semantics. +4. Remove repeated standard-suite commands from `releasekit.json` and example + profiles. Preserve additional checks that address actual product behavior. + Update in-repository callback callers and fixtures to provide small valid Go + modules with an effective default suite. A callback fixture must exercise + its intended callback behavior after that suite succeeds. +5. Update facade GoDoc, `docs/config.md`, `docs/cli.md`, check/publish consumer + guides, examples, and affected internal documentation. Explain migration: + rename the callback and remove standard-suite invocations from custom checks. + +**Completion evidence:** Through the public facade, prove that a failed standard +suite prevents the additional callback and publication, that an additional +failure prevents publication while preserving error identity, and that a +successful publication runs the standard suite and additional checks once for +its captured candidate. Reuse existing mutation/recheck tests with the new +callback. One CLI profile test covers ordered extra commands. Keep callback +unit coverage and end-to-end suite-count coverage at distinct boundaries. + +## Stage 4 — Consolidate artifact identity and declaration rules + +**Covers:** artifact portion of F8. **Primary owners:** `internal/build/`, +`internal/delivery/assets.go`, `cmd/releasekit/internal/cli/receipt.go`. + +1. Add a small internal artifact-contract owner for target normalization, + filename-component validation, artifact names, and the expected declaration + for a build. Choose `internal/artifact` for these shared pure rules. +2. Move the existing rules from builder, receipt, and delivery into that owner. + Preserve accepted inputs, target order/deduplication, filenames, manifest + naming, and validation meaning. Keep build execution in `internal/build`, + hosted-content checks in delivery/Gitea, and receipt JSON/path handling in + the CLI adapter. +3. Use ordinary conversions at facade and receipt boundaries. Preserve + facade-owned public types and the current private receipt format. Consolidate + repeated declaration comparisons while retaining boundary-specific checks + for repository, commit, version, file location, and actual file contents. +4. Update the internal package inventory. Keep exact public build/result + contracts in GoDoc and private receipt lifecycle in its existing owner. + +**Completion evidence:** Existing build-to-receipt-to-delivery tests retain +behavior for normalized targets, filenames, altered files, mismatched identity, +and manifests. Add only missing coverage for disagreement between these +boundaries. The API/dependency checker confirms that the shared internal owner +has not leaked through exported signatures or runtime dependencies. + +## Stage 5 — Make delivery outcomes disjoint and actionable + +**Covers:** F7. **Primary owners:** `internal/gitea/upload.go`, delivery result +GoDoc, CLI delivery reporting, and their tests. + +1. Define the five collections as current observations for each reported asset. + `Matching` means existing matching content; `Uploaded` means confirmed upload + during this invocation; `Pending` means known missing work; `Conflicting` + means a detected conflict; `Uncertain` means unresolved state. Each asset + appears in at most one collection in a returned result. +2. In every upload/reconciliation branch, remove an asset from `Pending` when + moving it to matching, uploaded, conflicting, or uncertain. In particular, + fix failed reconciliation reads, conflicts, and unresolved writes. Later + known-missing assets can remain pending when an earlier upload stops work. +3. Preserve the existing overall delivery states and their handling of remote + writes. Early failures can return incomplete asset information. Category + exclusivity establishes no claim that every declaration has been observed. +4. Keep concise state-based recovery guidance in one CLI formatter: correct + local/preflight failures before retrying; retry partial delivery after fixing + its cause; resolve uncertain remote state before retrying; investigate + conflicting content and use a new version when source or published contents + require correction. Mention retained original artifacts when a rebuild would + conflict. Go callers use the documented overall state and asset categories. +5. Update delivery GoDoc, `docs/cli.md`, the delivery consumer guide and Gitea + integration documentation. Keep diagnostics available alongside the summary. + +**Completion evidence:** Update the existing reconciliation-read-failure test +that currently expects overlap. Extend existing upload tests to cover conflict, +missing-after-ambiguous-upload, matching-after-lost-acknowledgment, and later +pending assets. Assert category exclusivity and meaningful overall state at the +upload boundary. CLI tests verify recovery meaning and exit classification +without freezing full diagnostic wording. + +## Stage 6 — Give the facade ownership of build-and-deliver + +**Covers:** F5. **Primary owners:** `delivery.go`, `internal/delivery/`, +`internal/build/`, and existing temporary-directory helpers. + +1. Change `DeliveryRequest.Build` to `*BuildSpec`. Add + `Prebuilt *BuildResult` and `Output io.Writer`. `Build` requests managed builds; + `Prebuilt` supplies an existing result. Supplying both is an invalid request + because the operation needs one artifact source. With neither, or with an + empty selected target set, ordinary delivery is page-only. Preserve the + existing handling of empty prebuilt results. +2. Implement the reusable orchestration inside `internal/delivery`; the public + facade performs conversions. Verify version, product, local tag/HEAD + agreement, checkout cleanliness, and the committed release note before + compilation. Preserve historical lightweight-tag and detached-HEAD support. +3. For nonempty `Build`, create temporary output outside the worktree using the + existing helper, invoke the shared builder, and feed its result into the + existing asset validation/delivery path. Defer cleanup for success, failure, + and cancellation. Return diagnostic progress through `Output`; managed + temporary paths have no caller-owned lifetime. +4. Before hosted writes, retain the tagged-source eligibility check and the + build-result, file-digest, and manifest checks. A checkout change during the + build must fail eligibility. Use the same captured tag commit to read the + note and validate the build. Reuse the existing builders and delivery client. +5. `Prebuilt` retains caller-owned files and existing source/identity/content + checks. Its build result declares its targets as today. The CLI continues + comparing receipts with the selected profile. This path supports original + bytes across retries; callers own retention and cleanup. +6. Keep pre-remote build/preflight failures `DeliveryNotAttempted`. Preserve + candidate identity when known, wrapped error causes, cancellation, and the + current mapping of hosted failures and partial progress. +7. Update all Go callers for the request shape. As an intermediate step, map + the CLI's current already-built result to `Prebuilt`; Stage 7 removes that + duplicate orchestration. Update delivery GoDoc and the consumer guide with + the normal `Build` path and the explicit `Prebuilt` lifecycle. + +**Completion evidence:** Add facade-level tests using a real small Go consumer +and a local HTTP server for managed binary delivery and page-only delivery. +Prove invalid tagged source fails before Go compilation or hosted writes, +build failure prevents hosted writes, and managed temporary output is cleaned +on success and failure. Extend existing mutation/cancellation coverage where +needed. Preserve prebuilt retry, digest conflict, note conflict, and source +eligibility coverage. Confirm the two facades' dependency boundaries. + +## Stage 7 — Route ordinary CLI delivery through the facade + +**Covers:** the CLI portion of F5. **Primary owners:** +`cmd/releasekit/main.go`, CLI receipt adapters, CLI tests and documentation. + +1. Change ordinary `runDelivery` to pass the configured `BuildSpec` and output + writer directly to `Deliver`. Remove its temporary-directory and standalone + build coordination. Keep profile parsing, credential lookup, presentation, + and exit-code selection in the CLI. +2. Retain `build --output` and `deliver --assets`. The latter loads and verifies + the private receipt, compares it with the selected profile, and supplies + `Prebuilt`. Keep stale-receipt invalidation and standalone build behavior. +3. Share the final CLI-to-facade delivery adapter so the CI entry point in Stage + 9 can use it after preparation. Keep ordinary `deliver` free of dependency + downloading and checkout mutation. +4. Update CLI/configuration guidance and examples to make one `deliver` + invocation the normal path. Describe split build/delivery for retained bytes + and credential separation. Preserve exit statuses 0, 1, 2, and 3. + +**Completion evidence:** CLI tests cover source-only and binary profiles, +preflight failure before compilation, token/profile errors, and the explicit +receipt path. Reuse Stage 6 for domain failure coverage. Confirm the maintained +ordinary command exercises the facade-owned lifecycle and reports F7's results. + +## Stage 8 — Add reusable CI preparation operations + +**Covers:** preparation ownership in F6. **Primary owners:** a new root +`preparation.go`, `internal/git/`, `internal/gotool/`, and a small internal +preparation coordinator. + +1. Add facade-owned `TaggedCheckoutRequest` with `RepositoryDir`, `Version`, + `Remote`, and `ExpectedCommit` strings, and + `PrepareTaggedCheckout(context.Context, TaggedCheckoutRequest) error`. + An empty remote selects `origin`. This is an explicit preparation operation + for disposable CI checkouts; ordinary delivery keeps its current behavior. +2. Validate the version and required expected commit before mutation. Fetch + the selected tag from the selected remote with an explicit tag refspec, + verify that its peeled commit equals the expected CI commit, detach checkout + at that commit, and verify HEAD agreement. Use the existing Git subprocess + boundary and preserve Git errors. Use ordinary checkout/fetch behavior; + conflicting local changes or tags are reported for the operator to resolve. +3. Add `PrepareBuildDependencies(context.Context, string) error`, taking the + repository directory. Internally run `go mod download` with the available + compatible local Go toolchain and workspace discovery disabled. Preparation + uses the caller's dependency-access settings, including proxy/private-module + configuration and caches. This operation is explicitly network-capable. + Keep offline test/build environments from Stage 2 distinct from preparation. +4. Keep both operations behind the root facade with internal implementations. + These two additions serve the concrete shared CI workflow and Go consumers + with the same preparation needs. Keep their API small: CI-provider variables, + JSON profile loading, credentials, and output formatting stay in adapters. +5. Add GoDoc and a short preparation section to the delivery consumer guide; + update the internal package inventory. State filesystem/network effects and + cancellation behavior. Preparation does not publish a tag or hosted content. + +**Completion evidence:** Local Git fixtures verify expected-commit agreement, +wrong-tag rejection before checkout, detached checkout, and ordinary local +conflict behavior. A subprocess-boundary test verifies dependency preparation +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. + +## Stage 9 — Add the shared CI delivery command + +**Covers:** the shared command portion of F6. +**Primary owners:** CLI parsing/routing, CLI command tests, `docs/cli.md`, +and `docs/config.md`. + +1. Add: + + ```text + releasekit ci-deliver [--repo DIR] [--config FILE] [--remote NAME] --commit OID VERSION + ``` + + Options precede the version, consistent with existing commands. Repository + and profile defaults match `deliver`; remote defaults to `origin`. The + explicit command authorizes preparation of the selected CI checkout. +2. Call `PrepareTaggedCheckout`, then load the profile from that checked-out + source, then validate the selected delivery configuration and credentials. + When the profile selects binaries, call `PrepareBuildDependencies`. Finish + through Stage 7's ordinary delivery adapter and `Deliver`. Page-only profiles + skip application dependency preparation and binary work. Read custom profile + paths under the existing CLI path rules. +3. Keep the provider adapter declarative: Woodpecker supplies `CI_WORKSPACE`, + `CI_COMMIT_SHA`, and `CI_COMMIT_TAG` as command arguments. The library and + ordinary CLI operations remain independent of Woodpecker environment names. + Preparation failures return 1; argument/profile/credential errors return 2; + final delivery uses the existing success/failure/unknown status mapping. +4. Update command usage, `docs/cli.md`, and configuration guidance for the new + entry point, its preparation effects, profile-loading order, and exit codes. + Keep ordinary `deliver` documented as operating on prepared source. + +**Completion evidence:** Exercise the command with local Git/HTTP fixtures for +source-only and binary delivery. Prove the profile is read after checkout, +a wrong CI commit fails before application builds or hosted writes, and a +source-only module with unavailable dependencies still reaches page delivery. +Reuse facade tests for the individual preparation and delivery operations. + +## Stage 10 — Consolidate and exercise maintained CI templates + +**Covers:** installation, workflow duplication, and artifact-testing in F6. +**Primary owners:** `examples/woodpecker/`, CLI workflow tests, installation +instructions, and the product roadmap. + +1. Select versioned source execution as the default bootstrap: + `go run gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit@PIN ci-deliver ...`. + `PIN` is an immutable ReleaseKit revision or published version. Applications + choose a compatible Go/Git image and provision the delivery token. The shared + command owns checkout checks, conditional dependency preparation, and delivery. + The normal Go caches suffice; optional CI cache mounts remain deployment + configuration. Document `go install ...@PIN` for a locally retained executable + and one upgrade procedure based on changing the selected version. +2. Consolidate source-only and binary Woodpecker templates into one maintained + `examples/woodpecker/tag-delivery.yml`, with the product profile selecting + page-only or binary behavior. Remove the two superseded templates and repair + their links. Retain the distinct first-release bootstrap in + `releasekit-source-delivery.yml`, since ReleaseKit's own first source release + must build its tool from the tagged source. Simplify it around the shared + command where this preserves that bootstrap. +3. Replace tests that reconstruct the workflow commands with checks tied to the + maintained artifact. Use a small extractor for the template's one command + block and execute it with controlled CI variables, local Git/HTTP fixtures, + and a Go bootstrap shim that maps the pinned remote tool invocation to the + CLI built from the test checkout. Validate the module/command/version + arguments in the shim. Apply the template's matrix substitutions and + Woodpecker dollar escaping before shell execution. Keep the template subset + simple enough for a small test helper; a general YAML runner is unnecessary. +4. Document bootstrap requirements, token provision, compatible Go selection, + optional caches, dependency preparation, and the version upgrade procedure. + Align `releasekit.md`'s remaining adoption work with source installation; + identify live deployment and the real immutable pin as remaining work. + +**Completion evidence:** Execute the actual maintained command block for both +source-only and binary fixture delivery. A repeated invocation preserves +matching remote content. The bootstrap shim proves template wiring, not +published-module availability. Record that distinction and retain real +installation/live Woodpecker verification as deployment work. + +## Stage 11 — Validate representative adoption and close the sprint + +**Covers:** audit-wide acceptance and adoption evidence. **Primary owners:** +existing external-consumer fixtures, consumer guidance, this plan, and the +remaining-work section of `releasekit.md`. + +1. Exercise a source-only consumer with one meaningful extra check and a binary + consumer using `buildinfo`, selected targets, and Gitea delivery. Reuse and + extend the fixtures from prior stages. Verify publication through local Git + remotes and delivery through local HTTP fixtures as separate operations. +2. Review available sibling projects named by the product roadmap read-only. + Use PromptKit and Narratio as the source-only and binary representatives. + Record a concise migration assessment: retained product settings/checks, + release code and repeated tests that can be deleted, runtime-version + adaptation, and required policy + or procedure changes. Label projected deletions as estimates. If a sibling + checkout is unavailable, use the audit evidence and label its verification + date. Keep implementation tests self-contained in ReleaseKit. +3. Assess the final user workflow against the audit: standard tests once, + additional checks declared once, one ordinary delivery invocation, one + versioned CI entry point, clear recovery, and shared artifact/build rules. + Address implementation gaps within their existing stage scope before closing + the sprint. Record any new product decision as such. +4. Reconcile GoDoc, CLI/configuration references, consumer guides, maintained + examples, internal inventory, and the product roadmap with implemented + behavior. Keep the audit's original evidence historical. Record completion + here and link to the remaining adoption/deployment work. +5. Run the standard offline suite and API checks on the final implementation. + Run them with the minimum supported Go 1.25 toolchain when available in the + implementation environment; otherwise record that verification limitation + explicitly. Minimum-version verification is evidence about the existing + module requirement, rather than a new permanent release matrix. +6. Leave source publication, real installation verification, credentials, + workflow activation, live service checks, and changes in sibling repositories + for their deployment/adoption tasks. Follow the maintainer release procedure + when a release is separately requested. Keep ReleaseKit's own deliverables + source-only under the current release policy. + +**Completion evidence:** A concise final record identifies the passing checks, +representative workflows, projected adoption savings, implemented API/profile +migration, and remaining deployment work. Every F1–F8 finding has an implemented +resolution and appropriately scoped evidence. Review and commit the final +changes with a clean worktree. + +## Open Questions + +No unresolved product choice is required to implement these stages. The +selected approaches and rationale are recorded in the audit's design choices. +Real deployment pins, credentials, service availability, and per-application +migration scheduling are inputs to subsequent deployment/adoption work. They +are separate from the implementation acceptance criteria above.