Baselines, Drift Detection and Tamper Resistance

File-based architectural baselines with SHA-256 tamper detection, configurable drift thresholds, hotspot analysis, and structural hashing that detects when governed entities change between reviews.

March 5, 2026

An architecture baseline is a named, immutable reference point that records the approved state of the architecture at a specific moment. Baselines answer the question: "What did the architecture look like when it was last reviewed and approved?" Everything that changes after a baseline is drift, which may be intentional evolution or unintended deviation.

NeoArc implements baselines as JSON files rather than git tags. This design decision has significant implications for enterprise environments where git tag permissions are restricted, squash merges are standard, and audit requirements are strict.

Baseline File Format

Each baseline is stored as a JSON file in the .neoarc-baselines/ directory within your workspace. The file captures everything needed to reproduce and verify the approved state.

Field	Purpose
version	Human-readable version label (e.g. v1.0.0)
description	What this baseline represents
approvalId	External approval reference (e.g. Jira ticket, ARB decision number)
governanceLink	URL to the external governance record
createdBy	Name and email of the person who created the baseline
createdAt	ISO 8601 timestamp
commitSha	Full 40-character git commit hash pinning this baseline to a specific point in history
workspace	Workspace name for monorepo environments
approvedResources	Optional list of APIs and schemas explicitly approved in this baseline, each with resource type, ID, name, and version
resourceSummary	Counts of entities, schemas, endpoints, diagrams, and pages at baseline time
integrityHash	SHA-256 hash computed over all other fields in canonical JSON order

Why File-Based Baselines

Traditional approaches use git tags to mark baselines. NeoArc chose file-based baselines for several practical reasons.

No Special Permissions

Baselines are regular files committed through the normal PR review process. No git tag permissions are needed, which enterprise teams typically restrict on protected branches.

Survive Squash Merges

Git tags on feature branches are lost during squash merges and rebases. File-based baselines survive because they are committed content, not ref metadata.

PR-Reviewable

Creating a baseline produces a reviewable file change that goes through the same approval process as any other architectural artefact. Reviewers can see exactly what is being baselined.

Air-Gap Compatible

Works in environments with no push access to remote repositories. The baseline exists locally as a file and can be transferred alongside the workspace.

Tamper Detection

The integrityHash field is a SHA-256 hash computed over all other fields in the baseline file, serialised in canonical JSON order. When baselines are listed, the hash is recomputed and verified against the stored value.

Drift Dashboard

The drift dashboard measures how far the current architecture has moved from a selected baseline. Select a baseline and the system computes a drift percentage.

Drift Level	Threshold	Visual
Normal	Below 15%	Green gauge bar
Warning	15% to 30%	Amber gauge bar
High	30% to 50%	Red gauge bar
Critical	50% and above	Pulsing red gauge bar

The drift percentage is calculated as: (modified + added + removed) / totalAtBaseline x 100. Thresholds are configurable in the team-shared .neoarc-studio/git-settings.json file.

Hotspot Detection

Beyond the overall drift percentage, the dashboard identifies hotspots: the files that change most frequently. The top 10 most modified files are shown with change counts, unique author counts, and last modified dates. Colour intensity increases with frequency, making it easy to spot areas of high architectural churn that may indicate instability or areas requiring closer governance attention.

Structural Hashing for Governance References

Drift detection also operates at the node level through structural hashing. When you link a governance block to an architectural node (for example, linking a risk block to a model entity), NeoArc records an FNV-1a hash of the node's structurally significant fields.

Node Type	Fields Included in Hash	Fields Excluded
Model Entity	Label, properties (name and type)	ID, derivation paths, projections
Schema	Name/title, extends, fields (name and schema ref)	ID, lineage
Endpoint	Name/title, request body schema ref, response schema refs, path/query params	ID, API ID, header params
Graph Node	Label, properties (name and type)	ID, visual properties (x, y, colour)

Per-Resource Approval

Baselines are project-wide snapshots, but different APIs and schemas ship at different times. When creating a baseline, the dialog shows a checklist of all APIs and schemas that have been modified since the previous baseline. All are ticked by default. The architect can untick resources that are not formally approved in this baseline.

This distinction matters for impact analysis. If a REST API was approved at v1 in an earlier baseline, and a later baseline only approves a webhook while the REST API has in-progress changes, impact analysis for the REST API compares against the earlier baseline where it was last approved. Each resource is tracked independently.

Baseline Comparison

You can compare any two baselines using their pinned commit SHAs. The comparison uses the semantic diff engine to produce an architectural change set: resources added, removed, modified, and renamed, with each change classified as structural or cosmetic. This shows exactly how the architecture evolved between two approved states.