# Severity Model

Use this model when reporting findings for `agent-docs` audits, consistency checks, repo-alignment reviews, or post-change verification.

## Levels

- `blocking`: the current document graph or wording is unsafe to follow. The agent is likely to route incorrectly, guess through ambiguity, or apply conflicting rules.
- `major`: the docs are still usable, but the current state creates significant adherence risk, maintenance cost, or fact drift that should be fixed soon.
- `minor`: the issue is real but localized. It does not usually break routing or authority outright, yet it increases noise, review cost, or future drift risk.
- `observation`: useful context, tradeoff notes, or follow-up ideas that are not defects by themselves.

## Typical Mapping

- `blocking`
  - duplicate authority with no explicit tie-break
  - equally specific sibling docs that both explicitly apply
  - unreachable active child doc
  - stale references after a refactor
- `major`
  - high-noise secondary router behavior
  - missing `Authority` or `Classification Authority` where required
  - must-fix repo drift
  - structure that exceeds routing-depth or out-degree budgets and now needs refactor
- `minor`
  - vague `Applies To` wording
  - vague `Authority` wording that still has some usable anchor
  - wording drift that does not yet misstate repository facts
  - structure warnings that are notable but still acceptable for now
- `observation`
  - acceptable tradeoffs
  - optional cleanup ideas
  - residual risks after no concrete findings

## Reporting Rule

- Order findings by severity first, then by impact within the same severity.
- Do not inflate style preferences into `major` or `blocking`.
- If a finding could fit two levels, choose the higher one only when the current wording or structure is likely to cause a real routing, authority, or verification mistake.