TenantAtlas/specs/059-unified-badges/contracts/guardrails.md

Guardrails Contract — Unified Badge System (v1)

This feature enforces a single source of truth for status-like badge semantics (status/health and severity/risk).

What is enforced (v1)

• Status-like badges must not define meaning ad-hoc per page/resource/widget/view.
• Central semantics must be used for status/health and severity/risk signals.

Tag/category chips are out of scope for v1 and are not blocked by these guardrails.

Guard strategy (v1)

Mapping tests

• Each status-like badge domain has automated tests that assert canonical mappings and invariants.
• Invariant example: success/completed must never be represented with warning/attention meaning.

Lightweight repo guard

• A test scans the codebase and flags newly introduced ad-hoc status-like badge semantics patterns.
• The guard is intentionally lightweight (pattern-based) to keep noise low while preventing regression.

Examples of patterns the guard should flag

• Ad-hoc status/severity match blocks inside badge rendering logic for status-like fields.
• Per-resource status badge color maps defined inline on list pages/widgets.
• Custom Blade badge markup for status-like semantics when the central system exists.

The exact patterns are defined by the guard test implementation and may be refined to reduce false positives.