# AEGIS — Architecture Health Metrics

- **Document ID:** ARCH-44
- **Phase:** E.2 — Verification Methodology
- **Status:** Draft for review (post four-reviewer discipline)
- **Version:** 0.1
- **Date:** 2026-07-10
- **Owner:** Chief Security Architect

---

## 1. Purpose

Codify metrics that measure the health of the architecture itself, not just the running platform. Complements ARCH-24 (Security Metrics) with the *architecture-observability* dimension mandated by Phase-E.2 #6. Architecture health becomes measurable.

## 2. Metric Catalog

### 2.1 Decision Flow

- **M-ARCH-01. ADR Creation Rate.** ADRs per month. Trending; sudden drops = decision-stagnation; sudden spikes = architectural churn.
- **M-ARCH-02. ADR Approval Time.** Time from Proposed to Approved. p50/p95/p99. Target within SLO per ARCH-36 §5.
- **M-ARCH-03. Rejection Rate.** ADRs rejected / total. Low is not always good — very low may mean reviewers rubber-stamp; very high may mean poor design coming in.
- **M-ARCH-04. Conditional Verdict Rate.** Conditional / (Approved + Conditional). Rising = deferred debt.

### 2.2 Debt

- **M-ARCH-10. Debt Count.** Active Debt Register entries. Trending.
- **M-ARCH-11. Debt Age Distribution.** p50/p95 age. Rising = accumulating.
- **M-ARCH-12. Debt Renewal Rate.** Renewals / retirements. High = deferred progress.
- **M-ARCH-13. Debt Expiry Currency.** Expired-without-renewal count. Target 0; anomaly-alerted.

### 2.3 Threat Model

- **M-ARCH-20. Threat-Model Freshness.** Time since ARCH-03 last updated. Alarm if > 6 months absent other trigger.
- **M-ARCH-21. Post-Incident Threat Diffs.** Post-mortems producing threat_diff PRs / total post-mortems. Target 100% (Living Threat Model).
- **M-ARCH-22. Subsystem-Change Threat Diffs.** New subsystem ADRs with threat_diff sections / total. Target 100%.

### 2.4 Review

- **M-ARCH-30. Review Completion Rate.** Reviews completed within SLO / total.
- **M-ARCH-31. Reviewer Load.** Reviews per SR per month. Sustainability signal.
- **M-ARCH-32. Reviewer Independence.** Fraction of reviews where reviewer is on a different team than author. Target 100% for security-critical.
- **M-ARCH-33. Post-Implementation Delta Rate.** Deltas found between implementation and approved design / total subsystems reviewed post-hoc.

### 2.5 Verification

- **M-ARCH-40. Verification Coverage.** Claims with ≥ 1 evidence link / total claims. Target 100%.
- **M-ARCH-41. Evidence Freshness.** Claims with fresh evidence / total. Alarm on drop.
- **M-ARCH-42. Assurance-Level Delta.** Sum of |target − current| across subsystems. Trending down = progression.

### 2.6 Documentation

- **M-ARCH-50. Documentation Drift.** ARCH-* docs with staleness beyond policy / total. Consistency checker flags.
- **M-ARCH-51. Broken References Detected.** Consistency-checker C-1 detections per release. Target 0.
- **M-ARCH-52. Executable-Doc Coverage.** Claims / rules that are executable via tests / total claim + rules. Trending up.

### 2.7 Outstanding Assumptions

- **M-ARCH-60. Outstanding Assumptions.** Assumptions with no verification plan. Target 0; escalation on any.
- **M-ARCH-61. Assumption Currency.** Assumptions revalidated within window / total. Target ≥ 95%.

## 3. Reporting Cadence

- **Weekly ops review.** Debt Trend + ADR Approval Time + Review Completion.
- **Monthly architecture council.** Full architecture-health dashboard.
- **Quarterly executive brief.** Trends + top-5 issues + Debt Register spotlight.
- **Annually.** Full architecture-health audit; feeds Continuous Architecture Review.

## 4. Alarm Thresholds

- Debt Age p95 > 12 months → SEV-3.
- Broken references > 0 at release → block release.
- Threat-Model Freshness > 12 months absent other update → SEV-3.
- Reviewer independence < 100% for security-critical → SEV-3.
- Outstanding Assumptions > 0 → SEV-4 (per-item review).

## 5. Governance Integration

- Metrics feed Continuous Architecture Review (ARCH-47, upcoming).
- Trend degradation triggers Architecture Council review.
- Metrics inform Debt Register additions.

## 6. Independent Architecture Review

- **F-1.** *Metric proliferation.* Governance rule: adding requires justification (ARCH-24 M-8).
- **F-2.** *Anti-gaming.* External auditor annually samples metric integrity.

## 7. Adversarial Architect Review

- **A-1.** *Attacker manipulates ADR-Approval-Time to hide slow-review pattern.* Cross-substrate reconciliation with audit chain.
- **A-2.** *Insider tunes thresholds to hide degradation.* Threshold changes ceremony-controlled (ARCH-22 catalog).
- **A-3.** *Attacker suppresses debt-alerting.* Alerts have dual channels; auditor visibility.

## 8. Operational Reliability Review

- **O-1.** Dashboards owned; reviewed at Architecture Council.
- **O-2.** Metrics ingest cheap; bounded cardinality.
- **O-3.** 15-year sustainability via schema stability.

## 9. Self-Critique

- **S-1.** *Some metrics (reviewer load) touch sensitive HR territory.* Aggregated; not attributed to individuals externally.
- **S-2.** *"Trend interpretation is subjective."* Framework provides trend interpretation guide; anomaly-triggered rather than magnitude-triggered where possible.

## 10. First-Target Analysis and Redesign

**Target:** the metrics definitions themselves. If someone edits them to hide degradation, the whole observability layer becomes decorative. **Response:** definitions ceremony-controlled (ARCH-22 C-C class); auditor visibility; historical baselines retained.

## 11. Decisions

### D-44-1. Architecture Health Metric Catalog with reporting cadences

- **Reason.** Mandate #6.

## 12. Change Log

- **0.1 (2026-07-10)** — Initial draft.