aiox-core 5.0.2 → 5.0.3

package/pro/squads/squad-creator-pro/docs/MODEL-TIER-QUALIFICATION.md

@@ -0,0 +1,337 @@
+# Model Tier Qualification Framework
+
+> Squad Creator Token Economy - Validação Empírica de Tasks por Modelo
+
+**Status:** Active
+**Created:** 2026-02-11
+**Owner:** @pedro-valerio + @oalanicolas
+
+---
+
+## 1. Conceito Core
+
+```
+OPUS = BASELINE (100%)
+
+Para cada task:
+1. Roda Opus → Output = Gold Standard
+2. Roda Sonnet → Compara com Gold
+3. Roda Haiku → Compara com Gold
+
+Threshold de aprovação:
+├── Haiku >= 90% → USA HAIKU (máxima economia)
+├── Haiku < 90% mas Sonnet >= 95% → USA SONNET
+└── Ambos < threshold → MANTÉM OPUS
+```
+
+### Economia por Tier
+
+| Tier | Input/1M | Output/1M | vs Opus |
+|------|----------|-----------|---------|
+| Haiku | $1.00 | $5.00 | **-80%** |
+| Sonnet | $3.00 | $15.00 | **-40%** |
+| Opus | $5.00 | $25.00 | baseline |
+
+> **Nota:** Preços atualizados para Opus 4.5/4.6 (fev 2026). Legacy Opus 4.0/4.1 era $15/$75.
+
+---
+
+## 2. Scoring Rubric
+
+Cada output é avaliado em 5 dimensões:
+
+### Dimensões de Qualidade
+
+| Dimensão | Weight | Critério |
+|----------|--------|----------|
+| **Completeness** | 0.30 | Output tem todas as seções/campos esperados? |
+| **Accuracy** | 0.30 | Scores, decisões, classificações corretas? |
+| **Reasoning** | 0.20 | Justificativas coerentes e úteis? |
+| **Format** | 0.10 | Output segue formato esperado? |
+| **Actionability** | 0.10 | Recomendações são acionáveis? |
+
+### Escala de Scoring
+
+```yaml
+completeness:
+  10: "100% das seções presentes"
+  7: "80-99% das seções"
+  4: "50-79% das seções"
+  0: "<50% das seções"
+
+accuracy:
+  10: "100% match com Opus"
+  7: "Diferença < 10%"
+  4: "Diferença 10-30%"
+  0: "Diferença > 30%"
+
+reasoning:
+  10: "Reasoning equivalente ao Opus"
+  7: "Reasoning mais superficial mas correto"
+  4: "Reasoning parcialmente incorreto"
+  0: "Reasoning ausente ou errado"
+
+format:
+  10: "Formato perfeito"
+  5: "Formato parcial"
+  0: "Formato quebrado"
+
+actionability:
+  10: "Tão acionável quanto Opus"
+  5: "Menos específico"
+  0: "Genérico demais"
+```
+
+### Cálculo do Score Final
+
+```
+SCORE = Σ (dimension_score × weight)
+RANGE = 0-10
+PERCENTAGE = SCORE / OPUS_SCORE × 100
+
+THRESHOLD:
+  - Haiku: >= 90% (9.0/10)
+  - Sonnet: >= 95% (9.5/10)
+```
+
+---
+
+## 3. Loop de Compensação
+
+Quando Haiku não atinge 90%, aplicar compensações iterativas:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ COMPENSAÇÃO ITERATIVA                                           │
+│                                                                 │
+│ Tentativa 1: OUTPUT EXAMPLES detalhados                         │
+│              Adicionar 2-3 exemplos concretos no prompt         │
+│              Re-testar → Score melhorou?                        │
+│                                                                 │
+│ Tentativa 2: CHECKLIST INLINE no prompt                         │
+│              Adicionar checklist de validação no próprio prompt │
+│              Re-testar → Score melhorou?                        │
+│                                                                 │
+│ Tentativa 3: TEMPLATE STRICT com campos obrigatórios            │
+│              Forçar estrutura exata de output                   │
+│              Re-testar → Score melhorou?                        │
+│                                                                 │
+│ Tentativa 4: VALIDATION SCRIPT pós-output                       │
+│              Script que valida e pede correção se falhar        │
+│              Re-testar → Score melhorou?                        │
+│                                                                 │
+│ Se após 4 tentativas ainda < 90%:                               │
+│    → Documentar "Haiku não elegível"                            │
+│    → Promover para Sonnet                                       │
+│    → Repetir processo se Sonnet < 95%                           │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Tipos de Compensação
+
+| Tipo | Quando Usar | Exemplo |
+|------|-------------|---------|
+| **Output Examples** | Output está incompleto | Adicionar 2-3 outputs completos de referência |
+| **Checklist Inline** | Está faltando seções | "Verifique: [ ] seção A [ ] seção B [ ] seção C" |
+| **Template Strict** | Formato inconsistente | YAML/JSON schema no prompt |
+| **Validation Script** | Erros detectáveis | Script que valida e retorna erros |
+
+---
+
+## 4. Test Cases
+
+Cada task deve ter um test case padronizado:
+
+### Estrutura do Test Case
+
+```yaml
+# test-cases/{task-name}.yaml
+test_case:
+  name: "{task-name}-standard"
+  version: "1.0"
+
+  input:
+    # Dados de entrada para o teste
+    target: "path/to/real/test/data"
+    params:
+      key: value
+
+  expected_output:
+    # Seções obrigatórias no output
+    sections:
+      - section_1
+      - section_2
+      - section_3
+
+    # Validações específicas
+    validations:
+      - "score deve ser numérico entre 0-10"
+      - "status deve ser PASS|FAIL|REVIEW"
+      - "recommendations deve existir se score < 8"
+
+  baseline:
+    # Referência ao output do Opus
+    opus_output: "test-results/{task-name}/opus-baseline.yaml"
+    opus_score: 10.0  # Por definição
+```
+
+### Localização
+
+```
+squads/squad-creator-pro/
+├── test-cases/
+│   ├── _template.yaml              # Template para novos test cases
+│   │
+│   ├── pv-axioma-assessment/       # Cada task tem sua pasta
+│   │   ├── test-case.yaml          # Definição do teste
+│   │   ├── opus-baseline.yaml      # Output Opus (gold standard)
+│   │   ├── sonnet-output.yaml      # Output Sonnet
+│   │   └── haiku-output.yaml       # Output Haiku
+│   │
+│   ├── validate-squad/
+│   │   ├── test-case.yaml
+│   │   └── ...
+│   └── ...
+│
+├── config/
+│   ├── model-routing.yaml          # Tier assignments
+│   └── scoring-rubric.yaml         # Evaluation criteria
+│
+├── scripts/
+│   ├── model-tier-validator.cjs    # Validation tool
+│   └── model-usage-logger.cjs      # Usage tracking
+```
+
+**Estrutura por task:** Cada task tem sua própria pasta em `test-cases/` contendo:
+- `test-case.yaml` - Definição do teste
+- `{model}-output.yaml` - Outputs de cada modelo testado
+
+---
+
+## 5. Fluxo de Validação
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                                                                 │
+│  1. CRIAR SKILL (model: haiku)                                  │
+│                    ↓                                            │
+│  2. RODAR TEST CASE em [opus, sonnet, haiku]                    │
+│                    ↓                                            │
+│  3. SCORING (5 dimensões × weights)                             │
+│                    ↓                                            │
+│  4. COMPARAR com baseline (opus = 100%)                         │
+│                    ↓                                            │
+│  ┌────────────────────────────────────────────────────────┐     │
+│  │ Haiku >= 90%? ────────────────────────→ ✅ SHIP HAIKU  │     │
+│  │      │                                                 │     │
+│  │      ▼ NO                                              │     │
+│  │ COMPENSAR (examples/checklist/template/script)         │     │
+│  │      │                                                 │     │
+│  │      ▼                                                 │     │
+│  │ RE-TEST                                                │     │
+│  │      │                                                 │     │
+│  │      ▼                                                 │     │
+│  │ Haiku >= 90%? ────────────────────────→ ✅ SHIP HAIKU  │     │
+│  │      │                                                 │     │
+│  │      ▼ NO (após 4 tentativas)                          │     │
+│  │ Sonnet >= 95%? ───────────────────────→ ⚠️ SHIP SONNET │     │
+│  │      │                                                 │     │
+│  │      ▼ NO                                              │     │
+│  │ KEEP OPUS ────────────────────────────→ 🔴 SHIP OPUS   │     │
+│  └────────────────────────────────────────────────────────┘     │
+│                    ↓                                            │
+│  5. DOCUMENTAR resultado + padrão aprendido                     │
+│                    ↓                                            │
+│  6. ATUALIZAR config/model-routing.yaml                         │
+│                    ↓                                            │
+│  7. PRÓXIMA TASK                                                │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 6. Padrões Aprendidos
+
+Documentar padrões conforme testamos:
+
+### Haiku Funciona Bem Para
+
+- Scoring com fórmula definida
+- Checklist validation (PASS/FAIL)
+- Format conversion (estrutura clara)
+- Registry updates (determinístico)
+- Deterministic calculations
+- Template-based generation
+
+### Haiku Precisa de Compensação Para
+
+| Padrão | Compensação |
+|--------|-------------|
+| Multi-step reasoning | Chain-of-thought no prompt |
+| Complex output | Template strict com schema |
+| Quality judgment | Rubric inline detalhada |
+| Missing sections | Checklist de seções obrigatórias |
+
+### Haiku Não Elegível Para
+
+- Creative synthesis
+- Nuanced analysis requiring context
+- Multi-source integration
+- Novel framework creation
+- Complex trade-off decisions
+
+---
+
+## 7. Comandos
+
+### Rodar Validação
+
+```bash
+# Listar test cases disponíveis
+node squads/squad-creator-pro/scripts/model-tier-validator.cjs list
+
+# Validar uma task específica
+node squads/squad-creator-pro/scripts/model-tier-validator.cjs validate pv-axioma-assessment
+
+# Gerar relatório consolidado
+node squads/squad-creator-pro/scripts/model-tier-validator.cjs report
+
+# Atualizar routing config após validação
+node squads/squad-creator-pro/scripts/model-tier-validator.cjs update-routing pv-axioma-assessment haiku "Scoring determinístico"
+```
+
+### Logar Resultado Manual
+
+```bash
+node scripts/model-usage-logger.cjs log {task} {model} {tokens_in} {tokens_out} {latency}
+node scripts/model-usage-logger.cjs report
+```
+
+---
+
+## 8. Métricas de Sucesso
+
+| Métrica | Target | Atual | Medição |
+|---------|--------|-------|---------|
+| Tasks em Haiku | >= 15/41 (37%) | 15/41 | Após validação |
+| Tasks em Sonnet | <= 14/41 (34%) | 14/41 | Após validação |
+| Tasks em Opus | <= 12/41 (29%) | 12/41 | Após validação |
+| Economia total | >= 50% | ~60% | Comparado com tudo em Opus |
+| Qualidade mínima | >= 90% | TBD | Score vs Opus baseline |
+
+> **Nota:** Com Opus 4.5/4.6 a $5/$25, a economia de usar Haiku ($1/$5) é ~80%, não ~93%.
+
+---
+
+## 9. Changelog
+
+| Data | Mudança |
+|------|---------|
+| 2026-02-11 | Framework criado |
+| 2026-02-11 | pv-axioma-assessment validado (Haiku OK) |
+
+---
+
+*Model Tier Qualification Framework v1.0*
+*Squad Creator Token Economy*

package/pro/squads/squad-creator-pro/docs/PATTERN-LIBRARY.md

@@ -0,0 +1,333 @@
+# Pattern Library - Squad-Creator
+
+**Version:** 1.0
+**Last Updated:** 2026-02-10
+**Source:** HybridOps Migration
+
+---
+
+## Overview
+
+This document consolidates all patterns, heuristics, veto conditions, quality gates, and axiomas used by the Squad-Creator system.
+
+**Config Files:**
+- `config/heuristics.yaml` - 3 decision heuristics (SC_HE_*)
+- `config/veto-conditions.yaml` - 10 veto conditions (SC_VC_*)
+- `config/axioma-validator.yaml` - 10 axioma dimensions (D1-D10)
+- `config/quality-gates.yaml` - 10 quality gates (QG-SC-*)
+- `config/task-anatomy.yaml` - 8 mandatory task fields
+
+**Validation:**
+- `scripts/coherence-validator.py` - Validates cross-references between configs
+
+---
+
+## Heuristics (SC_HE_*)
+
+Decision heuristics derived from Pedro Valério's mind artifacts.
+
+| ID | Name | Source | Phase | Mode |
+|----|------|--------|-------|------|
+| SC_HE_001 | Vision Alignment | PV_BS_001 | architecture | `*eng-*` |
+| SC_HE_002 | Agent Coherence | PV_PA_001 | agent_creation | `*arq-*` |
+| SC_HE_003 | Workflow Automation | PV_PM_001 | workflow_design | `*auto-*` |
+
+### SC_HE_001: Vision Alignment
+
+**When to use:** Before starting any major squad creation
+**Decision Tree:**
+```
+Is vision defined and clear?
+├── YES (score >= 7) → PROCEED
+├── PARTIAL (score 5-6) → Document gaps, proceed with warning
+└── NO (score < 5) → VETO (SC_VC_002)
+```
+
+### SC_HE_002: Agent Coherence
+
+**When to use:** During agent creation or validation
+**Decision Tree:**
+```
+Does agent structure align with DNA?
+├── Voice + Thinking DNA match → PASS
+├── Minor inconsistencies → WARN, suggest fixes
+└── Major misalignment → VETO (SC_VC_005)
+```
+
+### SC_HE_003: Workflow Automation
+
+**When to use:** During workflow design or audit
+**Decision Tree:**
+```
+Can this step be automated without loss?
+├── YES → Implement as Worker/Agent
+├── NEEDS JUDGMENT → Implement as Hybrid
+└── REQUIRES HUMAN → Keep as Human, document why
+```
+
+---
+
+## Veto Conditions (SC_VC_*)
+
+Blocking conditions that MUST be resolved before proceeding.
+
+| Code | Name | Trigger | Resolution |
+|------|------|---------|------------|
+| SC_VC_001 | Domain Viability | domain_score < 5 | Research more, change scope |
+| SC_VC_002 | Vision Clarity | vision_score < 7 | Define clearer objectives |
+| SC_VC_003 | Source Quality | sources < 5 per mind | Add more sources |
+| SC_VC_004 | DNA Completeness | voice OR thinking missing | Extract missing DNA |
+| SC_VC_005 | Agent Coherence | misalignment detected | Realign voice+thinking |
+| SC_VC_006 | Smoke Test | any smoke test fails | Fix and re-test |
+| SC_VC_007 | Guardrail Missing | no veto condition | Add veto conditions |
+| SC_VC_008 | Unidirectional Flow | flow allows backtrack | Redesign flow |
+| SC_VC_009 | Axioma Score | D1 < 7.0 | Improve truthfulness |
+| SC_VC_010 | Task Anatomy | missing required field | Add missing fields |
+
+### Veto Hierarchy
+
+```
+HARD VETO (immediate stop):
+  SC_VC_003 (Source Quality) - No sources = no clone
+  SC_VC_006 (Smoke Test) - Failed behavior = broken agent
+  SC_VC_009 (Axioma D1) - Truthfulness below threshold
+
+SOFT VETO (warn, allow override):
+  SC_VC_001 (Domain Viability) - May proceed with reduced scope
+  SC_VC_010 (Task Anatomy) - May proceed with documentation
+```
+
+---
+
+## Axioma Dimensions (D1-D10)
+
+Based on Pedro Valério's META_AXIOMAS artifact. Each dimension measures a quality aspect.
+
+| ID | Name | Weight | Threshold | VETO Power |
+|----|------|--------|-----------|------------|
+| D1 | Truthfulness | 1.0 | 7.0 | **YES** |
+| D2 | Coherence | 0.9 | 6.0 | No |
+| D3 | Strategic Alignment | 0.9 | 6.0 | No |
+| D4 | Operational Excellence | 0.8 | 6.0 | No |
+| D5 | Innovation Capacity | 0.7 | 5.0 | No |
+| D6 | Risk Management | 0.8 | 6.0 | No |
+| D7 | Resource Optimization | 0.8 | 6.0 | No |
+| D8 | Stakeholder Value | 0.7 | 6.0 | No |
+| D9 | Sustainability | 0.7 | 6.0 | No |
+| D10 | Adaptability | 0.6 | 5.0 | No |
+
+### D1: Truthfulness (VETO POWER)
+
+The only dimension with automatic veto. If truthfulness < 7.0, entire validation fails.
+
+**Validation Questions:**
+- Todas as citações têm [SOURCE:] verificável?
+- Os frameworks são documentados ou inventados?
+- As inferências estão marcadas como tal?
+- Existe evidência para cada claim?
+
+**Red Flags:**
+- Citações sem fonte
+- Frameworks 'inspirados em' sem documentação
+- Afirmações categóricas sem evidência
+- Inferências apresentadas como fatos
+
+---
+
+## Quality Gates (QG-SC-*)
+
+Validation checkpoints throughout the workflow.
+
+### Auto Gates (Runtime, <60s)
+
+| ID | Name | Trigger | Validation |
+|----|------|---------|------------|
+| QG-SC-1.1 | Structure Validation | On artifact creation | YAML syntax, required fields |
+| QG-SC-1.2 | Schema Compliance | On artifact creation | task-anatomy fields |
+| QG-SC-2.1 | Reference Integrity | On artifact save | All refs exist |
+| QG-SC-3.1 | Veto Scan | On checkpoint | No active vetos |
+| QG-SC-4.1 | Coherence Check | On validation request | coherence-validator.py |
+| QG-SC-4.2 | Axioma Scoring | On validation request | D1-D10 scoring |
+
+### Hybrid Gates (AI + Human, <5min)
+
+| ID | Name | Trigger | Validation |
+|----|------|---------|------------|
+| QG-SC-5.1 | DNA Review | On DNA extraction complete | AI prepares, human validates |
+| QG-SC-5.2 | Smoke Test Review | On smoke test execution | AI runs, human verifies |
+| QG-SC-6.1 | Squad Review | On squad completion | Final human approval |
+| QG-SC-6.2 | Handoff Review | Before handoff | Validate deliverables |
+
+---
+
+## Task Anatomy (8 Fields)
+
+Every task MUST have these 8 fields:
+
+| # | Field | Type | Description |
+|---|-------|------|-------------|
+| 1 | task_name | string | Verb + Object (e.g., "Create Agent") |
+| 2 | status | enum | draft/ready/in_progress/done/blocked |
+| 3 | responsible_executor | string | Who executes (@agent or role) |
+| 4 | execution_type | enum | Human/Agent/Hybrid/Worker |
+| 5 | estimated_time | string | Duration with unit (e.g., "30 min") |
+| 6 | input | array | Required inputs to start |
+| 7 | output | array | Expected deliverables |
+| 8 | action_items | array | Concrete steps to execute |
+
+**Validation:** SC_VC_010 triggers if any field missing.
+
+---
+
+## Executor Types
+
+Decision tree for choosing executor (from `data/executor-decision-tree.md`):
+
+```
+Is output 100% predictable?
+├── YES → Can be written as pure function?
+│         ├── YES → Library/API exists?
+│         │         ├── YES → WORKER
+│         │         └── NO → Worth coding (used 3+ times)?
+│         │                  ├── YES → WORKER
+│         │                  └── NO → AGENT
+│         └── NO → (continue to NLP check)
+├── NO → Requires NLP interpretation?
+│         ├── YES → Error impact significant?
+│         │         ├── HIGH → HYBRID
+│         │         └── LOW → AGENT
+│         └── NO → Requires strategic judgment?
+│                  ├── YES → AI can assist?
+│                  │         ├── YES → HYBRID
+│                  │         └── NO → HUMAN
+│                  └── NO → (re-evaluate)
+```
+
+| Type | Cost | Speed | Consistency | When |
+|------|------|-------|-------------|------|
+| Worker | $ | ms-s | 100% | Deterministic transforms |
+| Agent | $$$$ | s-min | 85-95% | NLP, analysis, generation |
+| Hybrid | $$ | min-h | 95%+ | Critical output, human review |
+| Human | $$$ | h-days | Variable | Strategic, interpersonal |
+
+---
+
+## Cross-Reference Map
+
+How configs reference each other:
+
+```
+heuristics.yaml
+├── SC_HE_001 → veto_on_fail: SC_VC_002
+├── SC_HE_002 → veto_on_fail: SC_VC_005
+└── SC_HE_003 → veto_on_fail: SC_VC_007
+
+axioma-validator.yaml
+├── D1_truthfulness → maps_to_veto: SC_VC_003
+└── D1_truthfulness → maps_to_veto: SC_VC_009
+
+quality-gates.yaml
+├── QG-SC-3.1 → checks: veto-conditions.yaml
+├── QG-SC-4.1 → runs: coherence-validator.py
+└── QG-SC-4.2 → uses: axioma-validator.yaml
+```
+
+**Validation Command:**
+```bash
+python scripts/coherence-validator.py
+```
+
+---
+
+## Usage in Workflows
+
+### In wf-create-squad.yaml
+
+```yaml
+# Phase 1: Research
+heuristic:
+  id: SC_RES_001  # Legacy, maps to SC_HE_001
+  blocking: true
+  veto_conditions:
+    - SC_VC_002  # Vision Clarity
+    - SC_VC_003  # Source Quality
+
+# Phase 5: Validation
+quality_gates:
+  - QG-SC-4.1  # Coherence Check
+  - QG-SC-4.2  # Axioma Scoring
+  - QG-SC-6.1  # Final Human Approval
+```
+
+### In Agent Definitions
+
+```yaml
+# In squad-chief.md or any agent
+quality_standards:
+  agents:
+    required:
+      - "voice_dna com signature phrases rastreáveis a [SOURCE:]"  # D1
+      - "thinking_dna com heuristics que têm QUANDO usar"  # SC_HE_*
+      - "3 smoke tests que PASSAM"  # SC_VC_006
+      - "handoffs definidos"  # SC_HE_002
+```
+
+---
+
+## Validation Report Example
+
+```
+======================================================================
+COHERENCE VALIDATOR - Squad-Creator Configs
+======================================================================
+Config dir: /squads/squad-creator-pro/config
+Strict mode: False
+
+CONFIGS LOADED:
+  ✓ heuristics.yaml
+  ✓ veto-conditions.yaml
+  ✓ axioma-validator.yaml
+  ✓ quality-gates.yaml
+  ✓ task-anatomy.yaml
+
+VALIDATIONS:
+  ✓ heuristic_veto_coverage
+      Heuristics with veto: 3/3
+  ✓ axioma_threshold_coverage
+      Dimensions defined: 10/10
+  ✓ gate_reference_validity
+      Invalid references found: 0
+  ✓ veto_code_uniqueness
+      Unique veto codes: 10, Duplicates: 0
+  ✓ executor_consistency
+      Valid executor types: ['Worker', 'Agent', 'Hybrid', 'Human']
+  ✓ cross_reference_integrity
+      Total unique IDs across configs: 53
+
+======================================================================
+STATUS: ✓ PASS
+  Rules: 6 | Passed: 6 | Failed: 0 | Warnings: 0 | Skipped: 0
+======================================================================
+```
+
+---
+
+## Migration from HybridOps
+
+Patterns migrated from HybridOps to Squad-Creator:
+
+| HybridOps Pattern | Squad-Creator Equivalent |
+|-------------------|-------------------------|
+| HO-VC-* | SC_VC_* (10 veto conditions) |
+| HO-HE-* | SC_HE_* (3 heuristics) |
+| HO-QG-* | QG-SC-* (10 quality gates) |
+| executor-matrix-framework.md | task-anatomy.yaml + executor-decision-tree.md |
+| META_AXIOMAS.md | axioma-validator.yaml (D1-D10) |
+
+**Full migration roadmap:** `docs/MIGRATION-ROADMAP-HYBRIDOPS.md`
+
+---
+
+*Pattern Library v1.0*
+*Last Updated: 2026-02-10*
+*Executor: Pedro Valério (Process Absolutist)*