From d4feccc4568a1e399e7dd28177c0ed36d835462f Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 28 Sep 2026 01:35:01 +0000 Subject: [PATCH] Align architecture and source release policies --- docs/oss/attribution.md | 7 ++-- docs/policy/architecture.md | 67 +++++++++++++++++++++++++++------- docs/policy/release.md | 36 +++++++++--------- docs/release.md | 9 +++++ docs/roadmap/implementation.md | 2 + 5 files changed, 86 insertions(+), 35 deletions(-) diff --git a/docs/oss/attribution.md b/docs/oss/attribution.md index 47b0e537..3cf9722e 100644 --- a/docs/oss/attribution.md +++ b/docs/oss/attribution.md @@ -2,10 +2,9 @@ ## Standard Repository Policies -Material: `docs/policy/meta.md`, `docs/policy/oss.md`, -`docs/policy/agents.md`, `docs/policy/testing.md`, and -`docs/policy/documentation.md`, adapted for this repository. Root `AGENTS.md` -and the Policy Reading Guide in `docs/development.md`, copied without modification. +Material: policy documents under `docs/policy/`, adapted for this repository. +Root `AGENTS.md` and the Policy Reading Guide in `docs/development.md`, copied +without modification. Copyright (C) 2026 Eric Rakestraw diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index bc102273..994ddbdf 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -1,22 +1,46 @@ -# Architecture +# Architecture Policy -**Base Policy Version:** 1.1 +**Base Policy Version:** 1.3 -**Last Updated**: 2026-09-26 +**Last Updated**: 2026-09-28 -Notarius adapts the base template to its fixed pipeline, artifact families, -external adapters, state boundaries, and source-only distribution. +**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md -This document defines the intended high-level architecture of Notarius and the -invariants that changes must preserve. Implemented component details belong in -[Internal Overview](../internal/overview.md) and its linked documents. The -reasoning behind significant architectural choices belongs in -[ADRs](../adr/). +## Purpose And Ownership -An adopted constraint can govern future changes without implying that every -component it could govern exists. Descriptions of implemented structure must -remain accurate; proposals and transition status belong in roadmaps and ADRs. -Constraints reflect selected requirements, not incidental implementation choices. +The adopted policy defines the application's purpose and the architectural +constraints contributors must follow. It owns system boundaries, responsibility +and dependency rules, established invariants, and explicit non-goals. + +Describe the concrete package inventory and implementation mechanics in internal +documentation. Link to canonical public contracts for their exact behavior and +to ADRs for decision rationale. + +## Architectural Approach + +Hexagonal architecture is strongly recommended, including encapsulating external +integrations and APIs within internal adapters. Keep domain and application +logic independent of external integration details, and make dependency direction +clear in the adopted policy. + +Implement that separation with proportionate, idiomatic code. Choose interfaces +and package layout to serve the application's actual boundaries. Use adapters +for collaborators with external integration responsibilities. + +## 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. + +Notarius's fixed pipeline, artifact-family boundaries, and deployment-owned +cache permissions are established product decisions. The linked ADRs retain +their rationale; the [internal overview](../internal/overview.md) inventories +their implementation. ## System Shape @@ -291,6 +315,21 @@ LLM provenance to make a run auditable after configuration changes. Manifests record identities and bounded validation summaries rather than secret, raw model, correction, or large payload content. +## Trust Boundaries And Threat Scope + +Where useful, state the trust boundaries and threat scenarios relevant to the +application's adopted requirements, along with scenarios it explicitly excludes. +For example, distinguish handling untrusted application input from defending +against a privileged actor concurrently modifying the host filesystem. + +Threat exclusions define the scope of the adopted requirements. Base defenses +and guarantees on those requirements and raise unsettled scope for a deliberate +decision under the [agent policy](agents.md). + +Keep this discussion proportionate to the application. Configuration, +operations, and internal documents retain ownership of credential supply, +runtime handling, and implementation mechanisms under the documentation policy. + ## State, Output, And Safety Source material and model responses cross application validation boundaries. diff --git a/docs/policy/release.md b/docs/policy/release.md index c15760ba..dd3f89c7 100644 --- a/docs/policy/release.md +++ b/docs/policy/release.md @@ -1,11 +1,10 @@ # Release Policy -**Base Policy Version:** 1.1 +**Base Policy Version:** 1.4 -**Last Updated**: 2026-09-26 +**Last Updated**: 2026-09-28 -Notarius adaptations: source-only delivery, lightweight tags, branch-before-tag -publication, no prereleases, and the justified native command check below. +**Upstream Source**: https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md ## Purpose @@ -72,22 +71,26 @@ source tree. Use the complete version tag as the filename and begin with a title containing the product name and that exact version. Include a short summary and any relevant compatibility impact or upgrade -instructions. Keep the note proportionate to the change. Fixed sections and -explicit no-action boilerplate are not required. Existing historical notes -need not be rewritten to adopt this format. +instructions. Choose sections suited to the release and keep the note +proportionate to the change. Keep exact current contracts in their canonical documents and update affected documentation with the behavior change. Link to those documents from the note -where useful. A release note must not substitute for current documentation. +where useful. + +Include the release footer defined by the [OSS policy](oss.md#discoverability) +in each new release document. The [release procedure](../release.md) defines +its concrete immutable-tag URLs. Notarius has no hosted download page; preparing +these links with the note does not add a network check or approval gate. + Do not create retrospective notes for the pre-procedure v0.1.0, v0.2.0, or v0.3.0 tags. -Version selection, release-note content, and retirement of completed roadmaps -are preparation responsibilities, not separate human approval gates. Preserve -planned and deferred work and repair affected links when retiring roadmaps. -Ordinary change review covers unintended files, credentials, and private data; -do not repeat it as a release-specific sign-off. Ignored local files are not -prohibited merely because they exist: they are not included in the tagged source. +Handle version selection, release-note content, and retirement of completed +roadmaps during preparation. Preserve planned and deferred work and repair +affected links when retiring roadmaps. Reuse ordinary change review for +unintended files, credentials, and private data. Scope release-content review +to the tagged source. ## Candidate Validation @@ -191,9 +194,8 @@ identify: 1. prerequisites, primary branch, and authoritative remote; 2. version and release-note preparation; 3. one publication command with its selected local checks and automated guards; -4. declared deliverables, required build targets, and automation responsibilities; -5. the successful-push completion point and separately reported delivery status; - and +4. source-only delivery, required build targets, and automation responsibilities; +5. the successful-push completion point; and 6. failure handling and ambiguous-push recovery. Use copyable commands where practical. Keep optional diagnostics and consumer diff --git a/docs/release.md b/docs/release.md index da3488d6..e268ff91 100644 --- a/docs/release.md +++ b/docs/release.md @@ -22,6 +22,15 @@ required. Update current documentation with behavior changes; retire only completed roadmaps and preserve planned/deferred work. Commit the candidate on `main` after ordinary change review. There is no separate release sign-off. +End each new release note with this footer, replacing `` with the +selected tag. Check that `COPYRIGHT`, `LICENSE`, and `docs/oss/attribution.md` +exist in the candidate source before publication; the future tag need not +resolve remotely during preparation. + +```markdown +[COPYRIGHT](https://gitea.maximumdirect.net/eric/notarius/src/tag//COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/notarius/src/tag//LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/notarius/src/tag//docs/oss/attribution.md) +``` + ## Publish Run one command from the repository with the actual selected version: diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index e32e87f2..cda18468 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -142,6 +142,8 @@ developer-guide navigation, check attribution scope and relative links, and run ## Stage 3 — Align Architecture And Release Policies Without Contract Changes +**Status:** Complete (2026-09-28). + **Goal:** Complete the customized policies and release navigation. One prompt focused on preserving existing decisions rather than redesigning them.