From af1a76a2f793cc27a4ef350eb2e57b37451dc886 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 6 Oct 2026 14:13:41 +0000 Subject: [PATCH] Refresh architecture policy for the implemented library --- docs/policy/architecture.md | 52 ++++++++++++++++++------------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 66160cd..fba589e 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -2,31 +2,29 @@ **Base Policy Version:** 1.3 -**Last Updated**: 2026-10-05 +**Last Updated**: 2026-10-06 **Upstream Source:** [architecture.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md) ## Purpose And Ownership -ReleaseKit is being designed as an opinionated Go library and release executable -for common publication, builds, version injection, and delivery. This policy owns +ReleaseKit is an opinionated Go library and release executable for common +publication, builds, version injection, and delivery. This policy owns responsibility boundaries, dependency direction, and adopted constraints for development. The [product roadmap](../roadmap/releasekit.md) owns proposed capabilities, implementation status, and sequencing. -Describe concrete package inventory and implementation mechanics in internal -documentation when those packages exist. Link to canonical public contracts -for exact behavior and to ADRs for decision rationale. +The [internal documentation](../internal/overview.md) owns concrete package +inventory and implementation mechanics. Canonical public contracts own exact +behavior; ADRs record decision rationale. ## Adopted Constraints And Implemented Structure -Architectural constraints govern current and future development. Record -implemented structure accurately, proposals and implementation status in the -roadmap, and significant decisions and rationale in ADRs. Describe a target -structure as implemented when its changes land. - -Constraints must reflect deliberately selected requirements and decisions. -Do not promote incidental implementation choices into architectural invariants. +Architectural constraints govern current and future development and reflect +deliberately selected requirements and decisions. Current architecture describes +implemented structure. Roadmaps record proposals, implementation status, and +sequencing; ADRs record significant decisions and rationale. Internal +implementation choices evolve within these constraints. ## Success Criteria @@ -55,9 +53,9 @@ errors and outcomes, including partial progress and uncertain publication state. Consumers map those values to their own user interfaces. ReleaseKit builds and tests independently of consuming repositories. Production -dependencies use supported public contracts; consumer-private packages and local -checkout paths remain outside its dependency graph. Temporary local development -configuration stays outside committed module and workspace state. +dependencies use supported public contracts available independently of consumer +checkouts. Committed module and workspace configuration supports independent +builds; temporary local development configuration remains local. ## Public Facades And Dependency Direction @@ -81,11 +79,11 @@ durable consumer need. Go declarations and GoDoc own exact API contracts. Compiled-export checks, dependency checks, and external-package behavioral tests protect the selected -facade boundaries as implementation lands. +facade boundaries. ## Runtime Version Boundary -The `buildinfo` public API exposes only runtime information justified by +The `buildinfo` public API exposes runtime information justified by consumer needs. Its implementation uses the standard library and a small internal dependency graph independent of release orchestration. Applications read their embedded version through its supported accessor. @@ -104,18 +102,20 @@ The library owns reusable outcomes and failure handling; the executable owns presentation and process exits. Source publication and asynchronous delivery have distinct outcomes. The -[release policy](release.md) governs releases of ReleaseKit itself. Consumer -release capabilities and their implementation remain in the product roadmap -until supported contracts exist. +[release policy](release.md) governs releases of ReleaseKit itself. Go +declarations and GoDoc define supported consumer API contracts; +[consumer guides](../consumers/) explain their use, and +[integration guides](../integrations/) define external formats and protocols. +The product roadmap records planned capabilities and implementation status. ## Trust Boundaries And Threat Scope Base defenses and guarantees on selected requirements. Candidate validation, -remote-state changes, transport failures, and partial delivery require explicit -handling when those operations are implemented. Additional threat scenarios -require a deliberate scope decision under the [agent policy](agents.md). +remote-state changes, transport failures, and partial delivery receive explicit +handling. Additional threat scenarios require a deliberate scope decision under +the [agent policy](agents.md). -Credential supply and runtime handling belong in the applicable public or -integration contracts when implemented. Internal documents own the mechanisms. +Public API, [configuration](../config.md), and integration contracts own +credential supply and observable handling. Internal documents own the mechanisms. Tests use local collaborators and controlled failures as specified by the [testing policy](testing.md).