Skip to content

Alpha gate G: consolidated user-facing suppression & false-positive policy page #195

Description

@PhysShell

Agent brief — tier: basic. One PR (Closes #<this>); branch from main. House rules: AGENTS.md.

Goal

Gate G of docs/notes/alpha-readiness.md: suppression is designed and precision behaviour is strong, but the material is scattered. Produce one consolidated user-facing page: how to suppress a finding, and what the analyzer promises about false positives.

Sources of truth (this is consolidation, NOT new design)

  • docs/proposals/P-004-wpf-lifetime-profile.md — the [OwnIgnore("reason")] suppression design.
  • docs/proposals/P-015-configuration-surface.md — project-wide config (draft — present as planned, clearly marked).
  • The precision doctrine on record: "a false positive is worse than a miss"; "no FP from using"; severity tiering (error vs advisory warning).

Deliverable

docs/suppression-and-false-positives.md covering:

  1. The suppression mechanism ([OwnIgnore("reason")]; reason is mandatory by design).
  2. Project-wide configuration (what exists vs what is planned per P-015 — no vaporware presented as shipped).
  3. The FP policy: what the analyzer guarantees, severity tiers (when it errors vs warns), and what a user should do when they believe a finding is wrong.
  4. A single-line link from the README "Suppression & false positives" placeholder section.

Guardrails

  • Do not design new mechanisms; where a gap exists, say "planned (P-015)".
  • Nothing on the page may contradict P-004/P-015 — cross-check before committing.

Done when

The page exists, is linked from README, and a user hitting their first finding can figure out suppression in under a minute. ruff check . clean.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions