Document policy alignment and release workflow roadmaps

docs/roadmap/policy.md

@@ -0,0 +1,108 @@
+# Standard Policy Documentation Alignment
+
+Status: accepted target; implementation planning remains separate.
+
+## Intent and baseline
+
+Align ConfigKit's adopted documentation with Standard Repository Policies while
+preserving substantive local decisions. Prefer upstream wording verbatim wherever
+differences are editorial; do not maintain a parallel local paraphrase of shared
+rules. Customization must serve a locally significant requirement.
+
+Local baseline: `0adb94f59e44827908eff401d4381a398fe17107` (v0.4.1).
+The selected upstream revision is
+`d84a38ebab26f048cafbe59a2246700c35d29843`. Its
+[adoption guide](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md)
+owns the standard adoption procedure. This roadmap covers the adopted policy set,
+not just `docs/policy/documentation.md`.
+
+ConfigKit currently has six policies, no `meta.md`, and no per-document
+`Upstream Source` links. Its contributor guide routes tasks to documents but lacks
+the upstream selective-reading guidance. Licensing documentation covers the
+project and YAML dependency but not copied policy material. The release policy
+has intentionally retained its established workflow.
+
+Introduce accurate provenance going forward. Do not reconstruct old adoption
+baselines or add historical-uncertainty narratives.
+
+## Target policy set
+
+Remove upstream template instructions after adoption. Retain shared substantive
+wording unchanged except for necessary local adaptation and working references.
+
+| Document | Target |
+| --- | --- |
+| `docs/policy/meta.md` | Adopt upstream v1.0: local authority, upstream origin, discovery links, and policy provenance. |
+| `docs/policy/agents.md` | Adopt v1.3 wording, retaining local explanations of correctness constraints, protection of established contracts, and the rule that repeated agent-authored assertions are not evidence of approval. No change to standing commit authority. |
+| `docs/policy/architecture.md` | Use v1.3 as the customized template while preserving the opinionated library model, root-owned facade, dependency direction, existing invariants, and explicit avoidance of an imposed hexagonal framework. No code restructuring or new threat guarantees. |
+| `docs/policy/testing.md` | Adopt v1.3 shared wording. Retain ConfigKit-specific priorities and test ownership. Tests protect selected contracts; examples must not imply new rejection rules or mandatory inventories of techniques. |
+| `docs/policy/documentation.md` | Adopt v1.11 wording with a library-specific ownership table, including policy provenance. Omit inapplicable interfaces and empty placeholder documents. |
+| `docs/policy/oss.md` | Adopt v1.8 wording with necessary ConfigKit applicability and reference adjustments. Preserve the selected project grant and house interpretation of upstream notice links. |
+| `docs/policy/release.md` | Adopt compatible wording and accurate source metadata, preserving current operational requirements as explicit local adaptations until the separate release-workflow task lands. Do not describe the future publication command as implemented. |
+
+Each adopted document identifies its actual upstream template version, local
+update date, and full commit-specific `Upstream Source` URL. A deliberate adoption
+from the selected revision establishes the new baseline even where substantial
+project-specific content remains. Metadata must not imply adoption of upstream
+requirements deliberately replaced by local rules.
+
+## Orientation and upstream navigation
+
+Adapt upstream `agents/AGENTS.md` into the root orientation file. Keep the required
+agent-policy reading rule and route other reading through `docs/development.md`.
+The developer guide owns task triggers for all seven policies, including policy
+reviews through `meta.md`. Readers select applicable policies, reuse unchanged
+material already in context, follow relevant cross-references, and expand reading
+when scope changes. Reading the entire suite is not the default.
+
+Use live upstream project and adoption-guide URLs for discovery. Pin adopted-source
+and licensing-example URLs to full commits. Keep the upstream README, root agent
+instructions, contributor guide, adoption guide, and example collection upstream;
+do not copy them into ConfigKit. Root orientation derives from the upstream
+`agents/AGENTS.md` template, not its root AGENTS.md.
+
+## Attribution and licensing target
+
+Use the upstream canonical Standard Repository Policies entry in
+`docs/oss/attribution.md`, identifying the actual adapted material and linking its
+source, COPYRIGHT, and LICENSE at the selected commit. Include adapted orientation
+material where applicable. Preserve notices and modification identification
+without adding research or compliance narratives.
+
+Copy the applicable CC-BY-SA-4.0 text verbatim into `docs/oss/licenses/` and identify
+the separately licensed policy-document scope in root COPYRIGHT. ConfigKit code
+retains LGPL-3.0-or-later; root LICENSE retains the project license texts. Original
+upstream example formatting is CC0 and does not itself require an attribution
+entry or copying the example collection.
+
+Normalize the existing YAML entry to the current House Format: the prescribed
+document title, factual component identification, actual notice filenames,
+punctuation, and Source link. Remove editorial explanations while retaining
+upstream notices, copyright statements, license expression, and exact source
+revision. Keep MIT and Apache texts unchanged. Do not restore the author-owned
+adaptation section that the maintainer expressly removed.
+
+## Change surface and boundaries
+
+Affected files are the policy documents, root `AGENTS.md`, `docs/development.md`,
+COPYRIGHT, `docs/oss/attribution.md`, and the new CC license text. Repair affected
+local links and any misleading licensing summaries. Shared rules belong in their
+owning policies, not duplicated in the orientation guide or attribution entries.
+
+The [release-workflow roadmap](release.md) owns publication automation and gate
+selection. This work may align wording and references but does not alter release
+scripts, existing gates, supported platforms, publication completion, or library
+behavior. Coordinate edits to the release policy rather than maintaining two
+competing definitions. Published tags and historical release notes remain intact.
+
+## Completion criteria
+
+The policy set uses upstream language except for justified local substance,
+contains accurate forward-looking adoption metadata, and has working orientation
+and attribution links. Existing local contracts and explicit maintainer decisions
+remain intact. Documentation-link and whitespace checks, license-text comparisons,
+and ordinary content review provide proportionate validation. No synchronization
+service, scanner, legal sign-off, or new release gate is introduced.
+
+Detailed stages and executable implementation instructions belong in a later
+implementation plan. This roadmap authorizes neither publication nor a release.

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.