feat: inline suppression comments (# docvet: ignore[rule])

[Alberto-Codes]

Summary

Add inline comment-based suppression so users can intentionally silence specific docvet findings on a per-line or per-file basis, similar to # noqa, # type: ignore, and # pragma: no cover.

Motivation

Every mature linter provides an escape hatch for intentional deviations. Users will encounter cases where a finding is correct but the deviation is deliberate — e.g., a function that re-raises without documenting it, or a private helper where Examples aren't warranted despite the config toggle.

Without inline suppression, the only options are:

1. Disable the rule globally (too broad)
2. Add the symbol/file to exclude (clunky)
3. Write a placeholder docstring section (dishonest)

Inline suppression is the precise, self-documenting escape hatch.

Proposed syntax

def transfer(source: Account, target: Account, amount: Decimal) -> Receipt:  # docvet: ignore[missing-raises]
    """Transfer funds between accounts."""
    ...

Variants

# Line-level (suppress specific rules on this symbol)
def foo():  # docvet: ignore[missing-raises]
def bar():  # docvet: ignore[missing-raises,missing-yields]

# Line-level (suppress all rules on this symbol)
def baz():  # docvet: ignore

# File-level (at top of file, suppress for entire file)
# docvet: ignore-file[missing-examples]
# docvet: ignore-file

Design considerations

• Parse suppression comments from AST (ast.get_type_comment or tokenize module for inline comments)
• Match against Finding.rule identifiers
• Respect both line-level and file-level scopes
• Report suppressed findings in verbose mode (transparency)
• Consider --report-suppressed flag for auditing

Phasing suggestion

1. Phase 1: Line-level # docvet: ignore[rule] on the def/class line
2. Phase 2: File-level # docvet: ignore-file[rule]
3. Phase 3: --report-suppressed for auditing

Context

• Identified as a PRD Growth item (listed under "Post-Epic Features")
• Surfaced during BMAD planning audit (2026-03-06) as a missing fundamental
• Every comparable tool has this: ruff (# noqa), mypy (# type: ignore), pylint (# pylint: disable), pytest (# pragma: no cover)