Portfolio Portal
ADR accepted owner: Azwaan reviewed: 2026-07-05

ADR 0006: Adopt an Architecture Governance framework

  • Status: accepted
  • Date: 2026-07-05
  • Deciders: Azwaan
  • Tags: governance, process, meta

This ADR governs how the portal and ecosystem evolve (process), not the ecosystem’s implementation. Like ADR 0001 and ADR 0004, it is a portal-governance decision and changes no existing architecture.

Context

Through Phases A–E the portal came to describe repositories, capabilities, architecture, the operating model, and an enterprise review. What was missing was an explicit, evidence-based account of how future work is designed, reviewed, approved, and incorporated — so decisions stay consistent as the ecosystem and its AI autonomy grow. Governance discipline already existed implicitly (ADRs, the four-part test, phase-gated review, the Definition of Done, human approval gates) but was not consolidated.

Decision

Adopt an Architecture Governance section (portal/governance/) that consolidates and formalises existing discipline into:

  1. Governance objectives, decision process, ownership, review, approval, quality gates, and change management (Architecture Governance).
  2. A Capability Decision Framework and Decision Matrix — the standard reference for where a proposed thing belongs (including the proposed Platform Services layer).
  3. A Repository Lifecycle with governance expectations per stage.
  4. Documentation Governance defining the source of truth for every artefact.
  5. AI Governance defining AI responsibilities, authority boundaries, and required human approvals.
  6. An Architecture Review Lifecycle — review triggers and a standard checklist.

The governing rule is unchanged and now explicit: AI proposes and drafts; humans decide and approve; nothing customer-facing is auto-sent; deterministic rules decide and AI explains.

Options considered

Option Pros Cons
A (chosen): explicit governance section Consistent, teachable, scales with AI autonomy; consolidates existing discipline Another section to keep current
B: leave governance implicit (ADRs + CLAUDE.md only) No new pages Ambiguous as autonomy grows; placement decisions ad-hoc
C: heavyweight board/process Rigorous Overkill for a single-founder ecosystem; slows delivery

Consequences

  • Positive: future placement/creation/retirement decisions have a standard; AI participation has explicit limits; reviews have triggers and a checklist; the portal governs, not just describes.
  • Negative / trade-offs: governance pages must be kept current (a Documentation-Governance responsibility).
  • Follow-ups / affected pages: navigation, Portfolio Overview, and the Operating Model gain governance links; the proposed ADR 0005 Platform Services layer is referenced by the decision framework as a (proposed) destination.

Compliance / review

This framework governs itself: changes to governance follow the same ADR + review process it defines. Revisit at the annual strategic review.