ganbatte-os 0.2.34 → 0.2.35

package/.gos/scripts/integrations/migrate-task-status.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * migrate-task-status.js
+ *
+ * Migra task files do formato bugado (`## Status` no body, sem frontmatter)
+ * para o formato canonico (frontmatter YAML com `status:`).
+ *
+ * Origem do bug: plan-to-tasks/SKILL.md tinha template inline obsoleto sem
+ * `status:`. Tasks geradas ficavam travadas em `pendente` mesmo apos
+ * *execute-plan rodar codigo, porque progress-tracker procura no frontmatter
+ * e nao acha. Corrigido em commit subsequente; este script reabilita planos
+ * preexistentes.
+ *
+ * Uso:
+ *   node migrate-task-status.js <plan-dir>
+ *   node migrate-task-status.js <plan-dir> --infer-from-diff
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const args = process.argv.slice(2);
+const planDir = args[0];
+const inferFromDiff = args.includes('--infer-from-diff');
+
+if (!planDir || !fs.existsSync(planDir)) {
+  console.error('uso: migrate-task-status.js <plan-dir> [--infer-from-diff]');
+  process.exit(1);
+}
+
+const tasksDir = path.join(planDir, 'tasks');
+if (!fs.existsSync(tasksDir)) {
+  console.error(`tasks dir nao encontrado: ${tasksDir}`);
+  process.exit(1);
+}
+
+const planFile = path.join(planDir, 'plan.md');
+const planSlug = path.basename(planDir);
+const planId = planSlug.split('-').slice(0, 2).join('-');
+
+function gitLog(args) {
+  try {
+    return execFileSync('git', args, { encoding: 'utf8' }).trim();
+  } catch {
+    return '';
+  }
+}
+
+const taskFiles = fs.readdirSync(tasksDir)
+  .filter((f) => /^T-\d+.*\.md$/.test(f))
+  .map((f) => path.join(tasksDir, f));
+
+let migrated = 0;
+let skipped = 0;
+let failed = 0;
+
+for (const file of taskFiles) {
+  const raw = fs.readFileSync(file, 'utf8');
+
+  if (raw.startsWith('---\n')) {
+    skipped++;
+    continue;
+  }
+
+  const titleMatch = raw.match(/^# (T-\d+(?:-\d+)?)[ —-]+(.+?)$/m);
+  const statusMatch = raw.match(/^## Status\s*\n+`?(\w[\w-]*)`?/m);
+
+  if (!titleMatch) {
+    console.error(`falha: ${file} — sem heading T-NN`);
+    failed++;
+    continue;
+  }
+
+  const taskId = titleMatch[1];
+  const title = titleMatch[2].trim();
+  const seqRaw = (taskId.match(/T-(\d+)(?:-(\d+))?/) || [])[2] || taskId.split('-')[1];
+  const bodyStatus = statusMatch ? statusMatch[1] : 'pendente';
+
+  let finalStatus = bodyStatus;
+  if (inferFromDiff && bodyStatus === 'pendente') {
+    const addCommit = gitLog(['log', '--diff-filter=A', '--format=%H', '--', planFile]);
+    const sinceCommit = addCommit ? addCommit.split('\n').pop() : '';
+    if (sinceCommit) {
+      const diff = gitLog(['log', `${sinceCommit}..HEAD`, '--name-only', '--pretty=format:']);
+      if (diff) finalStatus = 'validacao';
+    }
+  }
+
+  const bodyWithoutStatus = raw
+    .replace(/^## Status\s*\n+`?\w[\w-]*`?\s*\n+/m, '')
+    .replace(/^# T-\d+.*?\n+/m, '');
+
+  const frontmatter = `---
+id: ${taskId}
+plan_id: ${planId}
+seq: ${parseInt(seqRaw, 10)}
+title: ${title}
+area: frontend
+labels: [agent:dev]
+priority: P1
+estimate: "4h"
+status: ${finalStatus}
+valida_em: ""
+depends_on_backend: []
+interaction_target: []
+override_target: []
+assignees: []
+links: []
+---
+
+# ${taskId} — ${title}
+
+`;
+
+  fs.writeFileSync(file, frontmatter + bodyWithoutStatus);
+  migrated++;
+  console.log(`migrado: ${path.basename(file)} → status=${finalStatus}`);
+}
+
+console.log(`\n[migrate-task-status] ${migrated} migrados | ${skipped} ja-validos | ${failed} falhas`);
+process.exit(failed > 0 ? 1 : 0);

package/.gos/scripts/integrations/setup-ide-adapters.js

@@ -22,15 +22,53 @@ function relativeTarget(fromFile, targetFile) {
   return path.relative(path.dirname(fromFile), targetFile).replace(/\\/g, '/');
 }
 
+function agentSlug(id) {
+  return id.startsWith('gos-') ? id : `gos-${id}`;
+}
+
+function cleanupStaleAdapters() {
+  // Remove arquivos .md soltos no root de skills/ (formato legado) em todas as IDEs.
+  // Codex/Qwen/Gemini/Opencode/Antigravity esperam <slug>/SKILL.md (diretorio), nao .md solto.
+  // .agent e o diretorio canonico do Antigravity (workspace scope: .agent/skills/, .agent/workflows/).
+  const allIdes = ['.codex', '.qwen', '.gemini', '.opencode', '.agent'];
+  for (const ide of allIdes) {
+    const skillsDir = path.join(root, ide, 'skills');
+    if (fs.existsSync(skillsDir)) {
+      for (const entry of fs.readdirSync(skillsDir)) {
+        const full = path.join(skillsDir, entry);
+        if (fs.statSync(full).isFile() && entry.endsWith('.md')) {
+          fs.unlinkSync(full);
+        }
+      }
+    }
+    const agentsDir = path.join(root, ide, 'agents');
+    if (fs.existsSync(agentsDir)) {
+      for (const entry of fs.readdirSync(agentsDir)) {
+        if (/^gos-gos-/.test(entry)) {
+          fs.unlinkSync(path.join(agentsDir, entry));
+        }
+      }
+    }
+  }
+
+  // Legado: .antigravity/ era o diretorio errado (Antigravity nunca leu isso — usa .agent/).
+  // Remove silenciosamente para evitar drift entre IDEs.
+  const legacyAntigravity = path.join(root, '.antigravity');
+  if (fs.existsSync(legacyAntigravity)) {
+    fs.rmSync(legacyAntigravity, { recursive: true, force: true });
+  }
+}
+
 function agentWrapper(agentId, target) {
   return `# ${agentId}\n\nFonte canonica: \`${target}\`\n\nLeia e siga o perfil em \`${target}\`.\nEste arquivo existe apenas como adapter fino para a IDE.`;
 }
 
 function skillWrapper(slug, target, description) {
-  const body = `# gos-${slug}\n\nFonte canonica: \`${target}\`\n\nLeia e siga a skill em \`${target}\`.\nEste arquivo existe apenas como adapter fino para a IDE.`;
+  const fullSlug = slug.startsWith('gos-') ? slug : `gos-${slug}`;
+  const body = `# ${fullSlug}\n\nFonte canonica: \`${target}\`\n\nLeia e siga a skill em \`${target}\`.\nEste arquivo existe apenas como adapter fino para a IDE.`;
   if (!description) return body;
   const desc = String(description).replace(/"/g, '\\"').replace(/\n/g, ' ').slice(0, 200);
-  return `---\nname: "gos-${slug}"\ndescription: "${desc}"\n---\n\n${body}`;
+  return `---\nname: "${fullSlug}"\ndescription: "${desc}"\n---\n\n${body}`;
 }
 
 function qwenCommandWrapper(name, description, target) {
@@ -38,10 +76,11 @@ function qwenCommandWrapper(name, description, target) {
   return `---\ndescription: "${desc}"\n---\n\n# ${name} (Qwen Command Adapter)\n\n> Adapter para Qwen Code. Fonte canonica: \`${target}\`.\n\nCANONICAL-SOURCE: ${target}\n\n## Adapter Contract\n\n1. Leia o arquivo canonico em **CANONICAL-SOURCE** por completo.\n2. Execute as instrucoes desse arquivo como fonte primaria.\n3. Argumentos do usuario: {{args}}`;
 }
 
-function claudeCommandWrapper(name, description, target, argumentHint) {
+function claudeCommandWrapper(name, description, target, argumentHint, ideLabel) {
   const desc = (description || name).replace(/"/g, '\\"').replace(/\n/g, ' ').slice(0, 200);
   const hint = argumentHint ? `\nargument-hint: "${argumentHint.replace(/"/g, '\\"')}"` : '\nargument-hint: "[argumentos opcionais]"';
-  return `---\ndescription: "${desc}"${hint}\n---\n\n# ${name} (Claude Adapter)\n\n> Adapter fino para Claude. Fonte canonica: \`${target}\`.\n\nCANONICAL-SOURCE: ${target}\n\n## Adapter Contract\n\n1. Leia o arquivo canonico indicado em **CANONICAL-SOURCE** por completo.\n2. Execute as instrucoes desse arquivo como fonte primaria.\n3. Argumentos do usuario: $ARGUMENTS`;
+  const label = ideLabel || 'Claude';
+  return `---\ndescription: "${desc}"${hint}\n---\n\n# ${name} (${label} Adapter)\n\n> Adapter fino para ${label}. Fonte canonica: \`${target}\`.\n\nCANONICAL-SOURCE: ${target}\n\n## Adapter Contract\n\n1. Leia o arquivo canonico indicado em **CANONICAL-SOURCE** por completo.\n2. Execute as instrucoes desse arquivo como fonte primaria.\n3. Argumentos do usuario: $ARGUMENTS`;
 }
 
 function extractAgentDescription(filePath) {
@@ -86,32 +125,51 @@ function main() {
   const agents = readJson(path.join(root, '.gos', 'agents', 'profiles', 'index.json')).profiles;
   const skills = readJson(path.join(root, '.gos', 'skills', 'registry.json')).skills;
 
+  cleanupStaleAdapters();
+
   for (const agent of agents) {
     const agentProfilePath = path.join(root, '.gos', 'agents', 'profiles', agent.path);
     const agentDesc = extractAgentDescription(agentProfilePath) || `${agent.id} agent`;
+    const aSlug = agentSlug(agent.id);
 
     // Claude commands (requires YAML frontmatter with description)
     const claudeFile = path.join(root, '.claude', 'commands', 'gos', 'agents', `${agent.id}.md`);
-    writeFile(claudeFile, claudeCommandWrapper(`gos-${agent.id}`, agentDesc, relativeTarget(claudeFile, agentProfilePath)));
+    writeFile(claudeFile, claudeCommandWrapper(aSlug, agentDesc, relativeTarget(claudeFile, agentProfilePath), '', 'Claude'));
 
     // Qwen commands (requires YAML frontmatter with description)
     const qwenCmd = path.join(root, '.qwen', 'commands', 'gos', 'agents', `${agent.id}.md`);
-    writeFile(qwenCmd, qwenCommandWrapper(`gos-${agent.id}`, agentDesc, relativeTarget(qwenCmd, agentProfilePath)));
+    writeFile(qwenCmd, qwenCommandWrapper(aSlug, agentDesc, relativeTarget(qwenCmd, agentProfilePath)));
 
     // Qwen sub-agents
-    const qwenAgent = path.join(root, '.qwen', 'agents', `gos-${agent.id}.md`);
+    const qwenAgent = path.join(root, '.qwen', 'agents', `${aSlug}.md`);
     const agentTarget = relativeTarget(qwenAgent, agentProfilePath);
     const safeDesc = agentDesc.replace(/"/g, '\\"').replace(/\n/g, ' ').slice(0, 200);
-    writeFile(qwenAgent, `---\nname: "gos-${agent.id}"\ndescription: "${safeDesc}"\nmodel: inherit\ntools:\n  - Read\n  - Glob\n  - Grep\n  - Bash\n  - Edit\n  - Write\n---\n\nFonte canonica: \`${agentTarget}\`\nLeia e siga o perfil em \`${agentTarget}\`.`);
+    writeFile(qwenAgent, `---\nname: "${aSlug}"\ndescription: "${safeDesc}"\nmodel: inherit\ntools:\n  - Read\n  - Glob\n  - Grep\n  - Bash\n  - Edit\n  - Write\n---\n\nFonte canonica: \`${agentTarget}\`\nLeia e siga o perfil em \`${agentTarget}\`.`);
 
     // Codex commands (slash commands no Codex IDE Extension)
     const codexCmd = path.join(root, '.codex', 'commands', 'gos', 'agents', `${agent.id}.md`);
-    writeFile(codexCmd, claudeCommandWrapper(`gos-${agent.id}`, agentDesc, relativeTarget(codexCmd, agentProfilePath)));
+    writeFile(codexCmd, claudeCommandWrapper(aSlug, agentDesc, relativeTarget(codexCmd, agentProfilePath), '', 'Codex'));
 
     // Codex sub-agents (Codex IDE espera .codex/agents/<id>.md)
-    const codexAgent = path.join(root, '.codex', 'agents', `gos-${agent.id}.md`);
+    const codexAgent = path.join(root, '.codex', 'agents', `${aSlug}.md`);
     const codexAgentTarget = relativeTarget(codexAgent, agentProfilePath);
-    writeFile(codexAgent, `---\nname: "gos-${agent.id}"\ndescription: "${safeDesc}"\nmodel: inherit\ntools:\n  - Read\n  - Glob\n  - Grep\n  - Bash\n  - Edit\n  - Write\n---\n\nFonte canonica: \`${codexAgentTarget}\`\nLeia e siga o perfil em \`${codexAgentTarget}\`.`);
+    writeFile(codexAgent, `---\nname: "${aSlug}"\ndescription: "${safeDesc}"\nmodel: inherit\ntools:\n  - Read\n  - Glob\n  - Grep\n  - Bash\n  - Edit\n  - Write\n---\n\nFonte canonica: \`${codexAgentTarget}\`\nLeia e siga o perfil em \`${codexAgentTarget}\`.`);
+
+    // Codex / Antigravity (.agent/) / Gemini / Opencode usam namespace plano gos-<slug> em skills/.
+    // Agents aparecem no mesmo picker se emitidos como wrapper SKILL.md em skills/.
+    for (const ide of ['.codex', '.agent', '.gemini', '.opencode']) {
+      const ideAgentSkill = path.join(root, ide, 'skills', aSlug, 'SKILL.md');
+      writeFile(ideAgentSkill, skillWrapper(agent.id, relativeTarget(ideAgentSkill, agentProfilePath), agentDesc));
+    }
+
+    // Antigravity workflows (.agent/workflows/<id>.md) — slash command invocation no picker.
+    const antigravityWorkflow = path.join(root, '.agent', 'workflows', `${agent.id}.md`);
+    const workflowTarget = relativeTarget(antigravityWorkflow, agentProfilePath);
+    const safeAgentDesc = agentDesc.replace(/"/g, '\\"').replace(/\n/g, ' ').slice(0, 200);
+    writeFile(
+      antigravityWorkflow,
+      `---\ndescription: "${safeAgentDesc}"\n---\n\n# /${agent.id} (Antigravity Workflow)\n\nFonte canonica: \`${workflowTarget}\`\n\nLeia o arquivo canonico apontado em CANONICAL-SOURCE e execute as instrucoes como fonte primaria.\n\nCANONICAL-SOURCE: ${workflowTarget}\n\nArgumentos do usuario seguem o prompt do agente.`
+    );
   }
 
   for (const skill of skills) {
@@ -119,8 +177,7 @@ function main() {
     const canonicalPath = path.join(root, '.gos', skillTargetPath);
     const claudeSkill = path.join(root, '.claude', 'commands', 'gos', 'skills', `${skill.slug}.md`);
     const codexSkill = path.join(root, '.codex', 'skills', `gos-${skill.slug}`, 'SKILL.md');
-    const codexSkillCmd = path.join(root, '.codex', 'commands', 'gos', 'skills', `${skill.slug}.md`);
-    const antigravitySkill = path.join(root, '.antigravity', 'skills', `gos-${skill.slug}`, 'SKILL.md');
+    const antigravitySkill = path.join(root, '.agent', 'skills', `gos-${skill.slug}`, 'SKILL.md');
     const geminiSkill = path.join(root, '.gemini', 'skills', `gos-${skill.slug}`, 'SKILL.md');
     const opencodeSkill = path.join(root, '.opencode', 'skills', `gos-${skill.slug}`, 'SKILL.md');
     const qwenSkill = path.join(root, '.qwen', 'skills', `gos-${skill.slug}`, 'SKILL.md');
@@ -131,7 +188,6 @@ function main() {
     const skillDesc = skillFm.description || skill.description || skill.name || skill.slug;
     const skillArgHint = skillFm['argument-hint'] || '';
 
-    writeFile(claudeSkill, skillWrapper(skill.slug, relativeTarget(claudeSkill, canonicalPath), skillDesc));
     writeFile(codexSkill, skillWrapper(skill.slug, relativeTarget(codexSkill, canonicalPath), skillDesc));
     writeFile(antigravitySkill, skillWrapper(skill.slug, relativeTarget(antigravitySkill, canonicalPath), skillDesc));
     writeFile(geminiSkill, skillWrapper(skill.slug, relativeTarget(geminiSkill, canonicalPath), skillDesc));
@@ -139,46 +195,13 @@ function main() {
     writeFile(qwenSkill, skillWrapper(skill.slug, relativeTarget(qwenSkill, canonicalPath), skillDesc));
 
     writeFile(qwenCmd, qwenCommandWrapper(`gos-${skill.slug}`, skillDesc, relativeTarget(qwenCmd, canonicalPath)));
-    writeFile(codexSkillCmd, claudeCommandWrapper(`gos-${skill.slug}`, skillDesc, relativeTarget(codexSkillCmd, canonicalPath), skillArgHint));
-    writeFile(claudeSkill, claudeCommandWrapper(`gos-${skill.slug}`, skillDesc, relativeTarget(claudeSkill, canonicalPath), skillArgHint));
+    writeFile(claudeSkill, claudeCommandWrapper(`gos-${skill.slug}`, skillDesc, relativeTarget(claudeSkill, canonicalPath), skillArgHint, 'Claude'));
   }
 
-  const antigravityInstructions = [
-    '# G-OS Antigravity Instructions',
-    '',
-    'Leia sempre:',
-    '- `AGENTS.md`',
-    '- `CLAUDE.md`',
-    '- `.gos/docs/toolchain-map.md`',
-    '',
-    'Agentes disponiveis:',
-    ...agents.map((agent) => `- ${agent.id}`),
-    '',
-    'Skills curadas:',
-    ...skills.map((skill) => `- ${skill.slug}`),
-    '',
-    '## Como invocar Skills',
-    '',
-    'Para usar uma skill, leia o arquivo canonico e siga suas instrucoes.',
-    'Skills tambem disponiveis como adapters em `.antigravity/skills/`.',
-    '',
-    '| Skill | Arquivo canonico |',
-    '|-------|-----------------|',
-    ...skills.map((skill) => `| \`gos-${skill.slug}\` | \`.gos/${skill.skillFile || skill.path}\` |`)
-  ].join('\n');
-
-  writeFile(path.join(root, '.antigravity', 'instructions.md'), antigravityInstructions);
-  writeFile(
-    path.join(root, '.antigravity', 'config.json'),
-    JSON.stringify(
-      {
-        project: 'g-os',
-        instructions: ['instructions.md', '../AGENTS.md', '../CLAUDE.md']
-      },
-      null,
-      2
-    )
-  );
+  // Antigravity le AGENTS.md no root do workspace (ja existe no projeto).
+  // Skills vivem em .agent/skills/<slug>/SKILL.md (workspace scope, registrado acima no loop).
+  // Workflows (.agent/workflows/<id>.md) sao slash commands no picker da IDE.
+  // Rules opcionais em .agent/rules/ — nao geramos automaticamente (regras vivem no AGENTS.md).
 
   // Codex IDE Extension — AGENTS.md + config.toml
   // Codex e o ambiente de EXECUCAO (Opus planeja, Codex executa). Bloco abaixo garante
@@ -217,9 +240,9 @@ function main() {
     '',
     '## Como o Codex consome',
     '',
-    '- Slash commands em `.codex/commands/gos/{agents,skills}/<id>.md` -> Codex carrega o canonico apontado em CANONICAL-SOURCE e executa.',
-    '- Subagents em `.codex/agents/gos-<id>.md` -> referencia o profile em `.gos/agents/profiles/`.',
-    '- Skills em `.codex/skills/gos-<slug>/SKILL.md` -> wrapper fino que aponta para `.gos/skills/<slug>/SKILL.md`.',
+    '- Slash commands em `.codex/commands/gos/{agents,skills}/<id>.md` -> unica superficie de skills/agents. Codex carrega o canonico apontado em CANONICAL-SOURCE e executa.',
+    '- Subagents em `.codex/agents/gos-<id>.md` -> declaracao de subagent (acessivel via Task tool e delegacao interna).',
+    '- Para invocar o orquestrador master, digite `/gos:agents:gos-master` no picker.',
     ''
   ].join('\n');
   writeFile(path.join(root, '.codex', 'AGENTS.md'), codexAgentsMd);
@@ -229,14 +252,7 @@ function main() {
     '# Edite os arquivos canonicos em .gos/ ao inves deste.',
     '',
     'project = "g-os"',
-    '',
-    '[instructions]',
-    'files = [',
-    '  "AGENTS.md",',
-    '  "../AGENTS.md",',
-    '  "../CLAUDE.md",',
-    '  "../.gos/docs/toolchain-map.md",',
-    ']',
+    'instructions = "AGENTS.md"',
     '',
     '[execution]',
     'primary_command = "*execute-plan"',
@@ -251,16 +267,14 @@ function main() {
   // Evita regressoes silenciosas que ja quebraram a IDE no passado.
   const codexFailures = [];
   for (const agent of agents) {
-    const expectedAgent = path.join(root, '.codex', 'agents', `gos-${agent.id}.md`);
+    const expectedAgent = path.join(root, '.codex', 'agents', `${agentSlug(agent.id)}.md`);
     const expectedCmd = path.join(root, '.codex', 'commands', 'gos', 'agents', `${agent.id}.md`);
     if (!fs.existsSync(expectedAgent)) codexFailures.push(expectedAgent);
     if (!fs.existsSync(expectedCmd)) codexFailures.push(expectedCmd);
   }
   for (const skill of skills) {
     const expectedSkill = path.join(root, '.codex', 'skills', `gos-${skill.slug}`, 'SKILL.md');
-    const expectedCmd = path.join(root, '.codex', 'commands', 'gos', 'skills', `${skill.slug}.md`);
     if (!fs.existsSync(expectedSkill)) codexFailures.push(expectedSkill);
-    if (!fs.existsSync(expectedCmd)) codexFailures.push(expectedCmd);
   }
   if (!fs.existsSync(path.join(root, '.codex', 'AGENTS.md'))) codexFailures.push('.codex/AGENTS.md');
   if (!fs.existsSync(path.join(root, '.codex', 'config.toml'))) codexFailures.push('.codex/config.toml');

package/.gos/skills/execute-plan/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: execute-plan
-description: Executa um plano (PLAN-NNN-<slug>) task-a-task aplicando state machine + visual gate contra Storybook canonico antes de marcar validacao. Comando primario do ambiente Codex IDE.
-argument-hint: "<PLAN-NNN-slug> [--task T-NNN-NN] [--skip-visual-gate]"
+description: Executa um plano (PLAN-NNN-<slug>) task-a-task aplicando state machine + visual gate contra Storybook canonico antes de marcar validacao. Non-blocking em backend gaps (abre tasks ClickUp + segue). Comando primario do ambiente Codex IDE.
+argument-hint: "<PLAN-NNN-slug> [--task T-NNN-NN] [--skip-visual-gate] [--skip-clickup]"
 allowedTools: [Read, Glob, Grep, Bash, Write, Edit, Agent, AskUserQuestion]
 sourceDocs:
   - templates/taskTemplate.md
@@ -35,11 +35,16 @@ Formato esperado:
 
 1. Resolver paths via `.gos-local/plan-paths.json`. Se ausente, abortar e instruir o usuario a rodar `*plan` primeiro.
 2. Localizar `<dirs.planos>/<PLAN-NNN-slug>/plan.md`. Se ausente, abortar.
-3. Ler `plan.md` por completo: frontmatter + Componentes mapeados + Componentes ausentes + Aderencia a stack + Plano de execucao + Checklist de aceite.
+3. Ler `plan.md` por completo: frontmatter + Componentes mapeados + Componentes ausentes + Aderencia a stack + Plano de execucao + Checklist de aceite + **Backend pendings**.
 4. Validar `stack_ref` do frontmatter contra `<dirs.stack>` (`docs/stack.md`):
    - Calcular sha-curto atual e comparar.
    - Drift detectado: ABORTAR e instruir `*stack drift` + replanejar com `*stack refresh`.
 5. Ler `<dirs.progress>` (progress.txt). Se aponta para outro plano ativo, perguntar se troca o foco antes de prosseguir.
+6. **Backend pendings (non-blocking)**: ler tabela `## Backend pendings` do `plan.md`. Para cada linha:
+   - Sem `ClickUp ID` -> criar task via `mcp__clickup__clickup_create_task` (assignee `112010775` salvo override `ASSIGNEE` no plano, list de `clickup.backend_list_id` em `plan-paths.json`, titulo `[Backend] PLAN-NNN: <gap>`). Gravar ID retornado de volta na coluna `ClickUp ID` do `plan.md`.
+   - Com `ClickUp ID` -> consultar `mcp__clickup__clickup_get_task <ID>`. Atualizar coluna `Status`. Se ainda aberta, registrar em `progress.txt` como `blockers=<T-IDs>:<ClickUp-ID>:<gap-curto>` (uma linha por bloqueio ativo).
+   - `--skip-clickup` desliga MCP; nesse caso so registra warning visivel mantendo o que ja esta no plano.
+   - **Importante**: backend gap aberto NAO aborta o execute-plan. Tasks frontend que dependem do gap serao classificadas como `bloqueada-backend` no loop abaixo; tasks sem dependencia seguem normal.
 
 ## Pre-flight visual
 
@@ -52,11 +57,41 @@ Formato esperado:
    - Se ausente: gerar task de criacao do componente ANTES das tasks de implementacao. Renumerar `seq` das tasks restantes.
 4. Output do pre-flight: bloco em `progress.txt` campo `notes=` com numero de stories indexadas e tasks de criacao geradas.
 
+## Pre-flight visual smoke (NOVO)
+
+Antes da T-01 (depois do pre-flight de stories acima), gera comparacao visual entre pagina renderizada e frame Figma para capturar gaps grandes ANTES da execucao — evita o padrao PLAN-005 onde feedback iterativo gerou 26 rodadas no fim.
+
+Ativacao:
+- Storybook disponivel: usa `.stories.tsx` da pagina-completa quando existe (ex.: `ProjetosPage.stories.tsx`) e renderiza via `npm run storybook -- --static-build` ou screenshot ja gerado em CI.
+- Playwright MCP disponivel (`mcp__plugin_playwright_playwright__*`): navega para localhost (rota da pagina + seed declarado em `## Mock strategy` ou seed nativo do projeto) e captura screenshot.
+- Nenhum disponivel: pula com warning em `progress.txt` (`smoke=skipped: no storybook story for full page nor playwright MCP`). NAO bloqueia.
+
+Comparacao:
+1. Carrega frame Figma principal (`figma_url` do plano) via Figma MCP — extrai layout/secoes esperadas.
+2. Confronta screenshot vs frame em 3 dimensoes basicas (sem refazer 4-dim por componente — isso fica no gate por task):
+   - **Secoes presentes**: KPI row, toolbar, table, drawer trigger, etc. — cada secao esperada esta no screenshot?
+   - **Layout grosseiro**: ordem vertical das secoes; colunas da table batem com Figma?
+   - **Cores/tokens primarios**: bg da pagina, accent color, contrast — sem inversao obvia.
+3. Output: `<dirs.planos>/<PLAN-NNN-slug>/preflight-smoke.md` com lista de gaps detectados (secao faltando, layout invertido, cor errada).
+4. Se gaps detectados: gerar tasks `T-000-XX` (prefixo `000` = pre-flight) com `priority: P0` e prepend no inicio da fila. Renumerar `seq` das tasks subsequentes.
+
+Pre-flight smoke nao substitui o visual gate por task — ele captura gaps grandes (componente faltando, KPI row ausente) que viraram tasks novas em PLAN-004/PLAN-005.
+
 ## Loop por task
 
-Iterar tasks em ordem de `seq`. Para cada `tasks/T-NNN-NN-*.md`:
+Iterar tasks em ordem de `seq`. Antes de executar cada task, **classificar**:
 
-1. **Mover para em-andamento**: `*progress status T-NNN-NN em-andamento`. State machine valida transicao.
+- Ler frontmatter `depends_on_backend:` da task (campo opcional, default `[]`). Cada item referencia uma `gap-key` da tabela `## Backend pendings` do plano (ex.: `migration-20260501150000`, `endpoint-projetos-fields`).
+- Se a task referencia gap em aberto (status no ClickUp != `concluido`/`closed`):
+  - `*progress status T-NNN-NN bloqueada-backend` (transicao livre desde `pendente` ou `em-andamento`).
+  - Anotar em `tasks/T-NNN-NN.notes.md` linha `## Bloqueada backend <iso>` com ClickUp IDs.
+  - **PULAR** task — NAO falha o loop, segue pra proxima.
+- Se a task tem `depends_on_backend: []` ou todas as dependencias estao `concluido` no ClickUp -> seguir fluxo normal abaixo.
+
+Para cada task **executavel**:
+
+0. **Pre-flight da task — gate de formato**: ler `tasks/T-NNN-NN*.md`. Confirmar que tem frontmatter YAML (`head -1 == "---"`) e contém `^status:` no frontmatter. Se ausente: ABORTAR a task com erro `task-malformada: T-NNN-NN sem frontmatter status — rodar plan-to-tasks regenerador OU migrate-task-status.js`. NUNCA tentar executar codigo sem frontmatter valido — sintoma do bug onde tasks ficam travadas em `pendente`.
+1. **Mover para em-andamento**: invocar `*progress status T-NNN-NN em-andamento` (skill `progress-tracker`). **Pos-condicao obrigatoria**: ler T-NNN-NN.md de novo e confirmar `^status: em-andamento$` no frontmatter. Se nao mudou: ABORTAR e instruir humano. NAO seguir para implementacao com status pendente — esse e o bug central reportado.
 2. **Despachar agent**: ler `labels: [agent:<slug>]` da task. Default: `dev`. Invocar via Agent tool com prompt completo (objetivo, plano de execucao, DoD, paths relevantes).
 3. **Implementacao**: agent edita arquivos seguindo o plano de execucao da task. Stack como contrato — nada fora de `docs/stack.md` salvo se `arch_change=true` no frontmatter do plano pai.
 4. **Visual gate** (antes de propor `validacao`):
@@ -64,29 +99,44 @@ Iterar tasks em ordem de `seq`. Para cada `tasks/T-NNN-NN-*.md`:
    Para cada componente alterado/criado pela task:
 
    a) Localizar `<Componente>.stories.tsx` em `<dirs.storybook>`.
-   b) Comparar implementacao vs story canonica em 4 dimensoes textuais:
+   b) Comparar implementacao vs story canonica em 5 dimensoes textuais:
       - **Anatomia**: ordem de slots/elementos (header -> corpo -> footer; icones esquerda/direita; campos do form na ordem do design).
-      - **Tokens**: classes Tailwind/variaveis CSS batem com DS (cor, raio, espacamento, tipografia).
-      - **Variants**: props expostos cobrem variants da story.
-      - **Densidade**: padding/gap dentro de +-1 step da escala do DS.
+      - **Tokens**: classes Tailwind/variaveis CSS batem com DS (cor, raio, espacamento, tipografia). Quando o componente aparece em `## Page-level overrides` do plano: a divergencia cosmetica registrada NAO falha o gate — o gate confirma que o override foi APLICADO conforme decisao (a/b/c).
+      - **Variants**: props expostos cobrem variants da story. Decisao (b) em `## Page-level overrides`: confirmar que a nova variant existe na story canonica.
+      - **Densidade**: padding/gap dentro de +-1 step da escala do DS (ou conforme override registrado).
+      - **Comportamentos** (NOVO, heuristico via JSX + grep, sem E2E):
+        - Para cada `interaction_target:` declarado no frontmatter da task: existe handler implementado no diff? (ex.: `row.onClick` chamando `openDrawer`; `button.onClick` chamando mutation; `form.onSubmit` chamando server action).
+        - Estados visuais (skeleton/empty/error/loading) declarados em `## Interações & Estados` renderizam? grep por `isLoading|isPending|isError|empty|skeleton` nos arquivos tocados.
+        - Refetch apos mutation: `invalidateQueries` / `router.refresh` / `setState` observavel no diff?
+        - Para cada `override_target:` declarado: classes/props da decisao (a/b/c) presentes no diff? grep das classes declaradas em `## Page-level overrides`.
    c) Para a tela como um todo: invocar Figma MCP no `figma_url` do plano e cruzar com o JSX renderizado em arvore (mesmo numero de secoes, mesma hierarquia, mesmas labels).
-   d) Output: relatorio curto em `tasks/T-NNN-NN.notes.md` (4 secoes: anatomia, tokens, variants, densidade + secao "Arvore vs Figma").
-   e) Divergencia >= 1 item critico (anatomia ou tokens) -> falha o gate.
+   d) Output: relatorio curto em `tasks/T-NNN-NN.notes.md` (5 secoes: anatomia, tokens, variants, densidade, comportamentos + secao "Arvore vs Figma").
+   e) Divergencia >= 1 item critico (anatomia, tokens nao-overrideados, ou comportamento mapeado sem implementacao) -> falha o gate.
 
 5. **Resultado do gate**:
-   - Sucesso -> `*progress status T-NNN-NN validacao`. Preparar arquivos staged (sem commit).
+   - Sucesso -> invocar `*progress status T-NNN-NN validacao`. **Pos-condicao obrigatoria**: ler T-NNN-NN.md, confirmar `^status: validacao$` no frontmatter. Se nao mudou: ABORTAR a task com erro `progress-tracker-falhou: T-NNN-NN`. Preparar arquivos staged (sem commit) somente apos confirmacao.
    - Falha -> manter em `em-andamento`, gravar diff em `T-NNN-NN.notes.md`, retornar pra etapa 3.
 
+**Invariante por task**: ao terminar a iteracao, T-NNN-NN.md DEVE ter status diferente de `pendente`. Se ainda for `pendente` apos a iteracao, registrar como bug do executor em `progress.txt` (`notes=executor-skipped-progress: T-NNN-NN`) e abortar o loop — sintoma do bug original.
+
 ## Fechamento
 
-Quando todas as tasks atingirem `validacao` E o checklist de aceite do plano estiver marcado:
+Quando o loop terminar (todas as tasks executaveis em `validacao` ou puladas em `bloqueada-backend`):
 
 1. Listar arquivos modificados via `git diff --name-only`.
-2. Preparar commit (NAO push). Mensagem segue Conventional Commits + referencia ao `PLAN-NNN-slug`.
-3. Resumo final ao usuario:
-   - Path do plano + numero de tasks concluidas.
-   - Lista de componentes que passaram/falharam o visual gate.
-   - Comando exato para o humano marcar `concluido`: `*progress status T-NNN-NN concluido` (apos validacao humana + smoke E2E).
+2. Preparar commit (NAO push). Mensagem segue Conventional Commits + referencia ao `PLAN-NNN-slug`. Se houve tasks bloqueadas, citar na mensagem (ex.: `feat(checkout): PLAN-042 T-01..T-05 (T-06,T-07 bloqueadas backend CU-XXX)`).
+3. Resumo final ao usuario em 4 blocos:
+   ```
+   [execute-plan] PLAN-NNN-<slug>
+
+   tasks validacao:    <N>  (T-..., T-...)
+   bloqueada-backend:  <K>  (T-...:CU-..., ...)
+   backend pendings:   <X>  abertas no ClickUp / <Y> concluidas
+   visual gate:        passou / falhou em (T-...)
+
+   proximo passo: *validate-plan PLAN-NNN-<slug>
+   ```
+4. Indicar que o turn seguinte e `*validate-plan PLAN-NNN-<slug>` (skill `validate-plan`, ambiente Opus 4.7). NAO marcar `concluido` automaticamente — `validate-plan` cuida disso.
 
 ## Ambiente Codex IDE — observacoes
 
@@ -98,8 +148,10 @@ Quando todas as tasks atingirem `validacao` E o checklist de aceite do plano est
 
 - **Visual gate nao e opcional** salvo `--skip-visual-gate` explicito. Skill nao silencia o gate.
 - **Sem push automatico**: commit fica preparado. Push e responsabilidade do humano.
-- **State machine inviolavel**: transicao `concluido` so apos humano validar + checklist.
-- **Storybook como contrato**: componente sem `.stories.tsx` em `<dirs.storybook>` bloqueia a task ate ser criado.
+- **State machine inviolavel**: transicao `concluido` ocorre via `*validate-plan` (auto-marca quando passa). Rollback humano: `*progress status T-NNN-NN pendente --rollback`.
+- **Non-blocking em backend gaps**: gap aberto no ClickUp NAO aborta. Tasks dependentes viram `bloqueada-backend`, demais seguem.
+- **Storybook como contrato base; Figma da pagina vence em conflito cosmetico**: componente sem `.stories.tsx` em `<dirs.storybook>` bloqueia a task ate ser criado. Divergencia cosmetica entre story e Figma da pagina que ESTA registrada em `## Page-level overrides` do plano: gate confirma aplicacao do override (decisao a/b/c). Divergencia NAO registrada no plano: gate falha — voltar pra `*plan` (ou registrar override no plan.md antes de prosseguir).
+- **Comportamento mapeado e vinculante**: `interaction_target:` declarado na task DEVE ter handler/estado implementado e observavel no diff. Caso contrario, gate falha mesmo se anatomia + tokens passarem.
 
 ## Model guidance