feat(engine): add inline suppression via archgate-ignore comments

docs/public/llms-full.txt

@@ -2993,6 +2993,89 @@ ARCH-006/no-unapproved-deps
 
 7. **Handle missing files gracefully.** If your rule reads a specific file like `package.json`, wrap the read in a try/catch and return early if the file does not exist.
 
+## Opt-out directives
+
+There are two ways to handle exceptions in Archgate: **engine-level suppression** (works with any rule automatically) and **custom rule-level directives** (implemented by the rule author for domain-specific opt-outs).
+
+### Engine-level suppression
+
+Archgate supports inline `archgate-ignore` comments that suppress violations without modifying the rule itself. The engine parses these comments and filters matching violations before reporting.
+
+**Next-line suppression** — suppresses the violation on the immediately following line:
+
+```typescript
+// archgate-ignore ARCH-006/no-unapproved-deps legacy dep, migration planned for Q3
+
+```
+
+**File-level suppression** — suppresses all matching violations anywhere in the file:
+
+```typescript
+// archgate-ignore-file ARCH-005/test-mirrors-src generated file, no manual test
+```
+
+**Multiple rules** — stack comments to suppress more than one rule on the same line:
+
+```typescript
+// archgate-ignore ARCH-006/no-unapproved-deps legacy dep
+// archgate-ignore ARCH-003/use-style-text third-party lib handles colors
+
+```
+
+Consecutive suppression comments all target the first non-suppression line that follows.
+
+The format is `ADR-ID/rule-id` followed by a reason. The reason is **required** — a suppression without a reason is ignored and produces a warning:
+
+```
+[suppression] Suppression for ARCH-006/no-unapproved-deps is missing a reason src/foo.ts:1
+```
+
+Both `//` and `#` comment styles are supported, so suppressions work in TypeScript, JavaScript, YAML, Python, shell scripts, and other file types your rules may scan.
+
+:::tip
+Unused suppression comments (comments that don't match any violation) also produce warnings, helping you clean up stale exceptions as code evolves.
+
+### Custom rule-level directives
+
+For domain-specific opt-outs, rule authors can implement their own comment-based directives inside the `check` function. This pattern gives the rule full control over the directive syntax, placement, and validation.
+
+```typescript
+// In your .rules.ts file:
+async check(ctx) {
+  const files = await ctx.glob("src/components/**/*Connected.tsx");
+
+  for (const file of files) {
+    const content = await ctx.readFile(file);
+
+    // Support opt-out directive at the top of the file
+    if (/^\/\/\s*@no-presentational:/u.test(content.trimStart())) continue;
+
+    // ... rule logic that may report a violation ...
+    ctx.report.violation({
+      message: "Missing presentational component",
+      file,
+      fix: 'Add "// @no-presentational: <reason>" at the top of the file to opt out',
+    });
+  }
+}
+```
+
+The developer opts out by adding the directive to their file:
+
+```typescript
+// @no-presentational: this component only redirects, no UI to render
+
+```
+
+### When to use which
+
+| Approach          | Best for                                         | Who controls it          |
+| ----------------- | ------------------------------------------------ | ------------------------ |
+| `archgate-ignore` | Ad-hoc exceptions for any rule                   | Developer using the rule |
+| Custom directive  | Domain-specific opt-outs with structured reasons | Rule author              |
+
+Use `archgate-ignore` when a developer needs to suppress a one-off violation. Use custom directives when the opt-out is a first-class concept in your rule's domain — for example, marking a component as intentionally unpaired, or a file as auto-generated.
+
 ## Next steps
 
 - [Common Rule Patterns](/examples/common-rule-patterns/) — Copy-pasteable patterns organized by category: dependency management, import restrictions, file structure, code quality, database schema, and architecture boundaries.
@@ -4975,6 +5058,19 @@ interface ViolationDetail {
 
 ---
 
+## Inline suppression
+
+Violations can be suppressed in source code using `archgate-ignore` comments. The engine handles this automatically — rules do not need any special logic.
+
+```typescript
+// archgate-ignore ARCH-006/no-unapproved-deps legacy dep, migration planned
+
+```
+
+A reason is required. File-level suppression uses `archgate-ignore-file`. Stack multiple comments to suppress more than one rule on the same line. See [Opt-out directives](/guides/writing-rules/#opt-out-directives) for full details and custom directive patterns.
+
+---
+
 ## RuleSet
 
 The type used with `satisfies` to type-check your rules object. Export a plain object that conforms to this shape.

docs/src/content/docs/guides/writing-rules.mdx

@@ -301,6 +301,90 @@ ARCH-006/no-unapproved-deps
 
 7. **Handle missing files gracefully.** If your rule reads a specific file like `package.json`, wrap the read in a try/catch and return early if the file does not exist.
 
+## Opt-out directives
+
+There are two ways to handle exceptions in Archgate: **engine-level suppression** (works with any rule automatically) and **custom rule-level directives** (implemented by the rule author for domain-specific opt-outs).
+
+### Engine-level suppression
+
+Archgate supports inline `archgate-ignore` comments that suppress violations without modifying the rule itself. The engine parses these comments and filters matching violations before reporting.
+
+**Next-line suppression** — suppresses the violation on the immediately following line:
+
+```typescript
+// archgate-ignore ARCH-006/no-unapproved-deps legacy dep, migration planned for Q3
+import chalk from "chalk";
+```
+
+**File-level suppression** — suppresses all matching violations anywhere in the file:
+
+```typescript
+// archgate-ignore-file ARCH-005/test-mirrors-src generated file, no manual test
+```
+
+**Multiple rules** — stack comments to suppress more than one rule on the same line:
+
+```typescript
+// archgate-ignore ARCH-006/no-unapproved-deps legacy dep
+// archgate-ignore ARCH-003/use-style-text third-party lib handles colors
+import chalk from "chalk";
+```
+
+Consecutive suppression comments all target the first non-suppression line that follows.
+
+The format is `ADR-ID/rule-id` followed by a reason. The reason is **required** — a suppression without a reason is ignored and produces a warning:
+
+```
+[suppression] Suppression for ARCH-006/no-unapproved-deps is missing a reason src/foo.ts:1
+```
+
+Both `//` and `#` comment styles are supported, so suppressions work in TypeScript, JavaScript, YAML, Python, shell scripts, and other file types your rules may scan.
+
+:::tip
+Unused suppression comments (comments that don't match any violation) also produce warnings, helping you clean up stale exceptions as code evolves.
+:::
+
+### Custom rule-level directives
+
+For domain-specific opt-outs, rule authors can implement their own comment-based directives inside the `check` function. This pattern gives the rule full control over the directive syntax, placement, and validation.
+
+```typescript
+// In your .rules.ts file:
+async check(ctx) {
+  const files = await ctx.glob("src/components/**/*Connected.tsx");
+
+  for (const file of files) {
+    const content = await ctx.readFile(file);
+
+    // Support opt-out directive at the top of the file
+    if (/^\/\/\s*@no-presentational:/u.test(content.trimStart())) continue;
+
+    // ... rule logic that may report a violation ...
+    ctx.report.violation({
+      message: "Missing presentational component",
+      file,
+      fix: 'Add "// @no-presentational: <reason>" at the top of the file to opt out',
+    });
+  }
+}
+```
+
+The developer opts out by adding the directive to their file:
+
+```typescript
+// @no-presentational: this component only redirects, no UI to render
+import { useNavigate } from "react-router";
+```
+
+### When to use which
+
+| Approach          | Best for                                         | Who controls it          |
+| ----------------- | ------------------------------------------------ | ------------------------ |
+| `archgate-ignore` | Ad-hoc exceptions for any rule                   | Developer using the rule |
+| Custom directive  | Domain-specific opt-outs with structured reasons | Rule author              |
+
+Use `archgate-ignore` when a developer needs to suppress a one-off violation. Use custom directives when the opt-out is a first-class concept in your rule's domain — for example, marking a component as intentionally unpaired, or a file as auto-generated.
+
 ## Next steps
 
 - [Common Rule Patterns](/examples/common-rule-patterns/) — Copy-pasteable patterns organized by category: dependency management, import restrictions, file structure, code quality, database schema, and architecture boundaries.

docs/src/content/docs/nb/guides/writing-rules.mdx

@@ -301,6 +301,90 @@ ARCH-006/no-unapproved-deps
 
 7. **Håndter manglende filer elegant.** Hvis regelen din leser en spesifikk fil som `package.json`, pakk lesingen i en try/catch og returner tidlig hvis filen ikke eksisterer.
 
+## Opt-out-direktiver
+
+Det finnes to måter å håndtere unntak i Archgate: **undertrykkelse på motornivå** (fungerer med alle regler automatisk) og **egendefinerte direktiver på regelnivå** (implementert av regelforfatteren for domenespesifikke opt-outs).
+
+### Undertrykkelse på motornivå
+
+Archgate støtter inline `archgate-ignore`-kommentarer som undertrykker brudd uten å endre selve regelen. Motoren analyserer disse kommentarene og filtrerer matchende brudd før rapportering.
+
+**Neste-linje-undertrykkelse** — undertrykker bruddet på den umiddelbart følgende linjen:
+
+```typescript
+// archgate-ignore ARCH-006/no-unapproved-deps legacy-avhengighet, migrering planlagt for Q3
+import chalk from "chalk";
+```
+
+**Filnivå-undertrykkelse** — undertrykker alle matchende brudd hvor som helst i filen:
+
+```typescript
+// archgate-ignore-file ARCH-005/test-mirrors-src generert fil, ingen manuell test
+```
+
+**Flere regler** — stable kommentarer for å undertrykke mer enn én regel på samme linje:
+
+```typescript
+// archgate-ignore ARCH-006/no-unapproved-deps legacy-avhengighet
+// archgate-ignore ARCH-003/use-style-text tredjepartsbibliotek håndterer farger
+import chalk from "chalk";
+```
+
+Sammenhengende undertrykkelseskommentarer sikter alle mot den første ikke-undertrykkelseslinjen etter blokken.
+
+Formatet er `ADR-ID/rule-id` etterfulgt av en begrunnelse. Begrunnelsen er **påkrevd** — en undertrykkelse uten begrunnelse ignoreres og gir en advarsel:
+
+```
+[suppression] Suppression for ARCH-006/no-unapproved-deps is missing a reason src/foo.ts:1
+```
+
+Både `//` og `#` kommentarstiler støttes, slik at undertrykkelser fungerer i TypeScript, JavaScript, YAML, Python, shell-skript og andre filtyper reglene dine kan skanne.
+
+:::tip
+Ubrukte undertrykkelseskommentarer (kommentarer som ikke matcher noen brudd) gir også advarsler, som hjelper deg med å rydde opp i foreldede unntak etter hvert som koden utvikler seg.
+:::
+
+### Egendefinerte direktiver på regelnivå
+
+For domenespesifikke opt-outs kan regelforfattere implementere sine egne kommentarbaserte direktiver inne i `check`-funksjonen. Dette mønsteret gir regelen full kontroll over direktivsyntaksen, plassering og validering.
+
+```typescript
+// I din .rules.ts-fil:
+async check(ctx) {
+  const files = await ctx.glob("src/components/**/*Connected.tsx");
+
+  for (const file of files) {
+    const content = await ctx.readFile(file);
+
+    // Støtt opt-out-direktiv øverst i filen
+    if (/^\/\/\s*@no-presentational:/u.test(content.trimStart())) continue;
+
+    // ... regellogikk som kan rapportere et brudd ...
+    ctx.report.violation({
+      message: "Manglende presentasjonskomponent",
+      file,
+      fix: 'Legg til "// @no-presentational: <begrunnelse>" øverst i filen for å gjøre opt-out',
+    });
+  }
+}
+```
+
+Utvikleren gjør opt-out ved å legge til direktivet i filen sin:
+
+```typescript
+// @no-presentational: denne komponenten bare omdirigerer, ingen UI å rendre
+import { useNavigate } from "react-router";
+```
+
+### Når bruke hva
+
+| Tilnærming            | Best for                                                | Hvem kontrollerer             |
+| --------------------- | ------------------------------------------------------- | ----------------------------- |
+| `archgate-ignore`     | Ad-hoc-unntak for alle regler                           | Utvikleren som bruker regelen |
+| Egendefinert direktiv | Domenespesifikke opt-outs med strukturerte begrunnelser | Regelforfatteren              |
+
+Bruk `archgate-ignore` når en utvikler trenger å undertrykke et engangsbrudd. Bruk egendefinerte direktiver når opt-outen er et førsteklasses konsept i regelens domene — for eksempel å markere en komponent som med vilje uparet, eller en fil som automatisk generert.
+
 ## Neste steg
 
 - [Vanlige regelmønstre](/examples/common-rule-patterns/) -- Kopier-og-lim-inn-mønstre organisert etter kategori: avhengighetshåndtering, importrestriksjoner, filstruktur, kodekvalitet, databaseskjema og arkitekturgrenser.

docs/src/content/docs/nb/reference/rule-api.mdx

@@ -301,6 +301,19 @@ interface ViolationDetail {
 
 ---
 
+## Inline undertrykkelse
+
+Brudd kan undertrykkes i kildekoden ved hjelp av `archgate-ignore`-kommentarer. Motoren håndterer dette automatisk — regler trenger ingen spesiell logikk.
+
+```typescript
+// archgate-ignore ARCH-006/no-unapproved-deps legacy-avhengighet, migrering planlagt
+import chalk from "chalk";
+```
+
+En begrunnelse er påkrevd. Filnivå-undertrykkelse bruker `archgate-ignore-file`. Stable flere kommentarer for å undertrykke mer enn én regel på samme linje. Se [Opt-out-direktiver](/guides/writing-rules/#opt-out-direktiver) for fullstendige detaljer og egendefinerte direktivmønstre.
+
+---
+
 ## RuleSet
 
 Typen brukt med `satisfies` for a typekontrollere regelobjektet ditt. Eksporter et vanlig objekt som samsvarer med denne formen.