ajuste no guardraild COE

tests/docs/OBSERVABILITY_CONTRACT_REGISTRY.md

@@ -0,0 +1,43 @@
+# Observability Contract Registry
+
+`config/observability_mapping.yaml` é a única tabela usada pelo framework para duas responsabilidades relacionadas ao contrato externo:
+
+1. traduzir nomes/códigos semânticos para labels exigidos pela observabilidade do cliente;
+2. preservar ações legadas de guardrails (`retry`, `handover`, etc.) sem hardcode de nomes no Python.
+
+A sintaxe v1 continua válida:
+
+```yaml
+mappings:
+  guardrail.dlex_in: GRL.004
+```
+
+A forma rica adiciona `action` e `aliases`:
+
+```yaml
+mappings:
+  guardrail.revprec:
+    action: retry
+    aliases: [REVPREC, TIM_REVPREC]
+```
+
+`label` é opcional. Quando ausente, o nome de observabilidade não é renomeado. `action` também é opcional.
+
+## Precedência de ação
+
+Para uma decisão negada, o framework usa:
+
+1. `metadata.terminal_action` retornado pelo rail;
+2. `on_deny` do `guardrails.yaml`;
+3. `action` resolvida pelo `observability_mapping.yaml`;
+4. `BLOCK` como fallback fail-safe.
+
+Isso mantém compatibilidade com rails internos e externos sem que `OutputSupervisor` ou `ParallelRailExecutor` conheçam nomes como `REVPREC`, `CMP`, `SCO`, `GND`, `ATH` ou `HUMAN`.
+
+## Aliases
+
+Uma entrada `guardrail.revprec` é automaticamente resolvida também por `REVPREC`. Aliases explícitos permitem associar nomes externos ou históricos, por exemplo `TIM_REVPREC`.
+
+## Compatibilidade
+
+Mappings escalares continuam funcionando sem alteração. Agentes que não habilitam o mapper continuam em passthrough e usam `BLOCK` para negações sem ação explícita.