@spec-wave/cli 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
   "type": "module",
   "bin": {

package/src/api/github-rest.mjs

@@ -150,8 +150,10 @@ export async function removeLabel(token, owner, repo, issueNumber, labelName) {
   }
 }
 
-// Lista todos os comentários de uma issue/PR: [{ author, body, createdAt }].
-// Paginado — traz o histórico completo (usado pela crítica adversarial).
+// Lista todos os comentários de uma issue/PR: [{ id, author, body, createdAt }].
+// Paginado — traz o histórico completo (usado pela crítica adversarial e pelo
+// comentário acumulado de uso de IA). `id` é o database id do comentário,
+// exigido pelo updateComment.
 export async function listIssueComments(token, owner, repo, issueNumber) {
   const octokit = makeOctokit(token);
   const comments = await octokit.paginate(octokit.rest.issues.listComments, {
@@ -161,12 +163,25 @@ export async function listIssueComments(token, owner, repo, issueNumber) {
     per_page: 100,
   });
   return comments.map(c => ({
+    id: c.id,
     author: c.user?.login || '',
     body: c.body || '',
     createdAt: c.created_at,
   }));
 }
 
+// Atualiza o corpo de um comentário existente. `commentId` é o database id
+// retornado por listIssueComments.
+export async function updateComment(token, owner, repo, commentId, body) {
+  const octokit = makeOctokit(token);
+  await octokit.rest.issues.updateComment({
+    owner,
+    repo,
+    comment_id: commentId,
+    body,
+  });
+}
+
 // Marca uma issue como bloqueada por outra (relação nativa do GitHub).
 // `blockingIssueId` é o DATABASE id da issue bloqueadora (não o number nem o
 // node id — ver createIssue). Erros propagam: o chamador usa como fallback.

package/src/commands/decompose.mjs

@@ -1,42 +1,22 @@
 import { existsSync, readFileSync } from 'node:fs';
-import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, createIssue, removeLabel, addLabel, commentOnIssue, addBlockedBy } from '../api/github-rest.mjs';
-import { addSubIssue, addProjectItem, setItemSingleSelect, getSingleSelectField, listSubIssues } from '../api/github-graphql.mjs';
+import { addSubIssue, listSubIssues } from '../api/github-graphql.mjs';
+import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
 import { generateDocument } from '../lib/claude.mjs';
 import { runCritique } from '../lib/critique.mjs';
+import { recordUsage } from '../lib/usage-report.mjs';
 import { formatDependencyLine } from '../lib/dependencies.mjs';
 import { lintLanguage } from '../lib/output-lint.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
-import { CONFIG_FILE, DECOMPOSE_TARGETS, LABEL_DECOMPOSED, LABEL_CRITIQUE_FAILED, TARGET_LANGUAGE } from '../config.mjs';
+import { DECOMPOSE_TARGETS, LABEL_DECOMPOSED, LABEL_CRITIQUE_FAILED, TARGET_LANGUAGE, STAGE_READY, PROGRESS_TODO } from '../config.mjs';
 
-const READY_STAGE = 'Todo';
-
-// Carrega o projeto do .spec-wave.json. Retorna null se ausente ou sem project.id.
-function loadProject() {
-  const configPath = path.join(process.cwd(), CONFIG_FILE);
-  if (!existsSync(configPath)) return null;
-  try {
-    return JSON.parse(readFileSync(configPath, 'utf-8')).project || null;
-  } catch {
-    return null;
-  }
-}
-
-// Resolve o campo Status do Project: usa .spec-wave.json ou consulta API.
-async function resolveStatusField(token, project) {
-  if (project.fields?.Status) return project.fields.Status;
-  return await getSingleSelectField(token, project.id, 'Status');
-}
-
-// Adiciona issue ao board e move para a etapa informada. Best-effort.
-async function moveToStage(token, project, statusField, nodeId, stageName) {
-  if (!project?.id || !statusField) return;
-  const optionId = statusField.options?.[stageName];
-  if (!statusField.id || !optionId) return;
-  const itemId = await addProjectItem(token, project.id, nodeId);
-  await setItemSingleSelect(token, project.id, itemId, statusField.id, optionId);
+// Adiciona a issue ao board na Etapa ✅ Ready / Status Todo. Best-effort; a
+// Etapa nunca retrocede (advanceToStage não toca itens já adiante).
+async function moveToReady(token, project, etapaField, statusField, nodeId) {
+  if (!project?.id) return;
+  await advanceToStage(token, project, etapaField, statusField, nodeId, STAGE_READY, PROGRESS_TODO);
 }
 
 // Extrai JSON da resposta do modelo (tolera texto em volta).
@@ -148,7 +128,7 @@ Regras:
 
 // Decompõe uma Feature em Stories (+ Tasks), cada uma vinculada como sub-issue.
 async function decomposeFeature(ctx) {
-  const { token, projectToken, owner, repo, issue, issueNumber, project, statusField } = ctx;
+  const { token, projectToken, owner, repo, issue, issueNumber, project, etapaField, statusField, usage } = ctx;
   const slug = slugify(issue.title);
   const featureDir = `docs/features/${slug}`;
 
@@ -167,7 +147,7 @@ async function decomposeFeature(ctx) {
     `\n## plan.md\n${planContent}`,
   ].join('\n');
 
-  const decomposition = parseJson(await generateDocument(FEATURE_SYSTEM_PROMPT, userContent));
+  const decomposition = parseJson(await generateDocument(FEATURE_SYSTEM_PROMPT, userContent, { action: 'decompose', usage }));
 
   // Crítica adversarial ANTES de criar qualquer issue: stories que contradizem
   // a spec/plan não devem virar trabalho. Crítica indisponível → só avisa.
@@ -178,6 +158,7 @@ async function decomposeFeature(ctx) {
       spec: existsSync(`${featureDir}/spec.md`) ? specContent : null,
       plan: existsSync(`${featureDir}/plan.md`) ? planContent : null,
       stories: decomposition.stories,
+      usage,
     });
   } catch (err) {
     console.warn(`Crítica adversarial indisponível: ${err.message}`);
@@ -241,9 +222,9 @@ async function decomposeFeature(ctx) {
       console.warn(`  Story #${createdStory.number} criada, mas falhou ao vincular à Feature: ${err.message}`);
     }
     try {
-      await moveToStage(projectToken, project, statusField, createdStory.nodeId, READY_STAGE);
+      await moveToReady(projectToken, project, etapaField, statusField, createdStory.nodeId);
     } catch (err) {
-      console.warn(`  Falha ao mover story #${createdStory.number} para "${READY_STAGE}": ${err.message}`);
+      console.warn(`  Falha ao mover story #${createdStory.number} para "${STAGE_READY}": ${err.message}`);
     }
 
     for (const task of story.tasks || []) {
@@ -258,18 +239,18 @@ async function decomposeFeature(ctx) {
         console.warn(`    Task #${createdTask.number} criada, mas falhou ao vincular à Story: ${err.message}`);
       }
       try {
-        await moveToStage(projectToken, project, statusField, createdTask.nodeId, READY_STAGE);
+        await moveToReady(projectToken, project, etapaField, statusField, createdTask.nodeId);
       } catch (err) {
-        console.warn(`    Falha ao mover task #${createdTask.number} para "${READY_STAGE}": ${err.message}`);
+        console.warn(`    Falha ao mover task #${createdTask.number} para "${STAGE_READY}": ${err.message}`);
       }
     }
   }
 
   try {
-    await moveToStage(projectToken, project, statusField, featureNodeId, READY_STAGE);
-    if (project?.id && statusField) console.log(`Feature movida para "${READY_STAGE}" no board.`);
+    await moveToReady(projectToken, project, etapaField, statusField, featureNodeId);
+    if (project?.id && etapaField) console.log(`Feature movida para "${STAGE_READY}" no board.`);
   } catch (err) {
-    console.warn(`Falha ao mover Feature para "${READY_STAGE}": ${err.message}`);
+    console.warn(`Falha ao mover Feature para "${STAGE_READY}": ${err.message}`);
   }
 
   // Marca a Feature como decomposta (guard de idempotência em runs futuros).
@@ -293,7 +274,7 @@ async function decomposeFeature(ctx) {
 // Decompõe um RFC diretamente em Tasks (sem Stories), cada uma vinculada como
 // sub-issue do RFC.
 async function decomposeRFC(ctx) {
-  const { token, projectToken, owner, repo, issue, issueNumber, project, statusField } = ctx;
+  const { token, projectToken, owner, repo, issue, issueNumber, project, etapaField, statusField, usage } = ctx;
   console.log(`Decompondo RFC: ${issue.title}`);
 
   const userContent = [
@@ -302,7 +283,7 @@ async function decomposeRFC(ctx) {
     `\n## Descrição\n${issue.body || '(sem descrição)'}`,
   ].join('\n');
 
-  const decomposition = parseJson(await generateDocument(RFC_SYSTEM_PROMPT, userContent));
+  const decomposition = parseJson(await generateDocument(RFC_SYSTEM_PROMPT, userContent, { action: 'decompose', usage }));
   const rfcNodeId = issue.node_id;
   const tasks = decomposition.tasks || [];
   const created = [];
@@ -322,9 +303,9 @@ async function decomposeRFC(ctx) {
       console.warn(`  Task #${createdTask.number} criada, mas falhou ao vincular ao RFC: ${err.message}`);
     }
     try {
-      await moveToStage(projectToken, project, statusField, createdTask.nodeId, READY_STAGE);
+      await moveToReady(projectToken, project, etapaField, statusField, createdTask.nodeId);
     } catch (err) {
-      console.warn(`  Falha ao mover task #${createdTask.number} para "${READY_STAGE}": ${err.message}`);
+      console.warn(`  Falha ao mover task #${createdTask.number} para "${STAGE_READY}": ${err.message}`);
     }
   }
 
@@ -397,18 +378,33 @@ export async function decompose({ issueNumber }) {
     return;
   }
 
-  // Projeto + campo Status (reutilizado em todos os itens).
-  const project = loadProject();
+  // Projeto + campos Etapa/Status do board (reutilizados em todos os itens).
+  const { project, error: projectError } = loadProjectConfig();
+  if (projectError) console.warn(`${projectError} — itens criados não serão posicionados no board.`);
+  let etapaField = null;
   let statusField = null;
   if (project?.id) {
     try {
-      statusField = await resolveStatusField(projectToken, project);
+      etapaField = await resolveField(projectToken, project, 'Etapa');
+    } catch (err) {
+      console.warn(`Não foi possível resolver campo Etapa do board: ${err.message}`);
+    }
+    try {
+      statusField = await resolveField(projectToken, project, 'Status');
     } catch (err) {
       console.warn(`Não foi possível resolver campo Status do board: ${err.message}`);
     }
   }
 
-  const ctx = { token, projectToken, owner, repo, issue, issueNumber, project, statusField };
-  if (type === 'Feature') await decomposeFeature(ctx);
-  else if (type === 'RFC') await decomposeRFC(ctx);
+  // Coletor de uso de IA — o finally registra o custo já incorrido mesmo nos
+  // fluxos que retornam cedo (ex.: abort da crítica grave) ou que falham.
+  const usageEntries = [];
+  const ctx = { token, projectToken, owner, repo, issue, issueNumber, project, etapaField, statusField, usage: usageEntries };
+  try {
+    if (type === 'Feature') await decomposeFeature(ctx);
+    else if (type === 'RFC') await decomposeRFC(ctx);
+  } finally {
+    // Best-effort: nunca propaga erro (ver recordUsage).
+    await recordUsage({ token, owner, repo, issueNumber: parseInt(issueNumber, 10), entries: usageEntries });
+  }
 }

package/src/commands/doctor.mjs

@@ -333,6 +333,37 @@ async function checkAi(ctx) {
   return { name, status, detail: notes.join('\n') };
 }
 
+// Exportado para teste: só lê ctx.cfg e process.env — sem rede/filesystem.
+export function checkSpecKit(ctx) {
+  const name = 'Spec-kit (specKit.command para o implement)';
+  const fromEnv = process.env.SPEC_WAVE_IMPLEMENT_CMD;
+  const fromConfig = ctx.cfg?.specKit?.command;
+  if (fromEnv) {
+    return {
+      name,
+      status: 'ok',
+      detail: `Definido via env SPEC_WAVE_IMPLEMENT_CMD${fromConfig ? ' (sobrepõe o specKit.command do config)' : ''}: ${fromEnv}`,
+    };
+  }
+  if (fromConfig) {
+    return { name, status: 'ok', detail: `Definido no ${CONFIG_FILE}: ${fromConfig}` };
+  }
+  return {
+    name,
+    status: 'warn',
+    detail:
+      'Nenhum comando configurado — `implement` só monta o contexto, sem acionar um agente.\n' +
+      `Defina "specKit": { "command": "..." } no ${CONFIG_FILE} (ou a env SPEC_WAVE_IMPLEMENT_CMD).\n` +
+      'Placeholders: {tasksFile} {specFile} {planFile} {issue} {type} {title}. Exemplos por agente:\n' +
+      '  Claude Code: claude -p "Implemente as tasks descritas em {tasksFile}"\n' +
+      '  opencode:    opencode run "Implemente as tasks descritas em {tasksFile}"\n' +
+      '  Codex:       codex exec "Implemente as tasks descritas em {tasksFile}"\n' +
+      '  Copilot CLI: copilot -p "Implemente as tasks descritas em {tasksFile}" --allow-all-tools\n' +
+      '  Kiro CLI:    kiro-cli chat --no-interactive --trust-all-tools "Implemente as tasks descritas em {tasksFile}"\n' +
+      '  Qwen Code:   qwen -p "Implemente as tasks descritas em {tasksFile}"',
+  };
+}
+
 async function checkWorkflows(ctx) {
   const name = 'Workflows do Actions';
   const dir = path.join(ctx.cwd, '.github', 'workflows');
@@ -380,6 +411,7 @@ export async function doctor() {
     checkConfig,
     checkRepoAccess,
     checkAi,
+    checkSpecKit,
     checkWorkflows,
   ];
   const results = [];

package/src/commands/generate-plan.mjs

@@ -6,6 +6,7 @@ import { detectIssueType } from '../lib/issue-type.mjs';
 import { allowsSpecPlan, SPEC_PLAN_EXCLUDED_TYPES, TARGET_LANGUAGE, LABEL_CRITIQUE_FAILED } from '../config.mjs';
 import { generateDocument } from '../lib/claude.mjs';
 import { runCritique } from '../lib/critique.mjs';
+import { recordUsage } from '../lib/usage-report.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { buildTechContext } from '../lib/tech-context.mjs';
 
@@ -26,6 +27,7 @@ O plano deve conter EXATAMENTE estas seções em português, nesta ordem:
 # Estratégia Técnica
   - Abordagem Arquitetural, Decisões-Chave e uma Matriz de Rastreabilidade (tabela) ligando cada Critério de Aceite do spec a um componente técnico.
 # Detalhamento da Implementação
+  - Abra a seção com um diagrama de sequência Mermaid (bloco \`\`\`mermaid iniciado com sequenceDiagram) do fluxo principal ponta a ponta, com os componentes técnicos reais como participants (frontend, endpoints/controllers, services, banco de dados, filas). Use APENAS componentes do tech_context ou definidos neste plano; rotule as mensagens com os caminhos de endpoint e nomes de método reais, em português.
   - Subseções: ## Backend, ## Banco de Dados, ## Frontend, ## Infraestrutura.
 # Segurança e Conformidade
 # Estratégia de Testes
@@ -91,59 +93,69 @@ export async function generatePlan({ issueNumber }) {
   };
   const userContent = `Gere o plan.md a partir deste payload JSON:\n\n${JSON.stringify(payload, null, 2)}`;
 
-  console.log(`Gerando plan.md para: ${issue.title}`);
-  const { content, lintFindings } = await generateDocument(SYSTEM_PROMPT, userContent, {
-    action: 'plan',
-    lint: { lang: TARGET_LANGUAGE },
-    withReport: true,
-  });
-
-  mkdirSync(featureDir, { recursive: true });
-  writeFileSync(filePath, content, 'utf-8');
-
-  // Commit and push
-  const git = (cmd) => execSync(cmd, { stdio: 'inherit' });
-  git(`git config user.email "spec-wave[bot]@github.com"`);
-  git(`git config user.name "spec-wave[bot]"`);
-  git(`git add "${filePath}"`);
-  git(`git commit -m "docs: generate plan.md for ${slug} [spec-wave]"`);
-  git('git pull --rebase');
-  git('git push');
-
-  // Remove trigger label
-  await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:plan');
-
-  // Comment on issue
-  await commentOnIssue(
-    token, owner, repo, parseInt(issueNumber, 10),
-    `📋 **plan.md gerado automaticamente!**\n\n` +
-    `📄 Arquivo: [\`${filePath}\`](https://github.com/${owner}/${repo}/blob/main/${filePath})\n\n` +
-    `Revise o plano e, quando estiver pronto, valide a Feature: mova o card para **✅ Ready** ou use:\n` +
-    `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:ready"\n\`\`\`` +
-    formatLintWarning(lintFindings)
-  );
-
-  // Crítica adversarial: audita o plan recém-comitado contra spec +
-  // tech_context. NUNCA desfaz o plan — falha da crítica vira só um aviso.
+  // Coletor de uso de IA — o finally registra o custo já incorrido (geração +
+  // crítica) mesmo se o fluxo falhar no meio.
+  const usageEntries = [];
   try {
-    const critique = await runCritique({
-      kind: 'plan',
-      spec: specContent,
-      plan: content,
-      techContextYaml: tech.yaml,
+    console.log(`Gerando plan.md para: ${issue.title}`);
+    const { content, lintFindings } = await generateDocument(SYSTEM_PROMPT, userContent, {
+      action: 'plan',
+      lint: { lang: TARGET_LANGUAGE },
+      withReport: true,
+      usage: usageEntries,
     });
-    await commentOnIssue(token, owner, repo, parseInt(issueNumber, 10), critique.markdown);
-    if (critique.grave) {
-      await addLabel(token, owner, repo, parseInt(issueNumber, 10), LABEL_CRITIQUE_FAILED);
-      console.log(`Crítica adversarial apontou findings GRAVES — label ${LABEL_CRITIQUE_FAILED} aplicada.`);
-    }
-  } catch (err) {
-    console.warn(`Crítica adversarial indisponível: ${err.message}`);
+
+    mkdirSync(featureDir, { recursive: true });
+    writeFileSync(filePath, content, 'utf-8');
+
+    // Commit and push
+    const git = (cmd) => execSync(cmd, { stdio: 'inherit' });
+    git(`git config user.email "spec-wave[bot]@github.com"`);
+    git(`git config user.name "spec-wave[bot]"`);
+    git(`git add "${filePath}"`);
+    git(`git commit -m "docs: generate plan.md for ${slug} [spec-wave]"`);
+    git('git pull --rebase');
+    git('git push');
+
+    // Remove trigger label
+    await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:plan');
+
+    // Comment on issue
     await commentOnIssue(
       token, owner, repo, parseInt(issueNumber, 10),
-      `⚠️ crítica adversarial indisponível (erro: ${err.message})`
-    ).catch(() => {});
-  }
+      `📋 **plan.md gerado automaticamente!**\n\n` +
+      `📄 Arquivo: [\`${filePath}\`](https://github.com/${owner}/${repo}/blob/main/${filePath})\n\n` +
+      `Revise o plano e, quando estiver pronto, valide a Feature: mova o card para **✅ Ready** ou use:\n` +
+      `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:ready"\n\`\`\`` +
+      formatLintWarning(lintFindings)
+    );
 
-  console.log(`plan.md criado em: ${filePath}`);
+    // Crítica adversarial: audita o plan recém-comitado contra spec +
+    // tech_context. NUNCA desfaz o plan — falha da crítica vira só um aviso.
+    try {
+      const critique = await runCritique({
+        kind: 'plan',
+        spec: specContent,
+        plan: content,
+        techContextYaml: tech.yaml,
+        usage: usageEntries,
+      });
+      await commentOnIssue(token, owner, repo, parseInt(issueNumber, 10), critique.markdown);
+      if (critique.grave) {
+        await addLabel(token, owner, repo, parseInt(issueNumber, 10), LABEL_CRITIQUE_FAILED);
+        console.log(`Crítica adversarial apontou findings GRAVES — label ${LABEL_CRITIQUE_FAILED} aplicada.`);
+      }
+    } catch (err) {
+      console.warn(`Crítica adversarial indisponível: ${err.message}`);
+      await commentOnIssue(
+        token, owner, repo, parseInt(issueNumber, 10),
+        `⚠️ crítica adversarial indisponível (erro: ${err.message})`
+      ).catch(() => {});
+    }
+
+    console.log(`plan.md criado em: ${filePath}`);
+  } finally {
+    // Best-effort: nunca propaga erro (ver recordUsage).
+    await recordUsage({ token, owner, repo, issueNumber: parseInt(issueNumber, 10), entries: usageEntries });
+  }
 }

package/src/commands/generate-spec.mjs

@@ -3,6 +3,7 @@ import { mkdirSync, writeFileSync } from 'node:fs';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, removeLabel, commentOnIssue } from '../api/github-rest.mjs';
 import { generateDocument } from '../lib/claude.mjs';
+import { recordUsage } from '../lib/usage-report.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { allowsSpecPlan, SPEC_PLAN_EXCLUDED_TYPES, TARGET_LANGUAGE } from '../config.mjs';
@@ -26,6 +27,8 @@ O spec deve conter EXATAMENTE estas seções em português, nesta ordem:
 # Regras de Negócio
 # Fluxos
   - Subseções: ## Fluxo Principal (Happy Path), ## Fluxos Alternativos, ## Cenários de Erro.
+  - O Fluxo Principal DEVE conter, além da descrição passo a passo, um diagrama de sequência Mermaid (bloco \`\`\`mermaid iniciado com sequenceDiagram) mostrando a interação entre as personas (actor) e o sistema (participant). Rotule mensagens e notas em português.
+  - Cubra os Fluxos Alternativos e Cenários de Erro relevantes no mesmo diagrama usando blocos alt/opt/break — ou, se ficarem complexos, em um segundo diagrama na subseção correspondente.
 # Critérios de Aceite
   - OBRIGATORIAMENTE no formato Gherkin, dentro de um bloco \`\`\`gherkin com Given/When/Then. Um cenário por critério.
 # Dependências
@@ -84,37 +87,46 @@ export async function generateSpec({ issueNumber }) {
   };
   const userContent = `Gere o spec.md a partir deste payload JSON:\n\n${JSON.stringify(payload, null, 2)}`;
 
-  console.log(`Gerando spec.md para: ${issue.title}`);
-  const { content, lintFindings } = await generateDocument(SYSTEM_PROMPT, userContent, {
-    action: 'spec',
-    lint: { lang: TARGET_LANGUAGE },
-    withReport: true,
-  });
-
-  mkdirSync(featureDir, { recursive: true });
-  writeFileSync(filePath, content, 'utf-8');
-
-  // Commit and push
-  const git = (cmd) => execSync(cmd, { stdio: 'inherit' });
-  git(`git config user.email "spec-wave[bot]@github.com"`);
-  git(`git config user.name "spec-wave[bot]"`);
-  git(`git add "${filePath}"`);
-  git(`git commit -m "docs: generate spec.md for ${slug} [spec-wave]"`);
-  git('git pull --rebase');
-  git('git push');
-
-  // Remove trigger label
-  await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:spec');
-
-  // Comment on issue
-  await commentOnIssue(
-    token, owner, repo, parseInt(issueNumber, 10),
-    `📋 **spec.md gerado automaticamente!**\n\n` +
-    `📄 Arquivo: [\`${filePath}\`](https://github.com/${owner}/${repo}/blob/main/${filePath})\n\n` +
-    `Revise a especificação e, quando estiver pronto, gere o plano técnico: mova o card para **📋 Plan** ou use:\n` +
-    `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:plan"\n\`\`\`` +
-    formatLintWarning(lintFindings)
-  );
-
-  console.log(`spec.md criado em: ${filePath}`);
+  // Coletor de uso de IA — o finally registra o custo já incorrido mesmo se o
+  // fluxo falhar depois da geração.
+  const usageEntries = [];
+  try {
+    console.log(`Gerando spec.md para: ${issue.title}`);
+    const { content, lintFindings } = await generateDocument(SYSTEM_PROMPT, userContent, {
+      action: 'spec',
+      lint: { lang: TARGET_LANGUAGE },
+      withReport: true,
+      usage: usageEntries,
+    });
+
+    mkdirSync(featureDir, { recursive: true });
+    writeFileSync(filePath, content, 'utf-8');
+
+    // Commit and push
+    const git = (cmd) => execSync(cmd, { stdio: 'inherit' });
+    git(`git config user.email "spec-wave[bot]@github.com"`);
+    git(`git config user.name "spec-wave[bot]"`);
+    git(`git add "${filePath}"`);
+    git(`git commit -m "docs: generate spec.md for ${slug} [spec-wave]"`);
+    git('git pull --rebase');
+    git('git push');
+
+    // Remove trigger label
+    await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:spec');
+
+    // Comment on issue
+    await commentOnIssue(
+      token, owner, repo, parseInt(issueNumber, 10),
+      `📋 **spec.md gerado automaticamente!**\n\n` +
+      `📄 Arquivo: [\`${filePath}\`](https://github.com/${owner}/${repo}/blob/main/${filePath})\n\n` +
+      `Revise a especificação e, quando estiver pronto, gere o plano técnico: mova o card para **📋 Plan** ou use:\n` +
+      `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:plan"\n\`\`\`` +
+      formatLintWarning(lintFindings)
+    );
+
+    console.log(`spec.md criado em: ${filePath}`);
+  } finally {
+    // Best-effort: nunca propaga erro (ver recordUsage).
+    await recordUsage({ token, owner, repo, issueNumber: parseInt(issueNumber, 10), entries: usageEntries });
+  }
 }

package/src/commands/info.mjs

@@ -3,20 +3,57 @@ import chalk from 'chalk';
 import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
 import { CONFIG_FILE, PORTAL_URL } from '../config.mjs';
+import { skillStatus } from './install-skill.mjs';
+
+// Resume o estado da skill para a saída JSON. `null` = não foi possível checar.
+function skillJson(status) {
+  if (!status) return null;
+  return {
+    agentsDetected: status.agentsDetected,
+    installNeeded: status.agentsDetected.length === 0 || status.pending.length > 0,
+    pending: status.pending,
+  };
+}
+
+// Reporta (saída humana) se o usuário precisa rodar o install-skill: nenhum
+// agente detectado → não dá para validar, sugere instalar; cópia ausente ou
+// de versão antiga → aponta o agente e o motivo.
+function reportSkill(status) {
+  if (!status) return;
+  if (status.agentsDetected.length === 0) {
+    p.log.warn(
+      'Nenhum agente de código detectado neste diretório — a skill spec-wave ' +
+      'não parece instalada. Rode `npx @spec-wave/cli install-skill`.'
+    );
+    return;
+  }
+  if (status.pending.length === 0) {
+    p.log.success(`Skill instalada e atualizada (${status.agentsDetected.join(', ')}).`);
+    return;
+  }
+  p.log.warn(
+    'Skill pendente de instalação/atualização:\n' +
+    status.pending.map(s => `  ${chalk.yellow('↻')} ${s.agent} (${s.reason}) — ${chalk.dim(s.path)}`).join('\n') +
+    '\nRode `npx @spec-wave/cli install-skill` (ou `npx @spec-wave/cli update`).'
+  );
+}
 
 // Lê o marcador .spec-wave.json do repositório atual (cwd) e reporta se o
 // spec-wave já foi inicializado. Usado pela skill para decidir entre mostrar
-// as informações ou oferecer rodar o `init`.
+// as informações ou oferecer rodar o `init`. Também valida se a skill instalada
+// nos agentes detectados está em dia com a versão empacotada na CLI.
 export async function info(options = {}) {
   const configPath = path.join(process.cwd(), CONFIG_FILE);
+  const skill = skillStatus();
 
   if (!existsSync(configPath)) {
     if (options.json) {
-      console.log(JSON.stringify({ initialized: false }));
+      console.log(JSON.stringify({ initialized: false, skill: skillJson(skill) }));
       return;
     }
     p.intro(chalk.bold('spec-wave info'));
     p.log.warn(`Este repositório ${chalk.bold('não foi inicializado')} (sem ${CONFIG_FILE}).`);
+    reportSkill(skill);
     p.log.info(`🌐 Acesse o Portal Web da ferramenta em ${chalk.cyan(PORTAL_URL)}`);
     p.outro('Execute `npx @spec-wave/cli init` para configurar.');
     return;
@@ -27,7 +64,7 @@ export async function info(options = {}) {
     config = JSON.parse(readFileSync(configPath, 'utf-8'));
   } catch (err) {
     if (options.json) {
-      console.log(JSON.stringify({ initialized: false, error: err.message }));
+      console.log(JSON.stringify({ initialized: false, error: err.message, skill: skillJson(skill) }));
       return;
     }
     p.log.error(`${CONFIG_FILE} existe mas está corrompido: ${err.message}`);
@@ -36,7 +73,7 @@ export async function info(options = {}) {
   }
 
   if (options.json) {
-    console.log(JSON.stringify({ initialized: true, ...config }));
+    console.log(JSON.stringify({ initialized: true, ...config, skill: skillJson(skill) }));
     return;
   }
 
@@ -51,6 +88,7 @@ export async function info(options = {}) {
     `${chalk.dim('Criado em:')}   ${config.initializedAt ?? '?'}`,
     'Configuração'
   );
+  reportSkill(skill);
   p.log.info(`🌐 Acesse o Portal Web da ferramenta em ${chalk.cyan(PORTAL_URL)}`);
   p.outro('Use `/spec-wave feature <descrição>` para criar uma Feature.');
 }

package/src/commands/install-skill.mjs

@@ -178,6 +178,46 @@ export function isDetected(target, baseDir) {
   return target.detect.some((sig) => existsSync(path.join(baseDir, sig)));
 }
 
+// Motivo pelo qual a cópia da skill em `dest` precisa ser (re)instalada:
+// 'ausente' | 'bloco ausente' | 'desatualizada' — ou null se está em dia com a
+// versão empacotada na CLI. Compartilhado entre `update` e `info`.
+export function skillCopyReason(dest, parsed) {
+  const desired = renderContent(dest.format, parsed, CLI_VERSION);
+  const existing = existsSync(dest.path) ? readFileSync(dest.path, 'utf-8') : null;
+  if (existing === null) return 'ausente';
+  if (dest.format === 'agents') {
+    const block = extractAgentsBlock(existing);
+    if (block === null) return 'bloco ausente';
+    return block.trim() !== desired.trim() ? 'desatualizada' : null;
+  }
+  return existing !== desired ? 'desatualizada' : null;
+}
+
+// Estado da skill para os agentes detectados em cwd (escopo projeto), com
+// fallback: uma cópia GLOBAL atualizada atende o agente mesmo sem cópia local.
+// Retorna null quando a fonte da skill não está no pacote (instalação parcial).
+export function skillStatus(cwd = process.cwd()) {
+  if (!existsSync(SKILL_SOURCE)) return null;
+  const parsed = parseSkill(readFileSync(SKILL_SOURCE, 'utf-8'));
+  const agentsDetected = [];
+  const pending = [];
+  for (const target of TARGETS) {
+    if (!isDetected(target, cwd)) continue;
+    agentsDetected.push(target.name);
+    const dest = resolveDest(target, cwd, false);
+    if (!dest) continue;
+    let reason = skillCopyReason(dest, parsed);
+    if (reason === 'ausente') {
+      const globalDest = resolveDest(target, homedir(), true);
+      if (globalDest && skillCopyReason(globalDest, parsed) === null) reason = null;
+    }
+    if (reason) {
+      pending.push({ agent: target.name, key: target.key, path: dest.path, reason });
+    }
+  }
+  return { agentsDetected, pending };
+}
+
 export async function installSkill(options = {}) {
   p.intro(chalk.bold('spec-wave install-skill'));
 

package/src/commands/update.mjs

@@ -12,7 +12,7 @@ import {
 } from '../api/github-rest.mjs';
 import {
   TARGETS, SKILL_SOURCE, CLI_VERSION, parseSkill, renderContent,
-  mergeAgentsFile, resolveDest, isDetected, extractAgentsBlock,
+  mergeAgentsFile, resolveDest, isDetected, skillCopyReason,
 } from './install-skill.mjs';
 
 const __dir = path.dirname(fileURLToPath(import.meta.url));
@@ -35,19 +35,10 @@ function detectSkill(parsed, baseDir, isGlobal) {
     if (!isDetected(target, baseDir)) continue;
     const dest = resolveDest(target, baseDir, isGlobal);
     if (!dest) continue;
-    const desired = renderContent(dest.format, parsed, CLI_VERSION);
-    const existing = existsSync(dest.path) ? readFileSync(dest.path, 'utf-8') : null;
-    let reason = null;
-    if (existing === null) {
-      reason = 'ausente';
-    } else if (dest.format === 'agents') {
-      const block = extractAgentsBlock(existing);
-      if (block === null) reason = 'bloco ausente';
-      else if (block.trim() !== desired.trim()) reason = 'desatualizada';
-    } else if (existing !== desired) {
-      reason = 'desatualizada';
+    const reason = skillCopyReason(dest, parsed);
+    if (reason) {
+      jobs.push({ target, dest, desired: renderContent(dest.format, parsed, CLI_VERSION), reason });
     }
-    if (reason) jobs.push({ target, dest, desired, reason });
   }
   return jobs;
 }

package/src/config.mjs

@@ -68,6 +68,7 @@ export const STATUS_OPTIONS = [
 //    atual. Ao avançar de etapa, o Status reinicia em "Todo".
 
 // Etapas (campo Etapa) referenciadas pelo fluxo de implementação.
+export const STAGE_READY = STATUS_OPTIONS.find(s => s.name.includes('Ready')).name;
 export const STAGE_DEVELOPMENT = STATUS_OPTIONS.find(s => s.name.includes('Desenvolvimento')).name;
 export const STAGE_CODE_REVIEW = STATUS_OPTIONS.find(s => s.name.includes('Code Review')).name;
 export const STAGE_DONE = STATUS_OPTIONS.find(s => s.name.includes('Done')).name;

package/src/lib/claude.mjs

@@ -3,6 +3,7 @@ import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
 import { CONFIG_FILE, getProvider, DEFAULT_PROVIDER } from '../config.mjs';
 import { lintLanguage } from './output-lint.mjs';
+import { computeCost } from './usage-report.mjs';
 
 /**
  * Resolve provider/modelo de IA (função PURA — testável sem process.env nem fs).
@@ -16,7 +17,7 @@ import { lintLanguage } from './output-lint.mjs';
  * @param {object} [params.env] objeto tipo process.env
  * @param {object} [params.fileAi] bloco `ai` do .spec-wave.json
  * @param {string} [params.action] ação de IA (ver AI_ACTIONS em config.mjs)
- * @returns {{ provider: string, model: string, secret: string }}
+ * @returns {{ provider: string, model: string, secret: string, pricing: object|null }}
  */
 export function resolveAiConfig({ env = {}, fileAi = {}, action } = {}) {
   const provider = (env.SPEC_WAVE_PROVIDER || fileAi.provider || DEFAULT_PROVIDER).toLowerCase();
@@ -25,7 +26,10 @@ export function resolveAiConfig({ env = {}, fileAi = {}, action } = {}) {
     || (action && fileAi.models?.[action])
     || fileAi.model
     || meta.defaultModel;
-  return { provider: meta.value, model, secret: meta.secret };
+  // pricing: tabela `ai.pricing` do .spec-wave.json ({ [model]: { input,
+  // output } } em USD/1M tokens) — usada para estimar custo quando o provider
+  // não devolve o valor (Anthropic).
+  return { provider: meta.value, model, secret: meta.secret, pricing: fileAi.pricing || null };
 }
 
 // Resolve o provider/modelo de IA a partir do .spec-wave.json (gravado pelo init
@@ -55,7 +59,10 @@ function resolveAi(action) {
 //    RE-GERA uma única vez com instrução de idioma reforçada; se reprovar de
 //    novo, segue com o conteúdo e reporta os findings;
 //  • withReport: true → retorna { content, lintFindings, retried } em vez da
-//    string (o retorno string é mantido para os chamadores existentes).
+//    string (o retorno string é mantido para os chamadores existentes);
+//  • usage: array coletor — recebe push de UMA entrada { at, action, provider,
+//    model, inputTokens, outputTokens, cost } por invocação (o retry de lint
+//    soma tokens/custo na MESMA entrada).
 export async function generateDocument(systemPrompt, userContent, opts = {}) {
   const ai = resolveAi(opts.action);
   const temperature = opts.temperature ?? 0.2;
@@ -64,11 +71,19 @@ export async function generateDocument(systemPrompt, userContent, opts = {}) {
   const maxTokens = opts.maxTokens ?? 8192;
   console.log(`Provider de IA: ${ai.provider} · modelo: ${ai.model} · temperature: ${temperature} · max_tokens: ${maxTokens}`);
 
+  // Acumuladores de uso desta invocação (1 ou 2 chamadas, com o retry de lint).
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cost = null; // soma dos custos conhecidos; se todos null → null
+
   const generate = async (system) => {
-    const raw = ai.provider === 'openrouter'
+    const { text, usage } = ai.provider === 'openrouter'
       ? await generateWithOpenRouter(system, userContent, ai, temperature, maxTokens)
       : await generateWithAnthropic(system, userContent, ai, temperature, maxTokens);
-    return stripOuterFence(raw);
+    inputTokens += usage.inputTokens;
+    outputTokens += usage.outputTokens;
+    if (typeof usage.cost === 'number') cost = (cost ?? 0) + usage.cost;
+    return stripOuterFence(text);
   };
 
   let content = await generate(systemPrompt);
@@ -97,6 +112,23 @@ export async function generateDocument(systemPrompt, userContent, opts = {}) {
     }
   }
 
+  // Telemetria: uma entrada por invocação no coletor passado pelo chamador.
+  // A Anthropic não devolve custo — estima via tabela ai.pricing, se houver.
+  if (Array.isArray(opts.usage)) {
+    if (cost === null && ai.provider === 'anthropic') {
+      cost = computeCost({ model: ai.model, inputTokens, outputTokens, pricing: ai.pricing });
+    }
+    opts.usage.push({
+      at: new Date().toISOString(),
+      action: opts.action || 'unknown',
+      provider: ai.provider,
+      model: ai.model,
+      inputTokens,
+      outputTokens,
+      cost,
+    });
+  }
+
   return opts.withReport ? { content, lintFindings, retried } : content;
 }
 
@@ -116,6 +148,37 @@ function stripOuterFence(text) {
   return m ? m[1].trim() : t;
 }
 
+/**
+ * Normaliza o bloco `usage` da API da Anthropic (função PURA — testável).
+ * A Anthropic não informa custo em USD → cost sempre null (estimado depois
+ * via computeCost, se houver tabela de preços).
+ *
+ * @param {object} [usage] `message.usage` da resposta ({ input_tokens, output_tokens })
+ * @returns {{ inputTokens: number, outputTokens: number, cost: null }}
+ */
+export function extractAnthropicUsage(usage) {
+  return {
+    inputTokens: usage?.input_tokens ?? 0,
+    outputTokens: usage?.output_tokens ?? 0,
+    cost: null,
+  };
+}
+
+/**
+ * Normaliza o bloco `usage` da API do OpenRouter (função PURA — testável).
+ * Com `usage: { include: true }` no request, o OpenRouter devolve `cost` em USD.
+ *
+ * @param {object} [usage] `data.usage` da resposta ({ prompt_tokens, completion_tokens, cost })
+ * @returns {{ inputTokens: number, outputTokens: number, cost: number|null }}
+ */
+export function extractOpenRouterUsage(usage) {
+  return {
+    inputTokens: usage?.prompt_tokens ?? 0,
+    outputTokens: usage?.completion_tokens ?? 0,
+    cost: typeof usage?.cost === 'number' ? usage.cost : null,
+  };
+}
+
 async function generateWithAnthropic(systemPrompt, userContent, ai, temperature, maxTokens) {
   const apiKey = process.env.ANTHROPIC_API_KEY;
   if (!apiKey) {
@@ -134,7 +197,7 @@ async function generateWithAnthropic(systemPrompt, userContent, ai, temperature,
     system: systemPrompt,
   });
 
-  return message.content[0].text;
+  return { text: message.content[0].text, usage: extractAnthropicUsage(message.usage) };
 }
 
 async function generateWithOpenRouter(systemPrompt, userContent, ai, temperature, maxTokens) {
@@ -162,6 +225,8 @@ async function generateWithOpenRouter(systemPrompt, userContent, ai, temperature
         { role: 'system', content: systemPrompt },
         { role: 'user', content: userContent },
       ],
+      // Pede o bloco `usage` completo na resposta (inclui `cost` em USD).
+      usage: { include: true },
     }),
   });
 
@@ -175,5 +240,5 @@ async function generateWithOpenRouter(systemPrompt, userContent, ai, temperature
   if (!content) {
     throw new Error(`OpenRouter retornou resposta vazia: ${JSON.stringify(data)}`);
   }
-  return content;
+  return { text: content, usage: extractOpenRouterUsage(data.usage) };
 }

package/src/lib/critique.mjs

@@ -137,9 +137,10 @@ function renderMarkdown(findings) {
  * @param {string} [params.plan] conteúdo do plan.md
  * @param {string} [params.techContextYaml] tech_context serializado em YAML
  * @param {object[]} [params.stories] stories propostas (antes da criação)
+ * @param {object[]} [params.usage] coletor de uso de IA (repassado ao generateDocument)
  * @returns {Promise<{ grave: boolean, findings: Array<{ severity: string, text: string }>, markdown: string }>}
  */
-export async function runCritique({ kind, spec, plan, techContextYaml, stories } = {}) {
+export async function runCritique({ kind, spec, plan, techContextYaml, stories, usage } = {}) {
   const sections = [];
   if (spec) sections.push(`## spec.md\n\n${spec}`);
   if (plan) sections.push(`## plan.md\n\n${plan}`);
@@ -151,6 +152,7 @@ export async function runCritique({ kind, spec, plan, techContextYaml, stories }
     action: 'critique',
     temperature: 0,
     maxTokens: 4096,
+    usage,
   });
 
   const { grave, findings } = parseCritiqueResponse(raw);

package/src/lib/usage-report.mjs

@@ -0,0 +1,167 @@
+// Telemetria de uso de IA (tokens/custo por chamada) → comentário único
+// acumulado na issue da Feature.
+//
+// Cada invocação de generateDocument gera UMA entrada { at, action, provider,
+// model, inputTokens, outputTokens, cost }. O recordUsage acumula as entradas
+// num comentário markdown identificado pelo USAGE_MARKER: parse do comentário
+// existente → concat com as novas → re-render → update (ou create).
+//
+// Contrato: registrar uso NUNCA derruba o fluxo principal — recordUsage é
+// best-effort e engole qualquer erro com um console.warn.
+
+import { listIssueComments, updateComment, commentOnIssue } from '../api/github-rest.mjs';
+
+// Marcador HTML invisível que identifica o comentário de uso na issue.
+export const USAGE_MARKER = '<!-- spec-wave:usage -->';
+
+// Teto de linhas de dados na tabela — ao exceder, descarta as mais antigas
+// (o comentário não pode crescer sem limite em Features longevas).
+const MAX_ROWS = 100;
+
+/**
+ * Calcula o custo em USD a partir da tabela de preços (função PURA — testável).
+ *
+ * `pricing` vem do bloco `ai.pricing` do .spec-wave.json, no formato
+ * `{ [model]: { input, output } }` em USD por 1M de tokens. Sem pricing ou sem
+ * o modelo na tabela → null (custo desconhecido, nunca chuta).
+ *
+ * @param {object} params
+ * @param {string} params.model modelo usado na chamada
+ * @param {number} params.inputTokens tokens de entrada
+ * @param {number} params.outputTokens tokens de saída
+ * @param {object|null} [params.pricing] tabela de preços por modelo
+ * @returns {number|null} custo em USD, ou null se desconhecido
+ */
+export function computeCost({ model, inputTokens, outputTokens, pricing } = {}) {
+  const price = pricing?.[model];
+  if (!price || typeof price.input !== 'number' || typeof price.output !== 'number') {
+    return null;
+  }
+  return ((inputTokens || 0) * price.input + (outputTokens || 0) * price.output) / 1_000_000;
+}
+
+// ISO timestamp → "YYYY-MM-DD HH:mm" em UTC (formato da coluna Data).
+function formatAt(at) {
+  const date = new Date(at);
+  if (Number.isNaN(date.getTime())) return String(at || '');
+  return date.toISOString().slice(0, 16).replace('T', ' ');
+}
+
+// Custo → "$X.XXXX"; null (desconhecido) → travessão.
+function formatCost(cost) {
+  return typeof cost === 'number' ? `$${cost.toFixed(4)}` : '—';
+}
+
+/**
+ * Interpreta o comentário de uso de volta para entries (função PURA — round-trip
+ * do renderUsageComment). Linhas de header, separador e Total são ignoradas.
+ * `at` é reconstruído como `YYYY-MM-DDTHH:mm:00.000Z` (segundos zerados).
+ *
+ * @param {string} body corpo do comentário
+ * @returns {Array<object>|null} entries, ou null se sem marcador ou tabela irreconhecível
+ */
+export function parseUsageComment(body) {
+  const text = body || '';
+  if (!text.includes(USAGE_MARKER)) return null;
+
+  const entries = [];
+  let sawHeader = false;
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    const cells = trimmed.split('|').slice(1, -1).map(c => c.trim());
+    if (cells.length !== 6) continue;
+    if (cells[0] === 'Data (UTC)') { sawHeader = true; continue; } // header
+    if (/^:?-{3,}:?$/.test(cells[0])) continue;                    // separador
+    if (cells[0].includes('Total')) continue;                      // linha Total
+
+    const dateMatch = cells[0].match(/^(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2})$/);
+    const inputTokens = Number.parseInt(cells[3], 10);
+    const outputTokens = Number.parseInt(cells[4], 10);
+    if (!dateMatch || Number.isNaN(inputTokens) || Number.isNaN(outputTokens)) continue;
+
+    const costMatch = cells[5].match(/^\$(\d+(?:\.\d+)?)$/);
+    entries.push({
+      at: `${dateMatch[1]}T${dateMatch[2]}:00.000Z`,
+      action: cells[1],
+      model: cells[2],
+      inputTokens,
+      outputTokens,
+      cost: costMatch ? Number.parseFloat(costMatch[1]) : null,
+    });
+  }
+
+  // Marcador presente mas tabela irreconhecível (sem header ou sem nenhuma
+  // linha de dados válida) → null: o chamador recomeça só com as novas entradas.
+  if (!sawHeader || entries.length === 0) return null;
+  return entries;
+}
+
+/**
+ * Renderiza as entries como comentário markdown (função PURA — testável).
+ *
+ * Cap de MAX_ROWS linhas de dados (descarta as mais antigas). A linha Total
+ * soma os tokens de todas as linhas exibidas e só os custos conhecidos —
+ * custos indisponíveis (—) ficam fora do total.
+ *
+ * @param {Array<object>} entries entradas de uso
+ * @returns {string} corpo markdown do comentário
+ */
+export function renderUsageComment(entries) {
+  const rows = (entries || []).slice(-MAX_ROWS);
+
+  const totalIn = rows.reduce((sum, e) => sum + (e.inputTokens || 0), 0);
+  const totalOut = rows.reduce((sum, e) => sum + (e.outputTokens || 0), 0);
+  const known = rows.filter(e => typeof e.cost === 'number');
+  const totalCost = known.length > 0
+    ? formatCost(known.reduce((sum, e) => sum + e.cost, 0))
+    : '—';
+
+  return [
+    USAGE_MARKER,
+    '📊 **Uso de IA (spec-wave)**',
+    '',
+    '| Data (UTC) | Ação | Modelo | Tokens in | Tokens out | Custo (USD) |',
+    '| --- | --- | --- | ---: | ---: | ---: |',
+    ...rows.map(e =>
+      `| ${formatAt(e.at)} | ${e.action} | ${e.model} | ${e.inputTokens} | ${e.outputTokens} | ${formatCost(e.cost)} |`
+    ),
+    `| **Total** | | | **${totalIn}** | **${totalOut}** | **${totalCost}** |`,
+    '',
+    '_Custos indisponíveis (—) não entram no total. Atualizado automaticamente pelo spec-wave._',
+  ].join('\n');
+}
+
+/**
+ * Registra as entries no comentário de uso da issue (impura, best-effort).
+ *
+ * Acha o comentário com USAGE_MARKER, faz parse das entradas antigas, concatena
+ * as novas e atualiza (ou cria, se não existir). Qualquer erro vira só um
+ * console.warn — telemetria nunca derruba o fluxo principal.
+ *
+ * @param {object} params
+ * @param {string} params.token token do GitHub
+ * @param {string} params.owner dono do repo
+ * @param {string} params.repo nome do repo
+ * @param {number} params.issueNumber número da issue
+ * @param {Array<object>} params.entries novas entradas de uso
+ */
+export async function recordUsage({ token, owner, repo, issueNumber, entries } = {}) {
+  if (!Array.isArray(entries) || entries.length === 0) return;
+  try {
+    const comments = await listIssueComments(token, owner, repo, issueNumber);
+    const existing = comments.find(c => (c.body || '').includes(USAGE_MARKER));
+
+    // Comentário antigo irreconhecível → recomeça só com as novas entradas.
+    const previous = existing ? parseUsageComment(existing.body) : null;
+    const body = renderUsageComment([...(previous || []), ...entries]);
+
+    if (existing?.id) {
+      await updateComment(token, owner, repo, existing.id, body);
+    } else {
+      await commentOnIssue(token, owner, repo, issueNumber, body);
+    }
+  } catch (err) {
+    console.warn('Não foi possível registrar uso de IA:', err.message);
+  }
+}

package/src/templates/skill/SKILL.md

@@ -137,7 +137,9 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 ### `@spec-wave/cli info` — status de configuração do repo atual
 | Flag | Tipo | Descrição |
 |------|------|-----------|
-| `--json` | flag | Saída JSON (`{"initialized":bool, ...}`) para parsing programático. |
+| `--json` | flag | Saída JSON (`{"initialized":bool, ..., "skill":{...}}`) para parsing programático. |
+
+> Além do `.spec-wave.json`, valida a **skill instalada**: para cada agente detectado no diretório, compara a cópia instalada com a versão empacotada na CLI (uma cópia **global** atualizada também conta). No JSON, o campo `skill` traz `{agentsDetected, installNeeded, pending:[{agent, reason, path}]}` — `installNeeded: true` significa que o usuário precisa rodar `install-skill` (ou `update`).
 
 ### `@spec-wave/cli refresh` — atualiza o `.spec-wave.json` local
 | Flag | Tipo | Descrição |
@@ -177,7 +179,7 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 > Diferente dos quatro acima, `implement` roda **localmente** (lê `.spec-wave.json`, como `issue`), não por Action. Detecta o tipo da issue: **Story** → coleta todas as Tasks (sub-issues) e aciona o spec-kit uma única vez; **Task** → só aquela task. Monta o contexto em `.spec-wave/implement-<n>.md` e chama o comando configurado em `specKit.command` (no `.spec-wave.json`) ou na env `SPEC_WAVE_IMPLEMENT_CMD`. Placeholders disponíveis no template: `{tasksFile} {specFile} {planFile} {issue} {type} {title}`. Se nada estiver configurado, ele apenas monta o contexto e mostra como configurar (não executa). O contexto inclui os **comentários da issue**, um **digest do código recente** e um **aviso de dependências pendentes** quando a issue depende (linha `Depende de: #N` ou relação nativa *blocked by*) de outra que ainda não foi concluída — nesse caso, confirme com o usuário antes de seguir. Inclui também instruções para o agente implementar as Tasks **sequencialmente, uma por vez** (nunca duas com Status "In Progress" ao mesmo tempo): cada Task usa o **Status** (In Progress) *dentro* da Etapa 🚧 Desenvolvimento e, **ao concluir, avança para a Etapa 🎉 Done com Status Done**. **Ao concluir toda a Story**: fazer o commit, abrir o PR e **avançar a Etapa da Story para 👀 Code Review** (Status → Todo) — as Tasks já estão em 🎉 Done. A **Feature só avança** para Code Review quando **TODAS as suas Stories** já estiverem em Code Review — enquanto houver Story pendente, a Feature fica em 🚧 Desenvolvimento. Etapa só avança (nunca volta); Status mede o progresso dentro da etapa.
 
 ### `@spec-wave/cli doctor` — preflight de auth e configuração (comando LOCAL)
-Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub (e a fonte dele), escopos (`repo`, `project`, `workflow` — com degradação para checks funcionais em fine-grained PATs), conta ativa do `gh` vs. owner, `.spec-wave.json` (campos e sincronia com o Project real), acesso ao repositório, configuração de IA (provider/modelo/`ai.models` + secrets do Actions) e presença dos workflows.
+Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub (e a fonte dele), escopos (`repo`, `project`, `workflow` — com degradação para checks funcionais em fine-grained PATs), conta ativa do `gh` vs. owner, `.spec-wave.json` (campos e sincronia com o Project real), acesso ao repositório, configuração de IA (provider/modelo/`ai.models` + secrets do Actions), **spec-kit** (`specKit.command` / env `SPEC_WAVE_IMPLEMENT_CMD` — se ausente, avisa e sugere exemplos por agente: Claude Code, opencode, Codex, Copilot CLI, Kiro CLI, Qwen Code) e presença dos workflows.
 
 > Saída: `✓` ok, `✗` problema confirmado, `!` não verificável (best-effort — falha de rede nunca derruba o doctor). **Exit 1** se houver algum `✗`. **Quando rodar:** no início de uma sessão de trabalho, ou sempre que aparecer um erro estranho (ex.: **404 ao criar issues** — causa típica: token sem acesso ao repo/org, que o doctor aponta). É o primeiro passo de troubleshooting — prefira-o a depurar `gh api` na mão.
 
@@ -263,6 +265,7 @@ Mostra se o repositório atual já foi configurado com o spec-wave.
 3. **Se NÃO estiver inicializado**, pergunte ao usuário: "Este repositório ainda não foi configurado com o spec-wave. Quer rodar o `init` agora?"
    - Se sim → siga o fluxo de `/spec-wave setup`.
    - Se não → encerre sem alterar nada.
+4. **Se a saída indicar skill pendente** (aviso "Skill pendente de instalação/atualização" ou, no `--json`, `skill.installNeeded: true`), pergunte ao usuário se quer instalar/atualizar agora: skill `ausente` → `npx @spec-wave/cli install-skill`; skill `desatualizada` → `npx @spec-wave/cli update` (atualiza tudo que ficou para trás). Lembre-o de recarregar o agente depois.
 
 ---
 
@@ -470,7 +473,7 @@ Para qualquer outro tipo (Spike, Bug, Story, Task, …) o Action **recusa** e co
    gh issue edit <número> --add-label "spec-wave:decompose"
    ```
 3. Informe: "Decomposição iniciada — Feature gera Stories+Tasks; RFC gera Tasks."
-4. Após a conclusão, as issues filhas aparecerão como comentário na issue pai, junto com o comentário 🔎 da crítica adversarial. As Stories geradas trazem a linha `Depende de: #N` (+ relação *blocked by*) — use `npx @spec-wave/cli order <número>` para ver a ordem de execução.
+4. Após a conclusão, as issues filhas aparecerão como comentário na issue pai, junto com o comentário 🔎 da crítica adversarial. A issue pai e as Stories/Tasks criadas entram no board na Etapa **✅ Ready** (Status Todo; a Etapa nunca retrocede — itens já adiante não são tocados). As Stories geradas trazem a linha `Depende de: #N` (+ relação *blocked by*) — use `npx @spec-wave/cli order <número>` para ver a ordem de execução.
 5. A issue recebe a label `spec-wave:decomposed` (guard de idempotência): rodar de novo **não** duplica as issues. Para forçar um re-decompose, siga a seção *Guard de idempotência*.
 
 ---