@spec-wave/cli 0.10.0 → 0.11.1

package/src/commands/generate-spec.mjs

@@ -5,6 +5,7 @@ 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 { isForced, consumeForceLabel } from '../lib/force.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { allowsSpecPlan, SPEC_PLAN_EXCLUDED_TYPES, TARGET_LANGUAGE } from '../config.mjs';
 
@@ -41,7 +42,7 @@ Regras:
 - Seja específico e detalhado em cada seção.
 - Responda APENAS com o conteúdo do spec.md, sem texto adicional.`;
 
-export async function generateSpec({ issueNumber }) {
+export async function generateSpec({ issueNumber, force = false }) {
   const token = await resolveToken();
   const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
 
@@ -70,6 +71,13 @@ export async function generateSpec({ issueNumber }) {
     return;
   }
 
+  // A geração de spec/plan não tem guard — re-acionar a label já regera e
+  // sobrescreve o arquivo. O force existe por simetria com o decompose (e para
+  // a label ser consumida quando aplicada aos três de uma vez).
+  const forced = isForced({ labels: issue.labels || [], flag: force });
+  await consumeForceLabel(token, owner, repo, parseInt(issueNumber, 10));
+  if (forced) console.log('Modo forçado ativo — spec.md será regerado (sobrescreve o existente).');
+
   const slug = slugify(issue.title);
   const featureDir = `docs/features/${slug}`;
   const filePath = `${featureDir}/spec.md`;
@@ -125,6 +133,21 @@ export async function generateSpec({ issueNumber }) {
     );
 
     console.log(`spec.md criado em: ${filePath}`);
+  } catch (err) {
+    // Sem isto a label de gatilho fica aplicada — e como o workflow dispara em
+    // `issues: [labeled]`, re-adicionar uma label já presente não emite evento:
+    // a issue vira um beco sem saída, sem comentário e sem sinal no board.
+    // Espelha o tratamento do tipo não suportado (acima): remove o gatilho e
+    // reporta na issue. O erro segue propagando para o Action falhar visível.
+    await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:spec').catch(() => {});
+    await commentOnIssue(
+      token, owner, repo, parseInt(issueNumber, 10),
+      `❌ **Falha ao gerar a spec.md**\n\n` +
+      `\`\`\`\n${err.message}\n\`\`\`\n\n` +
+      `A label \`spec-wave:spec\` foi removida para destravar o gatilho — ` +
+      `adicione-a de novo para tentar outra vez.`
+    ).catch(() => {});
+    throw err;
   } finally {
     // Best-effort: nunca propaga erro (ver recordUsage).
     await recordUsage({ token, owner, repo, issueNumber: parseInt(issueNumber, 10), entries: usageEntries });

package/src/commands/validate.mjs

@@ -4,6 +4,7 @@ import { resolveToken } from '../api/auth.mjs';
 import { getIssue, removeLabel, addLabel, commentOnIssue } from '../api/github-rest.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { CONFIG_FILE, LABEL_CRITIQUE_FAILED, REQUIRED_PLAN_SECTIONS, REQUIRED_SPEC_SECTIONS } from '../config.mjs';
+import { findIncompleteDocSigns } from '../lib/doc-completeness.mjs';
 
 export async function validate({ issueNumber }) {
   const token = await resolveToken();
@@ -49,6 +50,9 @@ export async function validate({ issueNumber }) {
         errors.push(`❌ Seção obrigatória ausente no plan.md: **${section}**`);
       }
     }
+    for (const problem of findIncompleteDocSigns(planContent)) {
+      errors.push(`❌ \`plan.md\` parece incompleto: ${problem}`);
+    }
   }
 
   // Check spec.md
@@ -62,6 +66,11 @@ export async function validate({ issueNumber }) {
         errors.push(`❌ Seção obrigatória ausente no spec.md: **${section}**`);
       }
     }
+    // Seções presentes não garantem documento completo: um corte dentro da
+    // última seção passa na checagem acima (foi o caso da EP2-F13).
+    for (const problem of findIncompleteDocSigns(specContent)) {
+      errors.push(`❌ \`spec.md\` parece incompleto: ${problem}`);
+    }
   }
 
   // Remove trigger label

package/src/config.mjs

@@ -183,6 +183,10 @@ export const PRIORITY_LABELS = [
 // Labels de estado gravadas pelas automações (não são gatilhos do usuário).
 export const LABEL_CRITIQUE_FAILED = 'spec-wave:critique-failed';
 export const LABEL_DECOMPOSED = 'spec-wave:decomposed';
+// Modificador (não é gatilho — sozinha não dispara workflow nenhum): quando
+// presente junto de uma label de gatilho, manda o comando re-executar a etapa
+// ignorando os guards. É consumida (removida) pelo run que a leu.
+export const LABEL_FORCE = 'spec-wave:force';
 
 export const TRIGGER_LABELS = [
   { name: 'spec-wave:spec',          color: 'BFD4F2', description: 'Gerar spec.md via GitHub Action'      },
@@ -192,6 +196,7 @@ export const TRIGGER_LABELS = [
   { name: 'spec-wave:decompose',     color: 'BFD4F2', description: 'Decompor em Stories e Tasks'          },
   { name: LABEL_CRITIQUE_FAILED,     color: 'B60205', description: 'Crítica adversarial apontou contradições graves' },
   { name: LABEL_DECOMPOSED,          color: 'EDEDED', description: 'Feature já decomposta em Stories e Tasks' },
+  { name: LABEL_FORCE,               color: 'D93F0B', description: 'Re-executa a etapa ignorando os guards (consumida no run)' },
 ];
 
 export const ALL_LABELS = [...TYPE_LABELS, ...PRIORITY_LABELS, ...TRIGGER_LABELS];

package/src/lib/claude.mjs

@@ -5,19 +5,30 @@ import { CONFIG_FILE, getProvider, DEFAULT_PROVIDER } from '../config.mjs';
 import { lintLanguage } from './output-lint.mjs';
 import { computeCost } from './usage-report.mjs';
 
+// Teto de saída padrão. O valor anterior (8192) truncava specs reais: um
+// documento de ~20 KB em pt-BR já custa ~6k tokens, e modelos com raciocínio
+// (Opus 4.7+, deepseek-r1) gastam o restante "pensando" ANTES de escrever. O
+// teto de saída dos modelos atuais é 128k — 32k deixa folga sem virar cheque em
+// branco. Ajustável por `ai.maxTokens` / `ai.maxTokensByAction`.
+export const DEFAULT_MAX_TOKENS = 32768;
+
 /**
- * Resolve provider/modelo de IA (função PURA — testável sem process.env nem fs).
+ * Resolve provider/modelo/teto de tokens de IA (função PURA — testável sem
+ * process.env nem fs).
  *
  * Precedência do modelo: env.SPEC_WAVE_MODEL → fileAi.models[action] →
  * fileAi.model → default do provider. Provider: env.SPEC_WAVE_PROVIDER →
  * fileAi.provider → default. Assim uma ação específica (ex.: critique) pode
  * usar modelo próprio via bloco `ai.models` do .spec-wave.json.
  *
+ * maxTokens segue a mesma forma: env.SPEC_WAVE_MAX_TOKENS →
+ * fileAi.maxTokensByAction[action] → fileAi.maxTokens → DEFAULT_MAX_TOKENS.
+ *
  * @param {object} params
  * @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, pricing: object|null }}
+ * @returns {{ provider: string, model: string, secret: string, pricing: object|null, maxTokens: number }}
  */
 export function resolveAiConfig({ env = {}, fileAi = {}, action } = {}) {
   const provider = (env.SPEC_WAVE_PROVIDER || fileAi.provider || DEFAULT_PROVIDER).toLowerCase();
@@ -29,7 +40,24 @@ export function resolveAiConfig({ env = {}, fileAi = {}, action } = {}) {
   // 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 };
+  const maxTokens = positiveInt(env.SPEC_WAVE_MAX_TOKENS)
+    ?? (action ? positiveInt(fileAi.maxTokensByAction?.[action]) : undefined)
+    ?? positiveInt(fileAi.maxTokens)
+    ?? DEFAULT_MAX_TOKENS;
+  return {
+    provider: meta.value,
+    model,
+    secret: meta.secret,
+    pricing: fileAi.pricing || null,
+    maxTokens,
+  };
+}
+
+// Config vinda de JSON/env pode trazer string, zero ou lixo — só aceita inteiro
+// positivo, senão cai na próxima fonte da precedência.
+function positiveInt(value) {
+  const n = Number(value);
+  return Number.isInteger(n) && n > 0 ? n : undefined;
 }
 
 // Resolve o provider/modelo de IA a partir do .spec-wave.json (gravado pelo init
@@ -49,6 +77,87 @@ function resolveAi(action) {
   return resolveAiConfig({ env: process.env, fileAi, action });
 }
 
+// Retry de falha transitória do provedor. Sem isto, um corpo cortado numa
+// geração de 90s derruba o Action inteiro e a issue fica sem spec — o custo de
+// esperar alguns segundos é irrisório perto de refazer o ciclo à mão.
+export const RETRY_ATTEMPTS = 3;
+const RETRY_BASE_MS = 2000;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// Transitório = vale a pena repetir a MESMA requisição. Erro de configuração
+// (401, 400, chave ausente) não entra aqui: repetir só atrasa a mensagem útil.
+export function isTransientProviderError(err) {
+  if (!err) return false;
+  if (err.transient) return true; // marcado na origem (corpo inválido/vazio)
+  const status = err.status ?? err.statusCode;
+  if (status === 429 || (status >= 500 && status < 600)) return true;
+  // undici/fetch: falha de rede vem como TypeError com cause
+  return /fetch failed|ECONNRESET|ETIMEDOUT|EAI_AGAIN|socket hang up|network|aborted/i
+    .test(err.message || '');
+}
+
+export async function withRetry(label, fn, { attempts = RETRY_ATTEMPTS, baseMs = RETRY_BASE_MS } = {}) {
+  let lastErr;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      if (attempt === attempts || !isTransientProviderError(err)) break;
+      const delayMs = baseMs * 2 ** (attempt - 1); // 2s, 4s, 8s…
+      console.warn(
+        `${label}: falha transitória na tentativa ${attempt}/${attempts} (${err.message}) — ` +
+        `repetindo em ${delayMs / 1000}s.`
+      );
+      await sleep(delayMs);
+    }
+  }
+  throw lastErr;
+}
+
+// Truncamento: os dois provedores dizem explicitamente que cortaram a saída no
+// teto de tokens — OpenRouter (formato OpenAI) em `choices[0].finish_reason`,
+// Anthropic em `message.stop_reason`. Ignorar esse campo é o que produzia um
+// documento cortado no meio de uma frase, commitado como se estivesse completo.
+const TRUNCATION_REASONS = new Set(['length', 'max_tokens']);
+
+/** Motivo de parada indica saída cortada no teto de tokens? (função PURA) */
+export function isTruncationReason(reason) {
+  return TRUNCATION_REASONS.has(reason);
+}
+
+// Repetir a MESMA requisição depois de truncar dá o mesmo corte — só sobe o
+// custo. Por isso NÃO é marcado como transitório: o erro sobe, o Action falha
+// visível, destrava a label e comenta na issue o que ajustar.
+export class TruncatedOutputError extends Error {
+  constructor({ provider, model, maxTokens, reason, chars }) {
+    super(
+      `Saída truncada pelo teto de tokens (${provider} · ${model} · max_tokens=${maxTokens} · ` +
+      `motivo=${reason}). Foram gerados ~${chars} caracteres antes do corte. ` +
+      'Aumente `ai.maxTokens` (ou `ai.maxTokensByAction`) no .spec-wave.json, ou reduza o ' +
+      'tamanho da issue de origem. O documento NÃO foi gravado — um documento cortado ' +
+      'passaria na validação de seções e valeria menos que nenhum.'
+    );
+    this.name = 'TruncatedOutputError';
+    this.truncated = true;
+  }
+}
+
+// Os parâmetros de sampling foram REMOVIDOS a partir do Claude Opus 4.7 (vale
+// para 4.8 e 5, Sonnet 5, Fable 5 e Mythos 5): enviar temperature/top_p/top_k
+// devolve 400. A OpenRouter hoje normaliza e não quebra, mas o caminho direto
+// da Anthropic quebraria em toda requisição — daí a checagem no modelo, não no
+// provider. Aceita tanto o id primário (`claude-opus-4-8`) quanto o slug da
+// OpenRouter (`anthropic/claude-opus-4.8`).
+const MODELS_WITHOUT_SAMPLING_PARAMS =
+  /claude-(?:opus-(?:4[.-]7|4[.-]8|5)|sonnet-5|fable-5|mythos-5)/i;
+
+/** O modelo ainda aceita `temperature`? (função PURA) */
+export function supportsTemperature(model) {
+  return !MODELS_WITHOUT_SAMPLING_PARAMS.test(model || '');
+}
+
 // temperature padrão 0.2 (RFC-002 §5): "Determinism over Creativity". Pode ser
 // sobrescrita por chamada via opts, mas o default cobre spec/plan/decompose.
 //
@@ -66,10 +175,16 @@ function resolveAi(action) {
 export async function generateDocument(systemPrompt, userContent, opts = {}) {
   const ai = resolveAi(opts.action);
   const temperature = opts.temperature ?? 0.2;
-  // Modelos de reasoning (ex.: deepseek-r1) consomem tokens "pensando" antes da
-  // resposta, então o teto precisa ser maior para o plano não vir truncado.
-  const maxTokens = opts.maxTokens ?? 8192;
-  console.log(`Provider de IA: ${ai.provider} · modelo: ${ai.model} · temperature: ${temperature} · max_tokens: ${maxTokens}`);
+  // Modelos de reasoning (ex.: deepseek-r1, Opus 4.7+) consomem tokens
+  // "pensando" antes da resposta, então o teto precisa cobrir raciocínio +
+  // documento — ver DEFAULT_MAX_TOKENS.
+  const maxTokens = opts.maxTokens ?? ai.maxTokens;
+  const sendTemperature = supportsTemperature(ai.model);
+  console.log(
+    `Provider de IA: ${ai.provider} · modelo: ${ai.model} · ` +
+    `temperature: ${sendTemperature ? temperature : 'n/a (removida neste modelo)'} · ` +
+    `max_tokens: ${maxTokens}`
+  );
 
   // Acumuladores de uso desta invocação (1 ou 2 chamadas, com o retry de lint).
   let inputTokens = 0;
@@ -77,9 +192,14 @@ export async function generateDocument(systemPrompt, userContent, opts = {}) {
   let cost = null; // soma dos custos conhecidos; se todos null → null
 
   const generate = async (system) => {
-    const { text, usage } = ai.provider === 'openrouter'
-      ? await generateWithOpenRouter(system, userContent, ai, temperature, maxTokens)
-      : await generateWithAnthropic(system, userContent, ai, temperature, maxTokens);
+    const callOpts = {
+      temperature: sendTemperature ? temperature : undefined,
+      maxTokens,
+    };
+    const { text, usage } = await withRetry(`Geração via ${ai.provider}`, () =>
+      ai.provider === 'openrouter'
+        ? generateWithOpenRouter(system, userContent, ai, callOpts)
+        : generateWithAnthropic(system, userContent, ai, callOpts));
     inputTokens += usage.inputTokens;
     outputTokens += usage.outputTokens;
     if (typeof usage.cost === 'number') cost = (cost ?? 0) + usage.cost;
@@ -179,7 +299,7 @@ export function extractOpenRouterUsage(usage) {
   };
 }
 
-async function generateWithAnthropic(systemPrompt, userContent, ai, temperature, maxTokens) {
+async function generateWithAnthropic(systemPrompt, userContent, ai, { temperature, maxTokens }) {
   const apiKey = process.env.ANTHROPIC_API_KEY;
   if (!apiKey) {
     throw new Error(
@@ -192,15 +312,56 @@ async function generateWithAnthropic(systemPrompt, userContent, ai, temperature,
   const message = await client.messages.create({
     model: ai.model,
     max_tokens: maxTokens,
-    temperature,
+    // Omitida nos modelos que removeram sampling (Opus 4.7+, Sonnet 5, Fable 5):
+    // enviá-la devolve 400.
+    ...(temperature === undefined ? {} : { temperature }),
     messages: [{ role: 'user', content: userContent }],
     system: systemPrompt,
   });
 
-  return { text: message.content[0].text, usage: extractAnthropicUsage(message.usage) };
+  // A resposta nem sempre começa com um bloco de texto (recusa, resposta vazia):
+  // `content[0].text` cru virava TypeError com mensagem inútil.
+  const text = (message.content || [])
+    .filter((block) => block.type === 'text')
+    .map((block) => block.text)
+    .join('');
+
+  if (message.stop_reason === 'refusal') {
+    throw new Error(
+      `A Anthropic recusou a requisição (stop_reason=refusal` +
+      `${message.stop_details?.category ? `, categoria=${message.stop_details.category}` : ''}). ` +
+      'Revise o conteúdo da issue de origem.'
+    );
+  }
+  if (message.stop_reason === 'model_context_window_exceeded') {
+    // Estouro na ENTRADA — subir max_tokens não resolve; o que precisa encolher
+    // é a issue/contexto enviado.
+    throw new Error(
+      `Contexto de entrada excedido (${ai.model}). Reduza o tamanho da issue de origem ` +
+      'ou do tech_context antes de repetir.'
+    );
+  }
+  if (isTruncationReason(message.stop_reason)) {
+    throw new TruncatedOutputError({
+      provider: 'anthropic',
+      model: ai.model,
+      maxTokens,
+      reason: message.stop_reason,
+      chars: text.length,
+    });
+  }
+  if (!text) {
+    const err = new Error(
+      `A Anthropic retornou resposta sem texto (stop_reason=${message.stop_reason}).`
+    );
+    err.transient = true;
+    throw err;
+  }
+
+  return { text, usage: extractAnthropicUsage(message.usage) };
 }
 
-async function generateWithOpenRouter(systemPrompt, userContent, ai, temperature, maxTokens) {
+async function generateWithOpenRouter(systemPrompt, userContent, ai, { temperature, maxTokens }) {
   const apiKey = process.env.OPENROUTER_API_KEY;
   if (!apiKey) {
     throw new Error(
@@ -220,7 +381,8 @@ async function generateWithOpenRouter(systemPrompt, userContent, ai, temperature
     body: JSON.stringify({
       model: ai.model,
       max_tokens: maxTokens,
-      temperature,
+      // Omitida nos modelos que removeram sampling (Opus 4.7+, Sonnet 5, Fable 5).
+      ...(temperature === undefined ? {} : { temperature }),
       messages: [
         { role: 'system', content: systemPrompt },
         { role: 'user', content: userContent },
@@ -232,13 +394,48 @@ async function generateWithOpenRouter(systemPrompt, userContent, ai, temperature
 
   if (!res.ok) {
     const body = await res.text();
-    throw new Error(`OpenRouter API ${res.status}: ${body}`);
+    const err = new Error(`OpenRouter API ${res.status}: ${body}`);
+    err.status = res.status;
+    throw err;
   }
 
-  const data = await res.json();
-  const content = stripReasoning(data?.choices?.[0]?.message?.content || '');
+  // Um 200 com corpo vazio ou cortado acontece em gerações longas. `res.json()`
+  // cru lançaria "Unexpected end of JSON input" — mensagem que não diz nada a
+  // quem está olhando o board. Lê como texto, reporta o que veio e marca como
+  // transitória para o retry pegar.
+  const raw = await res.text();
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    const err = new Error(
+      `OpenRouter devolveu ${res.status} com corpo inválido (${raw.length} bytes): ` +
+      `${raw.slice(0, 200) || '(vazio)'}`
+    );
+    err.transient = true;
+    throw err;
+  }
+
+  const choice = data?.choices?.[0];
+  const content = stripReasoning(choice?.message?.content || '');
+
+  // finish_reason='length' = cortado no teto. Checado ANTES do conteúdo vazio:
+  // um corte durante o raciocínio devolve texto vazio, e "resposta vazia" (que
+  // é tratada como transitória) esconderia a causa real por trás de 3 retries.
+  if (isTruncationReason(choice?.finish_reason)) {
+    throw new TruncatedOutputError({
+      provider: 'openrouter',
+      model: ai.model,
+      maxTokens,
+      // native_finish_reason preserva o motivo cru do provedor upstream.
+      reason: `${choice.finish_reason}${choice.native_finish_reason ? `/${choice.native_finish_reason}` : ''}`,
+      chars: content.length,
+    });
+  }
   if (!content) {
-    throw new Error(`OpenRouter retornou resposta vazia: ${JSON.stringify(data)}`);
+    const err = new Error(`OpenRouter retornou resposta vazia: ${JSON.stringify(data)}`);
+    err.transient = true;
+    throw err;
   }
   return { text: content, usage: extractOpenRouterUsage(data.usage) };
 }

package/src/lib/critique.mjs

@@ -151,7 +151,11 @@ export async function runCritique({ kind, spec, plan, techContextYaml, stories,
   const raw = await generateDocument(buildSystemPrompt(kind), userContent, {
     action: 'critique',
     temperature: 0,
-    maxTokens: 4096,
+    // Teto próprio: a crítica devolve uma lista JSON de findings, bem menor que
+    // um spec/plan. 4096 ficava justo quando os dois documentos são longos e o
+    // JSON vinha cortado — o parse falhava sem dizer por quê. Com a detecção de
+    // truncamento o corte agora é explícito, e a folga evita chegar nele.
+    maxTokens: 8192,
     usage,
   });
 

package/src/lib/doc-completeness.mjs

@@ -0,0 +1,54 @@
+// Rede de segurança contra documento cortado.
+//
+// A defesa principal contra truncamento é a detecção no provedor
+// (claude.mjs → TruncatedOutputError): um documento cortado nunca chega a ser
+// gravado. Esta checagem cobre o que escapa disso — documento editado à mão,
+// commit parcial, ou geração feita por uma versão antiga da CLI.
+//
+// O critério é DELIBERADAMENTE estreito. Só entram sinais que não têm leitura
+// inocente em Markdown: um falso positivo aqui bloqueia o ready de uma Feature
+// legítima, o que é pior que deixar passar um documento suspeito. "Termina sem
+// ponto final" e afins ficaram de fora de propósito — títulos, tabelas e itens
+// de lista terminam assim o tempo todo.
+
+/**
+ * Procura sinais objetivos de documento incompleto (função PURA).
+ *
+ * @param {string} content conteúdo do markdown
+ * @returns {string[]} descrições dos problemas encontrados (vazio = sem sinais)
+ */
+export function findIncompleteDocSigns(content) {
+  const problems = [];
+  const text = content || '';
+
+  if (!text.trim()) {
+    return ['o arquivo está vazio'];
+  }
+
+  // 1. Cerca de código aberta. Um ``` sem par significa que o corte aconteceu
+  //    dentro de um bloco (gherkin, mermaid, yaml) — não há leitura válida.
+  const fences = text.split('\n').filter((line) => /^\s*```/.test(line)).length;
+  if (fences % 2 !== 0) {
+    problems.push(`bloco de código não fechado (${fences} marcações \`\`\`)`);
+  }
+
+  // 2. Parênteses/colchetes abertos na última linha com conteúdo. É o formato
+  //    exato de um corte no meio da frase — ex.: "...(versionCode/S" — e prosa
+  //    completa não termina assim.
+  const lines = text.split('\n').filter((line) => line.trim());
+  const lastLine = lines[lines.length - 1] || '';
+  for (const [open, close, nome] of [['(', ')', 'parêntese'], ['[', ']', 'colchete']]) {
+    const opened = lastLine.split(open).length - 1;
+    const closed = lastLine.split(close).length - 1;
+    if (opened > closed) {
+      problems.push(`${nome} aberto e não fechado na última linha: "${truncate(lastLine)}"`);
+    }
+  }
+
+  return problems;
+}
+
+function truncate(line, max = 60) {
+  const t = line.trim();
+  return t.length > max ? `${t.slice(0, max)}…` : t;
+}

package/src/lib/force.mjs

@@ -0,0 +1,34 @@
+// Detecção do modo "force" (re-executar a etapa ignorando os guards).
+//
+// Os comandos generate-spec/generate-plan/decompose rodam dentro de Actions
+// disparadas por label — a linha de comando do workflow é fixa e não tem como
+// receber uma flag. Por isso o force chega de duas formas equivalentes:
+//   • label `spec-wave:force` na issue (fluxo normal, pelo board);
+//   • flag `--force` (execução local/manual da CLI).
+// A label é CONSUMIDA pelo run que a leu (ver consumeForceLabel), senão ela
+// ficaria pendurada e forçaria silenciosamente todos os runs seguintes.
+import { LABEL_FORCE } from '../config.mjs';
+import { removeLabel } from '../api/github-rest.mjs';
+
+/**
+ * Diz se a etapa deve ser re-executada ignorando os guards (função PURA).
+ *
+ * @param {object} [params]
+ * @param {Array<string|{name: string}>} [params.labels] labels da issue
+ * @param {boolean} [params.flag] valor da flag `--force` da CLI
+ * @returns {boolean}
+ */
+export function isForced({ labels = [], flag = false } = {}) {
+  if (flag) return true;
+  return (labels || [])
+    .map(l => (typeof l === 'string' ? l : l?.name))
+    .includes(LABEL_FORCE);
+}
+
+/**
+ * Remove a label `spec-wave:force` da issue. Best-effort: nunca lança — deixar
+ * de consumir a label é um incômodo, não um motivo para derrubar o comando.
+ */
+export async function consumeForceLabel(token, owner, repo, issueNumber) {
+  await removeLabel(token, owner, repo, issueNumber, LABEL_FORCE).catch(() => {});
+}

package/src/templates/agent/dev.specwave.agent.plist

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+ "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>dev.specwave.agent</string>
+  <key>ProgramArguments</key>
+    <array><string>{bin}</string></array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>RUST_LOG</key><string>info</string>
+    <key>PATH</key><string>{path}</string>
+  </dict>
+  <key>StandardOutPath</key><string>{home}/Library/Logs/spec-wave-agent.log</string>
+  <key>StandardErrorPath</key><string>{home}/Library/Logs/spec-wave-agent.log</string>
+</dict></plist>

package/src/templates/agent/spec-wave-agent.service

@@ -0,0 +1,18 @@
+[Unit]
+Description=spec-wave dev agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart={bin}
+Restart=on-failure
+RestartSec=10
+Environment=RUST_LOG=info
+Environment=PATH={path}
+# SIGTERM no desligamento => checkpoint + release do lease (takeover imediato)
+KillSignal=SIGTERM
+# Deve ser maior que o tempo do checkpoint (commit + push do WIP)
+TimeoutStopSec=30
+
+[Install]
+WantedBy=default.target