ReleaseKit/docs/roadmap/policy.md

Adopt the policy framework

Status: Policy adoption complete. Source publication, its maintainer runbook, and prepared hosted note-page delivery are implemented; no ReleaseKit release has been published. Binary distribution remains deferred.

Date: 2026-10-05

Purpose and scope

Standard Repository Policies are adopted into ReleaseKit as locally maintained rules for an opinionated Go library and its proposed release executable. The adoption preserves the project's existing licensing choice, supports deliberate standardization of release behavior, and keeps documentation accurate about what has been implemented.

This roadmap covers policy adoption, contributor navigation, documentation ownership, licensing notices, and the preparation of ReleaseKit's own release procedure. Product implementation and consumer migrations belong to the separate ReleaseKit proposal.

Upstream baseline and references

Use upstream commit d84a38ebab26f048cafbe59a2246700c35d29843. The local ../policy checkout and upstream main matched that revision during the review. PromptKit and ConfigKit adopted the same baseline.

Follow the adoption guide at the selected revision. Copy applicable policies locally and customize them. Retain each file's exact upstream provenance; later upstream changes become local rules through deliberate review and adoption. Git history is sufficient to record this process.

Useful library adaptations include ConfigKit's architecture policy, PromptKit's architecture policy, and their documentation, testing, and attribution policies. Use these as examples of adaptation rather than copying their product-specific requirements.

Policy adaptations

All seven policies are adopted under docs/policy/:

Policy	Base version	ReleaseKit adaptation
meta.md	1.0	Retain local authority, per-document adoption provenance, and upstream update navigation.
agents.md	1.3	Retain proportionate implementation and local commit practices. Add the libraries' clarification that implementation, tests, and agent-authored plans do not independently establish new contracts.
architecture.md	1.3	Define the library, proposed executable, consumer responsibilities, external effects, and dependency boundaries.
testing.md	1.3	Retain behavioral, deterministic, offline testing. Prioritize publication integrity, ambiguous outcomes, partial delivery, cross-builds, and version injection as those features are implemented.
documentation.md	1.11	Assign exact exported Go contracts to declarations and GoDoc, workflows to consumer guides, and proposals to roadmap documents. Add CLI and integration owners when those interfaces exist.
oss.md	1.8	Preserve the library licensing choice, apply the attribution format, and identify separately licensed copied policy material.
release.md	1.4	Govern releases of ReleaseKit itself, with explicit deliverables and justified checks. Distinguish its maintainer procedure from the release standard offered to consumers.

Adopted architectural constraints

The architecture policy owns the adopted boundaries, including ADR 0001 and the runtime version constraints. The following summarizes those rules for this adoption record.

Evaluate ReleaseKit against both of ConfigKit's relevant success criteria: applications should delete substantial infrastructure, and consumers should adopt one consistent set of deliberately selected conventions.

• ReleaseKit owns the selected publication, version injection, build, and delivery conventions. Consumers supply product identity, main package, selected targets, and application-specific checks.
• Consumers use the root releasekit orchestration facade and the lightweight buildinfo runtime facade. Both packages own their public contracts and delegate through private state and explicit conversions to internal implementation. ReleaseKit builds and tests independently of the consuming repositories and does not depend on their private packages.
• Git, filesystem, Go toolchain, and Gitea effects have proportionate boundaries and occur through explicit operations. Package layout and abstractions should serve those boundaries without requiring an application framework.
• The library returns meaningful errors and publication outcomes. The executable handles command parsing, output, and exit codes.
• The buildinfo facade provides runtime version access through a lightweight dependency graph. ReleaseKit's builder and runtime implementation own version injection together.

Architecture policy may govern future development. Concrete package inventory, API semantics, and implemented behavior must be documented when they exist.

Adoption stages

1. Copy and tailor policies

• Copy the seven policies from the selected baseline.
• Preserve each Base Policy Version, set Last Updated to the actual adoption date, and add an Upstream Source link to that file at the full commit.
• Customize the policies for ReleaseKit and remove their Base Policy Template sections.
• Adapt upstream agents/AGENTS.md into root AGENTS.md, preserving the existing knowledge-graph discovery instructions.
• Create docs/development.md with contributor orientation and the selective policy reading guide. Route tasks to applicable policies instead of requiring the entire suite for every task.

2. Establish documentation ownership

• Move the substantive contents of ideas.md to docs/roadmap/releasekit.md, preserving the proposal, and retain ideas.md as a navigation pointer. Update this roadmap's proposal link in the same change.
• Update README with accurate current status and navigation.
• Define ownership for GoDoc, consumer guidance, architecture constraints, internal implementation, release procedures, ADRs, and unfinished work.
• Reserve consumer, CLI, configuration, integration, and internal ownership in the documentation policy. Their documents await corresponding implementation; no empty owners or speculative command references were created.

3. Complete notices and attribution

• Add root COPYRIGHT using the upstream library example and verified project details. The grant is LGPL-3.0-or-later, consistent with the existing library licensing choice and the two library examples.
• Restore the complete, verbatim LGPLv3 and incorporated GPLv3 texts in LICENSE; the original contained reformatted text and a customized appendix. Keep project-specific grant statements in COPYRIGHT.
• Add docs/oss/attribution.md with the supplied policy attribution entry, describing the actual adapted policies, agent orientation, and reading guide.
• Copy the CC-BY-SA 4.0 text to docs/oss/licenses/CC-BY-SA-4.0.txt and identify the copied material's separate licensing scope in COPYRIGHT.
• Add README links to the project grant and attribution document. Keep source and notice links pinned to the adopted commit and reference examples upstream.

The library's selected license remains the project grant. A future executable does not automatically acquire a different license merely because the upstream policy has separate defaults for applications and libraries.

4. Define ReleaseKit's own release path

• Adopt the general versioning, compatibility, integrity, immutability, and successful-tag-push completion rules.
• Select the immutable source tag as the source-completion point and the hosted note page as a separate asynchronous deliverable. Supporting downstream cross-builds does not declare ReleaseKit binaries.
• Add docs/release.md alongside the first working publication command, documenting real prerequisites, authoritative remote, branch, validation, publication, and failure recovery.
• Account for first-release bootstrap: the initial publication command must run from the captured candidate source with dependencies prepared separately. The first release uses that source execution path before a released ReleaseKit tool exists. The maintainer procedure documents the command and the temporary repository integration test exercises the same CLI workflow.
• Add executable delivery declarations and target checks when corresponding deliverables exist. Keep source completion and asynchronous delivery status separate. This task is deferred unless executable deliverables are selected.

The publication command, its automated guards, offline candidate validation, executable maintainer runbook, and prepared hosted-page workflow are implemented. This adoption does not claim that a ReleaseKit version has been published.

Validation and completion

Review provenance, attribution scope, faithful license texts, template residue, local links, whitespace, and consistency with implemented repository behavior. Documentation-only adoption should use those checks; executable commands and examples added later require appropriate execution checks.

Adoption is complete when the tailored policy set, contributor navigation, documentation ownership, and licensing notices are coherent and verified. The source-publication command and hosted-page delivery are implemented; actual publication and binary distribution remain outside policy adoption.

Do not inherit PromptKit's or ConfigKit's extra release gates automatically. Select additional checks only for identified ReleaseKit risks, recording their justification in the adopted policy. Upstream synchronization, recurring license approval, and CI polling are not additional adoption or release gates.

Adoption result

The seven policies, root agent orientation, developer reading guide, documentation ownership, project grant, attribution, license texts, source publication command, maintainer runbook, and prepared hosted-page delivery are in place. The product proposal lives at docs/roadmap/releasekit.md; ideas.md remains a navigation pointer. Binary distribution is deferred, and no ReleaseKit release has been published.

Verification covers local file and fragment links, per-policy source revision and base version, removed template adoption sections, attribution scope and pinned notice destinations, verbatim license bytes, and prose whitespace. The preserved ADR decision and relocated proposal are checked against their pre-adoption source. ReleaseKit's source publication command, runbook, and hosted-page deliverable are implemented; binary delivery declarations remain deferred under stage 4.