aiox-core 5.0.4 → 5.0.7

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

@@ -0,0 +1,87 @@
+# AN_KE_041 - Output Path Discipline
+
+```yaml
+---
+id: AN_KE_041
+name: "Output Path Discipline"
+type: "Artifact Classification Heuristic"
+zone: "🔥 20% Impacto"
+agent: "@oalanicolas"
+pattern: "Separação outputs/ vs squads/"
+source: "[SOURCE: Sessão sinkra-hub 058541ef + regra artifact-classification.md]"
+sys_tension:
+  tension_with: "AN_KE_054 (Estrutura Orgânica de Diretórios) vs Isolamento de Outputs: paths devem ser orgânicos mas outputs devem ficar segregados"
+  resolution: "Criar symlinks em outputs/shared/ ou registry index em .aiox-core/core-config.yaml com mapa de outputs reutilizáveis por ID de artefato. Outputs imutáveis → versionados; outputs transitórios → TTL."
+```
+
+## Purpose
+
+Outputs de execução de pipelines/squads vão em `outputs/`, NUNCA dentro de `squads/` ou `workspace/`. Squads contêm config, agents, tasks. Outputs contêm resultados transitórios de execução.
+
+## Configuration
+
+```yaml
+AN_KE_041:
+  name: "Output Path Discipline"
+  zone: "impacto"
+  trigger: "Salvando resultados de pipeline, análise, validação, ou qualquer artefato gerado."
+
+  rule: |
+    SE artefato é resultado de execução de squad/task
+    ENTÃO salvar em outputs/{squad-name}/{context}/
+    NUNCA dentro de squads/{squad-name}/output/
+    NUNCA dentro de workspace/
+
+  veto_condition:
+    trigger: "Pipeline salvando resultados dentro da pasta do squad ao invés de outputs/."
+    action: "VETO — Mover para outputs/. Squads são config, não storage."
+
+  evidence:
+    - "[SOURCE: sessão 058541ef] 'o local certo para salvar isso é outputs na pasta principal e nao dentro do squad sinkra'"
+    - "[SOURCE: .claude/rules/artifact-classification.md] Decision tree: 'É output de execução de squad/task? SIM → outputs/{squad-name}/'"
+```
+
+## Decision Tree
+
+```javascript
+IF (saving_generated_artifact)
+  IF (artifact_is_config OR agent OR task OR template)
+    THEN SAVE in squads/{squad-name}/
+  ELSE IF (artifact_is_execution_output OR analysis OR report)
+    THEN SAVE in outputs/{squad-name}/{context}/
+  ELSE IF (artifact_is_business_document with template + registry)
+    THEN SAVE in workspace/businesses/{slug}/L{N}/
+```
+
+## Failure Modes
+
+### Squad Bloat
+- **Trigger:** Pipeline salva 50MB de outputs dentro de `squads/sinkra-squad/output/`.
+- **Manifestation:** Squad fica pesado, git clone lento, confusão entre config e outputs.
+- **Detection:** `du -sh squads/*/` mostra squad com >10MB.
+- **Recovery:** Mover para `outputs/` e atualizar paths nos scripts.
+
+## Integration with Workflow
+
+```yaml
+checkpoint:
+  id: "output-path-gate"
+  heuristic: AN_KE_041
+  phase: "Pipeline_Output_Design"
+```
+
+## Validation
+
+**Systemic Tension (sys_tension):**
+- **Tension With:** Pipeline reusability requirements vs. artifact isolation discipline
+- **Paradox:** Outputs must stay isolated in `outputs/` (not in `squads/`) to prevent config bloat → BUT outputs of one squad's execution frequently need to feed into downstream pipelines of other squads → requires fast discovery + access
+- **Resolution Path:** Version and index outputs via centralized registry (`.aiox-core/core-config.yaml → artifact_outputs[]`) instead of embedding paths. Symlinks allow logical grouping without duplication. TTL policies on transitional outputs separate temporary work from reusable artifacts.
+
+**Validation Checklist:**
+- [ ] Output directories contain ONLY execution artifacts (no config files, no agents, no tasks)
+- [ ] No outputs directory is nested inside `squads/{name}/`
+- [ ] `outputs/{squad-name}/{context}/` follows discoverable naming convention
+- [ ] Reusable outputs registered in artifact registry with immutability flag + version
+- [ ] Transitional outputs have explicit TTL; stale outputs pruned via `cleanup:artifacts` task
+- [ ] No pipeline reads outputs by hardcoded path; all reads go through registry lookup
+- [ ] git history shows outputs/ only contains committed outputs when intentional (not CI artifacts)

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

@@ -0,0 +1,89 @@
+# AN_KE_042 - Don't Regress Working Code
+
+**Type:** Development Discipline Heuristic
+**Zone:** 💎 4% Excelência
+**Agent:** @oalanicolas
+**Pattern:** Preservar o que Funciona
+**Source:** [SOURCE: Múltiplas sessões mmos — frustração recorrente com AI revertendo código funcional]
+
+## Purpose
+
+A IA tem tendência de "melhorar" código que já funciona, introduzindo regressões. Se algo funciona em localhost, a prioridade é PRESERVAR, não refatorar. Mudanças devem ser aditivas, nunca destrutivas sobre funcionalidade existente.
+
+## Configuration
+
+```yaml
+AN_KE_042:
+  name: "Don't Regress Working Code"
+  zone: "excelencia"
+  trigger: "IA propondo refatoração, simplificação, ou 'melhoria' de código existente."
+
+  rule: |
+    SE código funciona em localhost/prod
+    ENTÃO preservar. Mudanças aditivas, nunca destrutivas.
+    SE simplificação proposta → testar ANTES de aplicar.
+    SE regressão detectada → git revert imediato, não tentar consertar em cima.
+
+  sys_tension:
+    tension_with: "AN_KE_085 (Greenfield Over Spaghetti Refactor) — Refactoring vs Preservation"
+    resolution: "Default to PRESERVE when functionality works. Only REFACTOR when explicitly required for new feature integration. Always TEST before applying changes. If regression occurs, REVERT immediately and analyze surgically."
+
+  veto_condition:
+    trigger: "IA refatorando algo que estava funcionando sem garantir que continua funcionando."
+    action: "VETO — 'tava funcionando, pq está revertendo algo que estava funcionando?'"
+
+  evidence:
+    - "[SOURCE: sessão mmos 435f78cd] 'tava funcionando localhost, pq está revertendo algo que estava funcionando?'"
+    - "[SOURCE: sessão mmos 9701cc32] 'Continua puxando do banco de dados... basta reverter no git, no git tá funcionando'"
+    - "[SOURCE: sessão mmos c61a9260] 'vamos reverter essa simplificação'"
+    - "[SOURCE: sessão mmos cfecb27d] 'ta errado usar slug, o certo é usar o nome real do arquivo e trazendo a URL direto do banco'"
+```
+
+## Decision Tree
+
+```javascript
+IF (ai_proposes_refactor OR simplification)
+  IF (current_code_works_in_localhost)
+    THEN DEFAULT = PRESERVE
+    IF (refactor_is_critical for new feature)
+      THEN TEST_FIRST before applying
+    ELSE
+      THEN SKIP refactor — "if it works, don't touch it"
+  IF (regression_detected_after_change)
+    THEN IMMEDIATE git revert
+    THEN ANALYZE what broke
+    THEN RE-APPLY surgically (not the whole refactor)
+```
+
+## Failure Modes
+
+### A Melhoria que Quebra
+- **Trigger:** IA decide "simplificar" lógica de URL de imagens trocando campo real por slug derivado.
+- **Manifestation:** Imagens param de carregar. Slug não corresponde ao nome real do arquivo.
+- **Detection:** "ta errado usar slug, o certo é usar o nome real do arquivo".
+- **Recovery:** git revert + restaurar lógica original.
+- **Prevention:** Nunca substituir campo real (image_url) por campo derivado (slug) sem testar.
+
+## Integration with Workflow
+
+```yaml
+checkpoint:
+  id: "regression-prevention-gate"
+  heuristic: AN_KE_042
+  phase: "Code_Review / Refactoring"
+```
+
+## Validation
+
+**Paradox Identified:** The tension between code optimization (refactoring) and system stability (preservation of working functionality) is inherent to this heuristic. The resolution enforces a conservative bias: when functionality works, optimization is deferred unless explicitly required by new features. This prevents the error pattern where "improvements" introduce silent regressions.
+
+**Application Criteria:**
+- ✓ Code executes correctly in localhost/staging
+- ✓ Existing tests pass without modification
+- ✓ No performance degradation observed
+- ✓ No security vulnerabilities exploited
+
+**Validation Triggers:**
+1. If AI proposes refactoring → require BEFORE/AFTER test evidence
+2. If regression detected → mandatory git revert + root cause analysis
+3. If refactor is feature-critical → apply surgical changes only, not full refactors

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

@@ -0,0 +1,78 @@
+# AN_KE_043 - Zero Achismos
+
+**Type:** Mental Model & Data Execution Heuristic
+**Zone:** 🔥 20% Impacto
+**Agent:** @oalanicolas
+**Pattern:** Rejeição de Alucinação Criativa / Grounded Delivery
+**Source:** [SOURCE: Extrações de alinhamento estratégico, forçando a LLM e agentes a jamais inventarem diretrizes com base na teoria estocástica generalista da rede, e sim na crueza dos templates do local de trabalho.]
+
+## Purpose
+
+Prevenir que a superinteligência LLM opere no "modo palpiteiro hiper-confiante" preenchendo as lacunas e inventando estratégias maravilhosas, gerando extrapolações perigosas sem validações com a dura e inegável base dos dados, documentos reais e processos corporativos.
+
+## Configuration
+
+```yaml
+AN_KE_043:
+  name: "Zero Achismos"
+  zone: "impacto"
+  trigger: "Agente encarregado de desenhar tarefas estratégicas de execução (SOPs, Workouts) onde faltam direções."
+
+  rule: |
+    SE a IA perceber uma lacuna estratégica ao criar a solução pedida a ela
+    ENTÃO acione a diretiva de Grounded Inference: "Apenas entregue processos baseados integralmente nos templates disponíveis na base e evidências já mapeadas".
+
+  veto_condition:
+    trigger: "Criar uma tática mirabolante importada genericamente do modelo geral LLM por falta de consulta apropriada aos Manuais e Dados operacionais."
+    action: "VETO — Destrua as inovações infundadas, e opere restritamente nas paredes do que é conhecido provado da organização."
+
+  sys_tension:
+    tension_with: "AN_KE_017 (Research No Meio, Não No Início) — Permite exploração criativa durante execução vs. Zero Achismos exigindo grounding total pré-execução"
+    resolution: "When a template gap is discovered: (1) Flag the gap explicitly, (2) Deliver only grounded portions, (3) Ask human to provide the missing template or accept the incomplete scope. NEVER extrapolate to fill gaps."
+
+  evidence:
+    - "[EXACT WORDS]: Gostei, mas quero isso baseado em processos reais, em algo palpável e não achismos da LLM, cada task precisa ser baseado em estratégias comprovadas e baseada 100% em dados que temos disponiveis sem criar extrapolações."
+```
+
+## Decision Tree
+
+```javascript
+IF (creating_strategy OR fulfilling_empty_gaps_in_task)
+  IF (strategy_concept_originates_from_company_document == TRUE)
+    // Document exists e.g., 'templates/our-proven-sales-funnel.md'
+    THEN ALLOW_APPLICATION
+  ELSE
+    // Extrapolating a theoretical standard idea out of GPT's brain
+    THEN BLOCK_EXTRAPOLATION
+    THEN SEARCH_INTERNAL_BASE ("Requirir explicitamente os moldes originais locais")
+      IF (no mold found)
+        THEN RAISE_EXCEPTION_TO_USER ("Alan, não possuo o template real base disto, devo esperar que me adicione ou interromper?")
+```
+
+## Failure Modes
+
+### Escorregamento "Fake-Guru"
+- **Trigger:** Ao pesquisar e consolidar um livro de um expert, uma etapa exigia a descrição dos maiores KPIs de funil mas o documento raiz não listava nada disso.
+- **Manifestation:** O agente deduz os "5 típicos funis mundiais", escreve 18 páginas cheias de arrogância estocástica e entrega. O time acata como se fosse a genialidade do expert original.
+- **Detection:** Disparidade grave entre o trabalho pregresso (onde o modelo mental genuíno era adotado) e este "copy paste de blog moderno americano".
+- **Recovery:** Interromper, apagar os artefatos, mandar o agente reler e assumir onde "Não consta em documentação - lacuna necessária preencher por humanos".
+- **Prevention:** Gates de restrição mental: "Só responda pelo que está presente concretamente na RAG ou nos `.md` passados."
+
+## Integration with Workflow
+
+```yaml
+checkpoint:
+  id: "anti-hallucination-strategy-gate"
+  heuristic: AN_KE_043
+  phase: "Knowledge_Synthesis"
+
+  validation_questions:
+    - "Eu posso atestar em um tribunal a origem literata deste arquivo interno em relação a cada um dos processos operacionais sugeridos acima?"
+```
+
+## Validation
+
+- **Template Traceability:** Every suggested process MUST be traceable to a named template file (e.g., `templates/sales-funnel-v2.md`) or an exact document section with line reference.
+- **Evidence Chain:** If no template exists, the gap MUST be documented as `LACUNA-{id}` with escalation to human for template provisioning.
+- **No Speculative Fills:** Creativity is welcome AFTER the human provides the missing template. Until then: BLOCK and REPORT.
+- **Audit Trail:** Every decision to apply or reject a strategy suggestion MUST be logged with the source evidence or the "no source found" exception.

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

@@ -0,0 +1,97 @@
+---
+heuristic_id: AN_KE_044
+name: "URL = State Truth (Deep Linking)"
+zone: excelencia
+type: "Architecture UI/UX Heuristic"
+agent: "@oalanicolas"
+pattern: "React & JS State vs Browser History"
+sys_tension:
+  tension_with: "AN_KE_103 (Local Caching Over Live Database)"
+  resolution: "Lazy-load state from URL params on mount; cache parsed state in React memory for perf; invalidate on URL change"
+source: |
+  Frustrações expressas com componentes que aprisionam o "State" localmente e quebram as premissas primárias do "Browser" (foward, back, refresh). Refatorações em Dashboards e Lojas de Cursos.
+---
+
+# AN_KE_044 - URL = State Truth (Deep Linking)
+
+**Type:** Architecture UI/UX Heuristic
+**Zone:** 💎 4% Excelência
+**Agent:** @oalanicolas
+**Pattern:** React & JS State vs Browser History
+**Source:** [SOURCE: Frustrações expressas com componentes que aprisionam o "State" localmente e quebram as premissas primárias do "Browser" (foward, back, refresh). Refatorações em Dashboards e Lojas de Cursos.]
+
+## Purpose
+
+Assegurar acessibilidade profunda em projetos web complexos. Quando listas compridas, filtros ou abas vivem apenas em um `useState` em React sem reflexos na URL do browser (e.g. `?tab=cursos&page=2`), o usuário perde anos de memória celular de navegação web (refresh destrói as tabs ativas).
+
+## Configuration
+
+```yaml
+AN_KE_044:
+  name: "URL = State Truth (Deep Linking)"
+  zone: "excelencia"
+  trigger: "Construindo gerenciamento de estado em UIs complexas (Listas, Filtros, Tabs, Paineis modais extensos ou Breadcrumbs)."
+
+  rule: |
+    SE você implementar a gestão de estado central de um componente pesado de navegação
+    ENTÃO ele DEVE modificar dinamicamente a URL usando searchParams ou Pathing Slug.
+    A URL dita quem é o State do aplicativo; NUNCA deixe estado trancado na caixinha de memória da página, se o usuário der refresh, a página não deve resetar misteriosamente para o estado zero.
+
+  veto_condition:
+    trigger: "Criar uma tabela enorme de usuários com React Data Table onde filtrar `name=john` não altera o query da URL em cima."
+    action: "VETO — Amarre os gatilhos ao useSearchParams / history Push para resiliência de recarregamento (F5) impecável."
+
+  evidence:
+    - "[EXACT WORDS]: Eu quero que o sistema funcione modifiquendo também a URL, assim pode voltar para mesma página sem precisar navegar até ela sempre que entrar."
+```
+
+## Decision Tree
+
+```javascript
+IF (creating_filter OR implementing_tabs_panel OR page_pagination)
+  IF (state_management_is_exclusively_local_memory == TRUE)
+    // Only uses React hooks like `const [activeTab, setActiveTab] = useState()`
+    THEN INITIATE_VETO
+    THEN REQUIRE_URL_SYNCHRONIZATION ("Refatore para usar next/compat ou Router Hooks injetando '?tab=X' na URI da aba e a tela leia essa fonte da verdade.")
+      IF (State is successfully extracted from URI)
+        THEN proceed cleanly. (User can bookmark the current filtered setup)
+  ELSE
+    // Standard approach of Web Routing
+    THEN ALLOW_PRODUCTION
+```
+
+## Failure Modes
+
+### Amnésia Total por Refresh
+- **Trigger:** Após aplicar 5 complexos dropdown filters e selecionar arquivos em um checklist massivo de cursos dentro da URL raiz.
+- **Manifestation:** O usuário clica em "Detalhes do Produto" em nova aba. Em seguida, erra o clique no histórico ("back"). Todos os 5 filtros somem. A página retorna estúpida.
+- **Detection:** Reclamações frustrantes de clientes pedindo que o sistema lembre deles.
+- **Recovery:** Re-codificar a máquina de estados (React Query etc.) atrelando puramente search params.
+- **Prevention:** Exigência no prompt de design de UX "Todas as escolhas não efêmeras de navegação devem gerar hashes de URL".
+
+## Integration with Workflow
+
+```yaml
+checkpoint:
+  id: "state-lives-in-url"
+  heuristic: AN_KE_044
+  phase: "Frontend_Component_Creation"
+```
+
+## Validation
+
+**Acceptance Criteria:**
+- [ ] All filterable/navigable state is present in URL searchParams or path slug
+- [ ] Refresh (F5) preserves the exact UI state without loss of context
+- [ ] Browser back/forward buttons correctly traverse the state history
+- [ ] Bookmarkable URLs resolve to the exact same component state
+- [ ] Performance is not degraded (cached state in React; lazy-load from URL on mount only)
+
+**Test Case:**
+1. Apply 5 complex filters + select items in a checklist
+2. Refresh the page (F5)
+3. Verify all filters and selections remain intact
+4. Verify URL contains all state parameters
+5. Copy URL, open in new tab, verify identical state loads
+
+**Resolution:** If state is lost on refresh or URL does not reflect UI state, apply VETO and refactor using `useSearchParams()` (Next.js) or `useLocation/history` (React Router) to synchronize state bidirectionally with the browser URL.

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

@@ -0,0 +1,82 @@
+# AN_KE_045 - Subtraction First Strategy
+
+**Type:** Analytical Framework
+**Zone:** 🧠 0,8% Genialidade
+**Agent:** @oalanicolas
+**Pattern:** Ockham's Razor e Simplicidade Oculta
+**Source:** [SOURCE: Extrações base do handoff do PKM v2 e modelamento central do Derek Sivers.]
+
+## Purpose
+
+Criar um atalho radical de eficiência cortando camadas burocráticas inteiras (workflows, apps e bots soltos). A intuição humana nativa sempre adiciona mais mecanismos para lidar com atrito; gênios resolvem problemas removendo as camadas defeituosas que os criam.
+
+## Configuration
+
+```yaml
+AN_KE_045:
+  name: "Subtraction First Strategy"
+  zone: "genialidade"
+  trigger: "Quando avaliando novos recursos, apps secundários, integrações ou o workflow diário da Base."
+
+  rule: |
+    SE você encontrar um gargalo burocrático, lento ou atritivo numa arquitetura ou modelo de conhecimento
+    ENTÃO DESTRUA em vez de construir paliativos em cima. Pare de adicionar plugins e scripts de conserto; aplique "Subtract not Add".
+
+  sys_tension:
+    tension_with: "AN_KE_073 (Parallel Subagents for Throughput) — Subtração remove camadas de orquestração necessárias para paralelização efetiva, criando gargalo sequencial em arquiteturas distribuídas."
+    resolution: "Validar pré-remoção: (1) alternativa sobrevive escalas futuras? (2) Não há conformidade/auditoria perdida? (3) Custo de re-arquitetar depois < custo mantendo stack atual? Se NÃO em qualquer, use SIMPLIFY ao invés de SUBTRACT."
+
+  veto_condition:
+    trigger: "Tentativa de resolver a complexidade de múltiplos calendários criando uma nova IA central de 'Sincronização entre Agendas'."
+    action: "VETO — Force o corte radical. Remova 3 das agendas. Zere a variável na origem."
+
+  evidence:
+    - "[EXACT WORDS]: O que tira peso mental? 'Subtract not add' - Remove antes de adicionar ferramentas de 'manage' de peso mental. Useful not true - Foco em modelos úteis."
+```
+
+## Decision Tree
+
+```javascript
+IF (identifying_frictions_in_current_setup OR feeling_cognitive_overload)
+  IF (solution_proposes_adding_new_tool == TRUE)
+    THEN BLOCK_ADDITION
+    THEN RUN_SUBTRACTION_AUDIT
+      IF (can drop the entire process out of existence safely)
+        THEN REMOVE_PROCESS
+      ELSE
+        THEN SIMPLIFY_DOWN_TO_BONE ("No plugins, plain text, single source.")
+  ELSE
+    // Directing towards native or zero-footprint approach
+    THEN ALLOW_MODIFICATION
+```
+
+## Failure Modes
+
+### Zumbis App-Stack
+- **Trigger:** Com a desculpa de "Otimizar o Flow", instalar Zapier, Make e Notion para organizar pastas do macOS.
+- **Manifestation:** Em menos de três semanas o sistema perde eficácia por não ser tolerante à bagunça. O indivíduo agora trabalha *para manter as ferramentas de produtividade*, e não para produzir.
+- **Detection:** Reclamação explícita sobre a lentidão nos handoffs e loops gigantes do Agente ou o dono de negócio gastando 70% do tempo arrumando etiquetas no Notion.
+- **Recovery:** Apagar as subcriaturas da stack, limpar a IA e retornar à base CLI/Text Puro.
+- **Prevention:** Um gate de "Adição" que exige provar a impossibilidade de usar a Subtração.
+
+## Integration with Workflow
+
+```yaml
+checkpoint:
+  id: "subtraction-razor-gate"
+  heuristic: AN_KE_045
+  phase: "Architecture_Review"
+
+  validation_questions:
+    - "A próxima ferramenta vai introduzir um peso de manutenção eterno para resolver um atrito efêmero? Posso purgar a ação defeituosa?"
+```
+
+## Validation
+
+**Paradox Check:** ✓ Identificado
+- **Paradoxo:** Subtração cria fragilidade (plain text sem escala) vs. Adição cria complexidade (stack bloated).
+- **Tensão Sistêmica:** Remover ferramentas de governança (auditoria, controle de acesso, versionamento) economiza peso mental *hoje* mas cria risco futuro.
+- **Resolução:** Não é SUBTRACT vs. ADD. É SUBTRACT vs. SIMPLIFY vs. ADAPT. Use SUBTRACT apenas se validar escalabilidade da alternativa.
+- **Evidência:** Zumbis app-stack (Notion pesado) vs. CLI puro sem histórico = dois extremos. O ponto ótimo está na *remoção seletiva*.
+
+**Aplicabilidade:** Medium (funciona para workflows pessoais; requer guardrails para arquiteturas compartilhadas).

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

@@ -0,0 +1,83 @@
+# AN_KE_046 - Fórmula da Transformação de Voz
+
+**Type:** Copywriting Core Heuristic
+**Zone:** 🔥 20% Impacto
+**Agent:** @oalanicolas
+**Pattern:** Content Generation (Non-Commodity)
+**Source:** [SOURCE: Extraído da fórmula magna da Mentelendária contra o tom artificial plastificado de robôs na internet.]
+
+## Purpose
+
+Forjar uma estrutura algorítmica inquebrável para escrita fantasma e comunicações "Soulful" originárias da Mente de Alan Nicolas. Destruir as introduções chatas e estabelecer a conexão profunda de dor e prova exigida pelo ICP Premium.
+
+## Configuration
+
+```yaml
+AN_KE_046:
+  name: "Fórmula da Transformação de Voz"
+  zone: "impacto"
+  trigger: "Quando o agente receber o comando para gerar copywriting profundo, emails diários ou livros sob o manto da marca Mentelendária."
+
+  sys_tension:
+    tension_with: "AN_KE_073 (Parallel Subagents for Throughput) vs Transformação Narrativa Profunda (processamento reflexivo linear)"
+    resolution: "Ancor a vulnerabilidade em dados concretos e histórias verificáveis. O dado prova a dor; a história humaniza a prova; o desafio socrático exige ação autêntica do leitor."
+
+  rule: |
+    SE o Agent precisar escrever textos longos ou argumentos narrativos de alta conversão
+    ENTÃO exija o enquadramento na fórmula inquebrável: [Vulnerabilidade + Dados + História + Desafio Socrático]. Sem isto é apenas dados; com isto é "Transformação".
+
+  veto_condition:
+    trigger: "Redigir inícios perfeitos onde o locutor é onisciente, não expõe o sacrifício e apresenta o framework de modo passivo/indiferente."
+    action: "VETO — Pare a geração. Quebre a linha. Force a injeção do caos humano e do choque paradoxal entre dois conceitos."
+
+  evidence:
+    - "[EXACT WORDS]: Vulnerabilidade + Dados + História + Desafio = Transformação... Contrastes extremos e perguntas socráticas... Primeira pessoa autêntica sempre."
+```
+
+## Decision Tree
+
+```javascript
+IF (writing_brand_story OR persuasive_copy)
+  IF (narrative_misses_Vulnerability_or_Socratic_Questions == TRUE)
+    THEN BLOCK_DELIVERY
+    THEN REWRITE_USING_FORMULA
+      IF (first_paragraph presents raw data immediately)
+        THEN INJECT "A ferida pessoal que gerou o contexto deste dado"
+      IF (conclusion presents standard list)
+        THEN INJECT "Socratic challenge leaving reader with burden of action"
+  ELSE
+    THEN ALLOW_PUBLICATION
+```
+
+## Failure Modes
+
+### Wikipedia-Síndrome
+- **Trigger:** Resumir um princípio de Arquitetura Limpa em post de Vendas. O modelo empaca e age como repórter factual ("Arquitetura Limpa é importante para...").
+- **Manifestation:** Leituras mornas, baixíssimo engajamento; o texto informa mas não "converte", "ensina", "liberta". Zero polarização. Lead não sai da letargia corporativa.
+- **Detection:** Textos terminando com o famigerado "A inteligência artificial transformará X..." (Passividade).
+- **Recovery:** Exigir o contraste radical ("Eu perdi 6 noites debuggando isso. E quase joguei a LLM no fogo. Você também sofre disto?").
+- **Prevention:** Incorporar a Fórmula (V+D+H+D) no Validator Final do Squad de Copy.
+
+## Integration with Workflow
+
+```yaml
+checkpoint:
+  id: "copy-transformative-lens"
+  heuristic: AN_KE_046
+  phase: "Ghostwriting_Review"
+
+  validation_questions:
+    - "A comunicação abre relatando uma jornada imperfeita e conflituosa ou tenta posar de acadêmico sem carne e osso?"
+```
+
+---
+
+## Validation
+
+✓ **Paradoxo Identificado:** Vulnerabilidade sem verdade = manipulação; Verdade sem vulnerabilidade = frieza analítica.
+
+✓ **Resolução:** Ancor vulnerabilidade em dados, história e desafio socrático para manter autenticidade e rigor simultaneamente.
+
+✓ **Integridade da Fórmula:** V+D+H+D permanece inquebrável porque cada componente valida o anterior (dado prova dor; história humaniza; desafio exige ação real).
+
+✓ **Aplicabilidade:** Todos os textos de marketing, ghostwriting e comunicação brand da Mentelendária devem passar por este checkpoint antes de publicação.

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

@@ -0,0 +1,77 @@
+# AN_KE_047 - AI-Predictable Design Systems
+
+**Type:** Modern Architecture Standard
+**Zone:** 💎 4% Excelência
+**Agent:** @oalanicolas
+**Pattern:** Machine-Readable Tokenization
+**Source:** [SOURCE: Criação do Academia Lendária Framework, focando a utilidade do Shadcn não só para humanos, mas também para consumo direto das prompts da LLM.]
+
+## Purpose
+
+Tornar o repositório perfeitamente auditável por IA. Se existirem 90 camadas de CSS modules anônimos separados cruzando SASS global solto, a IA enlouquece toda vez que precisar renderizar uma Landing Page. Ferramentas preditivas (Tailwind + CVA + Shadcn estritos) funcionam porque a API da camada de Design vira um Lego Lógico que modelos de linguagem conseguem decodificar cegamente sem precisar bater olho num figma.
+
+## Configuration
+
+```yaml
+AN_KE_047:
+  name: "AI-Predictable Design Systems"
+  zone: "excelencia"
+  trigger: "Criando ou editando as guias de interface, Design Systems e Repositórios Visuais num mundo LLM-first."
+
+  sys_tension:
+    tension_with: "AN_KE_073 (Parallel Subagents for Throughput) vs Complexidade de Parsing Local"
+    resolution: "CVA Variants as Bridge — Permite expressão criativa humana através de composições semânticas predizíveis para IA. O Designer define as variantes (art), a IA as combina (logic). Sistemas previsíveis para IA requerem linearidade; paralelização introduz não-determinismo."
+
+  rule: |
+    SE for adotar um framework de CSS/Design System
+    ENTÃO NUNCA permita configurações caóticas puramente visuais (como "SASS classes com 99 variaveis de rem magicas"). Trabalhe em lógicas nominais rígidas (CVA) onde a sintaxe por si só revele para o Claude qual a variação a se escalar e usar.
+
+  veto_condition:
+    trigger: "Criar variações customizadas sem atrelar Variância Explícita de Componentes (ex: `<Button className='bg-red text-2xl...' />`)."
+    action: "VETO — Encapsule dentro da Variante do Design System: `<Button variant='destructive' size='lg' />`."
+
+  evidence:
+    - "[EXACT WORDS]: Tailwind + shadcn/ui + CVA é literalmente a combinação perfeita pra transformar esse Brand Guide... E o fato de IAs também vão usar? Isso muda o jogo — precisa ser extremamente previsível."
+```
+
+## Decision Tree
+
+```javascript
+IF (styling_new_interface OR modifying_ui_elements)
+  IF (style_uses_loose_magic_variables_or_arbitrary_tailwind == TRUE)
+    THEN BLOCK_FRONTEND_COMMIT
+    THEN REQUIRE_CVA_ENCAPSULATION
+      IF (component properly defines 'variants' mapping to the Brand Design System standard)
+        THEN proceed scaling with AI automation smoothly
+  ELSE
+    // Component is correctly utilizing the highly strict 'Tailwind->CVA->Shadcn' pipeline
+    THEN ALLOW_RENDER
+```
+
+## Failure Modes
+
+### Hallucination UI Break
+- **Trigger:** IA tenta criar versão de tela preta e falha brutalmente, colapsando classes text-black no meio.
+- **Manifestation:** Em vez de usar a variação inteligente e legível que o CVA possibilita (`variant='dark_mode_inverted'`), a LLM tentou adivinhar com `className="dark:bg-black dark:text-gray-100 ..."`. Em uma lista extensa de cards customizados quebrando padronizações.
+- **Detection:** Análise de commits front-end mostrando desprendimento crônico do padrão primário (O botão padrão deixou de ser usado).
+- **Recovery:** Refatorar todos os componentes livres e criar Variantes Globais na CVA core baseadas nos arquivos mestre.
+- **Prevention:** Veto-Gates de Lint impedindo componentes customizados demais que rejeitassem a biblioteca central.
+
+## Integration with Workflow
+
+```yaml
+checkpoint:
+  id: "ai-readable-cva-gate"
+  heuristic: AN_KE_047
+  phase: "Frontend_Design_Architect"
+
+  validation_questions:
+    - "A LLM v3/v4 conseguirá prever com confiança absoluta o resultado visual que o Tailwind+CVA irá compilar para essa marca ao bater a variante exata 'accent'?"
+```
+
+## Validation
+
+- **Paradoxo Identificado:** Rigidez estrutural (CVA nominais) vs. Liberdade criativa do designer humano. Resolução através de variantes semânticas que são rígidas para IA mas flexíveis para composição humana.
+- **Checkpoint:** Verificar se 100% dos componentes novos passam pela gate `ai-readable-cva-gate` antes de merge.
+- **Métrica:** Zero commits front-end com classes Tailwind arbitrárias fora do CVA core.
+- **Escalabilidade:** CVA deve ser auditável por `grep` — se a variante não está no arquivo core, ela não deveria existir.