ADR-007: Severity vocabulary — two concepts, one shared palette

Source of truth: docs/adr/007-severity-vocabulary.md (synced at build time — edit the original, not this copy). Status: Accepted (2026-07-18). Pins the suite’s severity language: a single canonical 5-level Severity scale for detections/alerts/cases and every suite-seam payload, kept distinct from VectorFlow’s 3-level Ops alert level for infrastructure monitoring — both rendered from one shared token palette / badge promoted to @veltrosecurity/tokens + @veltrosecurity/ui. Amends nothing in ADR-001/002/003/004; it records a vocabulary decision that the family-convergence wave (shared UI packages) makes load-bearing.

Context

The three products grew two incompatible “severity” vocabularies:

• CHAD and Warden speak a 5-level security scale (critical / high / medium / low / informational) for detections, alerts, and case severity — the standard SOC vocabulary.
• VectorFlow speaks a 3-level scale (info / warning / critical) for pipeline and fleet infrastructure monitoring (metric alert rules) — the standard ops-monitoring vocabulary.

Left implicit, this caused real drift. The word “critical” means different things in different zones; Warden’s severity-badge component carried a comment falsely claiming to track VF’s 3-level tokens; and each app hand-rolled its own badge, so the same severity value could render differently across /vectorflow, /chad/, and /warden/. Worse, the CHAD → Warden Escalation payload (ADR-004 Decision 3, integration B) carries a severity field: once that field is on the wire between services, its allowed values are a contract, not a styling choice.

Two questions had to be settled before the family-convergence wave promotes a shared SeverityBadge into @veltrosecurity/ui: is there one severity scale or two, and what do the shared tokens encode.

Decision 1 — Two concepts, deliberately not merged

There are two distinct concepts, and they stay distinct:

• Severity — the canonical 5-level security scale critical | high | medium | low | informational. It is the single security vocabulary for detections, alerts, and cases, and it is the only vocabulary permitted in suite-seam payloads (the CHAD → Warden escalation, and any future cross-service security-finding payload).
• Ops alert level — VectorFlow’s 3-level infrastructure-monitoring scale info | warning | critical. It describes pipeline/fleet health, never a security finding, and it never crosses a suite seam.

We reject collapsing them into one scale. They answer different questions (“how bad is this security finding?” vs “how unhealthy is this pipeline?”), have different natural cardinalities (5 vs 3), and are authored by different personas (detection engineer vs pipeline engineer). Forcing VF’s infra monitoring onto a 5-level security scale — or diluting the security scale to 3 levels — would make both worse to serve the tidiness of one enum. The overlap in the word “critical” is coincidental, not a shared meaning.

Decision 2 — One shared palette, two badge components

Both concepts render from the same shared token palette promoted to @veltrosecurity/tokens, so a color reads consistently suite-wide, but each concept keeps its own component in @veltrosecurity/ui:

• SeverityBadge — driven by the 5-level Severity scale; used by CHAD and Warden (and any consumer of a seam payload).
• VF’s Ops alert level badge — 3-level, a distinct component drawing from the same token palette.

Sharing the palette (not the component) is what kills the copy-paste badge forks without pretending the two scales are one. The 5-level Severity enum is exported once from @veltrosecurity/tokens; VF’s 3-level ops levels map onto a subset of the same color ramp. Warden’s stale “tracks VF tokens” comment is deleted with its local fork.

Consequences

• The Severity enum is now a wire contract. critical | high | medium | low | informational is fixed for detections, alerts, cases, and seam payloads; changing or extending it is a breaking change to the CHAD → Warden escalation (ADR-004 integration B) and to any product reading it — the reason this is an ADR and not a component-library note. New severity vocabulary is prohibited.
• Ops alert level stays VF-local and 3-level; it must never leak into a seam payload or be relabeled “severity.”
• The shared token palette lands in @veltrosecurity/tokens and the SeverityBadge in @veltrosecurity/ui; per ADR-002 §9 every product takes the design-system minor that ships them, and CHAD/Warden delete their badge forks.
• This decision is hard to reverse. Two products, a cross-service payload, and a shared UI package all encode the 5-level scale; unwinding it later touches the wire format, so it is settled here up front.
• Amends nothing structural in prior ADRs; it makes explicit a vocabulary that ADR-004’s integration matrix already depended on implicitly.