Baselines and Architectural Governance

File-based baselines provide defence-grade reproducibility with SHA-256 integrity hashing. Unlike Git tags, baselines survive squash merges and rebases, go through PR review, and work in air-gapped environments.

February 23, 2026

A baseline is a named, immutable reference point that captures the exact state of your architecture at a governance-approved moment. NeoArc stores baselines as JSON files in a .neoarc-baselines/ directory within your workspace, making them version-controlled artefacts that go through the same review process as any other architectural resource.

What a Baseline Contains

Field	Purpose
Version	Semantic version label (e.g. v1.0.0)
Description	Human-readable description of this baseline
Approval ID	External governance reference (e.g. ARB-2024-042)
Governance Links	Links to documentation pages or ADRs
Created By	Author identity from Git configuration
Commit SHA	Full 40-character commit hash pinned at creation time
Approved Resources	Optional list of APIs and schemas explicitly approved in this baseline, each with type, ID, name, and version
Resource Summary	Counts of entities, schemas, endpoints, diagrams, pages
Integrity Hash	SHA-256 computed over all fields in canonical JSON order

Why Not Git Tags?

Git tags are the traditional way to mark release points, but they have significant limitations for architecture governance:

Concern	Git Tags	NeoArc Baselines
Permissions	Require special Git permissions to create/push	Regular files reviewed in PRs, no special permissions
Squash merges	Tags on squashed commits become orphaned	Files survive any merge strategy
Rebases	Tags point to now-invalid commit hashes	Baselines remain valid after rebase
Review process	Tags bypass code review entirely	Baselines go through PR review like any artefact
Air-gapped environments	Require push access to share	Files exist locally, no network needed
Tamper detection	No built-in integrity verification	SHA-256 hash detects any modification
Metadata	Limited to a short message	Rich metadata: approval ID, governance link, resource summary

Creating a Baseline

Governance Workflow

Architecture Review Board

Create a baseline after ARB approval. Link the baseline to the approval ticket via the governance link field.

Drift Monitoring

The drift dashboard measures how far the current state has moved from any baseline. Visual gauges show drift percentage with colour-coded thresholds.

Audit Trail

Baselines are version-controlled files. The Git log shows who created each baseline, when, and the PR that approved it.

Compliance Evidence

For regulated environments, baselines provide verifiable evidence of architectural state at a specific point in time, with integrity hashing to prove they have not been tampered with.

Deep Git Integration

NeoArc wraps Git with architecture-first concepts: checkpoints instead of commits, tracks instead of branches, baselines instead of tags. Semantic diff, conflict resolution, drift analytics, and shelving provide a complete governance workflow.

Drift Dashboard and Analytics

Monitor how far your architecture has drifted from a governance-approved baseline. Visual gauges, hotspot detection, change frequency heatmaps, and a chronological change feed give architects full visibility into architectural evolution.