Severity & the One-Way Ratchet

Severity in vybdocs controls what happens when a rule is violated. It has three levels — info, warn, and block — and a critical safety feature called the one-way ratchet: severity can only be increased, never decreased.

The three levels

Severity	Exit code effect	Typical use
info	None — always exit 0	Suggestions, style preferences, informational checks
warn	None by default (exit 0)	Important practices, team conventions, soft requirements
block	Exit 1 — always	Security requirements, compliance mandates, hard rules

info

Use info for guidelines that the team should be aware of but that should never block a PR. Useful for onboarding conventions:

- id: fe-010
  name: prefer-named-exports
  description: Prefer named exports over default exports for tree-shaking
  severity: info
  pattern: "^export default"
  remediation: Use named exports unless this is a Next.js page component.

warn

Use warn for rules that matter and should be addressed, but where blocking every PR would be too aggressive. Violations appear in the check output and are tracked in the Evidence Pack, but do not cause CI failure by default:

- id: dep-001
  name: no-lodash
  severity: warn
  pattern: "from 'lodash'"
  remediation: Use native methods or specific lodash-es imports.

To promote warns to blocking in CI without changing your spec, pass --fail-on-warn:

vyb check --fail-on-warn

block

Use block for hard requirements — security vulnerabilities, compliance mandates, architectural constraints that must never appear in merged code. A single block violation causes vyb check to exit with code 1, preventing PR merge in CI:

- id: sec-001
  name: no-eval
  severity: block
  pattern: "\\beval\\("
  maps-to:
    - framework: soc2
      control: CC7.1

The one-way ratchet

The one-way ratchet is enforced when allow-severity-downgrade: false is set in your spec (the default). It means:

info  →  warn  →  block   ✓  Allowed
block →  warn  →  info    ✗  Rejected with error

This is not just a UX choice — it is a compliance guarantee. If an auditor reviews your Evidence Pack and sees that sec-001 was always block, they can trust that no one (human or AI) softened that rule after the fact.

Why this matters for AI tools

Without the ratchet, an LLM could theoretically be prompted to "relax the eval rule to warn so my code passes." The ratchet makes this impossible at the engine level:

$ vyb mcp proposeRule --id sec-001 --severity warn

  Error: Cannot downgrade severity of sec-001 from block to warn.
  The one-way ratchet is active (allow-severity-downgrade: false).
  Only the spec author can change severity via a signed commit.

The same rejection applies through the Claude Desktop MCP server, the web UI rule editor, and any programmatic API call.

Overriding the ratchet

The ratchet can only be overridden by a human committing directly to the spec file with an explicit flag:

vyb pack --emit --allow-downgrade  # must be run locally, not via MCP

This emits a new pack version with a downgrade recorded in the audit log. The audit log entry is included in all subsequent Evidence Packs.

Severity floor

The severity-floor setting silently skips any rule below the threshold:

settings:
  severity-floor: warn

With this setting, all info-level rules are ignored during vyb check. Useful for production CI pipelines where you want signal-to-noise control, while still running info rules locally.

severity-floor	Rules evaluated
info (default)	All rules
warn	Only warn and block rules
block	Only block rules

Severity in packs

Pre-built packs set sensible defaults for their vertical. When you apply a pack, all rule severities are set to the pack's recommended values. You can override individual rules in your spec:

# Override a pack's default severity
categories:
  security:
    rules:
      - id: sec-001       # defined in the pack at warn
        severity: block   # our project upgrades it to block

This upgrade is valid and is recorded in the Evidence Pack. A downgrade would be rejected.

Summary

Scenario	Allowed
Upgrading warn → block	Yes
Upgrading info → warn	Yes
Downgrading block → warn	No (ratchet)
Downgrading via MCP/UI	No (ratchet)
Downgrading via direct commit + --allow-downgrade	Yes, with audit log

---

Next: Rules Overview