# Override Directives

Totem's deterministic enforcement layer (`totem lint`) is a strict gatekeeper for your architectural invariants. However, software development is rarely absolute. Edge cases exist, and breaking a rule is sometimes the correct technical decision.

To support this without destroying velocity or codebase integrity, Totem provides a suite of **Override Directives**.

## `// totem-context: <reason>` (Preferred)

This is the **Semantic Overlay**. It is the unified, primary mechanism for overriding Totem's rules everywhere (per ADR-071).

When you use `totem-context:`, you are telling the system: _"I know this breaks a rule, and here is my exact architectural reasoning for why it is necessary."_

- **Rule Engine:** It strictly suppresses the deterministic `totem lint` error for the following block of code.
- **Telemetry:** It writes an `exception` event into the **Trap Ledger**, capturing your reason. If a rule accumulates too many of these contexts, Totem will automatically downgrade the rule via `totem doctor --pr`.
- **Review Layer:** During an AI-powered `totem review`, the LLM reads your context as a semantic hint and incorporates your logic into its evaluation, rather than blindly flagging the violation.

**Example:**

```typescript
// totem-context: We are interacting with a legacy 3rd-party API that requires this mutable global state.
globalThis.__legacyAPIState = {};
```

## `// totem-ignore`

This is a hard suppression directive, modeled after `// eslint-disable`.

- **Behavior:** It suppresses all Totem rules for the entire file.
- **When to use:** Use this _only_ for temporary workarounds, autogenerated code, or vendor files.
- **Requirement:** In a properly governed Totem workspace, a naked `// totem-ignore` will often be flagged by code-review bots unless it is accompanied by a tracking ticket (e.g., `// totem-ignore - tracked in TICKET-123`).

## `// totem-ignore-next-line`

Similar to `totem-ignore`, but strictly scoped to the immediate next line of code.

**Example:**

```typescript
// totem-ignore-next-line - TODO: Refactor this to use the validated schema object (TICKET-456)
const payload = JSON.parse(rawInput);
```

## `// shield-context: <reason>` (Deprecated)

This is the deprecated alias for `totem-context:`.

- **Behavior:** It functions identically to `totem-context:`, but emits a one-time console deprecation warning as of 1.6.0.
- **Status:** **Deprecated.** This directive will be fully removed in `2.0.0`. Please migrate all instances to `// totem-context:`.
