feat(auditor): add accepted_warnings suppression support (REQ-357)

Add generic accepted_warnings suppression to the audit pipeline:
- AuditResult gains suppressed field; AuditReport gains suppressed_count
- _SUPPRESSION_ALIASES maps scaffold.yml alias names to check names
- _apply_accepted_warnings marks matching results as suppressed+passed
- run_audit reads accepted_warnings + audit_suppressions from scaffold.yml
- check_ledger_health no longer manually checks audit_suppressions
- run_auto_fix skips suppressed results
- CLI shows ~ icon and (accepted) suffix for suppressed checks
- 4 new tests covering aliases, backward compat, and properties

Co-Authored-By: Oz <oz-agent@warp.dev>

Author: tbitcs

src/specsmith/auditor.py

@@ -23,6 +23,7 @@ class AuditResult:
     passed: bool
     message: str
     fixable: bool = False
+    suppressed: bool = False
 
 
 @dataclass
@@ -37,7 +38,7 @@ def passed(self) -> int:
 
     @property
     def failed(self) -> int:
-        return sum(1 for r in self.results if not r.passed)
+        return sum(1 for r in self.results if not r.passed and not r.suppressed)
 
     @property
     def fixable(self) -> int:
@@ -47,6 +48,39 @@ def fixable(self) -> int:
     def healthy(self) -> bool:
         return self.failed == 0
 
+    @property
+    def suppressed_count(self) -> int:
+        return sum(1 for r in self.results if r.suppressed)
+
+
+# ---------------------------------------------------------------------------
+# Suppression aliases (scaffold.yml accepted_warnings → AuditResult.name)
+# ---------------------------------------------------------------------------
+
+_SUPPRESSION_ALIASES: dict[str, str] = {
+    "scaffold_type_mismatch": "type-mismatch",
+    "ledger_line_threshold": "ledger-size",
+    "open_todo_count": "ledger-open-todos",
+    "ledger_size": "ledger-size",
+}
+
+
+def _apply_accepted_warnings(report: AuditReport, accepted: list[str]) -> None:
+    """Mark audit results matching *accepted* warning names as suppressed.
+
+    Each entry in *accepted* is either a key in ``_SUPPRESSION_ALIASES`` or a
+    direct ``AuditResult.name`` (exact match or prefix match up to ``:``).
+    Matched results are set to ``suppressed=True`` and ``passed=True`` so they
+    no longer count as failures.
+    """
+    resolved: list[str] = [_SUPPRESSION_ALIASES.get(a, a) for a in accepted]
+    for result in report.results:
+        for name in resolved:
+            if result.name == name or result.name.startswith(name + ":"):
+                result.suppressed = True
+                result.passed = True
+                break
+
 
 # ---------------------------------------------------------------------------
 # Governance file existence checks
@@ -386,10 +420,7 @@ def check_ledger_health(root: Path) -> list[AuditResult]:
 
     # Size check — uses configurable threshold (#145)
     threshold = _get_ledger_threshold(root)
-    # Check audit_suppressions for opt-out
-    raw = _read_scaffold_raw(root)
-    suppressed = "ledger_size" in (raw.get("audit_suppressions") or [])
-    if not suppressed and line_count > threshold:
+    if line_count > threshold:
         results.append(
             AuditResult(
                 name="ledger-size",
@@ -1171,6 +1202,15 @@ def run_audit(root: Path) -> AuditReport:
     report.results.extend(check_industrial_artifacts(root))
     report.results.extend(check_derived_artifacts(root))
     report.results.extend(check_cross_repo_dependencies(root))
+
+    # Apply accepted_warnings / audit_suppressions from scaffold.yml (REQ-357)
+    raw = _read_scaffold_raw(root)
+    _accepted: list[str] = list(raw.get("accepted_warnings") or [])
+    # backward-compat: audit_suppressions list (pre-#188 ledger_size suppression)
+    _old_suppressed: list[str] = list(raw.get("audit_suppressions") or [])
+    _accepted = _accepted + _old_suppressed
+    if _accepted:
+        _apply_accepted_warnings(report, _accepted)
     return report
 
 
@@ -1182,7 +1222,7 @@ def run_auto_fix(root: Path, report: AuditReport) -> list[str]:
     fixed: list[str] = []
 
     for result in report.results:
-        if result.passed:
+        if result.passed or result.suppressed:
             continue
 
         # Fix missing required files with minimal stubs

src/specsmith/cli.py

@@ -441,8 +441,14 @@ def audit(fix: bool, project_dir: str) -> None:
     report = run_audit(root)
 
     for r in report.results:
-        icon = "[green]✓[/green]" if r.passed else "[red]✗[/red]"
-        console.print(f"  {icon} {r.message}")
+        if r.suppressed:
+            icon = "[dim]~[/dim]"
+        elif r.passed:
+            icon = "[green]✓[/green]"
+        else:
+            icon = "[red]✗[/red]"
+        msg = r.message + " [dim](accepted)[/dim]" if r.suppressed else r.message
+        console.print(f"  {icon} {msg}")
 
     console.print()
     if report.healthy:

tests/test_auditor.py

@@ -199,3 +199,108 @@ def test_sync_parse_tests_md_preserves_letter_suffix(self, tmp_path: Path) -> No
         assert "TEST-NN-002a" in ids
         assert "TEST-NN-002b" in ids
         assert "TEST-NN-002" not in ids  # must not be truncated
+
+
+# ---------------------------------------------------------------------------
+# REQ-357: accepted_warnings suppression
+# ---------------------------------------------------------------------------
+
+
+class TestAcceptedWarningsSuppression:
+    """Tests for REQ-357 — accepted_warnings suppression in auditor."""
+
+    def test_accepted_warnings_suppresses_type_mismatch(self, tmp_path: Path) -> None:
+        """scaffold_type_mismatch alias should suppress the type-mismatch check."""
+        # Set up a minimal project with a type that will mismatch detection
+        (tmp_path / "AGENTS.md").write_text("# AGENTS\nShort.\n", encoding="utf-8")
+        (tmp_path / "LEDGER.md").write_text("# Ledger\nDone.\n", encoding="utf-8")
+        docs = tmp_path / "docs"
+        docs.mkdir()
+        (docs / "TESTS.md").write_text("# Tests\n", encoding="utf-8")
+        # Use a type that differs from what detect_project will infer.
+        # "backend-frontend" is unlikely to match a near-empty tmp project.
+        (tmp_path / "scaffold.yml").write_text(
+            "name: test\n"
+            "type: backend-frontend\n"
+            "spec_version: 0.10.1\n"
+            "vcs_platform: github\n"
+            "accepted_warnings:\n"
+            "  - scaffold_type_mismatch\n",
+            encoding="utf-8",
+        )
+
+        report = run_audit(tmp_path)
+
+        # Find the type-mismatch result
+        tm_results = [r for r in report.results if r.name == "type-mismatch"]
+        if tm_results:
+            assert tm_results[0].suppressed is True
+            assert tm_results[0].passed is True
+        # The suppressed result must not count as a failure
+        type_mismatch_failures = [
+            r for r in report.results if r.name == "type-mismatch" and not r.passed
+        ]
+        assert len(type_mismatch_failures) == 0
+
+    def test_ledger_line_threshold_suppresses_ledger_size(self, tmp_path: Path) -> None:
+        """ledger_line_threshold alias should suppress ledger-size check."""
+        (tmp_path / "AGENTS.md").write_text("# AGENTS\nShort.\n", encoding="utf-8")
+        big_ledger = "# Ledger\n" + "\n".join(f"Line {i}" for i in range(600))
+        (tmp_path / "LEDGER.md").write_text(big_ledger, encoding="utf-8")
+        (tmp_path / "scaffold.yml").write_text(
+            "name: test\n"
+            "type: cli-python\n"
+            "spec_version: 0.10.1\n"
+            "vcs_platform: github\n"
+            "accepted_warnings:\n"
+            "  - ledger_line_threshold\n",
+            encoding="utf-8",
+        )
+
+        report = run_audit(tmp_path)
+
+        size_results = [r for r in report.results if r.name == "ledger-size"]
+        assert len(size_results) == 1
+        assert size_results[0].suppressed is True
+        assert size_results[0].passed is True
+        # Should not count toward failures
+        assert all(
+            r.passed or r.name != "ledger-size" for r in report.results
+        )
+
+    def test_audit_suppressions_backward_compat(self, tmp_path: Path) -> None:
+        """Old audit_suppressions: [ledger_size] field should still suppress ledger-size."""
+        (tmp_path / "AGENTS.md").write_text("# AGENTS\nShort.\n", encoding="utf-8")
+        big_ledger = "# Ledger\n" + "\n".join(f"Line {i}" for i in range(600))
+        (tmp_path / "LEDGER.md").write_text(big_ledger, encoding="utf-8")
+        (tmp_path / "scaffold.yml").write_text(
+            "name: test\n"
+            "type: cli-python\n"
+            "spec_version: 0.10.1\n"
+            "vcs_platform: github\n"
+            "audit_suppressions:\n"
+            "  - ledger_size\n",
+            encoding="utf-8",
+        )
+
+        report = run_audit(tmp_path)
+
+        size_results = [r for r in report.results if r.name == "ledger-size"]
+        assert len(size_results) == 1
+        assert size_results[0].suppressed is True
+        assert size_results[0].passed is True
+
+    def test_suppressed_count_property(self, tmp_path: Path) -> None:
+        """AuditReport.suppressed_count should reflect the number of suppressed results."""
+        from specsmith.auditor import AuditReport, AuditResult, _apply_accepted_warnings
+
+        report = AuditReport(results=[
+            AuditResult(name="ledger-size", passed=False, message="too big", fixable=True),
+            AuditResult(name="type-mismatch", passed=False, message="mismatch"),
+            AuditResult(name="other-check", passed=True, message="ok"),
+        ])
+        _apply_accepted_warnings(report, ["ledger_line_threshold", "scaffold_type_mismatch"])
+
+        assert report.suppressed_count == 2
+        assert report.failed == 0
+        assert report.healthy is True