Document policy alignment and release workflow roadmaps

docs/roadmap/release.md

@@ -0,0 +1,143 @@
+# Single-Command Release Workflow and Gate Review
+
+Status: accepted target; detailed design and implementation planning remain separate.
+
+## Intent and baseline
+
+Make source releases simple for humans and agents: one publication command
+validates the final committed candidate, checks publication state, and publishes
+only the intended refs. Keep the minimum gates justified by ConfigKit's actual
+risks, with no routine human intervention or waiting for CI.
+
+Local baseline: `0adb94f59e44827908eff401d4381a398fe17107` (v0.4.1).
+The upstream reference is release policy v1.4 at
+`d84a38ebab26f048cafbe59a2246700c35d29843`:
+[standard release policy](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md).
+
+Today, `scripts/release-check.sh` performs local validation; the runbook separately
+records a candidate commit and executes shell blocks for guards, branch push,
+annotated tagging, and tag push. The checker runs module hygiene, formatting and
+whitespace checks, one race-enabled suite, vet, and Linux amd64/arm64 cross-builds
+using a maintained Go 1.25 patch. Publication completes on successful tag push.
+
+These remain the current requirements until deliberately revised. This roadmap
+does not itself waive existing gates.
+
+## Target release contract
+
+ConfigKit remains a source-only Go module hosted at its authoritative Gitea
+remote. Releases identify a final committed source revision on `main`, one fresh
+immutable annotated version tag, and a matching checked-in release note.
+No binary distribution, hosted release object, or registry publication is added.
+
+The publication command owns validation, candidate identity, guards, and explicit
+ref publication. Preparation still supplies the version, committed release note,
+and dependencies/toolchain; the command must not silently edit or commit source,
+choose a version, or upgrade dependencies. Publication remains subject to user
+authorization, not the standing local-commit policy.
+
+The command validates the exact candidate once. An optional validation-only mode
+may support diagnosis but is not a prerequisite followed by duplicate validation.
+Do not require both everyday and release checkers. An implementation need not
+introduce a persistent validation cache merely to replace today's manual record.
+
+Mechanical guards ensure a clean worktree/index on the primary branch, an unused
+valid version locally and on the authoritative remote, a matching release note,
+and exact agreement between validated source and tagged source. Publish only
+intended refs without discarding remote history. Ignored local files are not
+release content and do not alone prevent publication.
+
+A successful intended tag push, with the source commit available on authoritative
+main, completes the release. Never wait for or poll CI, module availability,
+consumer installation, or optional verification. Do not add a successful-push
+remote read-back gate. If future artifact channels are adopted, delivery status
+must remain separate; this task introduces none.
+
+## Gate review target
+
+Keep the full deterministic offline suite as the core check. Evaluate every
+additional current gate for distinct protection, cost, and overlap; do not retain
+or remove it solely because it appears in a template. Record the selected rationale
+in the adopted release policy, with commands in the runbook and implementation.
+
+| Current check | Review question |
+| --- | --- |
+| Race detector | Does its coverage of ownership and concurrent loads justify retaining it as the single full-suite mode? Avoid a second ordinary suite. |
+| Vet | What additional static defects does it catch beyond the test invocation, and is that protection worth a separate gate? |
+| Module hygiene | Is reproducibility protection distinct from ordinary dependency-change review and offline tests? |
+| Formatting and whitespace | Which checks belong in ordinary development rather than blocking publication? Avoid repeated scans without distinct value. |
+| Linux amd64/arm64 builds | Preserve existing supported targets unless deliberately changed; remove only demonstrably redundant work, not support commitments by implication. |
+| Toolchain selection | Preserve minimum-line validation without adding a second-toolchain gate or per-release latest-version research. |
+
+Examples, consumer fixtures, documentation links, and import/public boundary tests
+are already in the suite; they must not become separately repeated release checks.
+macOS remains best-effort. No human sign-off, new linter, hardware requirement,
+scanner, credentials-dependent test, or remote application probe is introduced.
+
+## Documentation and recovery
+
+Align `docs/policy/release.md` with upstream shared wording, preserving explicit
+ConfigKit decisions and the selected gate rationale. The successful-tag-push rule
+is a normal supported choice under the new upstream policy, not an exception
+requiring newly invented compensating controls.
+
+Make `docs/release.md` a short executable runbook for preparation and the single
+command. New notes use a proportionate summary and applicable compatibility and
+upgrade information rather than mandatory empty sections. Preserve the licensing
+footer and version-specific immutable links. Derive annotated-tag summary content
+from the checked-in note. Keep historical notes unchanged.
+
+Validation or guard failure stops publication with actionable diagnostics and no
+force updates. A failed or ambiguous push requires resolving authoritative remote
+state before retrying or reporting success. A transient failure does not itself
+require a new version. Published tags remain immutable; removing an unpublished
+local tag requires confirmation it was never published. Explain partial progress
+such as a successful branch push followed by a failed tag push.
+
+## Changes needed and scope
+
+The work affects `docs/policy/release.md`, `docs/release.md`, release shell tooling,
+`release_check_test.go`, and relevant contributor guidance. Reuse existing
+validation mechanisms where appropriate; avoid a general release framework.
+Tests should exercise success and meaningful failure/recovery paths in disposable
+local repositories, without real publication or credentials. Match coverage to
+the chosen push strategy and protect against unintended refs or stale candidates.
+
+Coordinate provenance and licensing with the [policy roadmap](policy.md).
+Operational documentation changes land with the implementation they describe.
+No library behavior, dependency update, release tag, or push is authorized by
+implementing this roadmap alone.
+
+## Open Decisions
+
+### Final gate set
+
+Recommendation: use the current single race suite and Linux support matrix as the
+starting point, retaining additional checks only with specific nonredundant
+justification. Assess the remaining checks during implementation planning before
+changing the binding policy. This protects selected behavior without treating
+the existing checker as an untouchable inventory.
+
+Alternative: retain the entire existing checker and automate only publication.
+This minimizes behavioral change and is a viable initial scope, but it does not
+complete the requested gate review unless each retained check is justified.
+
+### Publication strategy
+
+Recommendation: retain explicit main-then-tag pushes inside the command. This
+matches the proven local workflow and avoids a new dependency on atomic-push
+support; recovery must describe a partially published sequence.
+
+Alternative: atomically push main and the tag after validating remote ancestry.
+This avoids a branch-only intermediate result but requires confirming server
+support and adapting failure tests. Select one strategy in the implementation
+plan rather than silently switching between them.
+
+## Completion criteria
+
+One documented command publishes a prepared candidate with the reviewed minimum
+gate set, no duplicate suite runs, and automated exact-source safeguards. Local
+regression tests demonstrate successful publication and safe failure handling.
+The policy, runbook, and scripts agree, and successful tag publication is reported
+without waiting for external completion evidence. Detailed stages belong in the
+later implementation plan, not this target-state roadmap.