Single-use override tokens

When a system has safety checks that can produce blockers, you need a way to override them in the rare cases the check is wrong. --yes or --force is the wrong shape because it bypasses every blocker, leaves no audit trail, and turns "this is risky" into "ignore everything risky." The right shape: a single-use override token, scoped to one blocker, audited on consumption.

The pattern

When the safety check blocks an operation, the user can request an override. The system mints a token tied to the specific blocker (kind, draft id, severity, time), records it in an audit table, and returns it. The user re-runs the operation with the token. The check still runs; if the blocker reappears, the token is consumed against it and the operation proceeds. One token, one consume, one audit row.

--yes confirms acknowledgment of warnings but doesn't bypass blockers. Two separate concepts, two separate mechanisms.

Why the granularity matters

A blanket --force says "I accept all risk for this run." That's almost never what the user means. What they actually mean is "I know this specific check is wrong about this specific thing." The token pattern encodes exactly that. If a new blocker appears that the user didn't see when minting the token, the operation still fails — the token doesn't cover it.

This also gives the audit log teeth. "User overrode blocker X on draft Y at time T" is a precise record. "User used --force on draft Y at time T" tells you nothing about what they were overriding.

What this rules out

• "Session overrides" that turn off a class of checks for some window
• Saving --force defaults in config (anywhere there's persistent state, there's eventual abuse)
• Override tokens that work across operations or expire by time rather than by single use
• Reusing the override mechanism for warnings — warnings are reviewable, blockers are explicit; conflating them breaks both

The complement: warnings are reviewable

The other side of strict-default UX is that warnings should not require ceremony to dismiss. If every minor warning needed an override token, users would mint tokens reflexively and the system would teach them to. The split is what makes the discipline work:

• Warnings: shown, dismissed by reviewing them with --yes
• Blockers: shown, only overridden via single-use tokens, audited on use

This way the user's instinct around --yes ("I read the warnings, proceed") and the user's instinct around override tokens ("the system is wrong about this specific thing") stay clean.

Where this generalizes

Any system with safety checks that occasionally need to be bypassed:

• Linter exceptions (one-time # noqa: rulename per line, not project-wide disable)
• Schema migration guardrails (one approval per dangerous migration, not "skip validation")
• Deploy gates (one approval per deploy with a specific reason, not standing override)
• Code review approval overrides (one acknowledgement per blocking comment, not bypass-merge)

The pattern is: the override exists, the override is granular, the override is audited, and reaching for the override costs more than reading the warning. That last property is what keeps the system honest — if overriding is too easy, the safety check becomes decorative.

See also

• Same-Code-Path Preview — the upstream discipline: don't let the override exist on a parallel path that skips the check entirely
• Mutations Documented Dry-Run First — the doc side: even with override tokens, the docs lead with dry-run
• Mxr — concrete instance: draft_safety_overrides table backs the pattern for the pre-send safety pipeline