Documentação / Qualidade e governança

Contrato de qualidade

As regras de qualidade ficam em um arquivo versionado do repositório, não no prompt, e valem igualmente para pessoas e agentes.

O contrato de qualidade é o arquivo .ai/contract.json do seu projeto. Ele define quanto rigor a equipe exige: limites de medição, cobertura, complexidade, tamanho das alterações, caminhos protegidos e exceções.

Ele é aplicado pelo gate do motor, pelos hooks do Git, pela CI e pelos agentes. O resultado não depende de quem escreve o código: uma pessoa, o Yuli, o Claude Code, o Codex, o Kiro ou o Antigravity.

Se o arquivo não existir ou não for válido, o Yuli usa os valores padrão (criticidade Negócio). Cada campo é opcional, então um contrato parcial também funciona.

Onde editar

Abra a Central de Governança (trilho direito → Mais ferramentas, ou a paleta de comandos com Abrir a Central de Governança) e entre na aba Contrato.

Ao salvar com Salvar e assinar, o Yuli registra a alteração com o seu git config user.name. Você pode ver todas as alterações em Histórico do contrato.

Criticidade

A criticidade escolhe um perfil completo de limites. Há quatro níveis:

Valor no arquivo Rótulo no Yuli Quando usar
low Baixa Protótipos, ferramentas internas, experimentos.
business Negócio Aplicações de negócio. É o valor padrão.
regulated Regulada Sistemas sujeitos a auditoria ou regulação.
safety Segurança crítica Software em que uma falha tem consequências graves.

Perfis

Limite Baixa Negócio Regulada Segurança crítica
Pontuação de aceitação 80 90 92 95
Rodadas de medição 2 3 4 5
Cobertura mínima 50 % 70 % 80 % 90 %
Complexidade cognitiva máx. 20 15 15 10
Complexidade ciclomática máx. 15 10 10 8
Mutação mínima 0 % 0 % 60 % 75 %
Arquivos por alteração 60 40 25 15
Linhas por alteração 2000 1000 600 400
Revisão independente Não Não Sim Sim
Bloquear trapaças em testes Não Sim Sim Sim
Aplicação estrita Não Não Sim Sim

Você pode substituir um limite específico em gates. Só esse campo muda; o restante continua vindo do perfil. Bloquear trapaças em testes e Aplicação estrita dependem apenas da criticidade e não podem ser substituídos.

A pontuação de aceitação e as rodadas do contrato substituem as configurações locais da fase de Medição.

Estrutura do arquivo

{
  "schemaVersion": 1,
  "criticality": "business",
  "gates": { "minCoverage": 75, "maxCyclomatic": null },
  "changeLimits": { "maxFiles": 40, "maxLines": 1000 },
  "protectedPaths": ["db/migrations/**"],
  "waivers": []
}
Campo O que define
criticality low, business, regulated ou safety.
gates acceptanceScore, maxMeasureRounds, minCoverage, maxCognitive, maxCyclomatic, requireIndependentReview, minMutationScore. null usa o valor do perfil.
changeLimits maxFiles e maxLines por alteração.
protectedPaths Globs extras, que se somam aos protegidos por padrão.
waivers Exceções com vencimento.
architecture Camadas (layers com name, paths, mayDependOn) e forbidCycles.
slos Objetivos de serviço: latencyP95Ms, availability ou errorRate.
licensePolicy Licenças permitidas (allow) e proibidas (deny), por SPDX ou por família, como strong-copyleft.
reviewer Revisor independente: requireOtherFamily, provider, model.
dataClassification Padrões de dados com seu nível: public, internal, confidential ou restricted.
finops Orçamento mensal por serviço e seu responsável.

Limites de alteração

O tamanho de uma alteração é medido com git diff --numstat. Os arquivos de lock (package-lock.json, yarn.lock, Cargo.lock, go.sum e similares) contam como arquivos, mas suas linhas não.

Ultrapassar o limite bloqueia com aplicação estrita (Regulada e Segurança crítica). Nos demais perfis, é um aviso.

Caminhos protegidos

Um agente não pode editar estes arquivos, mesmo que peçam a ele:

  • .ai/contract.json, .ai/quality.json e .ai/state/**
  • .claude/settings.json e .claude/settings.local.json
  • .githooks/**
  • .github/workflows/**, .gitlab-ci.yml e Jenkinsfile
  • CODEOWNERS e .github/CODEOWNERS

A comparação ignora maiúsculas e minúsculas. Adicione seus próprios caminhos em protectedPaths. Uma alteração no contrato salva pelo Yuli fica registrada na auditoria e conta como aprovada.

Exceções (waivers)

Uma exceção permite pular uma regra de forma temporária e justificada.

Campo Conteúdo
id Identificador da exceção.
rule Regra excetuada: secrets, protectedPaths, testIntegrity, um tipo específico de trapaça ou *.
path Glob ao qual se aplica. Vazio significa qualquer caminho.
reason Motivo.
approvedBy Quem a aprovou.
expires Data de vencimento, AAAA-MM-DD.
ticket Referência opcional.

Uma exceção vale até o dia de expires, inclusive. Uma data ausente ou mal escrita conta como vencida. Ao vencer, a regra volta a valer e o gate avisa.

Na interface, cada exceção mostra seu estado: Vigente, Vence em breve, Vencida ou Data inválida.

testIntegrity excetua todas as detecções de trapaças em testes de uma só vez. Use-a com um caminho restrito e uma data próxima.

Auditoria

Cada salvamento adiciona uma linha a .ai/state/contract-audit.jsonl com a data, o autor, o hash SHA-256 e um resumo (por exemplo, “criticality business→regulated; waivers +1”).

O autor é sempre uma pessoa: o nome informado ou o seu git config user.name. “Yuli” e “Yuli Code” são rejeitados como autores.

Próximo passo