Configuring clash rules

For Site admin / HSE / site manager

Your role

Clash policy — what counts as a clash, how severe it is, and who gets told — is configured in Settings → Rules → Clash. It is gated to the canManagePermitConfig band (SiteMembership roles HSE, admin, site manager); a plain coordinator can triage clashes but not author the rules, because this is permit-aware safety policy.

Policy lives on rules. A site is never blank — it ships with a seeded permit catalogue and a set of seeded ClashRules the moment it is created. Each rule says what counts as a clash (its conditions) and how severe; a rule may additionally carry an optional permit matrix that refines which permit combinations it fires for, and at what severity. You edit rules directly — the full conditions are always visible, never hidden behind a projection.

The surface

Open Settings → Rules → Clash. You see the rule list — every clash rule for the site, each showing its severity, the entity types it matches, and its conditions. From a rule you can:

1. Edit the rule — its entity scope, conditions and severity.
2. + Matrix (permit-config band) — expand a rule's optional permit-code × permit-code grid in place. Click a cell to cycle clear → red → amber → off: red/amber fire at that severity for that permit pair, off suppresses it, clear falls back to the rule's own severity. A floor control (*|*) sets what unlisted pairs do — off makes the matrix an allowlist (only the cells you turn on fire), inherit fires everything at the rule's base severity. A matrix badge marks rules that carry one.

The permit catalogue is the grid's axes, so define it first (in the permits panel). The re-runnable onboarding wizard in the permits panel still sequences catalogue → guided matrix → consequences for first-time setup.

Setting a cell

Each cell / the baseline takes one of four severities:

Severity	Meaning
Inherit (None)	No rule of your own here — the cell falls back to the Any × Any default (or to no clash). Shown dimmed.
Amber	A warning-level clash.
Red	A critical clash.
Off	Suppress this clash for your site — see below.

For Amber/Red you can also enter a proximity distance (metres) and attach a consequence. Leaving the distance untouched keeps the site's configured threshold (the same $site default the seeds use) — so a quick severity edit never silently loosens a seeded red threshold.

How many clashes a pair produces

This is the one concept worth understanding, because it is what makes the matrix predictable. Every distinct hazard between two tokens surfaces as its own clash. If two workers are too close and carry a conflicting pair of permits, you see both — the proximity clash and the permit-conflict clash. A worker carrying two permits (say Hot Works and Confined-Space) next to one carrying two others can trip several permit cells at once, and each surfaces. Nothing hides a genuinely different hazard behind a "more important" one.

Only one thing is ever merged: the same hazard at two severities. The baseline proximity rule ships as a looser amber band and a tighter red band; when both apply, you see only the red (the amber would be redundant). That is the single collapse — a looser amber is suppressed by the red of the same shape, never by a different hazard.

Two more rules decide which version of one hazard you see:

• A specific cell overrides the broad Any × Any of the same hazard. Author a Worker × Crane cell and it takes precedence over the carrier-agnostic default — even when you set it lower, because an override you author wins (a deliberate downgrade is honoured).
• Your per-site override beats the seeded default it forks — editing a seeded cell (even to a lower severity) takes effect for your site without changing anyone else's.

So: author a specific pair's cell to treat it differently from the Any × Any default; raise the Any × Any baseline to make everything stricter; and trust that a distinct permit hazard is never swallowed by the proximity rule (or vice-versa). The display always equals what the engine will actually emit.

Why a red is never hidden behind an amber. Within one hazard, the engine ranks severity above any internal priority number, so you can't make an amber "win" over a red of the same shape by a back-door priority (the #652 fix). And across hazards there is nothing to hide behind — each distinct hazard surfaces on its own (the 2026-06-30 correction). (ADR 2026-06-29-permit-aware-clash-matrix-and-consequences, D8 + its two corrections.)

Inheritance and overrides (Any × Any)

Hazards are mostly carrier-agnostic, so you author the Any × Any tier once and every specific pair inherits it. A specific pair only needs an override on the cells that genuinely differ by carrier. An inherited cell renders dimmed; an authored one renders solid. Overriding a seeded global cell forks a per-site copy — the global seed is left untouched, so other sites are unaffected, and the fork clones the seed's safety predicates so it can never loosen a seeded threshold.

Suppression — turning a seeded hazard Off

Sometimes a seeded clash genuinely doesn't apply to your site. Setting a cell to Off suppresses it: the engine still recognises the pair but emits no clash there, for your site only. Because turning a seeded hazard off is a deliberate loosening, the UI asks you to confirm first, and the action is gated to canManagePermitConfig.

Suppression is scoped and safe:

• It is per-site — it never affects another site or the global seed.
• It silences only that hazard. Switching the proximity baseline off never hides a distinct permit hazard on the same pair — that still surfaces, because it is a different hazard.
• It only ever silences a pair that would clash — it is not a blanket mute.

To restore the seeded behaviour, set the cell back to Inherit. (Note: disabling a rule is not the same as suppression — a disabled rule is invisible and the seed simply keeps firing; Off is the deliberate, visible silence.)

Consequences — who gets told

On any Amber/Red cell you can attach a consequence: when this clash is detected, notify the coordinators of the firms actually in the clash (the default, dynamic audience), by in-app and/or email. One consequence works for every instance of that clash regardless of which firms collide. The consequence is owned by its matrix cell; it shows read-only (with a link back) in the generic notification-rules screen, so there is only ever one place to edit it.

What happens after you save

Your policy drives detection immediately — clash rules need no deploy. From there, clashes surface to people (notifications, tasks, and the noticeboard) and carry a small lifecycle: an imminent badge as a planned clash's window approaches, an escalated marker when an amber worsened to red, and an "Occurred unresolved" noticeboard section for clashes whose window passed while still un-triaged — showing the last fortnight red-first, with a count line ("2 red · 41 amber · 12.4K older") that keeps the full unresolved history represented without listing it. How that surfacing reaches people is covered in How activity reaches people.