Ariel Baseline Lifecycle

ELI5

A baseline is a sealed envelope full of dated photocopies (configuration items) of design docs, code snippets, and diagrams. Once you seal it (freeze), you can verify the seal hasn’t been tampered with by recomputing the hashes inside, but you can’t add or remove pages — you must create a new envelope that supersedes the old one.

Technical Deep Dive

Tables (migration 005_ariel_baselines.sql)

baseline_status is an enum: draft, frozen, superseded, archived.

State Machine

stateDiagram-v2
  [*] --> draft
  draft --> frozen : ariel_baseline_freeze
  frozen --> superseded : new baseline cites it as parent_baseline
  frozen --> archived : explicit archive
  draft --> archived : explicit archive
  superseded --> archived : retention policy
  archived --> [*]

frozen_at is set when status flips to frozen. parent_baseline (a baseline_id, not a UUID) lets a chain of baselines refer back to the one they replace.

Configuration Item Identity

Within a baseline, a CI is uniquely identified by (baseline_id, type, ref) — enforced by uq_ariel_ci_baseline_type_ref. Types observed in the schema header: doc, concept, snippet, diagram, asset. The hash column carries sha256:<hex> so a verify operation can re-hash the source and compare.

Traceo References

ariel_traceo_references carries one row per (baseline_id, traceo_id, relationship) triple. relationship reuses Traceo’s relationship taxonomy — typical values: satisfies, implements, depends_on. This is how a baseline becomes traceable inside the Traceo matrix without storing requirement copies.

ER Sketch

erDiagram
  ARIEL_BASELINES ||--o{ ARIEL_CONFIGURATION_ITEMS : contains
  ARIEL_BASELINES ||--o{ ARIEL_TRACEO_REFERENCES : cites
  ARIEL_BASELINES ||--o{ ARIEL_SYNC_HISTORY : logs
  ARIEL_BASELINES }|..|| ARIEL_BASELINES : parent_baseline
  WORKSPACES ||--o{ ARIEL_BASELINES : owns

MCP Surface

ariel_baseline_create → …_add_ci → …_freeze → …_verify is the canonical path. …_diff(baseline_a, baseline_b) produces a CI-level diff; …_trace projects the references into a per-baseline traceability matrix (independent of get_traceability_matrix).

Key Terms

• CI (Configuration Item) → an entry in ariel_configuration_items; the smallest hashed unit inside a baseline.
• Freeze → terminal state transition that sets frozen_at and locks the CI list.
• Supersede → soft replacement; the new baseline’s parent_baseline points at the old baseline_id.

Q&A

Q: Can I add a CI to a frozen baseline? A: No — the lifecycle is enforced at the service layer. To extend a frozen baseline, create a new draft, copy CIs, add new ones, freeze, and set parent_baseline to the previous baseline_id.

Q: What does ariel_baseline_verify actually check? A: It re-hashes each CI’s source artefact and compares to the stored hash (sha256:<hex>). A mismatch indicates either drift in the underlying source or a tampered DB row.

Q: Where is the JWT-to-Ariel identity bridge? A: ariel_integration/auth_bridge.py maps Traceo’s UserContext to the format Ariel’s library expects, so MCP-authorised callers carry the same identity into Ariel operations.

Examples

A release manager calls ariel_baseline_create(name="ARCH-2026Q2", version="1.0.0"), then ariel_baseline_add_ci for each design doc and diagram. Once review closes, ariel_baseline_freeze flips status to frozen and records frozen_at. A month later, ariel_baseline_diff("ARCH-2026Q2", "ARCH-2026Q3") lists the CIs added, removed, or whose hash changed.