feat(guard): un except que escribe un código constante debe guardar la causa

[wolverin0]

Tercera aparición del mismo defecto

Y las tres costaron días:

#	Dónde	Qué se perdió
1	profile/engine.py	Registraba AntigravityError —un nombre de proveedor— cuando el fallo real era ProfileValidationError: profile candidates must appear exactly once. Diez días apuntando a una caída de proveedor que no existía.
2	graph_observation_engine.py	except Exception: sin capturar, error_code="synthesis_failed" fijo. Cinco intentos, cinco veces la misma palabra, cero información.
3	Migración 0022	Su propio docstring: "el único rastro de por qué era un sha256 de los códigos de diagnóstico — la razón se destruía al escribir".

Una corrección que recurre tres veces tiene que volverse algo que falle solo, no otra línea de prosa.

El guard

scripts/check_swallowed_cause.py camina el AST: si dentro de un handler se pasa un string literal a un parámetro que nombra la causa (error_code, error, reason, outcome), el handler tiene que ligar la excepción y usarla. Escape declarado: # swallow-ok: <motivo>.

Calibración — lo que decide si un guard sobrevive: 4 hallazgos en todo el repo, los 4 genuinos. Incluida discovery_failed, hermana de la que ya conocíamos y que nadie había visto. Un guard que inunda entrena a apaciguarlo, y termina desactivado.

Arreglado de raíz

fail_job no tenía dónde poner el detalle — esa era la falta estructural. Ahora acepta detail y lo escribe en diagnostic_codes, la columna de texto legible que la migración 0022 agregó exactamente para esto, truncada a 500 chars (esta tabla no es un log).

• Los dos handlers de PPR-7 pasan f"{type(exc).__name__}: {exc}".
• Los dos de los hooks usan el escape con motivo: son quiet-by-contract y capture_usage.outcome es vocabulario de contabilidad ('ok'/'error'), no un campo de diagnóstico. Guardar la causa ahí pide una columna en otro subsistema. Deuda anotada, no escondida.

Barra roja contra historia real

No casos sintéticos — el guard corrido sobre la versión de main:

graph_observation_engine.py@main:221: error_code='discovery_failed'
graph_observation_engine.py@main:278: error_code='synthesis_failed'

Sobre la versión arreglada: 0.

Tests

11 del propio guard: 3 de alarma y 7 de SILENCIO — porque lo que lo hace sostenible es no ladrar ante código que ya cumple (liga y usa la excepción, re-lanza, valor derivado, palabras parecidas como status/code que quedan fuera a propósito). Más test_el_repo_pasa_el_guard, que lo corre contra el repo real: si se pone rojo, o hay un handler nuevo que tira la causa o el guard se volvió ancho, y las dos merecen mirarse.

185/185 en observaciones y dreaming, ruff limpio.