AlerisBrand OS

Accepted

Brand OS — Versioning Rules

How we track what changed and when it matters.

What gets versioned

Foundation — major versions (v1, v2, v3). The brand identity and reasoning system.

Branches — minor versions under their Foundation alignment (Baseline 1.0, 1.1, 1.2). Each branch versions independently.

Leaves (individual patterns, pages) — no version numbers. They carry depends_on metadata and status badges that tell you whether they're current relative to their parent branch and Foundation.

Foundation versions

Foundation v1 is what ships first. It stays v1 until something changes that would make existing branch content wrong — not just incomplete.

Triggers a new Foundation major version:

  • Changing the voice character (den nära experten) in a way that shifts what it means
  • Redefining or removing a core colour (not adding a tint — changing petrol or orange)
  • Changing the constant/contextual framework itself
  • Changing the emotional modes concept (not adding a mode — changing what modes mean)
  • Redefining the expression calibration spectrum

Does NOT trigger a new Foundation version:

  • Adding a new Foundation page (e.g. writing conventions for a new market)
  • Clarifying or expanding existing guidance without changing its direction
  • Adding examples, anti-patterns, or supporting content
  • Fixing errors or inconsistencies

The test: Would someone following the previous Foundation version now be making wrong decisions? If yes, new version. If they'd just be missing information, no version bump.

Branch versions

Branches use Foundation.Branch notation: Baseline 1.0 means "aligned with Foundation v1, first branch release."

Triggers a branch minor version increment:

  • Adding new patterns, components, or genre guides
  • Meaningful changes to existing branch guidance (not typo fixes)
  • New token values or component specs
  • Adding a new sub-section to the branch

Triggers a branch major version increment (rare):

  • Realigning with a new Foundation version
  • Restructuring the branch architecture

Does NOT trigger a version bump:

  • Typo fixes, clarifications, editorial passes
  • Adding frontmatter metadata
  • Internal planning document changes

How versions are tracked

Each Foundation page carries a version field in frontmatter:

version: 1
last_updated: 2026-03-23

Each branch page carries:

branch_version: 1.0
foundation_version: 1
last_updated: 2026-03-23
depends_on:
  - foundation/voice
  - foundation/reasoning/modes

When Foundation increments, every branch page with foundation_version less than current gets flagged "under review" — visible to stewards in the governance view, visible to consumers as a trust signal.

Changelog relationship

Every version bump gets a changelog entry. The changelog records what changed and why — not just the diff. See workspace/status/changelog.md.

These rules apply once Foundation v1 ships. During the build phase (now), we're working toward v1 — there's nothing to version yet.