policy/docs/policy/architecture.md

# Architecture Policy

**Base Policy Version:** 1.2

**Last Updated**: 2026-09-27

## Base Policy Template

This document is the base template for the canonical architecture policy.
Repositories that implement this policy should:

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 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 relevant to
the application from the examples below.

## Purpose And Ownership

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

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. 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.

## 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.

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. 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.