Skip to content
POP NetworkPOP Network
ConstitutionPOP Network Touring Intelligence™
Market Intelligence
Master Governance · Precedence 1

MASTER PRODUCT GOVERNANCE SPEC

POP Network Touring Intelligence™

Status: Active — supreme document Owner: Product Architecture Council Precedence: Above the Constitution. Every other document defers to this one.

1. Purpose

This document defines how the product evolves — not what it is. It regulates who may change what, when a decision requires an ADR, how EPICs relate to one another, how versions promote between develop and main, and which invariants may never be broken regardless of business pressure.

Any conflict between documents is resolved by the precedence hierarchy in §3.

2. Scope of authority

ConcernAuthority
Change to a Core Invariant (constitution/05-core-invariants.md)New ADR + unanimous review by Product Architecture Council + entry in constitution/00-preamble.md amendments log.
Change to any file under constitution/ADR required.
Change to any file under architecture/ADR required.
Change to any file under ontology/ or canonical-model/ADR required.
Change to governance/ADR required + note in roadmap/03-next-iteration-recommendations.md.
New EPIC documentPR review; ADR only if it touches an invariant.
Feature inside an approved EPICPR review; must reference the EPIC.
Design token values, copy, non-structural UXPR review only.

3. Precedence hierarchy of specifications

The following order is binding. A lower-precedence document that contradicts a higher one is invalid on its face and must be corrected before merge.

  1. MASTER PRODUCT GOVERNANCE SPEC (this file)
  2. Constitution — constitution/**
  3. Core Invariants — constitution/05-core-invariants.md
  4. Architecture — architecture/**
  5. Ontology & Canonical Model — ontology/**, canonical-model/**
  6. ADRs — adr/**
  7. Governance sub-policies — governance/**, ai/**, security/**, data-quality/**, testing/**, developer/**, ux/**, telemetry/**, scoring/**, connectors/**
  8. EPICs — epics/**
  9. Roadmap — roadmap/**
  10. Support material — design-system/**, data-dictionary/**, glossary/**, process/**, decisions/**

A rule stated at level n cannot be overridden by any document at level n+1 or lower. If real-world need forces such an override, the higher document must be amended first, via ADR.

4. When an ADR is mandatory

  • Introducing, removing, or changing an invariant.
  • Any technology ratification (framework, DB, graph engine, LLM vendor, feature-flag system, observability stack).
  • Any change to the domain model, relationship model, ontology, or canonical model semantics.
  • Any change to ingestion idempotency, reconciliation policy, or human-review policy.
  • Any deviation from Feature-First layout or the four-layer separation.
  • Any breaking change to public data contracts.

Cosmetic edits and typo fixes do not require an ADR.

5. EPIC-to-EPIC relationships

  • EPICs are additive. No EPIC may require refactoring another EPIC's core structure to ship.
  • If an EPIC needs to change contracts owned by a prior EPIC, it must open a companion ADR and remain backward-compatible behind a feature flag until the next major version.
  • EPICs must declare dependencies explicitly in their Dependencies section.
  • Two EPICs may not simultaneously own the same domain concept. Ownership is declared in the EPIC document.

6. Branch promotion and versioning

  • main — ratified, releasable state.
  • develop — integration branch for EPICs in flight.
  • feature/epic-XX-* — merges into develop via PR with green CI and passing spec checks.
  • develop → main only when all invariants pass, all merged EPICs' ADRs are Accepted, and roadmap/ reflects the new state.
  • SemVer applies to the product contract, not to code: MAJOR = invariant change, MINOR = new EPIC shipped, PATCH = fixes/clarifications.

7. Breaking-change policy

Breaking changes at precedence 1–5 require:

  1. An ADR marked Breaking.
  2. A migration note in governance/versioning-policy.md.
  3. A deprecation window behind a feature flag.
  4. A roadmap entry announcing the change at least one MINOR version before enforcement.

8. Invariants that may never be broken

Protected by this document; amendable only via §2:

  • Knowledge Graph First
  • Idempotent Ingestion
  • Human-in-the-Loop Reconciliation
  • Feature Flags over Code Removal
  • Strict Layering (Presentation ↛ Domain ↛ Infrastructure coupling forbidden)
  • Feature-First Architecture
  • Documentation Before Code
  • Neuroinclusive by Design (I11 — see ADR-0024 and ux/05-neuroinclusive-design-standard.md)

8b. Cognitive-load review gate

Any change that plausibly increases cognitive load — new decision points, new simultaneous states, new interruptions, new motion, new required memorisation, denser layouts, or altered navigation — must pass, before merge:

  1. Neuroinclusive UX review against ux/05-neuroinclusive-design-standard.md.
  2. Cognitive acceptance criteria in the PR (decisions per step, states covered, data-preservation strategy, keyboard/focus behaviour, error copy, motion usage, interruption policy).
  3. Accessibility testing per testing/testing-strategy.md — keyboard, focus order, focus visibility, zoom, reduced motion, contrast, screen reader where applicable, error-recovery and data-preservation.
  4. Explicit written justification in the PR body when a cognitive trade-off is unavoidable, naming the impacted user profile and the mitigation offered.

Automated tooling is necessary but never sufficient for approval.

9. Amendments

Amendments are appended in §10 and mirrored in adr/. This file is the only document that may amend itself.

10. Amendments log

  • 2026-07-21 — v1.0.0 — Initial ratification alongside the Constitution v1.0.0.
  • 2026-07-21 — v1.1.0 — Ratified Core Invariant I11 — Neuroinclusive by Design via ADR-0024. Added §8b cognitive-load review gate. Added ux/05-neuroinclusive-design-standard.md at precedence 7. Established src/platform/accessibility/ contracts.