Copilot instructions

1---
2applyTo: "**/architecture/**, **/adr/**, **/rfc/**, **/*.arch.md"
3description: "ARB process, ADR/RFC authoring standards, technology lifecycle classification, and architecture fitness functions for enterprise governance."
4---
5 
6# Architecture Governance — Copilot Instructions
7 
8> Applied automatically when working with architecture records, ADRs, RFCs, and architecture markdown files. Loaded alongside copilot-instructions.md.
9 
10---
11 
12## Architecture Review Board (ARB)
13 
14### Trigger Conditions — When ARB Review is Mandatory
15 
16The following changes **must not proceed to implementation** without a recorded ARB decision:
17 
18| Trigger | Examples |
19|---------|---------|
20| New service or application | A new Spring Boot service, a new Lambda function used by > 1 team |
21| New persistent data store | Adding DynamoDB table, RDS instance, ElasticSearch cluster, Redis for primary storage |
22| New cloud provider | First use of Azure or GCP resources in an AWS-primary estate |
23| Technology not on Approved List | Any language, framework, or SaaS tool with no existing approved usage in the estate |
24| Cross-domain data sharing | A service in Domain A reading data owned by Domain B |
25| Change to shared infrastructure | Changes to the VPC, Transit Gateway, API Gateway stage, or shared Route 53 zone |
26| Data residency or sovereignty change | Moving data outside the approved region set (e.g., eu-west-1 to us-east-1 for EU data) |
27| Vendor lock-in increase | Adopting a proprietary API where a vendor-neutral alternative exists and was not formally evaluated |
28 
29### Submitting for ARB Review
30 
311. Author an RFC using the `write-rfc.prompt.md` task prompt
322. Open a pull request targeting `architecture/rfcs/` — do not merge without an ARB decision
333. Tag `@arb-reviewer` and `@enterprise-architect` in the PR description
344. ARB meeting cadence: fortnightly; P1 incidents can trigger an emergency ARB within 24 hours
355. Record the outcome in `docs/architecture/decisions/governance-register.md`
36 
37See `.github/agents/arb-reviewer.agent.md` and `.github/agents/enterprise-architect.agent.md`.
38 
39---
40 
41## ADR — Architecture Decision Record
42 
43### Mandatory Format
44 
45Every ADR file must be at `docs/decisions/ADR-{NNN}-{slug}.md` and contain all six sections:
46 
47```markdown
48# ADR-{NNN}: {Title — present tense, e.g., "Use DynamoDB for session storage"}
49 
50Date: YYYY-MM-DD
51Status: Proposed | Accepted | Deprecated | Superseded by ADR-{NNN}
52Deciders: {Comma-separated names or teams}
53Tags: {storage | compute | integration | security | ml | platform}
54 
55## Context
56 
57What is the problem or opportunity forcing a decision? Include constraints, non-functional
58requirements, and any relevant business context. Minimum 3 sentences.
59 
60## Decision
61 
62State the decision as an active sentence: "We will use X because Y."
63Be specific — name the exact technology, version, configuration, or pattern chosen.
64 
65## Consequences
66 
67### Positive
68- {Concrete benefit with measurable expectation where possible}
69 
70### Negative
71- {Known cost, risk, or limitation that is accepted}
72 
73### Neutral
74- {Side effects that are neither clearly positive nor negative}
75 
76## Alternatives Considered
77 
78| Option | Pros | Cons | Reason Rejected |
79|--------|------|------|----------------|
80| Option A | ... | ... | ... |
81| Option B | ... | ... | ... |
82 
83## References
84 
85- RFC: {link if applicable}
86- Spike: {link to spike branch or document}
87- ARB Decision: {link to governance register entry}
88- External: {standards body reference, vendor documentation}
89```
90 
91### ADR Status Transitions
92 
93```
94Proposed → Accepted     (after ARB approval or team decision for non-ARB changes)
95Proposed → Rejected     (ARB or team rejects; reasons must be recorded in Context)
96Accepted → Deprecated   (technology end-of-life or superseded without a direct replacement)
97Accepted → Superseded by ADR-{NNN}  (replaced by a new decision)
98```
99 
100Never delete an ADR — only transition its status. The record of rejected paths is as valuable as accepted ones.
101 
102---
103 
104## RFC — Request for Comments
105 
106RFCs are required for any change that affects > 1 team or that the ARB must review. RFCs live at `architecture/rfcs/RFC-{NNN}-{slug}.md`.
107 
108### Mandatory RFC Sections
109 
110```markdown
111# RFC-{NNN}: {Title}
112 
113Author: {name}
114Date: YYYY-MM-DD
115Status: Draft | Under Review | Approved | Rejected | Withdrawn
116ARB Review Required: Yes | No
117Related ADRs: ADR-{NNN}, ...
118 
119## Problem Statement
120 
121Describe the specific problem being solved. Include evidence: error rates, latency p99 data,
122cost data, or incident references. Do not describe the solution here.
123 
124## Motivation
125 
126Why does this problem need to be solved now? What is the cost of inaction?
127 
128## Proposed Solution
129 
130Describe the solution precisely. Include:
131- Architecture diagrams (as Mermaid or PlantUML inline)
132- Configuration examples
133- API contracts (OpenAPI snippet or JSON Schema)
134- Data model changes (ERD or table definitions)
135 
136## Alternatives Considered
137 
138For each rejected alternative, state: what it was, why it was considered, why it was rejected.
139 
140## Drawbacks
141 
142What are the known downsides or risks of the proposed solution?
143 
144## Success Criteria
145 
146| Criterion | Measurement | Target |
147|-----------|------------|--------|
148| Latency   | p99 API response time | < 200ms |
149| Availability | Error rate | < 0.1% |
150 
151## Migration Plan
152 
153Step-by-step migration path including rollback procedure. Identify any dual-write periods,
154feature flags, or traffic shifting strategy.
155 
156## Rollout Plan
157 
158Phase 1: {scope, date, owners}
159Phase 2: {scope, date, owners}
160Rollback trigger: {specific condition that triggers rollback}
161```
162 
163---
164 
165## Technology Lifecycle Classification
166 
167All technologies used in the estate are classified using a four-tier model. The authoritative list is at `docs/architecture/tech-radar.md`.
168 
169| Tier | Definition | Action Required |
170|------|-----------|----------------|
171| **Invest** | Actively adopt and grow usage; long-term support confirmed | Default choice when applicable |
172| **Tolerate** | Acceptable for existing use; no new projects should start here | Plan migration to Invest-tier alternative; track in tech-debt register |
173| **Migrate** | Active migration away; new features must not use | Create migration ADR; assign sprint allocation |
174| **Eliminate** | No new usage; existing usage must be removed by sunset date | Hard gate in CI: flag usage in code scan |
175 
176### Current Classification Examples (update `tech-radar.md` as the source of truth)
177 
178| Technology | Tier | Notes |
179|-----------|------|-------|
180| Java 21 (LTS) | Invest | Target runtime for all JVM services |
181| Spring Boot 3.x | Invest | Standard application framework |
182| AWS CDK v2 (TypeScript) | Invest | Standard IaC |
183| Python 3.12 | Invest | Standard for ML and data workloads |
184| Java 11 | Tolerate | Existing services; migrate to Java 21 by Q4 2025 |
185| Spring Boot 2.x | Migrate | Spring Boot 2 OSS support ended Nov 2023 |
186| Java 8 | Eliminate | No new usage; sunset existing by Q2 2025 |
187| Apache Commons Collections 3.x | Eliminate | Known CVEs; replace with Guava or JDK equivalents |
188 
189---
190 
191## Architecture Fitness Functions
192 
193Fitness functions are automated checks that prevent architectural drift. They run in CI.
194 
195### ArchUnit Rules (Java — `src/test/java/architecture/ArchitectureTest.java`)
196 
197```java
198// No cross-schema SQL joins — services must not query across domain boundaries
199@ArchTest
200static final ArchRule no_cross_schema_joins = noClasses()
201    .that().resideInAPackage("..repository..")
202    .should().dependOnClassesThat()
203    .resideInAPackage("..repository..") // different bounded context
204    .because("Cross-domain queries couple bounded contexts — use APIs or events instead");
205 
206// No circular module dependencies
207@ArchTest
208static final ArchRule no_cycles = slices()
209    .matching("com.enterprise.(*)..").should().beFreeOfCycles();
210 
211// Domain layer must not depend on infrastructure
212@ArchTest
213static final ArchRule domain_independence = noClasses()
214    .that().resideInAPackage("..domain..")
215    .should().dependOnClassesThat()
216    .resideInAnyPackage("..infrastructure..", "..adapter..");
217 
218// Max efferent coupling per class: 20 dependencies
219@ArchTest
220static final ArchRule max_coupling = classes()
221    .should(haveMaximumNumberOfDependencies(20));
222```
223 
224### Coupling Thresholds
225 
226| Metric | Warning | Fail |
227|--------|---------|------|
228| Efferent coupling per class | > 15 | > 20 |
229| Package cyclomatic complexity | > 10 | > 15 |
230| Inter-service synchronous call chains | > 3 hops | > 5 hops |
231| Shared database tables across services | Any | Any |
232 
233---
234 
235## Technical Radar Format
236 
237The radar at `docs/architecture/tech-radar.md` uses four quadrants: Languages & Frameworks, Platforms, Tools, Techniques.
238 
239Each entry follows this format:
240 
241```markdown
242### {Technology Name} — {Invest | Tolerate | Migrate | Eliminate}
243 
244**Quadrant:** Languages & Frameworks | Platforms | Tools | Techniques
245**Since:** YYYY-MM-DD
246**Owner:** {team or person responsible}
247**Context:** One paragraph — why this classification, what triggered any status change.
248**Migration Path:** (only for Migrate/Eliminate) Link to ADR or migration guide.
249```
250 
251---
252 
253## Governance Decision Register
254 
255`docs/architecture/decisions/governance-register.md` records every ARB decision. Format:
256 
257```markdown
258| Date | RFC/ADR | Title | Decision | Deciders | Conditions |
259|------|---------|-------|----------|----------|-----------|
260| 2024-11-01 | RFC-014 | Adopt Kafka for event streaming | Approved | ARB Quorum | Must use MSK; Confluent Schema Registry required |
261| 2024-09-15 | RFC-011 | Add GCP Vertex AI | Rejected | ARB Quorum | AWS Bedrock covers use case; revisit if gap proven |
262```
263 
264---
265 
266## What Constitutes a Material Architectural Change
267 
268A change is **material** if it meets any of the following criteria. Material changes require an ADR at minimum; many also require ARB review per the trigger table above.
269 
270- Changes the public API contract of a service used by > 1 consumer
271- Changes the data model of a shared entity in a way that is not backward compatible
272- Introduces a new dependency on an external vendor API with data egress
273- Changes the authentication or authorization model for any user-facing system
274- Increases the blast radius of a failure (e.g., moves from stateless to stateful, adds shared mutable state)
275- Changes the deployment topology (e.g., single-region to multi-region, monolith to microservice)
276- Affects data retention, data classification, or PII handling
277 
278---
279 
280## Anti-Patterns — Flag These
281 
282| Pattern | Action |
283|---------|--------|
284| ADR with no Alternatives Considered section | Incomplete — request alternatives before approving |
285| RFC with no rollback plan | Block — rollback is mandatory for all RFC-gated changes |
286| Technology in Migrate/Eliminate tier introduced in new service | Block — raise ARB exception request |
287| Cross-domain database join in production code | Flag with ArchUnit rule violation; require RFC |
288| Architecture decision made in a Slack thread with no ADR | Create ADR from Slack thread content; date = decision date |
289