[CI]: Add flake8 local plugin enforcing the async naming convention

.flake8

@@ -0,0 +1,27 @@
+[flake8]
+# Flake8 runs ONLY the RAMPART local plugin. Every general-purpose check
+# (pycodestyle, pyflakes, mccabe) is ruff's job, so selecting just RMP keeps
+# the two linters from ever reporting the same problem twice.
+select = RMP
+
+# extend-exclude, not exclude, so flake8's defaults (__pycache__, .tox, .eggs)
+# are kept rather than replaced.
+extend-exclude = .venv,build,dist
+
+# Baseline of pre-existing violations, recorded so the rule can be enforced
+# from day one without a large mechanical rename in the same change. Each
+# entry is removed by the commit that fixes the file. Do not add new entries.
+per-file-ignores =
+    rampart/core/execution.py:RMP001
+    rampart/core/injection.py:RMP001
+    rampart/evaluators/llm_judge.py:RMP001
+    rampart/pyrit_bridge/llm_bridge.py:RMP001
+    rampart/pytest_plugin/_collection.py:RMP001
+    rampart/surfaces/onedrive.py:RMP001
+    tests/*:RMP001
+
+[flake8:local-plugins]
+extension =
+    RMP = flake8_rampart:RampartChecker
+paths =
+    ./tools

.github/instructions/coding-standards.instructions.md

@@ -53,6 +53,7 @@ Use parenthesized multi-line imports when importing 3+ names from the same modul
 - **MANDATORY**: All async functions and methods MUST end with `_async` suffix
 - This applies to ALL async functions without exception
 - **Exception**: Dunder methods (`__aenter__`, `__aexit__`, etc.) follow Python's protocol naming and are exempt
+- Enforced by `RMP001` (see [Automated Enforcement](#automated-enforcement))
 
 ```python
 # CORRECT
@@ -603,4 +604,30 @@ Before committing code, ensure:
 
 ---
 
+## Automated Enforcement
+
+| Convention | Code | Enforced by |
+|---|---|---|
+| Async `_async` suffix | `RMP001` | `tools/flake8_rampart.py`, a flake8 local plugin |
+
+### Async naming (`RMP001`)
+
+No ruff rule can require a name suffix, and ruff has no plugin system, so this
+rule is a [flake8 local plugin][flake8-local]. It needs no packaging:
+`.flake8` points flake8 at `tools/`, and `select = RMP` ensures flake8 runs
+*only* this check, leaving every general-purpose rule to ruff.
+
+Suppress with a same-line `# noqa: RMP001` and a short justification. Note the
+syntax: `# ruff: ignore[...]` is this repository's convention for ruff rules,
+while `# noqa:` is reserved for an RMP code (e.g., `RMP001`), which flake8
+rather than ruff reads. `RMP001` is listed in `[tool.ruff.lint] external` so
+that ruff's `RUF102` accepts it instead of rejecting it as an unknown code.
+
+`.flake8` carries a `per-file-ignores` baseline of files that predate the rule.
+Those entries are removed as the files are fixed; do not add new ones.
+
+[flake8-local]: https://flake8.pycqa.org/en/latest/user/configuration.html#using-local-plugins
+
+---
+
 **Remember**: Clean code is written for humans to read. Make your intent clear and your code self-documenting.

.github/workflows/ci.yml

@@ -44,6 +44,9 @@ jobs:
       - name: Ruff format check
         run: uv run ruff format --check .
 
+      - name: RAMPART conventions (flake8-rampart)
+        run: uv run flake8
+
       - name: ty
         run: uv run ty check
 

.pre-commit-config.yaml

@@ -14,3 +14,12 @@ repos:
       language: system
       types: [python]
       pass_filenames: false
+    - id: flake8-rampart
+      name: flake8-rampart
+      entry: uv run flake8
+      language: system
+      # flake8 scans its whole configured scope, so trigger on any Python file
+      # (mirroring the ty hook above) plus the config itself. `types` is omitted
+      # so that .flake8, which is not Python, still triggers the hook.
+      files: (\.py$|^\.flake8$)
+      pass_filenames: false

docs/contributing/code-style.md

@@ -8,11 +8,12 @@ RAMPART enforces a consistent code style through automated tooling and documente
 |------|---------|-----------------|
 | [Ruff](https://docs.astral.sh/ruff/) | Linting and formatting | `pyproject.toml` `[tool.ruff.*]` |
 | [ty](https://github.com/astral-sh/ty) | Static type checking | `pyproject.toml` `[tool.ty]` |
+| [flake8](https://flake8.pycqa.org/) | For project conventions Ruff cannot express | `.flake8`, `tools/flake8_rampart.py` |
 | [pre-commit](https://pre-commit.com/) | Git hooks for automated checks | `.pre-commit-config.yaml` |
 
 ### Running Checks
 
-Pre-commit is the primary entry point — it runs Ruff (lint + format) and ty in one command:
+Pre-commit is the primary entry point. It runs Ruff (lint + format), ty, and the RAMPART convention check in one command:
 
 ```bash
 # Install the Git hook once (optional, runs on every commit)
@@ -33,6 +34,7 @@ A few details worth knowing:
 
 - **Ruff** is configured with `select = ["ALL"]`. Test files have relaxed rules (no docstrings, no type annotations, magic values allowed) via `per-file-ignores` in `pyproject.toml`.
 - **ty** targets Python 3.11 — every function needs complete parameter and return type annotations.
+- **flake8** runs only `RMP` codes (`select = RMP` in `.flake8`), so it never overlaps Ruff. Suppress an RMP code with `# noqa: <CODE>` (e.g., `# noqa: RMP001`); Ruff rules use `# ruff: ignore[rule-name]`.
 
 
 ## Key Conventions
@@ -60,7 +62,7 @@ async def send_request_async(self, *, payload: str) -> Response: ...
 async def send_request(self, *, payload: str) -> Response: ...
 ```
 
-Dunder methods (`__aenter__`, `__aexit__`) are exempt.
+Dunder methods (`__aenter__`, `__aexit__`) are exempt. Enforced by `RMP001`.
 
 ### Keyword-Only Arguments
 
@@ -157,11 +159,10 @@ Before committing, run pre-commit — it covers everything the automated tooling
 uv run pre-commit run --all-files
 ```
 
-This runs Ruff (linting + formatting) and ty (type checking), which together enforce the copyright header, type annotations, log formatting, import organization, and most other conventions on this page.
+This runs Ruff (linting + formatting), ty (type checking), and flake8 (`RMP` codes), which together enforce the copyright header, type annotations, log formatting, import organization, the `_async` suffix, and most other conventions on this page.
 
 A few rules are **not** caught by tooling and still need a human eye:
 
-- [ ] All async functions end with `_async`
 - [ ] Functions with more than one parameter use keyword-only arguments (`*`)
 - [ ] `Enum` / `StrEnum` is used instead of `Literal` for predefined choices
 - [ ] PyRIT imports are lazy (inside functions), not module-level

docs/contributing/development-setup.md

@@ -62,7 +62,7 @@ Install the project dependencies using uv:
 uv sync
 ```
 
-`uv sync` installs the project in editable mode and includes the default `dev` group from `pyproject.toml` — ruff, ty, pytest-cov, pytest-xdist, and pre-commit — into a virtual environment managed by uv.
+`uv sync` installs the project in editable mode and includes the default `dev` group from `pyproject.toml` (ruff, ty, flake8, pytest-cov, pytest-xdist, and pre-commit) into a virtual environment managed by uv.
 
 If you also plan to build the documentation locally, include the `docs` group:
 

pyproject.toml

@@ -51,6 +51,7 @@ rampart = "rampart.pytest_plugin.plugin"
 
 [dependency-groups]
 dev = [
+    "flake8>=7.3.0",
     "hatch-vcs>=0.5.0",
     "hatchling>=1.30.1",
     "pre-commit>=4.5.1",
@@ -89,7 +90,7 @@ show_missing = true
 skip_empty = true
 
 [tool.pytest.ini_options]
-pythonpath = ["scripts"]
+pythonpath = ["scripts", "tools"]
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "session"
 markers = [
@@ -116,10 +117,17 @@ ignore = [
     "docstring-extraneous-exception", # Allow extraneous exceptions in docstrings to deliberately document the caller-visible contract, even if they propagate from a delegated callee.
 ]
 
+# RMP comes from the flake8 local plugin in tools/. Declaring it here stops
+# RUF102 (invalid-rule-code) from rejecting `# noqa: RMPXXX` as unknown.
+external = ["RMP001"]
+
 [tool.ruff.lint.per-file-ignores]
 "scripts/hatch_build.py" = [
   "implicit-namespace-package", # Top-level build hook
 ]
+"tools/flake8_rampart.py" = [
+  "implicit-namespace-package", # flake8 imports it as a top-level module
+]
 "tests/**" = [
   "any-type",                                          # no type annotations needed
   "assert",                                            # assert is pytest's API
@@ -170,10 +178,10 @@ max-args = 10
 
 [tool.ty.environment]
 python-version = "3.11"
-extra-paths = ["scripts"]
+extra-paths = ["scripts", "tools"]
 
 [tool.ty.src]
-include = ["rampart", "tests", "scripts"]
+include = ["rampart", "tests", "scripts", "tools"]
 
 [tool.uv.sources]
 pyrit = { git = "https://github.com/microsoft/PyRIT", rev = "6dc8b94139757390286bbce7d53c1f7e58e66e29" } # v0.13.0

tests/unit/tools/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.

tests/unit/tools/test_flake8_rampart.py

@@ -0,0 +1,99 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Tests for the flake8-rampart local plugin (RMP001)."""
+
+from __future__ import annotations
+
+import ast
+import subprocess  # ruff: ignore[suspicious-subprocess-import]
+import sys
+from pathlib import Path
+
+import pytest
+from flake8_rampart import RampartChecker
+
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+
+
+def _messages(source: str) -> list[str]:
+    """Return the messages the checker reports for a source snippet."""
+    return [msg for _, _, msg, _ in RampartChecker(ast.parse(source)).run()]
+
+
+class TestAsyncSuffixRule:
+    def test_flags_async_function_without_suffix(self) -> None:
+        (message,) = _messages("async def fetch(): ...")
+        assert message.startswith("RMP001")
+        assert "`fetch`" in message
+
+    def test_accepts_async_function_with_suffix(self) -> None:
+        assert _messages("async def fetch_async(): ...") == []
+
+    def test_ignores_sync_function(self) -> None:
+        assert _messages("def fetch(): ...") == []
+
+    def test_exempts_dunder(self) -> None:
+        assert _messages("async def __aenter__(self): ...") == []
+
+    def test_flags_method_inside_class(self) -> None:
+        source = "class A:\n    async def fetch(self): ...\n"
+        assert len(_messages(source)) == 1
+
+    def test_flags_nested_function(self) -> None:
+        source = "def outer():\n    async def inner(): ...\n"
+        assert len(_messages(source)) == 1
+
+    def test_reports_position_of_definition(self) -> None:
+        checker = RampartChecker(ast.parse("\n\nasync def fetch(): ..."))
+        ((line, col, _, _),) = checker.run()
+        assert (line, col) == (3, 0)
+
+
+@pytest.mark.slow
+class TestPluginWiring:
+    """Guard against the plugin silently failing to load.
+
+    ``flake8 --select=RMP`` exits 0 when no plugin owns the ``RMP`` prefix, so
+    a broken registration would disable the rule with no visible error. These
+    tests run the repository's real ``.flake8`` configuration to prove
+    otherwise.
+    """
+
+    def _run_flake8(self, target: Path) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true]
+            [sys.executable, "-m", "flake8", str(target)],
+            cwd=_REPO_ROOT,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+
+    def test_reports_violation_through_flake8(self, tmp_path: Path) -> None:
+        target = tmp_path / "sample.py"
+        target.write_text("async def fetch():\n    pass\n", encoding="utf-8")
+
+        result = self._run_flake8(target)
+
+        assert result.returncode == 1
+        assert "RMP001" in result.stdout
+
+    def test_honors_noqa_through_flake8(self, tmp_path: Path) -> None:
+        target = tmp_path / "sample.py"
+        target.write_text(
+            "async def fetch():  # noqa: RMP001\n    pass\n",
+            encoding="utf-8",
+        )
+
+        result = self._run_flake8(target)
+
+        assert result.returncode == 0, result.stdout
+
+    def test_runs_no_rules_other_than_rmp(self, tmp_path: Path) -> None:
+        """``select = RMP`` keeps pycodestyle and pyflakes off; that is ruff's job."""
+        target = tmp_path / "sample.py"
+        target.write_text("import os\nx=1\n", encoding="utf-8")
+
+        result = self._run_flake8(target)
+
+        assert result.returncode == 0, result.stdout

tools/flake8_rampart.py

@@ -0,0 +1,69 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Flake8 plugin for RAMPART conventions that ruff cannot express.
+
+Registered as a flake8 *local plugin*: see the ``[flake8:local-plugins]``
+section of ``.flake8``. Local plugins need no packaging or installation:
+flake8 adds ``tools/`` to ``sys.path`` and imports this module directly.
+
+Rules:
+    RMP001: Async functions must be named with an ``_async`` suffix.
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, ClassVar
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+RMP001 = "RMP001 async function `{name}` must be named with an `_async` suffix"
+
+
+def _is_dunder(name: str) -> bool:
+    """Return whether a name follows Python's ``__dunder__`` convention.
+
+    Args:
+        name (str): The function name to test.
+
+    Returns:
+        bool: True for names like ``__aenter__`` that Python itself defines.
+    """
+    return name.startswith("__") and name.endswith("__")
+
+
+class RampartChecker:
+    """Flake8 checker enforcing RAMPART's async naming convention."""
+
+    name: ClassVar[str] = "flake8-rampart"
+    version: ClassVar[str] = "1.0.0"
+
+    def __init__(self, tree: ast.AST) -> None:
+        """Store the module AST supplied by flake8.
+
+        Args:
+            tree (ast.AST): Parsed syntax tree for the file under check.
+        """
+        self._tree = tree
+
+    def run(self) -> Iterator[tuple[int, int, str, type]]:
+        """Yield a violation for every async function missing the suffix.
+
+        Yields:
+            tuple[int, int, str, type]: Line, column, message, and checker
+                type, in the 4-tuple shape flake8 expects.
+        """
+        for node in ast.walk(self._tree):
+            if not isinstance(node, ast.AsyncFunctionDef):
+                continue
+            # Dunders implement Python protocols; their names are not ours to choose.
+            if _is_dunder(node.name) or node.name.endswith("_async"):
+                continue
+            yield (
+                node.lineno,
+                node.col_offset,
+                RMP001.format(name=node.name),
+                type(self),
+            )