up-cc 0.14.0 → 0.16.0

package/{workflows → up/workflows}/builder.md

@@ -56,23 +56,83 @@ Neste modo, TODOS os agentes devem:
 </core_principle>
 
 <model_handling>
-## Modelos (v0.6.0+)
+## Modelos (v0.9.0+)
 
-**O runtime decide o modelo.** O UP nao especifica `model=opus/sonnet/haiku` em nenhum spawn de agente.
+**Model routing configuravel via `config.json`.** Dois eixos:
 
-- Em Claude Code, os agentes usam o modelo default (Opus 4.6) ou o que o usuario configurou via `/model`.
-- Em OpenCode, cada agente usa o modelo configurado no `opencode.json`.
-- Em Gemini CLI, usa o modelo do runtime.
+1. **Por papel** (planning/execution/governance/review) — preset estatico
+2. **Por complexidade da task** (simple/standard/complex) — classifier dinamico (Wave 5+)
 
-Antes v0.5.x tinha routing por papel (planning=opus, execution=sonnet). Isso foi removido em v0.6.0 para simplicidade e portabilidade entre runtimes.
+### Como funciona
 
-**Planos sao sempre gerados em nivel detalhado (Sonnet-ready)** independente do modelo que vai executar. Assim funcionam em qualquer runtime.
+**Default (per-role, comportamento v0.9):**
+```bash
+MODEL=$(node "$HOME/.claude/up/bin/up-tools.cjs" config resolve-model {agent-name} --raw)
+```
+
+**Wave 5+ (complexity routing):** quando spawn e contextual a um plano, use:
+```bash
+MODEL=$(node "$HOME/.claude/up/bin/up-tools.cjs" resolve-model-for-plan "$PLAN" {agent-name} --raw)
+```
+Isso le `config.modelos.routing` e decide:
+- `per-role` (default) → usa preset estatico
+- `complexity` → usa classifier do plano (haiku/sonnet/opus por score)
+- `complexity-with-cap` → complexity, mas capa por preset (orcamento)
+
+Se retorna `default`: nao passar `model=` (runtime decide).
+Se retorna `opus|sonnet|haiku`: passar no spawn.
+
+### Presets disponiveis (per-role)
+
+| Preset | Planning | Execution | Governance | Review |
+|--------|----------|-----------|------------|--------|
+| `runtime` | default | default | default | default |
+| `opus-completo` | opus | opus | opus | opus |
+| `hibrido` | opus | sonnet | opus | opus |
+| `sonnet-completo` | sonnet | sonnet | sonnet | sonnet |
+| `economico` | sonnet | sonnet | haiku | sonnet |
+| `custom` | manual | manual | manual | manual |
+
+### Routing modes (complexity)
+
+| Mode | Comportamento |
+|------|---------------|
+| `per-role` (default) | Preset estatico, nao olha o plano |
+| `complexity` | Classifier do plano decide (score 0-2 haiku, 3-5 sonnet, 6+ opus) |
+| `complexity-with-cap` | Classifier sugere, mas preset capa (ex: per-role=sonnet, complexity=opus → usa sonnet) |
+
+### Papeis dos agentes
+
+- **Planning:** planejador, arquiteto, product-analyst, system-designer, pesquisador-projeto, sintetizador, mapeador-codigo, requirements-validator
+- **Execution:** executor, frontend/backend/database-specialist, devops-agent, technical-writer
+- **Governance:** todos supervisores, chiefs, CEO, delivery-auditor, planning-auditor
+- **Review:** verificador, blind-validator, code-reviewer, security-reviewer, visual-critic, exhaustive-tester, api-tester, qa-agent, auditores, sintetizador-melhorias
+
+### Default
+
+Sem `modelos` no config.json = `runtime` (nenhum override). Identico ao v0.6.0.
+
+**Planos sao sempre gerados em nivel detalhado (Sonnet-ready)** independente do modelo que vai executar.
+
+### Ao spawnar qualquer agente
+
+**Spawn sem plano (CEO, planejador, supervisores cross-fase):**
+```bash
+MODEL=$(node "$HOME/.claude/up/bin/up-tools.cjs" config resolve-model up-executor --raw)
+```
+
+**Spawn com plano (specialist, executor, verificador por fase) — Wave 5+:**
+```bash
+MODEL=$(node "$HOME/.claude/up/bin/up-tools.cjs" resolve-model-for-plan "$PLAN" up-executor --raw)
+```
 
-**Ao spawnar qualquer agente:**
 ```python
-Task(subagent_type="up-executor", prompt="...")
+# Se MODEL != "default", passar model=
+Task(subagent_type="up-executor", model="{MODEL if MODEL != 'default' else omit}", prompt="...")
 ```
-Sem parametro `model`.
+
+**IMPORTANTE:** Se model=default (ou nao configurado), NAO passar parametro model no spawn.
+Isso mantem compatibilidade total com v0.6.0 e com runtimes que nao suportam model routing.
 </model_handling>
 
 <governance>
@@ -92,6 +152,28 @@ OPERATIONAL AGENTS (36) — fazem o trabalho
 
 **Referencia obrigatoria:** `@~/.claude/up/workflows/governance.md`
 
+**REGRA INVIOLAVEL — GOVERNANCA OBRIGATORIA COM GATES VERIFICAVEIS:**
+
+A governanca NAO PODE ser pulada, otimizada, resumida ou ignorada.
+Para IMPEDIR que o LLM otimize colapsando passos, cada etapa critica tem um **GATE** —
+um check de arquivo executado via Bash que BLOQUEIA o avanço se a etapa anterior nao produziu evidencia.
+
+**Mecanismo anti-colapso:**
+1. Cada supervisor DEVE escrever no `approvals.log` ANTES de retornar
+2. Cada GATE verifica que o `approvals.log` tem a entry esperada
+3. Se o gate falha → o builder NAO avanca → spawna o agente faltante
+4. O GATE E (final) verifica TODOS os 5 checks de uma vez
+
+**Pipeline obrigatorio por fase no Estagio 3:**
+```
+Planejador → Specialist → [GATE A] → EXECUTION-SUPERVISOR → [GATE B] → Code Reviewer → Verificador → [GATE C] → VERIFICATION-SUPERVISOR → [GATE D] → E2E + DCRV → CHIEF-ENGINEER → [GATE E] → Marcar completa
+```
+
+Cada GATE e um `bash` check que le `.plano/governance/approvals.log`.
+Se a entry esperada nao existe, o builder PARA e spawna o agente faltante.
+
+**NUNCA combinar dois agentes em um spawn. NUNCA pular um GATE.**
+
 **Regras gerais:**
 1. Todo output de agente operacional passa por supervisor
 2. Toda area tem chief que consolida
@@ -223,7 +305,6 @@ Spawnar CEO com contexto:
 ```python
 Agent(
   subagent_type="up-project-ceo",
-  model="opus",
   prompt=f"""
     Conduza intake para novo projeto UP.
     
@@ -664,7 +745,7 @@ Modo autonomo — NAO pergunte nada.
 - .plano/BRIEFING.md (Briefing e stack)
 - .plano/PRODUCT-ANALYSIS.md (Analise de produto — features, personas, modulos)
 - .plano/pesquisa/SUMMARY.md (Pesquisa, se existir)
-- $HOME/.claude/up/references/production-requirements.md (Requisitos universais)
+- $HOME/.claude/up/references/production-requirements-compressed.md (Requisitos universais)
 - $HOME/.claude/up/references/blueprints/ (Blueprints — ler os relevantes ao dominio)
 {BROWNFIELD EXTRA:}
 - .plano/codebase/STACK.md (Stack existente)
@@ -882,7 +963,15 @@ echo "=== GATE: Verificando artefatos do Estagio 2 ==="
 
 **Se todos OK:** Continuar para 3.0.
 
-### 3.0 Carregar Roadmap e Inicializar Lock
+### 3.0 Carregar Roadmap e Inicializar Lock + Governance
+
+**Inicializar diretorio de governanca (OBRIGATORIO):**
+```bash
+mkdir -p .plano/governance
+touch .plano/governance/approvals.log
+touch .plano/governance/technical-debt.log
+echo "# Governance initialized at $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> .plano/governance/approvals.log
+```
 
 ```bash
 ROADMAP=$(node "$HOME/.claude/up/bin/up-tools.cjs" roadmap analyze)
@@ -930,7 +1019,56 @@ sed -i "s/^phase: .*/phase: ${PHASE_NUMBER}/" .plano/LOCK.md
 sed -i "s/^updated: .*/updated: $(date -u +%Y-%m-%dT%H:%M:%SZ)/" .plano/LOCK.md
 ```
 
-### 3.1 Loop Principal
+### 3.1 Loop Principal — SEPARACAO RIGIDA DE AGENTES
+
+**REGRA ANTI-COLAPSO (ler com atencao):**
+
+O LLM tende a otimizar colapsando passos — dar ao mesmo agente tarefas de planejar + executar,
+ou pular supervisores por parecer "overhead". Isso e PROIBIDO.
+
+**Cada passo abaixo DEVE ser um Agent() ou Task() SEPARADO.**
+**NUNCA combinar dois passos em um unico spawn.**
+**NUNCA instruir um agente a fazer o trabalho de outro.**
+
+Exemplo do que NAO fazer:
+```
+# ERRADO — combina planejamento + execucao no mesmo agente
+Task(subagent_type="up-planejador", prompt="Planejar E executar a fase...")
+
+# ERRADO — pula supervisor
+Task(subagent_type="up-executor", prompt="Executar e verificar...")
+```
+
+Exemplo correto:
+```
+# CERTO — cada agente faz UMA coisa
+Task(subagent_type="up-planejador", prompt="Planejar fase...")
+# Depois:
+Task(subagent_type="up-executor", prompt="Executar plano...")
+# Depois:
+Agent(subagent_type="up-execution-supervisor", prompt="Revisar execucao...")
+```
+
+**Pipeline por fase — 9 passos sequenciais, NENHUM pode ser pulado:**
+
+```
+PASSO 1: up-planejador         → gera PLAN.md
+PASSO 2: up-{specialist}       → gera SUMMARY.md
+--- GATE A: verificar SUMMARY.md existe ---
+PASSO 3: up-execution-supervisor → gera EXEC-REVIEW em approvals.log
+--- GATE B: verificar approvals.log tem entry pra fase ---
+PASSO 4: up-code-reviewer      → gera CODE-REVIEW.md
+PASSO 5: up-verificador        → gera VERIFICATION.md
+--- GATE C: verificar VERIFICATION.md existe ---
+PASSO 6: up-verification-supervisor → gera entry em approvals.log
+--- GATE D: verificar approvals.log tem 2 entries pra fase ---
+PASSO 7: E2E + DCRV            → gera E2E-RESULTS.md
+PASSO 8: up-chief-engineer     → gera entry em approvals.log
+--- GATE E: verificar approvals.log tem 3 entries pra fase (exec-sup + verif-sup + chief) ---
+PASSO 9: Marcar completa
+```
+
+**GATES sao checks de arquivo executados via Bash. Se o gate falha, NAO avance.**
 
 Para cada fase no ROADMAP (da primeira a ultima):
 
@@ -1060,16 +1198,69 @@ Para cada plano, ler o frontmatter e detectar o dominio:
 
 Para cada wave, spawnar agentes especializados em paralelo (se parallelization=true):
 
+**Wave 2 (v0.11+) — pre-inline context:**
+ANTES do spawn, montar o bloco de contexto via `up-tools.cjs context`.
+Isso injeta PLAN, STATE, config, governance comprimida e engineering
+principles direto no prompt. O agente NAO precisa fazer Read desses
+arquivos — economiza ~30k tokens por spawn.
+
+```bash
+PLAN_FILE="{phase_dir}/{plan_file}"
+
+# Wave 5+ — decidir agent type ANTES (necessario pra manifest e routing)
+SPECIALIST_AGENT="up-executor"  # ou frontend/backend/database baseado em type do plano
+
+# Wave 6+ — manifest carrega so refs relevantes ao papel do agente
+CTX=$(node "$HOME/.claude/up/bin/up-tools.cjs" context \
+  --plan "${PLAN_FILE}" \
+  --state \
+  --config \
+  --manifest "${SPECIALIST_AGENT}" \
+  --raw)
+
+# Wave 5+ — complexity-aware model routing per plan
+MODEL=$(node "$HOME/.claude/up/bin/up-tools.cjs" resolve-model-for-plan \
+  "${PLAN_FILE}" "${SPECIALIST_AGENT}" --raw)
+CLASSIFY=$(node "$HOME/.claude/up/bin/up-tools.cjs" classify-task "${PLAN_FILE}" --raw)
+COMPLEXITY=$(echo "$CLASSIFY" | grep -oE '"complexity"[^,]+' | grep -oE '"(simple|standard|complex)"' | tr -d '"')
+SCORE=$(echo "$CLASSIFY" | grep -oE '"score"\s*:\s*[0-9]+' | grep -oE '[0-9]+')
+
+# Wave 6+ — Iron rule: validar plan ANTES de spawnar
+VALIDATE=$(node "$HOME/.claude/up/bin/up-tools.cjs" validate-plan "${PLAN_FILE}" --raw)
+VALIDATE_PASS=$(echo "$VALIDATE" | grep -oE '"pass"\s*:\s*(true|false)' | grep -oE '(true|false)')
+if [ "$VALIDATE_PASS" = "false" ]; then
+  echo "IRON RULE FALHOU: Plan ${PLAN_FILE} nao passou validate-plan."
+  echo "$VALIDATE" | grep -A 20 'suggestions'
+  echo "Voltando pro planejador pra refazer."
+  # Re-spawn planejador com VALIDATE como contexto. NAO seguir pro spawn de specialist.
+  exit 1
+fi
+
+# Log decisao (outcome marcado depois do retorno)
+node "$HOME/.claude/up/bin/up-tools.cjs" routing-log \
+  --plan "${PLAN_FILE}" \
+  --agent "${SPECIALIST_AGENT}" \
+  --model "${MODEL}" \
+  --complexity "${COMPLEXITY}" \
+  --score "${SCORE}" \
+  --outcome pending
+```
+
+Spawn:
+
 ```
 Task(
   subagent_type="{up-frontend-specialist | up-backend-specialist | up-database-specialist | up-executor}",
- ,
-  prompt="
+  prompt=f"""
     <objective>
     Executar plano {plan_number} da fase {phase_number}-{phase_name}.
     Commitar cada tarefa atomicamente. Criar SUMMARY.md. Atualizar STATE.md e ROADMAP.md.
     </objective>
 
+    <prompt_context>
+    {CTX}
+    </prompt_context>
+
     <execution_context>
     @~/.claude/up/workflows/executar-plano.md
     @~/.claude/up/references/checkpoints.md
@@ -1082,15 +1273,15 @@ Task(
     3. Checkpoints tipo checkpoint:decision → tomar a decisao mais razoavel
     4. Checkpoints tipo checkpoint:human-action → se possivel automatizar, faca; se nao, registrar como pendente
     5. Deviation Rule 4 (architectural changes) → decidir autonomamente e registrar no SUMMARY
-    6. CAPTURES: Se durante a execucao voce descobrir algo importante (padrao no codigo, problema potencial, oportunidade de melhoria, decisao arquitetural nao-obvia), registre em .plano/captures/ como arquivo markdown curto. Formato: `capture-{timestamp}-{slug}.md` com frontmatter: type (pattern|problem|opportunity|decision), severity (info|warning|critical), phase (numero). Corpo: 2-5 frases descrevendo o insight.
+    6. CAPTURES: Se durante a execucao voce descobrir algo importante (padrao no codigo, problema potencial, oportunidade de melhoria, decisao arquitetural nao-obvia), registre em .plano/captures/ como arquivo markdown curto. Formato: `capture-{{timestamp}}-{{slug}}.md` com frontmatter: type (pattern|problem|opportunity|decision), severity (info|warning|critical), phase (numero). Corpo: 2-5 frases descrevendo o insight.
     </builder_mode>
 
     <files_to_read>
-    Ler estes arquivos no inicio da execucao usando a ferramenta Read:
-    - {phase_dir}/{plan_file} (Plano)
-    - .plano/STATE.md (Estado)
-    - .plano/config.json (Config)
+    O contexto principal ja esta no <prompt_context> acima. Ler do disco APENAS:
     - ./CLAUDE.md (Instrucoes do projeto, se existir)
+    - Arquivos referenciados em <files> das tarefas (codigo a editar)
+
+    NAO refazer Read em PLAN, STATE.md, config.json — ja estao inline.
     </files_to_read>
 
     <success_criteria>
@@ -1100,7 +1291,7 @@ Task(
     - [ ] STATE.md atualizado
     - [ ] ROADMAP.md atualizado com progresso
     </success_criteria>
-  "
+  """
 )
 ```
 
@@ -1109,11 +1300,239 @@ Task(
 - Verificar que commits existem via `git log --oneline --grep`
 - Se falha: tentar re-executar o plano falho (max 1 retry)
 
+**Wave 5+ — Patch routing outcome apos retorno do spawn:**
+
+```bash
+# Apos spawn retornar (success path)
+if [ -f "${PHASE_DIR}/$(basename ${PLAN_FILE} .md | sed 's/-PLAN/-SUMMARY/')" ]; then
+  OUTCOME=success
+elif echo "$SPAWN_RETURN" | grep -q "^ABORTED:"; then
+  OUTCOME=abort
+else
+  OUTCOME=rework
+fi
+
+REWORK_CYCLES=${REWORK_COUNT:-0}
+
+node "$HOME/.claude/up/bin/up-tools.cjs" routing-log --update \
+  --plan "${PLAN_FILE}" \
+  --agent "${SPECIALIST_AGENT}" \
+  --model "${MODEL}" \
+  --complexity "${COMPLEXITY}" \
+  --score "${SCORE}" \
+  --outcome "${OUTCOME}" \
+  --rework-cycles "${REWORK_CYCLES}"
+```
+
+Sem este step, routing-history.log fica com entries `pending` orfas e
+`analyze-routing` nao tem dados pra sugerir ajustes.
+
+**Wave 3 (v0.12+) — handle ABORTED returns:**
+
+Se a mensagem de retorno do specialist comeca com `ABORTED:`:
+
+```bash
+if echo "$SPAWN_RETURN" | grep -q "^ABORTED:"; then
+  REASON=$(echo "$SPAWN_RETURN" | grep -oE "(timeout|stuck)" | head -1)
+  echo "WAVE INTERROMPIDA: ${REASON} na fase ${PHASE_NUMBER}"
+  
+  # Verificar se PARTIAL-SUMMARY existe
+  if [ -f "${PHASE_DIR}/PARTIAL-SUMMARY.md" ]; then
+    PARTIAL_TASKS=$(grep "last_completed_task:" "${PHASE_DIR}/PARTIAL-SUMMARY.md" | head -1)
+    
+    # Decisao: 1 retry com escopo reduzido OU escalar pro chief
+    ABORT_COUNT=$(grep -c "phase-${PHASE_NUMBER}.*ABORTED" .plano/governance/aborts.log 2>/dev/null)
+    
+    if [ "$ABORT_COUNT" -lt 2 ]; then
+      echo "Retry com escopo reduzido (1/2). Spawnando specialist novamente."
+      # Re-spawn com flag UP_RETRY_AFTER_ABORT=1 — agente pula tarefas opcionais
+      # (manter prompt principal, adicionar instrucao de retry)
+    else
+      echo "ABORTS limite (${ABORT_COUNT}). Escalando para chief-engineer."
+      # Spawn chief-engineer com PARTIAL-SUMMARY como contexto
+    fi
+  fi
+fi
+```
+
 ```
 Wave {N}: {count} planos executados
 ```
 
-#### 3.1.3 Reflect (Code Review)
+#### --- GATE A: Verificar que execucao produziu artefatos ---
+
+**EXECUTAR OBRIGATORIAMENTE antes de continuar:**
+
+```bash
+echo "=== GATE A: Verificando artefatos da execucao (Fase ${PHASE_NUMBER}) ==="
+SUMMARY_COUNT=$(ls ${PHASE_DIR}/*-SUMMARY.md 2>/dev/null | wc -l)
+if [ "$SUMMARY_COUNT" -eq 0 ]; then
+  echo "GATE A FALHOU: Nenhum SUMMARY.md encontrado em ${PHASE_DIR}"
+  echo "A execucao NAO produziu artefatos. Re-executar."
+  exit 1
+else
+  echo "GATE A OK: ${SUMMARY_COUNT} SUMMARY(s) encontrados"
+fi
+```
+
+**Se GATE A falhou:** Re-executar o specialist (max 1 retry). NAO avançar para supervisor.
+
+#### 3.1.2.1 GOVERNANCE OBRIGATORIA — Execution Supervisor Revisa (PASSO 3)
+
+**ESTE PASSO E OBRIGATORIO E NAO PODE SER PULADO.**
+**Referencia:** `@~/.claude/up/workflows/governance.md`
+
+Apos CADA wave de execucao completar, o execution-supervisor DEVE revisar o trabalho.
+
+```python
+Agent(
+  subagent_type="up-execution-supervisor",
+  prompt=f"""
+    Revisar execucao da Fase {phase_number}.
+    
+    <governance_compressed>
+    DECISOES: APPROVE | REQUEST_CHANGES | REQUEST_REPLAN | ESCALATE
+    REWORK: max 3 ciclos antes de forcar approval com debito
+    NUNCA APROVAR: trabalho nao verificado, evidencia ambigua, claim sem backing,
+                   stub/placeholder, falta de wiring
+    LOG OBRIGATORIO: .plano/governance/approvals.log
+    </governance_compressed>
+    
+    <engineering_principles_compressed>
+    1. Implementacao real (zero placeholder)
+    2. Correto, nao rapido
+    3. Conectado ponta a ponta
+    4. Consistencia (seguir patterns existentes)
+    5. Dados reais
+    6. Custo futuro
+    </engineering_principles_compressed>
+    
+    <files_to_read>
+    - {PLAN}
+    - {PHASE_DIR}/*-SUMMARY.md
+    - git diff (use Bash)
+    - .plano/fases/{phase_number}/REQUIREMENTS-SLICE.md (se existir)
+    
+    Sob demanda apenas:
+    - $HOME/.claude/up/references/engineering-principles-compressed.md (exemplos)
+    - $HOME/.claude/up/references/governance-rules-compressed.md (hierarquia)
+    - $HOME/.claude/up/references/rework-limits-compressed.md (fluxos)
+    - $HOME/.claude/up/references/production-requirements-compressed.md (IDs especificos)
+    </files_to_read>
+    
+    Decisao: APPROVE | REQUEST_CHANGES | REQUEST_REPLAN | ESCALATE
+    
+    REQUEST_REPLAN: Se descobrir que o plano e fundamentalmente errado/inviavel.
+                    Max 2 re-plans por projeto.
+    
+    **OUTPUT OBRIGATORIO (fazer ANTES de retornar):**
+    Escrever sua decisao no approvals.log:
+    ```bash
+    echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) | phase-{phase_number} | execution-supervisor | {DECISAO} | {motivo_resumido}" >> .plano/governance/approvals.log
+    ```
+    Sem este log, o GATE B vai bloquear o avanço do builder.
+  """
+)
+```
+
+#### 3.1.2.2 Processar Decisao do Execution Supervisor
+
+**Se APPROVE:** Verificar que approvals.log foi escrito (o supervisor deve ter feito). Prosseguir para 3.1.3.
+
+**Se REQUEST_CHANGES:** Re-spawn specialist com feedback (max 3 ciclos).
+
+```python
+# Re-spawn do specialist com review como contexto
+Agent(
+  subagent_type="{mesmo specialist da execucao}",
+  prompt=f"""
+    REWORK — Ciclo {{N}}/3
+    
+    Seu output anterior foi revisado pelo execution-supervisor e precisa de mudancas.
+    
+    Review: .plano/governance/{{review_file}}
+    
+    Mudancas requeridas:
+    {{lista_de_mudancas}}
+    
+    Refaca seu trabalho atendendo os criterios.
+  """
+)
+```
+
+Se apos 3 ciclos sem melhoria: FORCAR aprovacao com debito tecnico.
+
+```bash
+mkdir -p .plano/governance
+cat >> .plano/governance/technical-debt.log <<EOF
+$(date -u +%Y-%m-%dT%H:%M:%SZ) | phase-{phase_number} | execution-supervisor | FORCED_APPROVAL
+  Reason: Max rework cycles (3) reached without improvement
+  Remaining issues: [lista]
+EOF
+```
+
+**Se REQUEST_REPLAN:**
+
+```bash
+REPLAN_COUNT=$(cat .plano/governance/replans.log 2>/dev/null | wc -l)
+```
+
+Se `REPLAN_COUNT >= 2`: ESCALATE pro chief-engineer.
+
+Se `REPLAN_COUNT < 2`:
+1. Spawnar up-planejador LOCAL para refazer plano da fase
+2. Salvar como PLAN-v2.md (preservar v1 para historico)
+3. Spawnar up-planning-supervisor para revisar novo plano
+4. Se APPROVE: voltar para 3.1.2 (re-executar com novo plano)
+5. Se REJECT: ESCALATE pro chief-engineer
+
+```bash
+echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) | phase-${PHASE_NUMBER} | execution-supervisor | REPLAN | cycle $((REPLAN_COUNT+1))/2" >> .plano/governance/replans.log
+```
+
+**Se ESCALATE:** Spawnar chief-engineer para decidir.
+
+```python
+Agent(
+  subagent_type="up-chief-engineer",
+  prompt=f"""
+    Escalacao recebida do execution-supervisor.
+    Fase: {phase_number}
+    Problema: {descricao_do_problema}
+    
+    <files_to_read>
+    - {PHASE_DIR}/*-SUMMARY.md
+    - {PLAN}
+    - .plano/governance/approvals.log
+    </files_to_read>
+    
+    Decidir: APPROVE | REQUEST_CHANGES | ESCALATE_CEO
+  """
+)
+```
+
+Se chief-engineer retorna ESCALATE_CEO: spawnar CEO para alertar o dono.
+
+#### --- GATE B: Verificar que execution-supervisor logou decisao ---
+
+**EXECUTAR OBRIGATORIAMENTE antes de continuar:**
+
+```bash
+echo "=== GATE B: Verificando governance da execucao (Fase ${PHASE_NUMBER}) ==="
+EXEC_ENTRY=$(grep "phase-${PHASE_NUMBER}.*execution-supervisor" .plano/governance/approvals.log 2>/dev/null | tail -1)
+if [ -z "$EXEC_ENTRY" ]; then
+  echo "GATE B FALHOU: execution-supervisor NAO logou decisao para fase ${PHASE_NUMBER}"
+  echo "O execution-supervisor DEVE rodar antes de continuar."
+  echo "NAO pular este passo. Spawnar up-execution-supervisor agora."
+  exit 1
+else
+  echo "GATE B OK: $EXEC_ENTRY"
+fi
+```
+
+**Se GATE B falhou:** Spawnar execution-supervisor. NAO avançar para code review.
+
+#### 3.1.3 Reflect (Code Review) (PASSO 4)
 
 **O passo "Reflect" do ciclo RARV — revisa codigo ANTES da verificacao formal.**
 
@@ -1135,7 +1554,7 @@ Task(
 
     <files_to_read>
     - {phase_dir}/*-SUMMARY.md (O que foi implementado)
-    - $HOME/.claude/up/references/production-requirements.md (Checklist de producao)
+    - $HOME/.claude/up/references/production-requirements-compressed.md (Checklist de producao)
     - ./CLAUDE.md (Convencoes do projeto, se existir)
     </files_to_read>
 
@@ -1164,29 +1583,149 @@ Reflect: score {N}/10 | {criticas} criticas | {importantes} importantes | {menor
 
 #### 3.1.4 Verificar Fase
 
-Spawnar verificador autonomo:
+**Wave 4 (v0.13+) — Verification Ladder Determinística**
+
+ANTES de spawnar o verificador-LLM, rodar checks deterministicos via
+`up-tools.cjs verify-static`. Isso roda lint, typecheck, test e audit
+do projeto. Se TUDO passa, a verificacao LLM pode ser pulada (criar
+VERIFICATION.md sintetico marcando "passed via static checks").
+Se algo falha, o output capturado vira contexto pro verificador-LLM —
+ele foca no que quebrou em vez de re-rodar tudo.
+
+```bash
+# Step 1: Roda checks deterministicos
+STATIC=$(node "$HOME/.claude/up/bin/up-tools.cjs" verify-static --raw)
+STATIC_OVERALL=$(echo "$STATIC" | grep -oE 'overall.{1,20}' | head -1 | grep -oE '"(pass|fail|skip)"' | tr -d '"')
+
+if [ "$STATIC_OVERALL" = "pass" ]; then
+  # Step 2a: Tudo passou — criar VERIFICATION.md sintetico, pular LLM
+  cat > "${PHASE_DIR}/VERIFICATION.md" <<EOF
+---
+status: passed
+verifier: static-only
+phase: ${PHASE_NUMBER}
+checks_passed: lint+typecheck+test+audit
+timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+---
+
+# Verificacao da Fase ${PHASE_NUMBER}
 
+Aprovacao automatica via verificacao estatica deterministica.
+
+Detalhes em \`.plano/runtime/verify-static-*.log\`.
+EOF
+  echo "Verification: PASSED via static checks (LLM verifier skipped)"
+elif [ "$STATIC_OVERALL" = "skip" ]; then
+  # Sem scripts disponiveis — fallback pra LLM verifier
+  STATIC_CONTEXT="Static checks indisponiveis (sem lint/test scripts)."
+fi
 ```
+
+**Step 2b — Se STATIC falhou OU foi pulado:** spawnar verificador-LLM com output dos checks como contexto.
+
+```python
+# Carregar logs de checks que falharam
+STATIC_LOGS=""
+for log in .plano/runtime/verify-static-*.log; do
+  [ -f "$log" ] && STATIC_LOGS="${STATIC_LOGS}\n--- $(basename $log) ---\n$(cat $log)"
+done
+
 Task(
-  prompt="Verificar atingimento do objetivo da fase {phase_number}.
+  prompt=f"""Verificar atingimento do objetivo da fase {phase_number}.
 Diretorio da fase: {phase_dir}
-Objetivo da fase: {goal do ROADMAP.md}
+Objetivo da fase: {goal}
 IDs de requisitos da fase: {phase_req_ids}
 
+<static_check_results overall="{STATIC_OVERALL}">
+{STATIC_LOGS}
+</static_check_results>
+
 <builder_mode>
 Modo builder. NAO use AskUserQuestion.
+- FOCAR no que falhou nos static checks (nao reexecutar tudo)
 - Verificar must_haves contra codebase real
 - Cross-referenciar requisitos do frontmatter contra REQUIREMENTS.md
-- Rodar testes automatizados se existirem
+- Rodar testes APENAS se nao constam dos static checks
 - Se human_needed: considerar como PASSED (sera verificado no final)
 - Criar VERIFICATION.md
 </builder_mode>
-",
+""",
   subagent_type="up-verificador",
- 
 )
 ```
 
+#### --- GATE C: Verificar que verificacao produziu artefatos ---
+
+**EXECUTAR OBRIGATORIAMENTE antes de continuar:**
+
+```bash
+echo "=== GATE C: Verificando artefatos da verificacao (Fase ${PHASE_NUMBER}) ==="
+VERIF_COUNT=$(ls ${PHASE_DIR}/*-VERIFICATION.md 2>/dev/null | wc -l)
+if [ "$VERIF_COUNT" -eq 0 ]; then
+  echo "GATE C FALHOU: Nenhum VERIFICATION.md encontrado em ${PHASE_DIR}"
+  echo "O verificador NAO rodou. Spawnar up-verificador agora."
+  exit 1
+else
+  echo "GATE C OK: ${VERIF_COUNT} VERIFICATION(s) encontrados"
+fi
+```
+
+**Se GATE C falhou:** Spawnar verificador. NAO avançar para verification-supervisor.
+
+#### 3.1.4.1 GOVERNANCE OBRIGATORIA — Verification Supervisor Revisa (PASSO 6)
+
+**ESTE PASSO E OBRIGATORIO E NAO PODE SER PULADO.**
+**Referencia:** `@~/.claude/up/workflows/governance.md`
+
+Apos o verificador retornar, o verification-supervisor DEVE revisar a verificacao.
+
+```python
+Agent(
+  subagent_type="up-verification-supervisor",
+  prompt=f"""
+    Revisar verificacao da Fase {phase_number}.
+    
+    <governance_compressed>
+    DECISOES: APPROVE | REQUEST_CHANGES | ESCALATE
+    REWORK: max 3 ciclos antes de forcar approval com debito
+    NUNCA APROVAR SE:
+    - Verificacao superficial ("parece ok")
+    - VERIFICATION.md claim sem evidencia no codigo
+    - must_haves nao testados de fato
+    - Testes rodaram mas com falhas ignoradas
+    LOG OBRIGATORIO: .plano/governance/approvals.log
+    </governance_compressed>
+    
+    <files_to_read>
+    - {PHASE_DIR}/*-VERIFICATION.md
+    - {PHASE_DIR}/*-SUMMARY.md
+    - {PLAN}
+    - .plano/REQUIREMENTS.md (requisitos da fase)
+    
+    Sob demanda apenas:
+    - $HOME/.claude/up/references/governance-rules-compressed.md
+    - $HOME/.claude/up/references/rework-limits-compressed.md
+    </files_to_read>
+    
+    Validar que a verificacao foi rigorosa e que os claims tem backing.
+    Decisao: APPROVE | REQUEST_CHANGES | ESCALATE
+    
+    **OUTPUT OBRIGATORIO (fazer ANTES de retornar):**
+    Escrever sua decisao no approvals.log:
+    ```bash
+    echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) | phase-{phase_number} | verification-supervisor | {DECISAO} | {motivo_resumido}" >> .plano/governance/approvals.log
+    ```
+    Sem este log, o GATE D vai bloquear o avanço do builder.
+  """
+)
+```
+
+**Se APPROVE:** Verificar que approvals.log foi escrito. Prosseguir.
+
+**Se REQUEST_CHANGES:** Re-spawn verificador com feedback (max 3 ciclos).
+
+**Se ESCALATE:** Spawnar chief-engineer.
+
 Ler status da verificacao:
 
 ```bash
@@ -1195,11 +1734,34 @@ grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' '
 
 | Status | Acao no Builder |
 |--------|----------------|
-| `passed` | Marcar fase completa, avancar |
+| `passed` | Prosseguir para E2E |
 | `gaps_found` | Tentar corrigir (planejar gaps + executar, max 1 ciclo) |
 | `human_needed` | Registrar para revisao final, avancar |
 
-#### 3.1.5 Teste E2E da Fase (Playwright)
+#### --- GATE D: Verificar que AMBOS supervisores logaram decisao ---
+
+**EXECUTAR OBRIGATORIAMENTE antes de continuar:**
+
+```bash
+echo "=== GATE D: Verificando governance completa (Fase ${PHASE_NUMBER}) ==="
+EXEC_OK=$(grep -c "phase-${PHASE_NUMBER}.*execution-supervisor" .plano/governance/approvals.log 2>/dev/null)
+VERIF_OK=$(grep -c "phase-${PHASE_NUMBER}.*verification-supervisor" .plano/governance/approvals.log 2>/dev/null)
+
+if [ "$EXEC_OK" -eq 0 ] || [ "$VERIF_OK" -eq 0 ]; then
+  echo "GATE D FALHOU:"
+  [ "$EXEC_OK" -eq 0 ] && echo "  - execution-supervisor NAO logou decisao"
+  [ "$VERIF_OK" -eq 0 ] && echo "  - verification-supervisor NAO logou decisao"
+  echo "AMBOS supervisores DEVEM ter logado antes de continuar para E2E."
+  echo "Voltar e spawnar o supervisor faltante."
+  exit 1
+else
+  echo "GATE D OK: execution-supervisor (${EXEC_OK} entries) + verification-supervisor (${VERIF_OK} entries)"
+fi
+```
+
+**Se GATE D falhou:** Identificar qual supervisor faltou e spawnar. NAO avançar para E2E.
+
+#### 3.1.5 Teste E2E da Fase (Playwright) (PASSO 7)
 
 **Executar APENAS se a fase tem UI/rotas** (pular para fases de infra, schema, config).
 
@@ -1305,7 +1867,118 @@ Se regressao encontrada:
 Smoke test regressao: {N} rotas anteriores | {OK} ok | {REGRESS} regressoes [{FIXED} corrigidas]
 ```
 
-#### 3.1.6 Marcar Fase Completa
+#### 3.1.6 GOVERNANCE OBRIGATORIA — Chief-Engineer Aprova Fase
+
+**ESTE PASSO E OBRIGATORIO E NAO PODE SER PULADO.**
+**Referencia:** `@~/.claude/up/workflows/governance.md`
+
+Antes de marcar a fase como completa, o chief-engineer DEVE aprovar o trabalho consolidado da fase inteira.
+
+```python
+Agent(
+  subagent_type="up-chief-engineer",
+  prompt=f"""
+    Revisar Fase {phase_number} consolidada.
+    
+    <governance_compressed>
+    DECISOES: APPROVE | REQUEST_CHANGES | ESCALATE_CEO
+    REWORK (chief → supervisor): max 2 ciclos, depois escala pro CEO
+    
+    VERIFICAR:
+    1. Coerencia entre plano, execucao e verificacao
+    2. Drift arquitetural (decisoes que divergem do SYSTEM-DESIGN.md)
+    3. Debito tecnico acumulado (forced approvals)
+    4. Qualidade geral da fase (code review score + verificacao)
+    5. Requisitos da fase atendidos vs REQUIREMENTS.md
+    LOG OBRIGATORIO: .plano/governance/approvals.log
+    </governance_compressed>
+    
+    <files_to_read>
+    - {PHASE_DIR}/*-PLAN.md (planos)
+    - {PHASE_DIR}/*-SUMMARY.md (o que foi implementado)
+    - {PHASE_DIR}/*-VERIFICATION.md (resultado da verificacao)
+    - {PHASE_DIR}/CODE-REVIEW.md (se existir)
+    - .plano/governance/approvals.log (decisoes de supervisores)
+    - .plano/governance/technical-debt.log (se existir)
+    - .plano/SYSTEM-DESIGN.md (arquitetura original)
+    - .plano/REQUIREMENTS.md (requisitos)
+    
+    Sob demanda apenas:
+    - $HOME/.claude/up/references/governance-rules-compressed.md
+    - $HOME/.claude/up/references/rework-limits-compressed.md
+    </files_to_read>
+    
+    Consolidar tudo e decidir: APPROVE | REQUEST_CHANGES | ESCALATE_CEO
+    
+    **OUTPUT OBRIGATORIO (fazer ANTES de retornar):**
+    Escrever sua decisao no approvals.log:
+    ```bash
+    echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) | phase-{phase_number} | chief-engineer | {DECISAO} | {motivo_resumido}" >> .plano/governance/approvals.log
+    ```
+    Sem este log, o GATE E vai bloquear o avanço do builder.
+  """
+)
+```
+
+**Se APPROVE:** Verificar que approvals.log foi escrito. Prosseguir para GATE E.
+
+**Se REQUEST_CHANGES:**
+- Chief identifica area problematica e supervisor responsavel
+- Re-spawn supervisor correspondente com feedback do chief (max 2 ciclos chief ← supervisor)
+- Supervisor coordena rework com operacional
+- Chief re-revisa e loga novamente em approvals.log
+
+**Se ESCALATE_CEO:**
+- Spawnar CEO para alertar dono
+- CEO usa severidade: CRITICO (sempre interrompe) ou IMPORTANTE (registra)
+
+#### --- GATE E: Verificar TODA governanca antes de marcar completa ---
+
+**EXECUTAR OBRIGATORIAMENTE — este e o gate FINAL da fase:**
+
+```bash
+echo "=== GATE E: Verificacao FINAL de governanca (Fase ${PHASE_NUMBER}) ==="
+echo ""
+
+# Verificar 3 entries obrigatorias no approvals.log
+EXEC_OK=$(grep -c "phase-${PHASE_NUMBER}.*execution-supervisor" .plano/governance/approvals.log 2>/dev/null)
+VERIF_OK=$(grep -c "phase-${PHASE_NUMBER}.*verification-supervisor" .plano/governance/approvals.log 2>/dev/null)
+CHIEF_OK=$(grep -c "phase-${PHASE_NUMBER}.*chief-engineer" .plano/governance/approvals.log 2>/dev/null)
+
+# Verificar artefatos obrigatorios
+SUMMARY_OK=$(ls ${PHASE_DIR}/*-SUMMARY.md 2>/dev/null | wc -l)
+VERIF_FILE_OK=$(ls ${PHASE_DIR}/*-VERIFICATION.md 2>/dev/null | wc -l)
+
+PASS=true
+
+[ "$SUMMARY_OK" -eq 0 ] && echo "FALHA: Sem SUMMARY.md" && PASS=false
+[ "$VERIF_FILE_OK" -eq 0 ] && echo "FALHA: Sem VERIFICATION.md" && PASS=false
+[ "$EXEC_OK" -eq 0 ] && echo "FALHA: execution-supervisor NAO rodou" && PASS=false
+[ "$VERIF_OK" -eq 0 ] && echo "FALHA: verification-supervisor NAO rodou" && PASS=false
+[ "$CHIEF_OK" -eq 0 ] && echo "FALHA: chief-engineer NAO rodou" && PASS=false
+
+if [ "$PASS" = false ]; then
+  echo ""
+  echo "GATE E FALHOU: Fase ${PHASE_NUMBER} NAO pode ser marcada como completa."
+  echo "Voltar e executar os passos faltantes."
+  echo ""
+  echo "Checklist obrigatorio:"
+  echo "  [$([ $SUMMARY_OK -gt 0 ] && echo 'x' || echo ' ')] SUMMARY.md existe"
+  echo "  [$([ $EXEC_OK -gt 0 ] && echo 'x' || echo ' ')] execution-supervisor logou"
+  echo "  [$([ $VERIF_FILE_OK -gt 0 ] && echo 'x' || echo ' ')] VERIFICATION.md existe"
+  echo "  [$([ $VERIF_OK -gt 0 ] && echo 'x' || echo ' ')] verification-supervisor logou"
+  echo "  [$([ $CHIEF_OK -gt 0 ] && echo 'x' || echo ' ')] chief-engineer logou"
+  exit 1
+else
+  echo "GATE E OK: Todos 5 checks passaram. Fase pode ser marcada como completa."
+fi
+```
+
+**Se GATE E falhou:** PARAR. Ler o checklist e executar os passos faltantes. NAO marcar fase como completa sem todos os 5 checks.
+
+#### 3.1.6.1 Marcar Fase Completa (PASSO 9)
+
+**So atingir este passo apos GATE E passar (todos 5 checks OK).**
 
 ```bash
 COMPLETION=$(node "$HOME/.claude/up/bin/up-tools.cjs" phase complete "${PHASE_NUMBER}")
@@ -1993,7 +2666,6 @@ Antes do Delivery, o `up-delivery-auditor` valida que o processo inteiro foi com
 ```python
 Agent(
   subagent_type="up-delivery-auditor",
-  model="opus",
   prompt="""
     Auditar processo de entrega do projeto.
     
@@ -2227,7 +2899,6 @@ Delegar apresentacao final ao CEO:
 ```python
 Agent(
   subagent_type="up-project-ceo",
-  model="opus",
   prompt="""
     Apresentar resultado final do projeto ao dono.
     
@@ -2429,6 +3100,7 @@ Mesmo loop do full (3.1.1 → 3.1.5), mas:
 - **Sem reassessment** (poucas fases)
 - **Sem captures** (sessao curta)
 - **COM E2E Playwright** (se tem UI)
+- **Governanca LIGHT:** execution-supervisor roda (max 1 ciclo rework). Chief-engineer NAO roda. Verification-supervisor NAO roda.
 
 Para cada fase no ROADMAP:
 
@@ -2470,6 +3142,58 @@ Retornar: ## PLANNING COMPLETE
 
 Mesmo processo do full — spawnar up-executor por wave.
 
+**GATE LIGHT A — Verificar SUMMARY existe:**
+```bash
+SUMMARY_COUNT=$(ls ${PHASE_DIR}/*-SUMMARY.md 2>/dev/null | wc -l)
+[ "$SUMMARY_COUNT" -eq 0 ] && echo "GATE FALHOU: Sem SUMMARY" && exit 1
+```
+
+#### L3.2.1 GOVERNANCE LIGHT — Execution Supervisor
+
+**OBRIGATORIO mesmo no modo light.** Roda com max 1 ciclo de rework (vs 3 no full).
+**Este passo NAO pode ser colapsado com a execucao. DEVE ser um Agent() SEPARADO.**
+
+```bash
+mkdir -p .plano/governance
+```
+
+```python
+Agent(
+  subagent_type="up-execution-supervisor",
+  prompt=f"""
+    Revisar execucao da Fase {phase_number} (modo light — 1 ciclo max).
+    
+    <governance_compressed>
+    DECISOES: APPROVE | REQUEST_CHANGES
+    REWORK: max 1 ciclo, depois forca approval com debito
+    NUNCA APROVAR: stub/placeholder, falta de wiring, claim sem backing
+    </governance_compressed>
+    
+    <files_to_read>
+    - {PHASE_DIR}/*-PLAN.md
+    - {PHASE_DIR}/*-SUMMARY.md
+    - git diff (use Bash)
+    </files_to_read>
+    
+    Decisao: APPROVE | REQUEST_CHANGES
+    
+    **OUTPUT OBRIGATORIO (fazer ANTES de retornar):**
+    ```bash
+    echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) | phase-{phase_number} | execution-supervisor | {DECISAO} | {motivo}" >> .plano/governance/approvals.log
+    ```
+  """
+)
+```
+
+**GATE LIGHT B — Verificar supervisor logou:**
+```bash
+EXEC_OK=$(grep -c "phase-${PHASE_NUMBER}.*execution-supervisor" .plano/governance/approvals.log 2>/dev/null)
+[ "$EXEC_OK" -eq 0 ] && echo "GATE FALHOU: execution-supervisor NAO rodou. Spawnar agora." && exit 1
+```
+
+**Se APPROVE:** Prosseguir.
+**Se REQUEST_CHANGES:** Re-spawn specialist (1 ciclo). Se ainda falha: forced approval com debito.
+
 #### L3.3 Verificar Fase
 
 Spawnar up-verificador (mesmo do full — verificacao real, nao shortcut):
@@ -2581,9 +3305,11 @@ Quer mais? /up:modo-builder "proxima feature"
 **Light mode success criteria:**
 - [ ] .plano/ criado com PROJECT.md, ROADMAP.md, REQUIREMENTS.md
 - [ ] Todas fases executadas com commits atomicos
+- [ ] Execution-supervisor revisou CADA fase (GOVERNANCE OBRIGATORIA — 1 ciclo max)
 - [ ] Verificador rodou em cada fase (NAO quick check)
 - [ ] E2E Playwright rodou em fases com UI
 - [ ] DCRV light (1 ciclo) rodou em cada fase com UI/API
+- [ ] Governance logs em .plano/governance/approvals.log
 - [ ] Resumo final exibido com metricas
 
 </light_process>
@@ -2647,8 +3373,12 @@ Com 1M de contexto, a maioria dos projetos cabe sem /clear. Mas monitore:
 - [ ] Estagio 2: Requisitos completos (50-100 requisitos, 5 camadas)
 - [ ] Estagio 3: Todas as fases planejadas
 - [ ] Estagio 3: Todas as fases executadas (com specialist routing)
+- [ ] Estagio 3: Execution-supervisor revisou CADA fase (GOVERNANCE OBRIGATORIA)
 - [ ] Estagio 3: Reflect (code review) apos cada fase
 - [ ] Estagio 3: Todas as fases verificadas
+- [ ] Estagio 3: Verification-supervisor revisou CADA verificacao (GOVERNANCE OBRIGATORIA)
+- [ ] Estagio 3: Chief-engineer aprovou CADA fase consolidada (GOVERNANCE OBRIGATORIA)
+- [ ] Estagio 3: Governance logs em .plano/governance/approvals.log
 - [ ] Estagio 3: Fases com UI testadas via Playwright (E2E-RESULTS.md)
 - [ ] Estagio 3: Bugs E2E corrigidos (quando possivel)
 - [ ] Estagio 3: DCRV por fase executado (Visual Critic + Exhaustive Tester + API Tester)
@@ -2684,5 +3414,6 @@ Com 1M de contexto, a maioria dos projetos cabe sem /clear. Mas monitore:
 - [ ] Estagio 5: Resumo apresentado ao usuario
 
 **Minimo viavel:** Estagios 1-3 + Estagio 5. Estagios 4 (Polish) e E2E sao bonus.
+**INEGOCIAVEL:** Governanca no Estagio 3 (execution-supervisor + verification-supervisor + chief-engineer) NUNCA e bonus — e obrigatoria.
 
 </success_criteria>