policy-layer

name: policy-layer tier: full version: "1.0.0" description: "Especificação completa da camada de política de agentes — spend controls, rate limiting, tool access matrix e compliance checklist" license: Apache-2.0 metadata: owner: platform-governance version: "1.0.0" hseos: required_modes: [admin]

Policy Layer — Guia Completo

Quando usar

Carregue esta skill quando SABLE ou qualquer agente precisar:

• Auditar governance de agentes AI
• Configurar spend controls ou rate limiting
• Revisar ou atualizar a Tool Access Matrix
• Investigar acesso não autorizado a ferramenta
• Implementar HITL gates para operações destrutivas
• Validar configuração de settings.json para conformidade

PASSO 1 — Identificar o escopo da auditoria

Determinar o que está sendo auditado:

PASSO 2 — Spend Controls

Verificações obrigatórias:

• Existe daily spend cap por agente ou por projeto?
• Sessões têm limite de tempo? (ex: max 60 min por sessão autônoma)
• Custo é rastreado por role (ORBIT, KUBE, FORGE, etc.)?

Configuração de referência:

{
  "spend": {
    "daily_cap_usd": 5.00,
    "session_max_minutes": 60,
    "alert_threshold_usd": 3.00
  }
}

PASSO 3 — Rate Limiting

Verificações obrigatórias:

• APIs externas têm rate cap? (GitHub, Azure DevOps, Kubernetes)
• Há backoff logic para respostas 429?
• Operações bulk são batchadas para evitar burst?

Padrão HSEOS:

rate_limits:
  github_api: 30/min
  k8s_api: 20/min
  argocd_api: 10/min
  external_llm: 10/min

PASSO 4 — Tool Access (Least Privilege)

Verificações obrigatórias:

• Cada agente acessa apenas as ferramentas que precisa?
• Ferramentas destrutivas restritas a roles específicos?
• Acesso documentado em .claude/settings.json ou equivalente?

Tool Access Matrix (HSEOS canonical):

PASSO 5 — HITL Gates

Operações que obrigatoriamente requerem Human-In-The-Loop gate:

- kubectl delete (qualquer recurso)
- kubectl scale to 0
- git push --force
- git reset --hard
- docker rm / rmi (produção)
- DROP TABLE / truncate (banco)
- Modificar RBAC / permissões
- Deploy em prod sem aprovação explícita

Padrão de implementação do gate:

1. Agente descreve a operação destrutiva e o impacto
2. Agente aguarda confirmação explícita do usuário
3. Usuário confirma com "confirmar" ou "yes" (case-insensitive)
4. Agente executa e loga a ação com timestamp

PASSO 6 — Audit Trail

Verificações obrigatórias:

• Ações de agentes logadas com: timestamp, agent ID, tool chamado, resultado
• Tool calls rejeitados também logados (com motivo)
• Política de retenção definida para logs

Localização padrão HSEOS: .logs/agent-audit/YYYY-MM-DD.log

Formato de entrada:

[2026-04-25T05:49:00Z] KUBE kubectl apply -f manifests/prod/ → SUCCESS
[2026-04-25T05:49:01Z] FORGE gh pr create → SUCCESS (PR #42)
[2026-04-25T05:49:05Z] ORBIT kubectl delete → REJECTED (HITL gate — awaiting user)

PASSO 7 — Relatório de Compliance

Ao final da auditoria, gerar:

## Policy Layer Audit — [data]

**Agente/Projeto auditado:** [nome]
**Auditado por:** SABLE

### Spend Controls
- Status: [PASS / WARN / FAIL]
- [notas]

### Rate Limiting
- Status: [PASS / WARN / FAIL]
- [notas]

### Tool Access (Least Privilege)
- Status: [PASS / WARN / FAIL]
- Violações: [lista ou "nenhuma"]

### HITL Gates
- Status: [PASS / WARN / FAIL]
- [notas]

### Audit Trail
- Status: [PASS / WARN / FAIL]
- [notas]

### Ações Recomendadas
1. [ação prioritária]
2. [ação secundária]

Escalação

Escalar para SABLE (ou notificar o usuário) quando:

• Agente solicita acesso fora da sua coluna na Tool Access Matrix
• Spend cap atingido ou próximo (>80%)
• Operação destrutiva proposta sem HITL gate
• Audit logs ausentes para workflow concluído
• Tentativa de bypass de política detectada

Anti-patterns (NUNCA fazer)