Portfolio Portal
Governance living owner: Azwaan reviewed: 2026-07-05

Architecture Review Lifecycle

When architectural reviews should occur, and a standard checklist to run each time. This formalises the ecosystem’s existing “phase-gated, reviewable change” discipline (Principle 10; WIL “each phase ends with an architecture review and does not continue until reviewed”). Evidence-first.

Review triggers

Trigger Why review Depth Output
New repository Confirm it’s needed & correctly placed (not a pack/skill/feature) Light–standard Placement decision + ADR + registry row
Major capability Ownership, reuse, duplication, layer placement Standard Capability page + Reuse Map update
Platform restructuring Layer boundaries, dependency directions Deep ADR (e.g. 0005) + updated diagrams
Cross-venture reuse Prevent trapped/duplicated capabilities Standard Extraction decision; Reuse Map update
Commercialisation External exposure, multi-tenancy, guardrails Deep Risk review + ADR
New/changed AI autonomy Authority boundary + approvals Standard AI Governance entry + ADR
Annual strategic review Whole-ecosystem health, drift, roadmap Deep Refreshed Architecture Review + risks
Phase boundary (portal) Gate before the next phase Standard Phase changelog + review notes

Review depth

graph LR
    T[Trigger] --> D{Structural or cross-repo?}
    D -->|no| L[Light review<br/>Definition of Done + consistency]
    D -->|yes| S{Changes layer model / dependencies / autonomy?}
    S -->|no| ST[Standard review<br/>checklist + ADR]
    S -->|yes| DP[Deep review<br/>full checklist + risks + evolution impact]

Standard review checklist

Run this checklist at every review; deep reviews add the starred (★) items.

Placement & necessity

  • [ ] Passes the four-part test (real problem · reduces coupling · clear owner · one-paragraph)
  • [ ] Correct destination per the Decision Matrix
  • [ ] Not a reusable capability being trapped in a venture repo
  • [ ] Not duplicating an existing concept (Concept Ownership Registry)

Ownership & dependencies

  • [ ] Single, clear owner named (no diffuse ownership)
  • [ ] Dependencies point at contracts, not venture repos; no new circular/hidden dependency
  • [ ] ★ Impact on the system dependency map assessed

Evidence & documentation

  • [ ] Claims cite evidence; uncertainty recorded (Principle 8)
  • [ ] Uses the canonical template; frontmatter correct
  • [ ] Digest / capability page / diagrams updated; registry row present
  • [ ] llms.txt + current-state (changelog, dashboard) updated

Decision & governance

Consistency (Definition of Done)

  • [ ] Registry ⇄ digests ⇄ diagrams agree; no orphans, no dead links
  • [ ] last_reviewed dates current

Cadence

  • Triggered reviews — on any trigger above (event-driven).
  • Annual strategic review — a scheduled deep review refreshing the Architecture Review, Risks, Opportunities, and Evolution pages.
  • Portal phase gates — each phase (A–F and beyond) ends with a review before the next begins.
  • ✅ Implemented: phase-gated reviews (portal phases A–F; WIL phase gates); the Phase-D ecosystem review; ADR sign-off.
  • ⏳ Recommended: a standing annual review cadence; automated pre-review checks (link/orphan/pin-freshness) via the orchestrator so human review focuses on judgement, not mechanics.