up-cc 0.6.0 → 0.8.0

package/bin/up-instrument.cjs

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+
+/**
+ * UP Instrumentation — measures token usage per UP agent
+ *
+ * Reads Claude Code session.jsonl + subagent jsonls and produces a token cost
+ * report grouped by agent. Used to identify the heaviest agents (so we know
+ * where to apply tiered context optimizations) and to give users visibility
+ * into the cost of a build.
+ *
+ * Usage:
+ *   node up-instrument.cjs report                # current project, current session
+ *   node up-instrument.cjs report --all-sessions # current project, all sessions
+ *   node up-instrument.cjs report --json         # JSON output
+ *   node up-instrument.cjs watch                 # write .plano/INSTRUMENTATION.md continuously
+ *
+ * Opt-in via /up:configurar (instrumentation.enabled = true).
+ * Default: off.
+ *
+ * NOTE: Only works with Claude Code runtime (reads ~/.claude/projects).
+ *       OpenCode and Gemini CLI use different log formats — falls back gracefully.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const HOME = os.homedir();
+const CLAUDE_PROJECTS = path.join(HOME, '.claude', 'projects');
+
+// Convert /home/projects/up-cc → -home-projects-up-cc
+function projectKey(cwd) {
+  return cwd.replace(/^\//, '').replace(/\//g, '-').replace(/^/, '-');
+}
+
+function listSessions(projectDir) {
+  if (!fs.existsSync(projectDir)) return [];
+  return fs
+    .readdirSync(projectDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => path.join(projectDir, d.name));
+}
+
+function listJsonls(sessionDir) {
+  const files = [];
+  const walk = (dir) => {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.name.endsWith('.jsonl')) files.push(full);
+    }
+  };
+  walk(sessionDir);
+  return files;
+}
+
+function parseJsonl(file) {
+  const events = [];
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return events;
+  }
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      events.push(JSON.parse(line));
+    } catch {
+      // skip malformed
+    }
+  }
+  return events;
+}
+
+// Build canonical list of UP agent names from agents/ directory.
+// This gives us ground truth and avoids false matches like "up-hover" or "up-load".
+function loadUpAgentNames() {
+  const candidates = [
+    path.join(__dirname, '..', 'agents'),
+    path.join(__dirname, '..', 'up', 'agents'),
+    path.join(HOME, '.claude', 'up', 'agents'),
+    path.join(HOME, '.claude', 'agents'),
+  ];
+  const names = new Set();
+  for (const dir of candidates) {
+    if (!fs.existsSync(dir)) continue;
+    for (const f of fs.readdirSync(dir)) {
+      if (f.startsWith('up-') && f.endsWith('.md')) {
+        names.add(f.replace(/\.md$/, ''));
+      }
+    }
+  }
+  return names;
+}
+
+const KNOWN_UP_AGENTS = loadUpAgentNames();
+
+// Extract agent name from a subagent jsonl path or first event.
+// Subagent files live in <session>/subagents/agent-<id>.jsonl.
+function detectAgentName(events, file) {
+  // Strategy 1: scan events for known UP agent names in content
+  for (const ev of events.slice(0, 5)) {
+    const c = ev?.message?.content;
+    let text = '';
+    if (typeof c === 'string') text = c;
+    else if (Array.isArray(c)) {
+      text = c
+        .map((item) => (typeof item === 'string' ? item : item?.text || ''))
+        .join(' ');
+    }
+    if (!text) continue;
+
+    // Match against canonical UP agent names
+    for (const name of KNOWN_UP_AGENTS) {
+      if (text.includes(name)) return name;
+    }
+
+    // Match "Voce e o {something}" pattern from UP role definitions
+    const roleMatch = text.match(/Voce e o ([A-Z][a-zA-Z ]+?)( UP|\.|,|\n)/);
+    if (roleMatch) {
+      const role = roleMatch[1].trim().toLowerCase().replace(/\s+/g, '-');
+      const candidate = `up-${role}`;
+      if (KNOWN_UP_AGENTS.has(candidate)) return candidate;
+    }
+  }
+
+  // Strategy 2: top-level fields
+  for (const ev of events.slice(0, 3)) {
+    if (ev?.subagent_type && ev.subagent_type.startsWith('up-')) {
+      return ev.subagent_type;
+    }
+    if (ev?.slug && ev.slug.startsWith('up-') && KNOWN_UP_AGENTS.has(ev.slug)) {
+      return ev.slug;
+    }
+  }
+
+  // Strategy 3: file id fallback (grouped under "non-up" so we don't pollute UP stats)
+  const m = file.match(/agent-([a-z0-9]+)\.jsonl$/);
+  return m ? `non-up-agent` : 'unknown';
+}
+
+function aggregateUsage(events) {
+  let input = 0;
+  let cacheCreation = 0;
+  let cacheRead = 0;
+  let output = 0;
+  let calls = 0;
+  for (const ev of events) {
+    const u = ev?.message?.usage || ev?.usage;
+    if (!u) continue;
+    input += u.input_tokens || 0;
+    cacheCreation += u.cache_creation_input_tokens || 0;
+    cacheRead += u.cache_read_input_tokens || 0;
+    output += u.output_tokens || 0;
+    calls += 1;
+  }
+  return { input, cacheCreation, cacheRead, output, calls };
+}
+
+// Opus 4.6 1M pricing (rough): input $15/M, output $75/M, cache write $18.75/M, cache read $1.50/M
+function estimateCost(usage) {
+  const PRICE = {
+    input: 15 / 1_000_000,
+    cacheCreation: 18.75 / 1_000_000,
+    cacheRead: 1.5 / 1_000_000,
+    output: 75 / 1_000_000,
+  };
+  return (
+    usage.input * PRICE.input +
+    usage.cacheCreation * PRICE.cacheCreation +
+    usage.cacheRead * PRICE.cacheRead +
+    usage.output * PRICE.output
+  );
+}
+
+function formatNumber(n) {
+  if (n >= 1_000_000) return (n / 1_000_000).toFixed(2) + 'M';
+  if (n >= 1_000) return (n / 1_000).toFixed(1) + 'k';
+  return String(n);
+}
+
+function buildReport(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const projectDir = path.join(CLAUDE_PROJECTS, projectKey(cwd));
+  const sessions = listSessions(projectDir);
+  if (sessions.length === 0) {
+    return { error: 'no_sessions', message: `No Claude Code sessions found for ${cwd}. Are you running in Claude Code runtime?` };
+  }
+
+  const targetSessions = opts.allSessions ? sessions : [sessions[sessions.length - 1]];
+  const byAgent = new Map();
+  const filesScanned = [];
+
+  for (const sessionDir of targetSessions) {
+    const subagentDir = path.join(sessionDir, 'subagents');
+    const files = listJsonls(subagentDir);
+    for (const file of files) {
+      filesScanned.push(file);
+      const events = parseJsonl(file);
+      const name = detectAgentName(events, file);
+      const usage = aggregateUsage(events);
+      const prev = byAgent.get(name) || { input: 0, cacheCreation: 0, cacheRead: 0, output: 0, calls: 0, invocations: 0 };
+      prev.input += usage.input;
+      prev.cacheCreation += usage.cacheCreation;
+      prev.cacheRead += usage.cacheRead;
+      prev.output += usage.output;
+      prev.calls += usage.calls;
+      prev.invocations += 1;
+      byAgent.set(name, prev);
+    }
+  }
+
+  const rows = [];
+  let totalCost = 0;
+  let totalInput = 0;
+  let totalOutput = 0;
+  for (const [agent, u] of byAgent.entries()) {
+    const cost = estimateCost(u);
+    totalCost += cost;
+    totalInput += u.input + u.cacheCreation + u.cacheRead;
+    totalOutput += u.output;
+    rows.push({
+      agent,
+      invocations: u.invocations,
+      input: u.input + u.cacheCreation + u.cacheRead,
+      output: u.output,
+      cost,
+      avgPerInvoc: u.invocations > 0 ? (u.input + u.cacheCreation + u.cacheRead) / u.invocations : 0,
+    });
+  }
+  rows.sort((a, b) => b.cost - a.cost);
+
+  return {
+    cwd,
+    sessions: targetSessions.length,
+    files_scanned: filesScanned.length,
+    total_input_tokens: totalInput,
+    total_output_tokens: totalOutput,
+    total_cost_usd: totalCost,
+    agents: rows,
+  };
+}
+
+function renderMarkdown(report) {
+  if (report.error) return `# Instrumentation\n\n${report.message}\n`;
+  const lines = [];
+  lines.push('# Token Instrumentation');
+  lines.push('');
+  lines.push(`Project: \`${report.cwd}\``);
+  lines.push(`Sessions analyzed: ${report.sessions}`);
+  lines.push(`Subagent files scanned: ${report.files_scanned}`);
+  lines.push('');
+  lines.push('## Totals');
+  lines.push(`- Input tokens: **${formatNumber(report.total_input_tokens)}**`);
+  lines.push(`- Output tokens: **${formatNumber(report.total_output_tokens)}**`);
+  lines.push(`- Estimated cost (Opus 4.6 pricing): **$${report.total_cost_usd.toFixed(2)}**`);
+  lines.push('');
+  lines.push('## Top agents by cost');
+  lines.push('');
+  lines.push('| Agent | Invocations | Input | Avg/invoc | Output | Cost |');
+  lines.push('|---|---:|---:|---:|---:|---:|');
+  for (const row of report.agents.slice(0, 20)) {
+    lines.push(
+      `| ${row.agent} | ${row.invocations} | ${formatNumber(row.input)} | ${formatNumber(row.avgPerInvoc)} | ${formatNumber(row.output)} | $${row.cost.toFixed(2)} |`
+    );
+  }
+  lines.push('');
+  lines.push(`> Generated by \`up-instrument\` at ${new Date().toISOString()}`);
+  lines.push('> Pricing assumes Claude Opus 4.6 1M context. Real cost may vary.');
+  return lines.join('\n') + '\n';
+}
+
+function renderTable(report) {
+  if (report.error) return report.message;
+  const lines = [];
+  lines.push(`Project: ${report.cwd}`);
+  lines.push(`Sessions: ${report.sessions}  Files: ${report.files_scanned}`);
+  lines.push(`Total: ${formatNumber(report.total_input_tokens)} in / ${formatNumber(report.total_output_tokens)} out / $${report.total_cost_usd.toFixed(2)}`);
+  lines.push('');
+  lines.push('Top agents:');
+  for (const row of report.agents.slice(0, 15)) {
+    const pad = (s, n) => String(s).padEnd(n);
+    lines.push(`  ${pad(row.agent, 30)} ${pad(row.invocations + 'x', 6)} ${pad(formatNumber(row.input), 8)} avg ${pad(formatNumber(row.avgPerInvoc), 8)} $${row.cost.toFixed(2)}`);
+  }
+  return lines.join('\n');
+}
+
+// CLI
+const args = process.argv.slice(2);
+const cmd = args[0] || 'report';
+const opts = {
+  allSessions: args.includes('--all-sessions'),
+  json: args.includes('--json'),
+  cwd: process.cwd(),
+};
+
+if (cmd === 'report') {
+  const report = buildReport(opts);
+  if (opts.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(renderTable(report));
+  }
+} else if (cmd === 'write') {
+  const report = buildReport(opts);
+  const planoDir = path.join(opts.cwd, '.plano');
+  if (!fs.existsSync(planoDir)) {
+    console.error('No .plano directory found in current cwd. Run from a UP project root.');
+    process.exit(1);
+  }
+  const outFile = path.join(planoDir, 'INSTRUMENTATION.md');
+  fs.writeFileSync(outFile, renderMarkdown(report));
+  console.log(`Wrote ${outFile}`);
+} else if (cmd === '--help' || cmd === 'help') {
+  console.log(`up-instrument — token usage measurement for UP agents
+
+Commands:
+  report                Print top agents by cost (default, current session)
+  report --all-sessions Same but across all sessions for current project
+  report --json         JSON output
+  write                 Write .plano/INSTRUMENTATION.md (current session)
+  write --all-sessions  Write report across all sessions
+
+Notes:
+  - Only works with Claude Code (reads ~/.claude/projects/<key>/subagents/*.jsonl)
+  - OpenCode and Gemini CLI use different log formats and are not supported yet
+  - Pricing assumes Claude Opus 4.6 1M context — real cost may vary`);
+} else {
+  console.error(`Unknown command: ${cmd}. Try 'help'.`);
+  process.exit(1);
+}

package/commands/custos.md

@@ -0,0 +1,67 @@
+---
+name: up:custos
+description: Mostra estimativa de custo em tokens dos agentes UP usados no projeto atual (Claude Code only)
+allowed-tools:
+  - Bash
+  - Read
+---
+
+<objective>
+Reportar custo estimado de tokens consumidos por agentes UP no projeto atual.
+Usa `bin/up-instrument.cjs` para parsear `~/.claude/projects/<key>/subagents/*.jsonl`
+e agregar uso por agente.
+</objective>
+
+<process>
+
+## 1. Detectar runtime
+
+```bash
+if [ ! -d "$HOME/.claude/projects" ]; then
+  echo "Instrumentation requer Claude Code runtime."
+  echo "OpenCode e Gemini CLI usam formatos de log diferentes (nao suportado ainda)."
+  exit 0
+fi
+```
+
+## 2. Rodar relatorio
+
+```bash
+# Default: sessao mais recente
+node "$HOME/.claude/up/bin/up-instrument.cjs" report
+
+# Se quiser todas as sessoes do projeto:
+# node "$HOME/.claude/up/bin/up-instrument.cjs" report --all-sessions
+
+# Se quiser JSON:
+# node "$HOME/.claude/up/bin/up-instrument.cjs" report --json
+```
+
+## 3. Salvar em .plano/INSTRUMENTATION.md (opcional)
+
+Se a flag `--save` foi passada OU se .plano/ existe:
+
+```bash
+if [ -d ".plano" ]; then
+  node "$HOME/.claude/up/bin/up-instrument.cjs" write
+  echo ""
+  echo "Relatorio salvo em .plano/INSTRUMENTATION.md"
+fi
+```
+
+## 4. Apresentar interpretacao
+
+Apos mostrar a tabela, comentar:
+
+- **Top 3 agentes mais caros** — onde focar otimizacao
+- **Total estimado** — em USD assumindo Opus 4.6 pricing
+- **Comparacao com outras sessoes** se historico disponivel
+
+</process>
+
+<notes>
+- Pricing assume Opus 4.6 1M context: input $15/M, output $75/M, cache write $18.75/M, cache read $1.50/M
+- Custos reais podem variar conforme modelo selecionado no /model
+- Apenas funciona em Claude Code — OpenCode e Gemini CLI nao expoe usage por subagent ainda
+- Detecta agentes UP cruzando contra a lista canonica em `agents/up-*.md`
+</notes>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "up-cc",
-  "version": "0.6.0",
-  "description": "Simplified spec-driven development for Claude Code, Gemini and OpenCode.",
+  "version": "0.8.0",
+  "description": "Simplified spec-driven development for Claude Code, Gemini, OpenCode and OpenAI Codex.",
   "bin": {
     "up-cc": "bin/install.js"
   },

package/references/engineering-principles-compressed.md

@@ -0,0 +1,26 @@
+# Engineering Principles (compressed)
+
+> Versao compactada para injecao inline em prompts. ~400 tokens vs 2.5k da versao completa.
+> Versao completa em `engineering-principles.md` — Read sob demanda se precisar de exemplos detalhados.
+
+## 6 Principios
+
+1. **Implementacao real, nao simulacao** — Zero `onClick={() => {}}`, zero placeholder, zero API que retorna `{ok: true}` estatico, zero `useState([])` sem setter, zero imports nao usados. Se nao pode implementar agora: declare explicitamente como debito tecnico.
+
+2. **Correto, nao rapido** — Tipagem explicita (sem `any`). Validacao com lib (zod/yup). Queries parametrizadas. `===` nao `==`. `crypto.randomUUID()` nao `Math.random()`. `structuredClone` nao `Object.assign` raso.
+
+3. **Conectado de ponta a ponta** — Componente → rota navegavel. API → frontend chama + trata response. Schema → migration rodada. Validacao → form aplica + feedback visivel. "Arquivo existe" ≠ "funciona". Usuario consegue usar no browser.
+
+4. **Consistencia sobre criatividade** — Antes de implementar: `grep` por pattern similar no codebase. Se React Query existe, use `useQuery`. Se Button component existe, use `<Button>`. Se Tailwind, use classes. Nao invente patterns paralelos.
+
+5. **Dados reais desde o primeiro momento** — Banco real com seed > API real > mock temporario removido > hardcoded (PROIBIDO). Se banco existe, conecte desde o primeiro componente. Mock so em testes automatizados.
+
+6. **Cada decisao tem custo futuro** — Sem tipagem = bugs silenciosos. Sem pagination = trava com 10k items. Sem error handling = crash cego. Sem indices = queries lentas. Custo de fazer certo e linear, refatorar e exponencial.
+
+## Aplicacao
+
+- Antes de cada tarefa: reler mentalmente os 6
+- Durante: checar cada decisao contra a lista
+- Antes de commit: self-review rapido
+- No SUMMARY: documentar violacoes como debito tecnico
+- Para exemplos detalhados: `Read references/engineering-principles.md`

package/references/governance-rules-compressed.md

@@ -0,0 +1,31 @@
+# Governance Rules (compressed)
+
+> Versao compactada para injecao inline. ~250 tokens vs 1.9k da versao completa.
+> Versao completa em `governance-rules.md` — Read sob demanda para hierarquia detalhada.
+
+## Hierarquia
+DONO → CEO → 5 Chiefs → 8 Supervisores → 36 Operacionais
+
+## Decisoes do Supervisor (apos cada operacional)
+- **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
+
+## Decisoes do Chief (apos area completa)
+- APPROVE | REQUEST_CHANGES (volta pro supervisor) | ESCALATE pro CEO
+
+## Decisoes do CEO (antes de delivery)
+- APPROVE_DELIVERY | ALERTA_DONO | REWORK (volta pro chief)
+
+## Anti-patterns (NUNCA aprovar se)
+- Trabalho nao foi de fato verificado ("parece ok")
+- Evidencia faltando ou ambigua
+- SUMMARY claim sem backing no codigo
+- Rework cycle no max sem melhoria
+- Stub/placeholder em vez de implementacao real
+- Falta de wiring (componente criado mas nao conectado)
+
+## Logging obrigatorio
+Toda decisao em `.plano/governance/approvals.log | reworks.log | escalations.log`.
+
+Para detalhes de poderes especificos por nivel: `Read references/governance-rules.md`

package/references/production-requirements-compressed.md

@@ -0,0 +1,23 @@
+# Production Requirements (compressed)
+
+> Versao compactada para injecao inline. ~300 tokens vs 1.3k da versao completa.
+> Versao completa em `production-requirements.md` — Read sob demanda para checklist completo (60+ itens).
+
+## Categorias e contagem (cada item tem ID)
+- **UIST** (8) — UI States: loading/error/empty/success, disabled, optimistic, confirm destrutivo
+- **ERR** (8) — Error handling: boundaries, try/catch, sessao expirada, 404, offline, server-side validation
+- **PERF** (9) — Performance: lazy loading, code split, debounce, pagination, cache, memo, prefetch
+- **FORM** (8) — Forms: inline validation, mensagens especificas, autofocus, tab order, defaults, mascaras
+- **RESP** (7) — Responsividade: 375px funcional, touch 44x44, hamburger mobile, modais fullscreen
+- **META** (7) — Meta/SEO: title unico, og tags, favicon, manifest, canonical, robots
+- **A11Y** (9) — Acessibilidade: alt, labels, focus visible, keyboard, aria, contraste 4.5:1, landmarks
+- **SEC** (8) — Seguranca: rotas protegidas, CSRF, XSS, rate limit, headers, UUID, env vars, RLS
+- **POLISH** (7) — Visual: hover, transicoes 150-300ms, escala espacamento, design tokens, dark mode
+
+## Total: 71 requisitos de producao em 9 categorias
+
+Quando precisar de IDs especificos ou descricao detalhada de um item:
+`Read references/production-requirements.md` e procure pela categoria.
+
+Arquiteto/system-designer injetam estes requisitos automaticamente no REQUIREMENTS.md.
+Supervisores validam contra eles antes de approval.

package/references/rework-limits-compressed.md

@@ -0,0 +1,22 @@
+# Rework Limits (compressed)
+
+> Versao compactada para injecao inline. ~150 tokens vs 2k da versao completa.
+> Versao completa em `rework-limits.md` — Read sob demanda para fluxos detalhados.
+
+## Limites por nivel
+| Nivel | Max Ciclos | Apos limite |
+|---|---|---|
+| Operacional ← Supervisor | **3** | Forca approval, marca como debito tecnico |
+| Supervisor ← Chief | **2** | Escalacao pro CEO |
+| Chief ← CEO | **1** | CEO decide: aceitar ou alertar dono |
+
+## Quando forcar aprovacao (apos max ciclos)
+- Melhoria entre ciclos < 10% (diminishing returns)
+- Issue nao pode ser resolvida sem info externa
+- Acao: registrar em `governance/technical-debt.log`, marcar item como `completed_with_debt`
+
+## Rework rate saudavel: 15-30%
+- < 5% = supervisor mal calibrado, aprovando sem criterio
+- > 40% = prompt vago ou criterios muito rigidos
+
+Para fluxos completos por ciclo: `Read references/rework-limits.md`

package/workflows/build.md

@@ -181,12 +181,47 @@ Agent(
   prompt=f"""
     Executar Plano da Fase {phase_number}.
     
+    <engineering_principles_compressed>
+    1. Implementacao real, nao simulacao (zero placeholder, zero stub)
+    2. Correto, nao rapido (sem `any`, validacao com lib, queries parametrizadas)
+    3. Conectado ponta a ponta (componente → API → DB com dados fluindo)
+    4. Consistencia (grep por pattern existente antes de inventar)
+    5. Dados reais desde o primeiro momento (sem hardcode)
+    6. Cada decisao tem custo futuro (escolher solucao escalavel)
+    
+    Em duvida entre rapido e correto: sempre o correto.
+    Sob demanda: Read references/engineering-principles.md para exemplos.
+    </engineering_principles_compressed>
+    
+    <production_requirements_compressed>
+    Categorias a respeitar (71 requisitos no total):
+    - UIST (UI States): loading/error/empty/success em TODA operacao async
+    - ERR (Error handling): boundaries, try/catch, sessao expirada, 404
+    - PERF: lazy loading, code split, debounce, pagination > 20 items, cache
+    - FORM: validacao inline, mensagens especificas, autofocus, mascaras
+    - RESP: 375px funcional, touch 44x44, hamburger mobile
+    - A11Y: alt, labels, focus visible, keyboard, contraste 4.5:1
+    - SEC: rotas protegidas, CSRF, XSS, rate limit, env vars, RLS
+    - POLISH: hover, transicoes 150-300ms, design tokens
+    
+    Sob demanda: Read references/production-requirements.md para IDs especificos.
+    </production_requirements_compressed>
+    
     <files_to_read>
+    TIER 1 — Sempre:
     - {PLAN}
-    - .plano/PROJECT.md
-    - .plano/SYSTEM-DESIGN.md
-    - $HOME/.claude/up/references/engineering-principles.md
-    - $HOME/.claude/up/references/production-requirements.md
+    - .plano/STATE.md
+    - ./CLAUDE.md (se existir)
+    
+    TIER 2 — Se a slice da fase existe (v0.7.0+):
+    - .plano/fases/{phase_number}/PHASE.md (objetivo da fase)
+    - .plano/fases/{phase_number}/REQUIREMENTS-SLICE.md (REQs APENAS desta fase)
+    - .plano/DESIGN-TOKENS.md (se for frontend e existir)
+    
+    TIER 3 — Sob demanda apenas:
+    - .plano/PROJECT.md (so se precisar visao geral)
+    - .plano/SYSTEM-DESIGN.md (so se decisao de arquitetura aparecer)
+    - .plano/REQUIREMENTS.md (so se a slice nao tiver info suficiente)
     </files_to_read>
     
     Implementar todas as tarefas. Commitar atomicamente.
@@ -203,10 +238,33 @@ Agent(
   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
+    </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
+    - git diff (use Bash)
+    - .plano/fases/{phase_number}/REQUIREMENTS-SLICE.md (se existir)
+    
+    Sob demanda apenas:
+    - $HOME/.claude/up/references/engineering-principles.md (exemplos)
+    - $HOME/.claude/up/references/governance-rules.md (hierarquia)
+    - $HOME/.claude/up/references/rework-limits.md (fluxos)
+    - $HOME/.claude/up/references/production-requirements.md (IDs especificos)
     </files_to_read>
     
     Decisao: APPROVE | REQUEST_CHANGES | REQUEST_REPLAN | ESCALATE

package/workflows/governance.md

@@ -32,17 +32,39 @@ Spawnar o supervisor:
 ```python
 Agent(
   subagent_type="up-{supervisor_name}",
-  model="opus",
   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>
-    - $HOME/.claude/up/references/governance-rules.md
-    - $HOME/.claude/up/references/rework-limits.md
     - [arquivos do output do operacional]
-    - [arquivos de contexto]
+    - [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.md
+    - Read $HOME/.claude/up/references/rework-limits.md
+    - Read $HOME/.claude/up/references/engineering-principles.md
+    
     Avaliar contra criterios objetivos.
     Retornar: APPROVE | REQUEST_CHANGES | ESCALATE
   """

package/workflows/plan.md

@@ -155,12 +155,24 @@ Agent(
     Sonnet-ready: SEMPRE (default v0.6.0+)
     
     <files_to_read>
+    TIER 1 — Sempre:
     - .plano/STATE.md
-    - .plano/ROADMAP.md
-    - .plano/REQUIREMENTS.md
-    - .plano/SYSTEM-DESIGN.md
-    - .plano/PROJECT.md
-    - .plano/codebase/* (se brownfield)
+    - .plano/fases/{phase_number}/PHASE.md (slice do ROADMAP — v0.7.0+)
+    - .plano/fases/{phase_number}/REQUIREMENTS-SLICE.md (REQs APENAS desta fase — v0.7.0+)
+    
+    TIER 2 — Se brownfield apenas:
+    - .plano/codebase/CONVENTIONS.md
+    - .plano/codebase/CONCERNS.md
+    - .plano/codebase/ARCHITECTURE.md
+    
+    TIER 3 — Sob demanda apenas:
+    - .plano/SYSTEM-DESIGN.md (so se decisao arquitetural especifica)
+    - .plano/PROJECT.md (so se precisar visao geral)
+    - .plano/ROADMAP.md (so se precisar entender fases adjacentes)
+    - .plano/REQUIREMENTS.md (so se a slice nao tiver info suficiente)
+    
+    FALLBACK: Se as slices nao existem (projeto pre-v0.7.0), carregar
+    .plano/ROADMAP.md e .plano/REQUIREMENTS.md completos.
     </files_to_read>
     
     REQs da fase: {phase_req_ids}