revisão e complementação da documentação do projeto

2026-11-05 22:14:11 +00:00 · 2026-09-14 14:01:27 -03:00
parent 2fe6d6d508
commit 9a99ec6cc8
65 changed files with 6630 additions and 1854 deletions
--- a/docs/adr/ADR-001-teto-de-privilegio-do-agente.md
+++ b/docs/adr/ADR-001-teto-de-privilegio-do-agente.md
@@ -1,7 +1,7 @@
 # ADR-001: Fronteira de MaximumEntitlement no MCP Client

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-001 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-002-enforcement-no-gateway.md
+++ b/docs/adr/ADR-002-enforcement-no-gateway.md
@@ -1,7 +1,7 @@
 # ADR-002: MCP Gateway como PEP unico

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-002 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-003-reautorizacao-de-tools-call.md
+++ b/docs/adr/ADR-003-reautorizacao-de-tools-call.md
@@ -1,7 +1,7 @@
 # ADR-003: Reautorizacao independente em tools/call

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-003 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-004-contexto-nunca-eleva-privilegio.md
+++ b/docs/adr/ADR-004-contexto-nunca-eleva-privilegio.md
@@ -1,7 +1,7 @@
 # ADR-004: Contexto agentico nunca eleva privilegio

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-004 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-005-cache-privado-de-tools-list.md
+++ b/docs/adr/ADR-005-cache-privado-de-tools-list.md
@@ -1,7 +1,7 @@
 # ADR-005: Cache privado de tools/list

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-005 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-006-sem-token-passthrough.md
+++ b/docs/adr/ADR-006-sem-token-passthrough.md
@@ -1,7 +1,7 @@
 # ADR-006: Proibicao de token passthrough

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-006 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-007-backend-nao-exposto-diretamente.md
+++ b/docs/adr/ADR-007-backend-nao-exposto-diretamente.md
@@ -1,7 +1,7 @@
 # ADR-007: Backend nunca exposto diretamente ao client

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-007 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-008-segmentacao-por-dominio-e-risco.md
+++ b/docs/adr/ADR-008-segmentacao-por-dominio-e-risco.md
@@ -1,7 +1,7 @@
 # ADR-008: Segmentacao de clients por dominio e risk tier

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-008 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-009-risk-tiers-de-capabilities.md
+++ b/docs/adr/ADR-009-risk-tiers-de-capabilities.md
@@ -1,7 +1,7 @@
 # ADR-009: Risk tiers R0-R4 para capabilities

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-009 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-010-governanca-do-registry.md
+++ b/docs/adr/ADR-010-governanca-do-registry.md
@@ -1,7 +1,7 @@
 # ADR-010: Governanca do Global Capability Registry

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-010 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-011-pipeline-de-publicacao.md
+++ b/docs/adr/ADR-011-pipeline-de-publicacao.md
@@ -1,7 +1,7 @@
 # ADR-011: Pipeline obrigatorio de publicacao de capabilities

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-011 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-012-entitlement-manager-como-autoridade.md
+++ b/docs/adr/ADR-012-entitlement-manager-como-autoridade.md
@@ -1,7 +1,7 @@
 # ADR-012: Entitlement Manager como autoridade unica de MaximumEntitlement

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-012 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-013-contrato-de-profile-intelligence.md
+++ b/docs/adr/ADR-013-contrato-de-profile-intelligence.md
@@ -1,7 +1,7 @@
 # ADR-013: Contrato plugavel de Profile Intelligence

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-013 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-014-perfil-nunca-amplia-entitlement.md
+++ b/docs/adr/ADR-014-perfil-nunca-amplia-entitlement.md
@@ -1,7 +1,7 @@
 # ADR-014: Perfil nunca amplia entitlement

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-014 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-015-nba-nao-e-autorizacao.md
+++ b/docs/adr/ADR-015-nba-nao-e-autorizacao.md
@@ -1,7 +1,7 @@
 # ADR-015: NBA como decisao de orquestracao, nao de autorizacao

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-015 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-016-contrato-de-dispatch-handoff.md
+++ b/docs/adr/ADR-016-contrato-de-dispatch-handoff.md
@@ -1,7 +1,7 @@
 # ADR-016: Contrato de dispatch/handoff do Agent Runtime

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-016 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-017-correlacao-ponta-a-ponta.md
+++ b/docs/adr/ADR-017-correlacao-ponta-a-ponta.md
@@ -1,7 +1,7 @@
 # ADR-017: Correlacao ponta a ponta via IDs versionados

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-017 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-018-stack-de-implementacao.md
+++ b/docs/adr/ADR-018-stack-de-implementacao.md
@@ -1,7 +1,7 @@
 # ADR-018: Stack de implementacao da RI

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-018 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

@@ -21,8 +21,8 @@ Define toda a estrutura de repositório (8.5).

 ## Versões confirmadas (EP-16-T04)

-Spike sem dependências, executável a qualquer momento (`docs/RI-PLANNING.md`
-EP-16-T04): confirmar, imediatamente antes de fixar em `pyproject.toml`/
+Spike sem dependências, executável a qualquer momento (EP-16-T04): confirmar,
+imediatamente antes de fixar em `pyproject.toml`/
 `docker-compose.yml`, os números exatos de versão estável de cada peça da
 stack — nenhuma versão citada em código/config sem confirmação real
 (`pip index versions`/download direto/instalação real), nunca de memória.
--- a/docs/adr/ADR-019-identity-extension.md
+++ b/docs/adr/ADR-019-identity-extension.md
@@ -1,7 +1,10 @@
 # ADR-019: MCP Client identity -- production extension point (mTLS / workload identity)

 **Status:** Documented (spike), not implemented in the RI (EP-01-T04, `could`).
-**Related:** `docs/RI-PLANNING.md` ADR-019 entry (confirmed decision, 2026-09-11), README.md §19, RF-02, Axiom 2.
+**Related:** this ADR is the canonical record of this decision -- no longer generated from
+`docs/RI-PLANNING.md` (removed from the repository after M4 completed; history preserved in
+git). See `RI/docs/AS-BUILT.md` and `RI/docs/interfaces/identity-oidc.md` for implementation and
+validation context. Also relevant: README.md §19, RF-02, Axiom 2.

 ## Context

--- a/docs/adr/ADR-020-downstream-identity.md
+++ b/docs/adr/ADR-020-downstream-identity.md
@@ -1,7 +1,7 @@
 # ADR-020: Downstream identity: token exchange ou service account isolado

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-020 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-021-escopo-langgraph-langfuse.md
+++ b/docs/adr/ADR-021-escopo-langgraph-langfuse.md
@@ -1,7 +1,7 @@
 # ADR-021: Escopo de LangGraph e Langfuse na RI

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-021 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-022-referencia-hoshikawa-agent-platform-oci.md
+++ b/docs/adr/ADR-022-referencia-hoshikawa-agent-platform-oci.md
@@ -1,7 +1,7 @@
 # ADR-022: Referencia operacional: Agent Platform OCI (Hoshikawa)

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-022 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-023-autorizacao-nunca-vem-do-payload.md
+++ b/docs/adr/ADR-023-autorizacao-nunca-vem-do-payload.md
@@ -1,7 +1,7 @@
 # ADR-023: Autorizacao de tools nunca vem de campo declarado no payload

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-023 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-024-posicionamento-multiagente.md
+++ b/docs/adr/ADR-024-posicionamento-multiagente.md
@@ -1,7 +1,7 @@
 # ADR-024: Posicionamento do E-MCP-BUS frente a plataformas multiagente externas

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-024 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto

--- a/docs/adr/ADR-025-engine-do-pdp.md
+++ b/docs/adr/ADR-025-engine-do-pdp.md
@@ -1,7 +1,7 @@
 # ADR-025: OPA/Rego como engine do PDP

 **Status:** Aceito.
-**Fonte:** `docs/RI-PLANNING.md` §8.4 (tabela de ADRs), linha ADR-025 — gerado a partir dela por EP-16-T03. Onde a RI tem um componente/teste concreto implementando a decisão, este documento aponta para ele; a tabela em si continua a referência primária e mais atualizada.
+**Fonte:** este ADR é o registro canônico desta decisão — não é mais gerado a partir de `docs/RI-PLANNING.md` (removido do repositório após a conclusão do marco M4; histórico preservado no git). Para contexto de implementação e validação, ver `RI/docs/AS-BUILT.md` e, quando aplicável, o contrato relevante em `RI/docs/interfaces/`.

 ## Contexto