aiox-core 5.0.5 → 5.0.7

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

@@ -0,0 +1,69 @@
+# AN_KE_013 - Regra dos 3+ Consumidores
+
+**Type:** Decision Heuristic
+**Zone:** 💎 4% Excelência
+**Agent:** @oalanicolas
+**Pattern:** Abstraction Threshold
+**Source:** [SOURCE: Epic 71 — scoring engine validate-squad NÃO extraído (1 consumidor, 7 guardrails específicos)]
+
+---
+
+**sys_tension:**
+  - tension_with: "AN_KE_007 (REUSE > CREATE) vs Pragmatic Extraction Threshold"
+  - resolution: "Require 3+ independent consumers before extraction; domain-specific logic stays inline"
+
+## Purpose
+
+Só extrair para shared lib quando 3+ scripts usam o mesmo pattern. Com 2 é coincidência. Com 3 é padrão.
+
+## Configuration
+
+```yaml
+AN_KE_013:
+  name: "Regra dos 3+ Consumidores"
+  zone: "excelencia"
+  trigger: "Tentação de extrair código para shared lib"
+
+  rule: |
+    SE pattern aparece em 1-2 scripts → MANTER inline
+    SE pattern aparece em 3+ scripts → EXTRAIR para shared lib
+    NUNCA extrair lógica domain-specific (scoring com 7 guardrails de 1 script)
+
+  anti_pattern: "Abstrair prematuramente algo que só 1 script usa"
+
+  evidence:
+    - "security scan: validate-skill + validate-squad + sinkra-map = 3 → extraído para security.sh"
+    - "scoring engine: só validate-squad usa 9 dims + 7 guardrails = 1 → mantido inline"
+    - "colors ANSI: 14 scripts usam = 14 → extraído para colors.sh"
+```
+
+## Decision Tree
+
+```
+IF (consumers >= 3 AND logic_is_generic)
+  THEN extract to shared lib
+ELSE IF (consumers == 2 AND logic_is_identical)
+  THEN monitor, extract when 3rd appears
+ELSE
+  THEN keep inline — premature abstraction is worse than duplication
+```
+
+## Failure Modes
+
+### O Módulo Shared que Ninguém Mais Usa
+- **Trigger:** Scoring engine extraído para 1 consumidor "porque outros vão usar no futuro."
+- **Manifestation:** Módulo shared com 1 consumidor + 7 guardrails que só fazem sentido pra esse consumidor.
+- **Detection:** `grep -r 'require.*module' | wc -l` mostra 1 consumer.
+- **Prevention:** Regra dos 3+. "NÃO extraído porque 1 consumidor com 7 guardrails específicos."
+
+---
+
+## Validation ✓
+
+✅ **Paradoxo Identificado:** Abstraction Efficiency (reutilização via shared lib) vs. Pragmatic Coupling (manter inline para evitar overhead)
+
+✅ **Tensão Sistêmica:** A heurística resolve o paradoxo via threshold quantitativo (3+ consumidores = ponto de inflexão onde abstração se justifica)
+
+✅ **Aplicabilidade:** Validado em scoring engine (1 consumidor, mantido inline) + ANSI colors (14 consumidores, extraído)
+
+✅ **Decisão Determinística:** Regra objetiva, sem ambiguidade interpretativa

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

@@ -0,0 +1,69 @@
+# AN_KE_014 - Fan-out > Linhas Removidas
+
+**Type:** Decision Heuristic
+**Zone:** 🚀 20% Impacto
+**Agent:** @oalanicolas
+**Pattern:** Correct ROI Metric
+**Source:** [SOURCE: Epic 71 — net +345 linhas, mas 1 edit em state-manager.sh resolve 8 scripts]
+**sys_tension:**
+  - tension_with: "AN_KE_045 (Subtraction First Strategy) vs Fan-out Reduction"
+  - resolution: "Fan-out (impacto de mudança) é a métrica verdadeira; mais linhas são aceitáveis se reduzem edições futuras (ROI temporal, não quantitativo)"
+
+## Purpose
+
+Shared infra sempre aumenta linhas totais no início. Medir sucesso por "linhas removidas" é a métrica errada. Medir por fan-out: quantos arquivos preciso editar quando algo muda.
+
+## Configuration
+
+```yaml
+AN_KE_014:
+  name: "Fan-out > Linhas Removidas"
+  zone: "impacto"
+  trigger: "Avaliando ROI de shared lib"
+
+  rule: |
+    SE avaliando se shared lib valeu a pena
+    NÃO medir por linhas removidas (sempre negativo no início)
+    MEDIR por fan-out de mudança: 1 edit → N scripts afetados
+
+  metric:
+    correct: "Fan-out de mudança (1 edit → N scripts)"
+    incorrect: "Linhas removidas vs adicionadas"
+
+  evidence:
+    - "Epic 71: +501 linhas módulos, -156 linhas scripts = net +345"
+    - "Mas: novo runtime = 1 edit em arg-parser.sh em vez de 8 edits"
+    - "Bug fix = 1 fix em state-manager.sh em vez de caçar em 8 scripts"
+```
+
+## Decision Tree
+
+```javascript
+IF (evaluating_shared_lib_ROI)
+  WRONG_METRIC: total_lines_after - total_lines_before  // Always negative initially
+  RIGHT_METRIC: fan_out = files_that_need_editing_when_something_changes
+    BEFORE shared lib: bug fix = edit N scripts individually
+    AFTER shared lib: bug fix = edit 1 module, N scripts inherit
+  IF (fan_out_reduction > 3x) → shared lib justified
+  IF (fan_out_reduction < 2x) → reconsider extraction
+```
+
+## Failure Modes
+
+### A Lib Shared que "Não Valeu a Pena"
+- **Trigger:** Epic review mostra net +345 linhas. Stakeholder questiona ROI.
+- **Manifestation:** "Adicionamos mais linhas do que removemos" — conclusão incorreta.
+- **Detection:** Medindo ROI por diff size em vez de fan-out.
+- **Prevention:** Medir fan-out: "1 edit em arg-parser.sh em vez de 8 edits" = 8x ROI real.
+
+## Validation
+
+**Paradox Resolution Validated:** A aparente contradição "mais linhas = mal" coexiste com "mais linhas = bom se reduz fan-out". A resolução está no shift de métrica: ROI não é quantidade de linhas, mas velocidade de mudança. Uma shared lib que adiciona 345 linhas mas reduz fan-out de 8→1 tem ROI massivo (8x retorno temporal). Métrica correta: `fan_out_reduction_ratio ≥ 3x` justifica investimento inicial em linhas.
+
+**Evidence Chain:**
+- Epic 71 net: +345 linhas totais
+- Antes: bug fix = edit 8 scripts
+- Depois: bug fix = edit 1 módulo, 8 scripts herdam → fan-out = 8x reduction
+- Conclusão: ROI positivo apesar de linha count negativa
+
+**Aplicability:** Decisões sobre shared libraries, refactoring, platform engineering.

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

@@ -0,0 +1,83 @@
+# AN_KE_015 - Fallback Graceful É Non-Negotiable
+
+**Type:** Veto Heuristic
+**Zone:** 💎 4% Excelência
+**Agent:** @oalanicolas
+**Pattern:** Dependency Safety
+**Source:** [SOURCE: Epic 71 — todos 7 módulos v2 têm RUNNER_LIB_*=true/false + fallback inline]
+**sys_tension:** (shared_dependency, graceful_fallback, "Módulos compartilhados devem ser reutilizáveis mas nunca podem quebrar o consumidor — resolver via availability flag + fallback inline")
+
+## Purpose
+
+Módulo shared nunca pode ser dependência hard. Se o módulo não carregar, o script deve continuar com comportamento degradado mas funcional.
+
+## Configuration
+
+```yaml
+AN_KE_015:
+  name: "Fallback Graceful"
+  zone: "excelencia"
+  trigger: "Criando módulo shared / integrando dependência"
+
+  rule: |
+    SE criando módulo shared
+    ENTÃO flag de disponibilidade (MODULE_NAME=true/false)
+    E branch condicional no consumidor
+    E fallback inline quando módulo indisponível
+    NUNCA hard dependency — script DEVE funcionar sem o módulo
+
+  veto_condition:
+    trigger: "Módulo sem fallback"
+    action: "VETO — adicionar fallback antes de merge"
+
+  pattern: |
+    # No módulo:
+    MODULE_FLAG=true
+
+    # No consumidor:
+    if [[ "${MODULE_FLAG:-false}" == "true" ]]; then
+      use_shared_function
+    else
+      inline_fallback
+    fi
+
+  evidence:
+    - "validate-skill.sh funciona SEM validator-lib (fallback inline para cores, scoring, security)"
+    - "sinkra-map.sh funciona SEM pipeline-bootstrap (fallback para source lib/runtime.sh)"
+    - "12 flags de disponibilidade no pipeline-bootstrap.sh"
+
+  tension_with: "AN_KE_013 (Regra dos 3+ Consumidores) — Módulos compartilhados ganham complexidade de fallback, mas tornam-se resilientes em vez de rígidos"
+```
+
+## Decision Tree
+
+```javascript
+IF (creating_shared_module)
+  REQUIRE: availability flag (MODULE_NAME=true/false)
+  REQUIRE: consumer checks flag before using module
+  REQUIRE: inline fallback when flag=false
+  TEST: script must work with MODULE_FLAG=false
+  NEVER: hard import without availability check
+```
+
+## Failure Modes
+
+### O Pipeline que Quebrou no CI
+- **Trigger:** Shared module not available in CI environment (different PATH, missing dep).
+- **Manifestation:** `source: file not found` → pipeline abort.
+- **Detection:** CI fails but local passes.
+- **Prevention:** Flag check + inline fallback. CI runs with MODULE_FLAG=false automatically.
+
+---
+
+## Validation
+
+✅ **Paradoxo identificado:** Compartilhamento (reutilização) vs Independência (resiliência)
+
+✅ **Resolução:** Opcionais via availability flags + fallbacks inline garantem que o consumidor funciona sempre, com ou sem o módulo compartilhado
+
+✅ **Evidência:** 12 flags de disponibilidade no pipeline-bootstrap.sh + 7 módulos v2 com RUNNER_LIB_*=true/false
+
+✅ **Teste:** Scripts executam com MODULE_FLAG=false sem falhas
+
+✅ **Status:** Veto habilitado para módulos sem fallback

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

@@ -0,0 +1,67 @@
+# AN_KE_016 - Testar Módulo Isolado, Não Pipeline
+
+**Type:** Decision Heuristic
+**Zone:** 🚀 20% Impacto
+**Agent:** @oalanicolas
+**Pattern:** Test Isolation
+**Source:** [SOURCE: Epic 71 — bug ${} quoting encontrado em 2s pelo test suite, não em 30min de pipeline]
+**sys_tension:**
+  - tension_with: "AN_KE_073 (Parallel Subagents for Throughput) vs Isolamento Sequencial de Módulos"
+    resolution: "Testes isolados em <5s MAIS regressão cíclica (1/semana) vs pipeline contínuo. Isolado evita falsos-negativos de performance; pipeline evita falsos-positivos de integração"
+
+## Purpose
+
+Cada módulo shared deve ter smoke test que roda em <5s sem dependências externas. Se precisa rodar pipeline completo pra testar uma função, a função está mal isolada.
+
+## Configuration
+
+```yaml
+AN_KE_016:
+  name: "Testar Módulo Isolado"
+  zone: "impacto"
+  trigger: "Testando módulo shared ou função extraída"
+
+  rule: |
+    SE módulo shared criado/modificado
+    ENTÃO smoke test isolado em <5s (sem LLM, sem rede, sem squad)
+    SE precisa do pipeline completo pra testar → função mal isolada, refatorar
+
+  evidence:
+    - "Bug $\{} quoting: encontrado pelo test suite 30s, não pelo sinkra-map 30min"
+    - "94 testes rodando em 30s = 19 syntax + 12 bootstrap + 10 json + 9 state + 8 smoke + 36 skills"
+    - "Debug isolado: 2s. Debug em pipeline: 10-30min"
+```
+
+## Decision Tree
+
+```javascript
+IF (testing_shared_module)
+  REQUIRE: smoke test that runs in <5s
+    NO LLM dependency
+    NO network dependency
+    NO squad/pipeline dependency
+  IF (test requires full pipeline) → module is poorly isolated → REFACTOR
+  IF (test runs standalone in <5s) → module is well-isolated → PASS
+```
+
+## Failure Modes
+
+### O Bug que Levou 30min pra Achar
+- **Trigger:** `${variable}` quoting bug in shared function. Tested via full pipeline.
+- **Manifestation:** 30 min debugging pipeline logs to find 1-character bug.
+- **Detection:** Test suite would find it in 2 seconds.
+- **Prevention:** Smoke test isolado. 94 testes em 30s catch o que pipeline levaria 30min.
+
+---
+
+## Validation
+
+✅ **Paradoxo Identificado:** Isolamento X Integração
+- **Isolado:** Rápido (2s), mas não valida dependências reais
+- **Pipeline:** Lento (30min), mas mascara bugs locais em ruído de logs
+
+✅ **Resolução:** Camadas — Isolado (smoke) + Semanal (full pipeline) + Contínuo (regressão por feature)
+
+✅ **Evidence Linking:** Bug ${} seria encontrado em 2s, não 30min
+
+✅ **Actionable:** IF módulo compartilhado THEN <5s smoke test SEM exceção

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

@@ -0,0 +1,64 @@
+# AN_KE_017 - Research No Meio, Não No Início
+
+**Type:** Decision Heuristic
+**Zone:** 🚀 20% Impacto
+**Agent:** @oalanicolas
+**Pattern:** Timing Optimization
+**Source:** [SOURCE: Epic 71 — tech-research feita após Wave 2, gerou 4 melhorias antes da Wave 3]
+**sys_tension:** (no-research-early vs paralysis-cost, do-research-mid-cycle)
+
+## Purpose
+
+Research no início é paralisante (muitas opções, zero implementação). Research no meio é otimizante (já tem código, valida e melhora). Fazer entre Wave 2 e Wave 3.
+
+## Configuration
+
+```yaml
+AN_KE_017:
+  name: "Research No Meio"
+  zone: "impacto"
+  trigger: "Planejando quando fazer pesquisa/benchmarking"
+
+  rule: |
+    SE projeto tem múltiplas waves/fases
+    NÃO pesquisar antes da Wave 1 (paralisa)
+    PESQUISAR entre Wave 2 e Wave 3 (otimiza)
+    PORQUE já tem implementação real pra comparar com estado da arte
+
+  evidence:
+    - "Wave 1+2: criou módulos + migrou sinkra squad"
+    - "Research: confirmou alinhamento com Anthropic, achou 4 gaps"
+    - "Wave 3: migrou cross-squad COM as 4 melhorias aplicadas"
+    - "Se research fosse antes: 2h de análise sem código pra comparar"
+```
+
+## Decision Tree
+
+```javascript
+IF (planning_research_timing)
+  Wave 1-2: BUILD first implementation (no research yet)
+  BETWEEN Wave 2-3: RESEARCH state of the art
+    COMPARE: your implementation vs industry best practices
+    IDENTIFY: gaps to address in Wave 3
+  Wave 3+: APPLY research findings to improve existing code
+  NEVER: research before Wave 1 (paralizes with options)
+  NEVER: research after final wave (too late to apply)
+```
+
+## Failure Modes
+
+### A Paralisia por Análise
+- **Trigger:** 2 horas pesquisando frameworks antes de escrever 1 linha.
+- **Manifestation:** Análise extensa, zero implementação. Decision fatigue.
+- **Detection:** Research duration > implementation duration at start of project.
+- **Prevention:** Build first (waves 1-2), research mid-project (between 2-3), apply findings (wave 3+).
+
+## Validation
+
+**Paradoxo Identificado:** Research é essencial para decisões informadas, mas research antecipado paralisa a ação. A tensão é entre:
+- **TENSION_WITH:** AN_KE_011 (Compare Antes de Construir) — Temporal Sequencing Inversion: AN_KE_011 demands research/comparison BEFORE implementation; AN_KE_017 mandates BUILD first, research/validation BETWEEN cycles
+- **RESOLUTION:** "Pesquisa no meio ciclo valida implementação contra state-of-the-art enquanto código já existe pra comparar"
+
+**Validação Empírica:** Epic 71 confirmou: research entre Wave 2-3 gerou 4 melhorias aplicáveis diretamente. Research antecipado teria consumido 2h sem contexto de implementação.
+
+**Validação Processual:** A heurística foi testada em contexto de multi-wave planning e otimizou time-to-value vs decision quality.

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

@@ -0,0 +1,79 @@
+# AN_KE_018 - Audit Gate Antes de Cleanup
+
+**Type:** Veto Heuristic
+**Zone:** 💎 4% Excelência
+**Agent:** @oalanicolas
+**Pattern:** Safe Deletion Protocol
+**Source:** [SOURCE: Story 71.10a — post-process.sh parecia removível, audit descobriu referência transitiva via phase-execution.sh]
+
+## Purpose
+
+Nunca remover código sem grep exaustivo + smoke test. "0 referências diretas" não significa "0 referências transitivas".
+
+## Configuration
+
+```yaml
+AN_KE_018:
+  name: "Audit Gate Antes de Cleanup"
+  zone: "excelencia"
+  trigger: "Removendo código, lib, arquivo, dependência"
+
+  rule: |
+    SE removendo qualquer código/lib/arquivo
+    ENTÃO ANTES:
+    1. grep -rn em TODO o repo (não só no diretório)
+    2. Verificar referências TRANSITIVAS (A sourcea B que usa C)
+    3. Rodar --help/--dry-run em TODOS os consumidores
+    4. Só deletar se 0 referências diretas E 0 transitivas
+
+  veto_condition:
+    trigger: "git rm sem audit"
+    action: "VETO — rodar audit gate primeiro"
+
+  evidence:
+    - "post-process.sh: 0 refs diretas de _safe_jq_update"
+    - "MAS: sinkra-map.sh sourcea post-process.sh que define post_process_phase()"
+    - "phase-execution.sh chama post_process_phase() em 2 pontos"
+    - "Sem audit: teria quebrado sinkra-map pipeline"
+
+  sys_tension:
+    tension_with: "AN_KE_075 (Delete Stale Recreate from Scratch) — assume que deletar rápido é válido vs necessidade de auditoria"
+    resolution: "Grepping direto é necessário mas insuficiente. Transitividade exige rastreamento de cadeias: A→B→C. Apenas smoke tests covering ALL consumers validam segurança."
+```
+
+## Decision Tree
+
+```
+IF (removing code/lib/file)
+  THEN grep -rn across ENTIRE repo
+    IF (0 direct refs)
+      THEN check transitive refs (A→B→C)
+        IF (0 transitive refs)
+          THEN smoke test ALL consumers
+            IF (all pass)
+              THEN safe to remove
+            ELSE
+              VETO
+        ELSE
+          VETO — still in use transitively
+    ELSE
+      VETO — still in direct use
+```
+
+## Failure Modes
+
+### O post-process.sh que Quase Morreu
+- **Trigger:** 0 direct references to `_safe_jq_update` → seems safe to remove.
+- **Manifestation:** sinkra-map.sh sources post-process.sh which defines `post_process_phase()`. phase-execution.sh calls it in 2 points. Pipeline would break.
+- **Detection:** Audit gate: grep transitivo found chain: sinkra-map → post-process → phase-execution.
+- **Prevention:** ALWAYS check transitive references. `grep -rn` across ENTIRE repo, not just direct callers.
+
+---
+
+## Validation
+
+✅ **Paradoxo identificado:** "Ausência de refs diretas (0)" ⟷ "Presença de refs transitivas (múltiplas)"
+
+✅ **Sys_tension documentado:** Conflito entre otimização prematura e segurança via rastreamento transitivo + smoke testing
+
+✅ **Resolução:** Grepping + transitividade + consumer smoke tests = gate seguro antes de deletar

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

@@ -0,0 +1,69 @@
+# AN_KE_019 - Bug de Produção → Módulo Shared
+
+**Type:** Decision Heuristic
+**Zone:** 🔥 0,8% Genialidade
+**Agent:** @oalanicolas
+**Pattern:** Incident → Systemic Protection
+**Source:** [SOURCE: conversa Eudes 2026-03-29 sobre JSON mal-formado → json-validator.sh protege 14 runners]
+**sys_tension:** (localized_fix_vs_systemic_module, h3_threshold_decision)
+
+## Purpose
+
+Quando um bug de produção aparece, perguntar "outros scripts têm o mesmo risco?" Se sim, a correção deve ser um módulo shared, não um fix pontual. Custo igual, blast radius de proteção Nx maior.
+
+## Configuration
+
+```yaml
+AN_KE_019:
+  name: "Bug → Módulo Shared"
+  zone: "genialidade"
+  trigger: "Bug de produção reportado"
+
+  rule: |
+    SE bug de produção aparece
+    ENTÃO PERGUNTAR: "Outros scripts/runners têm o MESMO risco?"
+    SE SIM (3+ afetados) → criar módulo shared, não fix pontual
+    SE NÃO (isolado) → fix pontual OK
+
+  rationale: |
+    Custo de 1 módulo ≈ custo de 1 fix pontual
+    Mas proteção de 1 módulo = N scripts protegidos
+    ROI cresce linearmente com número de consumidores
+
+  evidence:
+    - "Eudes: JSON mal-formado em 1 pipeline"
+    - "Análise: 14 runners parsam JSON de LLM"
+    - "Fix pontual: protege 1. json-validator.sh: protege 14"
+    - "Custo: ~2h em ambos os casos"
+    - "Funções: json_extract (4 strategies), json_validate, json_get, json_has_fields"
+
+  tension_with: "AN_KE_007 (REUSE > CREATE) vs Quando criar módulo shared para bug sistêmico"
+```
+
+## Decision Tree
+
+```
+IF (production_bug_reported)
+  THEN count affected_scripts = grep across codebase
+    IF (affected_scripts >= 3)
+      THEN create shared module (H3 threshold met)
+      THEN integrate into all affected scripts
+    ELSE IF (affected_scripts == 1)
+      THEN fix pontual is OK
+    ELSE (affected_scripts == 2)
+      THEN fix pontual NOW, extract when 3rd appears (H3)
+```
+
+## Failure Modes
+
+### O JSON que Derrubou 14 Runners
+- **Trigger:** LLM gera JSON mal-formado. Sem json-validator.sh, 14 runners falhavam silenciosamente.
+- **Manifestation:** Bug descoberto em 1 script → mesma vulnerabilidade em 14 outros.
+- **Detection:** Eudes reportou JSON parsing error no pipeline.
+- **Prevention:** Bug em 1 script + afeta N scripts = shared module. json-validator.sh protege todos 14.
+
+## Validation
+
+**Paradoxo Identificado:** Custo de criação (1 módulo shared) ≈ Custo de fix pontual. Mas impacto de proteção é assimétrico: **1 fix protege 1 runner** vs **1 módulo protege 14 runners**. A decisão não é econômica (custo), é estratégica (cobertura de risco). O H3 threshold (3+ afetados) é o ponto de inflexão onde a assimetria justifica o investimento.
+
+**Resolução:** When cost is equal, blast radius of protection determines the decision. Systemic protection always wins over localized fixes when N ≥ 3.

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

@@ -0,0 +1,67 @@
+# AN_KE_020 - Formato Do Artefato É o Contrato
+
+**Type:** Decision Heuristic
+**Zone:** 🚀 20% Impacto
+**Agent:** @oalanicolas
+**Pattern:** Schema as Contract
+**Source:** [SOURCE: Epic 70+71 — validation.log e score_card.yaml padronizados via reporting.sh, 3 formatos → 1]
+**sys_tension:** (code_flexibility_vs_schema_rigidity, unified_schema_enforced_via_shared_emitters)
+
+## Purpose
+
+O formato do artefato de saída (log, score_card, state.json, progress.txt) é o contrato entre o runner e seus consumidores. Padronizar o formato é mais importante que padronizar o código.
+
+## Configuration
+
+```yaml
+AN_KE_020:
+  name: "Formato = Contrato"
+  zone: "impacto"
+  trigger: "Definindo outputs de pipeline/runner/processo"
+
+  rule: |
+    SE múltiplos scripts produzem artefatos consumidos por outros
+    ENTÃO padronizar o SCHEMA do artefato (campos, tipos, formato)
+    Código interno pode variar — o que importa é o output
+    Dois scripts podem ter código totalmente diferente
+    DESDE QUE produzam artefatos no mesmo schema
+
+  evidence:
+    - "validation.log: 3 formatos diferentes → 1 (Target/Type/Score/Verdict/Dims)"
+    - "score_card.yaml: 3 schemas → 1 (validation/checks/dimensions/scores)"
+    - "Qualquer ferramenta que lê score_card de qualquer runner sabe o schema"
+    - "reporting.sh: emit_validation_log() + emit_score_card_yaml() = contrato"
+
+  tension_with: "AN_KE_021 (Repair Layer Between Generator and Validator) — Schema rigidez vs flexibilidade de adaptação"
+```
+
+## Decision Tree
+
+```javascript
+IF (defining_pipeline_outputs)
+  STEP_1: DEFINE output schema (fields, types, format)
+    SCHEMA is the contract, not the code
+  STEP_2: VALIDATE all producers emit same schema
+    IF (producer_A.schema != producer_B.schema) → ALIGN schemas
+  STEP_3: CODE is free to vary internally
+    Two scripts with different code but same output schema = OK
+  NEVER: standardize code but leave outputs inconsistent
+```
+
+## Failure Modes
+
+### Os 3 Formatos de Score Card
+- **Trigger:** validate-skill, validate-squad, sinkra-map each produce score cards in different formats.
+- **Manifestation:** Consumer tool can't read score cards from different producers.
+- **Detection:** 3 parsers needed for 3 producers. Should be 1 parser, 1 schema.
+- **Prevention:** emit_score_card_yaml() as shared function. Schema = contract.
+
+## Validation
+
+**✓ Verified:** Schema standardization enforces contract invariants across heterogeneous producers.
+
+**✓ Evidence:** reporting.sh emit_validation_log() + emit_score_card_yaml() demonstrate single schema consumable by N producers with M internal implementations (code free to vary, schema immutable).
+
+**✓ Resolution:** Tension resolved via shared emitter functions — code flexibility achieved by centralizing schema contract, not duplicating it across producers.
+
+**✓ Applied in:** validate-skill, validate-squad, sinkra-map (unified score_card.yaml schema, parallel codebases).

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

@@ -0,0 +1,114 @@
+# AN_KE_021 - Repair Layer Between Generator and Validator
+
+**Type:** Architecture Heuristic
+**Zone:** 🚀 20% Impacto
+**Agent:** @oalanicolas
+**Pattern:** Defense in Depth
+**Source:** [SOURCE: Sessao 2026-03-29 — yaml-repair.py desbloqueou Opus (0% → 67% completion)]
+**sys_tension:** (Repair gratuito ($0) vs custo de implementar/manter worker determinístico | Resolver com automação open-source: json_repair (3M+ downloads), yaml-repair.py — um padrão já validado pela indústria)
+
+## Purpose
+
+Entre a geracao do LLM e a validacao, deve existir uma camada de repair deterministica. Repair e instantaneo e gratuito. Retry custa tokens e tempo.
+
+## Configuration
+
+```yaml
+AN_KE_021:
+  name: "Repair Layer"
+  zone: "impacto"
+  trigger: "Pipeline com LLM gerando structured output + validation"
+
+  rule: |
+    SEMPRE ter Worker de repair entre geracao e validacao
+    Fluxo: LLM gera → repair (deterministic, $0) → validate → retry (se necessario)
+    NUNCA validar output cru do LLM sem repair primeiro
+    Repair e mais barato que 1 retry (tokens vs $0)
+
+  anti_pattern: "Validar direto → falhar → retry → LLM gera mesmo erro → retry → circuit breaker"
+
+  tension_with: "AN_KE_058 (Verify LLM Output) — Direct validation vs repair-then-validate"
+
+  evidence:
+    - "Opus sem repair: 0/9 fases (5 iteracoes desperdicadas na fase 1)"
+    - "Opus com repair: 6/9 fases ($0.28, yaml-repair corrigiu 11 erros em <1s)"
+    - "Haiku sem repair: 0/9 fases (nested quotes repetiam 5x)"
+    - "Haiku com repair: 5/9 fases ($0.08)"
+    - "json_repair (pip): 3M+ downloads/mes — industria ja usa este pattern"
+    - "Custo de 1 repair: $0, <1s. Custo de 1 retry: ~$0.02-0.05, ~60s"
+
+  architecture:
+    flow: |
+      LLM.generate()
+        → repair_worker(output)     # $0, <1s, deterministic
+          → schema_validate(output) # $0, <1s, deterministic
+            → [PASS] use output
+            → [FAIL] retry_with_error_context(max=3)  # $$ per retry
+              → [STILL FAIL] fallback_model or escalate
+
+    repair_types:
+      json:
+        library: "json_repair (pip)"
+        fixes: "missing quotes, trailing commas, unescaped chars, incomplete objects"
+      yaml:
+        library: "yaml-repair.py (custom)"
+        fixes: "colon-in-value, nested quotes, tabs→spaces, scalar-with-child"
+      markdown:
+        library: "none needed (tolerant format)"
+
+  cost_comparison:
+    without_repair:
+      avg_retries: 2.5
+      cost_per_retry: "$0.02-0.05"
+      total_wasted: "$0.05-0.13 per phase"
+      time_wasted: "150-300s per phase"
+    with_repair:
+      repair_cost: "$0"
+      repair_time: "<1s"
+      avg_retries: 0.3
+      total_saved: "~$0.04-0.10 per phase"
+```
+
+## Decision Tree
+
+```javascript
+IF (pipeline_has_llm_generating_structured_output)
+  CHECK: is there a repair layer between generate and validate?
+    IF (NO) → ADD repair layer
+    IF (YES) → verify it covers most common error types
+
+  FLOW: LLM.generate() → repair($0, <1s) → validate($0) → [PASS|FAIL→retry($$)]
+
+  REPAIR_TYPE_SELECTION:
+    IF (json output) → use json_repair (pip, 3M+ downloads)
+    IF (yaml output) → use yaml-repair.py (custom: colon-in-value, nested quotes)
+    IF (markdown output) → no repair needed (tolerant format)
+
+  NEVER: validate raw LLM output without repair first
+  NEVER: use LLM for repair (defeats purpose — repair must be $0)
+```
+
+## Failure Modes
+
+### O Opus que Custou 5x Mais
+- **Trigger:** Opus generates YAML with syntax errors. No repair layer. 5 retries per phase.
+- **Manifestation:** 0/9 phases completed. 5 iterations wasted on phase 1. Cost: $0.05-0.13/phase in retries.
+- **Detection:** Retry rate > 2 per phase. Same error category repeating.
+- **Prevention:** yaml-repair.py between generate and validate. 0% → 67% completion. Repair cost: $0, <1s.
+
+## Validation
+
+**Checkpoints:**
+- [ ] Pipeline tem LLM gerando structured output (JSON/YAML)?
+- [ ] Existe repair layer entre generate e validate?
+- [ ] Repair é determinístico (não usa LLM)?
+- [ ] Repair custa $0 e roda em <1s?
+- [ ] Cobre json_repair (3M+ downloads) para JSON?
+- [ ] Cobre yaml-repair.py para YAML?
+- [ ] Retry só ocorre pós-repair e validation?
+- [ ] Métricas rastreiam retry rate vs repair cost?
+
+**Validação de Efetividade:**
+- Baseline: Retry rate > 2 por phase = sinal de falta de repair
+- Com repair: Retry rate cai para 0.3 por phase (90% redução)
+- ROI: ~$0.04-0.10 economizado por phase em retries evitados