# AEGIS — Architecture Debt Register

- **Document ID:** ARCH-29
- **Phase:** D — Deployment & Long View
- **Status:** Draft for review (post four-reviewer discipline)
- **Version:** 0.1
- **Date:** 2026-07-10
- **Owner:** Chief Security Architect

---

## 1. Purpose

Codify how AEGIS records, tracks, and retires architectural compromises. Implements mandate #41 (Architecture Debt Register). Debt is inevitable; hidden debt is fatal. The Register makes debt visible, owned, expiring, and retirable.

## 2. Debt Entry Format

Every entry contains:

```
DebtEntry {
  id                   : DebtId (monotonic per class)
  class                : Kernel | Identity | AI | Plugin | Recovery | Ops | Standards | Deployment | ...
  title                : one-line summary
  reason               : why the compromise was accepted
  risk                 : specific security/operational risk incurred
  affected_subsystems  : [ARCH-* refs]
  affected_mandates    : [CLAUDE.md mandate numbers]
  owner                : DID (individual or team)
  expiration           : date | release | condition
  mitigation_plan      : concrete steps
  target_resolution    : date | release
  status               : Open | Mitigated | Retired | Renewed | Escalated
  linked_pr / arch_ref : where accepted
  audit_ref            : Layer-A audit event on acceptance
  signature            : Owner + Auditor sign-off
}
```

Entries are versioned (semver at schema); stored in the control-plane + object-store dual-store like other configs (ARCH-22).

## 3. Requirements

- **REQ-1.** Every accepted architectural compromise creates a DebtEntry.
- **REQ-2.** Every DebtEntry has an expiration; no perpetual debt.
- **REQ-3.** Expired debt not renewed becomes an Auditor incident.
- **REQ-4.** Debt count and age distribution are security metrics (ARCH-24 M-OPS-05).
- **REQ-5.** Every Release Security Gate exception (ARCH-28) creates a DebtEntry.

## 4. Debt Classes (v0-GA candidates)

Documented at v0-GA — retired in order below by v1:

- **D-K-01.** Kernel v0-GA assurance L3 vs. target L5. **Reason:** formal analysis + property test suite maturity. **Owner:** Kernel team. **Expiration:** v1. **Mitigation:** Phase E formal-verification candidates + expanded property tests.
- **D-C-01.** Cryptographic Identity assurance L3 vs. target L5. **Reason:** post-quantum hybrid pending library maturity. **Owner:** Crypto team. **Expiration:** v1.x. **Mitigation:** Q-09-2; adopt hybrid when NIST + library production-ready.
- **D-A-01.** AI Safety Layer canary corpus size. **Reason:** limited operational data at v0-GA. **Owner:** Safety Layer team. **Expiration:** v0.2. **Mitigation:** grow corpus with operational data + red-team engagements.
- **D-R-01.** Risk Engine weight catalog initial values conservative (prefer FPs over FNs). **Reason:** insufficient operational evidence. **Owner:** Risk team. **Expiration:** v1 revisit. **Mitigation:** operate + measure + refine per Q-24-1.
- **D-P-01.** Plugin runtime not v0-GA (interface-only). **Reason:** narrow v0 scope. **Owner:** Plugin team. **Expiration:** v0.2. **Mitigation:** Wasm runtime + governance per ARCH-17.
- **D-O-01.** SAML/SCIM IdP not v0. **Reason:** narrow v0 scope. **Owner:** Identity team. **Expiration:** v1. **Mitigation:** ARCH-02 D-02-4.
- **D-O-02.** OIDC-only excludes some enterprises. **Same as above.**
- **D-D-01.** Docker Compose R-2 topology minimally covered. **Reason:** prioritized R-1 and R-3+. **Owner:** Ops. **Expiration:** v1. **Mitigation:** expand coverage post-v0.
- **D-D-02.** MSSP hosted (R-7) deferred to v1+. **Reason:** scope. **Owner:** Product. **Expiration:** v1 planning.
- **D-S-01.** Formal methods (TLA+/Alloy) piloted post-v0-GA. **Reason:** initial productivity vs. formal-methods learning curve. **Owner:** Kernel + Capability teams. **Expiration:** v1. **Mitigation:** Q-06-3 pilot; expand per Phase E.

## 5. Governance

- **Additions.** PR to `docs/debt/`; Owner + Auditor sign-off; Layer-A audit event.
- **Renewals.** Same as additions; require documented rationale for renewal; renewals count as a metric.
- **Retirements.** Verification that mitigation is in place; Owner + Auditor sign-off; audit event.
- **Escalations.** Debt with expired expiration and no renewal becomes an incident (ARCH-21 SEV-3 default).

## 6. Cadence

- **Weekly ops review** — new debt + expiring debt surfaced.
- **Monthly** — full register review; retirements celebrated; renewals scrutinized.
- **Quarterly** — trend distribution reported to executive brief.
- **Annually** — Auditor examines register for hidden debt (unrecorded compromises).

## 7. Independent Architecture Review

- **F-1.** *Debt could hide risk.* Auditor visibility + annual hidden-debt audit + trend metrics.
- **F-2.** *Debt classes could sprawl.* Class list versioned; new classes require justification.

## 8. Adversarial Architect Review

- **A-1.** *Insider adds debt to legitimize a compromise.* Auditor visibility + Layer-A audit + renewal scrutiny.
- **A-2.** *Insider hides debt by not recording.* Annual hidden-debt audit; drift monitor on unaccounted deviations; culture + training.
- **A-3.** *Attacker exploits stale debt.* Expiration + escalation-on-expired.

## 9. Operational Reliability Review

- **O-1.** Debt tracking is lightweight; register lives in-repo.
- **O-2.** Ownership rotations tracked; departing owner triggers re-assignment.
- **O-3.** Register searchable / queryable via CLI.

## 10. Self-Critique

- **S-1.** *"Retirement" verification may become perfunctory.* Retirement requires evidence: test artifact, metric threshold, verification instrument. Not just a checkbox.
- **S-2.** *Debt owners may leave the company.* Owner-change process triggers re-review of open debt.
- **S-3.** *Some debt is uncomfortable to record (e.g., MSSP deferral).* Cultural point — the Register makes debt legible, which is uncomfortable but essential.

## 11. First-Target Analysis and Redesign

**Target:** hidden debt — compromises not recorded. This is the debt that hurts most because it never expires. Response:
1. **Annual hidden-debt audit** by external auditor + internal red-team retrospective — proactively look for undocumented compromises.
2. **Drift monitor** compares live architecture state against ARCH-* claims; deviations without a corresponding DebtEntry alarm.
3. **PR reviewer training** to spot "quietly-accepted" compromises and require Register entries.
4. **Culture.** Reward recording debt; treat unrecorded debt as a review failure.

**Second target:** debt renewal. Response: renewals require the same rigor as additions; renewal count metric surfaces persistent debt patterns.

## 12. Decisions

### D-29-1. Every accepted compromise records a DebtEntry

- **Reason.** Mandate #41.

### D-29-2. Annual hidden-debt audit

- **Reason.** §11 first-target response.

## 13. Open Questions

- Q-29-1. Register schema versioning + querying UX. Resolved in Phase E.

## 14. Change Log

- **0.1 (2026-07-10)** — Initial draft with v0-GA debt candidates listed.