eric/policy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Simplify policy wording while preserving explicit safeguards

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-27 19:46:41 +00:00
parent ad4a20e17f
commit bf92cb1c83
11 changed files with 152 additions and 462 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
docs/policy/architecture.md
View File

@@ -1,8 +1,8 @@
# Architecture Policy
**Base Policy Version:** 1.1
**Base Policy Version:** 1.2
**Last Updated**: 2026-09-25
**Last Updated**: 2026-09-27
## Base Policy Template
@@ -14,14 +14,12 @@ Repositories that implement this policy should:
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;
3. Reference supporting documents when they contain useful information;
4. Update the `Last Updated` field to the current date; and
5. Remove this heading (`Base Policy Template`) and the associated text.
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.
This template requires substantial customization. Select topics relevant to
the application from the examples below.
## Purpose And Ownership
@@ -31,7 +29,7 @@ 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 rather than repeating those definitions here.
to ADRs for decision rationale.
## Architectural Approach
@@ -40,23 +38,22 @@ 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.
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
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.
An adopted architectural constraint governs development, including future
functionality. For example, a rule that external integrations belong behind
adapters applies whenever such integrations are introduced. Describe current
structure from implemented behavior.
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.
transition through those documents. Describe the target structure as implemented
when the corresponding changes land.
Constraints must reflect deliberately selected requirements and decisions.
Do not promote incidental implementation choices into architectural invariants.
@@ -81,12 +78,11 @@ 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
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. 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,
Keep this discussion proportionate to the application. A separate threat
assessment or security document is optional when adopting this template.
Configuration, operations, and internal documents retain ownership of credential supply,
runtime handling, and implementation mechanisms under the documentation policy.