@spec-wave/cli 0.32.0 → 0.34.0

package/package.json

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

package/src/api/github-graphql.mjs

@@ -528,3 +528,31 @@ export async function linkProjectToRepo(token, projectId, repositoryId) {
     }
   `, { projectId, repositoryId });
 }
+
+/**
+ * Cota do GraphQL restante (item 5 do rfc/plano-hardening-agentes-2026-08.md).
+ *
+ * `rateLimit` é o único campo da API que consultar **não custa pontos** — é
+ * assim que o `doctor` consegue medir ANTES de gastar, em vez de descobrir o
+ * esgotamento no meio de uma varredura de sub-issues.
+ *
+ * @returns {Promise<{limit:number, remaining:number, resetAt:string}|null>}
+ *          null em qualquer falha (rede, token sem escopo) — best-effort.
+ */
+export async function getRateLimit(token) {
+  const client = makeClient(token);
+  try {
+    const result = await client(`
+      query RateLimit {
+        rateLimit {
+          limit
+          remaining
+          resetAt
+        }
+      }
+    `);
+    return result.rateLimit || null;
+  } catch {
+    return null;
+  }
+}

package/src/api/github-rest.mjs

@@ -359,6 +359,19 @@ export async function deleteLabel(token, owner, repo, name) {
   }
 }
 
+// Quantas issues ABERTAS têm uma label — usado pelo `update` para não apagar
+// uma label `spec-wave:*` órfã que ainda está em uso (item 7 do
+// rfc/plano-hardening-agentes-2026-08.md): apagar uma label no GitHub a
+// remove de TODA issue que a tem, o que é irreversível. PRs entram na mesma
+// listagem de issues da API REST — filtrados fora, não são o que se quer contar.
+export async function countOpenIssuesWithLabel(token, owner, repo, labelName) {
+  const octokit = makeOctokit(token);
+  const issues = await octokit.paginate('GET /repos/{owner}/{repo}/issues', {
+    owner, repo, labels: labelName, state: 'open', per_page: 100,
+  });
+  return issues.filter(i => !i.pull_request).length;
+}
+
 /**
  * Apaga a ref de uma branch.
  *
@@ -515,6 +528,17 @@ export async function getPR(token, owner, repo, prNumber) {
   return res.data;
 }
 
+// Mensagens de commit (assunto + corpo) de um PR — usado por `--verify-commits`
+// (implement) e pela conferência do `merge` para ler os git trailer de
+// Story/Task sem precisar de checkout local (lib/commit-trailers.mjs).
+export async function listPullRequestCommitMessages(token, owner, repo, prNumber) {
+  const octokit = makeOctokit(token);
+  const commits = await octokit.paginate(octokit.rest.pulls.listCommits, {
+    owner, repo, pull_number: prNumber, per_page: 100,
+  });
+  return commits.map(c => c.commit.message);
+}
+
 // `ref` é opcional (compatível com os chamadores de 4 argumentos): o modo PR do
 // `update` precisa ler o .spec-wave.json na BASE, não no que a API escolher.
 export async function getFileContent(token, owner, repo, path, ref) {

package/src/cli.mjs

@@ -213,6 +213,7 @@ export function buildProgram() {
     .option('--no-skill-in-pr', 'Força manter a skill dos agentes fora do Pull Request')
     .option('--dry-run', 'Mostra o que seria atualizado sem alterar nada')
     .option('--yes', 'Aplica sem pedir confirmação')
+    .option('--force-labels', 'Remove labels spec-wave:* órfãs mesmo com issues abertas usando-as (padrão: mantém)')
     .action(async (options) => {
       const { update } = await import('./commands/update.mjs');
       await update(options).catch(err => { console.error(err.message); process.exit(1); });
@@ -423,6 +424,7 @@ Docs: https://astratech-net-br.github.io/spec-wave-cli/guia/qa/`);
     .option('--feature-dir <path>', 'Caminho do docs/features/<slug> (sobrescreve a resolução automática)')
     .option('--dry-run', 'Monta o contexto e imprime o comando sem executar o spec-kit')
     .option('--refresh', 'Ignora o cache local (sub-issues/dependências) e reconsulta a API')
+    .option('--verify-commits', 'Confere se os commits recentes trazem o trailer Spec-Wave-Story/Tasks (best-effort, nunca bloqueia)')
     .action(async (issue, options) => {
       const { implement } = await import('./commands/implement.mjs');
       await implement({ issue, ...options }).catch(err => { console.error(err.message); process.exit(1); });
@@ -521,6 +523,7 @@ para incluí-lo na consulta, ou --sync para gravá-lo em definitivo nos artefato
     .option('--dry-run', 'Mostra o que seria instalado sem gravar')
     .option('--force', 'Reinstala o binário e regrava a config')
     .option('--yes', 'Modo não-interativo')
+    .option('--queue <nome>', 'No --install/--build: fila deste daemon (padrão: dev-agent). Para uma trilha extra, declare-a em devAgent.queues do .spec-wave.json antes — senão update/doctor não reconhecem a label')
     .action(async (options) => {
       const { devAgent } = await import('./commands/dev-agent.mjs');
       await devAgent(options).catch(err => { console.error(err.message); process.exit(1); });
@@ -529,9 +532,10 @@ para incluí-lo na consulta, ou --sync para gravá-lo em definitivo nos artefato
   program
     .command('doctor')
     .description('Diagnostica a configuração do spec-wave no repositório atual')
-    .action(async () => {
+    .option('--deep', 'Confere também as Tasks de cada decomposição aplicada (1 chamada GraphQL a mais por Story; padrão: só Stories)')
+    .action(async (options) => {
       const { doctor } = await import('./commands/doctor.mjs');
-      await doctor().catch(err => { console.error(err.message); process.exit(1); });
+      await doctor(options).catch(err => { console.error(err.message); process.exit(1); });
     });
 
   // O mapa por tema no fim do --help: 29 comandos em lista plana dizem O QUE

package/src/commands/audit.mjs

@@ -144,7 +144,11 @@ export async function audit({ milestone: milestoneArg, critique = false, json =
   for (const issue of targetIssues) {
     if (detectIssueType(issue) !== 'Feature' || issue.state === 'closed') continue;
     const docs = featureDocPaths(root, issue, 'Feature');
-    const { content } = await loadArtifact({
+    // `state` distingue "não existe" ('missing') de "não deu para verificar
+    // agora" ('unknown' — rede/permissão) — item 8 do rfc/plano-hardening-
+    // agentes-2026-08.md: descartar isso é a mesma lacuna que o preflight já
+    // corrigiu (PRs #65/#66) e que este comando herdou sem herdar a distinção.
+    const { content, state } = await loadArtifact({
       token, owner, repo, root, base,
       pathRel: docs.spec.rel, doc: 'spec', issueNumber: issue.number,
     });
@@ -154,6 +158,7 @@ export async function audit({ milestone: milestoneArg, critique = false, json =
       slug: slugify(issue.title),
       milestone: { number: milestone.number, title: milestone.title, due_on: milestone.due_on ?? null },
       spec: content,
+      specState: state,
     });
   }
 
@@ -257,7 +262,11 @@ export async function audit({ milestone: milestoneArg, critique = false, json =
     return saida;
   }
 
+  // 'sem-alvo' ganha marca própria: sem ela, `dependsOn: []` fica idêntico ao
+  // de uma Feature 'vazia' (que diz "Nenhuma" de propósito) — item 3a do rfc/
+  // plano-hardening-agentes-2026-08.md.
   const grafoLinhas = resultado.grafo.map(g => {
+    if (g.secao === 'sem-alvo') return `  #${g.number} ⟨sem arestas legíveis⟩`;
     const deps = g.dependsOn.length ? ` ← depende de ${g.dependsOn.map(d => `#${d}`).join(', ')}` : '';
     return `  #${g.number}${deps}`;
   });

package/src/commands/dev-agent.mjs

@@ -76,13 +76,21 @@ function render(template, vars) {
 
 /**
  * config.toml do agente a partir do .spec-wave.json. Nunca escreve token.
+ *
+ * `queue` é o SUFIXO da trilha (sem `spec-wave:`) — `dev-agent` (default) ou
+ * uma trilha extra (`dev-agent-b`, `dev-agent-c`, …) para rodar mais de um
+ * daemon em paralelo. A label correspondente só é criada/preservada pelo
+ * `update`/`doctor` se estiver declarada em `devAgent.queues` do
+ * `.spec-wave.json` — ver `queueLabels` em `config.mjs` e o item 7 do
+ * rfc/plano-hardening-agentes-2026-08.md.
  */
-export function renderAgentConfig({ owner, repo }) {
+export function renderAgentConfig({ owner, repo, queue = 'dev-agent' }) {
+  const queueLabel = queue === 'dev-agent' ? LABEL_DEV_AGENT : `spec-wave:${queue}`;
   return `# spec-wave-agent — gerado por \`spec-wave dev-agent --install\`
 # Schema completo: https://github.com/${AGENT_REPO}#configuração
 
 repo = "${owner}/${repo}"
-queue_label = "${LABEL_DEV_AGENT}"
+queue_label = "${queueLabel}"
 
 # Defaults do agente (descomente para ajustar):
 #poll_interval_secs = 60       # consulta à fila quando ocioso
@@ -362,6 +370,14 @@ async function install(options) {
 
 /** Config + serviço + avisos finais — comum a --install e --build. */
 async function finishSetup({ cfg, home, binPath, configPath, options, configAction, servicePath }) {
+  const queue = options.queue || 'dev-agent';
+  if (queue !== 'dev-agent' && !(cfg.devAgent?.queues || []).includes(queue)) {
+    p.log.warn(
+      `Fila "${queue}" não está em devAgent.queues no ${CONFIG_FILE} deste repo — ` +
+      `\`spec-wave update\`/\`doctor\` não vão reconhecer a label spec-wave:${queue} e um ` +
+      'update de rotina pode removê-la, esvaziando esta trilha. Adicione-a e rode `spec-wave update` antes.'
+    );
+  }
   if (configAction === 'manter') {
     p.log.info(`Config mantida: ${configPath} já existe (use --force para regerar).`);
   } else if (existsSync(configPath) && !options.yes) {
@@ -370,12 +386,12 @@ async function finishSetup({ cfg, home, binPath, configPath, options, configActi
       p.log.info('Config mantida.');
     } else {
       mkdirSync(path.dirname(configPath), { recursive: true });
-      writeFileSync(configPath, renderAgentConfig(cfg), 'utf-8');
+      writeFileSync(configPath, renderAgentConfig({ ...cfg, queue: options.queue || 'dev-agent' }), 'utf-8');
       p.log.success(`Config regravada em ${configPath}.`);
     }
   } else {
     mkdirSync(path.dirname(configPath), { recursive: true });
-    writeFileSync(configPath, renderAgentConfig(cfg), 'utf-8');
+    writeFileSync(configPath, renderAgentConfig({ ...cfg, queue: options.queue || 'dev-agent' }), 'utf-8');
     p.log.success(`Config criada em ${chalk.cyan(configPath)} (repo ${cfg.owner}/${cfg.repo}).`);
   }
 

package/src/commands/doctor.mjs

@@ -14,16 +14,20 @@ import {
   resolveToken, verifyTokenScopes, describeTokenSource, activeGhAccount,
   tokenMismatchWarning, parseActiveAccount,
 } from '../api/auth.mjs';
-import { getProjectSnapshot, listSubIssues, listProjectItems } from '../api/github-graphql.mjs';
+import { getProjectSnapshot, listProjectItems, getRateLimit } from '../api/github-graphql.mjs';
 import { getRepoVariable } from '../api/github-rest.mjs';
 import {
   CONFIG_FILE, WORKFLOW_FILES, ARTIFACT_WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER,
   AI_PROVIDERS, STATUS_OPTIONS,
   RETIRED_STAGES, ALL_LABELS, allLabelsFor, LABEL_NEEDS_HUMAN, LABEL_QA_READY, MODEL_LABEL_PREFIX,
+  DEV_AGENT_QUEUE_PREFIX,
   DEFAULT_MAX_CRITIQUE_ATTEMPTS, STAGE_TRACKS, AI_ACTIONS, recommendedModelAliases,
   modelLabels, STAGE_QA,
 } from '../config.mjs';
 import { slugify } from '../lib/slugify.mjs';
+import { cachedSubIssues } from '../lib/story-graph.mjs';
+import { affordCheck } from '../lib/rate-budget.mjs';
+import { resolveCacheTtl } from '../lib/net-cache.mjs';
 import { QA_PLAN_FILE } from '../lib/qa-plan-doc.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
 import { configuredMode, describeModeState, EXECUTION_VARIABLE } from '../lib/execution-mode.mjs';
@@ -98,6 +102,31 @@ async function checkToken(ctx) {
   }
 }
 
+// Item 5 do rfc/plano-hardening-agentes-2026-08.md: medir a cota ANTES de
+// gastar. `rateLimit` não custa pontos, então isto é de graça — e é o que
+// falta para o doctor explicar "pulei este check por causa da cota" em vez de
+// piorar um esgotamento em silêncio (seis "!" sem dizer a causa comum).
+// Guardada em `ctx.rateLimit` para os checks caros consultarem depois.
+async function checkRateLimit(ctx) {
+  const name = 'Cota da API (GraphQL)';
+  if (!ctx.token) {
+    return { name, status: 'warn', detail: 'Sem token — cota não verificável.' };
+  }
+  ctx.rateLimit = await getRateLimit(ctx.token);
+  if (!ctx.rateLimit) {
+    return { name, status: 'warn', detail: 'Não foi possível consultar a cota agora.' };
+  }
+  const { remaining, limit, resetAt } = ctx.rateLimit;
+  const reset = new Date(resetAt).toLocaleTimeString('pt-BR');
+  const status = remaining < 500 ? 'warn' : 'ok';
+  return {
+    name,
+    status,
+    detail: `${remaining}/${limit} pontos restantes (reset ${reset}).` +
+      (status === 'warn' ? ' Cota baixa — checks caros do doctor podem ser pulados; veja as notas deles.' : ''),
+  };
+}
+
 async function checkScopes(ctx) {
   const name = 'Escopos do token';
   if (!ctx.token) {
@@ -355,7 +384,9 @@ export function suggestModelAliases({ provider = undefined, aliases = null } = {
   return { missing, snippet: `"modelAliases": ${JSON.stringify(merged, null, 2)}` };
 }
 
-export function inspectBoardHygiene({ boardStages = null, repoLabels = null, modelAliases = null } = {}) {
+export function inspectBoardHygiene({
+  boardStages = null, repoLabels = null, modelAliases = null, devAgentQueues = null,
+} = {}) {
   const canonical = STATUS_OPTIONS.map(s => s.name);
   const known = new Set(canonical);
   const retired = new Map(RETIRED_STAGES.map(s => [s.name, s]));
@@ -377,11 +408,21 @@ export function inspectBoardHygiene({ boardStages = null, repoLabels = null, mod
   // ai.modelAliases — aí o aviso é verdadeiro (label aponta para apelido que não
   // existe mais). Sem config (doctor sem acesso ao arquivo), nenhuma label de
   // modelo é acusada: melhor calar do que mandar apagar o que funciona.
-  const wantedLabels = allLabelsFor(modelAliases ? { modelAliases } : undefined);
+  //
+  // Mesma regra para `spec-wave:dev-agent-<sufixo>` (trilha extra do
+  // dev-agent, item 7 do rfc/plano-hardening-agentes-2026-08.md): sem
+  // devAgentQueues em mãos, nenhuma label desse padrão é acusada — apagá-la
+  // esvazia a fila inteira. A fila DEFAULT (`spec-wave:dev-agent`, sem
+  // sufixo) já está em ALL_LABELS e nunca cai neste ramo.
+  const wantedLabels = allLabelsFor(
+    modelAliases ? { modelAliases } : undefined,
+    devAgentQueues ? { queues: devAgentQueues } : undefined
+  );
   const knownLabels = new Set(wantedLabels.map(l => l.name));
   const orphanLabels = repoLabels
     ? repoLabels.filter(n => n.startsWith('spec-wave:') && !knownLabels.has(n)
-        && (modelAliases !== null || !n.startsWith(MODEL_LABEL_PREFIX)))
+        && (modelAliases !== null || !n.startsWith(MODEL_LABEL_PREFIX))
+        && (devAgentQueues !== null || !n.startsWith(DEV_AGENT_QUEUE_PREFIX)))
     : [];
   // Ausentes saem em duas listas: uma label do fluxo que falta é um repo
   // desatualizado; uma `spec-wave:model:<apelido>` que falta é um apelido
@@ -457,7 +498,11 @@ async function checkBoardHygiene(ctx) {
   }
 
   const { unknownStages, retiredStages, missingStages, orphanLabels, missingLabels, missingModelLabels } =
-    inspectBoardHygiene({ boardStages, repoLabels, modelAliases: cfg?.ai?.modelAliases ?? null });
+    inspectBoardHygiene({
+      boardStages, repoLabels,
+      modelAliases: cfg?.ai?.modelAliases ?? null,
+      devAgentQueues: cfg?.devAgent?.queues ?? null,
+    });
 
   const notes = [];
   let status = 'ok';
@@ -831,6 +876,26 @@ export function decompositionDrift(doc, atual = new Map()) {
   return out;
 }
 
+/**
+ * Prepara o doc para `decompositionDrift` quando a árvore fetchada não desceu
+ * ao nível de Task (função PURA — item 5 do rfc/plano-hardening-agentes-
+ * 2026-08.md, a checagem sem `--deep` só busca as Stories).
+ *
+ * Comparar um doc com Tasks contra uma árvore sem Tasks reportaria CADA Task
+ * como "rescopada ou apagada" por engano — o dado não foi buscado, não é que
+ * ele sumiu. Tirar as Tasks dos dois lados evita o falso positivo sem mentir
+ * sobre profundidade: quem lê a nota do doctor sabe que só Stories foram
+ * conferidas.
+ *
+ * @param {object} doc documento parseado (parseDecompositionDoc)
+ * @param {{deep: boolean}} params
+ * @returns {object} doc, ou uma cópia com `stories[].tasks` esvaziado
+ */
+export function decompositionDocForDrift(doc, { deep }) {
+  if (deep) return doc;
+  return { ...doc, stories: (doc.stories || []).map(s => ({ ...s, tasks: [] })) };
+}
+
 // Lê os decomposition.md aplicados e confere se ainda descrevem a árvore real.
 // Best-effort e sempre warn: divergência aqui é informação para o humano, não
 // falha de configuração — rescopar issues à mão é legítimo, esquecer de dizer
@@ -876,16 +941,43 @@ async function checkDecompositions(ctx) {
       continue;
     }
 
-    // Monta a árvore real: sub-issues da Feature + as de cada Story.
+    // Orçamento: 1 GraphQL para as Stories da Feature + (só com --deep) 1 por
+    // Story, para as Tasks. Sem isso este check sozinho podia custar 1 REST +
+    // 1 GraphQL por Feature + 1 GraphQL POR STORY da milestone inteira, sem
+    // teto nem cache — o padrão que dependency-map.mjs existe para eliminar.
+    const storyCount = (doc.stories || []).length;
+    const estimated = 1 + (ctx.deep ? storyCount : 0);
+    const budget = affordCheck({
+      remaining: ctx.rateLimit?.remaining ?? null,
+      estimated,
+      resetAt: ctx.rateLimit?.resetAt ?? null,
+    });
+    if (!budget.run) {
+      status = 'warn';
+      notes.push(`${rel}: árvore de #${doc.issueNumber} não verificada — ${budget.motivo}`);
+      continue;
+    }
+
+    // Monta a árvore real: sub-issues da Feature (cacheadas, TTL de
+    // cache.ttlSec) e, só com --deep, as de cada Story também.
     const atual = new Map();
     try {
       const issue = await makeOctokit(ctx.token).rest.issues.get({
         owner: ctx.cfg.owner, repo: ctx.cfg.repo, issue_number: doc.issueNumber,
       });
-      const subs = await listSubIssues(ctx.token, issue.data.node_id);
+      const ttlSec = resolveCacheTtl(ctx.cfg);
+      const { subs } = await cachedSubIssues({
+        token: ctx.token, owner: ctx.cfg.owner, repo: ctx.cfg.repo, root, ttlSec,
+        parent: { number: doc.issueNumber, nodeId: issue.data.node_id },
+      });
       for (const s of subs) {
         atual.set(s.number, { title: s.title, state: s.state, stateReason: s.stateReason });
-        for (const t of await listSubIssues(ctx.token, s.nodeId).catch(() => [])) {
+        if (!ctx.deep) continue;
+        const { subs: tasks } = await cachedSubIssues({
+          token: ctx.token, owner: ctx.cfg.owner, repo: ctx.cfg.repo, root, ttlSec,
+          parent: { number: s.number, nodeId: s.nodeId },
+        }).catch(() => ({ subs: [] }));
+        for (const t of tasks) {
           atual.set(t.number, { title: t.title, state: t.state, stateReason: t.stateReason });
         }
       }
@@ -894,14 +986,15 @@ async function checkDecompositions(ctx) {
       continue;
     }
 
-    const drift = decompositionDrift(doc, atual);
+    const drift = decompositionDrift(decompositionDocForDrift(doc, { deep: ctx.deep }), atual);
+    const profundidade = ctx.deep ? '' : ' (só Stories — rode com --deep para conferir as Tasks também)';
     if (drift.length === 0) {
-      notes.push(`${rel}: confere com as ${atual.size} issue(s) de #${doc.issueNumber}.`);
+      notes.push(`${rel}: confere com as ${atual.size} issue(s) de #${doc.issueNumber}${profundidade}.`);
       continue;
     }
     status = 'warn';
     notes.push(
-      `${rel} descreve um desenho diferente do que existe hoje:\n` +
+      `${rel} descreve um desenho diferente do que existe hoje${profundidade}:\n` +
       drift.map(d => `  - ${d}`).join('\n') + '\n' +
       '  Atualize o arquivo ou marque-o como histórico — aplicado ele é registro, e registro ' +
       'errado parece confiável.'
@@ -1427,11 +1520,11 @@ async function checkWorkflows(ctx) {
 
 // ── Comando ─────────────────────────────────────────────────────────────────
 
-export async function doctor() {
+export async function doctor(options = {}) {
   p.intro(chalk.bold('spec-wave doctor'));
 
   // Contexto compartilhado entre os checks (token, config, resultados parciais).
-  const ctx = { cwd: process.cwd() };
+  const ctx = { cwd: process.cwd(), deep: !!options.deep };
   // Procurado subindo na árvore: rodar o doctor de um subdiretório deve
   // diagnosticar o repositório, não reportar "não inicializado".
   ctx.configPath = findConfigPath(ctx.cwd);
@@ -1448,6 +1541,7 @@ export async function doctor() {
 
   const checks = [
     checkToken,
+    checkRateLimit,
     checkScopes,
     checkGhAccount,
     checkConfig,