releasekit/docs/roadmap/remediation.md

Audit remediation roadmap

Status and scope

Agreed remediation target as of 2026-11-01. Implementation is pending against baseline 59bb074.

This roadmap defines the desired behavior and scope for all three findings in the functional correctness audit and all five findings in the interface audit. Those documents retain their reproduction circumstances and evidence. The implementation plan owns staging, code changes, regression checks, and completion tracking.

Purpose and architectural scope

ReleaseKit owns routine release mechanics so consumers supply product facts and product-specific checks with little release-related code. As recorded in ADR 0002, internal complexity is justified when it reduces caller-owned release work. In particular, callers can reuse a repository location across preparation and subsequent orchestration without normalization code or another configuration option.

The existing public orchestration and runtime facades and internal package boundaries remain appropriate. These corrections use the existing public types, receipt schema, module/tag conventions, and publication/delivery model.

Desired behavior

Incomplete publication observations

After a failed push acknowledgment, a query containing only a peeled tag record provides insufficient evidence about the exact annotated tag object. Publication remains unknown and retains the original push cause. A complete response works in either record order. Existing exact-object matches, genuinely absent tags, different objects, and exact-object-only responses retain their current outcomes.

Dependency preparation and ambient module files

Preparation uses ordinary Go module discovery from its selected directory even when inherited or persistent GOFLAGS selects an alternate module file. It retains other effective flags and existing proxy, private-module, authentication, checksum, cache, workspace, and local-toolchain behavior. Go retains its existing checksum-update behavior, including upward declaration discovery for standalone package-directory preparation.

Valid candidate tags

Candidate checking establishes that the complete derived release tag is a valid Git ref before accepting it as unused. Git's own ref rules remain the authority. The correction concerns release candidate validity; standalone local builds retain their existing filesystem choices and version rules.

Identifiable build cancellation

Cancellation or deadline expiration during build source inspection remains identifiable through the error chain. Ordinary Git failures retain useful diagnostics, and partial results retain already completed artifacts.

Gitea release identity at asset use

A backend-produced handle with a missing or nonpositive service release ID is a malformed observation when an asset operation needs that ID. A handle of the wrong type remains an invalid request. Locally rejected uploads retain not-attempted write evidence.

Existing page-only reads retain their current minimal response requirements. This correction adds no universal positive-ID or page-URL requirement to a successful release lookup and preserves existing delivery progress semantics.

Consistent preparation paths

Within a Git checkout, preparation resolves its containing root automatically and interprets ModuleDir relative to that root. Empty selection means the root module, consistently with Check, Build, and Deliver. This includes calls made from checkout subdirectories and filesystem aliases.

Outside a Git checkout, preparation retains the supplied directory as its base and the existing relative module selection. Standalone use remains supported. It retains its existing Go-only use when Git is unavailable and the directory can be identified as outside a checkout. Discovery distinguishes this case from cancellation, permission failures, and other Git errors, which remain failures. Existing symlink and containment rules and the CLI's root normalization continue to apply.

Empty prebuilt results

Page-only callers ordinarily omit both Build and Prebuilt. A supplied prebuilt result with no targets or artifacts still identifies the matching repository, module, tag, commit, and version. Documentation states that requirement clearly. A zero BuildResult gains no new compatibility behavior.

Artifact-verification order

Documentation consistently describes cheap local/source checks, read-only credential preflight, full local artifact verification, and then hosted writes. Digest verification completes before hosted writes. Credential preflight can precede that verification and confirms only the access evidence exposed by the backend.

Scope boundaries

The corrections retain the current source-verification observations, bounded publication recovery, explicit forge selection, and additive hosted delivery policy. They introduce no new public configuration knobs, compatibility shims, release procedure, pilot release, or intermediate human-review requirement. The targeted sprint reaches this complete end state through local repository work and automated validation.