From 45591a79004c6811950f14dca554f6ff69b7f58e Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 25 Sep 2026 15:54:56 +0000 Subject: [PATCH] Clarify architectural constraints and threat scope --- docs/policy/architecture.md | 98 +++++++++++++++++++++++++++++------- docs/policy/documentation.md | 11 ++-- 2 files changed, 87 insertions(+), 22 deletions(-) diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 40daea7..8432508 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -1,30 +1,92 @@ # Architecture Policy -**Base Policy Version:** 1.0 +**Base Policy Version:** 1.1 -**Last Updated**: 2026-09-06 +**Last Updated**: 2026-09-25 ## Base Policy Template -This document is the base template for the canonical architecture policy,. Repositories that implement this policy should: +This document is the base template for the canonical architecture policy. +Repositories that implement this policy should: -1. Revise this document to include an architectural policy tailored to the implementing repository, including a description of the repository's purpose, overall intended system shape, and any architectural and/or engineering invariants that must be maintained during future development; -2. Ensure that any supporting documents referenced in the architecture policy are present on the filesystem, even if the initial content is simply `TODO`; -3. Update the `Last Updated` field to the current date; and -4. Remove this heading (`Base Policy Template`) and the associated text. +1. Replace the application-specific guidance below with the repository's + purpose, adopted architectural constraints, and relevant non-goals; +2. Distinguish rules governing development from descriptions of implemented + structure. Keep proposed changes and implementation status in their canonical + documents under the [documentation policy](documentation.md); +3. Reference supporting documents only when they contain useful information. + Do not create `TODO` documents solely to populate an architectural outline; +4. Update the `Last Updated` field to the current date; and +5. Remove this heading (`Base Policy Template`) and the associated text. -As compared to other base policy documents, the Architecture Policy is the document that should be most heavily customized and tailored to the intended architecture of a particular application. +This template requires substantial customization. Select topics that matter to +the application; the examples below are not a checklist of required subsystems, +interfaces, or supporting documents. -## Purpose +## Purpose And Ownership -This policy defines the purpose of this repository and the architectural principles that contributors -must follow during development. +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. -TODO: Complete this document. +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 rather than repeating those definitions here. -Non-limiting examples of topics that may be addressed by an architectural policy include: -- Adherence to a hexagonal architecture, including whether external integrations/APIs must be encapsulated within internal adapters (strongly recommended) -- Whether a library is intended to provide a highly flexible API that supports a variety of downstream consumers, or a strongly opinionated API that is intended to enforce consistency across downstream consumers -- Whether an application should support a full DAG, or alternatively a strongly ordered sequence of discrete stages -- Whether the application should use specific external libraries to provide key functionality (e.g., FeedKit, ConfigKit, PromptKit) -- Any explicit architectural non-goals \ No newline at end of file +## 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. The preference +does not by itself require an interface for every type, a fixed directory tree, +or adapters for collaborators that have no external integration responsibility. + +## Adopted Constraints And Implemented Structure + +An adopted architectural constraint governs development. It is not evidence +that every component or capability to which it could apply already exists. +For example, a rule that external integrations belong behind adapters can +apply to future integrations without implying that those integrations are +implemented or planned. + +Describe implemented structure accurately. Keep proposals and implementation +status in the roadmap, and significant decisions and their rationale in ADRs. +When an accepted decision requires changing existing structure, identify that +transition through those documents; do not describe the target structure as +already implemented or treat acceptance as proof of compliance. + +Constraints must reflect deliberately selected requirements and decisions. +Do not promote incidental implementation choices into architectural invariants. + +## Application-Specific Topics + +Replace this guidance with the relevant decisions for the application, such as: + +- its purpose, overall system shape, and responsibility boundaries; +- dependency direction and the treatment of external integrations; +- whether a library provides a flexible API for varied consumers or an + opinionated API that enforces deliberately selected conventions; +- whether orchestration supports a full DAG or an ordered sequence of stages; +- any deliberately selected libraries that form an architectural dependency; +- established invariants that future changes must preserve; and +- explicit architectural non-goals. + +## 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. + +These statements should explain the scope of the adopted architectural constraints. Excluding a scenario is not a claim that it cannot occur. Do not +infer additional defenses or guarantees merely because a hypothetical threat +can be described. Unsettled scope decisions should be raised for a deliberate +decision under the [agent policy](agents.md). + +Keep this discussion proportionate. A separate threat assessment or security +document is not required merely to adopt this template. Configuration, +operations, and internal documents retain ownership of credential supply, +runtime handling, and implementation mechanisms under the documentation policy. diff --git a/docs/policy/documentation.md b/docs/policy/documentation.md index 0fa0f8b..af468ca 100644 --- a/docs/policy/documentation.md +++ b/docs/policy/documentation.md @@ -1,6 +1,6 @@ # Documentation Policy -**Base Policy Version:** 1.2 +**Base Policy Version:** 1.3 **Last Updated**: 2026-09-25 @@ -37,9 +37,12 @@ contract, maintain it only in the owning document. Outside `docs/roadmap/`, documentation describes implemented behavior only. Partial features may be described only to their implemented boundary. -ADRs are the narrow exception: an ADR may record an accepted architectural -decision before implementation, but acceptance must not be presented as proof -that the behavior exists. The roadmap owns implementation status and sequencing +Architectural constraints may govern future changes without implying that the +components or capabilities they would govern already exist. This does not permit +describing a proposed system structure as implemented. + +ADRs may record an accepted architectural decision before implementation, but +acceptance must not be presented as proof that the behavior exists. The roadmap owns implementation status and sequencing until the decision is implemented. Current architecture, user, operator, integration, and internal documentation are updated when the behavior lands.