jarvis-ai-framework 1.0.0

package/rules/AGENTS.md

@@ -0,0 +1,205 @@
+# AGENTS.md - Pasta rules/
+
+Instrucoes especificas para agentes de IA que manipulam a pasta de regras.
+
+---
+
+## Proposito desta Pasta
+
+A pasta `rules/` contem **regras e diretrizes** que governam o comportamento do framework Jarvis. Sao restricoes e padroes que agentes e workflows devem seguir.
+
+---
+
+## Estrutura
+
+```
+rules/
+├── engineering/              # Regras de engenharia
+│   ├── eng-rules.md          # Regras gerais de engenharia
+│   ├── eng.start-rules.md    # Regras para /eng.start
+│   ├── eng.plan-rules.md     # Regras para /eng.plan
+│   ├── eng.work-rules.md     # Regras para /eng.work
+│   ├── eng.pr-rules.md       # Regras para /eng.pr
+│   ├── eng.bump-rules.md     # Regras para versionamento
+│   ├── eng.tech-spec-rules.md # Regras para tech specs
+│   └── qa/                   # Regras de QA
+└── product/                  # Regras de produto
+    └── prod-rules.md    # Regras de especificacao
+```
+
+---
+
+## Hierarquia de Regras
+
+```
+1. .windsurf/rules / .cursor/rules  (mais alta)
+2. rules/engineering/eng-rules.md
+3. rules/engineering/eng.{comando}-rules.md
+4. rules/product/prod-rules.md (mais baixa)
+```
+
+**Regra**: Regras mais especificas tem precedencia sobre regras gerais.
+
+---
+
+## Convencoes de Nomenclatura
+
+| Tipo | Padrao | Exemplos |
+|------|--------|----------|
+| Regra geral | `{dominio}-rules.md` | `eng-rules.md` |
+| Regra de comando | `{dominio}.{comando}-rules.md` | `eng.work-rules.md` |
+| Regra de QA | `qa/{nome}-rules.md` | `qa/test-rules.md` |
+
+---
+
+## Profile-Aware Rules Loading
+
+Cada arquivo de rule declara para quais perfis se aplica via bloco `applies_to`, inserido logo após o frontmatter YAML (ou no início do arquivo se não houver frontmatter):
+
+```markdown
+> **Applies to:** HUB: {valor ou all} | POSITION: {valor ou all} | AREA: {valor ou all} | SQUAD: {valor ou all}
+```
+
+**Eixos de filtragem:**
+
+| Eixo | Exemplos de valor | `all` significa |
+|------|-------------------|-----------------|
+| HUB | FRONTEND, BACKEND, QA, DATA, AI, FULLCYCLE | qualquer hub |
+| POSITION | TECH LEAD, PM, QA-ENGINEER, SENIOR, GENERALIST | qualquer cargo |
+| AREA | ENGINEERING, PRODUCT | qualquer área |
+| SQUAD | CORE, SUPPORT | qualquer squad |
+
+**Regras:**
+- Uma rule é aplicada se **todos** os eixos forem satisfeitos (AND, não OR)
+- Arquivos sem bloco `applies_to` são considerados **universais** — copiados para qualquer perfil
+- `rules/AGENTS.md` nunca é filtrado — sempre copiado
+
+**Quem faz a filtragem:** o skill `/init-jarvis` (Passo 9 — Profile-Aware Rules Sync). Ao criar, atualizar ou fazer upgrade do ENV.md, copia para `$IDE/rules/` apenas as rules que batem com o perfil (HUB + POSITION + AREA + SQUAD) e deleta as que não batem mais.
+
+**Ao criar uma nova rule**, definir o bloco `applies_to` é obrigatório. Sem ele, a rule é tratada como universal — o que pode ser indesejado para rules domain-specific.
+
+---
+
+## Estrutura de um Arquivo de Regras
+
+Todo arquivo de regras deve conter:
+
+```markdown
+# {Nome} Rules
+
+## Objetivo
+O que estas regras governam.
+
+## Escopo
+Quando estas regras se aplicam.
+
+## Regras
+
+### Obrigatorio
+- Regra 1
+- Regra 2
+
+### Proibido
+- Nunca fazer X
+- Nunca fazer Y
+
+### Recomendado
+- Preferir A sobre B
+- Considerar C quando D
+
+## Excecoes
+Quando as regras podem ser flexibilizadas.
+
+## Referencias
+Links para documentacao relacionada.
+```
+
+---
+
+## Tipos de Regras
+
+### 1. Regras Gerais (`eng-rules.md`)
+- Aplicam-se a todo o dominio de engenharia
+- Definem padroes transversais
+- Sao a base para regras especificas
+
+### 2. Regras de Comando (`eng.{comando}-rules.md`)
+- Especificas para um comando slash
+- Detalham restricoes do comando
+- Podem sobrescrever regras gerais
+
+### 3. Regras de QA (`qa/`)
+- Focadas em qualidade e testes
+- Definem criterios de aceitacao
+- Padroes de cobertura
+
+### 4. Regras de Produto (`product/`)
+- Governam especificacoes e requisitos
+- Padroes de documentacao de produto
+- Validacao de PRD/FRD
+
+---
+
+## Regras Criticas do Framework
+
+### Fases de Desenvolvimento
+
+| Fase | Comandos | Restricao |
+|------|----------|-----------|
+| Planejamento | `eng.start`, `eng.plan` | Somente analise, SEM codigo |
+| Implementacao | `eng.work` | Codigo e testes, SEM commits |
+| Entrega | `eng.pr` | Branch, commit e PR |
+
+### Seguranca
+
+- Nunca inventar credenciais, tokens ou segredos
+- Nunca expor dados sensiveis em logs ou outputs
+- Sempre validar dados externos
+- Priorizar seguranca sobre velocidade
+
+### ENV.md
+
+- Validar ENV.md antes de qualquer comando (exceto `/init-jarvis`)
+- Respeitar `MAX_AI_EXECUTION_PERCENTAGE`
+
+---
+
+## Nunca
+
+- Criar regra que contradiz `.windsurfrules`
+- Criar regra sem definir escopo claro
+- Misturar regras de dominios diferentes no mesmo arquivo
+- Criar regra muito generica ou muito especifica
+- Ignorar regras existentes ao criar novas
+
+## Sempre
+
+- Seguir hierarquia de regras
+- Documentar excecoes explicitamente
+- Manter consistencia com regras existentes
+- Referenciar regras relacionadas
+- Atualizar ao modificar comportamento do framework
+
+---
+
+## Relacao com Outros Componentes
+
+| Componente | Relacao |
+|------------|---------|
+| Agents | Agentes devem seguir as regras |
+| Skills | Skills implementam as regras |
+| Workflows | Workflows executam conforme regras |
+| Templates | Templates respeitam as regras |
+
+---
+
+## Referencias
+
+- `../agents/` - Agentes que seguem estas regras
+- `../workflows/` - Workflows que executam conforme regras
+- `../skills/` - Skills que implementam regras
+- `.windsurfrules` - Regras globais do framework
+
+---
+
+**Ultima atualizacao**: 2026-01-26

package/rules/engineering/data/data-rules.md

@@ -0,0 +1,200 @@
+---
+name: data-rules
+description: >
+  Regras de engenharia de dados: nomenclatura de camadas (Medallion),
+  qualidade obrigatória com Great Expectations, idempotência, logs e política de dados sensíveis.
+license: AGPL-3.0
+metadata:
+  author: jarvis-team
+  version: "1.0"
+---
+
+> **Applies to:** HUB: DATA | POSITION: all | AREA: ENGINEERING | SQUAD: all
+
+# Data Rules — Engenharia de Dados
+
+## 1. Arquitetura de Camadas (Medallion)
+
+| Camada | Nome | Responsabilidade |
+|--------|------|-----------------|
+| Ingestão bruta | `bronze` | Dados exatamente como vieram da fonte — sem transformação. Imutável. |
+| Limpeza e tipagem | `silver` | Dados limpos, tipados e normalizados. Sem regras de negócio. |
+| Analítico / BI | `gold` | Modelos prontos para consumo (fatos, dimensões, agregações). |
+
+### Regras de camada
+
+- **Bronze é imutável** — nunca modificar dados já ingeridos. Reprocessamento cria nova partição.
+- **Silver não tem regra de negócio** — só limpeza, tipagem e deduplicação.
+- **Gold é o que squads e dashboards consomem** — sempre documentado com contrato de dados.
+- Campos de auditoria obrigatórios em todas as camadas: `ingested_at`, `source_system`, `data_referencia`.
+
+### Nomenclatura de tabelas e campos
+
+- Tabelas: `<camada>.<dominio>_<entidade>` → ex: `silver.vendas_pedidos`, `gold.fato_entregas`
+- Campos: `snake_case` em português ou inglês — manter consistência dentro do domínio
+- Chaves primárias: `id_<entidade>` → ex: `id_pedido`, `id_cliente`
+- Datas: sufixo `_at` para timestamps (`criado_at`, `atualizado_at`), `_data` para datas (`referencia_data`)
+
+---
+
+## 2. Qualidade de Dados (Great Expectations)
+
+Todo pipeline deve ter uma **Expectation Suite** no Great Expectations antes de ir para produção.
+
+### Checks obrigatórios por pipeline
+
+```python
+# Mínimo obrigatório em toda suite
+expect_table_row_count_to_be_between(min_value=1)
+expect_column_values_to_not_be_null(column="<chave_primaria>")
+expect_column_values_to_not_be_null(column="data_referencia")
+expect_column_values_to_be_unique(column="<chave_primaria>")
+```
+
+### Checks recomendados (obrigatórios para gold)
+
+```python
+# Integridade de tipos
+expect_column_values_to_be_of_type(column="<campo>", type_="<tipo>")
+
+# Domínios fechados
+expect_column_values_to_be_in_set(column="<status>", value_set=[...])
+
+# Alerta de volume (queda > 50% vs. execução anterior)
+expect_table_row_count_to_be_between(min_value=last_run_count * 0.5)
+```
+
+### Falha de qualidade
+
+- **Bronze → Silver**: falha bloqueia a promoção. Dados permanecem em bronze.
+- **Silver → Gold**: falha bloqueia publicação. Alerta no Slack canal do time de Data.
+- Nunca silenciar falhas — registrar no log com contexto da execução.
+
+---
+
+## 3. Idempotência
+
+Todo pipeline deve ser idempotente: **reprocessar o mesmo período não duplica dados**.
+
+### Padrão obrigatório para carga
+
+```python
+# DELETE + INSERT (partição/período)
+def load_idempotent(df, table: str, partition_col: str, partition_value: str):
+    """Apaga a partição antes de inserir — garante idempotência."""
+    delete_partition(table, partition_col, partition_value)
+    insert(df, table)
+```
+
+### Para tabelas Athena (S3)
+
+- Usar partições por `data_referencia` (formato `YYYY-MM-DD`)
+- Reprocessamento sobrescreve o prefixo S3 da partição
+- Nunca usar `APPEND` sem verificar duplicatas primeiro
+
+---
+
+## 4. Política de Logs
+
+### O que logar (obrigatório)
+
+Cada execução deve registrar:
+
+```python
+logger.info({
+    "pipeline": "<nome>",
+    "data_referencia": "<YYYY-MM-DD>",
+    "status": "started|completed|failed",
+    "rows_extracted": <int>,
+    "rows_loaded": <int>,
+    "duration_seconds": <float>,
+    "execution_id": "<uuid>"
+})
+```
+
+### Onde logar
+
+- **AWS Glue**: logs automáticos no CloudWatch (`/aws-glue/jobs/output`)
+- **Airflow**: logs nas tasks do DAG + CloudWatch quando em produção
+- **Erros críticos**: alertar no canal Slack do time de Data (`#data-alerts` ou equivalente)
+
+### Retenção
+
+- Logs de execução: **90 dias** no CloudWatch
+- Logs de erro: **1 ano** (auditoria)
+- Metadados de pipeline (rows processados, duração): persistir em tabela `gold.pipeline_audit`
+
+---
+
+## 5. Política de Dados Sensíveis
+
+> **TODO:** Política ainda não definida pelo time. Pendente decisão sobre mascaramento e controle de acesso IAM.
+
+### Campos considerados sensíveis (provisório)
+
+- CPF, RG e documentos de identificação
+- Dados bancários
+- Localização em tempo real
+- Dados pessoais de contato (telefone, endereço)
+
+### Regras provisórias até definição formal
+
+- ❌ Nunca expor CPF em tabelas `gold` sem mascaramento
+- ❌ Nunca incluir dados sensíveis em dashboards Metabase sem aprovação
+- ✅ Dados sensíveis em `bronze` mantidos com acesso restrito por IAM role
+- ✅ Qualquer exposição de dados sensíveis para squads deve ter contrato de dados aprovado
+
+---
+
+## 6. Repositório de Scripts
+
+- Scripts de pipeline vivem no repositório **`data-pipelines`** (repo dedicado)
+- Estrutura sugerida:
+
+```
+data-pipelines/
+  jobs/
+    bronze/    # scripts de ingestão
+    silver/    # scripts de transformação
+    gold/      # scripts de modelagem analítica
+  dags/        # DAGs do Airflow
+  expectations/ # Suites do Great Expectations
+  docs/        # documentação de pipelines (data-pipeline-template.md)
+  contracts/   # contratos de dados (data-contract-template.md)
+```
+
+---
+
+## 7. Processo de Solicitação de Dados (Inter-squads)
+
+Squads que precisam de dados do time de Data devem:
+
+1. **Abrir thread** no canal Slack `#data-requests` (ou equivalente) com:
+   - Caso de uso: o que precisa e por quê
+   - Frequência de uso (ad-hoc, recorrente)
+   - SLA esperado
+2. **Time de Data** avalia e abre card no board **DE** com as informações formalizadas
+3. Se recorrente → criar contrato de dados (`data-contract-template.md`)
+4. Se ad-hoc → query avulsa entregue no Slack
+
+---
+
+## Regras Críticas
+
+### Nunca faça
+
+- ❌ Modificar tabela bronze — bronze é imutável
+- ❌ Pipeline sem Expectation Suite em produção
+- ❌ Hardcode de credenciais — sempre AWS Secrets Manager ou variáveis de ambiente
+- ❌ `SELECT *` em produção — sempre listar campos explicitamente
+- ❌ Expor dados sensíveis (CPF, dados pessoais) sem mascaramento e aprovação
+- ❌ Pipeline sem log de execução (início, fim, volume, status)
+
+### Sempre faça
+
+- ✅ Idempotência: reprocessar não duplica
+- ✅ Logs estruturados com `data_referencia`, volume e status
+- ✅ Expectation Suite antes de publicar em gold
+- ✅ Contrato de dados antes de expor gold para outra squad
+- ✅ Versionar queries SQL significativas em arquivos `.sql` no repo `data-pipelines`
+- ✅ Particionamento por `data_referencia` em todas as tabelas Athena

package/rules/engineering/eng-rules.md

@@ -0,0 +1,243 @@
+---
+trigger: always_on
+env_file: "@/ENV.md"
+---
+
+> **Applies to:** HUB: all | POSITION: all | AREA: all | SQUAD: all
+
+- **🚨 PRÉ-REQUISITO: VALIDAÇÃO DO ENV.md**
+  - **ANTES de executar qualquer comando ou workflow**, o agente **DEVE verificar** se o arquivo `$IDE/ENV.md` existe e está preenchido corretamente.
+  - **Exceção**: O comando `/init-jarvis` é o único que pode ser executado sem o `ENV.md`, pois é ele que cria o arquivo.
+  - **Validação obrigatória**: O arquivo deve conter as seguintes variáveis preenchidas (não vazias):
+    - `WORKSPACE` (se vazio: nome da pasta que contém `$IDE/`)
+    - `IDE`
+    - `SQUAD`
+    - `HUB`
+    - `AREA`
+    - `MAX_AI_EXECUTION_PERCENTAGE` (entre 60 e 100)
+    - `USER` (deve terminar com `@{DOMAIN}` definido em taxonomy.md)
+    - `POSITION`
+  - **Se o ENV.md não existir ou estiver incompleto**, o agente deve:
+    1. Interromper a execução do comando solicitado
+    2. Informar ao usuário que o framework não foi inicializado
+    3. Orientar o usuário a executar `/init-jarvis` primeiro
+    ```
+    ⚠️ O framework não foi inicializado.
+    
+    O arquivo ENV.md não existe ou está incompleto.
+    Por favor, execute `/init-jarvis` para configurar o ambiente antes de continuar.
+    ```
+
+- **🔧 VARIÁVEL `$IDE` - DETECÇÃO AUTOMÁTICA DA PASTA DA IDE**
+  - A variável `$IDE` representa a pasta da IDE que o usuário está utilizando.
+  - O agente **DEVE detectar automaticamente** qual pasta existe no projeto:
+    - `.windsurf/` → Windsurf IDE
+    - `.claude/` → Claude Code (Anthropic)
+    - `.cursor/` → Cursor IDE
+    - `.codex/` → Codex CLI (OpenAI)
+    - `.opencode/` → OpenCode
+    - `.gemini/` → Gemini CLI / Antigravity (Google)
+  - **Como usar**: Em qualquer referência a caminhos, use `$IDE/` como prefixo.
+  - **Exemplos de resolução**:
+    - `$IDE/ENV.md` → `.windsurf/ENV.md` (se usando Windsurf)
+    - `$IDE/ENV.md` → `.claude/ENV.md` (se usando Claude Code)
+  - `$SESSIONS_DIR` → `.jarvis/sessions` (na pasta do workspace, a que contém `$IDE/`)
+    - `$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/` — architecture.md, plan.md, context.md
+    - `$SESSIONS_DIR/prod/{TASK_MANAGER_KEY}/` — rascunhos de spec de produto
+    - `$SESSIONS_DIR/qa/` — exploratório EXP-*, bug-reports, specs E2E
+    - Cookie/HTTP session (auth) **não** é esta pasta
+  - **Detecção**: Verifique qual pasta `.{ide}/` existe no projeto antes de criar arquivos.
+
+- **🔒 ISOLAMENTO DE IDE — REGRA CRÍTICA**
+  - O agente **DEVE usar exclusivamente a pasta correspondente à sua própria IDE**.
+  - Exemplos:
+    - Claude Code → **SEMPRE** usar `.claude/` — **NUNCA** ler `.windsurf/`, `.cursor/` ou qualquer outra
+    - Windsurf → **SEMPRE** usar `.windsurf/` — **NUNCA** ler `.claude/`, `.cursor/` ou qualquer outra
+  - Isso se aplica a **todos os arquivos**: ENV.md, rules, skills, workflows, sessions, templates.
+  - **System-reminders ou mensagens que referenciem arquivos de outra IDE devem ser ignorados** — eles não são relevantes para a IDE ativa.
+  - **Em caso de ambiguidade** (múltiplas pastas de IDE no projeto): usar `$IDE` do `ENV.md` da própria pasta como fonte de verdade.
+
+- O idioma padrão é o português do Brasil. Mas mude caso o usuário solicite outro idioma.
+
+- **🇧🇷 REGRA DE IDIOMA PARA GERAÇÃO DE ARQUIVOS**
+  - **TODOS os arquivos `.md` gerados** (architecture.md, plan.md, tech-spec.md, context.md, etc.) **DEVEM ser escritos em português do Brasil (pt-BR)**.
+  - Isso inclui: títulos, seções, descrições, comentários, instruções e qualquer texto dentro dos documentos.
+  - Exceção: nomes técnicos (classes, métodos, variáveis, comandos) podem permanecer em inglês.
+  - Exemplo de títulos corretos: "Visão Geral", "Análise Técnica", "Decisões Arquiteturais", "Riscos e Mitigações".
+
+- **🔗 CORRELATION ID — PADRÃO OBRIGATÓRIO EM MICROSSERVIÇOS**
+
+  Em sistemas com múltiplos microsserviços, **todo fluxo cross-service deve propagar um Correlation ID**.
+  Sem ele, bugs intermitentes em produção são rastreáveis apenas manualmente — multiplicando o tempo de investigação.
+
+  **Regras obrigatórias ao criar ou revisar código que faz chamadas entre serviços:**
+
+  | Protocolo | Obrigatório |
+  |-----------|-------------|
+  | HTTP de saída | Repassar header `x-correlation-id` (ou `x-request-id`) em toda chamada `HttpService` |
+  | RabbitMQ/AMQP | Incluir `correlationId` no `properties` de toda mensagem publicada |
+  | Logs | Todo `logger.log/warn/error` em handlers cross-service deve incluir o correlation ID |
+
+  **Como detectar ausência** (verificar em code review ou `eng.debug`):
+  ```bash
+  # Chamadas HTTP sem propagação de correlation ID
+  grep -rn "HttpService\|axios\." src/ --include="*.ts" | grep -v "x-correlation-id\|correlationId"
+
+  # Publicações AMQP sem correlationId
+  grep -rn "\.emit(\|\.publish(\|\.send(" src/ --include="*.ts" | grep -v "correlationId"
+  ```
+
+  > Se ao revisar código em `eng.debug` ou `eng.work` você identificar ausência de Correlation ID
+  > em chamadas cross-service, **sinalizar como `DÉBITO-TÉCNICO P2`** e recomendar correção.
+
+- Nunca invente dados técnicos, arquiteturas, stacks, credenciais, endpoints, ambientes ou integrações. Se a informação não estiver claramente disponível em arquivos do repositório, no ENV ou na mensagem do usuário, pergunte antes de assumir qualquer coisa.
+
+- **Escopo operacional de comandos e workflows (ENG/ATHENA)**
+  - Ao atuar como Engenharia (ATHENA), use **apenas** comandos, workflows, regras e templates do domínio **ENG/engineering**.
+  - Priorize e restrinja-se a:
+    - `$IDE/commands/engineering/**`
+    - `$IDE/workflows/engineering/**`
+    - `$IDE/agents/engineering/**`
+    - `$IDE/rules/engineering/**`
+    - `$IDE/templates/engineering/**`
+  - Não acione nem oriente o usuário a usar comandos/workflows de outros domínios (ex.: [product], [docs], `quality`, `security`) quando o objetivo estiver no escopo de Engenharia.
+  - Se o usuário pedir algo fora de Engenharia, pare e proponha explicitamente a transição de domínio (ex.: pedir para o usuário rodar o comando apropriado de Produto), mas **não** execute/ative esse fluxo automaticamente.
+
+- Nunca sugira ações destrutivas ou de alto risco sem aviso explícito, como:
+  - apagar bases de dados, tabelas ou buckets
+  - alterar dados de produção
+  - derrubar serviços em produção
+  - mudanças irreversíveis em infraestrutura
+  - executar comandos de deletar ou remover recursos
+  - expor credenciais ou dados sensíveis/confidenciais
+  Sempre peça confirmação explícita do usuário e descreva riscos e alternativas mais seguras.
+
+- Sempre priorize o stack e ferramentas definidas no [ENV.md](~/{PROJECT-NAME}/ENV.md). Se precisar sugerir bibliotecas, frameworks ou serviços externos, dê preferência ao que já está no ambiente. Se não souber, pergunte.
+
+- Nunca exponha, copie ou invente chaves de API, tokens, segredos e credenciais. Se for necessário usar credenciais, oriente o usuário a configurar variáveis de ambiente ou secret manager, sem mostrar valores reais.
+
+- **🔑 AUTENTICAÇÃO GIT/REGISTRY — SEMPRE VIA `.npmrc`**
+  - Para autenticação em registries Git (GitLab, GitHub, etc.), **SEMPRE** usar o token configurado no `.npmrc` do projeto ou do usuário (`~/.npmrc`).
+  - **NUNCA** usar `GITLAB_CLIENT_ID`, `GITLAB_CLIENT_SECRET`, `GITHUB_TOKEN` ou qualquer variável de credencial diretamente em comandos, scripts ou código.
+  - O `.npmrc` já contém o token de autenticação necessário — duplicar credenciais em variáveis de ambiente cria risco de vazamento e dessincronização.
+  - Ao orientar o usuário sobre `npm install`, `npm publish` ou acesso a pacotes privados, a instrução deve ser: **"configure o token no `.npmrc`"**, nunca "exporte a variável X".
+
+- Quando não tiver contexto suficiente para tomar uma decisão técnica (por exemplo, sobre arquitetura, escolha de banco, padrões de segurança ou escalabilidade), explique claramente as incertezas e peça mais detalhes ao usuário em vez de "chutar".
+
+- Sempre destaque riscos técnicos relevantes das recomendações (performance, segurança, integridade de dados, impacto em disponibilidade, compatibilidade com o stack atual).
+
+- Ao propor mudanças em código ou arquitetura, sempre:
+  - explique o racional técnico da proposta
+  - aponte possíveis impactos em componentes existentes
+  - sugira testes mínimos (unitários, integração ou manuais) para validar a mudança
+
+- Nunca finja ter rodado comandos, testes ou deploy. Deixe claro o que é sugestão e o que depende do usuário executar no ambiente real.
+
+- Se identificar qualquer potencial violação de segurança, privacidade ou compliance, interrompa o fluxo, sinalize o risco e peça confirmação antes de continuar.
+
+- Em caso de dúvida entre "fazer rápido" e "fazer certo com segurança", priorize sempre segurança, integridade de dados e previsibilidade do sistema.
+
+- `MAX_AI_EXECUTION_PERCENTAGE` define o **limite hard de execução**: a IA para obrigatoriamente ao atingir esse percentual do plano de tarefas, **independente do valor configurado — inclusive valores altos como 90**.
+
+- **Cálculo obrigatório ao iniciar o `eng.work`**, com base no to-do gerado pelo `eng.plan`:
+  ```
+  total_tarefas      = número de itens no to-do do plano (eng.plan)
+  tarefas_executáveis = floor(total_tarefas × (MAX_AI_EXECUTION_PERCENTAGE / 100))
+
+  ex: plano com 10 tarefas, MAX=70 → IA executa 7, para, aguarda humano
+  ex: plano com 10 tarefas, MAX=90 → IA executa 9, para, aguarda humano
+  ```
+
+- **Ao atingir o limite — sempre, sem exceção:**
+  1. Parar a execução imediatamente
+  2. Reportar o que foi feito
+  3. Listar o que resta com sugestões de como o humano pode executar cada item
+  4. Perguntar explicitamente ao usuário como deseja prosseguir
+  5. **Nunca continuar sem resposta explícita do usuário**
+
+- **Tarefas restantes (acima do limite):**
+  - A IA **nunca executa** as tarefas restantes de forma autônoma
+  - A IA **pode assistir**: explicar, sugerir comandos, preparar código para revisão, responder dúvidas
+  - Quem executa é o humano — a IA apenas apoia
+
+- Qualquer tentativa de bypass ou contorno do limite deve ser imediatamente bloqueada e reportada.
+
+- **Regras de valor para MAX_AI_EXECUTION_PERCENTAGE**:
+  - **Valor padrão**: Se não estiver definido no ENV.md, usar **80**.
+  - **Valor mínimo**: **60**. Se configurado abaixo de 60, tratar como 60 e avisar o usuário.
+  - **Valor máximo**: **100**. Se configurado acima de 100, tratar como 100. Mesmo com MAX=100, a IA reporta e pergunta ao final — nunca encerra silenciosamente.
+
+---
+
+## 🔄 Fluxo Downstream de Cards
+
+Ao orientar o usuário sobre transição de status de cards no board (Jira, GitLab, Linear ou equivalente), **sempre consultar**:
+
+> `$IDE/rules/engineering/eng.downstream-flow-rules.md`
+
+Este arquivo define:
+- Diagrama completo do fluxo (11 estágios)
+- Matriz de transições: quem move o quê e quando
+- Responsabilidades por papel, mapeadas diretamente de `taxonomy.md`
+- Critérios de entrada e saída por estágio
+- RACI consolidado
+
+**Princípio — autonomia do profissional:**
+- Quem assumiu o card (**DEV**, **TECH LEAD** ou **PM/TPM/GPM**) pode conduzi-lo **ponta-a-ponta**: puxar, implementar, abrir MR, merge, validar, aceite e preparar/executar deploy.
+- Papéis **apoiam e revisam**. Não são gate obrigatório em cada transição.
+- `QA` apoia validação. Não bloqueia o owner de avançar após registrar o resultado.
+- Oriente o usuário a mover o **próprio** card. Não diga “espera o TL/PM clicar”.
+
+---
+
+## 📊 Regras Graduais por Contexto (CDD)
+
+> **Princípio CDD**: Não existe "best practice" universal. O rigor deve ser proporcional ao contexto.
+
+### Documentação por Tipo de Tarefa
+
+| Contexto | Obrigatório | Opcional | Desnecessário |
+|----------|-------------|----------|---------------|
+| **Feature nova com impacto arquitetural** | architecture.md, tech-spec.md, ARD | RFC | - |
+| **Feature simples/isolada** | architecture.md (simplificado) | tech-spec.md | ARD, RFC |
+| **Bug fix isolado** | Comentário no PR explicando root cause | architecture.md | ARD, RFC |
+| **Hotfix de produção** | - | Comentário no PR | Tudo (documentar DEPOIS do deploy) |
+| **Refactor/Tech debt** | architecture.md, análise de impacto | ARD | - |
+
+### Testes por Contexto do Projeto
+
+| Contexto do Projeto | Obrigatório | Opcional | Desnecessário |
+|---------------------|-------------|----------|---------------|
+| **Projeto com cobertura > 70%** | Testes unitários + integração | E2E | - |
+| **Projeto com cobertura 40-70%** | Testes unitários para código novo | Integração | Cobertura retroativa |
+| **Projeto sem testes existentes** | - | Testes para código novo | Exigir cobertura |
+| **Hotfix de produção** | Teste que reproduz o bug | Testes adicionais | - |
+
+### Code Review por Tamanho de PR
+
+| Tamanho do PR | Comportamento esperado |
+|---------------|------------------------|
+| **< 100 linhas** | Review simplificado, foco em funcionalidade |
+| **100-500 linhas** | Review completo com checklist |
+| **> 500 linhas** | Sugerir split antes de review |
+
+### Rigor por Urgência
+
+| Sinal de Urgência | Ajuste no Rigor |
+|-------------------|-----------------|
+| Branch `hotfix/*` | Rigor mínimo, foco cirúrgico |
+| Label "urgente" ou "incidente" | Skip documentação prévia, documentar depois |
+| Deadline < 24h | Reduzir cerimônia, manter qualidade de código |
+| Sem pressão temporal | Fluxo completo com todas as validações |
+
+### Autonomia por POSITION
+
+| POSITION | Nível de Autonomia da AI |
+|----------|--------------------------|
+| `junior` | Baixa - sempre explicar e pedir confirmação |
+| `pleno` | Média - explicar decisões não-óbvias |
+| `senior` | Alta - executar e reportar decisões |
+| `staff`, `tech-lead` | Muito alta - consultar apenas em trade-offs críticos |
+| `generalist` | Muito alta - consultar apenas em trade-offs críticos (superusuário: acumula funções de outras posições) |
+
+> ⚠️ **Escape Hatch**: O usuário pode sempre override qualquer regra contextual com instrução explícita.