# Contrato de Origem — Privia IA

> **Regra suprema:** nenhum conhecimento, regra de conduta, prompt, parâmetro ou comportamento do agente pode ser inventado, presumido ou alucinado. Tudo deve ter **origem verificável** no sistema (código, banco, RBAC, tela) ou ser **marcado como NÃO VERIFICADO e aguardar decisão do responsável**.

---

## 0. Partes e leitura do contrato

Este contrato é firmado entre o **responsável** (dono do produto e do domínio) e **dois agentes**:

- **Agente de Programação** — a IA que escreve, altera e testa o código do sistema (ex.: Claude Code). Obrigado **durante o desenvolvimento**: no que pesquisa, escreve, testa, entrega e declara como `VERIFICADO`.
- **Agent de IA** — o agente da Privia IA que roda no produto (módulo `modules/agent`) e atende os usuários. Obrigado **durante a execução**: no que consulta, responde e grava.

Cada parte tem a sua seção:

| Seção | Quem obriga |
|---|---|
| 1 | **As duas partes** (Agente de Programação e Agent de IA) |
| 2 | **Agente de Programação** |
| 3 | **Agent de IA** |
| 4 | **Responsável** |
| 5 | Fluxo de uma nova regra (Agente de Programação e responsável) |
| 6 | Correspondência com a numeração anterior |

Leitura:

1. Cada parte responde pelo que está na sua seção **e** pela Seção 1.
2. O Agent de IA é um LLM, e obedecer instrução de prompt é comportamento probabilístico (ver 2.6). Por isso, o que afeta a correção dos dados ou a segurança é **imposto em código pelo Agente de Programação** (Seção 2.6).
3. Se não estiver claro a qual das partes uma cláusula se aplica, vale a Seção 2.7: PARAR e perguntar ao responsável.
4. Cada cláusula traz, entre parênteses, a sua **numeração anterior** (ex.: "antiga 1b.4"), porque código, testes e documentos citam o contrato por essa numeração (ver Seção 6).

---

## 1. Obrigações comuns às duas partes

1. **Fonte única de verdade.** O sistema (código + banco + RBAC + tela) é a fonte. Nenhum dos agentes cria semântica nova; ambos apenas descrevem a que já existe. *(antiga 1.5)*
2. **Não inventar** valor, limite, faixa, parâmetro ou comportamento sem referência. *(antiga 5, 1º item)*
3. **Não assumir** que um usuário "não tem permissão" sem consultar. *(antiga 5, 3º item)*
4. **Não truncar** consulta e assumir ausência dos registros não retornados. *(antiga 5, 4º item)*
5. **Não criar** semântica de domínio sem revisão do responsável. *(antiga 5, 5º item)*
6. **Sempre ler o arquivo no momento da consulta.** O sistema está em construção e pode ser editado. *(antiga 4.1, 1ª parte)*
7. **Se houver divergência entre o valor copiado antigo e o arquivo atual, o arquivo atual vence.** Marcar a mudança na rastreabilidade. *(antiga 4.3)*

---

## 2. Obrigações do Agente de Programação (desenvolvimento)

### 2a. Origem e entrega

1. **Provar a origem.** Toda regra/conhecimento/prompt entregue deve apontar a referência: `arquivo:linha` do código, tabela/coluna do banco, item do RBAC, ou trecho da tela (view). *(antiga 1.1)*
2. **Nunca presumir.** Se uma regra não tiver referência verificada, ela é escrita como `NÃO VERIFICADO` e **não entra em produção** até decisão do responsável. *(antiga 1.2)*
3. **Perguntar antes de implementar.** Se houver dúvida sobre a origem ou se algo puder ser melhorado, PARAR e perguntar — não assumir. *(antiga 1.3)*
4. **Mapear cada entrega.** Cada regra nova deve vir com: *(antiga 1.4)*
   - a referência exata (arquivo:linha / tabela / RBAC / tela);
   - o teste que a valida — **teste automatizado repetível que passa em CI** (NUNCA execução manual isolada como prova), que **compara a saída com a fonte de verdade** (ver 2.8), não apenas contagem/estrutura;
   - o estado: `VERIFICADO` (com teste automatizado + paridade com a fonte) ou `NÃO VERIFICADO (aguardando você)`.

### 2b. Robustez de entrega (garantia, não instrução)

5. **"Validado" exige repetibilidade.** Uma entrega só é `VERIFICADO` se passar em **teste automatizado** que roda de forma determinística e repetível (ex.: CI). Uma execução manual única NÃO conta como validação. *(antiga 1b.1)*
6. **Comportamento determinístico obrigatório.** Se um comportamento pode depender do LLM "obedecer" o prompt (ex.: "não exibir regras internas"), ele **deve ser forçado no código** (filtro/enforcement), NÃO apenas instruído no prompt. O prompt instrui; o código garante. *(antiga 1b.2)*
   - **Código, obrigatório:** tudo que afeta a **correção dos dados** ou a **segurança** (o que é retornado, filtrado, calculado, autorizado ou isolado por tenant).
   - **Prompt, aceito:** o que for **estilo e apresentação** (formato, tom, ordem, tabela x lista, escolha de palavras). Fica **sempre marcado `NÃO VERIFICADO (depende do LLM)`** e nunca é declarado `VERIFICADO` (o LLM é probabilístico; uma execução, ou várias, com LLM real não são prova repetível — 2.5).
   - Se houver dúvida sobre em qual dos dois lados um comportamento cai, vale a 2.7: PARAR e perguntar ao responsável.
7. **Dúvida de robustez obriga a perguntar.** Se houver risco de a entrega não ser garantida (LLM probabilístico, limitação técnica, ambiguidade), PARAR e perguntar ao responsável — sem exceção. *(antiga 1b.3)*
8. **Veracidade (paridade com a fonte) é obrigatória.** Teste de contagem/estrutura/ausência de padrões NÃO prova correção. Toda entrega de dados deve ter a saída **comparada registro a registro com a fonte real** (banco/RBAC/tela), verificando que os VALORES retornados são exatamente os da fonte — não apenas "tem N registros" nem "tem a coluna X". Critérios: *(antiga 1b.4)*
   - "N registros presentes" **nunca** é critério de correção;
   - a paridade (campo a campo, registro a registro) é **parte obrigatória** da declaração de `VERIFICADO`;
   - se a paridade não for implementável no teste unitário (ex.: banco de teste vazio), a entrega fica **`NÃO VERIFICADO (aguardando auditoria contra o banco real)`** até que a comparação com a fonte seja executada e documentada;
   - a auditoria de conteúdo deve ser **repetida sempre que a fonte mudar** (novos registros, edições de permissões, mudanças de schema), não apenas na primeira validação.

### 2c. O arquivo atual é a fonte (não valores copiados)

9. **Nunca copiar/duplicar o valor default** de uma regra para o `agent_dominio` ou prompt — a regra deve **referenciar/ler o arquivo atual** (`Base::faixasPadrao()`, constante, etc.). *(antiga 4.1, 2ª parte)*
10. **Registrar a data da consulta.** Na rastreabilidade de cada regra, anotar **quando** o arquivo foi consultado (formato `YYYY-MM-DD`), para identificarmos mudanças futuras. Se uma regra for reutilizada depois, a data deve ser atualizada. *(antiga 4.2)*

### 2d. O que NÃO é permitido ao Agente de Programação

11. Copiar um valor default para o `agent_dominio`/prompt em vez de ler o arquivo atual. *(antiga 5, 2º item)*
12. **Declarar `VERIFICADO` com base apenas em contagem/estrutura/ausência de padrões** — sem comparar a saída registro a registro com a fonte real (2.8). *(antiga 5, 6º item)*
13. **Garantir só por instrução de prompt (ou descrição de ferramenta) algo que afete a correção dos dados ou a segurança** — isso exige código (2.6). *(antiga 5, 7º item)*
14. **Declarar `VERIFICADO` um comportamento de estilo/apresentação que dependa do LLM** — ele permanece `NÃO VERIFICADO (depende do LLM)` (2.6). *(antiga 5, 8º item)*

### 2e. Limite de alteração

15. **Não alterar nada fora do módulo `agent`.** O Agente de Programação não pode alterar nada fora do módulo `agent` (`modules/agent`), exceto se for expressamente determinado pelo responsável. *(nova, 2026-09-21)*

---

## 3. Obrigações do Agent de IA (execução)

Além da Seção 1, o Agent de IA é **somente leitura**: consulta (`SELECT`) e não cria, altera nem exclui registros, **exceto** pela única atividade de escrita autorizada abaixo.

1. **Permissão.** O Agent de IA pode cadastrar um `inventario_scope` (também chamado de inventário de dados ou processo). Nenhuma outra atividade de escrita está autorizada. *(nova, 2026-09-21)*
2. **Tabelas.** A escrita se limita às tabelas envolvidas no cadastro de um `inventario_scope`: `inventario_scope` (o processo e o seu percentual respondido), `scope` (somente o recálculo do percentual respondido do item do organograma) `log` (o registro da ação) e `agent_acao_pendente` (as pendências de confirmação do cadastro, tabela do próprio agente). Qualquer outra tabela é negada. *(nova, 2026-09-21; origem consultada em 2026-09-21: `controllers/InventarioDadosController.php:472-476`, `models/Scope.php:376-409`, `models/Base.php:94-114`)*
3. **Condições.** A ação é condicionada ao **`TenantGuard`** (só no cliente/contexto a que o usuário logado tem acesso) e ao **Soft Delete** (só considera registros ativos, nunca inativos). *(nova, 2026-09-21)*
4. **E-mail ao responsável.** O Agent de IA pode enviar e-mail ao responsável do `inventario_scope` cadastrado, e somente se houver endereço de e-mail informado no cadastro. Nenhum outro e-mail está autorizado. *(nova, 2026-09-21; origem consultada em 2026-09-21: `controllers/InventarioDadosController.php:458-469`, `mail/_inventario_scope.php`)*

---

## 4. Obrigações do responsável

1. **Definir critério de aceite** para cada entrega antes de começar. *(antiga 2.1)*
2. **Revisar o conhecimento/prompt** antes de valer em produção (o `agent_dominio` e o `systemPrompt` são decisão de produto/domínio). *(antiga 2.2)*
3. **Revisar por fase** — não só no fim. *(antiga 2.3)*

---

## 5. Fluxo de uma nova regra/conhecimento (Agente de Programação e responsável)

```
1. Identificar a referência no sistema (arquivo:linha / tabela / RBAC / tela)
2. VERIFICADO? ─ sim → registrar com origem + teste
                  └─ não → marcar "NÃO VERIFICADO (aguardando responsável)" e NÃO usar
3. Se dúvida → perguntar ao responsável antes de prosseguir
4. Revisão do responsável antes de valer em produção
```

*(antiga 3)*

---

## 6. Correspondência com a numeração anterior

Código, testes e documentos citam o contrato pela numeração antiga (ex.: `contrato §1b.4`). Essas referências continuam válidas e devem ser lidas por esta tabela:

| Numeração antiga | Onde está agora |
|---|---|
| 1.1 a 1.4 | 2.1 a 2.4 |
| 1.5 | 1.1 |
| 1b.1 a 1b.4 | 2.5 a 2.8 |
| 2 (1 a 3) | 4.1 a 4.3 |
| 3 | 5 |
| 4.1 | 1.6 e 2.9 |
| 4.2 | 2.10 |
| 4.3 | 1.7 |
| 5 (itens 1, 3, 4, 5) | 1.2 a 1.5 |
| 5 (itens 2, 6, 7, 8) | 2.11 a 2.14 |
| 6 (abertura) e 6.1 a 6.7 | removidas em 2026-09-21 (escrita pela IA) |

---

*Este contrato é vinculante a partir da assinatura. Qualquer violação deve ser corrigida e o `agent_dominio`/prompt auditado.*

*Alteração de 2026-09-21, por decisão do responsável: Seção 1b.2 (escopo "código obrigatório" x "prompt aceito") e duas linhas na Seção 5.*

*Alteração de 2026-09-21, por decisão do responsável: removida a escrita pela IA (a antiga Seção 6, as cláusulas correspondentes da Seção 2, o conteúdo da Seção 3 e a cláusula 4.4). O Agent de IA volta à premissa de somente leitura.*

*Alteração de 2026-09-21, por decisão do responsável: o contrato é entre o responsável e dois agentes (o Agente de Programação e o Agent de IA).*

*Alteração de 2026-09-21, por decisão do responsável: estrutura reorganizada por parte (Seção 1 comuns, 2 Agente de Programação, 3 Agent de IA, 4 responsável, 5 fluxo, 6 correspondência). Nenhuma cláusula foi removida; a numeração anterior está na Seção 6. A distribuição de cada cláusula entre as partes foi validada pelo responsável em 2026-09-21.*

*Alteração de 2026-09-21, por decisão do responsável: nova cláusula 2.15 (o Agente de Programação não pode alterar nada fora do módulo `agent`, exceto se for expressamente determinado).*

*Alteração de 2026-09-21, por decisão do responsável: a Seção 3 passa a autorizar uma única atividade de escrita, o cadastro de um `inventario_scope` pelo Agent de IA, limitada às tabelas envolvidas e condicionada ao `TenantGuard` e ao Soft Delete.*

*Alteração de 2026-09-21, por decisão do responsável: a Seção 3 passa a autorizar também o envio de e-mail ao responsável do `inventario_scope` cadastrado, se houver endereço de e-mail (cláusula 3.4).*

*Alteração de 2026-09-21, por decisão do responsável: a cláusula 3.2 passa a incluir a tabela `agent_acao_pendente` (pendências de confirmação do cadastro).*