Skip to content

ADR-002 — Source of Truth Strategy

Status: Accepted

Date: 2026-07-04

Owner: Architecture Board

Decision Type: Foundational

Context

UC-BoK is now a model-driven knowledge platform.

The repository contains project identity, architecture decisions, normative specifications, validation schemas, canonical catalogs, executable graph logic, query tooling, documentation, generated output and planning material.

Without an explicit source-of-truth strategy, the repository risks duplicating knowledge across canonical catalogs, normative specifications and generated documentation.

This ADR defines the authoritative source for every major information type and freezes the repository responsibility model.

Decision

Every information type SHALL have exactly one authoritative source.

Generated, compatibility and transitional files SHALL NOT become authoritative.

No new top-level directory SHALL be introduced without an ADR.

No existing top-level directory SHALL change responsibility without an ADR.

Source Of Truth Matrix

Information Type Authoritative Source
Project identity, vision, mission and principles PROJECT.md
Architecture decisions adr/
Normative framework rules specifications/
Machine-readable validation rules schemas/
Canonical Unified Commerce knowledge catalogs/
Executable graph model graph/
Query runtime queries/
Automation, generators and validators scripts/
Validation scenarios tests/
Human-readable explanation docs/
Published generated site site/
AI working memory and reports .context/
GitHub and agent configuration .github/, .skills/

Project Constitution

PROJECT.md is the Project Constitution.

It defines:

  • project identity
  • vision
  • mission
  • scope
  • non-goals
  • principles
  • lifecycle

PROJECT.md is not business documentation, generated documentation or architecture specification. It is the constitutional reference for why the project exists and how it behaves.

Repository Classes

Class Paths
Project Constitution PROJECT.md
Normative adr/, specifications/
Validation schemas/, tests/
Canonical catalogs/
Executable graph/, queries/, scripts/
Documentation docs/
Generated site/, docs/generated/
Configuration .github/, .skills/, root configuration files
Temporary .context/, caches, local exports

Planning

The former planning/ directory is not part of the frozen canonical repository layout.

Backlog and roadmap management SHOULD move to the issue tracker or another external planning system.

Planning files MUST NOT contain canonical business knowledge, normative architecture or generated documentation.

Removed in: v0.4.

Models Directory

The former models/ directory is removed.

Its content was migrated to catalogs/ and catalogs/legacy/.

The canonical business source of truth is catalogs/.

New business knowledge SHALL NOT be added outside catalogs/.

Generators, validators and query tooling SHALL read from catalogs/.

Removed in: v0.4.

Specifications Documentation

specifications/ is the only authoritative location for normative specifications.

The former docs/specifications/ directory is removed.

The repository SHALL resolve this ambiguity by removing docs/specifications/ or replacing it with generated documentation derived from specifications/.

Decision: remove docs/specifications/.

Removed in: v0.4.

Knowledge Pipeline

The canonical repository pipeline is:

PROJECT.md
    ↓
adr/
    ↓
specifications/
    ↓
schemas/
    ↓
catalogs/
    ↓
validation
    ↓
graph/
    ↓
queries/
    ↓
docs/
    ↓
site/

Documentation MUST NOT bypass this lifecycle.

Generated artifacts are never authoritative.

Repository Layout Freeze

The repository layout is frozen after this ADR.

Allowed changes:

  • adding content under existing directories according to their responsibility
  • adding generated output through approved generators
  • adding validation scenarios under tests/
  • adding ADRs under adr/

Disallowed without a new ADR:

  • new top-level directories
  • responsibility changes for top-level directories
  • new canonical source locations
  • new generated output locations
  • manual edits to generated output

Consequences

  • Future work should focus on canonical catalogs and the executable knowledge model.
  • Repository engineering issues should become rare.
  • planning/, docs/specifications/ and the former model directory were removed in v0.4.
  • Validators and generators must progressively depend on catalogs/, schemas/ and specifications/, not on legacy model files.