> ## Documentation Index
> Fetch the complete documentation index at: https://tashfiq.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Suppress a Finding

> Record a governed suppression for a false positive or accepted risk, with a reason and expiry.

Suppression is how you keep accepted exceptions visible without letting them disappear. Charter treats suppressions as governance artifacts — they are audited on every scan, not silently honored.

## When to suppress

<CardGroup cols={2}>
  <Card title="Confirmed false positive" icon="check">
    The finding doesn't reflect a real problem in your repo — Charter's detection doesn't apply to your specific setup.
  </Card>

  <Card title="Accepted risk with justification" icon="check">
    The risk is real but intentionally accepted, documented, and has an owner and a time horizon.
  </Card>

  <Card title="Genuine issue not yet addressed" icon="x">
    Don't suppress findings you just haven't gotten around to fixing. Fix them, or leave them in the active findings list until you do.
  </Card>

  <Card title="Score inflation" icon="x">
    Don't suppress to hit a threshold. A suppressed finding still represents real repo state — suppressions don't make problems go away.
  </Card>
</CardGroup>

If you can fix the underlying problem cleanly, do that first.

<Steps>
  <Step title="Run the suppression command">
    The standard suppression path is a time-bounded waiver:

    ```bash theme={null}
    charter suppress AE-CC-001 \
      --reason "Claude hook config lives in a separate infra repo" \
      --expires 90d
    ```
  </Step>

  <Step title="Review what was written">
    `charter suppress` appends an entry to `.charter-suppress.yml`:

    ```yaml theme={null}
    suppressions:
      - rule: AE-CC-001
        reason: Claude hook config lives in a separate infra repo
        expires: 2026-09-07
    ```

    Commit this file — it is part of your repo's governance record, not a local override.
  </Step>

  <Step title="Re-scan to confirm">
    ```bash theme={null}
    charter doctor
    ```

    `AE-CC-001` should no longer appear in the active findings list. It will appear in the "suppressed" section of the scan output instead, so it's still visible.
  </Step>
</Steps>

## Expiry values

| Value        | Meaning                                  |
| ------------ | ---------------------------------------- |
| `30d`        | 30 days from today                       |
| `90d`        | 90 days from today (recommended default) |
| `1y`         | One year from today                      |
| `2026-12-31` | Explicit calendar date                   |
| `permanent`  | No expiry — requires `--approver`        |

<Warning>
  Permanent suppressions require `--approver`. Without it, `AE-SUPPRESS-002` fires as a High finding on every scan — which costs you points and makes the suppression effectively ungoverned.

  ```bash theme={null}
  charter suppress AE-CC-002 \
    --reason "legacy accepted risk" \
    --expires permanent \
    --approver security-team
  ```
</Warning>

A permanent suppression with an approver looks like this in `.charter-suppress.yml`:

```yaml theme={null}
suppressions:
  - rule: AE-CC-002
    reason: legacy accepted risk
    expires: permanent
    approver: security-team
```

## Inline suppression

For single-line, line-anchored findings in source files, you can suppress inline instead of writing to `.charter-suppress.yml`:

<AccordionGroup>
  <Accordion title="Inline suppression syntax">
    Place the directive on the same line as the triggering content, using the file's native comment syntax:

    ```yaml theme={null}
    # charter:ignore AE-ENV-001 reason="mise managed externally for this workspace"
    ```

    ```javascript theme={null}
    // charter:ignore AE-SEC-001 reason="fixture secret for detector test"
    ```

    ```html theme={null}
    <!-- charter:ignore AE-CTX-001 reason="context file lives at monorepo root" -->
    ```

    Supported comment forms: `#`, `//`, `<!-- -->`
  </Accordion>

  <Accordion title="Inline suppression limits">
    Inline suppression does **not** work for:

    * file-level findings (no single line to anchor to)
    * strict JSON configs like `.mcp.json` (no comment syntax)
    * multi-line findings

    For those cases, use `.charter-suppress.yml` as the primary suppression path.
  </Accordion>
</AccordionGroup>

## Governance rules Charter enforces

Charter audits every suppression on each scan:

| Rule                                        | What it checks                           |
| ------------------------------------------- | ---------------------------------------- |
| [`AE-SUPPRESS-001`](/rules/AE-SUPPRESS-001) | Suppression is missing a reason          |
| [`AE-SUPPRESS-002`](/rules/AE-SUPPRESS-002) | Permanent suppression has no approver    |
| [`AE-SUPPRESS-003`](/rules/AE-SUPPRESS-003) | Suppression rate across the repo is high |

A high suppression rate (`AE-SUPPRESS-003`) is informational — it tells you the repo may be muting more than it's fixing. For why suppressions are governed this way and how they affect the score, see [Suppression Governance](/docs/concepts/suppression-governance).

## Good suppression hygiene

* Prefer a real fix when the repo state is genuinely wrong
* Use finite `--expires` windows rather than `permanent`
* Write reasons that explain the decision, not just `"false positive"`
* Add `--approver` for any long-lived accepted risk
* Review `.charter-suppress.yml` periodically — don't let it grow silently

## Next steps

<CardGroup cols={2}>
  <Card title="Suppression Governance" icon="scale" href="/docs/concepts/suppression-governance">
    Why suppressions are audited and how they change the score.
  </Card>

  <Card title="AE-SUPPRESS-002" icon="shield-lock" href="/rules/AE-SUPPRESS-002">
    The approver requirement for permanent waivers.
  </Card>

  <Card title="charter suppress" icon="ban" href="/cli/suppress">
    Every flag the suppress command accepts.
  </Card>

  <Card title="Use charter fix Safely" icon="shield-check" href="/docs/how-to/use-charter-fix-safely">
    Prefer a real fix over a suppression when one is available.
  </Card>
</CardGroup>