# AEGIS — Architecture Consistency Verification

- **Document ID:** ARCH-41
- **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

Automated verification that the ARCH-* corpus + ADR corpus + Verification Matrix + Debt Register + threat model are internally consistent. Implements Phase-E.2 mandates #1 (Knowledge Graph), #2 (Decision Traceability), #3 (Consistency Verification as release gate).

## 2. The Architecture Knowledge Graph

- **Nodes:** ARCH-* docs, ADRs, requirements (from ARCH-02), threats (ARCH-03), assets (ARCH-04), engines (ARCH-07), capabilities (ARCH-08), policies (per Policy Engine corpus), Verification Matrix rows (ARCH-37), Debt Register entries (ARCH-29), metric definitions (ARCH-24), runbooks (ARCH-21), incidents (post-mortems).
- **Edges (typed):** `depends_on`, `mitigates`, `verified_by`, `measured_by`, `governs`, `implements`, `supersedes`, `deprecates`, `owned_by`, `references`.
- **Storage.** Graph derived from `docs/**/*.md` frontmatter + explicit reference blocks + ADR fields. Materialized in CI to a queryable form (SQLite-graph or similar).

## 3. Consistency Checks (Automated)

Run in CI on every PR touching architecture; also full-run at Architecture Freeze and before every release.

- **C-1 Broken references.** Every `[ARCH-*]`, `[ADR-*]`, `[SEC-*]` link resolves.
- **C-2 Missing dependencies.** Every ADR lists dependencies; every referenced doc exists.
- **C-3 Missing verification.** Every architectural claim has ≥ 1 Verification Matrix row.
- **C-4 Missing metrics.** Every ADR references ≥ 1 metric per mandate #2.
- **C-5 Missing threat-model diff.** Every architectural ADR has a threat-model diff section (per ARCH-35 amended template).
- **C-6 Missing ADR references.** ARCH-* docs referencing Decisions (D-*) map to ADRs post-Freeze.
- **C-7 Conflicting policies.** Policy Engine corpus validators run: no rule contradicts an invariant; classification ceilings consistent across policies.
- **C-8 Conflicting trust boundaries.** Boundary contracts (ARCH-05 BC-*) consistent across engine specs.
- **C-9 Capability mismatches.** Every capability referenced in an engine spec exists in the ARCH-08 vocabulary; every capability in vocabulary is used or explicitly reserved.
- **C-10 Unverified assumptions.** Every "assumption" section entry has an owner + verification approach; unhandled assumptions are Debt Register entries.
- **C-11 Principle citations.** Every ADR cites at least one principle; principles exist in ARCH-33.
- **C-12 Debt currency.** Every Debt Register entry has an expiration ≤ target release; expired debt without renewal alarms.
- **C-13 Metric-to-mandate map.** Every mandate has ≥ 1 metric (per ARCH-24 requirement).
- **C-14 Ownership completeness.** Every engine, standard, policy, and matrix row has a named owner.

## 4. Failure Handling

- **Blocking checks** (C-1..C-9) block PR merge.
- **Warning checks** (C-10..C-14) produce warnings + Debt Register entries if not addressed within SLO.

Exceptions require ARCH-19-EXCEPTION marker + Owner + Auditor sign-off + expiration.

## 5. Release Gate Integration

- Full consistency run is part of Release Certification Checklist (ARCH-46).
- Failed checks block release regardless of other gates.

## 6. Living Threat Model Enforcement

- Every incident post-mortem triggers a `threat_diff` PR against ARCH-03.
- Every new subsystem's ADR must have a threat-model diff (C-5).
- Consistency checker verifies the threat model updates match incident/subsystem entries.

## 7. Independent Architecture Review

- **F-1.** *Graph maintenance overhead.* Auto-derived; explicit link fields; validated in CI.
- **F-2.** *False positives on link checks.* Whitelist for known-fuzzy references + rule tuning.
- **F-3.** *Living Threat Model discipline decays.* Currency metric + auditor visibility.

## 8. Adversarial Architect Review

- **A-1.** *Attacker adds an ARCH-EXCEPTION to hide inconsistency.* Exception register (ARCH-19) + auditor visibility + expiry + drift monitor on exception count.
- **A-2.** *Attacker rewires the graph to hide a broken link.* Graph derived from source docs; hash-chained; tamper-evident.
- **A-3.** *Attacker degrades a policy to mask conflicts.* Policy versioned + ceremony changes; validators catch semantic conflicts.

## 9. Operational Reliability Review

- **O-1.** CI time budget documented; graph derivation cached.
- **O-2.** Failure messages actionable + linked to fix guidance.
- **O-3.** Sustainability: minimal manual work when authoring follows templates.

## 10. Self-Critique

- **S-1.** *"Consistency" is only as good as the checks defined.* New checks added on incident learnings.
- **S-2.** *Graph derivation from markdown is fragile.* Explicit frontmatter + parser tests + fuzz on the parser.
- **S-3.** *Human authors will resist strict CI.* Balanced by clear error messages + reviewer help.

## 11. First-Target Analysis and Redesign

**Target:** the consistency checker itself. If compromised or misconfigured, it becomes a rubber stamp — false confidence that architecture is sound. **Response:** checker is versioned in the ARCH-* corpus; changes reviewed like any security-critical code; two-approver; auditor visibility; checker's own tests exist; drift monitor between checker version and repo state; external audit samples random inconsistencies to verify the checker catches them.

## 12. Decisions

### D-41-1. Automated Knowledge Graph derivation + 14 consistency checks + release gate

- **Reason.** Mandates #1, #2, #3.

## 13. Change Log

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