python-vibe-guard 0.12.0__tar.gz → 0.12.2__tar.gz

{python_vibe_guard-0.12.0 → python_vibe_guard-0.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-vibe-guard
-Version: 0.12.0
+Version: 0.12.2
 Summary: Runtime anti-pattern scanner for async Python — detects what AI-generated code gets wrong
 License: MIT
 Keywords: async,linter,fastapi,asyncio,static-analysis
@@ -79,7 +79,7 @@ Patterns that introduce data races, swallowed errors, or runaway loops under con
 | PYVIBE-020 | `put_nowait()` without `asyncio.QueueFull` handler | any | `QueueFull` propagates unhandled; item is silently lost on bounded queues |
 
 **Severity notes:**
-- PYVIBE-005: `CRITICAL` — checks per-task decorator arguments only. **If your project sets a global `task_time_limit` via `app.conf.task_time_limit`, `app.conf.update(...)`, or in `celeryconfig.py` / `settings.py`, tasks already covered by that global limit will still be flagged.** Add per-task limits (self-documenting, immune to config drift) or suppress with `# noqa: PYVIBE-005`.
+- PYVIBE-005: `CRITICAL` — checks per-task decorator arguments only. **If your project sets a global `task_time_limit` via `app.conf.task_time_limit`, `app.conf.update(...)`, or in `celeryconfig.py` / `settings.py`, tasks already covered by that global limit will still be flagged.** Add per-task limits (self-documenting, immune to config drift) or suppress with `# pyvibe: ignore PYVIBE-005` on the task's `def` line.
 - PYVIBE-009: `CRITICAL` in production files; automatically downgraded to `WARNING` in test files (`test_*.py`, `*_test.py`, `tests/`). **Context matters:** `open()` in a hot-path request handler blocks all concurrent coroutines (CRITICAL); `open()` in a startup/lifespan function runs before requests are served and has zero practical impact. The rule cannot distinguish these contexts via AST — if you use `open()` in an `async def` lifespan or one-time initializer, the idiomatic fix is to use plain `def` instead (FastAPI's own docs do this), which avoids the flag entirely.
 - PYVIBE-017: bare `except` → `CRITICAL` (catches `KeyboardInterrupt`/`SystemExit`); `except Exception` with empty body → `WARNING`. Specific exceptions (`except ValueError: pass`) are not flagged.
 - PYVIBE-013 in test files: automatically downgraded to `WARNING` in files matching `test_*.py`, `*_test.py`, or paths under `tests/` — exceptions should propagate for assertions in test code.
@@ -181,6 +181,11 @@ python -m pyvibe src/ --baseline          # only reports findings NOT in the bas
 # Show suppressed findings (inline comments + pyvibe.toml) alongside the report
 python -m pyvibe src/ --verbose
 
+# Audit inline suppressions: justification coverage + orphaned (unused) suppressions
+python -m pyvibe audit src/
+python -m pyvibe audit src/ --json
+python -m pyvibe audit src/ --fail-on-unused --fail-on-unjustified
+
 # Exit code: 0 = clean, 1 = violations found, 2 = path error
 ```
 
@@ -314,6 +319,14 @@ conn = sqlite3.connect(...)              # suppressed — always targets the nex
 `pyvibe:` is case-insensitive. A directive with no recognizable `PYVIBE-XXX` id is ignored
 (treated as a regular comment).
 
+Add an optional justification after `--` — it's free text, stored and shown in `pyvibe audit`:
+
+```python
+conn = sqlite3.connect(...)  # pyvibe: ignore PYVIBE-008 -- legacy sqlite wrapper
+# pyvibe: ignore-next-line PYVIBE-008 -- startup only
+conn = sqlite3.connect(...)
+```
+
 For project-wide rules, add a `pyvibe.toml` next to your code (python-vibe-guard walks up
 from the scan target to find it, same convention as `pyproject.toml`):
 
@@ -346,6 +359,44 @@ Add `--verbose` to see exactly what was suppressed and why:
     PYVIBE-019 legacy.py:81 (config)
 ```
 
+### `pyvibe audit`
+
+Audits every inline `# pyvibe: ignore` comment in a codebase: how many carry a justification,
+and how many are **orphaned** — the rule they name never actually fires on the target line,
+usually because the underlying code changed since the suppression was added.
+
+```
+$ pyvibe audit src/
+
+Suppressions audit
+──────────────────
+Total suppressions: 12
+With justification: 9 (75%)
+Without justification: 3
+Unused (no violation found): 2
+
+By rule:
+PYVIBE-008   5
+PYVIBE-019   4
+PYVIBE-003   3
+
+Unused suppressions:
+app/legacy.py:41  # pyvibe: ignore PYVIBE-008
+
+Without justification:
+models/db.py:88  # pyvibe: ignore PYVIBE-019
+```
+
+- `--json` — machine-readable output (`total`, `with_justification`, `without_justification`,
+  `unused`, `by_rule`, `unused_suppressions`, `without_justification_suppressions`).
+- `--fail-on-unused` — exit `1` if any orphaned suppression is found.
+- `--fail-on-unjustified` — exit `1` if any suppression is missing a justification.
+- `--max-unused N` — exit `1` if more than `N` orphaned suppressions are found.
+- `--exclude DIR` — same directory-exclusion convention as `pyvibe scan`.
+
+With no flags, `pyvibe audit` is purely informational (exit `0`) — the flags above are what
+you wire into CI to enforce a justification/cleanup policy over time.
+
 ---
 
 ## CI/CD integration
@@ -400,7 +451,7 @@ Add to your `.pre-commit-config.yaml`:
 ```yaml
 repos:
   - repo: https://github.com/Joaquinriosheredia/python-vibe-guard
-    rev: v0.7.0
+    rev: v0.12.2
     hooks:
       - id: python-vibe-guard
 ```
@@ -443,7 +494,13 @@ python -m pytest tests/ -v
 python tests/test_rules.py
 ```
 
-309 tests: true positives + false-positive guards for every rule, plus SARIF output, `pyvibe explain`, `pyvibe review`, baseline mode, and suppressions (inline comments + pyvibe.toml) coverage.
+331 tests: true positives + false-positive guards for every rule, plus SARIF output, `pyvibe explain`, `pyvibe review`, baseline mode, suppressions (inline comments + pyvibe.toml), and `pyvibe audit` (justifications + orphan detection) coverage.
+
+---
+
+## Documentation
+
+- [research/public-findings.md](research/public-findings.md) — real findings reported to public open source projects, including confirmed cases and cases where context changed the outcome.
 
 ---
 

{python_vibe_guard-0.12.0 → python_vibe_guard-0.12.2}/README.md

@@ -63,7 +63,7 @@ Patterns that introduce data races, swallowed errors, or runaway loops under con
 | PYVIBE-020 | `put_nowait()` without `asyncio.QueueFull` handler | any | `QueueFull` propagates unhandled; item is silently lost on bounded queues |
 
 **Severity notes:**
-- PYVIBE-005: `CRITICAL` — checks per-task decorator arguments only. **If your project sets a global `task_time_limit` via `app.conf.task_time_limit`, `app.conf.update(...)`, or in `celeryconfig.py` / `settings.py`, tasks already covered by that global limit will still be flagged.** Add per-task limits (self-documenting, immune to config drift) or suppress with `# noqa: PYVIBE-005`.
+- PYVIBE-005: `CRITICAL` — checks per-task decorator arguments only. **If your project sets a global `task_time_limit` via `app.conf.task_time_limit`, `app.conf.update(...)`, or in `celeryconfig.py` / `settings.py`, tasks already covered by that global limit will still be flagged.** Add per-task limits (self-documenting, immune to config drift) or suppress with `# pyvibe: ignore PYVIBE-005` on the task's `def` line.
 - PYVIBE-009: `CRITICAL` in production files; automatically downgraded to `WARNING` in test files (`test_*.py`, `*_test.py`, `tests/`). **Context matters:** `open()` in a hot-path request handler blocks all concurrent coroutines (CRITICAL); `open()` in a startup/lifespan function runs before requests are served and has zero practical impact. The rule cannot distinguish these contexts via AST — if you use `open()` in an `async def` lifespan or one-time initializer, the idiomatic fix is to use plain `def` instead (FastAPI's own docs do this), which avoids the flag entirely.
 - PYVIBE-017: bare `except` → `CRITICAL` (catches `KeyboardInterrupt`/`SystemExit`); `except Exception` with empty body → `WARNING`. Specific exceptions (`except ValueError: pass`) are not flagged.
 - PYVIBE-013 in test files: automatically downgraded to `WARNING` in files matching `test_*.py`, `*_test.py`, or paths under `tests/` — exceptions should propagate for assertions in test code.
@@ -165,6 +165,11 @@ python -m pyvibe src/ --baseline          # only reports findings NOT in the bas
 # Show suppressed findings (inline comments + pyvibe.toml) alongside the report
 python -m pyvibe src/ --verbose
 
+# Audit inline suppressions: justification coverage + orphaned (unused) suppressions
+python -m pyvibe audit src/
+python -m pyvibe audit src/ --json
+python -m pyvibe audit src/ --fail-on-unused --fail-on-unjustified
+
 # Exit code: 0 = clean, 1 = violations found, 2 = path error
 ```
 
@@ -298,6 +303,14 @@ conn = sqlite3.connect(...)              # suppressed — always targets the nex
 `pyvibe:` is case-insensitive. A directive with no recognizable `PYVIBE-XXX` id is ignored
 (treated as a regular comment).
 
+Add an optional justification after `--` — it's free text, stored and shown in `pyvibe audit`:
+
+```python
+conn = sqlite3.connect(...)  # pyvibe: ignore PYVIBE-008 -- legacy sqlite wrapper
+# pyvibe: ignore-next-line PYVIBE-008 -- startup only
+conn = sqlite3.connect(...)
+```
+
 For project-wide rules, add a `pyvibe.toml` next to your code (python-vibe-guard walks up
 from the scan target to find it, same convention as `pyproject.toml`):
 
@@ -330,6 +343,44 @@ Add `--verbose` to see exactly what was suppressed and why:
     PYVIBE-019 legacy.py:81 (config)
 ```
 
+### `pyvibe audit`
+
+Audits every inline `# pyvibe: ignore` comment in a codebase: how many carry a justification,
+and how many are **orphaned** — the rule they name never actually fires on the target line,
+usually because the underlying code changed since the suppression was added.
+
+```
+$ pyvibe audit src/
+
+Suppressions audit
+──────────────────
+Total suppressions: 12
+With justification: 9 (75%)
+Without justification: 3
+Unused (no violation found): 2
+
+By rule:
+PYVIBE-008   5
+PYVIBE-019   4
+PYVIBE-003   3
+
+Unused suppressions:
+app/legacy.py:41  # pyvibe: ignore PYVIBE-008
+
+Without justification:
+models/db.py:88  # pyvibe: ignore PYVIBE-019
+```
+
+- `--json` — machine-readable output (`total`, `with_justification`, `without_justification`,
+  `unused`, `by_rule`, `unused_suppressions`, `without_justification_suppressions`).
+- `--fail-on-unused` — exit `1` if any orphaned suppression is found.
+- `--fail-on-unjustified` — exit `1` if any suppression is missing a justification.
+- `--max-unused N` — exit `1` if more than `N` orphaned suppressions are found.
+- `--exclude DIR` — same directory-exclusion convention as `pyvibe scan`.
+
+With no flags, `pyvibe audit` is purely informational (exit `0`) — the flags above are what
+you wire into CI to enforce a justification/cleanup policy over time.
+
 ---
 
 ## CI/CD integration
@@ -384,7 +435,7 @@ Add to your `.pre-commit-config.yaml`:
 ```yaml
 repos:
   - repo: https://github.com/Joaquinriosheredia/python-vibe-guard
-    rev: v0.7.0
+    rev: v0.12.2
     hooks:
       - id: python-vibe-guard
 ```
@@ -427,7 +478,13 @@ python -m pytest tests/ -v
 python tests/test_rules.py
 ```
 
-309 tests: true positives + false-positive guards for every rule, plus SARIF output, `pyvibe explain`, `pyvibe review`, baseline mode, and suppressions (inline comments + pyvibe.toml) coverage.
+331 tests: true positives + false-positive guards for every rule, plus SARIF output, `pyvibe explain`, `pyvibe review`, baseline mode, suppressions (inline comments + pyvibe.toml), and `pyvibe audit` (justifications + orphan detection) coverage.
+
+---
+
+## Documentation
+
+- [research/public-findings.md](research/public-findings.md) — real findings reported to public open source projects, including confirmed cases and cases where context changed the outcome.
 
 ---
 

{python_vibe_guard-0.12.0 → python_vibe_guard-0.12.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-vibe-guard"
-version = "0.12.0"
+version = "0.12.2"
 description = "Runtime anti-pattern scanner for async Python — detects what AI-generated code gets wrong"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -28,3 +28,6 @@ pyvibe = "pyvibe.cli:main"
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["pyvibe*"]
+
+[tool.setuptools.package-data]
+pyvibe = ["_evidence/*.md", "_evidence/accepted/*.md"]

{python_vibe_guard-0.12.0 → python_vibe_guard-0.12.2}/python_vibe_guard.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-vibe-guard
-Version: 0.12.0
+Version: 0.12.2
 Summary: Runtime anti-pattern scanner for async Python — detects what AI-generated code gets wrong
 License: MIT
 Keywords: async,linter,fastapi,asyncio,static-analysis
@@ -79,7 +79,7 @@ Patterns that introduce data races, swallowed errors, or runaway loops under con
 | PYVIBE-020 | `put_nowait()` without `asyncio.QueueFull` handler | any | `QueueFull` propagates unhandled; item is silently lost on bounded queues |
 
 **Severity notes:**
-- PYVIBE-005: `CRITICAL` — checks per-task decorator arguments only. **If your project sets a global `task_time_limit` via `app.conf.task_time_limit`, `app.conf.update(...)`, or in `celeryconfig.py` / `settings.py`, tasks already covered by that global limit will still be flagged.** Add per-task limits (self-documenting, immune to config drift) or suppress with `# noqa: PYVIBE-005`.
+- PYVIBE-005: `CRITICAL` — checks per-task decorator arguments only. **If your project sets a global `task_time_limit` via `app.conf.task_time_limit`, `app.conf.update(...)`, or in `celeryconfig.py` / `settings.py`, tasks already covered by that global limit will still be flagged.** Add per-task limits (self-documenting, immune to config drift) or suppress with `# pyvibe: ignore PYVIBE-005` on the task's `def` line.
 - PYVIBE-009: `CRITICAL` in production files; automatically downgraded to `WARNING` in test files (`test_*.py`, `*_test.py`, `tests/`). **Context matters:** `open()` in a hot-path request handler blocks all concurrent coroutines (CRITICAL); `open()` in a startup/lifespan function runs before requests are served and has zero practical impact. The rule cannot distinguish these contexts via AST — if you use `open()` in an `async def` lifespan or one-time initializer, the idiomatic fix is to use plain `def` instead (FastAPI's own docs do this), which avoids the flag entirely.
 - PYVIBE-017: bare `except` → `CRITICAL` (catches `KeyboardInterrupt`/`SystemExit`); `except Exception` with empty body → `WARNING`. Specific exceptions (`except ValueError: pass`) are not flagged.
 - PYVIBE-013 in test files: automatically downgraded to `WARNING` in files matching `test_*.py`, `*_test.py`, or paths under `tests/` — exceptions should propagate for assertions in test code.
@@ -181,6 +181,11 @@ python -m pyvibe src/ --baseline          # only reports findings NOT in the bas
 # Show suppressed findings (inline comments + pyvibe.toml) alongside the report
 python -m pyvibe src/ --verbose
 
+# Audit inline suppressions: justification coverage + orphaned (unused) suppressions
+python -m pyvibe audit src/
+python -m pyvibe audit src/ --json
+python -m pyvibe audit src/ --fail-on-unused --fail-on-unjustified
+
 # Exit code: 0 = clean, 1 = violations found, 2 = path error
 ```
 
@@ -314,6 +319,14 @@ conn = sqlite3.connect(...)              # suppressed — always targets the nex
 `pyvibe:` is case-insensitive. A directive with no recognizable `PYVIBE-XXX` id is ignored
 (treated as a regular comment).
 
+Add an optional justification after `--` — it's free text, stored and shown in `pyvibe audit`:
+
+```python
+conn = sqlite3.connect(...)  # pyvibe: ignore PYVIBE-008 -- legacy sqlite wrapper
+# pyvibe: ignore-next-line PYVIBE-008 -- startup only
+conn = sqlite3.connect(...)
+```
+
 For project-wide rules, add a `pyvibe.toml` next to your code (python-vibe-guard walks up
 from the scan target to find it, same convention as `pyproject.toml`):
 
@@ -346,6 +359,44 @@ Add `--verbose` to see exactly what was suppressed and why:
     PYVIBE-019 legacy.py:81 (config)
 ```
 
+### `pyvibe audit`
+
+Audits every inline `# pyvibe: ignore` comment in a codebase: how many carry a justification,
+and how many are **orphaned** — the rule they name never actually fires on the target line,
+usually because the underlying code changed since the suppression was added.
+
+```
+$ pyvibe audit src/
+
+Suppressions audit
+──────────────────
+Total suppressions: 12
+With justification: 9 (75%)
+Without justification: 3
+Unused (no violation found): 2
+
+By rule:
+PYVIBE-008   5
+PYVIBE-019   4
+PYVIBE-003   3
+
+Unused suppressions:
+app/legacy.py:41  # pyvibe: ignore PYVIBE-008
+
+Without justification:
+models/db.py:88  # pyvibe: ignore PYVIBE-019
+```
+
+- `--json` — machine-readable output (`total`, `with_justification`, `without_justification`,
+  `unused`, `by_rule`, `unused_suppressions`, `without_justification_suppressions`).
+- `--fail-on-unused` — exit `1` if any orphaned suppression is found.
+- `--fail-on-unjustified` — exit `1` if any suppression is missing a justification.
+- `--max-unused N` — exit `1` if more than `N` orphaned suppressions are found.
+- `--exclude DIR` — same directory-exclusion convention as `pyvibe scan`.
+
+With no flags, `pyvibe audit` is purely informational (exit `0`) — the flags above are what
+you wire into CI to enforce a justification/cleanup policy over time.
+
 ---
 
 ## CI/CD integration
@@ -400,7 +451,7 @@ Add to your `.pre-commit-config.yaml`:
 ```yaml
 repos:
   - repo: https://github.com/Joaquinriosheredia/python-vibe-guard
-    rev: v0.7.0
+    rev: v0.12.2
     hooks:
       - id: python-vibe-guard
 ```
@@ -443,7 +494,13 @@ python -m pytest tests/ -v
 python tests/test_rules.py
 ```
 
-309 tests: true positives + false-positive guards for every rule, plus SARIF output, `pyvibe explain`, `pyvibe review`, baseline mode, and suppressions (inline comments + pyvibe.toml) coverage.
+331 tests: true positives + false-positive guards for every rule, plus SARIF output, `pyvibe explain`, `pyvibe review`, baseline mode, suppressions (inline comments + pyvibe.toml), and `pyvibe audit` (justifications + orphan detection) coverage.
+
+---
+
+## Documentation
+
+- [research/public-findings.md](research/public-findings.md) — real findings reported to public open source projects, including confirmed cases and cases where context changed the outcome.
 
 ---
 

{python_vibe_guard-0.12.0 → python_vibe_guard-0.12.2}/python_vibe_guard.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ python_vibe_guard.egg-info/top_level.txt
 pyvibe/__init__.py
 pyvibe/__main__.py
 pyvibe/analyzer.py
+pyvibe/audit.py
 pyvibe/autofix.py
 pyvibe/baseline.py
 pyvibe/cli.py
@@ -18,6 +19,27 @@ pyvibe/explain.py
 pyvibe/rule_docs.py
 pyvibe/sarif.py
 pyvibe/suppressions.py
+pyvibe/_evidence/precision-audit.md
+pyvibe/_evidence/accepted/PYVIBE-001.md
+pyvibe/_evidence/accepted/PYVIBE-002.md
+pyvibe/_evidence/accepted/PYVIBE-003.md
+pyvibe/_evidence/accepted/PYVIBE-004.md
+pyvibe/_evidence/accepted/PYVIBE-005.md
+pyvibe/_evidence/accepted/PYVIBE-006.md
+pyvibe/_evidence/accepted/PYVIBE-007.md
+pyvibe/_evidence/accepted/PYVIBE-008.md
+pyvibe/_evidence/accepted/PYVIBE-009.md
+pyvibe/_evidence/accepted/PYVIBE-010.md
+pyvibe/_evidence/accepted/PYVIBE-011.md
+pyvibe/_evidence/accepted/PYVIBE-012.md
+pyvibe/_evidence/accepted/PYVIBE-013.md
+pyvibe/_evidence/accepted/PYVIBE-014.md
+pyvibe/_evidence/accepted/PYVIBE-015.md
+pyvibe/_evidence/accepted/PYVIBE-016.md
+pyvibe/_evidence/accepted/PYVIBE-017.md
+pyvibe/_evidence/accepted/PYVIBE-018.md
+pyvibe/_evidence/accepted/PYVIBE-019.md
+pyvibe/_evidence/accepted/PYVIBE-020.md
 pyvibe/rules/__init__.py
 pyvibe/rules/async_requests.py
 pyvibe/rules/async_sleep.py
@@ -40,9 +62,11 @@ pyvibe/rules/sqlite_async.py
 pyvibe/rules/subprocess_async.py
 pyvibe/rules/threading_lock.py
 pyvibe/rules/while_true_no_await.py
+tests/test_audit.py
 tests/test_baseline.py
 tests/test_config.py
 tests/test_diff.py
+tests/test_evidence_sync.py
 tests/test_exclude.py
 tests/test_explain.py
 tests/test_rules.py

python_vibe_guard-0.12.2/pyvibe/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.12.2"

python_vibe_guard-0.12.2/pyvibe/_evidence/accepted/PYVIBE-001.md

@@ -0,0 +1,172 @@
+# PYVIBE-001 — time.sleep() en async def
+
+**Severidad:** CRITICAL  
+**Archivo:** `pyvibe/rules/async_sleep.py`  
+**Patrón:** `time.sleep(N)` llamado directamente dentro de `async def`
+
+---
+
+## Datos objetivos
+
+| Métrica | 100 repos | 250 repos |
+|---------|-----------|-----------|
+| Repos afectados | 16/100 (16.0%) | 31/250 (12.4%) |
+| Total hits | 55 | 87 |
+| Estabilidad 100→250 | Alta (−3.6 pp) | |
+| Falsos positivos documentados | 0 | |
+
+## Repos representativos (sweep 250)
+
+- `home-assistant/core` — 17 hits
+- `pmh1314520/WebRPA` — 9 hits
+- `MODSetter/SurfSense` — 7 hits
+- `IBM/mcp-context-forge` — 6 hits
+- `learning-at-home/hivemind` — 5 hits
+
+---
+
+## Evidence Review Protocol v1
+
+### Paso 1 — Documentación oficial
+
+**Resultado: CONFIRMADO — mención explícita en docs.python.org**
+
+`docs.python.org/3/library/asyncio-task.html` (sección `asyncio.to_thread()`) usa `time.sleep()` como el ejemplo canónico de llamada bloqueante, con la nota explícita:
+
+> *"Note that time.sleep() can be replaced with any blocking IO-bound operation, such as file operations."*
+
+y el efecto documentado:
+
+> *"Directly calling blocking_io() in any coroutine would block the event loop for its duration, resulting in an additional 1 second of run time."*
+
+El ejemplo de código en la doc muestra `time.sleep(1)` dentro de una función sync (correctamente) y la llamada bloqueante desde una coroutine como el antipatrón a evitar, mostrando `asyncio.to_thread(blocking_io)` como la solución.
+
+`docs.python.org/3/library/asyncio-dev.html` (Developing with asyncio) añade:
+
+> *"Blocking (CPU-bound) code should not be called directly. For example, if a function performs a CPU-intensive calculation for 1 second, all concurrent asyncio Tasks and IO operations would be delayed by 1 second."*
+
+Este texto no nombra `time.sleep()` explícitamente, pero lo describe de forma genérica.
+
+**Tornado FAQ** (framework de referencia para async Python predecesor de asyncio):
+
+> *"time.sleep is a blocking function: it doesn't allow control to return to the IOLoop so that other handlers can be run."*
+
+**Veredicto paso 1:** documentación oficial Python nombra `time.sleep()` explícitamente como el ejemplo estándar de llamada bloqueante que no debe usarse directamente en coroutines.
+
+---
+
+### Paso 2 — Incidentes reales
+
+**Resultado: CONFIRMADO — issue real en producción**
+
+**[home-assistant/core#119628](https://github.com/home-assistant/core/issues/119628)** (cerrado):  
+`time.sleep(0.3)` en la librería `pyserial-asyncio` (línea 104 de `serial/urlhandler/protocol_socket.py`) era llamado desde dentro del event loop de Home Assistant. Home Assistant 2024.6.2 introdujo detección activa de llamadas bloqueantes y produjo el warning:
+
+> *"Detected blocking call to sleep inside the event loop by integration 'config'..."*
+
+La issue fue reportada en core-2024.6.2 y no ocurría en core-2024.4.4. Issue cerrada — el impacto fue degradación de responsividad durante reloads de integration.
+
+**[MagicStack/uvloop#29](https://github.com/MagicStack/uvloop/issues/29)** (aparece en búsqueda, no verificado con fetch):  
+Mencionado en el contexto de que "el tiempo del loop no avanza cuando el loop está bloqueado por time.sleep()" — consistente con el comportamiento documentado.
+
+**DEV.to "3-Hour Debugging: How time.sleep in Async Functions Killed Our asyncio Concurrency":**  
+Post con formato de caso de debugging. El síntoma: un servicio de recolección de datos que no mejoró al convertirse a async, tomando los mismos 30 minutos por ejecución. Causa raíz: `time.sleep(0.5)` enterrado en una función anidada. **No es un postmortem con nombre de empresa verificable** — es contenido educativo presentado como caso de estudio. No cuenta como incidente público confirmado.
+
+**Veredicto paso 2:** un incidente real confirmado en GitHub (home-assistant/core#119628, cerrado). El impacto fue observable en producción.
+
+---
+
+### Paso 3 — Comunidad
+
+**Resultado: CONSENSO UNIVERSAL — sin casos de desacuerdo**
+
+La búsqueda no encontró ninguna discusión en Stack Overflow, DEV.to, Medium o foros que sugiera que `time.sleep()` dentro de `async def` sea aceptable. El consenso es unánime:
+
+- La causa síntomática más reportada: *"convertí mi código a async pero no mejora la velocidad"*
+- Solución universal documentada: reemplazar `time.sleep(n)` por `await asyncio.sleep(n)`, o por `await asyncio.to_thread(time.sleep, n)` si la intención es bloquear en un thread aparte
+- El Mergify blog documenta la detección de event loop blocking mediante medición de latencia; usa `time.sleep()` como ejemplo paradigmático del problema a detectar
+
+**Veredicto paso 3:** la comunidad no tiene posiciones encontradas sobre este patrón. Es tratado como bug obvio.
+
+---
+
+### Paso 4 — Evidencia empírica propia
+
+**Resultado: FUERTE**
+
+- 31/250 repos afectados (12.4%) — estabilidad Alta (−3.6 pp entre 100 y 250 repos)
+- 87 hits totales en proyectos de alta estrella con asyncio
+- Presente en repos de referencia: `home-assistant/core`, `MODSetter/SurfSense`, `IBM/mcp-context-forge`
+- 0 falsos positivos documentados en 250 repos escaneados
+
+---
+
+### Paso 5 — Intento de refutación
+
+**Búsqueda activa de excepciones legítimas.**
+
+**¿Existe algún caso donde `time.sleep()` dentro de `async def` sea intencional y correcto?**
+
+La búsqueda encontró tres escenarios candidatos:
+
+**Candidato A — Testing de comportamiento bloqueante**  
+Usar `time.sleep()` en un test `async def` para simular una llamada bloqueante y verificar que el detector de blocking funciona. *Técnicamente funciona, pero:*
+- `asynctest` y `sleepfake` (librerías de testing para asyncio) proveen `advance()` y mocking de clock precisamente para evitar `time.sleep()` real en tests
+- Ningún framework de testing Python recomienda `time.sleep()` real en async tests; se recomienda mockear o usar `asyncio.sleep()` con un loop de testing
+- **Veredicto: no es una excepción legítima que invalide la regla**
+
+**Candidato B — Delay deliberado en un sistema sin concurrencia**  
+Código que usa `async def` pero en la práctica solo ejecuta una tarea a la vez y quiere añadir un delay. `time.sleep()` funciona en este caso porque no hay otra coroutine esperando.  
+- Esto es una antipatrón de diseño: si no se necesita concurrencia, no debería usarse asyncio
+- Si se necesita asyncio pero se quiere bloquear un momento, `await asyncio.sleep(n)` es siempre equivalente y correcto
+- **Veredicto: funciona técnicamente pero nunca es la opción correcta**
+
+**Candidato C — Wrapper para `asyncio.to_thread()`**  
+`await asyncio.to_thread(time.sleep, n)` — llamar `time.sleep` desde `async def` *como argumento de `to_thread`*, no como llamada directa. Esto ES correcto.  
+- PYVIBE-001 **no flagea este patrón**: la regla detecta `time.sleep(...)` como expresión directa en el cuerpo de `async def`, no como argumento de otra función
+- **Veredicto: caso correcto, y la regla ya lo maneja bien**
+
+**Excepción conocida documentada:**  
+No se encontró ningún caso donde `time.sleep(n)` directamente en el cuerpo de `async def` sea la opción técnicamente correcta sobre `await asyncio.sleep(n)`. Tornado FAQ, Python docs y comunidad son unánimes.
+
+**Límite honesto:** los 31 repos con hits no han sido auditados manualmente para verificar si algún hit está en un test que específicamente testea comportamiento bloqueante. Este caso extremo existe en teoría pero no se ha verificado en el scan actual.
+
+---
+
+## Clasificación final
+
+**Evidence Level: A+**
+
+| Criterio | Estado |
+|----------|--------|
+| Validada en repos reales (31/250, 12.4%) | ✅ |
+| Documentación oficial Python nombra `time.sleep()` explícitamente | ✅ |
+| Incidente público confirmado (HA core#119628, cerrado) | ✅ |
+| Falsos positivos documentados en campo | ✅ 0 |
+| Excepción legítima conocida | ✅ ninguna para llamada directa |
+
+---
+
+## Confidence
+
+```
+Confidence:
+  Detection:         High — AST directo sobre name="sleep" en module time;
+                            0 FP documentados en 250 repos; el Candidato C
+                            (to_thread) no es flagueado correctamente
+  Runtime impact:    High — bloquea el event loop completo para toda la
+                            duración del sleep; efecto demostrado en HA prod
+  External evidence: High — docs.python.org nombra time.sleep() explícitamente
+                            + HA issue real cerrado + consenso comunitario unánime
+```
+
+---
+
+## Fuentes verificadas
+
+- [asyncio-task.html — asyncio.to_thread() example](https://docs.python.org/3/library/asyncio-task.html)
+- [asyncio-dev.html — Developing with asyncio](https://docs.python.org/3/library/asyncio-dev.html)
+- [Tornado FAQ — time.sleep is a blocking function](https://www.tornadoweb.org/en/stable/faq.html)
+- [home-assistant/core#119628 — Blocking call to sleep inside event loop](https://github.com/home-assistant/core/issues/119628)
+- [Mergify — Detecting Blocking Tasks in Asyncio](https://mergify.com/blog/detecting-blocking-tasks-in-asyncio-by-measuring-event-loop-latency/)
+- [DEV.to — 3-Hour Debugging case study (educativo, sin empresa verificable)](https://dev.to/_eb7f2a654e97a60ae9f96e/3-hour-debugging-how-timesleep-in-async-functions-killed-our-asyncio-concurrency-43c3)

python_vibe_guard-0.12.2/pyvibe/_evidence/accepted/PYVIBE-002.md

@@ -0,0 +1,86 @@
+# PYVIBE-002 — requests.get/post en async def
+
+**Severidad:** CRITICAL  
+**Archivo:** `pyvibe/rules/async_requests.py`  
+**Patrón:** `requests.get(...)` / `requests.post(...)` / etc. dentro de `async def`
+
+## Datos objetivos
+
+| Métrica | 100 repos | 250 repos |
+|---------|-----------|-----------|
+| Repos afectados | 3/100 (3.0%) | 10/250 (4.0%) |
+| Total hits | 5 | 14 |
+| Estabilidad 100→250 | Alta (+1.0 pp) | |
+| Falsos positivos documentados | 0 | |
+
+## Repos representativos (sweep 250)
+
+- `paulpierre/RasaGPT` — 3 hits
+- `home-assistant/core` — 2 hits
+- `learning-at-home/hivemind` — 2 hits
+- `bmoscon/cryptofeed` — 1 hit
+- `pydantic/logfire` — 1 hit
+
+## Evidence Level: B
+
+- ✅ Validada en repos reales: 10 repos afectados en muestra de 250
+- ⏳ Documentación oficial o incidentes públicos confirmando `requests` sync en async como bug: **PENDIENTE — requiere investigación manual**
+- ✅ Falsos positivos documentados en campo: 0
+
+---
+
+## Auditoría de Precisión (Sweep 250)
+
+**Muestra analizada:** 14 hits de 14 totales (10 repos)
+**Metodología:** 100% audit (14 hits)
+
+### Clasificación hit-by-hit
+
+| # | Repo | File:Line | Function | Clasificación | Razón |
+|---|------|-----------|----------|---------------|-------|
+| 1 | BetaStreetOmnis__xhs_ai_publisher | src/core/pages/tools.py:63 | async_process | FP | `requests.post()` dentro de `loop.run_in_executor(None, lambda: requests.post(...))` — la llamada síncrona está correctamente delegada al executor de threads; el comentario en código incluso menciona que se podría usar aiohttp |
+| 2 | Kav-K__GPTDiscord | models/openai_model.py:1312 | save_image_urls_and_return | FP | `requests.get()` dentro de `asyncio.get_running_loop().run_in_executor(None, lambda: [...])` — correctamente envuelto en executor |
+| 3 | bmoscon__cryptofeed | cryptofeed/exchanges/binance.py:158 | _refresh_token | TP | `requests.put()` directo en `async def _refresh_token`, sin executor. Bug real — bloquea el event loop durante token refresh en un bucle while True |
+| 4 | home-assistant__core | homeassistant/components/downloader/services.py:64 | download_file | FP | `requests.get()` dentro de `def do_download()` (función síncrona), que se llama luego con `await service.hass.async_add_executor_job(do_download)` — el detector flagueó la línea del requests.get pero está en una función def interna que se ejecuta en executor |
+| 5 | home-assistant__core | homeassistant/components/xmpp/notify.py:274 | upload_file_from_url | FP | `requests.get()` en `def get_url(url)` síncrona interna, llamada con `await hass.async_add_executor_job(get_url, url)` — mismo patrón que hit 4 |
+| 6 | learning-at-home__hivemind | hivemind/p2p/p2p_daemon.py:440 | _read_stream | FP | La variable `requests` en este contexto es `asyncio.Queue(max_prefetch)` — no es el módulo `requests`. El detector tiene un FP por colisión de nombre de variable: `requests = asyncio.Queue(...)`, luego `request = await requests.get()` |
+| 7 | learning-at-home__hivemind | hivemind/p2p/p2p_daemon.py:477 | _handle_stream | FP | Mismo contexto que hit 6 — `requests` es una `asyncio.Queue`, no el módulo HTTP |
+| 8 | paulpierre__RasaGPT | app/rasa-credentials/main.py:65 | get_active_tunnels | TP | `requests.get()` directo en `async def get_active_tunnels()`, sin executor. Bug real. |
+| 9 | paulpierre__RasaGPT | app/rasa-credentials/main.py:78 | stop_tunnel | TP | `requests.delete()` directo en `async def stop_tunnel()`. Bug real. |
+| 10 | paulpierre__RasaGPT | app/rasa-credentials/main.py:118 | create_tunnel | TP | `requests.post()` directo en `async def create_tunnel()`. Bug real. |
+| 11 | pydantic__logfire | tests/otel_integrations/test_requests.py:41 | test_requests_instrumentation | FP | Test async que verifica instrumentación del módulo `requests` — `requests.get()` es el objeto bajo prueba (test de observabilidad). Uso legítimo en test. |
+| 12 | python-kasa__python-kasa | kasa/protocols/smartprotocol.py:299 | _execute_multiple_query | FP | La variable `requests` es un `dict` local (mapa de requests al protocolo KASA), no el módulo `requests`. `requests.get(method)` es `dict.get()` en un dict llamado `requests`. Colisión de nombre. |
+| 13 | raullenchai__Rapid-MLX | tests/evals/gsm8k/gsm8k_eval.py:136 | evaluate_with_server | EDGE | `requests.post()` en bucle de evaluación async — es un test/benchmark que llama a un servidor local; técnicamente bloquea el loop pero es un script de evaluación no de producción. Contexto borderline. |
+| 14 | wyeeeee__hajimi | app/utils/version.py:23 | check_version | TP | `requests.get()` directo en `async def check_version()`, sin executor. Bug real — bloquea el loop en cada check de versión. |
+
+### Resultado
+
+| Métrica | Valor |
+|---------|-------|
+| TP | 5 |
+| FP | 8 |
+| EDGE | 1 |
+| Precisión (TP/total sin EDGE) | 5/13 = 38% |
+| Precisión (TP/total con EDGE) | 5/14 = 36% |
+
+### Patrones de FP identificados
+
+1. **EXECUTOR_WRAPPER** — `requests.*()` dentro de `run_in_executor(None, lambda: ...)` o `async_add_executor_job()`. La llamada síncrona está correctamente delegada al pool de threads.
+   - Ejemplo: `await loop.run_in_executor(None, lambda: requests.post(...))`
+   - Repos afectados: 2 (xhs_ai_publisher, GPTDiscord) + 2 en Home Assistant (como inner def)
+
+2. **INNER_SYNC_FUNCTION_EXECUTOR** — `requests.*()` en una función `def` interna que luego se pasa a `executor_job`. El detector flagueó la llamada en el scope síncrono pero no detectó que se ejecutará en executor.
+   - Ejemplo: `def do_download(): requests.get(...)` → `await hass.async_add_executor_job(do_download)`
+   - Repos afectados: 1 (home-assistant/core, 2 instancias)
+
+3. **VARIABLE_NAME_COLLISION** — variable local llamada `requests` que no es el módulo HTTP (puede ser un dict, una Queue, etc.).
+   - Ejemplo: `requests = asyncio.Queue(max_prefetch)` → detector flagueó `requests.get()` como llamada HTTP
+   - Ejemplo: `requests = {}` (dict) → `requests.get(method)` es un dict lookup
+   - Repos afectados: 2 (hivemind, python-kasa)
+
+4. **TEST_SUBJECT** — test async que verifica el módulo `requests` como objeto bajo prueba para instrumentación.
+   - Repos afectados: 1 (pydantic/logfire)
+
+### Recomendación de Evidence Level
+
+**Mantener B. Precisión preocupante: 36-38%.** El problema principal es triple: (a) colisiones de nombre de variable (`requests` como nombre de dict/Queue), (b) `requests.*()` en funciones `def` síncronas internas que se pasan a executor, (c) test subjects. El detector necesita mejorar: verificar que `requests` sea realmente el módulo importado (no una variable local), y detectar el patrón `run_in_executor` en el contexto inmediato. Los 5 TP reales son genuinamente problemáticos. **FP rate alto (62%) requiere acción antes de considerar elevación a Evidence A.**