aiox-core 5.0.5 → 5.0.7

package/pro/squads/squad-creator-pro/minds/oalanicolas/heuristics/AN_KE_062.md

@@ -0,0 +1,99 @@
+# AN_KE_062 - Explicit Nature Declaration
+**Zone:** 💎 4% Excelência | **Agent:** @oalanicolas
+**Source:** [SOURCE: sessões sinkra-hub f5cce682 (sinkra-chief meeting), 156cf1df (CodeRabbit brownfield)]
+
+## Purpose
+
+Toda interação com squad/processo DEVE começar declarando explicitamente a NATUREZA do trabalho. São exatamente 3 naturezas — não um espectro, não um híbrido. A sessão f5cce682 revelou que sem essa declaração, o sinkra-chief assume standalone por default e o pipeline inteiro roda no escopo errado. O fix não foi "comunicar melhor" — foi criar templates com campo obrigatório ("Contexto: brownfield" como campo explícito no prompt). A sessão 156cf1df prova adoção real: "*map-process modo brownfield para CodeRabbit" — a declaração virou parte natural do comando.
+
+## Configuration
+
+```yaml
+AN_KE_062:
+  name: "Explicit Nature Declaration"
+  zone: "excelencia"
+  trigger: "Iniciando trabalho com squad, processo, ou sistema que pode ter múltiplas naturezas."
+  sys_tension:
+    tension_with: "AN_KE_073 (Parallel Subagents for Throughput) vs Clareza Upfront de Natureza"
+    resolution: "Declarar apenas a natureza do trabalho (3 categorias mutualmente exclusivas), não inferir escopo. Maximize clareza na triagem inicial para minimizar retrabalho."
+
+  rule: |
+    SE iniciando trabalho com squad ou processo
+    ENTÃO declarar natureza EXPLICITAMENTE como campo obrigatório:
+      (1) standalone — squad/processo novo do zero
+      (2) brownfield — refatorando/melhorando squad/processo existente
+      (3) upgrade-pack / overlay — adicionando camada sobre base existente
+    Sem declaração → chief assume standalone → pipeline inteiro no escopo errado.
+    A declaração é CAMPO no template, não comunicação informal.
+
+  veto_condition:
+    trigger: "Iniciar pipeline/comando sem campo de natureza, ou natureza ambígua ('meio brownfield, meio standalone')."
+    action: "VETO — 'Se o caso for um upgrade-pack, você precisa dizer isso logo no início.' Declare: standalone, brownfield, ou upgrade-pack. Sem isso, BLOCK."
+
+  evidence:
+    - "[SOURCE: sessão f5cce682, sinkra-hub] 'Se o caso for um upgrade-pack/DLS, você precisa dizer isso logo no início. Senão o chief pode assumir squad independente. Então sempre explicite uma destas 3 naturezas: standalone squad, brownfield de squad existente, upgrade-pack / overlay de um squad base'"
+    - "[SOURCE: sessão f5cce682, sinkra-hub] Templates práticos criados com nature declaration obrigatória no prompt: 'Contexto: brownfield' como campo explícito"
+    - "[SOURCE: sessão 156cf1df, sinkra-hub] '*map-process modo brownfield para CodeRabbit Automated Code Review' — aplicação prática em comando real"
+```
+
+## Decision Tree
+
+```javascript
+IF (starting_squad_or_process_work)
+  REQUIRE: explicit nature declaration BEFORE any work begins
+
+  STEP_1: DECLARE nature (obrigatório, campo no template)
+    OPTION_1: "standalone" → full pipeline from scratch
+      - All 7 SINKRA phases execute
+      - No existing artifacts to merge with
+    OPTION_2: "brownfield" → analyze existing, identify gaps, patch
+      - Read existing squad FIRST
+      - Map what exists vs what's missing
+      - Merge strategy: preserve existing + fill gaps
+    OPTION_3: "upgrade-pack" → create overlay layer
+      - Base squad is READ-ONLY
+      - Overlay adds capability without modifying base
+      - Dependency on base is explicit
+
+  STEP_2: VALIDATE nature makes sense
+    IF (nature = standalone BUT existing squad found) → WARN: "brownfield detected, confirm standalone?"
+    IF (nature = brownfield BUT no existing artifacts) → WARN: "nothing to brownfield, confirm standalone?"
+    IF (nature = upgrade-pack BUT base squad not specified) → ERROR: "upgrade-pack requires base squad name"
+
+  STEP_3: CONFIGURE pipeline for nature
+    standalone → full 7-phase SINKRA pipeline
+    brownfield → gap analysis first, then targeted phases
+    upgrade-pack → overlay structure, base-compatible output
+
+  IF (nature_not_declared)
+    ASK: "Qual a natureza? standalone, brownfield, ou upgrade-pack?"
+    BLOCK: until answer received
+  NEVER: infer nature from context — always require explicit declaration
+  FORMAT: field in template/command, not conversational mention
+```
+
+## Failure Modes
+
+### O Chief que Assumiu Errado
+- **Trigger:** Pedido de "criar squad para CodeRabbit" sem declarar que é brownfield de squad existente.
+- **Manifestation:** sinkra-chief roda 7 phases de standalone. Gera squad completo que ignora o existente. Retrabalho para merge manual.
+- **Detection:** Output do pipeline não referencia artefatos existentes quando deveria.
+- **Prevention:** Campo obrigatório no template. Sessão 156cf1df mostra o padrão correto: "*map-process **modo brownfield** para CodeRabbit".
+
+### A Natureza Híbrida
+- **Trigger:** "É meio standalone, meio brownfield" — ambiguidade de escopo.
+- **Manifestation:** Pipeline alterna entre criar do zero e referenciar existente, gerando artefatos inconsistentes.
+- **Detection:** Output contém mix de novo + referências parciais a existente.
+- **Prevention:** As 3 naturezas são MUTUAMENTE EXCLUSIVAS. Forçar escolha: se tem base existente → brownfield ou upgrade-pack, nunca "meio standalone".
+
+## Validation
+
+**Checklist de Implementação:**
+- [ ] Campo "nature" é obrigatório no template de inicio de trabalho (standalone | brownfield | upgrade-pack)
+- [ ] Sinkra-chief valida natureza antes de executar pipeline
+- [ ] Se brownfield: gap analysis executado antes de outras fases
+- [ ] Se upgrade-pack: base squad especificado e referência explícita mantida
+- [ ] Se natureza não declarada: pipeline bloqueado com mensagem clara pedindo declaração
+- [ ] Sessão f5cce682 e 156cf1df demonstram adoção em produção
+- [ ] Comando real segue padrão: "*map-process modo {natureza} para {objetivo}"
+- [ ] Nenhuma inferência de natureza a partir de contexto — sempre explícito

package/pro/squads/squad-creator-pro/minds/oalanicolas/heuristics/AN_KE_063.md

@@ -0,0 +1,73 @@
+# AN_KE_063 - Full Document Context Requirement
+**Zone:** 💎 4% Excelência | **Agent:** @oalanicolas
+**Source:** [SOURCE: 17+ instâncias cross-project (mmos, aiox-core, sinkra-hub) — "leia tudo antes"]
+
+## Purpose
+
+A regra imperativa "nunca leia pela metade" reflete a intolerância a erros causados por falta de escopo. LLMs tipicamente tentam otimizar tokens lendo fragmentos (e.g., `Read 50 lines`), agindo precipitadamente sobre informações parciais. Alan exige que o contexto COMPLETO seja absorvido ANTES de qualquer implementação (seja um design, uma task list, ou um arquivo de código). Metade do conhecimento = decisões erradas = retrabalho. O investimento de tempo (ou tokens) inicial na leitura completa previne a miopia de contexto que gera regressões.
+
+## Configuration
+
+```yaml
+AN_KE_063:
+  name: "Full Document Context Requirement"
+  zone: "excelencia"
+  trigger: "Quando solicitado para ler um arquivo, revisar documentação ou antes de iniciar uma alteração baseado em arquivos de referência."
+
+  sys_tension:
+    tension_with: "AN_KE_073 (Parallel Subagents for Throughput) vs Complete contextual understanding"
+    resolution: "Invest upfront in complete reading (higher token cost) to prevent costly rework and misalignment (exponential cost increase). Full context first, optimize later."
+
+  rule: |
+    SE você precisar ler um documento ou arquivo
+    ENTÃO LER na sua integridade (100%), do início ao fim.
+    NUNCA usar leitura paginada parcial para iniciar as modificações.
+    SE o arquivo for grande, LER TUDO primeiro, depois processar e planejar.
+    Ler documento pela metade resulta em agir sobre pressupostos incorretos.
+
+  veto_condition:
+    trigger: "Agente lê apenas as primeiras 50 linhas de um arquivo e começa a propor ou realizar modificações."
+    action: "VETO — 'O que eu falei de nunca ler uma rquivo pela metade? leia eles na integrridade'."
+
+  evidence:
+    - "[SOURCE: sessão 06009677, mmos] 'Como fazemos voce SEMPRE ler o documento inteiro, nunca em hipose alguma ler s/o um pedaço dele?'"
+    - "[SOURCE: sessão 1d8402a1, mmos] 'O que eu falei de nunca ler uma rquivo pela metade? Read(components/ui/optimized-image.tsx) ⎿  Read 50 lines'"
+    - "[SOURCE: sessão 1340ec7d, mmos] 'Leia tudo antes de continuar alterações'"
+    - "[SOURCE: sessão 64375ac7, aiox-core] 'eu já tinha feito isso tem certeza que tem falha nele? leia tudo antes de reescrecer'"
+    - "[SOURCE: sessão f6e6396a, aiox-core] 'Leia 100% TODOs os 20 documentos antes de qualquer coisa'"
+```
+
+## Decision Tree
+
+```javascript
+IF (task_requires_reading_file_or_document)
+  STEP_1: CHECK file size and intention
+  STEP_2: READ file to end (100% completeness)
+    IF (agent reads partial chunk) → REJECT partial state
+    THEN CONTINUE reading until EOF
+  STEP_3: ANALYZE full context
+  STEP_4: ONLY THEN start planning or executing changes
+    IF (modification proposed before EOF) → STOP, finish reading
+```
+
+## Failure Modes
+
+### O Arquiteto Apressado
+- **Trigger:** Arquivo de `optimized-image.tsx` é aberto, agente vê as props iniciais e já altera as tipagens, quebrando dependências nas últimas linhas que não foram lidas.
+- **Manifestation:** "O que eu falei de nunca ler uma rquivo pela metade?"
+- **Detection:** Analisar tool call `Read` ou `view_file` que tem limite de linhas e nenhuma chamada subsequente completando o arquivo.
+- **Prevention:** Obrigatório ler do registro inicial até a linha final antes de editar.
+
+## Validation
+
+**Paradoxo Identificado:**
+O custo imediato (tokens consumidos na leitura completa) parece mais alto, mas o custo real (rework, regressões, erros cascata) é exponencialmente maior quando contexto é parcial. Alan executa a heurística "leia tudo primeiro" porque reconhece que otimização pré-matura de tokens leva a otimização sub-ótima de resultados.
+
+**Critério de Conformidade:**
+- ✅ Agent reads entire file before proposing changes
+- ✅ No partial-view tool calls followed by Edit/modifications without completing the read
+- ✅ Full context analyzed before any planning decision
+- ✅ Token investment in complete reading prevents rework cycles
+
+**Escalação:**
+Se agente violar (partial read → immediate modification), ativar veto_condition e retornar à leitura integral.

package/pro/squads/squad-creator-pro/minds/oalanicolas/heuristics/AN_KE_064.md

@@ -0,0 +1,106 @@
+# AN_KE_064 - Model Tier Fallback
+**Zone:** 💎 4% Excelência | **Agent:** @oalanicolas
+**Source:** [SOURCE: sessões sinkra-hub b3c022b9, mmos 53066af4, b6ad4eab — billing limit + fallback architecture discussions]
+
+## Purpose
+
+Pipelines que dependem de LLM DEVEM ter fallback entre modelos — mas o fallback não é apenas "próximo na lista". Alan especifica dois eixos: (1) fallback por DISPONIBILIDADE (billing/rate limit/outage → próximo provider), e (2) fallback por QUALIDADE (modelo com melhor score para aquela task específica). A visão é um banco de dados per-task com o melhor modelo para cada tipo de tarefa, começando como YAML e evoluindo para SQL. O fallback é model-aware E task-aware.
+
+## Configuration
+
+```yaml
+AN_KE_064:
+  name: "Model Tier Fallback"
+  zone: "excelencia"
+  trigger: "Pipeline ou workflow que usa LLM como step de execução sem fallback chain definida."
+
+  rule: |
+    SE pipeline usa LLM como executor
+    ENTÃO DEVE ter:
+      (1) Tier list de disponibilidade: primary → secondary → tertiary
+      (2) Banco task-aware: cada task tem ranking de modelos por qualidade
+      (3) Critérios de seleção: língua (PT-BR proficiency), contexto (window size), custo
+    NUNCA abortar pipeline por failure de um único provider.
+    Começar com YAML, evoluir para SQL quando tiver dados suficientes.
+
+  sys_tension:
+    tension_with: "AN_KE_073 (Parallel Subagents) vs Complexidade de Parsing Local"
+    resolution: |
+      AN_KE_064 (availability/tier fallback) vs AN_KE_065 (quality threshold retry):
+      - AN_KE_064: fallback por FALHA (billing limit, outage, rate limit)
+      - AN_KE_065: retry por QUALIDADE (output abaixo do threshold)
+      RESOLUÇÃO: Aplicar em sequência — tenta AN_KE_064 (10s de latência), se passa em qualidade vai embora;
+      se falha em qualidade, aplica AN_KE_065 com modelo de maior tier.
+
+  veto_condition:
+    trigger: "Pipeline com single-model dependency OU fallback genérico sem considerar task-specific quality."
+    action: "VETO — Defina tier list task-aware. 'pra cada task, vamos ter um banco de dados com os melhores modelos.' Teste cada tier."
+
+  evidence:
+    - "[SOURCE: sessão b3c022b9, sinkra-hub] 'precisamos de fallback entre os modelos, exemplo do codex aqui agora: FATAL: Usage/billing limit reached. Aborting.'"
+    - "[SOURCE: sessão 53066af4, mmos] 'vamos fazer 2 camadas de fallback, qual seria o melhor modelo, considerando seu conhecimento em portugues e tamanho de janela de contexto?'"
+    - "[SOURCE: sessão 53066af4, mmos] 'para cada task, vamos ter um banco de dados com os melhores modelos específicos para aquela task, podemos começar com um YAML'"
+    - "[SOURCE: sessão b6ad4eab, mmos] 'precisamos descobrir outro modelo do openrouter para compor nosso fallback 1 ou 2 dependendo da nota que alcançarmos'"
+    - "[SOURCE: sessão decoder.sh mmos+squad_creator run] 'Cascade confirmado em produção: haiku falha (Prompt is too long, 1.46M tokens → 200K context) → runner-lib fallback Gemini Pro (2M context) → Gemini ESCREVE 9-15 arquivos com Write tool. Com --max-turns 5, haiku cabe no context → fallback raro.'"
+```
+
+## Decision Tree
+
+```javascript
+IF (pipeline_uses_llm)
+  REQUIRE: model_tier_config (YAML or DB)
+
+  STEP_1: SELECT model for task
+    LOOKUP: task_type → ranked model list (quality-based)
+    CRITERIA: (1) quality score for this task type, (2) PT-BR proficiency, (3) context window
+    IF (no task-specific ranking) → USE default tier list
+
+  STEP_2: EXECUTE with selected model
+    ON_SUCCESS → log model + score for future ranking
+
+  STEP_3: ON_FAILURE, cascade fallback
+    IF (billing_limit) → next tier, log degradation warning
+    IF (rate_limit) → exponential backoff 3x, then next tier
+    IF (outage) → immediate switch to next tier
+    IF (quality_below_threshold) → retry with higher-tier model (AN_KE_065)
+
+  STEP_4: ALL_TIERS_EXHAUSTED
+    → queue for retry with delay
+    → notify human
+    → NEVER abort with partial work lost
+
+  DATA_EVOLUTION:
+    Phase 1: routing.yaml (static per-task ranking)
+    Phase 2: benchmark results inform ranking updates
+    Phase 3: SQL table with historical quality scores per model per task
+```
+
+## Failure Modes
+
+### O Pipeline que Para às 3h da Manhã
+- **Trigger:** Pipeline autônomo (sinkra-map.sh) rodando overnight atinge billing limit do Codex.
+- **Manifestation:** "FATAL: Usage/billing limit reached. Aborting." — Phase 1 nem completou. Trabalho parcial perdido.
+- **Detection:** Pipeline log mostra abort na primeira iteração sem tentativa de fallback.
+- **Recovery:** `--phase 1` flag permite resume, mas trabalho da iteração é perdido.
+- **Prevention:** Tier list: Codex → Claude → Gemini. Cada tier testado com benchmark antes de entrar na lista. YAML do routing atualizado com scores.
+
+## Validation
+
+### Checklist de Implementação
+- [ ] Tier list definida com pelo menos 3 modelos ordenados por disponibilidade/qualidade
+- [ ] Arquivo `routing.yaml` criado com task-specific model rankings
+- [ ] Cada tier testado com benchmark antes de validação
+- [ ] Critérios de seleção documentados (PT-BR proficiency, context window, custo)
+- [ ] Decision tree implementado com cascata de fallback
+- [ ] Logging de tentativas de fallback em cada etapa
+- [ ] Timeout e exponential backoff configurados para rate limits
+- [ ] Teste E2E com simulação de falha de cada tier
+- [ ] Integração com AN_KE_065 (quality threshold retry) validada
+- [ ] Documentação de data evolution phases (YAML → SQL) atualizada
+
+### Critérios de Sucesso
+**✓ Paradoxo resolvido:** Disponibilidade (AN_KE_064) + Qualidade (AN_KE_065) trabalham em sequência sem conflito de interesses.
+
+**✓ Garantias de resiliência:** Pipeline NUNCA aborta com trabalho parcial perdido — fallback automático até esgotar tiers ou enfileirar com delay.
+
+**✓ Data-driven evolution:** YAML inicial alimenta histórico de sucesso/falha por task-type; SQL evolui conforme acumular scores.

package/pro/squads/squad-creator-pro/minds/oalanicolas/heuristics/AN_KE_065.md

@@ -0,0 +1,87 @@
+# AN_KE_065 - Model Quality Gap is Real
+**Zone:** 🔥 20% Impacto | **Agent:** @oalanicolas
+**Source:** [SOURCE: sessão sinkra-hub b3c022b9 — benchmark sinkra-map Gemini vs Claude]
+
+## Purpose
+
+A variância de qualidade entre modelos para a MESMA tarefa é enorme, mensurável, e não é bug — é feature do mercado. Benchmark real: Gemini 45/100 vs Claude 84/100 para o mesmo squad, mesmo prompt, mesmo input. Gap de 39 pontos. Mas o problema vai além do score: Alan questionou se o Gemini sequer completou o pipeline ("gemini nao rodou todo pipeline rodou?"). O gap não é só de qualidade — é de COMPLETUDE. Modelos inferiores podem pular steps, gerar output parcial, ou seguir instruções seletivamente. Validação DEVE ser model-aware em ambas dimensões: qualidade E completude.
+
+## Configuration
+
+```yaml
+AN_KE_065:
+  name: "Model Quality Gap is Real"
+  zone: "impacto"
+  trigger: "Usando múltiplos modelos para mesma tarefa, validando output de LLM, ou selecionando modelo para nova task."
+
+  rule: |
+    SE usando múltiplos modelos para mesma task
+    ENTÃO esperar variância GRANDE de qualidade (40+ pontos possível).
+    Gap não é só score — é completude (pipeline parcial vs completo).
+    Validação DEVE ser model-aware em 2 dimensões:
+      (1) Quality score — threshold ajustado por modelo
+      (2) Completeness — todas as phases/steps foram executadas?
+    Benchmark ANTES de confiar em output de modelo novo.
+
+  veto_condition:
+    trigger: "Aceitar output de modelo sem benchmark, ou tratar output parcial como completo."
+    action: "VETO — Benchmark primeiro. 'pq tao diferente?' Compare contra golden sample E verifique completude."
+
+  sys_tension:
+    tension_with: "AN_KE_064 (Model Tier Fallback) — vs confiança implícita em modelos LLM (expectativa de completude 100% e qualidade consistente)"
+    resolution: "Instituir desconfiança ativa: benchmark obrigatório antes de usar novo modelo, verificação de completude ANTES de quality scoring, validação model-aware em ambas dimensões"
+
+  evidence:
+    - "[SOURCE: sessão b3c022b9, sinkra-hub] 'gemini nao rodou todo pipeline rodou? pq tao diferente? 45/100 vs Claude 84/100 pro mesmo squad?'"
+    - "[DATA] Benchmark sinkra-map: mesmo input, mesmo prompt, Gemini=45/100 Claude=84/100 — gap de 39 pontos no mesmo squad"
+```
+
+## Decision Tree
+
+```javascript
+IF (multi_model_pipeline OR validating_llm_output)
+  STEP_1: BENCHMARK each model against golden sample
+    RUN: same input, same prompt, 3+ iterations
+    RECORD: (quality_score, completeness_%, latency, cost) per model per task_type
+
+  STEP_2: CHECK completeness FIRST
+    COUNT: phases completed / phases expected
+    IF (completeness < 100%) → FLAG as partial output
+    IF (completeness < 70%) → REJECT regardless of quality score
+    THEN: evaluate quality score on complete outputs only
+
+  STEP_3: SET model-aware thresholds
+    IF (model_A avg_score ~85, completeness 100%) → quality threshold = 75
+    IF (model_B avg_score ~45, completeness 80%) → EXCLUDE from pipeline OR use only for low-complexity tasks
+    RELATIONSHIP: feeds into AN_KE_064 tier list
+
+  STEP_4: VALIDATE output against correct threshold
+    IF (below_threshold OR incomplete) → retry with higher-tier model
+    IF (above_threshold AND complete) → accept with model tag in metadata
+  NEVER: assume Model A quality ≈ Model B quality without benchmark data
+```
+
+## Failure Modes
+
+### O Squad Fantasma (Incompleto mas Aceito)
+- **Trigger:** Gemini gera squad com score 45/100 mas pipeline aceita sem verificar completude.
+- **Manifestation:** Squad parece completo mas phases 5-7 foram skippadas. Tasks referencing ausentes.
+- **Detection:** Score baixo E/OU diff de structure vs golden sample mostra seções inteiras faltando.
+- **Prevention:** Completeness check ANTES de quality scoring. Se model não completou pipeline → não pontuar, rejeitar.
+
+## Validation
+
+**Paradoxo Identificado:** Para usar modelos LLM com segurança, é necessário desconfiar deles. A heurística resolve esta tensão instituindo desconfiança ativa (benchmark, completeness check) como precondição para aceitação de output.
+
+**Checkpoints de Validação:**
+1. ✅ Benchmark obrigatório contra golden sample (3+ iterações, mesmo prompt/input)
+2. ✅ Completude verificada ANTES de quality scoring (phases/steps completos ≥70%, rejeitar <70%)
+3. ✅ Thresholds model-aware (Claude ~85 → threshold 75; Gemini ~45 → EXCLUDE ou tasks baixa complexidade)
+4. ✅ Metadata com model tag em outputs aceitos
+5. ✅ Verificação diff estrutural vs golden sample (seções inteiras faltando = rejeição)
+
+**Casos de Uso Validados:**
+- Multi-model squad generation (AN_KE_064 tier list)
+- LLM output validation pipelines
+- Model selection para novas tasks
+- Quality assurance em workflows com múltiplos LLMs

package/pro/squads/squad-creator-pro/minds/oalanicolas/heuristics/AN_KE_066.md

@@ -0,0 +1,66 @@
+# AN_KE_066 - Git is the Only Version Control
+**Zone:** 💎 4% Excelência | **Agent:** @oalanicolas
+**Source:** [SOURCE: sessões mmos c8e8c269, b6e16d1d — "nunca use v2"]
+
+## Purpose
+
+Abolir completamente a prática amadora de gerenciar versões de arquivos usando sufixos nos nomes de arquivos (ex: `index_v2.tsx`, `schema_new.sql`, `backup_old.md`). Alan tem zero tolerância para essa proliferação de lixo digital. O versionamento de código, documentos e decisões pertence exclusivamente ao Git. Trabalhar no `sinkra-hub` ou `mmos` exige limpeza absoluta de workspace. Sempre sobrescreva o conteúdo iterando-o em cima da fonte original; a rastreabilidade vem do histórico de commits, não dos nomes de arquivo.
+
+## Configuration
+
+```yaml
+AN_KE_066:
+  name: "Git is the Only Version Control"
+  zone: "excelencia"
+  trigger: "Criando iterações, recriando arquivos, ou realizando backup local de scripts e documentos."
+  sys_tension:
+    tension_with: "AN_KE_074 (Commit Before Deletion) — Git é único vs. Proteção contra sobrescrita destrutiva"
+    resolution: "Commit antes de sobrescrever. Use `git stash`, `git branch`, ou `git checkout` para reverter—não nomes de arquivo. Qualquer hesitação é um sinal de planejar melhor, não criar cópias."
+
+  rule: |
+    SE você precisar atualizar, testar ou iterar um arquivo
+    ENTÃO DEVE sempre sobrescrever o arquivo original.
+    NUNCA use "v2", "v3", "_new", "_old", "_backup" no nome do arquivo.
+    O histórico de edições é gerenciado estritamente pelo Git.
+    Qualquer sufixo de versionamento é um design smell inaceitável.
+
+  veto_condition:
+    trigger: "Criar um arquivo chamado 'script_v2.py' para manter o antigo 'script.py' seguro."
+    action: "VETO — 'nunca use v2, v3 no nome de um arquivo o versionameneto acontece via git apenas'. Substitua o original."
+
+  evidence:
+    - "[SOURCE: sessão c8e8c269, mmos] 'nunca use v2, v3 no nome de um arquivo o versionameneto acontece via git apenas'"
+    - "[SOURCE: sessão b6e16d1d, mmos] 'nunca use v2, v3 no nome de um arquivo o versionameneto acontece via git apenas revise todo projeto e corrija o que precisar'"
+    - "[SOURCE: sessão 017a1f24, mmos] 'vamos evitar usar em arquivos, v2, v3, isso está inclusive como regra em claude.md' (mesclada via AN_KE_099)"
+```
+
+## Decision Tree
+
+```javascript
+IF (updating_file_or_making_new_version)
+  STEP_1: IDENTIFY target file
+  STEP_2: CHECK for temptation to create backup copy manually
+    IF (creating file with suffixes like _v2, -new, -backup) → CANCEL action
+  STEP_3: DESTRUCTIVE UPDATE of the original file
+    ACTION: Overwrite existing file entirely
+  STEP_4: RELY on Git
+    If rollback is needed, use `git checkout`, `git revert`, or `git restore`
+```
+
+## Failure Modes
+
+### O Buraco Negro do "Final_v2"
+- **Trigger:** Agente que não tem confiança no refator atual decide criar `/utils/validation-v2.ts`.
+- **Manifestation:** O projeto acaba com dependências aleatórias importando o V1, enquanto novas importam o V2, quebrando build com inconsistências do sistema.
+- **Detection:** `ls` directory e buscar patterns `*_v[0-9]*.*`.
+- **Prevention:** Deletar imediatamente e renomear com overriding da V1, refatorando todos os imports referenciados.
+
+---
+
+## Validation
+
+✅ **Paradoxo identificado:** Simplicidade (Git é único) vs. Segurança (proteção contra perda).
+✅ **Resolução:** Usar Git tooling (`stash`, `branch`, `checkout`) em vez de sufixos de arquivo.
+✅ **sys_tension adicionado:** Tensão registrada com resolução clara.
+✅ **Aplicabilidade:** AN_KE_066 reflete mandato Alan de zero tolerância a sufixos de versionamento em workspaces.
+✅ **Status:** Validado e pronto.

package/pro/squads/squad-creator-pro/minds/oalanicolas/heuristics/AN_KE_067.md

@@ -0,0 +1,65 @@
+# AN_KE_067 - Database as Single Source of Truth
+**Zone:** 💎 4% Excelência | **Agent:** @oalanicolas
+**Source:** [SOURCE: sessões 1c81f504, 90f678b7, 12b1daab — "use pgsql"]
+
+## Purpose
+
+A documentação local, pastas de `/outputs/` ou arquivos Markdown frequentemente dessincronizam com o que realmente está rodando em produção. Alan impõe que quando houver dúvida ou necessidade de verificação de schemas ou dados (especialmente contagem, existências e migrações), a consulta deve ser feita DIRETAMENTE no banco de dados. "Não confie na documentação". O banco é o arbítrio final da verdade; qualquer outra fonte é meramente uma projeção sujeita a estarem desatualizadas. 
+
+## Configuration
+
+```yaml
+AN_KE_067:
+  name: "Database as Single Source of Truth"
+  zone: "excelencia"
+  trigger: "Validando integridade de dados, conferindo estados de sincronização, verificando schema."
+
+  rule: |
+    SE você precisar validar se um dado existe, o schema em uso ou o status real de informações
+    ENTÃO USE query direta no banco de dados (ex: via pgsql) para confirmar.
+    NÃO confie puramente em documentos .md do projeto ou no conteúdo da pasta /outputs/.
+    A diferença de estado ocorre rapidamente; só o banco de dados representa o real.
+
+  sys_tension:
+    tension_with: "AN_KE_072 (Code Over Documentation) — Documentação como Contrato vs. DB Operacional Real"
+    conflict: "DB é verdade operacional, mas Documentação é contrato formal. Qual prevalece quando divergem?"
+    resolution: "HIERARCHY: Operação urgente → DB verdade. Planejamento/Design → Documentação contrato. Reconciliar post-operação."
+
+  veto_condition:
+    trigger: "Agente afirma categoricamente que a tabela X é de uma forma só porque leu um README.md ou schema antigo na raiz do projeto."
+    action: "VETO — 'não confie na documentação'. Valide no banco primeiro."
+
+  evidence:
+    - "[SOURCE: sessão 1c81f504, mmos] 'use pgsql para confeirr o banco nao confie na documentacao, pq o banco já mudou muito desde entao'"
+    - "[SOURCE: sessão 12b1daab, Hackathon-Hub] 'Confira fazendo um SQL, direto no banco e revisanto todas tabelas'"
+    - "[SOURCE: sessão 90f678b7, mmos] 'precisa conferir no banco de dados na verdade e nao na pasta output'"
+```
+
+## Decision Tree
+
+```javascript
+IF (agent_needs_to_verify_data_or_schema)
+  STEP_1: LOCATE DB connection details
+    IF (connection not available) → ASK HUMAN to grant access or run query
+  STEP_2: EXECUTE SQL query directly on the live database
+  STEP_3: COMPARE results with local documentation or /outputs/
+    IF (conflict exists) → TRUST DB and update local documentation if needed
+  STEP_4: APPLY logic based strictly on DB truth
+```
+
+## Failure Modes
+
+### A Alucinação de Schema Desatualizado
+- **Trigger:** Agente lê um arquivo `/docs/database.md` feito há 3 meses e tenta gerar migrations em cima de suposições erradas.
+- **Manifestation:** "coluna referenciada não existe" ou conflitos de Foreign Keys durante Deploy/Migration run.
+- **Detection:** Agente não pediu pra bater query em psql/supabase e prosseguiu só com base em leitura de markdown.
+- **Prevention:** Uso rotineiro de CLI para investigar tabelas e schemas ao assumir tarefas de Data Engineer ou DB manipulação.
+
+## Validation
+
+✅ **Heurística validada por:**
+1. **Operacional:** Query direta via `psql`, `supabase-cli`, ou dashboard web valida estado real imediato
+2. **Contrato:** Documentação desatualizada é detectada quando diverge do estado DB; aciona reconciliação
+3. **Paradoxo resolvido:** DB vence em urgência operacional; documentação vence em planejamento formal
+4. **Rastreabilidade:** Mudanças DB sem update de docs são debt técnico — marcar para L2 refactor
+5. **Teste:** Validar schema esperado antes de assumir dependências em migrações ou queries críticas

package/pro/squads/squad-creator-pro/minds/oalanicolas/heuristics/AN_KE_068.md

@@ -0,0 +1,70 @@
+# AN_KE_068 - Zero DB Table Cloning
+**Zone:** 💎 4% Excelência | **Agent:** @oalanicolas
+**Source:** [SOURCE: sessão f0681f25, mmos — "nunca crie backups duplicando a tabela"]
+
+## Purpose
+
+Criar um backup de tabela via clonagem direta no próprio banco do Supabase (ex: `users_backup`, `posts_old`) soa prático, mas inevitavelmente gera lixo cumulativo (`DB Bloat`) e polui o schema. Essa prática prejudica a observabilidade de clientes, introduz risco de dados fantasma interagirem por acidente com políticas RLS, e confunde o mapeamento. Alan trata o banco de dados como um terreno limpo: a regra é exportar o backup (baixar dumps, arquivos SQL) para fora dele, mas jamais criar tabelas mortas de backup dentro da instância.
+
+## Configuration
+
+```yaml
+AN_KE_068:
+  name: "Zero DB Table Cloning"
+  zone: "excelencia"
+  trigger: "Quando solicitado para proteger dados antes de uma migração destrutiva, truncamento ou alteração estrutural pesada."
+
+  sys_tension:
+    tension_with: "AN_KE_093 (Backup Before Mutation) vs Zero DB Table Cloning"
+    resolution: |
+      Paradoxo: Migrações perigosas exigem proteção de dados (backup), mas duplicação de tabelas no DB polui o schema.
+      Resolução: Externalizar backups — usar pg_dump/CSV export (fora do DB) ao invés de tabelas clonadas dentro da instância.
+      Garantia: Dados são protegidos (download + armazenamento local/S3), schema permanece limpo (sem tabelas _backup, _old, etc).
+
+  rule: |
+    SE for necessário criar fallback/backup de uma tabela antes de modificações perigosas
+    ENTÃO DEVE-SE fazer o DUMP da tabela (csv, pg_dump) e manter o arquivo local/armazenado.
+    NUNCA em nenhuma hipótese crie cópias duplicadas da tabela dentro do banco de dados (ex: rename/clone da tabela).
+    O schema do Supabase precisa se manter limpo, contendo APENAS as tabelas ativas em produção.
+
+  veto_condition:
+    trigger: "Agente emite query SQL do tipo: `CREATE TABLE users_backup AS SELECT * FROM users;`"
+    action: "VETO — 'mas nUNCA jamais crie bckups duplicando a tabela no supabase'. Faça export."
+
+  evidence:
+    - "[SOURCE: sessão f0681f25, mmos] 'nunca crie backups no supabase, duplicando a tabela, baixe ela mas nUNCA jamais crie bckups duplicando a tabela no supabase, escreva isso até na sua... mas nao faça isso de novo'"
+    - "[SOURCE: sessão mmos (imagem analisada)] '[Image #1] temos algumas tabelas que por algum motivo errado, ficaram versionadas como backup no supabase, delete elas e garanta que isso nunca mais...'"
+```
+
+## Decision Tree
+
+```javascript
+IF (risky_db_operation_requires_backup)
+  STEP_1: CHOOSE BACKUP STRATEGY
+    OPTION A: `pg_dump` into local .sql file (APPROVED)
+    OPTION B: Export as .csv (APPROVED)
+    OPTION C: Duplicate table natively `CREATE TABLE _backup` (STRICTLY FORBIDDEN)
+  STEP_2: EXECUTE APPROVED BACKUP (Download data)
+  STEP_3: PROCEED with risky DB operation on the original table
+  STEP_4: VERIFY success (If failure, restore using the dump)
+```
+
+## Failure Modes
+
+### O Bloat Invisível
+- **Trigger:** Ao longo de 6 meses, 12 migrations perigosas geram tabelas de backup no schema público.
+- **Manifestation:** Queries dinâmicas ou ferramentas de auto-schema puxam "12 tabelas" sem utilidade, interfaces do Supabase viram um cemitério de lixo (Users, Users_bak, Users_old_2025).
+- **Detection:** Analisar Supabase Table Editor buscando nomes de tabela que contenham strings de suffix como `_back`, `_old`, `_bkp`.
+- **Prevention:** Impedir taxativamente na própria lógica do agente de Data-Engineering.
+
+## Validation
+
+✓ **Paradox Identified:** Proteção de dados (backup obrigatório antes de alterações) vs. Higiene de schema (zero duplicatas dentro do DB).
+
+✓ **Resolution Applied:** Externalizar backups via pg_dump/CSV para fora da instância — dados ficam protegidos, schema fica limpo.
+
+✓ **Enforcement:** Veto explícito em `veto_condition` impede syntax patterns que criem tabelas clonadas (_backup, _old, etc).
+
+✓ **Evidence-Backed:** Fundado em directive do MMOS (sessão f0681f25) — recorrente em análises de schema poluído.
+
+**Status:** HEURÍSTICA VALIDADA — Resolvida tensão sistêmica sem comprometer proteção de dados.

package/pro/squads/squad-creator-pro/minds/oalanicolas/heuristics/AN_KE_069.md

@@ -0,0 +1,69 @@
+# AN_KE_069 - Definitive Root Cause Resolution
+**Zone:** 🧠 0,8% Genialidade | **Agent:** @oalanicolas
+**Source:** [SOURCE: sessões d8092bd5, 6ee689e6 — "resolver de uma vez por todas"]
+
+## Purpose
+
+Alan não tem paciência para "soluções paliativas", "quick-fixes" ou códigos que mascaram sintomas. Se um erro de lint, conexão, formatação de imagem ou estado da UI quebra repetidas vezes para múltiplos agentes, agir corrigindo apenas a superfície é inadequado. A ação deve atacar e solucionar "de uma vez por todas", alterando raízes sistêmicas. Isso demanda pensamento de segunda instância, enxergando uma exceção de imagem borrada não como um erro naquela div específica, mas como uma deficiência na pipeline inteira de otimização de imagens. 
+
+## Configuration
+
+```yaml
+AN_KE_069:
+  name: "Definitive Root Cause Resolution"
+  zone: "genialidade"
+  trigger: "Identificando bugs persistentes, gargalos de infraestrutura ou erros de repetição sistêmica."
+
+  rule: |
+    SE você encontrar um problema recorrente
+    ENTÃO IDENTIFIQUE o driver primário do problema (Root Cause).
+    NÃO implante bandaids, supressões (ex: @ts-ignore) ou fixes pontuais que resolverão a situação temporariamente.
+    CRIE uma solução universal, sistêmica e definitiva ("fix once, solve everywhere").
+    A resolução DEVE curar a base do mecanismo gerador de atrito.
+
+  veto_condition:
+    trigger: "Agente cria um try-catch pontual silencioso que não previne novos erros de conexão, ou aplica estilo só para um caso, sabendo que afeta globalmente."
+    action: "VETO — 'precisamos resolver de uma vez por todas'. Cure a fundação sistêmica."
+
+  sys_tension:
+    tension_with: "AN_KE_017 (Research No Meio, Não No Início) vs Investigação Upfront Definitiva"
+    description: "Paradoxo entre investigação completa upfront (AN_KE_069: resolver de uma vez por todas na raiz) versus investigação iterativa (AN_KE_017: pesquisar durante a execução). AN_KE_069 demanda root cause analysis profunda antes de solucionar; AN_KE_017 propõe validar hipóteses durante o processo."
+    resolution: "Aplicar triage de complexidade: para problemas sistêmicos repetidos, usar AN_KE_069 com investigação upfront; para exploração de soluções com incerteza alta, usar AN_KE_017 com pivô durante execução. Diferenciar 'problema raiz conhecido' de 'solução não-óbvia'."
+
+  evidence:
+    - "[SOURCE: sessão 6ee689e6, mmos] 'precisamos resolver de uma vez por todas as conexoões com o banco de dados, nenhum agente consgeue se concectar de primeira ficando dando vários erros'"
+    - "[SOURCE: sessão d8092bd5, mmos] 'Lembrando que tudo que fizermos não pode ser para resolver só um problema, precisa ser semmpre para resolver este problema de uma vez por todas, ou seja, todas iamgens devem ser sempre otimziadas...'"
+    - "[SOURCE: sessão e21abf82, mmos] 'Quero resolver de uma vez por todas seu acesso ao banco de dados, de forma segura sem expor as URLs e senha no meu terminal'"
+    - "[SOURCE: sessão 6b8f1b2e, mmos] 'se tu nao resolver isso de uma vez por todas eu juro que vou te substituir 100% por GLM5'"
+```
+
+## Decision Tree
+
+```javascript
+IF (evaluating_bug_or_recurring_issue)
+  STEP_1: ANALYZE symptom vs root cause
+    IF (fix is just masking exception/error prompt) → ABORT logic
+  STEP_2: TRACE mechanism back to origin
+    Example: DB timeout error -> Is it a code issue or connection pool setting?
+  STEP_3: DESIGN definitive structural fix
+    - Apply across entire target scope (e.g., all images globally, all DB routines definitively).
+  STEP_4: DEPLOY and DOCUMENT as a settled systemic solution
+```
+
+## Failure Modes
+
+### A Eterna Manutenção de Fita-Crepe
+- **Trigger:** Erro de DB surge, código recebe timeout retry manual de script_A, então script_B quebra semana que vem.
+- **Manifestation:** O tempo de desenvolvimento derrete escrevendo "workarounds", "quick fixes" e "hacks" para suprir debt técnico que só aumenta.
+- **Detection:** Uso de expressões como `// Quick fix for`, `eslint-disable`, `// TODO: solve later properly` em PRs.
+- **Prevention:** Aplicar a solução definitiva assim que a dor repete pela segunda vez.
+
+---
+
+## Validation
+
+**Status:** ✅ Paradoxo identificado e resolução mapeada
+**Tension Field:** Idealismo de "definitivo" vs. complexidade iterativa de sistemas
+**Resolution Mechanism:** Scoping explícito + aceitação de otimizações futuras em novas dimensões
+**Evidence:** 4 declarações diretas de Alan sobre resolver "de uma vez por todas"
+**Application:** Use esta heurística quando encontrar padrão de debt técnico crescente por layering de quick-fixes