up-cc 0.16.1 → 2.0.1

package/up/workflows/governance.md

@@ -1,259 +1,151 @@
 <purpose>
-Workflow de governanca do UP. Define o loop de aprovacao operacional → supervisor → chief → CEO.
+Workflow de governanca do UP — GATE-ONLY.
 
-Usado por todos os comandos UP que executam trabalho.
-</purpose>
-
-<process>
-
-## Loop de Governanca (Nivel Supervisor)
-
-### Passo 1: Operacional executa trabalho
-
-Qualquer agente operacional (planejador, executor, verificador, detector, auditor, etc.) completa sua tarefa e retorna output.
-
-### Passo 2: Supervisor correspondente revisa
-
-Determinar supervisor baseado no agente operacional:
-
-| Operacional | Supervisor |
-|------------|-----------|
-| planejador, roteirista | planning-supervisor |
-| executor, frontend/backend/database-specialist | execution-supervisor |
-| verificador, blind-validator | verification-supervisor |
-| visual-critic, exhaustive-tester, api-tester, qa-agent | quality-supervisor |
-| auditor-ux/perf/modernidade, security-reviewer, sintetizador-melhorias | audit-supervisor |
-| product-analyst, pesquisadores, mapeador-codigo | product-supervisor |
-| arquiteto, system-designer, requirements-validator | architecture-supervisor |
-| devops-agent, technical-writer | operations-supervisor |
-
-Spawnar o supervisor:
-
-```python
-Agent(
-  subagent_type="up-{supervisor_name}",
-  prompt="""
-    Revisar output de {operacional_name} para {context}.
-    
-    <governance_compressed>
-    DECISOES:
-    - APPROVE — criterios atendidos, sem issues criticas, evidencia clara
-    - REQUEST_CHANGES — 1+ criterio falhou, feedback especifico e acionavel
-    - ESCALATE — fora do escopo, decisao arquitetural ou conflito → chief
-    
-    REWORK LIMITS:
-    - Operacional ← Supervisor: max 3 ciclos, depois forca approval com debito tecnico
-    - Supervisor ← Chief: max 2 ciclos, depois escala pro CEO
-    
-    NUNCA APROVAR SE:
-    - Trabalho nao foi de fato verificado ("parece ok")
-    - Evidencia faltando ou ambigua
-    - SUMMARY claim sem backing no codigo
-    - Stub/placeholder em vez de implementacao real
-    - Falta de wiring (componente criado mas nao conectado)
-    
-    LOG OBRIGATORIO: .plano/governance/approvals.log
-    </governance_compressed>
-    
-    <files_to_read>
-    - [arquivos do output do operacional]
-    - [arquivos de contexto da fase — preferir slices em .plano/fases/{N}/]
-    </files_to_read>
-    
-    Versoes COMPLETAS (so se decisao precisa de detalhe):
-    - Read $HOME/.claude/up/references/governance-rules-compressed.md
-    - Read $HOME/.claude/up/references/rework-limits-compressed.md
-    - Read $HOME/.claude/up/references/engineering-principles-compressed.md
-    
-    Avaliar contra criterios objetivos.
-    Retornar: APPROVE | REQUEST_CHANGES | ESCALATE
-  """
-)
-```
+Reescrito no redesign v2: a hierarquia CEO -> chief -> supervisor foi removida (era teatro de
+modelo-burro). O que sobra e o mecanismo deterministico que importa: o GATE de fase baseado em
+`approvals.log`, com cap de rework de 1 round. Sem spawns de LLM aqui — so o contrato do gate.
 
-### Passo 3: Processar decisao do supervisor
-
-**Se APPROVE:**
-- Marcar item como completed no CHECKLIST
-- Logar em governance/approvals.log
-- Prosseguir pro proximo passo do pipeline
-
-**Se REQUEST_CHANGES:**
-- Incrementar rework_cycle do item
-- Se cycle < 3: re-spawnar operacional com review como contexto
-- Se cycle = 3: FORCA aprovacao com debito tecnico, registrar e prosseguir
-
-```python
-# Re-spawn do operacional
-Agent(
-  subagent_type="up-{operacional_name}",
-  model="{modelo correto}",
-  prompt="""
-    REWORK — Ciclo {N}/3
-    
-    Seu output anterior foi revisado e precisa de mudancas.
-    
-    Review: .plano/{path_do_review}
-    
-    Mudancas requeridas:
-    {lista_de_mudancas}
-    
-    Refaca seu trabalho atendendo os criterios.
-  """
-)
-```
+@-referenciado por build.md. O check de approvals.log e OURO: este arquivo preserva sua semantica
+intacta, apenas tira a camada de supervisores/chiefs/CEO que decidia em volta dele.
+</purpose>
 
-**Se ESCALATE:**
-- Supervisor nao consegue resolver, passa pro chief
-- Spawnar chief correspondente
-
-```python
-Agent(
-  subagent_type="up-chief-{area}",
-  model="opus",
-  prompt="""
-    Escalation recebida do {supervisor_name}.
-    
-    Problema: {problema}
-    Contexto: {files_to_read}
-    
-    Decidir: APPROVE | REQUEST_CHANGES | ESCALATE_CEO
-  """
-)
-```
+<core_principle>
+A seguranca do UP nunca foram os agentes de governanca; era (1) o `approvals.log` deterministico que
+um GATE em bash verifica, e (2) os detectores que rodam o app de verdade (DCRV). Este workflow define
+SO o (1). O veredito que alimenta o log vem de UM agente — `up-revisor` (two-stage) — nao de uma
+piramide de supervisores.
 
-## Loop de Governanca (Nivel Chief)
+Regras duras:
+- Cap de rework: **1 round**. Apos 1 ciclo sem melhoria, forca aprovacao com debito tecnico registrado.
+- O GATE nao avanca sem a entry esperada no `approvals.log`. Se faltar, spawnar o agente faltante.
+- Nenhum spawn de CEO/chief/supervisor. O revisor decide; o gate verifica.
+</core_principle>
 
-### Quando chief age
+<process>
 
-Chief age em 2 situacoes:
+## 1. Inicializar governance
 
-1. **Escalacao do supervisor** — problema que supervisor nao resolveu
-2. **Aprovacao consolidada** — revisao periodica do trabalho de uma area inteira
+```bash
+mkdir -p .plano/governance
+touch .plano/governance/approvals.log
+[ -s .plano/governance/approvals.log ] || \
+  echo "# Governance initialized at $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> .plano/governance/approvals.log
+```
 
-### Ciclos de Rework (Chief ← Supervisor)
+## 2. Contrato do approvals.log
 
-Max 2 ciclos:
+O `up-revisor` (e so ele) escreve no log ANTES de retornar. Formato ESTENDIDO (Fase 3 - TDD) de uma entry:
 
 ```
-Ciclo 1: Chief pede rework → Supervisor coordena com operacional
-Ciclo 2: Chief re-revisa → APPROVE ou ESCALATE_CEO
+<timestamp ISO> | <escopo> | up-revisor | <DECISAO> | <motivo> | evidence=<tipo>:<resultado>
 ```
 
-## Loop de Governanca (Nivel CEO)
+Onde:
+- `<escopo>` = `phase-N` (gate de fase no build) ou `planning` / `architecture` (gate no plan).
+- `<DECISAO>` = `APPROVE` | `REQUEST_CHANGES` | `BLOCK`.
+- `evidence=<tipo>:<resultado>` - **OBRIGATORIO no gate de fase** (escopo `phase-N`):
+  - `<tipo>` ∈ {`logic`, `ui`, `glue`}, derivado do `type` do plano (classify-task / heuristica):
+    parser/calculo/API-propria/bugfix -> `logic`; UI/CSS -> `ui`; integracao (Asaas/uazapi/etc) -> `glue`.
+  - `<resultado>` ∈ {`test_pass`, `visual`, `smoke`}: `logic:test_pass` (teste red-green),
+    `ui:visual` (captura antes/depois via Playwright), `glue:smoke` (smoke-test).
+  - O GATE de fase **so APROVA** se houver entry up-revisor com `evidence` preenchido do tipo certo.
+    Para escopos `planning`/`architecture` (gate do plan) o campo evidence e opcional.
 
-### Quando CEO age
+Exemplo (o revisor roda isto ao final - logica com teste red-green passando):
 
-1. **Escalacao do chief** — problema que chief nao resolveu
-2. **Pre-delivery** — auditoria final antes de entregar
-3. **Decisao estrategica** — briefing ambiguo, trade-off grande
+```bash
+echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) | phase-${PHASE_NUMBER} | up-revisor | APPROVE | spec ok, code-quality ok | evidence=logic:test_pass" \
+  >> .plano/governance/approvals.log
+```
 
-### Ciclos (CEO ← Chief)
+## 3. O GATE de fase (verificacao deterministica)
 
-Max 1 ciclo:
+Apos executor + verificador + revisor de uma fase, o orquestrador roda o gate. Ele NAO chama LLM:
 
-```
-Ciclo 1: CEO pede rework → Chief coordena com supervisores
-Apos isso: CEO decide APPROVE ou ALERTA_DONO
+```bash
+echo "=== GATE: Fase ${PHASE_NUMBER} ==="
+
+# Artefatos obrigatorios
+SUMMARY_OK=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null | wc -l)
+VERIF_OK=$(ls "${PHASE_DIR}"/*-VERIFICATION.md 2>/dev/null | wc -l)
+
+# Veredito do revisor logado para esta fase?
+REVISOR_ENTRY=$(grep "phase-${PHASE_NUMBER}.*up-revisor" .plano/governance/approvals.log 2>/dev/null | tail -1)
+
+PASS=true
+[ "$SUMMARY_OK" -eq 0 ] && echo "FALHA: sem SUMMARY.md" && PASS=false
+[ "$VERIF_OK" -eq 0 ] && echo "FALHA: sem VERIFICATION.md" && PASS=false
+[ -z "$REVISOR_ENTRY" ] && echo "FALHA: up-revisor NAO logou veredito" && PASS=false
+
+# Fase 3 - TDD: a entry PRECISA carregar evidence=<tipo>:<resultado> do tipo certo.
+# $EVIDENCE_TYPE e derivado no build.md (3.7) do type do plano; se vazio, exige so a presenca do campo.
+EVIDENCE_FIELD=$(echo "$REVISOR_ENTRY" | grep -oE 'evidence=(logic|ui|glue):(test_pass|visual|smoke)')
+if [ -z "$EVIDENCE_FIELD" ]; then
+  echo "FALHA: up-revisor sem campo evidence=<tipo>:<resultado>" && PASS=false
+elif [ -n "$EVIDENCE_TYPE" ] && ! echo "$EVIDENCE_FIELD" | grep -q "evidence=${EVIDENCE_TYPE}:"; then
+  echo "FALHA: evidence de tipo errado ($EVIDENCE_FIELD; esperado ${EVIDENCE_TYPE})" && PASS=false
+fi
+
+# Se logou, qual foi a decisao?
+DECISION=$(echo "$REVISOR_ENTRY" | awk -F'|' '{gsub(/ /,"",$4); print $4}')
+
+if [ "$PASS" = false ]; then
+  echo "GATE FALHOU: spawnar o agente faltante (verificador ou up-revisor) e re-rodar o gate."
+  # NAO avancar. Voltar e completar o passo faltante.
+elif [ "$DECISION" = "APPROVE" ]; then
+  echo "GATE OK: fase ${PHASE_NUMBER} aprovada. Marcar completa e avancar."
+elif [ "$DECISION" = "REQUEST_CHANGES" ]; then
+  echo "GATE: rework necessario na fase ${PHASE_NUMBER}. Ver passo 4 (cap 1 round)."
+elif [ "$DECISION" = "BLOCK" ]; then
+  echo "GATE: fase ${PHASE_NUMBER} BLOQUEADA pelo revisor. Alertar o dono (AskUserQuestion)."
+fi
 ```
 
-### Se CEO decide ALERTA_DONO
+## 4. Cap de rework (1 round)
 
-CEO usa severidade apropriada:
-- 🔴 Critico: sempre interrompe via AskUserQuestion
-- 🟡 Importante: interrompe se --interactive
-- 🟢 FYI: apenas registra
+Quando o revisor decide `REQUEST_CHANGES`:
 
-## Forced Approval (Debito Tecnico)
+```bash
+REWORK_FILE=".plano/governance/rework-phase-${PHASE_NUMBER}.count"
+ROUND=$(cat "$REWORK_FILE" 2>/dev/null || echo 0)
+```
 
-Quando max ciclos atingido sem melhoria:
+- **ROUND = 0:** re-spawnar o agente operacional (executor/specialist) com o review como contexto.
+  Incrementar: `echo 1 > "$REWORK_FILE"`. Depois re-rodar verificador + up-revisor + gate.
+- **ROUND >= 1:** NAO re-spawnar de novo. Forcar aprovacao com debito tecnico:
 
 ```bash
-# Registrar
 cat >> .plano/governance/technical-debt.log <<EOF
-$(date -u +%Y-%m-%dT%H:%M:%SZ) | {item-id} | {supervisor} | FORCED_APPROVAL
-  Reason: Max rework cycles ({N}) reached without improvement
-  Remaining issues: [lista]
+$(date -u +%Y-%m-%dT%H:%M:%SZ) | phase-${PHASE_NUMBER} | up-revisor | FORCED_APPROVAL
+  Reason: cap de rework (1 round) atingido sem resolucao completa
+  Remaining: [issues pendentes do review]
 EOF
 
-# Atualizar checklist
-node "$HOME/.claude/up/bin/up-tools.cjs" checklist update \
-  --item "{item-id}" \
-  --status "completed_with_debt"
+echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) | phase-${PHASE_NUMBER} | up-revisor | APPROVE | forced (debito tecnico) | evidence=${EVIDENCE_TYPE:-logic}:${EVIDENCE_RESULT:-test_pass}" \
+  >> .plano/governance/approvals.log
 ```
 
-Items com `completed_with_debt` aparecem no AUDIT-REPORT.md como ressalva.
-
-## Aplicacao em Cada Comando UP
-
-### /up:modo-builder (Full)
-- Governanca COMPLETA em todos estagios
-- CEO conduz intake e delivery
-- Supervisores em cada passo
-- Chiefs consolidam
-- CEO aprova antes do delivery
-
-### /up:modo-builder --light
-- Governanca LIGHT
-- Supervisores ainda ativos (criticos)
-- Chiefs pulados
-- CEO so no intake e delivery
-- Max rework: 1 ciclo
-
-### /up:rapido
-- Governanca MINIMAL
-- Apenas supervisor do operacional
-- Sem chief, sem CEO
-- Max rework: 1 ciclo
-
-### /up:planejar-fase
-- planning-supervisor ativo
-- Sem chief
-- Sem CEO
-
-### /up:executar-fase
-- execution-supervisor ativo
-- chief-engineer no final da fase
-- Sem CEO
+(O forced approval ainda carrega o campo `evidence` do tipo da fase para satisfazer o gate estendido; a
+ressalva de debito tecnico fica registrada em `technical-debt.log` e aparece no relatorio de entrega.)
 
-### /up:testar
-- quality-supervisor ativo
-- chief-quality no final
-- Sem CEO
-
-### /up:melhorias
-- audit-supervisor ativo
-- chief-quality no final
-
-### /up:verificar-trabalho
-- verification-supervisor ativo
-- Sem chief (UAT humano ja e autoritativo)
-
-## Flag Global: --no-supervision
-
-Para casos emergenciais onde voce precisa bypassar governanca:
-
-```
-/up:modo-builder "feature urgente" --no-supervision
-```
+Items com debito tecnico aparecem como ressalva no relatorio de entrega.
 
-Efeito:
-- Supervisores nao rodam
-- Nenhum rework
-- Trabalho direto pro proximo estagio
-- **Tudo registrado como SKIPPED_SUPERVISION no delivery**
+## 5. Bloqueio (BLOCK)
 
-Use APENAS em emergencia. Governanca existe por um motivo.
+Se o revisor decide `BLOCK` (ex: spec impossivel, perda de dados, ambiguidade critica), o orquestrador
+interrompe e alerta o dono via AskUserQuestion (sem CEO, output direto). O dono decide: ajustar escopo,
+re-planejar a fase (via `/up:plan`) ou abandonar.
 
 </process>
 
 <success_criteria>
-- [ ] Supervisor correspondente identificado
-- [ ] Supervisor spawnado com contexto correto
-- [ ] Decisao processada
-- [ ] Rework cycles respeitados
-- [ ] Escalacoes corretas
-- [ ] Forced approval com debito tecnico registrado
-- [ ] Checklist atualizado em cada passo
-- [ ] Governance logs mantidos
+- [ ] .plano/governance/approvals.log inicializado
+- [ ] Gate verifica artefatos (SUMMARY + VERIFICATION) e o veredito do up-revisor
+- [ ] Gate nao avanca sem entry do up-revisor para a fase
+- [ ] Gate exige campo evidence=<tipo>:<resultado> do tipo certo na entry (Fase 3 - TDD); forced approval
+      tambem carrega evidence
+- [ ] Cap de rework de 1 round respeitado; forced approval registra debito tecnico
+- [ ] BLOCK alerta o dono (sem CEO)
+- [ ] Nenhum spawn de CEO/chief/supervisor neste workflow
 </success_criteria>
+</output>