From ac90b9835b2fec10d6890a2a39fb4f139093afc2 Mon Sep 17 00:00:00 2001
From: Eric Rakestraw <eric@rakestraw.us>
Date: Thu, 8 Oct 2026 17:01:58 +0000
Subject: [PATCH] Record ReleaseKit adoption review findings

---
 docs/roadmap/remediation.md | 70 +++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 docs/roadmap/remediation.md

diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md
new file mode 100644
index 0000000..d5bfc6f
--- /dev/null
+++ b/docs/roadmap/remediation.md
@@ -0,0 +1,70 @@
+# ReleaseKit adoption review findings
+
+Reviewed commits `1917dcf` through `f887fac` against the
+[adoption roadmap](releasekit.md) and [implementation plan](implementation.md).
+The selected module, profile, validation sequence, and tag-only publication
+match the intended architecture. Address the following documentation findings.
+
+## 1. Preserve the captured endpoint during manual recovery (P2)
+
+Affected: [release procedure](../release.md#5-recover-from-a-failed-or-uncertain-tag-push),
+lines 180–199.
+
+The manual recovery command queries a literal URL without checking whether Git
+rewrites it. ReleaseKit v0.2.0's own recovery procedure verifies that the captured
+endpoint still resolves to itself before querying it. Without that check, the
+documented query can inspect a different repository and falsely establish that
+the published tag is absent. The runbook then permits deletion of the retained
+local tag and a retry based on that incorrect conclusion.
+
+Review reproduced this with two temporary bare repositories: the actual endpoint
+contained the published annotated tag; an `insteadOf` rewrite sent the runbook's
+query to a repository with the same `main` commit but no tag. The query succeeded
+and reported only `main`.
+
+Use the endpoint captured in the publication report and follow ReleaseKit's
+existing URL-resolution check before querying its refs, for example:
+
+```sh
+authoritative='COPY_CAPTURED_ENDPOINT'
+release_version='vMAJOR.MINOR.PATCH'
+test "$(git ls-remote --get-url -- "$authoritative")" = "$authoritative" &&
+  git ls-remote --refs -- "$authoritative" refs/heads/main "refs/tags/$release_version"
+```
+
+A failed equality check or query leaves the result unresolved. Retain the
+existing bounded recovery and confirmed-absence requirements. Verify this
+correction with a temporary URL-rewrite fixture; it adds no recurring release
+gate or ConfigKit-owned recovery implementation.
+
+## 2. Remove the unsupported prohibition on `go tool` (P3)
+
+Affected: [release procedure](../release.md#1-select-go-and-prepare-the-tool),
+lines 84–86.
+
+The runbook prohibits both `go run` and `go tool` on an exit-status rationale.
+That rationale applies to `go run`, but the review's Go 1.26.8 invocation
+`GOTOOLCHAIN=local GOPROXY=off go tool releasekit publish invalid` returned
+ReleaseKit's status 2 and its publication diagnostics unchanged. The blanket
+`go tool` prohibition unnecessarily extends the selected native-executable
+workflow into an unsupported restriction.
+
+Keep the documented temporary executable build and publication commands.
+Remove `go tool` from the prohibition and explain the exit-status limitation
+specifically for `go run`. No additional execution mode or test matrix is needed.
+
+## 3. Reconcile completed implementation status (P3)
+
+Affected: the adoption roadmap's opening status and final migration-verification
+bullet, and the implementation plan's opening status.
+
+All seven stage headings are marked complete, but the plan still says
+"Status: Planned" and the roadmap says isolated fixture verification remains
+unfinished. The final two commits identify that verification as completed;
+this review also reproduced validation failure without a tag, successful
+annotated-tag publication with each selected gate once, and wrong-endpoint
+rejection before any Go validation or tag creation.
+
+Mark the documents complete and describe the verification as completed.
+Keep retirement during release preparation under the existing release policy.
+Do not add a permanent migration-verification gate.